feat(control-plane): expose routing policy telemetry

Author: Simultech369

DESIGN.md

@@ -1777,3 +1777,15 @@ Rationale:
 - Routing policy was already tested as a control-plane module; this promotes it into the actual model-call path without granting any new promotion authority.
 - Operator views should reflect the route actually attempted, not reconstruct model choice from environment defaults after the fact.
 - Capability-first routing keeps frontend labels, backend execution, and prompt language aligned: use the best policy-permitted model available on this surface, then record what was actually selected.
+
+### D-0057: Operator-Visible Routing Policy Telemetry
+
+Decision:
+- Project routing-policy sub-receipts through router receipts and `/api/operator/receipts-telemetry`.
+- Summarize policy status and selected tier from persisted receipt facts, not from current environment defaults.
+- Keep the projection bounded to route IDs, model IDs, selected tier, attempt status, provider invocation, and receipt hashes.
+
+Rationale:
+- The operator cockpit needs to show whether a response was routed, blocked, downgraded, or served by a provider without requiring code inspection.
+- Persisted receipts may be older than current configuration, so telemetry must describe what happened at the time of execution rather than what the current model router would choose now.
+- This remains observability only. It does not prove output quality, provider availability beyond the attempted call, or Council promotion authority.

NEXT.md

@@ -30,6 +30,8 @@ These are future focuses for public collaborators, not current completion claims
 
 ## Completed
 
+- W-0132: Exposed routing-policy sub-receipts in operator telemetry (`agent_server.mjs`, `scripts/operator_telemetry_routes_test.mjs`, `DESIGN.md` [D-0057]). Router receipts now carry a sanitized `routing_policy` projection when dispatch supplies one, and `/api/operator/receipts-telemetry` summarizes routing-policy status and selected tier from receipt facts rather than reconstructing model choice from current environment defaults. This is cockpit observability only, not provider-quality proof or Council promotion authority. (Verification: `npm run test:operator-telemetry`; `npm run test:router`; `npm run check:council`)
+
 - W-0131: Routed live chat and utility provider calls through the capability-first routing policy (`lib/dispatch.mjs`, `lib/routing_policy.mjs`, `lib/gemini_client.mjs`, `scripts/dynamic_router_test.mjs`, `scripts/routing_policy_test.mjs`, `DESIGN.md` [D-0056]). Dispatch now plans Gemini/OpenAI-compatible/Ollama-style calls with surface-bound route evidence before invocation, emits routing-policy metadata in execution receipts, preserves redirect and isolation block reasons, and sends Gemini max-output limits as actual generation controls. This is live dispatch admission and observability, not Council promotion authority. (Verification: `npm run test:routing-policy`; `npm run test:router`; `npm run check:council`)
 
 - W-0126: Replaced the Python/Z3 bridge with a deterministic policy scorer. Removed the synchronous Python subprocess and Z3 SMT solver from memory conflict resolution. Implemented a pure JavaScript deterministic scorer based on confidence + 0.02 * reinforcement with a strict 0.05 dominance margin. Hard governance invariants are enforced as hard predicates before scoring. Re-anchored our roadmap around Anthropic's Building Effective Agents doctrine. (Verification: npm run check:council)

agent_server.mjs

@@ -437,6 +437,36 @@ function normalizeFreeText(value, maxChars = 20_000) {
   return String(value ?? "").trim().slice(0, Math.max(1, Number(maxChars) || 20_000));
 }
 
