One process, inward-pointing dependencies.
Every arrow is an allowed caller-to-dependency direction. Adapters sit at the rim; behavior owners sit inside; the Storage Kernel is the deepest module and knows nothing about protocols, query syntax, or providers. Cycles are a design failure.
Five ways to run one executable.
Modes are mutually exclusive. They are never hidden inside one process and never required to coexist.
positron servecomposes and runs the database.positron operatorcomposes and runs the Kubernetes reconciler.- Online CLIcalls the public or Control Listener interfaces.
- Offline CLIacquires exclusive storage ownership and composes only the read-only or explicitly mutating workflow it requires.
positron release verifycomposes offline release-trust verification and does not open database state.
Twenty deep modules. One owner each.
Every module states the interface callers learn and the complexity its implementation hides. Deleting any deep module would smear its rules across every caller — that is the depth test each one passes.
Foundation 2 modules
Domain Typesvalidated shared identities and value types
Callers learn
Tenant ID, principal, scope, signal kind, shard, commit position, typed telemetry values, and time with provenance — constructible only in valid states.
Implementation hides
Construction checks, type preservation, namespace separation, and impossible states. No I/O, no wire decoding, no utility collection.
Configurationresolve, validate, plan, publish one Effective Configuration
Callers learn
Resolve sources into a redacted typed candidate; diff it into a typed application plan; publish per declared mutability. Callers receive only their own typed section.
Implementation hides
Source precedence, schema generation, secrecy, live-reload vs drain vs restart classification, and semantic diff. No other module reads env vars or TOML.
Runtime 4 modules
Application Runtimerun the database, return one truthful exit outcome
Callers learn
serve(modules, host) → ExitOutcome. The composition root assembles modules once; nothing fetches dependencies from ambient state.
Implementation hides
Process phases, recovery ordering, listener activation, drain, and dependency retry. Readiness is a derived fact, not a flag.
Instance Bootstrapinitialize, resume, or claim one provably classified instance
Callers learn
classify, initialize (provably empty roots only), and one-time claim of the initial system-administrator credential.
Implementation hides
Empty-root proof, transactional initialization, instance and key identity, the default tenant, and atomic destruction of claim material. Ambiguous roots never initialize.
Listener Setactivate, replace, and drain complete listener generations
Callers learn
A generation carries complete per-listener profiles for control, operations, api, otlp-grpc, otlp-http, and loki-push. Partial mutation is impossible.
Implementation hides
TLS, mTLS, proxy trust, and pre-authentication Connection Admission: sockets, handshakes, headers, bodies, decompression, streams, and descriptors — all bounded before identity exists.
Operational Statetyped facts in, bounded health and telemetry out
Callers learn
Closed event and status types. Owning modules never construct metric labels or free-form diagnostics.
Implementation hides
Redaction, stable names, bounded cardinality, liveness and readiness derivation, and the self-export guard.
Edge 3 modules
Identity & Attributioncredential + intent → one authorized context
Callers learn
attribute(credential, intent, hints) binds exactly one principal, one scope and — for data-plane work — exactly one tenant. The result is an unforgeable typed input.
Implementation hides
Salted-hash verification, revocation, immutable identity snapshots, lifecycle checks, alias validation, trusted proxies, and constant-shape failures. Admin contexts cannot become tenant data contexts.
Public Interfacegenerated native request and result semantics
Callers learn
Generated servers and clients from api/positron/v1, plus authorization, idempotency, budget, completion, and retry semantics. Wire types stop at this seam.
Implementation hides
gRPC and HTTP/JSON mapping, OpenAPI generation, stable error mapping, capability negotiation, and schema-digest embedding. SDKs in six languages share this one definition.
Receiver Adaptersdecode one bounded, attributed protocol request
Callers learn
decode(AttributedBoundedPayload) → NativeBatch and render(IngestOutcome). The input type proves admission and attribution already happened.
Implementation hides
OTLP and Loki protocol mapping and partial-result rules. Vendor fields can become native values or validated hints — never tenant selection.
Data plane 4 modules
Ingestaccept one attributed native batch → one typed outcome
Callers learn
accept(batch) → IngestOutcome: committed, retryable, and permanently rejected records reported separately. No claim of atomicity or exactly-once.
Implementation hides
The exact pipeline: policy snapshot, validation, admission grouping by tenant + store + shard, reservations, block preparation, durable commit, acknowledgment.
Signal Storesprepare, scan, and optimize one signal's data
Callers learn
The SignalStore seam: prepare canonical store blocks, scan typed plan fragments, plan_maintenance. Two real adapters: Log Store and Trace Store.
Implementation hides
Log: full-text and attribute indexes, typed overflow, attribute promotion. Trace: span observations, consolidation, conflicts, summaries, quiescence. No Release 1 metric or profile store exists.
Querystart, resume, tail, or export one authorized query
Callers learn
Four operations with different completion contracts. Streams emit deterministic result batches and exactly one terminal status. Complete is a fact, never an inferred absence of error.
Implementation hides
Pipeline and SQL parsing into one typed logical plan, costing, budgets, snapshots, leases, cross-signal correlation, cursors, and result digests.
Storage Kernelcommit, pin, publish, schedule, inspect — through narrow handles
Callers learn
Four capability handles: KernelIngest, KernelQuery, KernelControl, KernelInspect. No caller receives raw volume, key, or catalog-marker access.
Implementation hides
Eight internal modules — detailed in the next section.
Control plane 4 modules
Administration & Governanceexecute or inspect one authorized administrative intent
Callers learn
execute(context, command) and inspect — with idempotency keys, expected generations, and durable operation IDs for long work.
Implementation hides
Canonical digests, tenant and principal state machines, audit intent, and the durable-operation handler seam: backup, restore, purge, key work, verification, migration, upgrade.
Backup & Restorestart or inspect backup, restore, and repository workflows
Callers learn
Workflow creation and inspection only; nobody invokes provider methods directly. A backup succeeds only after complete verification and independent key-recovery readiness.
Implementation hides
The Repository port — identify, ranged reads, put-if-absent, resumable upload, compare-and-swap head, observable delete. Listing is deliberately absent as a correctness primitive.
Upgrade & Migrationplan, run, or inspect one supported version transition
Callers learn
An authorized target release yields a preflight plan or a stable operation ID.
Implementation hides
Artifact verification, compatibility and migration-graph checks, drain, the quiescent upgrade snapshot, copy-on-write transformation, and atomic format-epoch publication. Failure before publication leaves the previous version current.
Diagnosticsproduce one Doctor Report or Support Bundle
Callers learn
doctor never mutates; offline doctor takes exclusive read-only ownership; bundles use a typed closed allowlist.
Implementation hides
Pseudonymization, declared truncation, encryption, signing — and a redaction report that lists every omission. Unknown fields are excluded, not heuristically scrubbed.
Ecosystem & trust 3 modules
Positron Operatorreconcile Kubernetes desired state through public calls
Callers learn
run for a configured scope. Reconciliation separates observation, pure plan construction, and effect application, so plans are testable without a cluster.
Implementation hides
Watches, lease leadership, apply ownership, finalizers, status. It never opens a data volume, never mounts a live PVC elsewhere, and never infers database completion from Kubernetes objects.
Release Trustverify one artifact set against an installed trust root
Callers learn
verify_release(artifacts, trust) → report — fully offline.
Implementation hides
Manifest authentication, revocation, checksums, schema digests, compatibility identity, and reproducible-payload comparison.
Qualification Harnessexecute one qualification cell, retain its evidence
Callers learn
The exact built artifact and its public interfaces are the test subject; targets are expanded before execution.
Implementation hides
Environment capture and immutable pass-and-fail evidence. A private function call cannot qualify an external protocol, provider, or recovery claim.
The kernel: one implementation, narrow handles.
Callers get capabilities, not access. The four handles are created together and handed out narrowly; the eight internal modules below them are private.
Not ports on purpose: the Primary Data Volume, Ingest, Query,
the Catalog Writer, the Resource Governor, and the Maintenance
Coordinator are concrete. A StorageBackend trait would
falsely imply object-store or multi-writer equivalence; a private
limiter or scheduler would fork the source of truth.
Encryption with a chain of custody.
Every persistent byte lives in an independently authenticated AES-256-GCM frame. Keys form a wrap-only hierarchy: no caller ever receives a root or tenant key, and every envelope is bound to its context by digest.
Canonical flows.
Six sequences define how work moves through the system. Each ends in a guarantee, not a hope.
- The Listener Set admits a bounded protocol request.
- Identity binds credential and intent to one tenant context.
- The Receiver Adapter decodes an attributed, bounded payload into a native batch.
- Ingest snapshots one policy generation, validates, and splits records into admission groups by tenant, store, and shard.
- The Resource Governor reserves memory, queue slots, and disk headroom per group.
- The owning Signal Store prepares canonical store blocks.
- The Storage Kernel commits each group durably and returns an authenticated receipt.
- The adapter renders committed, retryable, and rejected outcomes in protocol terms.
The commit receipt is the only acknowledgment truth. Queue acceptance, encoding, unsynchronized writes, and sealing prove nothing.
- Identity returns a tenant query context.
- The public adapter converts wire input into one native request.
- Pipeline or SQL parses into the same typed logical plan.
- Planning applies mandatory time bounds, estimates cost, and obtains a query-budget reservation.
- The kernel pins the catalog generation and each store's committed position — the query snapshot.
- Signal stores build physical scans over verified snapshot readers.
- Execution streams a typed header, deterministic result batches, and exactly one terminal status.
- Resume reauthenticates and continues the same snapshot and cumulative budget; tail bridges to per-shard committed positions.
No query path sees unverified plaintext, crosses tenants, changes snapshots on resume, or reports a truncated result as complete. Lagging tail consumers are disconnected explicitly, never silently.
- A caller submits a command with an idempotency key and expected generation.
- Administration canonicalizes, authorizes, and validates the transition.
- It hands the Catalog Writer a proposal plus audit intent.
- The writer persists immutable objects, then reserves a position and writes a prepared audit entry.
- It writes and synchronizes the catalog commit record.
- One atomic authenticated marker publishes the new generation and the audit entry together.
Governance state and its audit evidence publish jointly or not at all. If audit preparation is unavailable, the mutation does not publish. A prepared entry is never visible alone.
- Administration durably creates the operation; the coordinator reserves work and rolls active segments.
- Backup pins one complete catalog generation.
- The repository adapter transfers immutable, checksum-addressed encrypted objects, resuming interrupted uploads.
- The signed snapshot manifest and registry generation publish through compare-and-swap.
- Verification proves objects, catalog, signatures, registry head, key provider, and independent recovery readiness — only then Succeeded.
- Restore opens only an empty target, verifies the chain, applies purge tombstones before any tenant is visible, and publishes atomically.
A backup that cannot prove independent key recovery is not a backup. Restore has no merge and no in-place overwrite path.
- Administration binds explicit tenant ID, confirmation, generation, and idempotency.
- The tenant enters Purging; admission stops and existing work drains or terminates.
- Active segments roll; live manifests become unreachable.
- Data Protection evicts cached keys and removes live tenant-KEK envelopes.
- Every registered repository receives a signed purge tombstone and a new registry head with no reachable tenant envelope.
- All managed recovery paths are verified; remaining key material is destroyed; the tenant becomes Purged.
Purge is cryptographic, not cosmetic. An unavailable or immutability-locked repository leaves the operation pending rather than pretending completion. Tenant ID and slug are never reused.
- The first termination signal enters Draining and fails readiness.
- New data and mutation admission closes.
- Admitted durability work completes using retained reservations.
- Bounded reads drain; tails end with safe cursors; resumable operations checkpoint.
- Active segments seal; final frontiers and catalog state publish.
- Governance checkpoints and the graceful shutdown record is written.
- Cached keys zeroize, ownership releases, and the process exits successfully.
A second signal or an expired orchestrator deadline exits crash-safe and nonzero — it never fabricates graceful completion.
Lifecycle is a state machine, twice.
The process and each tenant move through explicit durable states. Ambiguity fences; nothing limps.
An acyclic workspace, enforced.
Fifteen crates, dependencies pointing strictly inward. The graph below is machine-checked on every pull request against a committed edge allowlist — a forbidden edge fails the build.
Layout rules with teeth: no common or utils crate, no
forwarding crates, no wire types in domain, no provider SDK outside
its adapter-owning module, no storage path outside kernel — and no
Release 1 crate or feature flag for deferred signals or clustering.
Traits only where variation is real.
A trait is permitted only at a justified varying seam with at least two real adapters. These are the Release 1 seams — everything else is deliberately concrete.
| Seam | Adapters | Why it is real |
|---|---|---|
| Public transport | gRPC · HTTP/JSON · conformance client | Multiple transports exercise one native interface |
| Receiver Adapter | OTLP grpc · OTLP http (pb/json) · Loki push · Loki OTLP | Protocol semantics genuinely vary |
| Signal Store | Log Store · Trace Store | Physical encoding and query behavior vary by signal |
| Key Provider | local · AWS · GCP · Azure · Vault · OpenBao · KMIP | Identity, credentials, outages, and wrapping vary |
| Repository | local · S3 · S3-compatible · GCS · Azure Blob | Conditional publication, uploads, deletion vary |
| Durable Operation | backup · restore · purge · key · verify · migrate · upgrade | Phases and irreversible boundaries vary |
| Maintenance Task | segment · compaction · retention · scrub · schema · key · … | Task phases vary; admission stays centralized |
| Catalog publication | filesystem · test-only fault adapter | Crash points must be deterministic; consensus reuses the seam |
| Crypto Backend | Rust backend · known-answer/fault adapter | One replaceable cryptographic seam with cross-platform proof |
| Clock & entropy | host · deterministic test adapters | Safety logic needs reproducible time and nonce tests |
| Kubernetes effects | client · deterministic fake · live conformance cluster | Reconciliation plans must survive outages and retries |
Invariants with enforcement, not intentions.
Forty-two mandatory invariants across nine families, each mapped one-to-one to an automated quality gate. A green gate is evidence for the exact revision; review never substitutes for a missing gate.
- ARC ×5
- contracts, single ownership, deep modules, boundary types, commit-then-publish
- RUST ×4
- Rust 2024, pinned toolchain, locked builds, clean lints, owned dependencies
- SAFE ×4
- unsafe forbidden by default, hard limits before use, verify before decode
- CON ×5
- owned tasks, bounded queues, explicit deadlines, no blocking on async workers
- ERR ×4
- closed typed outcomes, no panics in production paths, fail closed
- SEC ×5
- threat models first, attribution before decoding, no ambient authority, SBOM + provenance
- DOC ×4
- documented invariants, one canonical source, ADR before contract change
- TEST ×7
- adversarial tests at the lowest interface, fault injection at every publication point, frozen coverage and mutation baselines
- PERF ×4
- declared budgets, preregistered benchmarks, soak proof on the release artifact
Evidence-gated development: one Rust gate runner
(cargo xtask quality) drives every check from committed
registries. A retry is a new attempt and cannot erase the first
result; a timeout is a failure, not a skip; local evidence is
deliberately ineligible for merge.
The road to Release 1.
Vertical slices, in order. Each milestone must work end to end before the surface broadens, and later work may not bypass an earlier interface to look faster.
-
M0
Foundation in progress
Workspace, domain types, configuration skeleton, canonical public interface, stable errors, target registry, fault harness — and the quality-gate machinery that everything else must pass.
-
M1
First durable vertical
Runtime startup, instance bootstrap, local data protection, the primary data volume, catalog, resource governor, segment ledger, a minimal OTLP log receiver, ingest, minimal log store and query. M1 must prove acknowledged-data preservation before anything broadens.
-
M2
Complete log store
Full OTLP and Loki adapters, ingest policy, schema bounds, search, live tail, retention, and compaction.
-
M3
Complete trace store
Span observation consolidation, summaries, quiescence, structural query, and log–trace correlation.
-
M4
Full control plane
Identity, administration, tenant lifecycle, audit, durable operations, time safety, maintenance, integrity, process lifecycle, operational state, and diagnostics.
-
M5
Providers and platforms
External key providers, repository adapters, backup, restore, purge, upgrade, all distributions, the operator, Kubernetes, Grafana, and the SDK release set.
-
M6
Qualification and release
The complete qualification matrix, performance and soak evidence, reproducibility, publication, and independent verification.