gridstamp 1.0.0

package/src/gamification/fleet-leaderboard.ts

@@ -0,0 +1,293 @@
+/**
+ * Fleet Leaderboard — Competitive ranking across robot fleets
+ *
+ * Maps WeMeetWeMet's city/state/national leaderboard to fleet management.
+ * Fleet operators compare robots by: trust, deliveries, zones, safety.
+ * Time periods: daily, weekly, monthly, all-time.
+ * Entries are HMAC-signed to prevent tampering.
+ */
+
+import { hmacSign, hmacVerify } from '../utils/crypto.js';
+import { TrustTier } from './trust-tiers.js';
+
+export enum LeaderboardPeriod {
+  DAILY = 'daily',
+  WEEKLY = 'weekly',
+  MONTHLY = 'monthly',
+  ALL_TIME = 'all-time',
+}
+
+export enum LeaderboardMetric {
+  TRUST_SCORE = 'trust_score',
+  DELIVERIES = 'deliveries',
+  ZONE_COVERAGE = 'zone_coverage',
+  SAFETY_RECORD = 'safety_record',
+  COMPOSITE = 'composite',
+}
+
+export interface LeaderboardEntry {
+  readonly robotId: string;
+  readonly fleetId: string;
+  readonly rank: number;
+  readonly score: number;
+  readonly trustTier: TrustTier;
+  readonly totalVerifications: number;
+  readonly successRate: number;
+  readonly zonesExplored: number;
+  readonly badgeCount: number;
+  readonly streakDays: number;
+  readonly maxZoneMastery: number;
+  readonly spoofingIncidents: number;
+  readonly timestamp: number;
+  readonly signature: string;
+}
+
+export interface RobotStats {
+  readonly robotId: string;
+  readonly fleetId: string;
+  readonly trustTier: TrustTier;
+  readonly points: number;
+  readonly totalVerifications: number;
+  readonly successfulVerifications: number;
+  readonly zonesExplored: number;
+  readonly badgeCount: number;
+  readonly streakDays: number;
+  readonly maxZoneMastery: number;
+  readonly spoofingIncidents: number;
+}
+
+export interface FleetSummary {
+  readonly fleetId: string;
+  readonly robotCount: number;
+  readonly averageTrustScore: number;
+  readonly totalDeliveries: number;
+  readonly averageSuccessRate: number;
+  readonly totalZonesExplored: number;
+  readonly topRobotId: string | null;
+}
+
+function signEntry(entry: Omit<LeaderboardEntry, 'signature'>, secret: string): string {
+  const payload = `lb:${entry.robotId}:${entry.fleetId}:${entry.rank}:${entry.score}:${entry.timestamp}`;
+  return hmacSign(Buffer.from(payload), secret);
+}
+
+export function verifyLeaderboardEntry(entry: LeaderboardEntry, secret: string): boolean {
+  const payload = `lb:${entry.robotId}:${entry.fleetId}:${entry.rank}:${entry.score}:${entry.timestamp}`;
+  return hmacVerify(Buffer.from(payload), entry.signature, secret);
+}
+
+function computeCompositeScore(stats: RobotStats): number {
+  const successRate = stats.totalVerifications > 0
+    ? stats.successfulVerifications / stats.totalVerifications
+    : 0;
+
+  // Weighted composite:
+  // Trust tier contribution: 25%
+  const trustScore = (stats.trustTier / TrustTier.AUTONOMOUS) * 100;
+  // Delivery volume: 25%
+  const deliveryScore = Math.min(100, stats.totalVerifications / 100 * 100);
+  // Success rate: 25%
+  const rateScore = successRate * 100;
+  // Safety: 15% (penalize spoofing)
+  const safetyScore = Math.max(0, 100 - stats.spoofingIncidents * 20);
+  // Zone mastery: 10%
+  const zoneScore = stats.maxZoneMastery * 100;
+
+  return trustScore * 0.25 + deliveryScore * 0.25 + rateScore * 0.25 + safetyScore * 0.15 + zoneScore * 0.10;
+}
+
+function computeMetricScore(stats: RobotStats, metric: LeaderboardMetric): number {
+  switch (metric) {
+    case LeaderboardMetric.TRUST_SCORE:
+      return stats.points;
+    case LeaderboardMetric.DELIVERIES:
+      return stats.successfulVerifications;
+    case LeaderboardMetric.ZONE_COVERAGE:
+      return stats.zonesExplored + stats.maxZoneMastery * 100;
+    case LeaderboardMetric.SAFETY_RECORD: {
+      const successRate = stats.totalVerifications > 0
+        ? stats.successfulVerifications / stats.totalVerifications
+        : 0;
+      return successRate * 100 - stats.spoofingIncidents * 10;
+    }
+    case LeaderboardMetric.COMPOSITE:
+      return computeCompositeScore(stats);
+  }
+}
+
+export class FleetLeaderboard {
+  private readonly robotStats = new Map<string, RobotStats>();
+  private readonly secret: string;
+
+  constructor(secret: string) {
+    if (!secret || secret.length < 32) {
+      throw new Error('FleetLeaderboard requires a secret of at least 32 chars');
+    }
+    this.secret = secret;
+  }
+
+  /**
+   * Update stats for a robot
+   */
+  updateStats(stats: RobotStats): void {
+    if (!stats.robotId) throw new Error('robotId is required');
+    if (!stats.fleetId) throw new Error('fleetId is required');
+    this.robotStats.set(stats.robotId, stats);
+  }
+
+  /**
+   * Generate ranked leaderboard for a fleet
+   */
+  getFleetLeaderboard(
+    fleetId: string,
+    metric: LeaderboardMetric = LeaderboardMetric.COMPOSITE,
+    limit: number = 50,
+  ): readonly LeaderboardEntry[] {
+    if (!fleetId) throw new Error('fleetId is required');
+    if (limit <= 0) throw new Error('limit must be positive');
+
+    const fleetRobots: RobotStats[] = [];
+    for (const stats of this.robotStats.values()) {
+      if (stats.fleetId === fleetId) {
+        fleetRobots.push(stats);
+      }
+    }
+
+    // Sort by metric score descending
+    const scored = fleetRobots
+      .map(stats => ({ stats, score: computeMetricScore(stats, metric) }))
+      .sort((a, b) => b.score - a.score)
+      .slice(0, limit);
+
+    const now = Date.now();
+    return scored.map(({ stats, score }, index) => {
+      const successRate = stats.totalVerifications > 0
+        ? stats.successfulVerifications / stats.totalVerifications
+        : 0;
+
+      const entry: Omit<LeaderboardEntry, 'signature'> = {
+        robotId: stats.robotId,
+        fleetId: stats.fleetId,
+        rank: index + 1,
+        score,
+        trustTier: stats.trustTier,
+        totalVerifications: stats.totalVerifications,
+        successRate,
+        zonesExplored: stats.zonesExplored,
+        badgeCount: stats.badgeCount,
+        streakDays: stats.streakDays,
+        maxZoneMastery: stats.maxZoneMastery,
+        spoofingIncidents: stats.spoofingIncidents,
+        timestamp: now,
+      };
+      return { ...entry, signature: signEntry(entry, this.secret) };
+    });
+  }
+
+  /**
+   * Generate global leaderboard across all fleets
+   */
+  getGlobalLeaderboard(
+    metric: LeaderboardMetric = LeaderboardMetric.COMPOSITE,
+    limit: number = 100,
+  ): readonly LeaderboardEntry[] {
+    if (limit <= 0) throw new Error('limit must be positive');
+
+    const all = Array.from(this.robotStats.values());
+    const scored = all
+      .map(stats => ({ stats, score: computeMetricScore(stats, metric) }))
+      .sort((a, b) => b.score - a.score)
+      .slice(0, limit);
+
+    const now = Date.now();
+    return scored.map(({ stats, score }, index) => {
+      const successRate = stats.totalVerifications > 0
+        ? stats.successfulVerifications / stats.totalVerifications
+        : 0;
+
+      const entry: Omit<LeaderboardEntry, 'signature'> = {
+        robotId: stats.robotId,
+        fleetId: stats.fleetId,
+        rank: index + 1,
+        score,
+        trustTier: stats.trustTier,
+        totalVerifications: stats.totalVerifications,
+        successRate,
+        zonesExplored: stats.zonesExplored,
+        badgeCount: stats.badgeCount,
+        streakDays: stats.streakDays,
+        maxZoneMastery: stats.maxZoneMastery,
+        spoofingIncidents: stats.spoofingIncidents,
+        timestamp: now,
+      };
+      return { ...entry, signature: signEntry(entry, this.secret) };
+    });
+  }
+
+  /**
+   * Get fleet summary
+   */
+  getFleetSummary(fleetId: string): FleetSummary {
+    if (!fleetId) throw new Error('fleetId is required');
+
+    const fleetRobots: RobotStats[] = [];
+    for (const stats of this.robotStats.values()) {
+      if (stats.fleetId === fleetId) fleetRobots.push(stats);
+    }
+
+    if (fleetRobots.length === 0) {
+      return {
+        fleetId,
+        robotCount: 0,
+        averageTrustScore: 0,
+        totalDeliveries: 0,
+        averageSuccessRate: 0,
+        totalZonesExplored: 0,
+        topRobotId: null,
+      };
+    }
+
+    const totalPoints = fleetRobots.reduce((s, r) => s + r.points, 0);
+    const totalVerifications = fleetRobots.reduce((s, r) => s + r.totalVerifications, 0);
+    const totalSuccesses = fleetRobots.reduce((s, r) => s + r.successfulVerifications, 0);
+    const allZones = new Set<number>();
+    fleetRobots.forEach(r => { for (let i = 0; i < r.zonesExplored; i++) allZones.add(i); });
+
+    // Find top robot by composite score
+    let topRobot = fleetRobots[0]!;
+    let topScore = computeCompositeScore(topRobot);
+    for (const robot of fleetRobots) {
+      const score = computeCompositeScore(robot);
+      if (score > topScore) {
+        topRobot = robot;
+        topScore = score;
+      }
+    }
+
+    return {
+      fleetId,
+      robotCount: fleetRobots.length,
+      averageTrustScore: totalPoints / fleetRobots.length,
+      totalDeliveries: totalSuccesses,
+      averageSuccessRate: totalVerifications > 0 ? totalSuccesses / totalVerifications : 0,
+      totalZonesExplored: fleetRobots.reduce((s, r) => s + r.zonesExplored, 0),
+      topRobotId: topRobot.robotId,
+    };
+  }
+
+  /**
+   * Get rank of a specific robot
+   */
+  getRobotRank(robotId: string, metric: LeaderboardMetric = LeaderboardMetric.COMPOSITE): number | null {
+    const stats = this.robotStats.get(robotId);
+    if (!stats) return null;
+
+    const leaderboard = this.getFleetLeaderboard(stats.fleetId, metric, 1000);
+    const entry = leaderboard.find(e => e.robotId === robotId);
+    return entry?.rank ?? null;
+  }
+
+  get totalRobots(): number {
+    return this.robotStats.size;
+  }
+}

