# Contracts and components

One models a complete system from small, independently owned contracts. Each
contract says exactly what consumers can rely on while leaving runtime and
provider choices open until planning.

## Data and schemas

Contracts define nominal values, schemas, codecs, compatibility, faults, and
cross-owner mappings. Data then owns state and physical data concerns:
transactions, queries, layouts, conversion paths, durability, replication,
partitioning, backup, and deletion.

Semantic and physical schemas stay distinct. An operation may require a
transactional record model without baking a storage engine into its API.
Planning selects a physical layout and provider only after proving conversions,
loss, cost, trust, topology, and policy.

## Operations and services

An operation owns its input, output, domain faults, effects, deadlines,
cancellation, idempotency, authority, and evidence obligations. A service is a
coherent set of operations and lifecycle behavior, not proof that those calls
are remote.

Planning may realize one edge as a static call and another as a process or
network boundary. Remote placement adds the exact codecs, identities,
transport, delivery, retries, backpressure, encryption, discovery,
observations, and cost that boundary requires.

## Jobs and workflows

Jobs model bounded background work. Workflows model durable coordination:
commands, history, timers, activities, retries, signals, queries, updates,
children, human tasks, compensation, and versioning.

Workflow determinism is explicit. External effects occur through journaled
activities with idempotency or reconciliation contracts. An unknown outcome is
never rewritten as failure merely so another attempt can begin.

## State and resources

Resources have identities, ownership, lifecycle, containment, borrowing, and
cleanup obligations. State bindings name semantic requirements independently
of storage realization.

One can compose embedded, remote, replicated, sharded, cached, streamed, and
offline-capable data paths, but each stronger claim needs its own executable
evidence. Package presence cannot turn an ephemeral store into durable state
or a single process into a multi-tenant stateful host.

## Applications and frontends

An ordinary web, mobile, desktop, terminal, or device application uses its
chosen framework directly. Its routes, components, loaders, actions, state,
layout, styling, and interaction behavior belong to the application.

The application consumes only the One contracts it needs: generated or
handwritten SDKs, schemas, operations, component bindings, artifacts,
authority, observations, and evidence. React, SwiftUI, Compose, Flutter,
Tauri, and other frameworks do not need to become One renderers before they
can participate in a One system.

## Local and distributed are one component model

One does not force distribution and does not disguise it. A component can be
realized as:

- a static in-process implementation;
- an executor task or thread;
- a sandboxed WebAssembly component;
- a supervised local process;
- a remote service;
- an external managed capability.

Each descent introduces only the contracts required by the selected boundary.
The semantic operation remains the same; the physical plan records the new
failure modes and costs.

## Example

Illustrative end-product syntax keeps a service contract independent from its
placement:

```one
semantic parcelhub.orders
    domain one.contracts@1
    operation Get@1
        input GetOrder output Order effect read(order)
    service Orders@1
        operation Get
    root OrdersApi@1
        require Orders.Get
```

Follow [Build a typed service](/one/examples/service) for the complete slice.

Canonical owners:
[Components](https://github.com/muijf/one/blob/main/systems/components/AGENTS.md),
[Data](https://github.com/muijf/one/blob/main/systems/data/AGENTS.md), and
[Communication](https://github.com/muijf/one/blob/main/systems/communication/AGENTS.md).

Next: [data and state](/one/model/data).