Skip to main content

​
Sprint 20: The Shadow Logger & Diagnostic Observability

With our core game loop and economic mechanics locked down, Sprint 20 establishes a robust, enterprise-grade telemetry, audit, and diagnostic observability layer. This ensures absolute visibility into our high-velocity, serverless-deployed digital economy without introducing runtime latency.

​
🛠 Context & Required Skills for AI Agents

When working inside this context:
  1. Zero-Trust Administrative Claims: Administrative actions, such as fetching unredacted solution vectors, must never expose client-side Firestore rules bypasses. Rely on secure Express APIs that verify session-based administrative claims.
  2. Non-Blocking Observability: Diagnostic operations must execute asynchronously in the background. Never let telemetry operations delay or block the HTTP boundary handshake.

​
🗺 Sprint 20 Roadmap

​
[x] Phase 0: Database & Schema Provisioning

  • Objective: Set up necessary database schema modifications to support admin flags and verbose log collection.
  • Tasks:
    • Added the is_admin boolean column to the PlayerAccount Postgres model.
    • Programmatically provisioned the VerboseDebugLogs table inside the Google Cloud BigQuery data warehouse.

​
[x] Phase 1: The HTTP Boundary (Shadow Middleware)

  • Objective: Establish global route request and response payload capturing.
  • Tasks:
    • Created global Express middleware shadowLogger to intercept req.body and hook res.json payloads.
    • Calculated exact route execution latencies using process.hrtime() and emitted flat Newline Delimited JSON (NDJSON) with appropriate GCP severities.

​
[x] Phase 2: The Database Boundary (Prisma Hooking)

  • Objective: Globally trace database query execution timings and queries.
  • Tasks:
    • Enforced a central Prisma client configuration with strict connection pool limits (max: 1) suitable for serverless scale.
    • Built a global $extends query hook to audit query timings and emit structured logs to stdout.

​
[x] Phase 3: The BigQuery Debug Sink

  • Objective: Construct an asynchronous, non-blocking telemetry log pipeline.
  • Tasks:
    • Built background-scheduled TelemetryQueue utilizing the BigQuery Storage Write API.
    • Added coordinate clamping breach checks that trigger severity: "WARNING" anomaly logs.
    • Hooked unhandled route exceptions to stream error call-stacks with severity: "ERROR" to BigQuery.

​
[x] Phase 4: Client-Side “God Mode” Overlay

  • Objective: Provide administrative visual tools in the Arena while preserving zero-trust security.
  • Tasks:
    • Refactored bouncer.js session resolution to inject req.isAdmin claims on authenticated request sessions.
    • Implemented secure API endpoint GET /debate/admin-vectors to fetch active News Stub solution coordinate shifts.
    • Developed and conditionally rendered the glassmorphic <AdminDebugPanel /> diagnostics overlay for authenticated administrators.

​
🏁 Retrospective & Conclusion

Sprint 20 successfully delivered absolute system-wide observability to the PCMTG monorepo. Through global HTTP shadow logging and Prisma client query extensions, we capture all boundary actions and database transaction speeds with minimal overhead. Our asynchronous BigQuery telemetry queue guarantees background shipping of diagnostic data, while our glassmorphic God Mode UI gives administrators precise interactive vector diagnostics safely wrapped inside a Zero-Trust claims architecture.