## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - The Codex driver needs a controller-owned oracle for semantic completion and replay > - Provider proposals are advisory and must satisfy the exact task envelope > - Persisted events must be bounded and validated before deterministic replay > - Live provider behaviors also need one checked-in, schema-validated fixture > - This pull request adds that test and conformance layer before the full driver > - The runner adapter remains disabled and no production execution path changes ## Linked Issues or Issue Description **Subsystem affected** `packages/paperclip-runner` Codex trace, result-validation, and replay conformance. **Problem or motivation** A provider-completed turn is not sufficient authority to finalize a Paperclip run. Results must match the controller-owned completion contract, and persisted provider events must be validated before they can rebuild controller state. **Proposed solution** Add a bounded Codex trace harness that validates result proposals, emits controller decisions and terminals, verifies live/replay parity, and rejects malformed persisted streams. Add a validated fixture for runtime requests, goals, lineage, controls, reconnect identity, and redaction cases. **Alternatives considered** Embedding these assertions only in the production driver would mix controller authority with provider transport behavior and make deterministic replay harder to review. **Roadmap alignment** This supports the Codex-first experimental runner. It does not enable the runner adapter or add another provider. ## What Changed - Added exact task-envelope result validation. - Added bounded persisted-event validation and deterministic replay. - Added a controller-owned Codex trace harness and parity assertions. - Added and validated the checked-in Live console conformance fixture. - Updated the generated protocol manifest with the fixture source. - Added focused result and fixture tests. ## Verification - `pnpm --filter @paperclipai/paperclip-runner test:typescript` - `pnpm -r typecheck` - `pnpm build` - The focused trace-conformance test has 2 passing cases. ## Risks The main risks are accepting a mismatched semantic result or replaying corrupted provider history. Validation covers schema, contract revision, criteria identity, disposition invariants, event identity, uniqueness, ordering, terminal count, and byte limits. ## Model Used OpenAI Codex with GPT-5.6 and repository tool use. ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have searched GitHub for duplicate or related PRs and linked them above - [x] I have either (a) linked existing issues with `Fixes: #` / `Closes #` / `Refs #` OR (b) described the issue in-PR following the relevant issue template - [x] I have not referenced internal/instance-local Paperclip issues or links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip` URLs) - [x] My branch name describes the change (e.g. `docs/...`, `fix/...`) and contains no internal Paperclip ticket id or instance-derived details - [x] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [ ] All Paperclip CI gates are green - [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [x] I will address all Greptile and reviewer comments before requesting merge
PRP v1 Contract
The JSON Schema files in schemas/ are the language-neutral source of truth for
Paperclip Runner Protocol version 1. The fixtures in fixtures/ define accepted
and rejected compatibility cases.
Compatibility
protocolVersion,fixtureVersion, andevent.schemaVersionare required.- A consumer fails closed when a required version or schema discriminator is not supported.
- A v1 envelope can contain an unknown optional property when its schema marks that object as extensible.
- A consumer ignores an unknown optional property until a later contract gives it meaning.
- A required field, enum value, or typed structured-input field is not optional.
- Question and answer identifiers are stable across the provider boundary.
The unknown-optional-fields.json fixture must be accepted. The
unsupported-required-version.json fixture must be rejected.
Scope
The first provider descriptor and adapter fixture cover Codex only. The schemas for provider-neutral events and semantic receipts do not enable those actions. Discovery and authorization are separate contracts.
The conformance manifest records every source file and its SHA-256 digest. Run
pnpm generate:protocol-manifest from this package after a source change. CI
runs the same generator with --check to reject drift. This check also compiles
the JSON Schemas and validates every replay, question, and cross-language
conformance fixture against its declared schema.
The files in fixtures/replay/golden/ are deterministic reducer oracles. Each
accepted replay fixture has a complete session snapshot and a compact parity
summary. pnpm generate:replay-goldens updates them after an intentional
reducer change; package build and CI fail when they drift.
The files in fixtures/local-runner/scripts/ drive the package-local fake
harness. They cover successful, failed, interrupted, interactive, duplicate
terminal, process-cleanup, and oversized-frame behavior without starting a
production adapter.