# Schemas and contracts

Schemas and contracts are the durable, language-neutral vocabulary of a One
system. They describe meaning independently of Rust layout, Python objects,
wire codecs, database rows, UI state, or transport.

## Bounded semantic data

A semantic type owns fields, variants, units, constraints, classifications,
purposes, identity, nullability, and compatibility. Bounds are operational
facts: they affect validation, allocation, frame admission, storage planning,
fuzzing, redaction, and generated clients.

Physical representations remain separate. One semantic record may be realized
as a Rust struct, TypeScript discriminated union, Python validated object,
Protobuf message, row layout, columnar array, or WIT record.

## Operations own more than signatures

An operation contract includes:

- nominal input, output, and recoverable domain faults;
- effect and state-impact semantics;
- deadline, cancellation, delivery, and idempotency obligations;
- authentication, authorization, capability, and data-policy requirements;
- streaming, backpressure, and compatibility behavior.

No executor, HTTP framework, database driver, or cloud type belongs in the
semantic contract.

## Domain faults are not invocation causes

| Channel | Examples |
| --- | --- |
| Domain fault | invalid order, insufficient stock, business rejection |
| Invocation cause | admission, cancellation, deadline, incompatibility, transport |
| Effect outcome | definitely aborted, committed, or outcome unknown |
| Defect | invariant violation, panic, corrupt provider output |

Keeping these separate lets a local call become remote without rewriting its
business fault schema.

## One Contract Schema

One Contract Schema (OCS) is the canonical, content-addressed contract package.
It contains nominal schemas, operations, faults, effects, resources, services,
capabilities, documentation, deprecation, and compatibility.

Rust, native One, TypeScript, Python, WIT, Protobuf, OpenAPI, and GraphQL are
profile-governed projections. Every projection records exact, represented,
shimmed, qualified, unsupported, and lossy dispositions.

Generated source is a disposable cache. Editing it cannot redefine the
contract.

## Compatibility is exact

Compatibility is checked at each real edge: stored state, active deployments,
remote peers, generated clients, histories, and imported models. Similar names
or shapes do not establish compatibility.

A mapping between owners is directional and destination-validated. A `U64`
cannot silently become a JavaScript `number`, and a remote typed failure cannot
collapse into an unchecked exception without an explicit loss disposition.

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