# One Database

One Database is One's native Data realization: a bounded single-node temporal
transaction engine selected through the same public contracts and exact root
lock as SQLite, PostgreSQL, and other removable providers. It is not a SQL
clone, application server, workflow engine, or bundle of unrelated databases.

Applications continue to declare schemas, operations, effects, state lanes,
bounds, queries, retention, recovery, and authority in ordinary `.one` source.
They do not add database-specific tables, reducers, SQL, physical indexes, or
a separate database manifest to activate the provider.

## One authority, many projections

Durable transaction authority is one verified checkpoint plus the contiguous,
checksummed, hash-linked commit-journal suffix after it. One commit sequence
identifies one atomic decision. A journal prefix is reclaimed only after a
replacement checkpoint is atomically installed and verified to preserve every
retained semantic, temporal, recovery, and projection obligation.

Everything optimized for reading is a projection of that authority:

- ordered current state;
- retained temporal layouts;
- secondary indexes and constraint indexes;
- columnar segments and other selected physical layouts;
- caches, incremental views, and subscriptions.

Every projection names its complete input, query or layout revision, source
commit watermark, authority and visibility scope, freshness, retention, and
rebuild receipt. It can be discarded and reconstructed when the required
checkpoint and journal range remain available. Otherwise the provider returns
a typed retention gap rather than inventing continuity.

The first ordered current-state layout is selected from measured workload
evidence. Ordered-tree, log-structured, columnar, chunked, compressed, and
other mechanisms are implementation candidates—not product identities or
application-visible table kinds. A physical mechanism remains absent unless
its end-to-end benefit, including write amplification, recovery, storage,
memory, maintenance, and operational cost, is proven.

## Always transactional, never ambient

Every read observes an immutable snapshot. Every admitted write transaction
program is a deterministic state transition over declared input, bounded state
lanes, an exact base snapshot, and explicit transaction context. It reaches
exactly one decision:

- `Committed`, with the typed output and exact commit receipt;
- `Rejected`, with a domain or contract reason and no admitted mutation; or
- `OutcomeUnknown`, with a stable recovery token that must be reconciled before
  redispatch.

Those decisions are distinct from outer execution failures such as
`Unsupported`, `Unsatisfied`, cancellation before admission, resource
exhaustion, an unavailable executor, malformed artifact, or implementation
defect. Once durability may have been crossed, loss of a response can no
longer be reported as definitely uncommitted.

There is no canonical client-controlled `begin -> arbitrary work -> commit`
surface. A transaction program cannot read ambient clock, entropy, filesystem,
network, process environment, or external services. Required time, randomness,
authority, and prior evidence enter as typed recorded input.

The native engine admits writes in a deterministic order. Read snapshots,
query kernels, batching, and rebuild work may run concurrently without
exposing write races. Parallel or optimistic write evaluation is an internal
replacement only when measured workload evidence justifies it and the public
transaction contract remains unchanged.

Explicitly mergeable state must name a bounded commutative, associative, and
idempotent algebra with its identity, causality, retention, and conformance
laws. Uniqueness, balance, authorization, and referential constraints never
silently weaken into conflict-resolution semantics.

## Keep external effects outside the commit

A transaction may atomically retain an outbox intent or workflow wakeup with
application state. It cannot atomically commit a carrier request, payment,
email, object-store write, or other external system.

Execution or workflow code performs that effect after the Data commit, retains
the exact Authority and recovery evidence, and reconciles an unknown outcome
before retry. One Database never claims global exactly-once delivery.

## Evolve meaning without confusing storage

One Database keeps three coordinates independent:

1. the Contracts-owned semantic schema revision;
2. the schema and codec revision under which a value entered commit authority;
3. the Data-owned physical layout revision.

Stored values retain stable field identities and their accepted schema and
codec. An optional field, defined default, admitted widening, or other
Contracts-proven total conversion is read at the requested revision through an
exact projection. Existing bytes need no blocking DDL, table rewrite,
migration script, dual application path, or hidden request-time mutation.

