Skip to content

Port /api/shadow-read-drift + /api/entropy into core observability router #29

@stackbilt-admin

Description

@stackbilt-admin

Background

aegis-daemon ships a Phase 2 shadow-read drift gauge (aegis#564) that writes rows into shadow_read_drift as readers (router / dashboard / decision-docs / overworld / mcp) exercise getProcedureWithDerivedStats / getAllProceduresWithDerivedStats. The diagnostic endpoint GET /api/shadow-read-drift is how the Phase 3 readiness gate is measured (p95 drift + per-pair readiness). An adjacent endpoint GET /api/entropy also lives only on the daemon side.

During v2.1.4 deploy we hit the project_daemon_kernel_shadow pattern: the daemon's web/src/routes/observability.ts is a superset of core's but was never imported by the daemon's src/index.ts, so both endpoints 404'd. v2.1.5 thin-mounted the daemon router via createAegisApp extension routes (relying on core winning first-match for colliding paths). That unblocks the rollout but leaves the two endpoints permanently shadow-forked.

Ask

Port the two endpoints into aegis-oss/web/src/routes/observability.ts:

  1. GET /api/shadow-read-drift — p50/p95/p99 absolute drift per reader (nearest-rank — D1 lacks percentile_cont), readiness gauge partitioned by (reader, task_pattern), top-15 drifters. Uses the shadow_read_drift table (migration 0030_shadow_read_drift.sql lives in the daemon; the table needs to exist in any downstream variant that turns the gauge on). Source of truth is currently aegis-daemon/web/src/routes/observability.ts:82-181.

  2. GET /api/entropy — wraps detectEntropy(env) from kernel/scheduled/entropy.js. Source: aegis-daemon/web/src/routes/observability.ts:75-80.

Coordination

  • The Phase 2 shadow-read infrastructure (migration, bulk aggregator, drift-log codepath, scheduled prune) currently lives in the daemon's local kernel/memory/procedural.ts + kernel/scheduled/shadow-read-prune.ts. These may also be shadow forks — if they are, porting just the route alone won't be enough (the table and writer need to live upstream too). Worth one grep pass before deciding scope.
  • After the port ships in a new @stackbilt/aegis-core release and the daemon bumps the dep, remove the daemon-side thin mount (src/index.ts additionalRoutes entry and the observability import).

Context

  • Daemon PR that added the endpoints: Stackbilt-dev/aegis#569
  • Daemon fix that thin-mounted: commit b8573fb (v2.1.5)
  • Project memory: project_daemon_kernel_shadow.md

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions