pluribus-context 0.3.40 → 0.3.42

package/examples/claude-md-read-receipts/check-read-receipt.mjs

@@ -0,0 +1,119 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+import path from 'node:path';
+
+const VALID_STATES = new Set(['fresh', 'compacted', 'topic_switched', 'resumed']);
+const REGROUNDING_STATES = new Set(['compacted', 'topic_switched', 'resumed']);
+
+function parseArgs(argv) {
+  const args = {};
+  for (let i = 0; i < argv.length; i += 1) {
+    const key = argv[i];
+    const value = argv[i + 1];
+    if (key === '--receipt') { args.receipt = value; i += 1; continue; }
+    if (key === '--help' || key === '-h') { args.help = true; continue; }
+    throw new Error(`Unknown argument: ${key}`);
+  }
+  return args;
+}
+
+function usage() {
+  return 'Usage: node check-read-receipt.mjs --receipt sample-read-receipt.json\n';
+}
+
+function hasText(value) {
+  return typeof value === 'string' && value.trim().length > 0;
+}
+
+function asArray(value) {
+  return Array.isArray(value) ? value : [];
+}
+
+function validate(receipt) {
+  const errors = [];
+  const warnings = [];
+
+  if (receipt.schema !== 'pluribus.claude_md_read_receipt.v1') {
+    errors.push('schema must be pluribus.claude_md_read_receipt.v1');
+  }
+  if (!VALID_STATES.has(receipt.session_state)) {
+    errors.push(`session_state must be one of: ${[...VALID_STATES].join(', ')}`);
+  }
+  if (!hasText(receipt.current_task)) {
+    errors.push('current_task is required');
+  }
+
+  const reloadedFiles = asArray(receipt.reloaded_files);
+  if (reloadedFiles.length === 0) {
+    errors.push('reloaded_files must name at least one file/source');
+  }
+  for (const [index, file] of reloadedFiles.entries()) {
+    if (!hasText(file.path)) errors.push(`reloaded_files[${index}].path is required`);
+    if (!hasText(file.why)) errors.push(`reloaded_files[${index}].why is required`);
+  }
+
+  const activeConstraints = asArray(receipt.active_constraints).filter(hasText);
+  if (activeConstraints.length < 3) {
+    errors.push('active_constraints must include at least 3 concrete constraints');
+  }
+
+  if (!Array.isArray(receipt.not_loaded_files)) {
+    errors.push('not_loaded_files must be present as an array; use [] only when nothing relevant was skipped');
+  } else {
+    for (const [index, file] of receipt.not_loaded_files.entries()) {
+      if (!hasText(file.path)) errors.push(`not_loaded_files[${index}].path is required`);
+      if (!hasText(file.why)) errors.push(`not_loaded_files[${index}].why is required`);
+    }
+  }
+
+  const routerLoaded = reloadedFiles.some((file) => /(^|\/)CLAUDE\.md$/i.test(file.path || '') || /router|index/i.test(file.role || ''));
+  if (!routerLoaded) warnings.push('no CLAUDE.md/router/index source named in reloaded_files');
+
+  const topicAuthorityLoaded = reloadedFiles.some((file) => /topic|authority|migration|spec|docs?\//i.test(`${file.role || ''} ${file.path || ''}`));
+  if (REGROUNDING_STATES.has(receipt.session_state) && !topicAuthorityLoaded) {
+    errors.push(`${receipt.session_state} receipts must name a topic authority/spec/doc reloaded after the boundary`);
+  }
+
+  if (receipt.safe_to_edit === true && errors.length > 0) {
+    warnings.push('safe_to_edit=true is ignored because the receipt failed validation');
+  }
+  if (typeof receipt.safe_to_edit !== 'boolean') {
+    errors.push('safe_to_edit must be a boolean');
+  }
+
+  const safeToEdit = errors.length === 0 && receipt.safe_to_edit === true;
+  return {
+    schema: 'pluribus.claude_md_read_receipt_check.v1',
+    source_receipt_schema: receipt.schema || null,
+    session_state: receipt.session_state || null,
+    current_task_present: hasText(receipt.current_task),
+    reloaded_files_count: reloadedFiles.length,
+    active_constraints_count: activeConstraints.length,
+    skipped_relevant_files_count: Array.isArray(receipt.not_loaded_files) ? receipt.not_loaded_files.length : null,
+    router_or_index_named: routerLoaded,
+    topic_authority_named: topicAuthorityLoaded,
+    stale_notes_named: asArray(receipt.stale_or_historical_notes).length,
+    errors,
+    warnings,
+    safe_to_edit: safeToEdit
+  };
+}
+
+function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (args.help) { process.stdout.write(usage()); return; }
+  if (!args.receipt) throw new Error(usage().trim());
+
+  const receiptPath = path.resolve(args.receipt);
+  const receipt = JSON.parse(fs.readFileSync(receiptPath, 'utf8'));
+  const result = validate(receipt);
+  process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+  if (!result.safe_to_edit) process.exitCode = 1;
+}
+
+try {
+  main();
+} catch (error) {
+  console.error(error.message);
+  process.exit(1);
+}

