CRUMB a card from devarno-cloud

Protocol Metrics Aggregation

meridian intermediate 5 min read

ELI5

The metrics endpoint is a six-shelf scoreboard: units, fingerprints, graph, councils, CI, intelligence. Some shelves count real items in the kitchen; some still have honest-zero placards because that part of the kitchen isn’t wired yet.

Technical Deep Dive

src/lib/metrics.ts exports computeProtocolMetrics() and computeMetricsSummary(). Both return Zod-validated payloads from @stratt/schema.

Metric Categories

flowchart TD
    UNITS[loadAllUnits] --> U1[unitMetrics<br/>by_type, by_status, by_domain]
    UNITS --> U2[fingerprintMetrics<br/>verified/tampered/missing<br/>integrity_pct]
    UNITS --> U3[graphMetrics<br/>nodes, edges, top_imported,<br/>connected_components, cyclic]
    COUNCILS[loadAllCouncils] --> U4[councilMetrics<br/>protected_agents,<br/>gate_authority_agents]
    PLACEHOLDER1[CI placeholder] --> U5[ciMetrics<br/>FM-01..FM-09 = 0<br/>pass_rate_pct = 100]
    PLACEHOLDER2[intelligence placeholder] --> U6[intelligenceMetrics<br/>active_signals = 0]
    U1 --> AGG[ProtocolMetricsSchema.parse]
    U2 --> AGG
    U3 --> AGG
    U4 --> AGG
    U5 --> AGG
    U6 --> AGG
    AGG --> SUM[computeMetricsSummary<br/>headline numbers]

Honest Approximations

MetricTruth StatusNote
units.*realfrom bundled YAML via loadAllUnits
fingerprint.*realreads unit.fingerprint_status
graph.edgesrealsum of imports.length
graph.connected_componentsapproxuses Math.max(1, domains.size) — assumes domain co-membership implies connectivity
graph.cyclicweakonly catches direct self-imports (imp === unit.uri)
councils.*realfrom loadAllCouncils
ci.*placeholderalways 11/11/100% until @stratt/graph runCIPipeline is called
intelligence.*placeholderzeros until orchestrator ledger is wired

Schema-Validated Output

The final step is ProtocolMetricsSchema.parse(metrics) — drift in shape (extra key, missing key, wrong type) throws at the seam, not in a downstream chart. MetricsSummarySchema.parse does the same for the headline payload that the dashboard card consumes.

Top Imported

top_imported is the 10 highest-incoming-degree units, sorted descending. It is the cheapest “what does the protocol orbit around?” signal and stays accurate even while the cycle and connectivity heuristics are approximations.

Key Terms

  • fingerprint_status → Per-unit verification status (verified | tampered | missing); set during parseUnit.
  • FM-01 … FM-09 → Failure-mode check identifiers from the @stratt/graph CI pipeline.
  • integrity_pct → verified / (verified + tampered + missing) * 100, rounded to two decimals.

Q&A

Q: Why is cyclic such a weak check? A: A real DFS would need to walk the whole graph and stays out of scope until @stratt/graph exposes a topological sort. The self-import check catches the most common authoring mistake at near-zero cost.

Q: Why does pass_rate_pct report 100% even when no real CI has run? A: The placeholder claims zero violations across all 11 checks. This is a known baseline, not a lie — the dashboard panel for CI explicitly shows the placeholder shape until runCIPipeline() is wired.

Q: Why split computeMetricsSummary from computeProtocolMetrics? A: The headline card in the dashboard only needs five numbers; serving the full payload to render the card wastes bandwidth and forces the consumer to know the full schema.

Examples

A fresh dev environment with 14 units across 3 domains, all fingerprints verified:

{
  "units": { "total": 14, "verified": 14 },
  "graph": { "edges": 22, "cyclic": false },
  "councils": { "total": 3, "agents": 9 },
  "ci": { "pass_rate_pct": 100 },
  "intelligence": { "active_signals": 0 }
}

Once one unit is tampered with, units.verified drops to 13 and integrity_pct falls below 100 — the headline card colour-flips without any other code change.

neighbors on the map