pluribus-context 0.3.35 → 0.3.37

package/examples/ai-pr-review-receipts/README.md

@@ -1,5 +1,55 @@
 # AI PR review receipts example
 
-This example contains a copyable GitHub PR template for agent-generated or agent-modified pull requests.
+This example contains a copyable GitHub PR template and CI gate for agent-generated or agent-modified pull requests.
 
 Use it when review risk depends on blast radius: schema/data contracts, async paths, rollout gates, external side effects, generated/public interfaces, or security-sensitive config.
+
+The point is not to make every AI PR small. It is to make the risky boundaries reviewable enough that CI or a maintainer can decide: merge, route to a human owner, or stop.
+
+## Files
+
+- [`.github/pull_request_template.md`](.github/pull_request_template.md) — human-readable PR body section for blast-radius review.
+- [`.github/workflows/ai-pr-review-receipt.yml`](.github/workflows/ai-pr-review-receipt.yml) — copyable GitHub Actions gate that validates a machine-readable receipt.
+- [`review-primitive-receipt.json`](review-primitive-receipt.json) — passing receipt fixture.
+- [`incomplete-review-primitive-receipt.json`](incomplete-review-primitive-receipt.json) — failing fixture for partial/unsafe evidence.
+
+## 60-second local smoke
+
+From the repository root:
+
+```bash
+node examples/review-primitive-gate/check-review-receipt.mjs \
+  examples/ai-pr-review-receipts/review-primitive-receipt.json
+```
+
+Expected: `ok: true`.
+
+Then run the incomplete fixture:
+
+```bash
+node examples/review-primitive-gate/check-review-receipt.mjs \
+  examples/ai-pr-review-receipts/incomplete-review-primitive-receipt.json
+```
+
+Expected: non-zero exit. The failure is intentional: unapproved scope change, skipped required test, missing evidence, and `partial` resume state should not silently pass a merge gate.
+
+## GitHub Actions usage
+
+1. Copy `.github/workflows/ai-pr-review-receipt.yml` into your repo.
+2. Have your Claude Code / Codex / Cursor / OpenClaw / review bot emit a privacy-safe receipt at `artifacts/review-primitive-receipt.json`.
+3. Keep raw prompts, transcripts, source code, secrets, stack traces, customer data, and raw tool output out of the receipt.
+4. Let the workflow fail if the receipt is partial, unsafe, missing evidence, or outside approved boundaries.
+
+The template and JSON receipt can be used together: the PR body explains the blast radius to humans, while the JSON receipt gives CI a hard decision primitive.
+
+## Why this exists
+
+Large AI PRs are not automatically unsafe, and small PRs are not automatically reviewable. Diff size is a proxy. This receipt makes the underlying question explicit:
+
+- Which assignment did the agent accept?
+- What read/write boundaries were approved?
+- Did scope or access change mid-run, and was it approved?
+- Which required checks actually ran, with evidence?
+- Did the agent refuse unsafe operations?
+- Is the handoff `complete`, `partial`, or `unsafe-to-resume`?
+- What is the next safe action for the reviewer?

package/examples/ai-pr-review-receipts/incomplete-review-primitive-receipt.json

@@ -0,0 +1,43 @@
+{
+  "type": "agent.review_primitive_receipt.v1",
+  "assignment_id": "pr-483-agent-review",
+  "run_id": "run-2026-05-31T23-10Z",
+  "agent": {
+    "tool": "claude-code-github-actions",
+    "role": "pr-reviewer"
+  },
+  "approved_boundaries": {
+    "read": ["src/auth/**", "tests/auth/**"],
+    "write": ["tests/auth/**"],
+    "network": false
+  },
+  "scope_access_changes": [
+    {
+      "change": "write src/auth/session.ts",
+      "reason": "agent attempted to patch production auth code during review",
+      "approved": false,
+      "approved_by": ""
+    }
+  ],
+  "commands_and_checks": [
+    {
+      "name": "npm test -- tests/auth",
+      "kind": "required_test",
+      "status": "skipped",
+      "evidence": "not-run"
+    }
+  ],
+  "refused_operations": [],
+  "handoff": {
+    "changed_files_bucket": "under_10",
+    "evidence_path": "artifacts/pr-483/review-primitive-receipt.json",
+    "next_safe_action": "human must inspect attempted auth write and run required tests before merge"
+  },
+  "resume_state": "partial",
+  "privacy": {
+    "raw_prompts_logged": false,
+    "raw_tool_output_logged": false,
+    "source_code_logged": false,
+    "secrets_logged": false
+  }
+}

