Rename Vector3D to VectorN

Author: roackb2

docs/specs/TECHNICAL_SPEC_v2.1.md

@@ -74,26 +74,26 @@ $$
 
 ## 3. Implementation Interfaces (The Bridge)
 
-We need to bridge the generic `State` from v1.0 with the rigorous `Vector3D` of v2.1.
+We need to bridge the generic `State` from v1.0 with the rigorous `VectorN` of v2.1.
 
 ### 3.1 The Kinematics Type Definition
 
 Create these in `src/core/kinematics/types.ts`.
 
 ```typescript
-export type Vector3D = number[]; // Embedding vector
+export type VectorN = number[]; // N-dimensional embedding vector
 
 // The Physics State (Hidden from the generic Orchestrator)
 export interface KinematicState {
-  position: Vector3D;      // S_i (Filtered)
-  velocity: Vector3D;      // v_i
-  heading: Vector3D;       // D_i
+  position: VectorN;      // S_i (Filtered)
+  velocity: VectorN;      // v_i
+  heading: VectorN;       // D_i
   stepIndex: number;
 }
 
 // The Control Signal returned by the PID controller
 export interface ControlSignal {
-  correctionVector: Vector3D; // u(i)
+  correctionVector: VectorN; // u(i)
   magnitude: number;          // How strong the correction is (0-1)
   isStable: boolean;          // Should we stop?
   log: string;               // Explanation for debug traces
@@ -113,7 +113,7 @@ import { State } from '../types';
 
 // Adapters must implement this to translate their Domain State (JSON) into Physics State (Vector)
 export interface StateEmbedder<S extends State> {
-  embed(state: S): Promise<Vector3D>;
+  embed(state: S): Promise<VectorN>;
 }
 
 // The v2.1 Configuration
@@ -138,8 +138,8 @@ A pure, deterministic class that holds the math. It does not know about LLMs or
 class PhysicsEngine {
   update(
     prev: KinematicState,
-    observation: Vector3D
-  ): { next: KinematicState; error: Vector3D } {
+    observation: VectorN
+  ): { next: KinematicState; error: VectorN } {
     // 1. EKF Predict & Update
     // 2. Calculate Heading D_i
     // 3. Calculate Cross-track Error e_i (Vector Rejection)
@@ -163,7 +163,7 @@ class KinematicProbePolicy<S> implements ProbePolicy<S, Action, Feedback> {
   ) {}
 
   async decide(state: S, ladder: Ladder): Promise<Action> {
-    // 1. Convert generic State -> Vector3D (using Embedder)
+    // 1. Convert generic State -> VectorN (using Embedder)
     const observation = await this.embedder.embed(state);
 
     // 2. Update Physics Engine
@@ -194,7 +194,7 @@ class KinematicProbePolicy<S> implements ProbePolicy<S, Action, Feedback> {
 When implementing v2.1, follow this sequence to avoid breaking existing code:
 
 1. **Scaffold**: Create `src/core/kinematics/` folder.
-2. **Math First**: Implement `Vector3D` operations (dot product, norm, projection, rejection) in `src/core/kinematics/math.ts`. **Do not use external heavy math libs**, keep it lightweight.
+2. **Math First**: Implement `VectorN` operations (dot product, norm, projection, rejection) in `src/core/geometry/vector.ts` (previously `src/core/kinematics/math.ts`). **Do not use external heavy math libs**, keep it lightweight.
 3. **Engine**: Implement `PhysicsEngine` with EKF and Heading logic.
 4. **Controller**: Implement `PIDController`.
 5. **Integration**: Create `KinematicProbePolicy`.
@@ -219,7 +219,7 @@ const controlled = cyberloop(agent, {
   middleware: [
     kinematicsMiddleware({
       embedder,          // StateEmbedder<S> — same as Section 3.2
-      goalEmbedding,     // Vector3D — task origin τ
+      goalEmbedding,     // VectorN — task origin τ
       pid: { Kp: 0.5, Ki: 0.0, Kd: 0.1, stabilityThreshold: 0.6 },
       physics: { processNoise: 0.1, measureNoise: 0.5 },
     }),

docs/specs/project-ariadne/wikipedia-deep-dive-agent.md

@@ -41,7 +41,7 @@ This adapter implements the standard AICL interfaces (`Environment`, `StateEmbed
 2. **Embedder (`WikipediaEmbedder`)**:
     * **Input:** `State.summary` + `State.goal`.
     * **Model:** `text-embedding-3-small` (Fast, cheap, effective).
