RomanNum3ral
/
paperclip
mirror of https://github.com/paperclipai/paperclip.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
paperclip/packages/paperclip-runner/protocol/README.md

2.0 KiB
Raw Blame History

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.