# State and data

One separates data meaning from physical representation, storage engine,
placement, and query execution.

## Semantic and physical schemas

A semantic schema describes what data means: nominal identity, fields,
constraints, units, classification, purpose, retention, residency, and
compatibility.

A physical schema describes how bytes are represented: rows or columns,
offsets, alignment, encoding, compression, encryption, device, ownership, and
mutability.

Many physical schemas may realize one semantic schema. A provider can change
without redefining the data contract.

## Explicit state contracts

State declarations describe required behavior such as:

- key-value, relational, graph, document, event, or specialized access;
- consistency, isolation, durability, and transaction domain;
- query and indexing intent;
- change streams, snapshots, cursors, lineage, and retention;
- classification, residency, encryption, and deletion obligations;
- capacity, latency, throughput, and cost envelopes.

Database-specific handles and SQL strings are implementation details unless an
explicit lower-level contract selects them.

## Transactions have bounded domains

Atomicity is valid only inside a declared transaction domain. Crossing storage
or provider boundaries requires a workflow, outbox, reconciliation, or another
explicit coordination contract.

One does not turn a distributed effect into a transaction by naming it one.

## Query and conversion planning

The Data system can select costed physical layouts, conversions, and kernels
while preserving the semantic type and recording every conversion loss.

Substrait may be used narrowly for relational query-plan interchange. It is not
the general `.one` language or semantic owner.

## Live data is a contract

A live projection defines snapshot identity, cursor scope, ordering, replay
window, tombstones, gap handling, overflow, resumption, authorization renewal,
and backpressure before selecting polling, SSE, WebSocket, WebTransport, or
another transport.

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