# OWP engineering specification

Current executable profiles are [documented here](../owp/implementation-status.md):
`owp-market-local/0.2` supplies the marketplace/weather kit and
`owp-eval-local/0.1` the earlier single-job lab. The specification below describes
canonical reconciliation and production requirements; it must not be read as an
inventory of only the original alpha schemas. See [current status](../STATUS.md).

## Routing and federation role — 23 September 2026

OWP is the router and matcher between Operanda and task agents. Operanda submits structured jobs with explicitly permitted routing metadata and field-level encrypted inputs or opaque references. OWP matches eligible agents and federates assignments and permitted outcome metadata. It never receives private-field plaintext or Vault keys, and cannot authorize a disclosure or side effect. Operanda independently enforces grants and delivers plaintext directly to the designated end service.

The [cross-app Vault decision](cross-app-vault.md) defines this target. The contract/conformance work below supports that routing role; it is not the whole product definition of OWP. Federation topology, routing projection and generated wire schemas remain implementation work. Existing alpha schemas do not prove a production router or allow matching services to inspect private memories.

Status: canonical reconciliation remains open. Executable local profiles include `coz-local-alpha/0.1`, `owp-market-local/0.2` and `owp-eval-local/0.1`; their authority and compatibility claims remain separate. Owner: contracts and interoperability. Issues: [#10](https://github.com/cairnhold/coz/issues/10), [#4](https://github.com/cairnhold/coz/issues/4), [#9](https://github.com/cairnhold/coz/issues/9).

For a visual introduction, open the [OWP HTML overview](../open-work-protocol.html).
It summarizes the linked v0.4 Notion source and architecture separation guide;
it is not a schema, adopted revision, or conformance result.

## Objective

Make work, input authority, runtime identity and outcome acceptance unambiguous across Coz, Operanda and agent runtimes. A JSON shape check does not establish authority, encrypted transport interoperability or adoption of a canonical specification. Preserve separate namespaces for historical baseline, 0.2 delta, executable alpha and newer unified-job-spec work.

## Baseline and reconciliation order

1. Recover the actual original 0.1 contract/OpenAPI attachment bytes. Store source URI, SHA-256, retrieval time and revision. Chapter prose alone is insufficient to reconstruct an authoritative contract.
2. Inventory every 0.2 addition against the actual baseline: fields, required/default semantics, visibility, owner/enforcer, enum values, errors and state transitions. Cross-reference BLK-02/04/06, CON-01/06/08 and PRC-08.
3. Resolve conflicts with decision records. Money units, ownership, recovery distribution, standing-grant attenuation and canonical profile naming require explicit adoption. Do not turn uploaded review suggestions into defaults.
4. Generate a merged candidate from source DTOs; keep alpha code on its pinned profile until a deliberate versioned migration exists.
5. Produce positive and negative vectors and run two independent implementations before labeling conformance.

Current build addition: companion DTOs reside in `packages/contracts/companion.ts` as dependency-free internal interface types. They preserve the current Hermes wire behavior. The file is not an alternative OWP schema or new public API. Existing runtime schemas still generate through `scripts/generate-contracts.ts`.

## Required contract families

| Family | Required binding / invariant | Current evidence / gap |
|---|---|---|
| Record and sealed payload | Space, revision, author, signer, visibility, provenance; fresh content key per revision | Alpha schemas and crypto tests exist; canonical classification incomplete |
| Device/node identity | Owner-authorized keys, revocation, profile and direction | Fixture certificate exists; production node enrollment absent |
| Work specification | Intent, output space, exact inputs, runtime/bundle, expected revision | Alpha pins inputs/runtime; newer unified job-spec PR must be reconciled |
| Assignment/lease/outcome | Attempt identity, lease fence, node identity, signed bounded result | Local lifecycle exists; distributed wire profile missing |
| Disclosure grant | Recipient, exact revisions, purpose/expiry/use limits; authority chain cannot widen | Exact fixture grant exists; standing and delegated grants remain off |
| Acceptance and action approval | Different authorities and digests for result acceptance versus side effects | Owner work acceptance exists; effect broker absent |
| Manifest and evaluation | Publisher signature, bundle digest, capabilities, runtime constraints, evaluation revision | Instruction catalog is not proof of executable admission |
| Money/settlement | Adopted currency exponent, representation and exact rounding/ownership rules | Disabled. No conversion inferred from review examples |

## Schema and API design rules

Source DTOs live in `packages/contracts`; generate JSON Schema/OpenAPI using `npm run contracts`. Generated files are outputs, never handwritten. Reject unknown authority-bearing fields and unsupported profile/version tokens. Put bounded lengths/counts on strings, arrays, envelopes and assignments. Canonicalize exactly the signed representation; preserve cross-language byte vectors. Never accept a signature over one projection and execute a different expanded object.

Current public alpha routes are `GET /health`, `POST /v1/pair` and `POST /v1/command`. Encrypted command `op` values include snapshot, record.put, work.draft/activate/cancel/accept and grant.create/revoke/deliver. An HTTP 200 only delivers an authenticated response envelope; clients must inspect the decrypted command result. Future APIs require explicit error mapping for unauthorized/revoked principal, stale revision/fence, unsupported profile, replay, conflicting request identity, unavailable node, missing disclosure, locked endpoint and unknown effect outcome.

Do not standardize current internal polling/storage routes as production assignment transport by accident. Do not claim the Hermes connector's `/v1/responses` is the OWP command protocol.

## Proposed reconciliation artifacts

Repository layout: `docs/architecture/sources/` for immutable retrieved originals; `docs/architecture/decisions/` for adopted conflicts; `packages/contracts/` for source validators; `generated/` for schemas/OpenAPI; `tests/fixtures/profiles/` for versioned vectors; `docs/engineering/conformance-matrix.md` for implementation/evidence coverage when available.

Inventory record: `{artifact_id, profile, source_uri, source_revision, sha256, media_type, retrieved_at}`. Field matrix: `{type, field, classification, writer, reader, enforcer, source_clause, disposition}`. Conformance evidence: `{requirement_id, profile, implementation_revision, test_id, result, evidence_digest}`. These are proposed engineering artifacts, not approved new wire DTOs. Never include credentials or private input examples.

## Negative test matrix

| Input / event | Expected result |
|---|---|
| Wrong profile, direction or recipient | Reject before plaintext use |
| Changed signed metadata/ciphertext | Signature or AEAD failure; no dispatch |
| Reused request ID with changed command | Conflict; no second operation |
| Stale pinned record / runtime digest | New review required; no execution |
| Shared output with private input | Authorization failure |
| Expired/revoked grant or widened attenuation | Reject disclosure |
| Old lease outcome after replacement worker | Stale fence rejection; no requeue authority |
| Missing completion after transport interruption | Unknown/partial state, no invented success |
| Effect response lost after possible provider success | Hold unknown outcome, reconcile without duplicate execution |

## Acceptance and release

Step 2 may ship a synthetic profile-specific native proof after tests, while canonical reconciliation remains pending. Its label must name the exact profile. Canonical release requires retrieved baseline bytes, adopted conflict decisions, complete visibility/error/state matrices, generated contracts, independent implementation vectors and migrations for every persisted changed field. Settlement and package execution require their own release evidence. Preserve old vectors and reject unsupported versions instead of quietly coercing them.

## Implemented audit — 22 September 2026

`npm run contracts` now also runs `contracts:audit`. The deterministic `generated/contract-audit.json` records SHA-256 hashes of six source artifacts and every generated schema, the exact implemented relay routes and encrypted command operations. It labels historical prose, the 0.2 delta, alpha runtime, job-spec and agent-evidence profiles separately. Canonical conformance remains explicitly false.

The original [Notion contract page](https://app.notion.com/p/3dded9cb320181728036fe59598718cd) was rechecked. It references the original schema and OpenAPI attachments, but the connector's attachment-download API returns not-found for those historical attachment IDs. The in-app browser requires sign-in; native UI access was unavailable while the Mac was locked. Original bytes were not recovered or reconstructed. The page confirms that occurrence uniqueness excludes definition revision and that DST policy skips nonexistent times and selects the earlier duplicated instant; historical prose still does not substitute for the missing contract files.