gridstamp 1.0.0

package/src/gamification/trust-tiers.ts

@@ -0,0 +1,393 @@
+/**
+ * Trust Tier System — Progressive robot trust based on verified operations
+ *
+ * Maps WeMeetWeMet's 5-level progression to robot fleet management:
+ *   Untrusted → Probation → Verified → Trusted → Elite → Autonomous
+ *
+ * Each tier controls: fee multiplier, tx limits, verification frequency, autonomy level.
+ * Tier changes are HMAC-signed to prevent forgery.
+ */
+
+import { hmacSign, hmacVerify, generateNonce } from '../utils/crypto.js';
+
+export enum TrustTier {
+  UNTRUSTED = 0,
+  PROBATION = 1,
+  VERIFIED = 2,
+  TRUSTED = 3,
+  ELITE = 4,
+  AUTONOMOUS = 5,
+}
+
+export interface TierConfig {
+  readonly name: string;
+  readonly minPoints: number;
+  readonly feeMultiplier: number;       // 1.0 = base fee, lower = discount
+  readonly maxTransactionAmount: number; // max single tx
+  readonly verificationFrequency: number; // every N operations must verify
+  readonly autonomyLevel: number;         // 0-100, how much unsupervised action
+  readonly minStreakDays: number;          // minimum consecutive days for promotion
+  readonly minBadges: number;             // minimum badges required
+  readonly minZoneMastery: number;        // minimum zone mastery score [0,1]
+}
+
+export const TIER_CONFIGS: Readonly<Record<TrustTier, TierConfig>> = {
+  [TrustTier.UNTRUSTED]: {
+    name: 'Untrusted',
+    minPoints: 0,
+    feeMultiplier: 2.5,
+    maxTransactionAmount: 10,
+    verificationFrequency: 1,   // verify EVERY operation
+    autonomyLevel: 0,
+    minStreakDays: 0,
+    minBadges: 0,
+    minZoneMastery: 0,
+  },
+  [TrustTier.PROBATION]: {
+    name: 'Probation',
+    minPoints: 100,
+    feeMultiplier: 2.0,
+    maxTransactionAmount: 50,
+    verificationFrequency: 1,
+    autonomyLevel: 10,
+    minStreakDays: 3,
+    minBadges: 1,
+    minZoneMastery: 0.1,
+  },
+  [TrustTier.VERIFIED]: {
+    name: 'Verified',
+    minPoints: 500,
+    feeMultiplier: 1.5,
+    maxTransactionAmount: 200,
+    verificationFrequency: 3,   // every 3rd operation
+    autonomyLevel: 40,
+    minStreakDays: 7,
+    minBadges: 3,
+    minZoneMastery: 0.3,
+  },
+  [TrustTier.TRUSTED]: {
+    name: 'Trusted',
+    minPoints: 2000,
+    feeMultiplier: 1.2,
+    maxTransactionAmount: 1000,
+    verificationFrequency: 5,
+    autonomyLevel: 70,
+    minStreakDays: 14,
+    minBadges: 8,
+    minZoneMastery: 0.5,
+  },
+  [TrustTier.ELITE]: {
+    name: 'Elite',
+    minPoints: 5000,
+    feeMultiplier: 1.0,
+    maxTransactionAmount: 5000,
+    verificationFrequency: 10,
+    autonomyLevel: 90,
+    minStreakDays: 30,
+    minBadges: 15,
+    minZoneMastery: 0.7,
+  },
+  [TrustTier.AUTONOMOUS]: {
+    name: 'Autonomous',
+    minPoints: 10000,
+    feeMultiplier: 0.8,           // discount for top-tier
+    maxTransactionAmount: 25000,
+    verificationFrequency: 20,    // spot checks only
+    autonomyLevel: 100,
+    minStreakDays: 60,
+    minBadges: 20,
+    minZoneMastery: 0.85,
+  },
+};
+
+export interface TierChangeEvent {
+  readonly id: string;
+  readonly robotId: string;
+  readonly previousTier: TrustTier;
+  readonly newTier: TrustTier;
+  readonly reason: string;
+  readonly points: number;
+  readonly timestamp: number;
+  readonly signature: string; // HMAC-signed to prevent forgery
+}
+
+export interface RobotTrustProfile {
+  readonly robotId: string;
+  readonly currentTier: TrustTier;
+  readonly points: number;
+  readonly totalVerifications: number;
+  readonly successfulVerifications: number;
+  readonly failedVerifications: number;
+  readonly spoofingIncidents: number;
+  readonly consecutiveSuccesses: number;
+  readonly history: readonly TierChangeEvent[];
+  readonly createdAt: number;
+  readonly lastActivityAt: number;
+}
+
+/**
+ * Sign a tier change event to prevent forgery
+ */
+function signTierChange(
+  robotId: string,
+  previousTier: TrustTier,
+  newTier: TrustTier,
+  points: number,
+  timestamp: number,
+  secret: string,
+): string {
+  const payload = `tier-change:${robotId}:${previousTier}:${newTier}:${points}:${timestamp}`;
+  return hmacSign(Buffer.from(payload), secret);
+}
+
+/**
+ * Verify a tier change event signature
+ */
+export function verifyTierChange(event: TierChangeEvent, secret: string): boolean {
+  const payload = `tier-change:${event.robotId}:${event.previousTier}:${event.newTier}:${event.points}:${event.timestamp}`;
+  return hmacVerify(Buffer.from(payload), event.signature, secret);
+}
+
+export class TrustTierSystem {
+  private readonly profiles = new Map<string, RobotTrustProfile>();
+  private readonly secret: string;
+
+  constructor(secret: string) {
+    if (!secret || secret.length < 32) {
+      throw new Error('TrustTierSystem requires a secret of at least 32 chars');
+    }
+    this.secret = secret;
+  }
+
+  /**
+   * Register a new robot (starts at Untrusted)
+   */
+  register(robotId: string): RobotTrustProfile {
+    if (!robotId || robotId.trim().length === 0) {
+      throw new Error('robotId is required');
+    }
+    if (this.profiles.has(robotId)) {
+      throw new Error(`Robot ${robotId} already registered`);
+    }
+    const now = Date.now();
+    const profile: RobotTrustProfile = {
+      robotId,
+      currentTier: TrustTier.UNTRUSTED,
+      points: 0,
+      totalVerifications: 0,
+      successfulVerifications: 0,
+      failedVerifications: 0,
+      spoofingIncidents: 0,
+      consecutiveSuccesses: 0,
+      history: [],
+      createdAt: now,
+      lastActivityAt: now,
+    };
+    this.profiles.set(robotId, profile);
+    return profile;
+  }
+
+  /**
+   * Get a robot's current trust profile
+   */
+  getProfile(robotId: string): RobotTrustProfile | undefined {
+    return this.profiles.get(robotId);
+  }
+
+  /**
+   * Record a successful spatial verification and award points
+   */
+  recordSuccess(robotId: string, pointsEarned: number): RobotTrustProfile {
+    const profile = this.profiles.get(robotId);
+    if (!profile) throw new Error(`Robot ${robotId} not registered`);
+    if (pointsEarned < 0) throw new Error('Points earned must be non-negative');
+
+    const updated: RobotTrustProfile = {
+      ...profile,
+      points: profile.points + pointsEarned,
+      totalVerifications: profile.totalVerifications + 1,
+      successfulVerifications: profile.successfulVerifications + 1,
+      consecutiveSuccesses: profile.consecutiveSuccesses + 1,
+      lastActivityAt: Date.now(),
+    };
+    this.profiles.set(robotId, updated);
+    return this.checkPromotion(robotId);
+  }
+
+  /**
+   * Record a failed verification — penalty + possible demotion
+   */
+  recordFailure(robotId: string, isSpoofingAttempt: boolean = false): RobotTrustProfile {
+    const profile = this.profiles.get(robotId);
+    if (!profile) throw new Error(`Robot ${robotId} not registered`);
+
+    // Penalty: lose 10% of points on failure, 25% on spoofing
+    const penalty = isSpoofingAttempt
+      ? Math.floor(profile.points * 0.25)
+      : Math.floor(profile.points * 0.10);
+
+    const updated: RobotTrustProfile = {
+      ...profile,
+      points: Math.max(0, profile.points - penalty),
+      totalVerifications: profile.totalVerifications + 1,
+      failedVerifications: profile.failedVerifications + 1,
+      spoofingIncidents: profile.spoofingIncidents + (isSpoofingAttempt ? 1 : 0),
+      consecutiveSuccesses: 0, // reset streak
+      lastActivityAt: Date.now(),
+    };
+    this.profiles.set(robotId, updated);
+    return this.checkDemotion(robotId, isSpoofingAttempt);
+  }
+
+  /**
+   * Check if robot qualifies for tier promotion
+   */
+  private checkPromotion(robotId: string): RobotTrustProfile {
+    const profile = this.profiles.get(robotId)!;
+    const currentTier = profile.currentTier;
+
+    // Can't promote beyond Autonomous
+    if (currentTier >= TrustTier.AUTONOMOUS) return profile;
+
+    const nextTier = (currentTier + 1) as TrustTier;
+    const nextConfig = TIER_CONFIGS[nextTier];
+
+    // Check all promotion criteria
+    if (profile.points < nextConfig.minPoints) return profile;
+
+    // Success rate must be > 90% for promotion
+    if (profile.totalVerifications > 0) {
+      const successRate = profile.successfulVerifications / profile.totalVerifications;
+      if (successRate < 0.9) return profile;
+    }
+
+    // No spoofing incidents allowed for Trusted+
+    if (nextTier >= TrustTier.TRUSTED && profile.spoofingIncidents > 0) return profile;
+
+    return this.changeTier(robotId, nextTier, 'Promotion: met all tier requirements');
+  }
+
+  /**
+   * Check if robot should be demoted
+   */
+  private checkDemotion(robotId: string, wasSpoofing: boolean): RobotTrustProfile {
+    const profile = this.profiles.get(robotId)!;
+    const currentTier = profile.currentTier;
+
+    // Can't demote below Untrusted
+    if (currentTier <= TrustTier.UNTRUSTED) return profile;
+
+    // Immediate demotion on spoofing if Trusted or above
+    if (wasSpoofing && currentTier >= TrustTier.TRUSTED) {
+      // Drop TWO tiers for spoofing at high trust
+      const newTier = Math.max(TrustTier.UNTRUSTED, currentTier - 2) as TrustTier;
+      return this.changeTier(robotId, newTier, 'Demotion: spoofing detected at high trust level');
+    }
+
+    // Demote if points dropped below current tier minimum
+    const currentConfig = TIER_CONFIGS[currentTier];
+    if (profile.points < currentConfig.minPoints) {
+      const newTier = (currentTier - 1) as TrustTier;
+      return this.changeTier(robotId, newTier, 'Demotion: points below tier minimum');
+    }
+
+    // Demote if success rate drops below 80%
+    if (profile.totalVerifications >= 10) {
+      const successRate = profile.successfulVerifications / profile.totalVerifications;
+      if (successRate < 0.8) {
+        const newTier = (currentTier - 1) as TrustTier;
+        return this.changeTier(robotId, newTier, 'Demotion: success rate below 80%');
+      }
+    }
+
+    return profile;
+  }
+
+  /**
+   * Execute tier change with HMAC-signed event
+   */
+  private changeTier(robotId: string, newTier: TrustTier, reason: string): RobotTrustProfile {
+    const profile = this.profiles.get(robotId)!;
+    if (profile.currentTier === newTier) return profile;
+
+    const now = Date.now();
+    const signature = signTierChange(
+      robotId,
+      profile.currentTier,
+      newTier,
+      profile.points,
+      now,
+      this.secret,
+    );
+
+    const event: TierChangeEvent = {
+      id: generateNonce(16),
+      robotId,
+      previousTier: profile.currentTier,
+      newTier,
+      reason,
+      points: profile.points,
+      timestamp: now,
+      signature,
+    };
+
+    const updated: RobotTrustProfile = {
+      ...profile,
+      currentTier: newTier,
+      history: [...profile.history, event],
+    };
+    this.profiles.set(robotId, updated);
+    return updated;
+  }
+
+  /**
+   * Get the fee multiplier for a robot
+   */
+  getFeeMultiplier(robotId: string): number {
+    const profile = this.profiles.get(robotId);
+    if (!profile) return TIER_CONFIGS[TrustTier.UNTRUSTED].feeMultiplier;
+    return TIER_CONFIGS[profile.currentTier].feeMultiplier;
+  }
+
+  /**
+   * Check if a transaction amount is within tier limits
+   */
+  isWithinLimits(robotId: string, amount: number): boolean {
+    const profile = this.profiles.get(robotId);
+    if (!profile) return amount <= TIER_CONFIGS[TrustTier.UNTRUSTED].maxTransactionAmount;
+    return amount <= TIER_CONFIGS[profile.currentTier].maxTransactionAmount;
+  }
+
+  /**
+   * Check if verification is required for this operation
+   */
+  requiresVerification(robotId: string, operationIndex: number): boolean {
+    const profile = this.profiles.get(robotId);
+    if (!profile) return true; // unknown robots always verify
+    const freq = TIER_CONFIGS[profile.currentTier].verificationFrequency;
+    return operationIndex % freq === 0;
+  }
+
+  /**
+   * Get all registered robots count
+   */
+  get robotCount(): number {
+    return this.profiles.size;
+  }
+
+  /**
+   * Verify integrity of a robot's entire tier history
+   */
+  verifyHistory(robotId: string): { valid: boolean; invalidEvents: number[] } {
+    const profile = this.profiles.get(robotId);
+    if (!profile) return { valid: false, invalidEvents: [] };
+
+    const invalidEvents: number[] = [];
+    for (let i = 0; i < profile.history.length; i++) {
+      if (!verifyTierChange(profile.history[i]!, this.secret)) {
+        invalidEvents.push(i);
+      }
+    }
+    return { valid: invalidEvents.length === 0, invalidEvents };
+  }
+}

