gridstamp 1.0.0

package/src/index.ts

@@ -0,0 +1,341 @@
+/**
+ * GridStamp — Spatial Proof-of-Presence for Autonomous Robots
+ *
+ * Nobody else unifies spatial memory + payment verification + anti-spoofing.
+ * - Niantic has maps but no payments
+ * - NVIDIA has rendering but no memory persistence
+ * - OpenMind has robot payments but no spatial proof
+ * - FOAM/Auki has proof-of-location but no payments
+ *
+ * GridStamp sits at the intersection.
+ *
+ * API:
+ *   agent.see()            — Capture + process current view
+ *   agent.remember()       — Store spatial context to memory
+ *   agent.navigate()       — Plan path to target
+ *   agent.verifySpatial()  — Prove robot is at claimed location
+ *   agent.settle()         — Payment with spatial proof requirement
+ */
+
+// Re-export all public types
+export type {
+  Vec3,
+  Quaternion,
+  Pose,
+  Mat4,
+  AABB,
+  CameraIntrinsics,
+  StereoConfig,
+  CameraFrame,
+  DepthMap,
+  CameraConfig,
+  GaussianSplat,
+  SplatScene,
+  RenderedView,
+  ShortTermEntry,
+  EpisodicMemory,
+  LongTermMemory,
+  ConsolidationEvent,
+  PlaceCell,
+  GridCell,
+  SpatialCode,
+  Waypoint,
+  Path,
+  SpatialMetrics,
+  VerificationThresholds,
+  SpatialProof,
+  SpatialSettlement,
+  ThreatDetection,
+  FrameIntegrity,
+  GridStampConfig,
+  GridStampAgent,
+} from './types/index.js';
+
+export {
+  CameraType,
+  MemoryTier,
+  PathAlgorithm,
+  ReferenceFrame,
+  SettlementStatus,
+  ThreatType,
+  ThreatSeverity,
+} from './types/index.js';
+
+// Re-export modules
+export * from './perception/index.js';
+export * from './memory/index.js';
+export * from './navigation/index.js';
+export * from './verification/index.js';
+export * from './antispoofing/index.js';
+export * from './gamification/index.js';
+
+// Re-export key utilities
+export {
+  hmacSign,
+  hmacVerify,
+  signFrame,
+  verifyFrame,
+  generateNonce,
+  sha256,
+  deriveKey,
+} from './utils/crypto.js';
+
+export {
+  vec3Distance,
+  vec3Add,
+  vec3Sub,
+  vec3Scale,
+  vec3Normalize,
+  egoToAllo,
+  alloToEgo,
+  stereoDepth,
+  gaussian3D,
+  meanAbsoluteError,
+  poseToMat4,
+  quatRotateVec3,
+  quatSlerp,
+} from './utils/math.js';
+
+// ============================================================
+// AGENT FACTORY
+// ============================================================
+
+import type {
+  GridStampConfig,
+  GridStampAgent as IGridStampAgent,
+  CameraFrame,
+  EpisodicMemory,
+  Path,
+  SpatialProof,
+  SpatialSettlement,
+  SpatialCode,
+  Pose,
+  Vec3,
+  PathAlgorithm,
+  VerificationThresholds,
+} from './types/index.js';
+import type { CameraDriver } from './perception/index.js';
+import { FrameCapture } from './perception/index.js';
+import {
+  ShortTermMemory,
+  MidTermMemory,
+  LongTermMemory as LongTermMemoryStore,
+  MemoryConsolidator,
+} from './memory/index.js';
+import { PlaceCellPopulation, GridCellSystem, computeSpatialCode } from './memory/index.js';
+import { OccupancyGrid, planPath } from './navigation/index.js';
+import {
+  generateSpatialProof,
+  createSettlement,
+} from './verification/index.js';
+import { FrameIntegrityChecker, CanarySystem } from './antispoofing/index.js';
+import { deriveKey } from './utils/crypto.js';
+
+/**
+ * Create a GridStamp agent
+ *
+ * This is the main entry point. Pass a config + camera driver,
+ * get back an agent with see/remember/navigate/verify/settle methods.
+ */
+export function createAgent(
+  config: GridStampConfig,
+  primaryDriver: CameraDriver,
+): IGridStampAgent {
+  // Validate config
+  if (!config.robotId) throw new Error('robotId is required');
+  if (!config.hmacSecret || config.hmacSecret.length < 32) {
+    throw new Error('hmacSecret must be at least 32 characters');
+  }
+
+  // Derive separate keys for each subsystem (key separation)
+  const frameKey = deriveKey(config.hmacSecret, 'frame-signing');
+  const memoryKey = deriveKey(config.hmacSecret, 'memory-signing');
+  const proofKey = config.hmacSecret; // proof uses master key
+
+  // Initialize subsystems
+  const frameCapture = new FrameCapture(
+    primaryDriver,
+    config.cameras[0]!,
+    frameKey,
+  );
+
+  const shortTerm = new ShortTermMemory(
+    900,
+    config.memoryConfig?.shortTermTTL ?? 30_000,
+  );
+  const midTerm = new MidTermMemory(
+    config.memoryConfig?.midTermMaxEntries ?? 1000,
+  );
+  const longTermStore = new LongTermMemoryStore(memoryKey);
+  const consolidator = new MemoryConsolidator(shortTerm, midTerm, longTermStore);
+
+  const placeCells = new PlaceCellPopulation();
+  const gridCells = new GridCellSystem();
+
+  const integrityChecker = new FrameIntegrityChecker(frameKey);
+  const canaries = new CanarySystem(memoryKey);
+
+  let lastFrame: CameraFrame | undefined;
+  let initialized = false;
+
+  const agent: IGridStampAgent = {
+    async see(): Promise<CameraFrame> {
+      if (!initialized) {
+        await frameCapture.initialize();
+        initialized = true;
+      }
+
+      const frame = await frameCapture.capture();
+
+      // Run integrity check on every frame (fail-closed)
+      const integrity = integrityChecker.check(frame);
+      if (!integrityChecker.isSafe(integrity)) {
+        const criticalThreats = integrity.threats
+          .filter(t => t.severity === 'critical')
+          .map(t => t.details)
+          .join('; ');
+        throw new Error(`Frame rejected by anti-spoofing: ${criticalThreats}`);
+      }
+
+      // Store in short-term memory (empty splats for now — 3DGS integration point)
+      shortTerm.add(frame, []);
+
+      // Auto-generate place cell at frame position if we have pose
+      if (frame.pose) {
+        const cell = (await import('./memory/place-cells.js')).createPlaceCell(
+          frame.pose.position,
+        );
+        placeCells.add(cell);
+      }
+
+      lastFrame = frame;
+      return frame;
+    },
+
+    async remember(tags?: string[]): Promise<EpisodicMemory> {
+      const consolidated = consolidator.consolidateToMidTerm(tags ?? []);
+      if (!consolidated) {
+        // Even if not enough for full consolidation, store what we have
+        const entries = shortTerm.getAll();
+        if (entries.length === 0) {
+          throw new Error('No frames in short-term memory to remember');
+        }
+        // Force store
+        const allSplats = entries.flatMap(e => e.splats);
+        const scene = {
+          id: (await import('./utils/crypto.js')).generateNonce(16),
+          splats: allSplats,
+          count: allSplats.length,
+          boundingBox: {
+            min: { x: 0, y: 0, z: 0 },
+            max: { x: 0, y: 0, z: 0 },
+          },
+          createdAt: Date.now(),
+        };
+        const location = lastFrame?.pose?.position ?? { x: 0, y: 0, z: 0 };
+        return midTerm.store(scene, location, tags ?? []);
+      }
+
+      // Get the most recent mid-term memory
+      const memories = midTerm.findNear(
+        lastFrame?.pose?.position ?? { x: 0, y: 0, z: 0 },
+        100,
+      );
+      return memories[0]!;
+    },
+
+    async navigate(target: Vec3, options?: { algorithm?: PathAlgorithm }): Promise<Path> {
+      const start = lastFrame?.pose?.position ?? { x: 0, y: 0, z: 0 };
+      const bounds = {
+        min: {
+          x: Math.min(start.x, target.x) - 10,
+          y: Math.min(start.y, target.y) - 10,
+          z: Math.min(start.z, target.z) - 2,
+        },
+        max: {
+          x: Math.max(start.x, target.x) + 10,
+          y: Math.max(start.y, target.y) + 10,
+          z: Math.max(start.z, target.z) + 2,
+        },
+      };
+      const grid = new OccupancyGrid(bounds);
+      const algorithm = options?.algorithm ?? config.navigationConfig?.defaultAlgorithm ?? 'a-star' as PathAlgorithm;
+      const path = planPath(start, target, grid, bounds, algorithm);
+      if (!path) throw new Error('No path found to target');
+      return path;
+    },
+
+    async verifySpatial(claimedPose?: Pose): Promise<SpatialProof> {
+      if (!lastFrame) throw new Error('No frame captured. Call see() first.');
+
+      const pose = claimedPose ?? lastFrame.pose;
+      if (!pose) throw new Error('No pose available. Provide claimedPose or ensure camera provides pose.');
+
+      // In production, this would render from long-term memory 3DGS
+      // For now, use the last frame as "expected" (self-verification)
+      const expectedRender = {
+        rgb: lastFrame.rgb,
+        depth: lastFrame.depth ?? new Float32Array(0),
+        width: lastFrame.width,
+        height: lastFrame.height,
+        pose,
+        renderTimeMs: 0,
+      };
+
+      return generateSpatialProof(
+        config.robotId,
+        pose,
+        lastFrame,
+        expectedRender,
+        'pending-merkle-root', // would come from long-term memory
+        [],
+        proofKey,
+        config.verificationThresholds as VerificationThresholds | undefined,
+      );
+    },
+
+    async settle(params: {
+      amount: number;
+      currency: string;
+      payeeId: string;
+      spatialProof: boolean;
+    }): Promise<SpatialSettlement> {
+      if (!params.spatialProof) {
+        throw new Error('GridStamp requires spatialProof=true. Use MnemoPay directly for non-spatial payments.');
+      }
+
+      const proof = await agent.verifySpatial();
+      return createSettlement(proof, params.amount, params.currency, params.payeeId, proofKey);
+    },
+
+    getSpatialCode(): SpatialCode {
+      const position = lastFrame?.pose?.position ?? { x: 0, y: 0, z: 0 };
+      return computeSpatialCode(position, placeCells, gridCells);
+    },
+
+    getMemoryStats() {
+      const shortEntries = shortTerm.getAll();
+      return {
+        shortTerm: {
+          count: shortTerm.count,
+          oldestMs: shortEntries.length > 0 ? Date.now() - shortEntries[0]!.timestamp : 0,
+        },
+        midTerm: {
+          count: midTerm.count,
+          totalSplats: midTerm.getTotalSplatCount(),
+        },
+        longTerm: {
+          count: longTermStore.totalEntries,
+          rooms: longTermStore.roomCount,
+        },
+      };
+    },
+
+    async shutdown(): Promise<void> {
+      await frameCapture.shutdown();
+      integrityChecker.reset();
+    },
+  };
+
+  return agent;
+}

