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:

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:

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:

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, data-intensive systems, and providers and adapters.