package/examples/claude-md-read-receipts/sample-read-receipt.json

@@ -0,0 +1,45 @@
+{
+  "schema": "pluribus.claude_md_read_receipt.v1",
+  "session_state": "topic_switched",
+  "current_task": "Update upload API retry handling without regressing the v2.4.0 migration",
+  "reloaded_files": [
+    {
+      "path": "CLAUDE.md",
+      "role": "router",
+      "why": "Confirms the project uses topic-specific docs and points upload work to docs/upload-api.md"
+    },
+    {
+      "path": "docs/upload-api.md",
+      "role": "topic_authority",
+      "why": "Current source for upload retries, deprecated helpers, and safety constraints"
+    },
+    {
+      "path": "docs/migrations/v2.4.0.md",
+      "role": "migration_note",
+      "why": "Current migration note for uploadFile behavior and legacy helper removal"
+    }
+  ],
+  "active_constraints": [
+    "Preserve max 3 retry attempts with exponential backoff",
+    "Never log raw file contents or customer uploads",
+    "Treat v2.4.0 uploadFile migration notes as current authority",
+    "Do not reintroduce uploadLegacy(path); it is removed after v2.5.0"
+  ],
+  "not_loaded_files": [
+    {
+      "path": "docs/payments.md",
+      "why": "Previous topic only; not authority for upload API edits"
+    },
+    {
+      "path": "notes/old-upload-spike.md",
+      "why": "Historical spike; superseded by docs/upload-api.md"
+    }
+  ],
+  "stale_or_historical_notes": [
+    {
+      "ref": "notes/old-upload-spike.md",
+      "reason": "Mentions uploadLegacy(path), which is no longer current"
+    }
+  ],
+  "safe_to_edit": true
+}

package/examples/claude-md-read-receipts/stale-read-receipt.json

@@ -0,0 +1,18 @@
+{
+  "schema": "pluribus.claude_md_read_receipt.v1",
+  "session_state": "compacted",
+  "current_task": "Continue whatever we were doing before compaction",
+  "reloaded_files": [
+    {
+      "path": "CLAUDE.md",
+      "role": "router",
+      "why": "It is usually loaded at startup"
+    }
+  ],
+  "active_constraints": [
+    "Use the normal project rules"
+  ],
+  "not_loaded_files": [],
+  "stale_or_historical_notes": [],
+  "safe_to_edit": true
+}

package/examples/context-attention-receipts/README.md

@@ -0,0 +1,41 @@
+# Context attention receipts
+
+This example is for the `r/ClaudeCode` / GraphRAG failure mode: a graph, memory, RAG, or MCP retrieval system finds the right context, but the coding agent behaves as if it never saw it.
+
+Pluribus should not replace graph memory, RAG, or MCP search. The useful boundary is smaller: emit a privacy-safe receipt proving whether selected context actually crossed the agent boundary and was treated as required before planning or editing.
+
+## What the receipt proves
+
+`pluribus.context_attention_receipt.v1` records low-cardinality evidence only:
+
+- which retrieval/memory/tool context IDs were required for the task;
+- which surface delivered them (`mcp_tool_response`, `claude_hook`, `CLAUDE.md`, `AGENTS.md`, etc.);
+- whether the agent acknowledged those IDs before plan/edit;
+- whether the final plan cites the IDs it depended on;
+- whether missing context forced a stop instead of a best-effort edit;
+- whether raw documents, prompts, source code, transcripts, tokens, or customer data were omitted.
+
+It intentionally does **not** store the retrieved chunks themselves. Use stable IDs, hashes, coarse labels, and evidence paths instead.
+
+## Smoke test
+
+```bash
+node examples/context-attention-receipts/check-attention-receipt.mjs \
+  examples/context-attention-receipts/attention-receipt-pass.json
+
+node examples/context-attention-receipts/check-attention-receipt.mjs \
+  examples/context-attention-receipts/attention-receipt-fail.json
+```
+
+The first command should pass. The second should fail because the graph/memory result was retrieved but not acknowledged or cited before editing.
+
+## Why this exists
+
+A high-quality retrieval layer is still weak if the next agent turn can ignore it. The receipt makes that failure visible:
+
+- retrieval succeeded;
+- required context was or was not delivered to the agent surface;
+- the agent did or did not acknowledge it before changing files;
+- the wrapper/hook did or did not stop the run when required context was missing.
+
+That is the narrow Pluribus angle: not more memory, not a new graph database, and not another router — evidence that the context boundary was actually crossed.