A breaking change to type, identity, key, requiredness, constraint,
classification, or meaning is a governed resumable projection:

```text
exact source snapshot
  -> typed transform
  -> target materialization
  -> follow journal changes from the source watermark
  -> validate constraints and lineage
  -> fence old writers
  -> select the target revision
  -> retain the rollback window
  -> policy-governed cleanup
```

Source and target remain truthful about schema and freshness while they
coexist. Cutover and rollback are forward operations through ordinary `plan ->
apply -> inspect`; there is no `one migrate` command or permanent old-schema
reader.

System time is present for every admitted value. Valid time exists only when
the owning schema declares its business meaning and correction rules. The
engine never guesses business-effective time from arrival time.

## Query current, temporal, and live state

Generated SDKs expose one typed query meaning across read modes:

```rust
let current = database
    .query::<OpenOrders>(args.clone(), ReadPoint::LatestCommitted)
    .await?;

let previous = database
    .query::<OpenOrders>(args.clone(), ReadPoint::SystemAsOf(commit))
    .await?;

let changes = database
    .subscribe::<OpenOrders>(args, SubscriptionStart::SnapshotThenChanges)
    .await?;
```

A query carries continuing identity and exact revision, input and output
schemas, finite arguments and bounds, authority and visibility scope, snapshot
or temporal coordinate, ordering, determinism, and permitted loss. Planning
and Build compile it to a bounded physical kernel. Explain output reports the
selected projections, conversions, estimated and observed bounds, layouts,
watermarks, freshness, lineage, spill, and cost.

The bounded operator set grows only from selected application queries: exact
key and ordered range; filter, project, sort, and limit; secondary-index lookup
and constraints; then justified joins, aggregates, temporal predicates, and
incremental maintenance. SQL is an optional external adapter and never defines
canonical nullability, temporal, transaction, query, or authority semantics.

## Subscribe without an unclassified gap

A subscription reads an exact snapshot and establishes a barrier in the same
commit sequence before delivering later changes. Any permitted duplicate has
stable commit and change identities and is labelled by the contract. A
subscriber that falls behind retained journal history receives a resnapshot
requirement.

The same bounded delta algebra drives query dependencies, coherent caches,
incremental views, and subscriptions. At the same snapshot and scope, full
query evaluation and a maintained view produce the same canonical result.
Cache identity includes query revision, arguments, schema, snapshot or
freshness policy, authority and visibility scope, conversion set, and physical
plan, so identical query bytes cannot leak data across principals or tenants.

## Recover and operate within finite resources

Media declarations include atomic-write unit, alignment, flush and barrier
behavior, persistence class, capacity, discard, and corruption assumptions.
Journal frames bind store and generation identity, logical address, commit
sequence, previous-frame commitment, payload schema, and encryption metadata.
Recovery distinguishes a truncated tail, corrupt range, stale or misdirected
media, lost durability window, and unavailable key domain.

Backups are proven by clean independent restore. Point-in-time recovery,
repair, compaction, rolling physical-format upgrades, retention, erasure, legal
hold, and key retirement retain exact authority, lineage, resource, and
inspection evidence.

Memory, file descriptors, journal space, query batches, spill, subscriptions,
projection work, compaction, and backup all have finite Resources-owned
budgets. Cancellation, overload, exhaustion, and deadline outcomes state exact
progress certainty; background analytics or rebuild work cannot indefinitely
starve foreground transaction admission.

## Select and inspect the provider

Review the native provider beside every other eligible realization:

```console
one select provider --root OrdersApi --for one.data#Transactional@1
one inspect root:OrdersApi --subject data
```

Planning may select One Database as the canonical Data realization only when
its exact requirements and admitted evidence satisfy that root. SQLite and
PostgreSQL remain available when explicitly selected and useful. Replacing a
stateful provider is a planned data movement, validation, fencing, recovery,
and cleanup operation—not a runtime toggle.

See [data and state](/one/model/data),
[data-intensive systems](/one/guides/data-systems), and
[providers and adapters](/one/platform/providers).