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:

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.

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 and Profiles and assurance.

ABI and wire boundaries#

A language projection never implies a transport or deployment boundary. See Packaging and boundaries.

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.

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.