package/examples/context-attention-receipts/attention-receipt-fail.json

@@ -0,0 +1,49 @@
+{
+  "schema": "pluribus.context_attention_receipt.v1",
+  "receipt_id": "attn_2026_06_09_demo_fail",
+  "task_id": "claude-code-refactor-185",
+  "agent_surface": "claude_code",
+  "retrieval_system": "graph_memory_mcp",
+  "required_context": [
+    {
+      "id": "ctx:architecture:tenant-routing",
+      "source_type": "knowledge_graph",
+      "source_hash": "sha256:7bf3e0c1-redacted",
+      "why_required": "routes tenant-scoped writes through the policy gateway"
+    },
+    {
+      "id": "ctx:decision:readonly-audit-first",
+      "source_type": "decision_log",
+      "source_hash": "sha256:11ab91d4-redacted",
+      "why_required": "requires dry-run/audit before writes"
+    }
+  ],
+  "delivery": {
+    "surface": "mcp_tool_response",
+    "delivered_context_ids": [
+      "ctx:architecture:tenant-routing",
+      "ctx:decision:readonly-audit-first"
+    ],
+    "raw_context_omitted": true,
+    "evidence_path": ".pluribus/receipts/context-attention.ndjson"
+  },
+  "attention": {
+    "acknowledged_before_plan": [
+      "ctx:architecture:tenant-routing"
+    ],
+    "cited_in_plan": [],
+    "missing_context_stop": false
+  },
+  "privacy": {
+    "raw_prompts_omitted": true,
+    "raw_documents_omitted": true,
+    "source_code_omitted": true,
+    "tool_outputs_omitted": true,
+    "tokens_omitted": true,
+    "customer_data_omitted": true
+  },
+  "result": {
+    "status": "unsafe_to_continue",
+    "next_safe_action": "stop and ask the retrieval wrapper to re-deliver required context before editing"
+  }
+}

package/examples/context-attention-receipts/attention-receipt-pass.json

@@ -0,0 +1,53 @@
+{
+  "schema": "pluribus.context_attention_receipt.v1",
+  "receipt_id": "attn_2026_06_09_demo_pass",
+  "task_id": "claude-code-refactor-184",
+  "agent_surface": "claude_code",
+  "retrieval_system": "graph_memory_mcp",
+  "required_context": [
+    {
+      "id": "ctx:architecture:tenant-routing",
+      "source_type": "knowledge_graph",
+      "source_hash": "sha256:7bf3e0c1-redacted",
+      "why_required": "routes tenant-scoped writes through the policy gateway"
+    },
+    {
+      "id": "ctx:decision:readonly-audit-first",
+      "source_type": "decision_log",
+      "source_hash": "sha256:11ab91d4-redacted",
+      "why_required": "requires dry-run/audit before writes"
+    }
+  ],
+  "delivery": {
+    "surface": "mcp_tool_response",
+    "delivered_context_ids": [
+      "ctx:architecture:tenant-routing",
+      "ctx:decision:readonly-audit-first"
+    ],
+    "raw_context_omitted": true,
+    "evidence_path": ".pluribus/receipts/context-attention.ndjson"
+  },
+  "attention": {
+    "acknowledged_before_plan": [
+      "ctx:architecture:tenant-routing",
+      "ctx:decision:readonly-audit-first"
+    ],
+    "cited_in_plan": [
+      "ctx:architecture:tenant-routing",
+      "ctx:decision:readonly-audit-first"
+    ],
+    "missing_context_stop": false
+  },
+  "privacy": {
+    "raw_prompts_omitted": true,
+    "raw_documents_omitted": true,
+    "source_code_omitted": true,
+    "tool_outputs_omitted": true,
+    "tokens_omitted": true,
+    "customer_data_omitted": true
+  },
+  "result": {
+    "status": "safe_to_continue",
+    "next_safe_action": "continue with dry-run refactor plan"
+  }
+}