package/examples/ai-pr-review-receipts/review-primitive-receipt.json

@@ -0,0 +1,60 @@
+{
+  "type": "agent.review_primitive_receipt.v1",
+  "assignment_id": "pr-482-agent-review",
+  "run_id": "run-2026-05-31T23-00Z",
+  "agent": {
+    "tool": "claude-code-github-actions",
+    "role": "pr-reviewer"
+  },
+  "approved_boundaries": {
+    "read": ["src/billing/**", "tests/billing/**", "docs/rollout/**"],
+    "write": ["tests/billing/**", "docs/review-receipts/**"],
+    "network": false
+  },
+  "scope_access_changes": [
+    {
+      "change": "read docs/rollout/**",
+      "reason": "verify feature-flag and rollback evidence for the PR receipt",
+      "approved": true,
+      "approved_by": "maintainer"
+    }
+  ],
+  "commands_and_checks": [
+    {
+      "name": "npm test -- tests/billing",
+      "kind": "required_test",
+      "status": "passed",
+      "evidence": "https://github.com/example/repo/actions/runs/123#billing-tests"
+    },
+    {
+      "name": "npm run lint",
+      "kind": "required_check",
+      "status": "passed",
+      "evidence": "https://github.com/example/repo/actions/runs/123#lint"
+    },
+    {
+      "name": "migration rollback smoke",
+      "kind": "required_check",
+      "status": "passed",
+      "evidence": "artifacts/pr-482/rollback-smoke.txt"
+    }
+  ],
+  "refused_operations": [
+    {
+      "operation": "write src/billing/charge-customer.ts",
+      "reason": "outside approved write boundary; reviewer requested tests/docs only"
+    }
+  ],
+  "handoff": {
+    "changed_files_bucket": "under_5",
+    "evidence_path": "artifacts/pr-482/review-primitive-receipt.json",
+    "next_safe_action": "review billing test assertions and rollback evidence before merge"
+  },
+  "resume_state": "complete",
+  "privacy": {
+    "raw_prompts_logged": false,
+    "raw_tool_output_logged": false,
+    "source_code_logged": false,
+    "secrets_logged": false
+  }
+}

package/examples/compaction-resume-receipts/README.md

@@ -0,0 +1,12 @@
+# Compaction resume receipt gate
+
+This example validates a privacy-safe receipt for `PostCompact`, `SessionStart(compact)`, or any workflow that resumes an AI coding session after summarization.
+
+Run:
+
+```bash
+node check-resume-receipt.mjs safe-resume-receipt.json
+node check-resume-receipt.mjs unsafe-resume-receipt.json
+```
+
+Use it as a tiny CI/hook check before an agent continues work after compaction. The receipt records hashes, refs, and verdicts — not raw transcripts or raw instruction bodies.

package/examples/compaction-resume-receipts/check-resume-receipt.mjs

