43 lines
2.0 KiB
Markdown
43 lines
2.0 KiB
Markdown
# 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`, and `event.schemaVersion` are 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.
|