package/src/memory/index.ts

@@ -0,0 +1,9 @@
+export { ShortTermMemory, MidTermMemory, LongTermMemory, MemoryConsolidator } from './spatial-memory.js';
+export {
+  createPlaceCell,
+  PlaceCellPopulation,
+  createGridCell,
+  GridCellModule,
+  GridCellSystem,
+  computeSpatialCode,
+} from './place-cells.js';

package/src/memory/place-cells.ts

@@ -0,0 +1,279 @@
+/**
+ * Place Cell & Grid Cell Model (Bio-inspired spatial coding)
+ *
+ * Based on Nobel Prize 2014 work:
+ * - Place cells (O'Keefe, 1971): Neurons in hippocampus that fire at specific locations
+ * - Grid cells (Moser & Moser, 2005): Neurons in entorhinal cortex with hexagonal firing patterns
+ *
+ * Together they form a biological GPS for spatial coding.
+ * We use them to create robust position estimates from noisy sensor data.
+ */
+import type { Vec3, PlaceCell, GridCell, SpatialCode } from '../types/index.js';
+import { vec3Distance, gaussian3D } from '../utils/math.js';
+import { generateNonce } from '../utils/crypto.js';
+
+// ============================================================
+// PLACE CELLS
+// ============================================================
+
+/**
+ * Create a place cell centered at a specific location
+ * Activation follows a 3D Gaussian: peaks at center, falls off with distance
+ */
+export function createPlaceCell(
+  center: Vec3,
+  radius: number = 2.0, // meters — typical place field radius
+  peakRate: number = 1.0,
+): PlaceCell {
+  const id = `pc_${generateNonce(8)}`;
+  const sigma = radius / 2.0; // sigma = half the field radius
+
+  return {
+    id,
+    center,
+    radius,
+    peakRate,
+    activation(position: Vec3): number {
+      return gaussian3D(position, center, sigma, peakRate);
+    },
+  };
+}
+
+/**
+ * Place cell population — manages a set of place cells covering an environment
+ */
+export class PlaceCellPopulation {
+  private cells: PlaceCell[] = [];
+  private readonly minSpacing: number; // minimum distance between cell centers
+
+  constructor(minSpacing: number = 1.5) {
+    this.minSpacing = minSpacing;
+  }
+
+  /** Add a place cell (reject if too close to existing cell) */
+  add(cell: PlaceCell): boolean {
+    for (const existing of this.cells) {
+      if (vec3Distance(existing.center, cell.center) < this.minSpacing) {
+        return false; // too close to existing cell
+      }
+    }
+    this.cells.push(cell);
+    return true;
+  }
+
+  /**
+   * Auto-generate place cells to cover a region
+   * Uses a quasi-random distribution for even coverage
+   */
+  coverRegion(
+    min: Vec3,
+    max: Vec3,
+    spacing: number = 2.0,
+    radius: number = 2.0,
+  ): number {
+    let count = 0;
+    for (let x = min.x; x <= max.x; x += spacing) {
+      for (let y = min.y; y <= max.y; y += spacing) {
+        for (let z = min.z; z <= max.z; z += spacing) {
+          const cell = createPlaceCell({ x, y, z }, radius);
+          if (this.add(cell)) count++;
+        }
+      }
+    }
+    return count;
+  }
+
+  /**
+   * Get activation of all place cells for a position
+   * Returns map of cell ID → activation level [0,1]
+   */
+  getActivations(position: Vec3): ReadonlyMap<string, number> {
+    const activations = new Map<string, number>();
+    for (const cell of this.cells) {
+      const a = cell.activation(position);
+      if (a > 0.01) { // threshold noise
+        activations.set(cell.id, a);
+      }
+    }
+    return activations;
+  }
+
+  /**
+   * Estimate position from place cell activations (population vector decoding)
+   * Weighted average of cell centers by activation level
+   */
+  decodePosition(activations: ReadonlyMap<string, number>): Vec3 {
+    let totalWeight = 0;
+    let wx = 0, wy = 0, wz = 0;
+
+    for (const [id, activation] of activations) {
+      const cell = this.cells.find(c => c.id === id);
+      if (!cell) continue;
+      wx += cell.center.x * activation;
+      wy += cell.center.y * activation;
+      wz += cell.center.z * activation;
+      totalWeight += activation;
+    }
+
+    if (totalWeight < 1e-10) {
+      return { x: 0, y: 0, z: 0 };
+    }
+    return {
+      x: wx / totalWeight,
+      y: wy / totalWeight,
+      z: wz / totalWeight,
+    };
+  }
+
+  get count(): number {
+    return this.cells.length;
+  }
+}
+
+// ============================================================
+// GRID CELLS
+// ============================================================
+
+/**
+ * Create a grid cell with hexagonal firing pattern
+ *
+ * Grid cells fire at regular intervals forming a hexagonal tiling.
+ * The activation is the sum of 3 cosine waves at 60° intervals.
+ * Parameters: spacing (period), orientation (rotation), phase (offset)
+ */
+export function createGridCell(
+  spacing: number = 1.0, // meters between grid vertices
+  orientation: number = 0, // radians
+  phase: Vec3 = { x: 0, y: 0, z: 0 },
+): GridCell {
+  const id = `gc_${generateNonce(8)}`;
+  const k = (2 * Math.PI) / spacing; // wave number
+
+  // Three direction vectors at 60° intervals (hexagonal)
+  const dirs = [0, Math.PI / 3, 2 * Math.PI / 3].map(angle => {
+    const a = angle + orientation;
+    return { x: Math.cos(a), y: Math.sin(a) };
+  });
+
+  return {
+    id,
+    spacing,
+    orientation,
+    phase,
+    activation(position: Vec3): number {
+      // Sum of 3 cosine waves creates hexagonal pattern
+      let sum = 0;
+      for (const dir of dirs) {
+        const proj = (position.x - phase.x) * dir.x + (position.y - phase.y) * dir.y;
+        sum += Math.cos(k * proj);
+      }
+      // Normalize from [-3, 3] to [0, 1]
+      return (sum + 3) / 6;
+    },
+  };
+}
+
+/**
+ * Grid cell module — a group of grid cells with the same spacing but different phases
+ * Multiple modules at different scales form a hierarchical coordinate system
+ */
+export class GridCellModule {
+  private cells: GridCell[] = [];
+  readonly spacing: number;
+  readonly orientation: number;
+
+  constructor(spacing: number, orientation: number, cellCount: number = 16) {
+    this.spacing = spacing;
+    this.orientation = orientation;
+
+    // Generate cells with different random phases
+    for (let i = 0; i < cellCount; i++) {
+      const phase: Vec3 = {
+        x: (Math.random() - 0.5) * spacing,
+        y: (Math.random() - 0.5) * spacing,
+        z: 0,
+      };
+      this.cells.push(createGridCell(spacing, orientation, phase));
+    }
+  }
+
+  getActivations(position: Vec3): ReadonlyMap<string, number> {
+    const activations = new Map<string, number>();
+    for (const cell of this.cells) {
+      activations.set(cell.id, cell.activation(position));
+    }
+    return activations;
+  }
+
+  get count(): number {
+    return this.cells.length;
+  }
+}
+
+/**
+ * Multi-scale grid cell system
+ * Uses modules at different spacings (like a multi-resolution ruler)
+ * Typical ratios: 1:1.4:2:2.8 (approximate √2 scaling)
+ */
+export class GridCellSystem {
+  private modules: GridCellModule[] = [];
+
+  constructor(
+    baseSpacing: number = 0.5,
+    scaleRatio: number = Math.SQRT2,
+    numModules: number = 4,
+    cellsPerModule: number = 16,
+  ) {
+    for (let i = 0; i < numModules; i++) {
+      const spacing = baseSpacing * Math.pow(scaleRatio, i);
+      const orientation = (i * Math.PI) / (6 * numModules); // slight rotation per module
+      this.modules.push(new GridCellModule(spacing, orientation, cellsPerModule));
+    }
+  }
+
+  getActivations(position: Vec3): ReadonlyMap<string, number> {
+    const all = new Map<string, number>();
+    for (const module of this.modules) {
+      for (const [id, activation] of module.getActivations(position)) {
+        all.set(id, activation);
+      }
+    }
+    return all;
+  }
+
+  get totalCells(): number {
+    return this.modules.reduce((sum, m) => sum + m.count, 0);
+  }
+}
+
+// ============================================================
+// SPATIAL CODING — combined place + grid cell system
+// ============================================================
+
+/**
+ * Compute full spatial code for a position
+ * Combines place cell and grid cell activations into a population vector
+ */
+export function computeSpatialCode(
+  position: Vec3,
+  placeCells: PlaceCellPopulation,
+  gridCells: GridCellSystem,
+): SpatialCode {
+  const placeActivations = placeCells.getActivations(position);
+  const gridActivations = gridCells.getActivations(position);
+
+  // Confidence based on number of active place cells
+  const activePlaceCells = [...placeActivations.values()].filter(a => a > 0.1).length;
+  const confidence = Math.min(1, activePlaceCells / 3); // 3+ active cells = full confidence
+
+  // Position estimate from place cell decoding
+  const estimatedPosition = placeCells.decodePosition(placeActivations);
+
+  return {
+    placeCellActivations: placeActivations,
+    gridCellActivations: gridActivations,
+    estimatedPosition,
+    confidence,
+    timestamp: Date.now(),
+  };
+}