PaperClipAI/packages/paperclip-runner/spec/prp-v1-expressiveness-audit.md

PRP v1 expressiveness audit

Verdict

PRP v1 is sufficient for runner lifecycle, replay integrity, negotiated runner features, runtime/issue-thread request routing, structured work disposition, terminal causality, and provider-neutral semantic-control-plane receipts. The optional semantic_tool and terminal.stopReason envelopes now type tool invocation, authorization denial, redaction, optimistic concurrency, mutation receipts, artifacts, governed targets, causal continuations, and budget stops. They remain receipts for control-plane-owned operations, not a provider tool catalog or permission to move control-plane policy into the runner.

prp-v1-expressiveness-crosswalk.json is the machine-checked source for this verdict. Its Vitest gate rejects an unclassified required fact, a fact justified only by a permissive field, an unbounded control-plane-local fact, or an accepted additive change without required fixtures.

Evidence boundary

This audit compares the canonical capability authority and its traceability inputs, the real-surface ledger, the deterministic mock, live Codex/runnerd transport, and PRP schemas/replay fixtures. The wire contract is not the tool catalog: capability placement controls exposure, while PRP carries execution and causality. generic_api_request remains test-only and cannot satisfy any coverage row.

What v1 proves directly

• capabilities.schema.json negotiates driver identity, session reuse, steering, interruption, resume, runtime requests, structured results, typed events, and explicit unsupported features.
• Events have stable source instance/event ids, source ordering, run/session/ turn/item correlation, priority, and an explicit v1 schema version. Replay rejects unsupported required event versions, requires byte-equivalent duplicate source events, records source gaps, and is side-effect free.
• Commands have controller ordering and preconditions; runtime and issue-thread requests have typed kinds/statuses; results require completion claims, verification, artifacts, and blocker/yield continuations where applicable.
• run.terminal is a typed terminal envelope with terminal state, work assessment, and issue-status decision references. Existing golden replay, duplicate-event, unknown-optional-fields, and unsupported-required-version fixtures demonstrate the compatibility boundary.
• capabilities.semanticTools advertises versioned, provider-neutral operation availability and redaction rules. Paired mcp_app.tool_input and mcp_app.tool_result events carry one safe semantic_tool envelope per call.
• terminal.stopReason carries a safe budget/cost aggregate and the decision receipt that stopped the run. Eval trace_completeness reads these PRP wire receipts when available while retaining the existing live-evidence fallback.

Landed additive v1 envelope

The correction is one optional, versioned semantic_tool envelope for mcp_app.tool_input / mcp_app.tool_result, plus an optional terminal.stopReason envelope. It defines:

• operation id, call id, correlation ids, idempotency key, outcome, stable code, retryability, and audit/operation receipt id;
• admitted input/output references or digests, redaction disposition, and only safe identifiers; never raw credentials, hidden-company identifiers, or secret payloads;
• authorization boundary (company, actor, active_task, grant, governed_action, lock, or revision), current revision where safe, and a deterministic conflict/duplicate result;
• artifact/work-product references linked to the semantic receipt and terminal result; immutable interaction/approval document or decision targets; and budget stop reason/aggregate/decision id.

This remains additive because existing v1 consumers can ignore the optional typed envelopes. The reducer intentionally does not project them into session state; they supply inspectable trace evidence only. Unknown optional fields are accepted, while an unknown required envelope version fails closed.

Classification and fixture plan

The crosswalk assigns every required fact to exactly one of: direct v1, compositional v1 with a listed invariant, control-plane-local, additive v1, missing fixture/docs, or breaking v2 work. Direct and compositional support is never inferred merely from additionalProperties: true.

The additive change graduated to direct support with these fixtures and golden projections:

1. semantic-tool-artifact-happy-path.json — artifact and work-product receipt;
2. semantic-tool-denial-redaction.json — denied/redacted with no fallback;
3. semantic-tool-conflict-duplicate-retry.json — stale conflict and exact retry;
4. semantic-tool-governance-wake-monitor.json — immutable governed targets and continuation chain;
5. budget-cost-stop-reason.json — typed terminal budget/cost stop;
6. semantic-tool-unknown-optional-envelope.json — optional fields accepted with unchanged projection;
7. semantic-tool-unsupported-required-version.json — required v2 envelope rejected fail-closed.

The six accepted fixtures replay to TypeScript/Rust parity summaries and golden snapshots. Shared high-risk semantic vectors compare normalized receipt and state-diff observations across deterministic mock and production bindings.

Explicit exclusions

Checkout/release, task selection, wake routing, budget enforcement, audit and run persistence/replay, assignment, and monitor management are control-plane actions, not runner-wire semantic operations. Cross-company discovery, broad audit access, destructive document lifecycle, and company administration are breaking v2/product-governance work. The runner must report typed unavailable or denied outcomes rather than tunnel those operations through generic payloads.

Review checklist

• Golden replay, duplicate/retry, and unknown-version fixtures accompany every accepted protocol schema/event addition.
• A semantic receipt is typed and safe before any surface is marked supported.
• Control-plane-local decisions stay out of the semantic tool wire.
• Eval trace scoring consumes wire receipts without changing projection semantics.