+function summarizeRoutingPolicyMetadata(policy) {
+  if (!policy || typeof policy !== "object" || Array.isArray(policy)) return null;
+  const attempts = Array.isArray(policy.attempts) ? policy.attempts.slice(0, 4).map((attempt) => ({
+    route_id: normalizeFreeText(attempt?.route_id || "", 160),
+    model_id: normalizeFreeText(attempt?.model_id || "", 160),
+    status: normalizeIdentifier(attempt?.status || "unknown", "unknown"),
+    error: attempt?.error ? normalizeIdentifier(attempt.error, "unknown_error") : null,
+    sent_model: normalizeFreeText(attempt?.sent_model || "", 160) || null,
+    reported_model: normalizeFreeText(attempt?.reported_model || "", 160) || null,
+    usage_known: attempt?.usage_known === true,
+    status_code: Number(attempt?.status_code) > 0 ? Number(attempt.status_code) : null,
+  })) : [];
+
+  return {
+    status: normalizeIdentifier(policy.status || "unknown", "unknown"),
+    task_class: normalizeIdentifier(policy.task_class || "unknown", "unknown"),
+    surface_id: normalizeIdentifier(policy.surface_id || "unknown", "unknown"),
+    requested_model: normalizeFreeText(policy.requested_model || "", 160) || null,
+    selected_tier: normalizeIdentifier(policy.selected_tier || "unknown", "unknown").toUpperCase(),
+    selected_model_or_route: normalizeFreeText(policy.selected_model_or_route || "", 160) || null,
+    provider_invoked: policy.provider_invoked === true,
+    downgrade_reason: policy.downgrade_reason ? normalizeIdentifier(policy.downgrade_reason, "unknown") : null,
+    fail_closed_reason: policy.fail_closed_reason ? normalizeIdentifier(policy.fail_closed_reason, "unknown") : null,
+    routing_receipt_sha256: /^[a-f0-9]{64}$/i.test(String(policy.routing_receipt_sha256 || ""))
+      ? String(policy.routing_receipt_sha256).toLowerCase()
+      : null,
+    attempts,
+  };
+}
+
 function countJsonlRows(filePath) {
   try {
     const raw = fs.readFileSync(filePath, "utf8").trim();
@@ -1020,6 +1050,7 @@ export async function createRuntime(opts = {}) {
       }
 
       function summarizeReceipt(receipt = {}) {
+        const routingPolicy = summarizeRoutingPolicyMetadata(receipt.routing_policy);
         return {
           schema_version: receipt.schema_version || "",
           task_id: receipt.task_id || "",
@@ -1031,6 +1062,7 @@ export async function createRuntime(opts = {}) {
           latency_ms: Number.isFinite(Number(receipt.latency_ms)) ? Math.max(0, Math.round(Number(receipt.latency_ms))) : 0,
           provider_health: receipt.provider_health || "unknown",
           persisted: Boolean(receipt.persisted),
+          routing_policy: routingPolicy,
         };
       }
 
@@ -1098,6 +1130,8 @@ export async function createRuntime(opts = {}) {
       const trustZonesSummary = {};
       const costBandsSummary = {};
       const latencyBandsSummary = {};
+      const routingPolicyStatuses = {};
+      const selectedTiersSummary = {};
       let totalLatencyMs = 0;
       let latencyCount = 0;
 
@@ -1110,6 +1144,12 @@ export async function createRuntime(opts = {}) {
         costBandsSummary[costBand] = (costBandsSummary[costBand] || 0) + 1;
         const band = latencyBand(r.latency_ms);
         latencyBandsSummary[band] = (latencyBandsSummary[band] || 0) + 1;
+        if (r.routing_policy) {
+          const policyStatus = r.routing_policy.status || "unknown";
+          routingPolicyStatuses[policyStatus] = (routingPolicyStatuses[policyStatus] || 0) + 1;
+          const selectedTier = r.routing_policy.selected_tier || "UNKNOWN";
+          selectedTiersSummary[selectedTier] = (selectedTiersSummary[selectedTier] || 0) + 1;
+        }
         if (typeof r.latency_ms === "number" && r.latency_ms > 0) {
           totalLatencyMs += r.latency_ms;
           latencyCount++;
@@ -1125,6 +1165,8 @@ export async function createRuntime(opts = {}) {
           trust_zones: trustZonesSummary,
           cost_bands: costBandsSummary,
           latency_bands: latencyBandsSummary,
+          routing_policy_statuses: routingPolicyStatuses,
+          selected_tiers: selectedTiersSummary,
           avg_latency_ms: latencyCount > 0 ? Math.round(totalLatencyMs / latencyCount) : 0,
         },
         pareto_frontier: paretoFrontier,
@@ -1409,6 +1451,7 @@ export async function createRuntime(opts = {}) {
       path: "none",
       blocked_reason: noExecutionReason
     };
+    const routingPolicy = summarizeRoutingPolicyMetadata(executionMetadata?.routing_policy);
 
     const receipt = {
       schema_version: "dizzy.router_receipt.v1",
@@ -1425,6 +1468,7 @@ export async function createRuntime(opts = {}) {
       provider_health: typeof executionMetadata?.provider_health === "string" ? executionMetadata.provider_health : (isNoneModel ? "unconfigured" : "healthy"),
       reason: executionMetadata?.reason || (isNoneModel ? `no_model_execution:${noExecutionReason}` : "default_triage_routing_to_chat"),
       fallback,
+      routing_policy: routingPolicy,
       trust_zone: capabilities.trust_zone || "paid_public",
       durable_memory_allowed: capabilities.durable_memory_allowed ?? false,
       voice_consent: false,

scripts/operator_telemetry_routes_test.mjs

@@ -1,4 +1,7 @@
 import assert from "node:assert/strict";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
 import { startServer } from "../agent_server.mjs";
 import { TENSION_MAP_SCHEMA } from "../lib/tension_map_engine.mjs";
 import { JOB_BOARD_INGRESS_SCHEMA } from "../lib/job_board_ingress.mjs";
@@ -15,6 +18,45 @@ async function getJson(url, token = TEST_AUTH_TOKEN) {
   return { status: res.status, data };
 }
 
+const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), "dizzy-operator-telemetry-"));
+const receiptPath = path.join(tempRoot, "router_receipts.jsonl");
+const oldReceiptPath = process.env.DIZZY_ROUTER_RECEIPT_PATH;
+process.env.DIZZY_ROUTER_RECEIPT_PATH = receiptPath;
+
+const routingReceiptHash = "a".repeat(64);
+fs.writeFileSync(receiptPath, JSON.stringify({
+  schema_version: "dizzy.router_receipt.v1",
+  task_id: "routing-telemetry-fixture",
+  timestamp: "2026-09-13T19:50:00.000Z",
+  task_class: "route_classify",
+  chosen_model: "openai_compat:gemma3:4b",
+  trust_zone: "paid_public",
+  estimated_cost_band: "low",
+  data_boundary: "local_machine",
+  model_origin_risk: "low",
+  latency_ms: 42,
+  provider_health: "healthy",
+  persisted: true,
+  routing_policy: {
+    status: "SUCCEEDED",
+    task_class: "chat",
+    surface_id: "dispatch",
+    requested_model: "gemma3:4b",
+    selected_tier: "T2",
+    selected_model_or_route: "openai_compat:gemma3:4b",
+    provider_invoked: true,
+    routing_receipt_sha256: routingReceiptHash,
+    attempts: [{
+      route_id: "openai_compat:gemma3:4b",
+      model_id: "gemma3:4b",
+      status: "SUCCEEDED",
+      sent_model: "gemma3:4b",
+      reported_model: "gemma3:4b",
+      usage_known: false,
+    }],
+  },
+}) + "\n", "utf8");
+
 const runtime = await startServer({
   port: 0,
   bindHost: "127.0.0.1",
@@ -109,7 +151,34 @@ try {
     console.log("  [PASS] Test 5: unconfigured council bridge status fails closed");
   }
 
+  // Test 6: receipts telemetry exposes capability-first routing facts without relying on env reconstruction
+  {
+    const { status, data } = await getJson(`${baseUrl}/api/operator/receipts-telemetry`);
+    assert.equal(status, 200);
+    assert.equal(data.ok, true);
+    assert.equal(data.receipt_count, 1);
+    assert.equal(data.summary.routing_policy_statuses.succeeded, 1);
+    assert.equal(data.summary.selected_tiers.T2, 1);
+    const receipt = data.recent_receipts[0];
+    assert.equal(receipt.task_id, "routing-telemetry-fixture");
+    assert.equal(receipt.routing_policy.status, "succeeded");
+    assert.equal(receipt.routing_policy.task_class, "chat");
+    assert.equal(receipt.routing_policy.surface_id, "dispatch");
+    assert.equal(receipt.routing_policy.selected_tier, "T2");
+    assert.equal(receipt.routing_policy.selected_model_or_route, "openai_compat:gemma3:4b");
+    assert.equal(receipt.routing_policy.provider_invoked, true);
+    assert.equal(receipt.routing_policy.routing_receipt_sha256, routingReceiptHash);
+    assert.equal(receipt.routing_policy.attempts[0].sent_model, "gemma3:4b");
+    console.log("  [PASS] Test 6: receipts telemetry exposes routing policy facts");
+  }
+
   console.log("\n[test:operator-telemetry-routes] ALL TESTS PASSED CLEANLY.\n");
 } finally {
   await runtime.stop?.();
+  if (oldReceiptPath === undefined) {
+    delete process.env.DIZZY_ROUTER_RECEIPT_PATH;
+  } else {
+    process.env.DIZZY_ROUTER_RECEIPT_PATH = oldReceiptPath;
+  }
+  fs.rmSync(tempRoot, { recursive: true, force: true });
 }