pluribus-context 0.3.33 → 0.3.35

package/examples/context-input-evidence/code-search-retrieval-receipt.ndjson

@@ -0,0 +1,8 @@
+{"trace_id":"02c8df97e575ea76a89acf4fe9194925","span_id":"9568b542931d5d73","name":"code.index.snapshot.used","time":"2026-05-26T14:00:01.000Z","attributes":{"session.id":"session-code-search-demo-001","gen_ai.conversation.id":"conv-code-search-demo-001","agent.name":"claude-code","code_search.index.snapshot_id_hash":"sha256:6a0d5bd7e10e","code_search.codebase.path_hash":"sha256:747ff961f5c565013d2b43aa6393ee4f328ed3d6a82f28fc4ca06b417c47ebfb","code_search.git.commit_hash":"sha256:87fe0690312cb4a86c9f9256ff9e1863118a67b44f286e3510c7816d430caae0","code_search.indexed_file_count_bucket":"over_1k","code_search.indexed_chunk_count_bucket":"over_1k","code_search.embedding.provider_hash":"sha256:15c5b8267d43","code_search.embedding.model_hash":"sha256:dbb48b3aa923","code_search.snapshot.status":"fresh","privacy.raw_codebase_path_recorded":false,"privacy.raw_embedding_config_recorded":false}}
+{"trace_id":"02c8df97e575ea76a89acf4fe9194925","span_id":"9568b542931d5d73","name":"code.search.performed","time":"2026-05-26T14:00:03.000Z","attributes":{"session.id":"session-code-search-demo-001","gen_ai.conversation.id":"conv-code-search-demo-001","code_search.query_hash":"sha256:436d2a7ed0737815a485101149ac0b2f0257573dc4a7d65cc3f5d1495bdb001a","code_search.query_category":"auth_session_debug","code_search.filter_hash":"sha256:823b6b5cedb4858291cc68b8eeaccd69cd4a8e4f54cbe62c6ca99bc590847335","code_search.top_k":8,"code_search.candidate_count_bucket":"over_1k","code_search.index.snapshot_id_hash":"sha256:6a0d5bd7e10e","privacy.raw_query_recorded":false,"privacy.raw_filter_recorded":false,"audit_gap":"proves search request identity and candidate scale, not semantic relevance"}}
+{"trace_id":"02c8df97e575ea76a89acf4fe9194925","span_id":"9568b542931d5d73","name":"code.search.result.returned","time":"2026-05-26T14:00:04.000Z","attributes":{"session.id":"session-code-search-demo-001","gen_ai.conversation.id":"conv-code-search-demo-001","code_search.index.snapshot_id_hash":"sha256:6a0d5bd7e10e","code_search.result.rank":1,"code_search.result.score_bucket":"very_high","code_search.result.chunk_id_hash":"sha256:9b5a0917012a","code_search.result.chunk_text_hash":"sha256:89f80a544ab501d52eb4f3cb9ff1aefe496570db864b06011895db06009142ce","code_search.result.path_hash":"sha256:d730007d6c0f93605282b288e74d7f544c7f6f341a3f3c4a38a82903df69766d","code_search.result.path_extension":"ts","code_search.result.line_range_bucket":"under_100_lines","code_search.result.stale":false,"code_search.result.duplicate_of_hash":"","code_search.result.loaded_into_agent_context":true,"code_search.result.suppressed_before_agent_context":false,"code_search.result.suppression_reason":"","privacy.raw_code_chunk_recorded":false,"privacy.raw_path_recorded":false}}
+{"trace_id":"02c8df97e575ea76a89acf4fe9194925","span_id":"9568b542931d5d73","name":"code.search.result.returned","time":"2026-05-26T14:00:04.000Z","attributes":{"session.id":"session-code-search-demo-001","gen_ai.conversation.id":"conv-code-search-demo-001","code_search.index.snapshot_id_hash":"sha256:6a0d5bd7e10e","code_search.result.rank":2,"code_search.result.score_bucket":"high","code_search.result.chunk_id_hash":"sha256:813c55aef28e","code_search.result.chunk_text_hash":"sha256:d73fdad68b67584cd00466261369d2c8bf41c7518ef39699c3962f6819a840b3","code_search.result.path_hash":"sha256:74915fb212979bb303ee810c9190a0d316ab17f1946975e3d1af57ed3001f058","code_search.result.path_extension":"ts","code_search.result.line_range_bucket":"under_100_lines","code_search.result.stale":false,"code_search.result.duplicate_of_hash":"","code_search.result.loaded_into_agent_context":true,"code_search.result.suppressed_before_agent_context":false,"code_search.result.suppression_reason":"","privacy.raw_code_chunk_recorded":false,"privacy.raw_path_recorded":false}}
+{"trace_id":"02c8df97e575ea76a89acf4fe9194925","span_id":"9568b542931d5d73","name":"code.search.result.returned","time":"2026-05-26T14:00:04.000Z","attributes":{"session.id":"session-code-search-demo-001","gen_ai.conversation.id":"conv-code-search-demo-001","code_search.index.snapshot_id_hash":"sha256:6a0d5bd7e10e","code_search.result.rank":3,"code_search.result.score_bucket":"high","code_search.result.chunk_id_hash":"sha256:0570aa4bf0e9","code_search.result.chunk_text_hash":"sha256:39b430127a752702d78ec3180e183f90732310d13e15bcc1adf44cfba2861152","code_search.result.path_hash":"sha256:504efd04322190f19e8d6268b79713d4f7ce890fe9279e76f69d8f18a1e20eb3","code_search.result.path_extension":"ts","code_search.result.line_range_bucket":"under_100_lines","code_search.result.stale":false,"code_search.result.duplicate_of_hash":"","code_search.result.loaded_into_agent_context":true,"code_search.result.suppressed_before_agent_context":false,"code_search.result.suppression_reason":"","privacy.raw_code_chunk_recorded":false,"privacy.raw_path_recorded":false}}
+{"trace_id":"02c8df97e575ea76a89acf4fe9194925","span_id":"9568b542931d5d73","name":"code.search.result.returned","time":"2026-05-26T14:00:04.000Z","attributes":{"session.id":"session-code-search-demo-001","gen_ai.conversation.id":"conv-code-search-demo-001","code_search.index.snapshot_id_hash":"sha256:6a0d5bd7e10e","code_search.result.rank":4,"code_search.result.score_bucket":"high","code_search.result.chunk_id_hash":"sha256:8f6ad990276d","code_search.result.chunk_text_hash":"sha256:fa92fc454797f886864101bdc4032b930d3243320829e4cab48b4f130f95c6b3","code_search.result.path_hash":"sha256:201aa087ff7e0ae80320fea83e0ab68442f48898f199564286804131f9cb9725","code_search.result.path_extension":"ts","code_search.result.line_range_bucket":"under_100_lines","code_search.result.stale":false,"code_search.result.duplicate_of_hash":"sha256:9b5a0917012a","code_search.result.loaded_into_agent_context":false,"code_search.result.suppressed_before_agent_context":true,"code_search.result.suppression_reason":"duplicate","privacy.raw_code_chunk_recorded":false,"privacy.raw_path_recorded":false}}
+{"trace_id":"02c8df97e575ea76a89acf4fe9194925","span_id":"9568b542931d5d73","name":"code.search.result.returned","time":"2026-05-26T14:00:04.000Z","attributes":{"session.id":"session-code-search-demo-001","gen_ai.conversation.id":"conv-code-search-demo-001","code_search.index.snapshot_id_hash":"sha256:6a0d5bd7e10e","code_search.result.rank":5,"code_search.result.score_bucket":"medium","code_search.result.chunk_id_hash":"sha256:cfc00599f288","code_search.result.chunk_text_hash":"sha256:ce03d90b6be534b863cda68baa527cd8067d2cc2b17909d224badc35aaea09a0","code_search.result.path_hash":"sha256:fec2453a62f266008a8ec7ca36bdaf87ff3da8a6e16a1af58f3e67a06eee3db1","code_search.result.path_extension":"md","code_search.result.line_range_bucket":"under_100_lines","code_search.result.stale":true,"code_search.result.duplicate_of_hash":"","code_search.result.loaded_into_agent_context":false,"code_search.result.suppressed_before_agent_context":true,"code_search.result.suppression_reason":"stale_snapshot_chunk","privacy.raw_code_chunk_recorded":false,"privacy.raw_path_recorded":false}}
+{"trace_id":"02c8df97e575ea76a89acf4fe9194925","span_id":"9568b542931d5d73","name":"context.input.loaded","time":"2026-05-26T14:00:06.000Z","attributes":{"session.id":"session-code-search-demo-001","gen_ai.conversation.id":"conv-code-search-demo-001","context.input.kind":"retrieved_code_chunks","context.input.source":"code_search","context.input.client_transform":"top_k_then_dedupe_then_stale_filter","context.input.loaded_chunk_count":3,"context.input.suppressed_chunk_count":2,"context.input.loaded_chunk_ids_hash":"sha256:65ecc531bcad826933c08dc1be4429a6c02f68f446517f6c16f06c9ba5492a72","context.input.suppressed_chunk_ids_hash":"sha256:f4baf0b7d5a2c8a337242746cc1bb6a0473761b4319c10b46c7332356d695c4e","context.input.prompt_token_bucket":"under_5k","context.input.raw_prompt_hash":"sha256:5d992588057a1ae2b6cb5675315c4804a23f1eb2724527d5036be185e3ce161d","privacy.raw_prompt_recorded":false,"privacy.raw_code_chunks_recorded":false,"privacy.raw_paths_recorded":false,"audit_gap":"proves returned-vs-loaded boundary, not answer correctness or retrieval optimality"}}

