# One Contract Schema (OCS)

One Contract Schema (OCS) is the normalized owned semantic model expressed as a
language-neutral, content-addressed contract package. It is not `.one`, WIT,
OpenAPI, Protobuf, or generated code, and it is not a second semantic source.

This is a reference page: it points at the owning contracts instead of
re-deriving their laws.

## What OCS covers

OCS covers the canonical contract meaning of one exact semantic revision:

- nominal records, variants, and enums;
- bounds and classifications;
- resources and handles;
- services and operations;
- unary and streaming interactions;
- recoverable domain faults;
- outer invocation causes;
- cancellation and deadlines;
- delivery;
- effects and idempotency;
- authentication and authorization requirements;
- capabilities;
- documentation and deprecation;
- compatibility.

A domain operation remains an ordinary exact operation contract across every
surface. CLI, Rust, TypeScript, HTTP, UI, and automation projections retain the
same operation identity.

## Canonical serialization

OCS is serialized canonically as versioned CBOR and has a human-readable
diagnostic form. The contract-package encoding is distinct from physical
request/response codecs. P-IR selects physical encodings without redefining
semantic identity.

## Semantic identity and wire format

Semantic identity lives in the contract package. Wire codecs, compatibility
fingerprints, and compatibility lanes are separate coordinates. A compatibility
lane never substitutes for the exact revision recorded in locks and receipts.

## Projection profiles and dispositions

A `LanguageProjectionProfile` describes how contracts are represented for a
language consumer. A distinct `ImplementationLanguageProfile` describes how an
authored implementation body is checked against its implementation claim, built,
and realized. They are distinct typed namespaces and never reuse one identity.

For every applicable item, a projection profile records one exhaustive
disposition:

| Disposition | Meaning |
| --- | --- |
| `exact` | The target directly expresses and enforces the semantic contract |
| `represented` | A generated nominal wrapper or library type preserves it |
| `shimmed` | Generated runtime code enforces it at a boundary |
| `qualified` | It is preserved only under explicit target/profile constraints |
| `unsupported` | Generation fails for this target/profile |
| `loss` | A named semantic loss remains and policy must explicitly admit it |

The generator cannot silently choose a weaker representation. For example, a
One `Integer` cannot become a JavaScript `number`; the TypeScript profile must
choose `bigint`, a checked branded representation, or a typed unsupported or
loss outcome. A remote `Exit<T,E>` cannot collapse into an unchecked exception,
and a language-level effect or ability type is never treated as a runtime grant.

## Generated code is a cache

Before generation, the Build lock contains one `ProjectionLockEntry` for each
reachable projection with its exact inputs. After realization, each projection
emits a content-addressed `ProjectionReceipt` binding that lock entry to the
action, output manifest, source maps, locked dispositions, ABI and runtime
consequences, and required conformance.

An output digest proves only those bytes. It does not prove semantic
correctness or reproducibility. Generated source is disposable and may be
regenerated from its lock; editing it cannot redefine the contract. See
[Generate and use an SDK client](/one/examples/sdk-client).

## Language-support capability sets

"Supports a language" is not one boolean claim. Each distribution declares the
capability sets it provides: contract values, client, service or activity
worker, portable workflow, implementation-body language, and native embedding.
A lower capability set never proves a higher one. See
[Languages and SDKs](/one/platform/languages) and
[Profiles and assurance](/one/reference/profiles).

## ABI and wire boundaries

| Boundary | Mapping |
| --- | --- |
| In-process Rust static | Native Rust types and monomorphized traits |
| WebAssembly component | WIT mapping and the Component Model canonical ABI |
| External process / remote | OCS frame protocol over the selected transport |
| C / native plugin | Versioned C ABI with opaque handles, fixed-width types, and explicit allocator and ownership |
| Rust dynamic library | Not a stable cross-version ABI; only inside one exact toolchain lock |

A language projection never implies a transport or deployment boundary. See
[Packaging and boundaries](/one/platform/packaging).

## Compatibility and negotiation

A contract carries stable operation, type, field, and variant IDs; compatibility
lanes; exact semantic and wire fingerprints; accepted input and output ranges;
unknown-field and unknown-variant behavior; fault and cause compatibility;
streaming, cancellation, and backpressure features; security minimums; and
deprecation and removal dates.

A handshake resolves a compatible exact mapping before application traffic. An
unsafe incompatibility yields `ContractIncompatible` with the exact field,
operation, disposition, and rule. A downgrade cannot weaken authentication,
authorization, effect, delivery, classification, or resource-bound semantics.

## Protocol and documentation projections

WIT, Protobuf, FlatBuffers, OpenAPI, GraphQL, and other protocol projections are
ordinary projection profiles with loss reports. Their evolution constraints do
not become canonical source-owner semantics. An unsupported or lossy export
blocks unless policy explicitly accepts a named degradation.

Documentation and developer portals are generated views of the semantic graph,
not a manually curated second source. They include operation meaning,
authorization and capabilities, effects, idempotency, faults and causes,
streaming and backpressure, compatibility, examples, provenance, and changelog.

## OCS package identity

OCS owns `ContractPackage`. It is distinct from `SemanticDomainPackage`,
`ProviderDistributionPackage`, `SemanticDistributionPackage`, and atom-sized
implementation crates. Distribution and implementation artifacts project or
realize exact OCS meaning; their presence never becomes semantic authority or
activation.

## Normative owner & evidence

The canonical owner is
[Contracts](https://github.com/muijf/one/blob/main/systems/contracts/AGENTS.md).

Demonstrated today: the Rust reference projection, the bounded TypeScript
bounded-unary contract slice with its capability-empty Rust-built Wasm OCS
kernel, and `one export ocs` over a selected root projection. Illustrative:
additional language and protocol projections, and any mapping or loss whose
exact profile, toolchain, and conformance are not yet selected for a root.