package/src/gamification/zone-mastery.ts

@@ -0,0 +1,256 @@
+/**
+ * Zone Mastery System — Geographic expertise tracking
+ *
+ * Maps WeMeetWeMet's venue collection to robot spatial knowledge:
+ *   Zone = AABB region of space
+ *   Mastery = coverage × success_rate × time_factor
+ *   Higher mastery = more trusted operations in that zone
+ */
+
+import type { Vec3, AABB } from '../types/index.js';
+import { hmacSign, generateNonce } from '../utils/crypto.js';
+
+export interface Zone {
+  readonly id: string;
+  readonly name: string;
+  readonly bounds: AABB;
+  readonly createdAt: number;
+}
+
+export interface ZoneMasteryRecord {
+  readonly zoneId: string;
+  readonly robotId: string;
+  readonly visitCount: number;
+  readonly successCount: number;
+  readonly failureCount: number;
+  readonly totalPointsInZone: number;
+  readonly uniquePositions: number;   // distinct locations visited (discretized)
+  readonly firstVisit: number;
+  readonly lastVisit: number;
+}
+
+export interface ZoneMasteryScore {
+  readonly zoneId: string;
+  readonly coverage: number;      // 0-1: how much of zone explored
+  readonly successRate: number;    // 0-1: verification success rate
+  readonly timeFactor: number;     // 0-1: recency + duration
+  readonly composite: number;      // weighted combination
+}
+
+function positionKey(pos: Vec3, gridSize: number): string {
+  const gx = Math.floor(pos.x / gridSize);
+  const gy = Math.floor(pos.y / gridSize);
+  const gz = Math.floor(pos.z / gridSize);
+  return `${gx}:${gy}:${gz}`;
+}
+
+function isInBounds(pos: Vec3, bounds: AABB): boolean {
+  return (
+    pos.x >= bounds.min.x && pos.x <= bounds.max.x &&
+    pos.y >= bounds.min.y && pos.y <= bounds.max.y &&
+    pos.z >= bounds.min.z && pos.z <= bounds.max.z
+  );
+}
+
+function zoneVolume(bounds: AABB): number {
+  return (
+    (bounds.max.x - bounds.min.x) *
+    (bounds.max.y - bounds.min.y) *
+    Math.max(1, bounds.max.z - bounds.min.z) // avoid zero for 2D zones
+  );
+}
+
+export class ZoneMasterySystem {
+  private readonly zones = new Map<string, Zone>();
+  private readonly mastery = new Map<string, ZoneMasteryRecord>(); // "robotId:zoneId" → record
+  private readonly visitedPositions = new Map<string, Set<string>>(); // "robotId:zoneId" → position keys
+  private readonly secret: string;
+  private readonly gridSize: number; // meters per cell for discretization
+
+  constructor(secret: string, gridSize: number = 2.0) {
+    if (!secret || secret.length < 32) {
+      throw new Error('ZoneMasterySystem requires a secret of at least 32 chars');
+    }
+    this.secret = secret;
+    this.gridSize = gridSize;
+  }
+
+  /**
+   * Define a new zone
+   */
+  defineZone(name: string, bounds: AABB): Zone {
+    if (!name) throw new Error('Zone name is required');
+    if (bounds.min.x >= bounds.max.x || bounds.min.y >= bounds.max.y) {
+      throw new Error('Invalid zone bounds: min must be less than max');
+    }
+    const zone: Zone = {
+      id: generateNonce(8),
+      name,
+      bounds,
+      createdAt: Date.now(),
+    };
+    this.zones.set(zone.id, zone);
+    return zone;
+  }
+
+  /**
+   * Find which zone a position belongs to (first match)
+   */
+  findZone(position: Vec3): Zone | undefined {
+    for (const zone of this.zones.values()) {
+      if (isInBounds(position, zone.bounds)) {
+        return zone;
+      }
+    }
+    return undefined;
+  }
+
+  /**
+   * Find all zones a position belongs to
+   */
+  findAllZones(position: Vec3): Zone[] {
+    const result: Zone[] = [];
+    for (const zone of this.zones.values()) {
+      if (isInBounds(position, zone.bounds)) {
+        result.push(zone);
+      }
+    }
+    return result;
+  }
+
+  /**
+   * Record a robot visit to a position (auto-discovers zone)
+   */
+  recordVisit(
+    robotId: string,
+    position: Vec3,
+    success: boolean,
+    pointsEarned: number = 0,
+  ): { zoneId: string | null; mastery: ZoneMasteryScore | null } {
+    if (!robotId) throw new Error('robotId is required');
+
+    const zone = this.findZone(position);
+    if (!zone) return { zoneId: null, mastery: null };
+
+    const key = `${robotId}:${zone.id}`;
+    const existing = this.mastery.get(key);
+    const posKey = positionKey(position, this.gridSize);
+
+    // Track unique positions
+    if (!this.visitedPositions.has(key)) {
+      this.visitedPositions.set(key, new Set());
+    }
+    this.visitedPositions.get(key)!.add(posKey);
+    const uniquePositions = this.visitedPositions.get(key)!.size;
+
+    const now = Date.now();
+    const record: ZoneMasteryRecord = {
+      zoneId: zone.id,
+      robotId,
+      visitCount: (existing?.visitCount ?? 0) + 1,
+      successCount: (existing?.successCount ?? 0) + (success ? 1 : 0),
+      failureCount: (existing?.failureCount ?? 0) + (success ? 0 : 1),
+      totalPointsInZone: (existing?.totalPointsInZone ?? 0) + pointsEarned,
+      uniquePositions,
+      firstVisit: existing?.firstVisit ?? now,
+      lastVisit: now,
+    };
+    this.mastery.set(key, record);
+
+    return { zoneId: zone.id, mastery: this.computeMastery(record, zone) };
+  }
+
+  /**
+   * Compute mastery score for a robot in a zone
+   */
+  private computeMastery(record: ZoneMasteryRecord, zone: Zone): ZoneMasteryScore {
+    // Coverage: unique cells / estimated total cells in zone
+    const vol = zoneVolume(zone.bounds);
+    const cellVol = this.gridSize * this.gridSize * Math.max(this.gridSize, 1);
+    const estimatedCells = Math.max(1, Math.ceil(vol / cellVol));
+    const coverage = Math.min(1, record.uniquePositions / estimatedCells);
+
+    // Success rate
+    const total = record.visitCount;
+    const successRate = total > 0 ? record.successCount / total : 0;
+
+    // Time factor: recency (exponential decay) + duration bonus
+    const now = Date.now();
+    const hoursSinceLastVisit = (now - record.lastVisit) / (1000 * 60 * 60);
+    const recency = Math.exp(-hoursSinceLastVisit / 168); // half-life ~1 week
+    const durationDays = (record.lastVisit - record.firstVisit) / (1000 * 60 * 60 * 24);
+    const durationBonus = Math.min(0.5, durationDays / 60); // max 0.5 after 60 days
+    const timeFactor = Math.min(1, recency * 0.6 + durationBonus + 0.1); // 0.1 base
+
+    // Composite: coverage 40%, success rate 35%, time 25%
+    const composite = coverage * 0.4 + successRate * 0.35 + timeFactor * 0.25;
+
+    return {
+      zoneId: record.zoneId,
+      coverage,
+      successRate,
+      timeFactor,
+      composite,
+    };
+  }
+
+  /**
+   * Get mastery score for a specific robot+zone
+   */
+  getMastery(robotId: string, zoneId: string): ZoneMasteryScore | undefined {
+    const key = `${robotId}:${zoneId}`;
+    const record = this.mastery.get(key);
+    if (!record) return undefined;
+    const zone = this.zones.get(zoneId);
+    if (!zone) return undefined;
+    return this.computeMastery(record, zone);
+  }
+
+  /**
+   * Get all mastery scores for a robot
+   */
+  getAllMastery(robotId: string): ZoneMasteryScore[] {
+    const scores: ZoneMasteryScore[] = [];
+    for (const [key, record] of this.mastery.entries()) {
+      if (!key.startsWith(`${robotId}:`)) continue;
+      const zone = this.zones.get(record.zoneId);
+      if (!zone) continue;
+      scores.push(this.computeMastery(record, zone));
+    }
+    return scores;
+  }
+
+  /**
+   * Get max mastery score across all zones for a robot
+   */
+  getMaxMastery(robotId: string): number {
+    const scores = this.getAllMastery(robotId);
+    if (scores.length === 0) return 0;
+    return Math.max(...scores.map(s => s.composite));
+  }
+
+  /**
+   * Get number of zones a robot has visited
+   */
+  getZoneCount(robotId: string): number {
+    let count = 0;
+    for (const key of this.mastery.keys()) {
+      if (key.startsWith(`${robotId}:`)) count++;
+    }
+    return count;
+  }
+
+  /**
+   * Sign a mastery snapshot for external verification
+   */
+  signMasterySnapshot(robotId: string): { scores: ZoneMasteryScore[]; signature: string } {
+    const scores = this.getAllMastery(robotId);
+    const payload = `mastery:${robotId}:${JSON.stringify(scores)}`;
+    const signature = hmacSign(Buffer.from(payload), this.secret);
+    return { scores, signature };
+  }
+
+  get totalZones(): number {
+    return this.zones.size;
+  }
+}