package/examples/context-input-evidence/convert-code-search-retrieval-log.mjs

@@ -0,0 +1,280 @@
+#!/usr/bin/env node
+import { createHash } from 'node:crypto';
+import { readFileSync, writeFileSync } from 'node:fs';
+import { dirname, extname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const here = dirname(fileURLToPath(import.meta.url));
+const inputPath = process.argv[2] ? resolve(process.argv[2]) : join(here, 'sample-code-search-retrieval-log.jsonl');
+const receiptPath = process.argv[3] ? resolve(process.argv[3]) : join(here, 'code-search-retrieval-receipt.ndjson');
+const tracePath = process.argv[4] ? resolve(process.argv[4]) : join(here, 'code-search-retrieval-otel-trace.json');
+
+function sha256(value) {
+  return `sha256:${createHash('sha256').update(value ?? '').digest('hex')}`;
+}
+
+function hashRef(value) {
+  return sha256(value ?? '').slice(0, 19);
+}
+
+function readJsonl(path) {
+  return readFileSync(path, 'utf8')
+    .trim()
+    .split('\n')
+    .filter(Boolean)
+    .map((line, index) => {
+      try {
+        return JSON.parse(line);
+      } catch (error) {
+        throw new Error(`Invalid JSONL at ${path}:${index + 1}: ${error.message}`);
+      }
+    });
+}
+
+function unixNano(isoTimestamp) {
+  return `${BigInt(Date.parse(isoTimestamp)) * 1_000_000n}`;
+}
+
+function otelValue(value) {
+  if (typeof value === 'boolean') return { boolValue: value };
+  if (typeof value === 'number' && Number.isInteger(value)) return { intValue: String(value) };
+  if (typeof value === 'number') return { doubleValue: value };
+  if (value == null) return { stringValue: '' };
+  return { stringValue: String(value) };
+}
+
+function attributesToOtel(attributes) {
+  return Object.entries(attributes).map(([key, value]) => ({ key, value: otelValue(value) }));
+}
+
+function countBucket(value) {
+  if (value === 0) return 'zero';
+  if (value <= 5) return 'under_5';
+  if (value <= 25) return 'under_25';
+  if (value <= 100) return 'under_100';
+  if (value <= 1_000) return 'under_1k';
+  return 'over_1k';
+}
+
+function tokenBucket(value) {
+  if (value < 1_000) return 'under_1k';
+  if (value < 5_000) return 'under_5k';
+  if (value < 10_000) return 'under_10k';
+  return 'over_10k';
+}
+
+function scoreBucket(score) {
+  if (score >= 0.9) return 'very_high';
+  if (score >= 0.8) return 'high';
+  if (score >= 0.6) return 'medium';
+  return 'low';
+}
+
+function lineRangeBucket(result) {
+  const lineCount = Math.max(0, Number(result.end_line) - Number(result.start_line) + 1);
+  if (lineCount <= 25) return 'under_25_lines';
+  if (lineCount <= 100) return 'under_100_lines';
+  return 'over_100_lines';
+}
+
+const records = readJsonl(inputPath);
+const session = records.find((record) => record.type === 'session.start');
+const snapshot = records.find((record) => record.type === 'code.index.snapshot.used');
+const search = records.find((record) => record.type === 'code.search.performed');
+const returned = records.find((record) => record.type === 'code.search.results.returned');
+const loaded = records.find((record) => record.type === 'context.input.loaded');
+
+if (!session || !snapshot || !search || !returned || !loaded) {
+  throw new Error(`Expected session.start, code.index.snapshot.used, code.search.performed, code.search.results.returned, and context.input.loaded records in ${inputPath}`);
+}
+
+const results = returned.results ?? [];
+const traceSeed = `${session.session_id}:${session.conversation_id}:code-search-retrieval`;
+const traceId = sha256(traceSeed).replace('sha256:', '').slice(0, 32);
+const spanId = sha256(`${traceSeed}:span`).replace('sha256:', '').slice(0, 16);
+const loadedIds = new Set(loaded.loaded_chunk_ids ?? []);
+const suppressedIds = new Set(loaded.suppressed_chunk_ids ?? []);
+
+const snapshotEvent = {
+  trace_id: traceId,
+  span_id: spanId,
+  name: 'code.index.snapshot.used',
+  time: snapshot.time,
+  attributes: {
+    'session.id': session.session_id,
+    'gen_ai.conversation.id': session.conversation_id,
+    'agent.name': session.agent,
+    'code_search.index.snapshot_id_hash': hashRef(snapshot.index_snapshot_id),
+    'code_search.codebase.path_hash': sha256(snapshot.codebase_path),
+    'code_search.git.commit_hash': sha256(snapshot.git_commit),
+    'code_search.indexed_file_count_bucket': countBucket(snapshot.indexed_file_count),
+    'code_search.indexed_chunk_count_bucket': countBucket(snapshot.indexed_chunk_count),
+    'code_search.embedding.provider_hash': hashRef(snapshot.embedding_provider),
+    'code_search.embedding.model_hash': hashRef(snapshot.embedding_model),
+    'code_search.snapshot.status': snapshot.snapshot_status,
+    'privacy.raw_codebase_path_recorded': false,
+    'privacy.raw_embedding_config_recorded': false
+  }
+};
+
+const searchEvent = {
+  trace_id: traceId,
+  span_id: spanId,
+  name: 'code.search.performed',
+  time: search.time,
+  attributes: {
+    'session.id': session.session_id,
+    'gen_ai.conversation.id': session.conversation_id,
+    'code_search.query_hash': sha256(search.raw_query),
+    'code_search.query_category': search.query_category,
+    'code_search.filter_hash': sha256(search.filter),
+    'code_search.top_k': search.top_k,
+    'code_search.candidate_count_bucket': countBucket(search.candidate_count),
+    'code_search.index.snapshot_id_hash': hashRef(search.index_snapshot_id),
+    'privacy.raw_query_recorded': false,
+    'privacy.raw_filter_recorded': false,
+    'audit_gap': 'proves search request identity and candidate scale, not semantic relevance'
+  }
+};
+
+const resultEvents = results.map((result) => ({
+  trace_id: traceId,
+  span_id: spanId,
+  name: 'code.search.result.returned',
+  time: returned.time,
+  attributes: {
+    'session.id': session.session_id,
+    'gen_ai.conversation.id': session.conversation_id,
+    'code_search.index.snapshot_id_hash': hashRef(returned.index_snapshot_id),
+    'code_search.result.rank': result.rank,
+    'code_search.result.score_bucket': scoreBucket(result.score),
+    'code_search.result.chunk_id_hash': hashRef(result.chunk_id),
+    'code_search.result.chunk_text_hash': sha256(result.raw_chunk_text),
+    'code_search.result.path_hash': sha256(result.path),
+    'code_search.result.path_extension': extname(result.path).slice(1) || 'none',
+    'code_search.result.line_range_bucket': lineRangeBucket(result),
+    'code_search.result.stale': Boolean(result.stale),
+    'code_search.result.duplicate_of_hash': result.duplicate_of ? hashRef(result.duplicate_of) : '',
+    'code_search.result.loaded_into_agent_context': loadedIds.has(result.chunk_id),
+    'code_search.result.suppressed_before_agent_context': suppressedIds.has(result.chunk_id),
+    'code_search.result.suppression_reason': loaded.suppression_reasons?.[result.chunk_id] ?? '',
+    'privacy.raw_code_chunk_recorded': false,
+    'privacy.raw_path_recorded': false
+  }
+}));
+
+const loadedEvent = {
+  trace_id: traceId,
+  span_id: spanId,
+  name: 'context.input.loaded',
+  time: loaded.time,
+  attributes: {
+    'session.id': session.session_id,
+    'gen_ai.conversation.id': session.conversation_id,
+    'context.input.kind': 'retrieved_code_chunks',
+    'context.input.source': 'code_search',
+    'context.input.client_transform': loaded.client_transform,
+    'context.input.loaded_chunk_count': loadedIds.size,
+    'context.input.suppressed_chunk_count': suppressedIds.size,
+    'context.input.loaded_chunk_ids_hash': sha256([...loadedIds].sort().join('\n')),
+    'context.input.suppressed_chunk_ids_hash': sha256([...suppressedIds].sort().join('\n')),
+    'context.input.prompt_token_bucket': tokenBucket(loaded.prompt_token_count),
+    'context.input.raw_prompt_hash': sha256(loaded.raw_prompt_fragment),
+    'privacy.raw_prompt_recorded': false,
+    'privacy.raw_code_chunks_recorded': false,
+    'privacy.raw_paths_recorded': false,
+    'audit_gap': 'proves returned-vs-loaded boundary, not answer correctness or retrieval optimality'
+  }
+};
+
+const events = [snapshotEvent, searchEvent, ...resultEvents, loadedEvent]
+  .sort((left, right) => Date.parse(left.time) - Date.parse(right.time) || left.name.localeCompare(right.name));
+
+writeFileSync(receiptPath, `${events.map((event) => JSON.stringify(event)).join('\n')}\n`);
+
+const trace = {
+  resourceSpans: [
+    {
+      resource: {
+        attributes: attributesToOtel({
+          'service.name': 'pluribus-code-search-retrieval-receipt-demo',
+          'service.version': '0.0.0-fixture',
+          'deployment.environment.name': 'local-fixture'
+        })
+      },
+      scopeSpans: [
+        {
+          scope: {
+            name: 'pluribus.context_input_evidence.code_search_retrieval_demo',
+            version: '0.0.0-fixture'
+          },
+          spans: [
+            {
+              traceId,
+              spanId,
+              parentSpanId: '',
+              name: 'agent.session.code_search_retrieval',
+              kind: 1,
+              startTimeUnixNano: unixNano(snapshot.time),
+              endTimeUnixNano: unixNano(loaded.time),
+              attributes: attributesToOtel({
+                'session.id': session.session_id,
+                'gen_ai.conversation.id': session.conversation_id,
+                'agent.name': session.agent,
+                'workspace.name_hash': hashRef(session.workspace),
+                'gen_ai.request.model': session.model,
+                'code_search.query_category': search.query_category
+              }),
+              events: events.map((event) => ({
+                name: event.name,
+                timeUnixNano: unixNano(event.time),
+                attributes: attributesToOtel(event.attributes)
+              }))
+            }
+          ]
+        }
+      ]
+    }
+  ]
+};
+
+writeFileSync(tracePath, `${JSON.stringify(trace, null, 2)}\n`);
+
+const forbiddenRawStrings = [
+  '/Users/alex/src/acme-payments/private-monorepo',
+  'Acme-Co',
+  'sk_live_private_fixture',
+  'finance-vp@acme.example',
+  'sso.internal.acme.example',
+  'tok_private_fixture',
+  'ACME-7391',
+  '+1-555-0100',
+  'https://acme.example/private/sso',
+  'src/auth/session-renewal.ts',
+  'src/auth/sso/failover.ts',
+  'src/billing/stripe-session.ts',
+  'docs/runbooks/sso-failover.md'
+];
+
+const receiptText = readFileSync(receiptPath, 'utf8');
+const traceText = readFileSync(tracePath, 'utf8');
+const leaked = forbiddenRawStrings.filter((value) => receiptText.includes(value) || traceText.includes(value));
+if (leaked.length > 0) {
+  throw new Error(`Receipt leaked raw private fixture strings: ${leaked.join(', ')}`);
+}
+
+console.log(JSON.stringify({
+  schema: 'pluribus.codeSearchRetrievalReceipt.demo.v0',
+  eventCount: events.length,
+  returnedResultCount: results.length,
+  loadedChunkCount: loadedIds.size,
+  suppressedChunkCount: suppressedIds.size,
+  staleReturnedCount: results.filter((result) => result.stale).length,
+  duplicateReturnedCount: results.filter((result) => result.duplicate_of).length,
+  rawCodeCopiedToReceipt: false,
+  rawPathsCopiedToReceipt: false,
+  rawQueryCopiedToReceipt: false,
+  receiptPath: 'examples/context-input-evidence/code-search-retrieval-receipt.ndjson',
+  tracePath: 'examples/context-input-evidence/code-search-retrieval-otel-trace.json',
+  lesson: 'Code-search tools should attest returned result identities separately from what the agent actually loaded, without exposing raw code or private paths.'
+}, null, 2));

package/examples/context-input-evidence/sample-code-search-retrieval-log.jsonl

@@ -0,0 +1,5 @@
+{"type":"session.start","time":"2026-05-26T14:00:00.000Z","session_id":"session-code-search-demo-001","conversation_id":"conv-code-search-demo-001","agent":"claude-code","workspace":"private-monorepo-fixture","model":"claude-opus-4.6"}
+{"type":"code.index.snapshot.used","time":"2026-05-26T14:00:01.000Z","index_snapshot_id":"snapshot-2026-05-26T13-55Z","codebase_path":"/Users/alex/src/acme-payments/private-monorepo","git_commit":"d34db33fd34db33fd34db33fd34db33fd34db33f","embedding_provider":"zilliz-cloud-openai","embedding_model":"text-embedding-3-large","indexed_file_count":1842,"indexed_chunk_count":12678,"snapshot_status":"fresh"}
+{"type":"code.search.performed","time":"2026-05-26T14:00:03.000Z","raw_query":"why does Acme-Co session renewal fail for enterprise SSO customers after region failover? include Stripe payment token path","query_category":"auth_session_debug","top_k":8,"candidate_count":12678,"filter":"language:typescript path:src/auth","index_snapshot_id":"snapshot-2026-05-26T13-55Z"}
+{"type":"code.search.results.returned","time":"2026-05-26T14:00:04.000Z","index_snapshot_id":"snapshot-2026-05-26T13-55Z","results":[{"rank":1,"score":0.912,"path":"src/auth/session-renewal.ts","start_line":42,"end_line":91,"chunk_id":"chunk-auth-renewal-42-91","raw_chunk_text":"const ACME_INTERNAL_SSO_CLIENT_SECRET = 'sk_live_private_fixture'; const customerEmail = 'finance-vp@acme.example'; renewSessionAfterRegionFailover();","stale":false,"duplicate_of":null},{"rank":2,"score":0.887,"path":"src/auth/sso/failover.ts","start_line":14,"end_line":66,"chunk_id":"chunk-sso-failover-14-66","raw_chunk_text":"handle failover for sso tenant acme-co with payment token tok_private_fixture and internal host sso.internal.acme.example","stale":false,"duplicate_of":null},{"rank":3,"score":0.861,"path":"src/billing/stripe-session.ts","start_line":108,"end_line":143,"chunk_id":"chunk-billing-stripe-108-143","raw_chunk_text":"stripe payment renewal path for customer acme-co. contains ticket ACME-7391 and private webhook payload.","stale":false,"duplicate_of":null},{"rank":4,"score":0.858,"path":"src/auth/session-renewal-copy.ts","start_line":42,"end_line":91,"chunk_id":"chunk-auth-renewal-copy-42-91","raw_chunk_text":"duplicate copy of the private Acme-Co session renewal fixture with sk_live_private_fixture","stale":false,"duplicate_of":"chunk-auth-renewal-42-91"},{"rank":5,"score":0.792,"path":"docs/runbooks/sso-failover.md","start_line":5,"end_line":38,"chunk_id":"chunk-runbook-sso-5-38","raw_chunk_text":"runbook says page oncall at +1-555-0100 and include customer URL https://acme.example/private/sso","stale":true,"duplicate_of":null}]}
+{"type":"context.input.loaded","time":"2026-05-26T14:00:06.000Z","index_snapshot_id":"snapshot-2026-05-26T13-55Z","loaded_chunk_ids":["chunk-auth-renewal-42-91","chunk-sso-failover-14-66","chunk-billing-stripe-108-143"],"suppressed_chunk_ids":["chunk-auth-renewal-copy-42-91","chunk-runbook-sso-5-38"],"suppression_reasons":{"chunk-auth-renewal-copy-42-91":"duplicate","chunk-runbook-sso-5-38":"stale_snapshot_chunk"},"prompt_token_count":2860,"raw_prompt_fragment":"User asked about Acme-Co private SSO failover and sk_live_private_fixture; include webhook payload from https://acme.example/private/sso","client_transform":"top_k_then_dedupe_then_stale_filter"}

package/examples/dynamic-workflow-run-receipts/README.md

@@ -0,0 +1,18 @@
+# Dynamic workflow run receipt example
+
+This example is a copyable privacy-safe receipt for Claude Code-style dynamic workflows, ultracode runs, local LLM gateway orchestration, or any script that spawns several subagents to audit, migrate, research, or verify a codebase.
+
+Use it when the parent session only sees the final report, but reviewers still need to understand:
+
+- which phases ran;
+- how many agents were spawned;
+- which role/model/provider each agent actually used;
+- which context was loaded, skipped, or suppressed;
+- which tools/capabilities were granted and used;
+- how token spend was bucketed;
+- where each agent stopped;
+- which gaps remain before mutation or merge.
+
+The example intentionally uses coarse labels, buckets, and hashes instead of raw prompts, source code, exact paths, transcripts, tool output, secrets, or customer data.
+
+See [`docs/dynamic-workflow-run-receipts.md`](../../docs/dynamic-workflow-run-receipts.md) for the checklist and field rationale.

package/examples/dynamic-workflow-run-receipts/workflow-run-receipt.json

@@ -0,0 +1,112 @@
+{
+  "type": "dynamic.workflow.run_receipt.v1",
+  "workflow": {
+    "workflow_id": "wf_checkout_auth_audit_2026_05_30",
+    "runner": "claude-code-dynamic-workflow",
+    "script_source": "generated-then-reviewed-command",
+    "script_hash": "sha256:example-only",
+    "task_kind": "codebase_auth_audit",
+    "plan_approved_before_run": true,
+    "resumable": true,
+    "max_wall_clock_bucket": "under_15m",
+    "kill_switch_available": true,
+    "started_at": "2026-05-30T15:20:00Z",
+    "completed_at": "2026-05-30T15:31:42Z"
+  },
+  "permissions": {
+    "tool_allowlist_inherited": true,
+    "writes_allowed": false,
+    "network_allowed": false,
+    "external_commands_allowed": ["grep", "test --dry-run"],
+    "permission_profile": "review-only"
+  },
+  "phases": [
+    {
+      "phase_id": "route-inventory",
+      "purpose": "find candidate auth-sensitive routes",
+      "agent_count": 3,
+      "token_spend_bucket": "under_50k",
+      "elapsed_ms_bucket": "under_2m",
+      "result": "completed"
+    },
+    {
+      "phase_id": "adversarial-review",
+      "purpose": "cross-check candidate misses",
+      "agent_count": 2,
+      "token_spend_bucket": "under_25k",
+      "elapsed_ms_bucket": "under_2m",
+      "result": "completed_with_gaps"
+    }
+  ],
+  "agents": [
+    {
+      "agent_id": "agent-route-auditor-1",
+      "phase_id": "route-inventory",
+      "role": "route-auth-auditor",
+      "model": "claude-sonnet",
+      "provider": "anthropic",
+      "context_loaded": ["repo-policy", "auth-boundary-rules", "route-index-summary"],
+      "context_skipped_or_suppressed": [
+        {
+          "source": "customer-fixture-dump",
+          "reason": "contains raw customer data; summary hash only"
+        }
+      ],
+      "tools_granted": ["read", "grep"],
+      "tools_used": ["grep"],
+      "feature_areas_checked": ["checkout routes", "admin routes"],
+      "token_budget_bucket": "under_25k",
+      "token_spend_bucket": "under_10k",
+      "max_iterations": 8,
+      "iterations_used": 3,
+      "heartbeat_seen_at": "2026-05-30T15:25:00Z",
+      "partial_progress_reported": true,
+      "fuse_triggered": false,
+      "stop_reason": "completed_assigned_partition",
+      "confidence": "medium",
+      "known_gaps": ["did not execute integration tests"],
+      "raw_prompt_logged": false,
+      "raw_tool_output_logged": false,
+      "raw_paths_logged": false
+    },
+    {
+      "agent_id": "agent-reviewer-1",
+      "phase_id": "adversarial-review",
+      "role": "adversarial-auth-reviewer",
+      "model": "local-codex-compatible",
+      "provider": "local-llm-gateway",
+      "context_loaded": ["candidate-findings-summary", "public-api-contract-summary"],
+      "context_skipped_or_suppressed": [],
+      "tools_granted": ["read"],
+      "tools_used": ["read"],
+      "feature_areas_checked": ["route findings cross-check"],
+      "token_budget_bucket": "under_10k",
+      "token_spend_bucket": "under_10k",
+      "max_iterations": 5,
+      "iterations_used": 5,
+      "heartbeat_seen_at": "2026-05-30T15:30:00Z",
+      "partial_progress_reported": true,
+      "fuse_triggered": true,
+      "stop_reason": "iteration_budget_reached_before_claim_verified",
+      "confidence": "low",
+      "known_gaps": ["one route requires owner confirmation before merge"],
+      "raw_prompt_logged": false,
+      "raw_tool_output_logged": false,
+      "raw_paths_logged": false
+    }
+  ],
+  "handoff": {
+    "final_result_kind": "workflow_review_receipt",
+    "claims_rejected_or_deferred": 1,
+    "next_safe_action": "ask route owner to confirm checkout callback auth before writing fix",
+    "where_it_stopped": "ambiguous auth boundary before mutation"
+  },
+  "privacy": {
+    "raw_prompts_logged": false,
+    "raw_source_logged": false,
+    "raw_tool_output_logged": false,
+    "transcripts_logged": false,
+    "secrets_logged": false,
+    "customer_data_logged": false
+  }
+}

package/examples/install-plan-receipts/README.md

@@ -0,0 +1,34 @@
+# Install-plan receipt example
+
+This example is for one-command agent setup tools that configure MCP, Skills, instruction files, hooks, or plugins across multiple AI coding tools.
+
+Use it when you want a setup script to prove what it will write before it writes anything.
+
+## Copyable preflight checklist
+
+Before applying installer changes, ask the agent or setup script to emit an `agent.install.plan.v1` receipt with:
+
+- `agents_detected`
+- `agents_selected`
+- `planned_writes[]` with `kind`, `target`, `operation`, and `backup_planned`
+- `external_commands_planned[]`
+- `network_after_install`
+- `writes_started=false`
+- `next_safe_command`
+
+Review the receipt, then run the apply command only if the planned writes match your intent.
+
+## Smoke test
+
+The sample receipt is intentionally static JSON so it can be inspected without running an installer:
+
+```bash
+cat examples/install-plan-receipts/agent-install-plan-receipt.json
+node -e "const r=require('./examples/install-plan-receipts/agent-install-plan-receipt.json'); if (r.writes_started !== false) process.exit(1); console.log(r.receipt_type, r.planned_writes.length)"
+```
+
+Expected output:
+
+```text
+agent.install.plan.v1 3
+```

package/examples/install-plan-receipts/agent-install-plan-receipt.json

@@ -0,0 +1,56 @@
+{
+  "receipt_type": "agent.install.plan.v1",
+  "run_id": "demo-install-2026-05-29T16:00Z",
+  "installer": "example-agent-setup",
+  "mode_requested": "plan",
+  "mode_effective": "plan",
+  "agents_detected": [
+    "claude-code",
+    "cursor",
+    "codex",
+    "openclaw"
+  ],
+  "agents_selected": [
+    "claude-code",
+    "openclaw"
+  ],
+  "planned_writes": [
+    {
+      "kind": "mcp_config",
+      "target": "claude-code project config",
+      "operation": "add_local_mcp_server",
+      "backup_planned": true
+    },
+    {
+      "kind": "instruction_file",
+      "target": "AGENTS.md",
+      "operation": "append_usage_notes",
+      "backup_planned": true
+    },
+    {
+      "kind": "hook",
+      "target": "pre-tool hook config",
+      "operation": "register_receipt_guard",
+      "backup_planned": true
+    }
+  ],
+  "external_commands_planned": [
+    {
+      "phase": "apply",
+      "command_class": "package_manager_install"
+    }
+  ],
+  "network_after_install": "local_mcp_server_only",
+  "writes_started": false,
+  "next_safe_command": "example-agent-setup apply --from-plan install-plan.json",
+  "privacy_exclusions": [
+    "raw_source",
+    "secrets",
+    "env_dump",
+    "raw_prompt",
+    "transcript",
+    "raw_tool_output",
+    "customer_data",
+    "private_absolute_path"
+  ]
+}

package/examples/review-primitive-gate/README.md

@@ -0,0 +1,19 @@
+# Review primitive gate example
+
+This example validates a privacy-safe agent handoff receipt as a reviewer/CI primitive.
+
+Run the passing fixture:
+
+```bash
+node examples/review-primitive-gate/check-review-receipt.mjs \
+  examples/review-primitive-gate/pass-review-receipt.json
+```
+
+Run the failing fixture:
+
+```bash
+node examples/review-primitive-gate/check-review-receipt.mjs \
+  examples/review-primitive-gate/fail-review-receipt.json
+```
+
+The script exits non-zero if the run is partial/unsafe, if a required check failed or was skipped, or if the agent changed scope/access without approval.

package/examples/review-primitive-gate/check-review-receipt.mjs

@@ -0,0 +1,100 @@
+#!/usr/bin/env node
+import { readFileSync } from 'node:fs'
+
+const [file] = process.argv.slice(2)
+
+if (!file) {
+  console.error('Usage: node check-review-receipt.mjs <receipt.json>')
+  process.exit(2)
+}
+
+let receipt
+try {
+  receipt = JSON.parse(readFileSync(file, 'utf8'))
+} catch (error) {
+  console.error(JSON.stringify({ ok: false, file, errors: [`invalid JSON: ${error.message}`] }, null, 2))
+  process.exit(2)
+}
+
+const errors = []
+const warnings = []
+
+if (receipt.type !== 'agent.review_primitive_receipt.v1') {
+  errors.push('type must be agent.review_primitive_receipt.v1')
+}
+
+for (const key of ['assignment_id', 'run_id']) {
+  if (!receipt[key] || typeof receipt[key] !== 'string') {
+    errors.push(`${key} is required`)
+  }
+}
+
+const boundaries = receipt.approved_boundaries || {}
+if (!Array.isArray(boundaries.read) || boundaries.read.length === 0) {
+  errors.push('approved_boundaries.read must name at least one coarse read boundary')
+}
+if (!Array.isArray(boundaries.write)) {
+  errors.push('approved_boundaries.write must be an array, even for read-only runs')
+}
+
+const scopeChanges = receipt.scope_access_changes || []
+if (!Array.isArray(scopeChanges)) {
+  errors.push('scope_access_changes must be an array')
+} else {
+  for (const [index, change] of scopeChanges.entries()) {
+    if (change?.approved !== true) {
+      errors.push(`scope_access_changes[${index}] is not explicitly approved`)
+    }
+  }
+}
+
+const checks = receipt.commands_and_checks || []
+if (!Array.isArray(checks) || checks.length === 0) {
+  errors.push('commands_and_checks must include at least one required check/test')
+} else {
+  for (const [index, check] of checks.entries()) {
+    if (!String(check?.kind || '').startsWith('required_')) continue
+    if (check.status !== 'passed') {
+      errors.push(`commands_and_checks[${index}] required check did not pass: ${check.status || 'missing status'}`)
+    }
+    if (!check.evidence || check.evidence === 'not-run') {
+      errors.push(`commands_and_checks[${index}] required check is missing evidence`)
+    }
+  }
+}
+
+const allowedResumeStates = new Set(['complete', 'partial', 'unsafe-to-resume'])
+if (!allowedResumeStates.has(receipt.resume_state)) {
+  errors.push('resume_state must be complete, partial, or unsafe-to-resume')
+}
+if (receipt.resume_state !== 'complete') {
+  errors.push(`resume_state is ${receipt.resume_state}; reviewer must inspect before merge/continuation`)
+}
+
+const handoff = receipt.handoff || {}
+if (!handoff.next_safe_action || typeof handoff.next_safe_action !== 'string') {
+  errors.push('handoff.next_safe_action is required')
+}
+if (!handoff.evidence_path || typeof handoff.evidence_path !== 'string') {
+  warnings.push('handoff.evidence_path is recommended for review traceability')
+}
+
+const privacy = receipt.privacy || {}
+for (const key of ['raw_prompts_logged', 'raw_tool_output_logged', 'source_code_logged', 'secrets_logged']) {
+  if (privacy[key] !== false) {
+    errors.push(`privacy.${key} must be false for this gate`) 
+  }
+}
+
+const result = {
+  ok: errors.length === 0,
+  file,
+  assignment_id: receipt.assignment_id,
+  run_id: receipt.run_id,
+  resume_state: receipt.resume_state,
+  errors,
+  warnings
+}
+
+console.log(JSON.stringify(result, null, 2))
+process.exit(result.ok ? 0 : 1)