-    * **Output:** `Vector3D`.
+    * **Output:** `VectorN`.
 
 3. **Policy (`SemanticNavigationPolicy`)**:
     * **Role:** Deterministic Inner Loop.

src/advanced/kinematics-middleware.ts

@@ -3,16 +3,16 @@ import { PhysicsEngine } from '../core/kinematics/engine';
 import type { StateEmbedder } from '../core/kinematics/interfaces';
 import { norm } from '../core/kinematics/math';
 import { PIDController } from '../core/kinematics/pid';
-import type { KinematicState, Vector3D } from '../core/kinematics/types';
+import type { KinematicState, VectorN } from '../core/kinematics/types';
 import type { Middleware, StepContext, StepResult } from '../core/middleware/types';
 
 /**
  * Kinematics data attached to `ctx.metadata['kinematics']` each step.
  */
 export interface KinematicsSnapshot {
-  position: Vector3D;
-  velocity: Vector3D;
-  error: Vector3D;
+  position: VectorN;
+  velocity: VectorN;
+  error: VectorN;
   errorMagnitude: number;
   correctionMagnitude: number;
   coherenceAngleDeg: number;
@@ -24,7 +24,7 @@ export interface KinematicsSnapshot {
  * Correction info attached to `ctx.metadata['kinematicsCorrection']` when drift is detected.
  */
 export interface CorrectionInfo {
-  vector: Vector3D;
+  vector: VectorN;
   magnitude: number;
   log: string;
 }
@@ -77,7 +77,7 @@ export function kinematicsMiddleware<S>(opts: KinematicsMiddlewareOpts<S>): Midd
   const engine = new PhysicsEngine({ ProcessNoise: processNoise, MeasureNoise: measureNoise, PID: { Kp, Ki, Kd }, MaxDeviation: stabilityThreshold });
   const pid = new PIDController(Kp, Ki, Kd, stabilityThreshold);
 
-  let origin: Vector3D | null = null;
+  let origin: VectorN | null = null;
   let lastPhysicsState: KinematicState | null = null;
 
   return {

src/core/geometry/vector.ts

@@ -2,9 +2,8 @@
  * Euclidean vector operations for semantic embedding spaces.
  *
  * This module provides the foundational vector math used by CyberLoop's
- * control layers. It operates on arbitrary-dimensional vectors (typed as
- * `Vector3D` for historical reasons — the name will be aliased in a future
- * version).
+ * control layers. It operates on arbitrary-dimensional vectors typed as
+ * `VectorN`.
  *
  * **v2.1:** Used by PhysicsEngine (EKF) and PIDController.
  * **v3.0:** Will be extended by `manifold.ts` (PCA, curvature, tangent plane).
@@ -15,75 +14,75 @@
 
 import { Matrix } from 'ml-matrix';
 
-import type { Vector3D } from '../kinematics/types';
+import type { VectorN } from '../kinematics/types';
 
 // Convert array to Matrix (column vector)
-export const toMatrix = (v: Vector3D): Matrix => {
+export const toMatrix = (v: VectorN): Matrix => {
   return new Matrix([v]).transpose();
 };
 
 // Convert Matrix to array
-export const toVector = (m: Matrix): Vector3D => {
+export const toVector = (m: Matrix): VectorN => {
   return m.to1DArray();
 };
 
-export const add = (v1: Vector3D, v2: Vector3D): Vector3D => {
+export const add = (v1: VectorN, v2: VectorN): VectorN => {
   const m1 = toMatrix(v1);
   const m2 = toMatrix(v2);
   return toVector(Matrix.add(m1, m2));
 };
 
-export const subtract = (v1: Vector3D, v2: Vector3D): Vector3D => {
+export const subtract = (v1: VectorN, v2: VectorN): VectorN => {
   const m1 = toMatrix(v1);
   const m2 = toMatrix(v2);
   return toVector(Matrix.sub(m1, m2));
 };
 
-export const scale = (v: Vector3D, scalar: number): Vector3D => {
+export const scale = (v: VectorN, scalar: number): VectorN => {
   const m = toMatrix(v);
   return toVector(Matrix.mul(m, scalar));
 };
 
-export const dot = (v1: Vector3D, v2: Vector3D): number => {
+export const dot = (v1: VectorN, v2: VectorN): number => {
   const m1 = toMatrix(v1);
   const m2 = toMatrix(v2);
   // Dot product is v1^T * v2
   return m1.transpose().mmul(m2).get(0, 0);
 };
 
-export const norm = (v: Vector3D): number => {
+export const norm = (v: VectorN): number => {
   const m = toMatrix(v);
   return m.norm('frobenius'); // Euclidean norm
 };
 
-export const normalize = (v: Vector3D): Vector3D => {
+export const normalize = (v: VectorN): VectorN => {
   const n = norm(v);
   if (n === 0) return v.map(() => 0);
   return scale(v, 1 / n);
 };
 
 // Projection of a onto b: proj_b(a) = (a . b / |b|^2) * b
-export const project = (a: Vector3D, b: Vector3D): Vector3D => {
+export const project = (a: VectorN, b: VectorN): VectorN => {
   const bNormSq = dot(b, b);
   if (bNormSq === 0) return b.map(() => 0);
   const scalar = dot(a, b) / bNormSq;
   return scale(b, scalar);
 };
 
 // Rejection of a from b: a - proj_b(a)
-export const reject = (a: Vector3D, b: Vector3D): Vector3D => {
+export const reject = (a: VectorN, b: VectorN): VectorN => {
   const proj = project(a, b);
   return subtract(a, proj);
 };
 
-export const cosineSimilarity = (v1: Vector3D, v2: Vector3D): number => {
+export const cosineSimilarity = (v1: VectorN, v2: VectorN): number => {
   const n1 = norm(v1);
   const n2 = norm(v2);
   if (n1 === 0 || n2 === 0) return 0;
   return dot(v1, v2) / (n1 * n2);
 };
 
-export const angleBetween = (v1: Vector3D, v2: Vector3D): number => {
+export const angleBetween = (v1: VectorN, v2: VectorN): number => {
   const cos = Math.max(-1, Math.min(1, cosineSimilarity(v1, v2)));
   return Math.acos(cos);
 };

src/core/kinematics/engine.ts

@@ -1,6 +1,6 @@
 import type { KinematicsConfig } from './interfaces';
 import { add, angleBetween, norm, reject, scale, subtract } from './math';
-import type { KinematicState, Vector3D } from './types';
+import type { KinematicState, VectorN } from './types';
 
 export class PhysicsEngine {
   constructor(private config: KinematicsConfig) { }
@@ -11,9 +11,9 @@ export class PhysicsEngine {
    */
   update(
     prev: KinematicState,
-    observation: Vector3D,
-    origin: Vector3D
-  ): { next: KinematicState; error: Vector3D; coherence: number } {
+    observation: VectorN,
+    origin: VectorN
+  ): { next: KinematicState; error: VectorN; coherence: number } {
     // 1. Predict (Simple Motion Model: assume constant velocity)
     const s_pred = add(prev.position, prev.velocity);
 
@@ -54,7 +54,7 @@ export class PhysicsEngine {
     const coherence = hasMomentum ? angleBetween(heading, prevHeading) : 0;
 
     // 5. Calculate Cross-track Error (Vector Rejection)
-    let error: Vector3D;
+    let error: VectorN;
 
     if (!hasMomentum) {
       // No previous track to follow, so error is zero.

src/core/kinematics/interfaces.ts

@@ -1,10 +1,10 @@
 import type { State } from '../types';
-import type { Vector3D } from './types';
+import type { VectorN } from './types';
 
 // Adapters must implement this to translate their Domain State (JSON) into Physics State (Vector)
 // This allows the user to define any embedding strategy (OpenAI, local BERT, random projection, etc.)
 export interface StateEmbedder<S extends State> {
-  embed(state: S): Promise<Vector3D>;
+  embed(state: S): Promise<VectorN>;
 }
 
 // The v2.1 Configuration

src/core/kinematics/pid.ts

@@ -1,9 +1,9 @@
 import { add, norm, scale, subtract } from './math';
-import type { ControlSignal, Vector3D } from './types';
+import type { ControlSignal, VectorN } from './types';
 
 export class PIDController {
-  private integral: Vector3D;
-  private lastError: Vector3D | null = null;
+  private integral: VectorN;
+  private lastError: VectorN | null = null;
 
   constructor(
     private Kp: number,
@@ -14,7 +14,7 @@ export class PIDController {
     this.integral = []; // Initialize empty, will adapt to dimension on first call
   }
 
-  compute(error: Vector3D, dt = 1): ControlSignal {
+  compute(error: VectorN, dt = 1): ControlSignal {
     // Initialize integral term if needed
     if (this.integral.length === 0) {
       this.integral = error.map(() => 0);

src/core/kinematics/policy.ts

@@ -4,11 +4,11 @@ import type { PhysicsEngine } from './engine';
 import type { StateEmbedder } from './interfaces';
 import { norm } from './math';
 import type { PIDController } from './pid';
-import type { CorrectionAction, KinematicState, Vector3D } from './types';
+import type { CorrectionAction, KinematicState, VectorN } from './types';
 
 export class KinematicProbePolicy<S extends State, A extends Action, F extends Feedback> implements ProbePolicy<S, A, F> {
   public id = 'kinematic-policy';
-  private origin: Vector3D | null = null;
+  private origin: VectorN | null = null;
   private lastPhysicsState: KinematicState | null = null;
 
   constructor(
@@ -35,7 +35,7 @@ export class KinematicProbePolicy<S extends State, A extends Action, F extends F
   }
 
   async decide(state: S, ladder: Ladder<F>): Promise<A> {
-    // 1. Convert generic State -> Vector3D
+    // 1. Convert generic State -> VectorN
     const observation = await this.embedder.embed(state);
 
     // Initialize Origin if this is the first step after initialize()

src/core/kinematics/types.ts

@@ -1,24 +1,28 @@
-export type Vector3D = number[]; // Embedding vector - named Vector3D but can be N-dimensional
+/** An N-dimensional embedding vector. */
+export type VectorN = number[];
+
+/** @deprecated Use `VectorN` instead. Alias kept for backward compatibility. */
+export type Vector3D = VectorN;
 
 // The Physics State (Hidden from the generic Orchestrator)
 export interface KinematicState {
-  position: Vector3D;      // S_i (Filtered)
-  velocity: Vector3D;      // v_i
-  heading: Vector3D;       // D_i
+  position: VectorN;      // S_i (Filtered)
+  velocity: VectorN;      // v_i
+  heading: VectorN;       // D_i
   stepIndex: number;
 }
 
 // The Control Signal returned by the PID controller
 export interface ControlSignal {
-  correctionVector: Vector3D; // u(i)
+  correctionVector: VectorN; // u(i)
   magnitude: number;          // How strong the correction is (0-1)
   isStable: boolean;          // Should we stop?
   log: string;               // Explanation for debug traces
 }
 
 export interface CorrectionAction {
   type: 'CORRECTION';
-  vector: Vector3D;
+  vector: VectorN;
   magnitude: number;
   log: string;
 }