@@ -0,0 +1,116 @@
+#!/usr/bin/env node
+import { readFileSync } from 'node:fs'
+
+const [file] = process.argv.slice(2)
+
+if (!file) {
+  console.error('Usage: node check-resume-receipt.mjs <compaction-resume-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.compaction_resume_receipt.v1') {
+  errors.push('type must be agent.compaction_resume_receipt.v1')
+}
+
+for (const key of ['compaction_event_id', 'session_id', 'trigger']) {
+  if (!receipt[key] || typeof receipt[key] !== 'string') {
+    errors.push(`${key} is required`)
+  }
+}
+
+const transcript = receipt.transcript || {}
+if (!transcript.range || typeof transcript.range !== 'string') {
+  errors.push('transcript.range is required')
+}
+if (!transcript.content_hash || typeof transcript.content_hash !== 'string') {
+  errors.push('transcript.content_hash is required; do not log raw transcript text')
+}
+if (transcript.raw_text_logged !== false) {
+  errors.push('transcript.raw_text_logged must be false')
+}
+
+const summary = receipt.summary || {}
+if (!summary.content_hash || typeof summary.content_hash !== 'string') {
+  errors.push('summary.content_hash is required')
+}
+if (!Number.isInteger(summary.token_count) || summary.token_count <= 0) {
+  errors.push('summary.token_count must be a positive integer')
+}
+
+const reloads = Array.isArray(receipt.instruction_sources_reloaded)
+  ? receipt.instruction_sources_reloaded
+  : []
+if (reloads.length === 0) {
+  errors.push('instruction_sources_reloaded must include at least one source')
+}
+for (const [index, source] of reloads.entries()) {
+  if (!source.kind || typeof source.kind !== 'string') {
+    errors.push(`instruction_sources_reloaded[${index}].kind is required`)
+  }
+  if (!source.ref || typeof source.ref !== 'string') {
+    errors.push(`instruction_sources_reloaded[${index}].ref is required`)
+  }
+  if (!source.content_hash || typeof source.content_hash !== 'string') {
+    errors.push(`instruction_sources_reloaded[${index}].content_hash is required`)
+  }
+  if (source.raw_body_logged !== false) {
+    errors.push(`instruction_sources_reloaded[${index}].raw_body_logged must be false`)
+  }
+}
+
+const state = receipt.state || {}
+const kept = Array.isArray(state.kept) ? state.kept : []
+const lost = Array.isArray(state.lost) ? state.lost : []
+if (kept.length === 0) {
+  warnings.push('state.kept is empty; reviewers may not know what survived compaction')
+}
+if (!Array.isArray(state.lost)) {
+  errors.push('state.lost must be an array, even when empty')
+}
+
+const verdict = receipt.resume_verdict || {}
+if (!['true', 'false', 'unknown'].includes(String(verdict.safe_to_resume))) {
+  errors.push('resume_verdict.safe_to_resume must be true, false, or unknown')
+}
+if (!Array.isArray(verdict.reasons) || verdict.reasons.length === 0) {
+  errors.push('resume_verdict.reasons must explain the verdict')
+}
+if (String(verdict.safe_to_resume) !== 'true') {
+  errors.push(`safe_to_resume is ${verdict.safe_to_resume}; stop, reload, or ask before continuing`)
+}
+if (lost.some((item) => item && item.blocks_resume === true)) {
+  errors.push('state.lost contains at least one blocks_resume=true item')
+}
+
+const privacy = receipt.privacy || {}
+for (const key of ['raw_prompts_logged', 'raw_tool_output_logged', 'secrets_logged', 'full_instruction_bodies_logged']) {
+  if (privacy[key] !== false) {
+    errors.push(`privacy.${key} must be false`)
+  }
+}
+
+const result = {
+  ok: errors.length === 0,
+  file,
+  compaction_event_id: receipt.compaction_event_id,
+  session_id: receipt.session_id,
+  safe_to_resume: verdict.safe_to_resume,
+  reloaded_sources: reloads.map((source) => `${source.kind}:${source.ref}`),
+  lost: lost.map((item) => item.ref || item.kind || 'unknown'),
+  errors,
+  warnings
+}
+
+console.log(JSON.stringify(result, null, 2))
+process.exit(result.ok ? 0 : 1)

package/examples/compaction-resume-receipts/safe-resume-receipt.json

@@ -0,0 +1,52 @@
+{
+  "type": "agent.compaction_resume_receipt.v1",
+  "compaction_event_id": "compact-2026-06-01T15-02-59Z",
+  "session_id": "codex-session-42",
+  "trigger": "PostCompact",
+  "transcript": {
+    "range": "messages:1-184",
+    "content_hash": "sha256-7f8f6fbf8a3e3fe0e9f6b59efac0e771d8f64a9ebff3e9b0f5162e43c2e3e89a",
+    "raw_text_logged": false
+  },
+  "summary": {
+    "content_hash": "sha256-8a4f6242e9800f1452bcfd5dbec7e9f1f0b543d72b0c96e57dece44f6c4b8de4",
+    "token_count": 1240
+  },
+  "instruction_sources_reloaded": [
+    {
+      "kind": "AGENTS.md",
+      "ref": "repo-root/AGENTS.md",
+      "content_hash": "sha256-06c39dfb1ba74f5ac6f0e1a6d6b4c65358c3f1a872e96f3fe8d61da947caa1d4",
+      "mtime": "2026-06-01T14:58:02Z",
+      "raw_body_logged": false
+    },
+    {
+      "kind": "plan",
+      "ref": "memory/current-plan.md#active",
+      "content_hash": "sha256-a9b30f8a50dd31ec3c818c9c0d05282bf97f54991a4032f2d547a30174de1c61",
+      "mtime": "2026-06-01T14:59:44Z",
+      "raw_body_logged": false
+    }
+  ],
+  "state": {
+    "kept": [
+      { "kind": "active_plan", "ref": "plan:fix-auth-smoke", "summary_hash": "sha256-4c0f7fd0a72b8cf7e45c0fb97b893590fa12e931f914a34b94756de0d876182c" },
+      { "kind": "open_diff", "ref": "git:working-tree", "summary_hash": "sha256-2e5a0da4b6b4e9d07f11c8f10f332fc74497ef6d052a46997c4f5d0bdb0e1b07" }
+    ],
+    "lost": []
+  },
+  "resume_verdict": {
+    "safe_to_resume": true,
+    "reasons": [
+      "instruction sources reloaded with hashes",
+      "active plan and open diff summarized",
+      "no blocking lost fields recorded"
+    ]
+  },
+  "privacy": {
+    "raw_prompts_logged": false,
+    "raw_tool_output_logged": false,
+    "secrets_logged": false,
+    "full_instruction_bodies_logged": false
+  }
+}

package/examples/compaction-resume-receipts/unsafe-resume-receipt.json

@@ -0,0 +1,41 @@
+{
+  "type": "agent.compaction_resume_receipt.v1",
+  "compaction_event_id": "compact-2026-06-01T15-02-59Z",
+  "session_id": "codex-session-42",
+  "trigger": "PostCompact",
+  "transcript": {
+    "range": "messages:1-184",
+    "content_hash": "sha256-7f8f6fbf8a3e3fe0e9f6b59efac0e771d8f64a9ebff3e9b0f5162e43c2e3e89a",
+    "raw_text_logged": true
+  },
+  "summary": {
+    "content_hash": "sha256-8a4f6242e9800f1452bcfd5dbec7e9f1f0b543d72b0c96e57dece44f6c4b8de4",
+    "token_count": 880
+  },
+  "instruction_sources_reloaded": [
+    {
+      "kind": "AGENTS.md",
+      "ref": "repo-root/AGENTS.md",
+      "content_hash": "",
+      "mtime": "2026-06-01T14:58:02Z",
+      "raw_body_logged": true
+    }
+  ],
+  "state": {
+    "kept": [],
+    "lost": [
+      { "kind": "rejected_decisions", "ref": "decision-log:missing", "blocks_resume": true },
+      { "kind": "pending_tests", "ref": "test-plan:unknown", "blocks_resume": true }
+    ]
+  },
+  "resume_verdict": {
+    "safe_to_resume": "unknown",
+    "reasons": ["AGENTS.md hash missing and blocking state was lost"]
+  },
+  "privacy": {
+    "raw_prompts_logged": true,
+    "raw_tool_output_logged": false,
+    "secrets_logged": false,
+    "full_instruction_bodies_logged": true
+  }
+}

package/examples/controlled-learning-queue/README.md

@@ -0,0 +1,26 @@
+# Controlled learning queue example
+
+A copyable layout for Claude Code/OpenClaw/Cursor-style "AI employee" agents that use a role file, Skills, memory, and external tools.
+
+The pattern is simple:
+
+- `role/job-contract.md` defines what the agent is allowed to do.
+- `skills/*.md` define procedures with inputs, outputs, and stop conditions.
+- `memory/durable.md` contains approved facts only.
+- `memory/working-notes.md` can hold temporary observations.
+- `learning_queue.md` is where the agent proposes durable memory changes as reviewable diffs.
+- `leads/*.md` are tiny active job cards.
+
+Run the smoke check:
+
+```bash
+node check-learning-queue.mjs learning_queue.md
+```
+
+Expected output:
+
+```text
+learning queue ok: 2 proposal(s), 1 pending review
+```
+
+Why it exists: agents can learn from outcomes, but durable cross-run memory should not be rewritten by one edge case without source, scope, expiry, and a promote/reject decision.

package/examples/controlled-learning-queue/check-learning-queue.mjs

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+
+const file = process.argv[2] || new URL('./learning_queue.md', import.meta.url).pathname;
+const text = fs.readFileSync(file, 'utf8');
+const proposals = text.split(/^## Proposal /m).slice(1);
+const required = ['Status', 'Source', 'Observed', 'Proposed durable change', 'Reason', 'Scope', 'Expiry', 'Reviewer', 'Decision'];
+const rawRisk = /(api[_-]?key|secret|password|token\s*[:=]|-----BEGIN|raw transcript|verbatim customer|full email)/i;
+const errors = [];
+let pending = 0;
+
+if (proposals.length === 0) errors.push('missing proposals');
+
+for (const [index, block] of proposals.entries()) {
+  const id = block.split('\n', 1)[0].trim() || `#${index + 1}`;
+  for (const field of required) {
+    if (!new RegExp(`^${field}:\\s*\\S`, 'mi').test(block)) {
+      errors.push(`${id}: missing ${field}`);
+    }
+  }
+
+  const status = block.match(/^Status:\s*(.+)$/mi)?.[1]?.trim().toLowerCase();
+  const reviewer = block.match(/^Reviewer:\s*(.+)$/mi)?.[1]?.trim().toLowerCase();
+  const decision = block.match(/^Decision:\s*(.+)$/mi)?.[1]?.trim().toLowerCase();
+
+  if (status === 'proposed') pending += 1;
+  if (status === 'promoted' && (!reviewer || reviewer === 'pending' || !decision || decision === 'pending')) {
+    errors.push(`${id}: promoted proposal needs reviewer and decision`);
+  }
+  if (/(auto-promote|autopromote|self-approved|self approved)/i.test(block)) {
+    errors.push(`${id}: auto-promotion is not allowed`);
+  }
+  if (rawRisk.test(block)) {
+    errors.push(`${id}: possible raw secret/private payload in learning queue`);
+  }
+}
+
+if (errors.length) {
+  console.error(`learning queue failed (${errors.length}):`);
+  for (const error of errors) console.error(`- ${error}`);
+  process.exit(1);
+}
+
+console.log(`learning queue ok: ${proposals.length} proposal(s), ${pending} pending review`);

package/examples/controlled-learning-queue/leads/acme-job-card.md

@@ -0,0 +1,12 @@
+# Lead job card: acme
+
+## Goal
+Prepare a qualification summary for a human owner.
+
+## Known facts
+- Source: demo form `lead-acme-2026-06-02`.
+- Interest: AI agent workflows for sales operations.
+- Constraint: no pricing promises without human owner.
+
+## Next safe action
+Draft questions about current workflow, systems of record, and approval boundaries.

package/examples/controlled-learning-queue/learning_queue.md

@@ -0,0 +1,27 @@
+# Learning queue
+
+Agents may propose durable memory updates here. Humans or maintainers promote/reject them.
+
+## Proposal 2026-06-02-001
+
+Status: proposed
+Source: lead-acme-2026-06-02 job card, redacted summary only
+Observed: Prospect asked how to prevent a role-based agent from changing ICP after one edge case.
+Proposed durable change: Add "role-based agents may propose ICP changes, but ICP memory changes require human promote/reject review" to `memory/durable.md`.
+Reason: This is a reusable safety boundary for future lead qualification runs.
+Scope: sales-ops-agent / ICP memory
+Expiry: 2026-07-02
+Reviewer: pending
+Decision: pending
+
+## Proposal 2026-06-02-002
+
+Status: rejected
+Source: lead-beta-2026-06-01 job card, redacted summary only
+Observed: One prospect wanted a custom discount workflow.
+Proposed durable change: Add "discount requests are common" to `memory/durable.md`.
+Reason: Rejected because one request is not enough to change durable market assumptions.
+Scope: sales-ops-agent / pricing assumptions
+Expiry: 2026-06-15
+Reviewer: owner@example.invalid
+Decision: reject; keep as working note only

package/examples/controlled-learning-queue/memory/durable.md

@@ -0,0 +1,10 @@
+# Durable memory
+
+Approved facts only.
+
+## ICP
+- Early-stage teams adopting AI coding agents need lightweight reviewable context, not another opaque memory dump.
+
+## Boundaries
+- Do not store raw customer messages, secrets, or private transcripts.
+- Pricing, legal commitments, and delivery promises require human review.

package/examples/controlled-learning-queue/memory/working-notes.md

@@ -0,0 +1,5 @@
+# Working notes
+
+Temporary notes may live here during an active job. Promote nothing from this file into durable memory without a `learning_queue.md` proposal.
+
+- 2026-06-02 lead-acme: asked about using Skills for sales ops. Needs human review before any pricing language.

package/examples/controlled-learning-queue/role/job-contract.md

@@ -0,0 +1,18 @@
+# Sales ops agent role
+
+## Mission
+Help qualify inbound leads and prepare concise handoff notes for a human owner.
+
+## Allowed
+- Read approved lead/job cards.
+- Draft next-step suggestions.
+- Propose changes to durable memory through `learning_queue.md`.
+
+## Not allowed
+- Promise pricing, discounts, contracts, legal terms, or delivery dates.
+- Rewrite `memory/durable.md` directly.
+- Store raw private email/chat text in durable memory.
+
+## Escalate when
+- A lead asks for legal/financial commitments.
+- A proposed learning would change ICP, pricing assumptions, compliance boundaries, or data-retention rules.

package/examples/controlled-learning-queue/skills/qualify-lead.md

@@ -0,0 +1,17 @@
+# Skill: qualify lead
+
+## Inputs
+- Lead job card path.
+- Current durable memory.
+- Any approved working notes for this lead.
+
+## Output
+- Qualification summary.
+- Open questions.
+- Suggested next action.
+- Optional `learning_queue.md` proposal if the case reveals a reusable durable fact.
+
+## Stop conditions
+- Missing consent or unclear data source.
+- Request requires a human commitment.
+- Proposed durable learning lacks source, scope, or expiry.

package/examples/loaded-resource-boundary/README.md

@@ -0,0 +1,22 @@
+# Loaded-resource boundary example
+
+This example turns "my Skill works in chat but disappears in ACP/Zed/CLI" into a stage-level receipt.
+
+Run:
+
+```bash
+node check-loaded-resource-boundary.mjs loaded-resource-boundary.json
+```
+
+Expected output:
+
+```text
+loaded-resource boundary ok: 1 required resource/runtime gap recorded
+```
+
+The sample records the same project skills across two sessions:
+
+- `chat` discovers, attaches, injects, and reads `skill:pr-review`;
+- `acp`/`zed` discovers and attaches it, but never injects it, so the receipt records `runtime_does_not_inject_resources` and sets `safe_to_continue=false`.
+
+Use this shape when prompt instructions cannot explain a missing Skill. The host/runtime needs to prove the resource crossed the boundary, not merely that it exists on disk.

package/examples/loaded-resource-boundary/check-loaded-resource-boundary.mjs

@@ -0,0 +1,65 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+
+const file = process.argv[2] ?? new URL('./loaded-resource-boundary.json', import.meta.url);
+const receipt = JSON.parse(fs.readFileSync(file, 'utf8'));
+const fail = (message) => {
+  console.error(`loaded-resource boundary invalid: ${message}`);
+  process.exit(1);
+};
+
+if (receipt.receipt_type !== 'pluribus.loaded_resource_boundary.v1') fail('unexpected receipt_type');
+if (!Array.isArray(receipt.expected_resources) || receipt.expected_resources.length === 0) fail('expected_resources must be non-empty');
+if (!Array.isArray(receipt.sessions) || receipt.sessions.length < 2) fail('sessions must include at least two runtimes for parity checks');
+
+const expectedIds = new Set(receipt.expected_resources.map((resource) => resource.id));
+const requiredIds = new Set(receipt.expected_resources.filter((resource) => resource.required !== false).map((resource) => resource.id));
+for (const resource of receipt.expected_resources) {
+  if (!resource.id || !resource.kind || !resource.source_ref || !resource.source_hash?.startsWith('sha256:')) {
+    fail(`expected resource ${resource.id ?? '<missing>'} needs id, kind, source_ref, and sha256 source_hash`);
+  }
+}
+
+const allowedSkipReasons = new Set([
+  'not_discovered',
+  'not_attached_to_agent',
+  'runtime_does_not_inject_resources',
+  'trigger_not_matched',
+  'resource_read_failed'
+]);
+
+let mismatches = 0;
+for (const session of receipt.sessions) {
+  for (const key of ['runtime', 'client', 'agent']) {
+    if (!session[key]) fail(`session ${session.session_id ?? '<missing>'} missing ${key}`);
+  }
+  for (const listName of ['discovered_resources', 'attached_resources', 'injected_resources', 'readable_resources', 'skipped_resources']) {
+    if (!Array.isArray(session[listName])) fail(`${session.session_id}: ${listName} must be an array`);
+  }
+
+  const stageSets = {
+    discovered: new Set(session.discovered_resources),
+    attached: new Set(session.attached_resources),
+    injected: new Set(session.injected_resources),
+    readable: new Set(session.readable_resources)
+  };
+  const skipped = new Map(session.skipped_resources.map((skip) => [skip.id, skip]));
+
+  for (const id of expectedIds) {
+    if (stageSets.readable.has(id)) continue;
+    const skip = skipped.get(id);
+    if (!skip) {
+      if (requiredIds.has(id)) fail(`${session.session_id}: ${id} is required, not readable, and has no skipped_resources entry`);
+      continue;
+    }
+    if (!allowedSkipReasons.has(skip.reason)) fail(`${session.session_id}: ${id} has unknown skip reason ${skip.reason}`);
+    if (!skip.stage) fail(`${session.session_id}: ${id} skip entry needs a stage`);
+    if (requiredIds.has(id)) mismatches += 1;
+  }
+}
+
+if (receipt.safe_to_continue !== false && mismatches > 0) {
+  fail('safe_to_continue must be false when expected resources are missing or skipped');
+}
+
+console.log(`loaded-resource boundary ok: ${mismatches} required resource/runtime gaps recorded`);