package/src/gamification/index.ts

@@ -0,0 +1,44 @@
+export {
+  TrustTier,
+  TrustTierSystem,
+  verifyTierChange,
+  TIER_CONFIGS,
+  type TierConfig,
+  type TierChangeEvent,
+  type RobotTrustProfile,
+} from './trust-tiers.js';
+
+export {
+  BadgeCategory,
+  BadgeRarity,
+  BadgeSystem,
+  verifyBadgeAward,
+  BADGE_CATALOG,
+  type BadgeDefinition,
+  type BadgeCriteria,
+  type EarnedBadge,
+  type RobotMetrics,
+} from './badges.js';
+
+export {
+  StreakSystem,
+  type StreakRecord,
+  type StreakConfig,
+} from './streaks.js';
+
+export {
+  ZoneMasterySystem,
+  type Zone,
+  type ZoneMasteryRecord,
+  type ZoneMasteryScore,
+} from './zone-mastery.js';
+
+export {
+  FleetLeaderboard,
+  LeaderboardPeriod,
+  LeaderboardMetric,
+  verifyLeaderboardEntry,
+  type LeaderboardEntry,
+  type RobotStats,
+  type FleetSummary,
+} from './fleet-leaderboard.js';

package/src/gamification/streaks.ts

@@ -0,0 +1,243 @@
+/**
+ * Streak Multiplier System — Reward consistent daily operation
+ *
+ * Maps WeMeetWeMet's streak system:
+ *   Consecutive verified days → multiplier bonus → trust acceleration
+ *   Streak freeze available at a point cost (max 2/month)
+ *   Break = reset to 0, trust penalty applied
+ */
+
+import { hmacSign } from '../utils/crypto.js';
+
+export interface StreakRecord {
+  readonly robotId: string;
+  readonly currentStreak: number;        // consecutive days
+  readonly longestStreak: number;
+  readonly lastActivityDate: string;     // YYYY-MM-DD (UTC)
+  readonly freezesUsedThisMonth: number;
+  readonly freezeMonth: string;          // YYYY-MM for freeze tracking
+  readonly totalPointsFromStreaks: number;
+  readonly signature: string;            // HMAC of current state
+}
+
+export interface StreakConfig {
+  readonly maxMultiplier: number;        // cap (default 2.0)
+  readonly multiplierStep: number;       // per day (default 0.1)
+  readonly baseMultiplier: number;       // starting (default 1.0)
+  readonly maxFreezesPerMonth: number;   // default 2
+  readonly freezeCostPoints: number;     // default 500
+  readonly breakPenaltyPercent: number;  // % of points lost on break (default 5)
+}
+
+const DEFAULT_CONFIG: StreakConfig = {
+  maxMultiplier: 2.0,
+  multiplierStep: 0.1,
+  baseMultiplier: 1.0,
+  maxFreezesPerMonth: 2,
+  freezeCostPoints: 500,
+  breakPenaltyPercent: 5,
+};
+
+function getUTCDateString(timestamp?: number): string {
+  const d = timestamp ? new Date(timestamp) : new Date();
+  return d.toISOString().split('T')[0]!;
+}
+
+function getUTCMonthString(timestamp?: number): string {
+  const d = timestamp ? new Date(timestamp) : new Date();
+  return d.toISOString().slice(0, 7); // YYYY-MM
+}
+
+function daysBetween(dateA: string, dateB: string): number {
+  const a = new Date(dateA + 'T00:00:00Z').getTime();
+  const b = new Date(dateB + 'T00:00:00Z').getTime();
+  return Math.abs(Math.round((b - a) / (24 * 60 * 60 * 1000)));
+}
+
+function signStreak(record: Omit<StreakRecord, 'signature'>, secret: string): string {
+  const payload = `streak:${record.robotId}:${record.currentStreak}:${record.longestStreak}:${record.lastActivityDate}:${record.totalPointsFromStreaks}`;
+  return hmacSign(Buffer.from(payload), secret);
+}
+
+export class StreakSystem {
+  private readonly records = new Map<string, StreakRecord>();
+  private readonly secret: string;
+  private readonly config: StreakConfig;
+
+  constructor(secret: string, config?: Partial<StreakConfig>) {
+    if (!secret || secret.length < 32) {
+      throw new Error('StreakSystem requires a secret of at least 32 chars');
+    }
+    this.secret = secret;
+    this.config = { ...DEFAULT_CONFIG, ...config };
+  }
+
+  /**
+   * Register a robot for streak tracking
+   */
+  register(robotId: string): StreakRecord {
+    if (!robotId) throw new Error('robotId is required');
+    if (this.records.has(robotId)) throw new Error(`Robot ${robotId} already registered`);
+
+    const record: Omit<StreakRecord, 'signature'> = {
+      robotId,
+      currentStreak: 0,
+      longestStreak: 0,
+      lastActivityDate: '',
+      freezesUsedThisMonth: 0,
+      freezeMonth: getUTCMonthString(),
+      totalPointsFromStreaks: 0,
+    };
+    const signed: StreakRecord = { ...record, signature: signStreak(record, this.secret) };
+    this.records.set(robotId, signed);
+    return signed;
+  }
+
+  /**
+   * Record daily activity — extends or starts streak
+   * Returns: { streakDays, multiplier, bonusPoints }
+   */
+  recordActivity(
+    robotId: string,
+    basePoints: number,
+    now?: number,
+  ): { streakDays: number; multiplier: number; bonusPoints: number; totalPoints: number } {
+    const record = this.records.get(robotId);
+    if (!record) throw new Error(`Robot ${robotId} not registered`);
+    if (basePoints < 0) throw new Error('basePoints must be non-negative');
+
+    const today = getUTCDateString(now);
+    const currentMonth = getUTCMonthString(now);
+
+    // Reset freeze counter if new month
+    let freezesUsed = record.freezesUsedThisMonth;
+    let freezeMonth = record.freezeMonth;
+    if (currentMonth !== record.freezeMonth) {
+      freezesUsed = 0;
+      freezeMonth = currentMonth;
+    }
+
+    let newStreak: number;
+
+    if (record.lastActivityDate === '') {
+      // First activity ever
+      newStreak = 1;
+    } else if (record.lastActivityDate === today) {
+      // Already recorded today — no streak change, just return current
+      newStreak = record.currentStreak;
+    } else {
+      const gap = daysBetween(record.lastActivityDate, today);
+      if (gap === 1) {
+        // Consecutive day — extend streak
+        newStreak = record.currentStreak + 1;
+      } else if (gap === 0) {
+        // Same day
+        newStreak = record.currentStreak;
+      } else {
+        // Gap detected — streak broken
+        newStreak = 1; // restart
+      }
+    }
+
+    const multiplier = this.calculateMultiplier(newStreak);
+    const bonusPoints = Math.round(basePoints * (multiplier - 1));
+    const totalPoints = basePoints + bonusPoints;
+
+    const updated: Omit<StreakRecord, 'signature'> = {
+      robotId,
+      currentStreak: newStreak,
+      longestStreak: Math.max(record.longestStreak, newStreak),
+      lastActivityDate: today,
+      freezesUsedThisMonth: freezesUsed,
+      freezeMonth,
+      totalPointsFromStreaks: record.totalPointsFromStreaks + bonusPoints,
+    };
+    this.records.set(robotId, { ...updated, signature: signStreak(updated, this.secret) });
+
+    return { streakDays: newStreak, multiplier, bonusPoints, totalPoints };
+  }
+
+  /**
+   * Use a streak freeze to preserve streak during a missed day
+   * Returns true if freeze applied, false if not available
+   */
+  useFreeze(robotId: string, currentPoints: number, now?: number): { applied: boolean; pointsDeducted: number } {
+    const record = this.records.get(robotId);
+    if (!record) throw new Error(`Robot ${robotId} not registered`);
+
+    const currentMonth = getUTCMonthString(now);
+    let freezesUsed = record.freezesUsedThisMonth;
+    let freezeMonth = record.freezeMonth;
+
+    // Reset if new month
+    if (currentMonth !== record.freezeMonth) {
+      freezesUsed = 0;
+      freezeMonth = currentMonth;
+    }
+
+    // Check if freeze is available
+    if (freezesUsed >= this.config.maxFreezesPerMonth) {
+      return { applied: false, pointsDeducted: 0 };
+    }
+
+    // Check if robot can afford the freeze
+    if (currentPoints < this.config.freezeCostPoints) {
+      return { applied: false, pointsDeducted: 0 };
+    }
+
+    // Apply freeze — streak is preserved, points deducted
+    const updated: Omit<StreakRecord, 'signature'> = {
+      ...record,
+      freezesUsedThisMonth: freezesUsed + 1,
+      freezeMonth,
+    };
+    this.records.set(robotId, { ...updated, signature: signStreak(updated, this.secret) });
+
+    return { applied: true, pointsDeducted: this.config.freezeCostPoints };
+  }
+
+  /**
+   * Force break a streak (called on verification failure or spoofing)
+   */
+  breakStreak(robotId: string): { penaltyPercent: number } {
+    const record = this.records.get(robotId);
+    if (!record) throw new Error(`Robot ${robotId} not registered`);
+
+    const updated: Omit<StreakRecord, 'signature'> = {
+      ...record,
+      currentStreak: 0,
+    };
+    this.records.set(robotId, { ...updated, signature: signStreak(updated, this.secret) });
+
+    return { penaltyPercent: this.config.breakPenaltyPercent };
+  }
+
+  /**
+   * Calculate multiplier for a given streak length
+   */
+  calculateMultiplier(streakDays: number): number {
+    const raw = this.config.baseMultiplier + (streakDays * this.config.multiplierStep);
+    return Math.min(raw, this.config.maxMultiplier);
+  }
+
+  /**
+   * Get current streak record
+   */
+  getRecord(robotId: string): StreakRecord | undefined {
+    return this.records.get(robotId);
+  }
+
+  /**
+   * Verify integrity of a streak record
+   */
+  verifyRecord(robotId: string): boolean {
+    const record = this.records.get(robotId);
+    if (!record) return false;
+    const { signature, ...rest } = record;
+    return signStreak(rest, this.secret) === signature;
+  }
+
+  get robotCount(): number {
+    return this.records.size;
+  }
+}