package/examples/context-attention-receipts/check-attention-receipt.mjs

@@ -0,0 +1,97 @@
+#!/usr/bin/env node
+import { readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+
+const [receiptPathArg] = process.argv.slice(2)
+
+if (!receiptPathArg) {
+  fail(['usage: node check-attention-receipt.mjs <receipt.json>'], 2)
+}
+
+const receiptPath = resolve(process.cwd(), receiptPathArg)
+let receipt
+try {
+  receipt = JSON.parse(readFileSync(receiptPath, 'utf8'))
+} catch (error) {
+  fail([`could not read receipt JSON: ${error.message}`], 2)
+}
+
+const errors = []
+const warnings = []
+
+if (receipt.schema !== 'pluribus.context_attention_receipt.v1') {
+  errors.push('schema must be pluribus.context_attention_receipt.v1')
+}
+
+const requiredIds = ids(receipt.required_context?.map((item) => item.id))
+const deliveredIds = ids(receipt.delivery?.delivered_context_ids)
+const acknowledgedIds = ids(receipt.attention?.acknowledged_before_plan)
+const citedIds = ids(receipt.attention?.cited_in_plan)
+
+if (requiredIds.length === 0) errors.push('required_context must name at least one context id')
+
+for (const id of requiredIds) {
+  if (!deliveredIds.includes(id)) errors.push(`required context not delivered: ${id}`)
+  if (!acknowledgedIds.includes(id)) errors.push(`required context not acknowledged before plan: ${id}`)
+  if (!citedIds.includes(id)) errors.push(`required context not cited in plan: ${id}`)
+}
+
+if (receipt.delivery?.raw_context_omitted !== true) {
+  errors.push('delivery.raw_context_omitted must be true')
+}
+
+const privacy = receipt.privacy || {}
+for (const field of [
+  'raw_prompts_omitted',
+  'raw_documents_omitted',
+  'source_code_omitted',
+  'tool_outputs_omitted',
+  'tokens_omitted',
+  'customer_data_omitted'
+]) {
+  if (privacy[field] !== true) errors.push(`privacy.${field} must be true`)
+}
+
+if (errors.length > 0 && receipt.attention?.missing_context_stop !== true) {
+  errors.push('missing_context_stop must be true when required context attention evidence is incomplete')
+}
+
+if (receipt.result?.status === 'safe_to_continue' && errors.length > 0) {
+  errors.push('result.status cannot be safe_to_continue when required evidence is incomplete')
+}
+
+if (!receipt.delivery?.evidence_path) {
+  warnings.push('delivery.evidence_path is missing; reviewers need a pointer to the audit trail')
+}
+
+const output = {
+  ok: errors.length === 0,
+  receipt_id: receipt.receipt_id || null,
+  task_id: receipt.task_id || null,
+  agent_surface: receipt.agent_surface || null,
+  required_count: requiredIds.length,
+  delivered_count: deliveredIds.length,
+  acknowledged_count: acknowledgedIds.length,
+  cited_count: citedIds.length,
+  status: receipt.result?.status || null,
+  next_safe_action: receipt.result?.next_safe_action || null,
+  errors,
+  warnings
+}
+
+if (output.ok) {
+  console.log(JSON.stringify(output, null, 2))
+  process.exit(0)
+}
+
+console.error(JSON.stringify(output, null, 2))
+process.exit(1)
+
+function ids(value) {
+  return Array.isArray(value) ? value.filter((id) => typeof id === 'string' && id.length > 0) : []
+}
+
+function fail(errors, code) {
+  console.error(JSON.stringify({ ok: false, errors }, null, 2))
+  process.exit(code)
+}

package/examples/context-sufficiency-trace/README.md

@@ -0,0 +1,22 @@
+# Context sufficiency trace
+
+Tiny fixture for the market signal that token-saving context tools need a second metric: did the agent receive the files it later needed?
+
+The example compares a retrieval/context-bundle trace against task ground truth and reports:
+
+- `gold_context_recall`: required files returned before the edit;
+- `missed_required_file_rate`: required files not returned by the bundle;
+- `late_context_rate`: required files first discovered after the edit started;
+- `frontier_cut_misses`: required files that were seen as candidates but cut from the bundle.
+
+Run it:
+
+```bash
+node examples/context-sufficiency-trace/check-context-sufficiency.mjs \
+  examples/context-sufficiency-trace/ground-truth.json \
+  examples/context-sufficiency-trace/context-trace.json
+```
+
+Expected result for the included fixture: fail. The bundle saved tokens, but it missed `src/auth/session.ts`, which was required for the task and only appeared after editing began.
+
+Why this exists: score + token savings can hide a bad context bundle. A sufficiency trace turns the hidden failure into something benchmarkable before a team trusts compression.

package/examples/context-sufficiency-trace/check-context-sufficiency.mjs

@@ -0,0 +1,40 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+
+const [truthPath, tracePath] = process.argv.slice(2);
+if (!truthPath || !tracePath) {
+  console.error('Usage: node check-context-sufficiency.mjs <ground-truth.json> <context-trace.json>');
+  process.exit(2);
+}
+
+const readJson = (path) => JSON.parse(fs.readFileSync(path, 'utf8'));
+const truth = readJson(truthPath);
+const trace = readJson(tracePath);
+
+const required = new Set(truth.required_files || []);
+const returned = new Set((trace.returned_files || []).map((file) => file.path));
+const frontierCut = new Set((trace.frontier_cut || []).map((file) => file.path));
+const late = new Set((trace.late_files || []).map((file) => file.path));
+
+const requiredList = [...required];
+const returnedRequired = requiredList.filter((path) => returned.has(path));
+const missedRequired = requiredList.filter((path) => !returned.has(path));
+const frontierCutMisses = missedRequired.filter((path) => frontierCut.has(path));
+const lateMisses = missedRequired.filter((path) => late.has(path));
+
+const ratio = (count, total) => (total === 0 ? 0 : Number((count / total).toFixed(4)));
+const report = {
+  task_id: truth.task_id,
+  trace_id: trace.trace_id,
+  required_files: requiredList.length,
+  returned_files: returned.size,
+  gold_context_recall: ratio(returnedRequired.length, requiredList.length),
+  missed_required_file_rate: ratio(missedRequired.length, requiredList.length),
+  late_context_rate: ratio(lateMisses.length, requiredList.length),
+  missed_required_files: missedRequired,
+  frontier_cut_misses: frontierCutMisses,
+  verdict: missedRequired.length === 0 ? 'pass' : 'fail'
+};
+
+console.log(JSON.stringify(report, null, 2));
+process.exit(report.verdict === 'pass' ? 0 : 1);

package/examples/context-sufficiency-trace/context-trace-pass.json

@@ -0,0 +1,28 @@
+{
+  "trace_id": "ctxtrace_2026_06_17_demo_pass",
+  "query": "fix stale session redirect after token refresh",
+  "token_budget": 12000,
+  "index_revision": "sha256:demo-index-revision",
+  "returned_files": [
+    {
+      "path": "src/auth/session.ts",
+      "hash": "sha256:demo-session",
+      "tokens": 2200,
+      "reason": "session refresh state owns the redirect freshness condition"
+    },
+    {
+      "path": "src/routes/redirect.ts",
+      "hash": "sha256:demo-redirect",
+      "tokens": 1400,
+      "reason": "direct redirect logic match"
+    },
+    {
+      "path": "test/auth-refresh.test.ts",
+      "hash": "sha256:demo-test",
+      "tokens": 900,
+      "reason": "failing test references token refresh redirect"
+    }
+  ],
+  "frontier_cut": [],
+  "late_files": []
+}

package/examples/context-sufficiency-trace/context-trace.json

@@ -0,0 +1,47 @@
+{
+  "trace_id": "ctxtrace_2026_06_17_demo",
+  "query": "fix stale session redirect after token refresh",
+  "token_budget": 12000,
+  "index_revision": "sha256:demo-index-revision",
+  "returned_files": [
+    {
+      "path": "src/routes/redirect.ts",
+      "hash": "sha256:demo-redirect",
+      "tokens": 1400,
+      "reason": "direct redirect logic match"
+    },
+    {
+      "path": "test/auth-refresh.test.ts",
+      "hash": "sha256:demo-test",
+      "tokens": 900,
+      "reason": "failing test references token refresh redirect"
+    },
+    {
+      "path": "docs/auth-flow.md",
+      "hash": "sha256:demo-doc",
+      "tokens": 1300,
+      "reason": "architecture notes for auth flow"
+    }
+  ],
+  "frontier_cut": [
+    {
+      "path": "src/auth/session.ts",
+      "hash": "sha256:demo-session",
+      "tokens": 2200,
+      "reason": "ranked 4th; cut to preserve budget"
+    },
+    {
+      "path": "src/auth/cookies.ts",
+      "hash": "sha256:demo-cookies",
+      "tokens": 1800,
+      "reason": "ranked 5th; cut to preserve budget"
+    }
+  ],
+  "late_files": [
+    {
+      "path": "src/auth/session.ts",
+      "first_seen_after": "edit_started",
+      "reason": "test failure showed refresh state was stored outside redirect.ts"
+    }
+  ]
+}

package/examples/context-sufficiency-trace/ground-truth.json

@@ -0,0 +1,13 @@
+{
+  "task_id": "tsbench-style-auth-redirect",
+  "task": "Fix the stale session redirect after token refresh.",
+  "required_files": [
+    "src/auth/session.ts",
+    "src/routes/redirect.ts",
+    "test/auth-refresh.test.ts"
+  ],
+  "edit_files": [
+    "src/routes/redirect.ts",
+    "test/auth-refresh.test.ts"
+  ]
+}

package/examples/provider-degradation-canaries/README.md

@@ -0,0 +1,79 @@
+# Provider degradation canary receipt
+
+A tiny gate for agent runs when the model/provider may be silently degraded: slower than normal, timing out, drifting on tool calls, breaking JSON, or producing weaker code edits while the status page still looks green.
+
+Use this before side-effecting agent actions such as patches, PRs, migrations, shell commands, deploys, or external writes. The receipt does **not** log prompts or model outputs. It records transport health, cheap capability canaries, and the decision to continue, fallback, pause writes, or stop.
+
+## Prompt / harness pattern
+
+```text
+Before this agent run writes anything, record a degradation decision:
+- provider/model/region and prompt template hash
+- latency/error summary for the run window
+- capability canaries that match this app: JSON schema, tool choice, patch format, refusal/over-refusal, citation grounding
+- failed canaries and severity
+- fallback chosen, if any
+- write gate: continue, read_only, fallback_model, pause_writes, or stop
+- confidence: provider_degraded, app_bug, network, unknown, or healthy
+```
+
+If tool-choice or patch-format canaries fail, keep read-only analysis alive but pause writes until a fallback or human review confirms the agent can still act safely.
+
+## Run the sample checker
+
+```bash
+cd examples/provider-degradation-canaries
+node check-degradation-receipt.mjs --receipt healthy-decision.json
+```
+
+The bundled healthy receipt passes because transport is stable, app-critical canaries pass, and the write gate is allowed.
+
+A degraded write attempt should fail:
+
+```bash
+node check-degradation-receipt.mjs --receipt unsafe-write-decision.json
+```
+
+## Receipt shape
+
+```json
+{
+  "schema": "pluribus.provider_degradation_decision.v1",
+  "run_id": "agent-run-2026-06-15T20:02Z",
+  "provider": "anthropic",
+  "model": "claude-sonnet-4",
+  "region": "us-east-1",
+  "prompt_template_hash": "sha256:...",
+  "canary_suite_version": "coding-agent-smoke-2026-06-15",
+  "transport": {
+    "window_minutes": 10,
+    "ttft_p95_ms": 1400,
+    "total_latency_p95_ms": 9200,
+    "timeout_rate": 0.01,
+    "error_rate": 0,
+    "retry_count": 1,
+    "status_incident_url": null
+  },
+  "capability_canaries": [
+    { "name": "json_schema", "status": "pass", "severity": "write_blocking" },
+    { "name": "tool_choice", "status": "pass", "severity": "write_blocking" },
+    { "name": "patch_format", "status": "pass", "severity": "write_blocking" }
+  ],
+  "fallback": { "chosen": false, "reason": null },
+  "confidence": "healthy",
+  "write_gate": "continue"
+}
+```
+
+## Why this exists
+
+The market signal from Claude Code / API builders is practical: when an LLM silently degrades, teams lose time deciding whether provider behavior, network health, prompt changes, or their own code caused the failure.
+
+This receipt keeps that decision falsifiable:
+
+- latency alerts and provider status are separated from capability drift;
+- canaries are app-critical, not generic benchmarks;
+- side-effecting actions get stricter gates than read-only analysis;
+- fallback and pause decisions are recorded as evidence, not hidden in transcripts.
+
+Pair this with Pluribus context receipts when runtime inputs are the problem. Use this receipt when the question is whether the model/provider is currently reliable enough to let an agent keep writing.