= Target architecture: the layers
:toc: macro
Part of xref:index.adoc[the target architecture]. The three-layer plan, the
dependency DAG, the six shipped `metis` primitives with the reasoning that
ordered them, and the trajectory the sixth (the causal store algebra) grew
into: the store family and its maintained reads (the section at the end
points at the documents that own it).
toc::[]
== Layered architecture
The crate is organized as three layers. All three now have shipping code; the
`metis` layer holds the causal materials (a version vector with both lattice operations, the
order `Ideal`, a sender-side event producer, a cross-node stability tracker, and an exact
have-set), the wire-codec and gate/capacity seams those materials expose, and,
since the exploration epoch, the causal store family the sixth primitive
seeded (`Dotted<S>` over the open `DotStore` axis, composing with `DotSet` and
its sibling instances through the sequence store and its movement, annotation,
and node stages, while the delivery and stability primitives stand beside the
family sharing the same dot vocabulary; the trajectory section below points at
the owning charters).
[cols="1,2,3,1",options="header"]
|===
| Layer | Greek frame | Responsibility | Status
| `kairos`
| kairos / chronos
| The causal stamp and the clock that mints it. The 128-bit `Kairos` timestamp,
the lock-free `Clock`, and the `TimeSource` / `Backoff` seams.
| Implemented
| `chronos`
| chronos
| Concrete, production-grade time sources, kept separate from logical-clock
policy: a wall-clock `SystemTimeSource` and a per-process `MonotonicTimeSource`,
under `std`. The `no_std` test sources stay in `kairos` (the auto-ticking
`TickCounter` and the caller-advanced `VirtualTimeSource`, S13); only a `std`-only
deadline source would belong here, and none is needed yet.
| Implemented (std sources)
| `metis`
| mētis
| The decision layer. Primitives that _consume_ stamps to reason about
causality: delivery buffers (order ideals), version and dotted-version vectors, conflict
detection, and CRDT-style merge for event-sourced state.
| Implemented (version vector, xref:../prd/0004-metis-causal-ordering.adoc[PRD 0004];
causal-order delivery buffer, xref:../prd/0005-metis-causal-order-buffer.adoc[PRD 0005], S14b;
sender-side event producer, xref:../prd/0006-metis-event-producer.adoc[PRD 0006], S15b;
canonical wire codec, xref:../prd/0007-metis-event-wire-encoding.adoc[PRD 0007], S16b;
generic `Gate` seam with `Causal` and `Fifo`,
xref:../prd/0009-metis-ideal-gate-generic.adoc[PRD 0009], S27b;
bounded backlog mechanism, S30; causal-stability watermark, `VersionVector::meet` plus the
roster-fixed `Stability` tracker,
xref:../prd/0011-metis-causal-stability-watermark.adoc[PRD 0011], S78; exact have-set,
`DotSet`, xref:../prd/0012-metis-dot-set-exact-have-set.adoc[PRD 0012], S83; and the causal
store family those materials composed into, from the `Dotted` kernel,
xref:../prd/0015-metis-causal-store-algebra.adoc[PRD 0015], S96, through the `Rhapsody`
sequence store, xref:../prd/0017-metis-rhapsody-sequence-store.adoc[PRD 0017], and the
structured-document stages of xref:../prd/0019-metis-structured-document-horizon.adoc[PRD
0019]: the `Node` kind closure, the `Scholia` mark store, and the `Metatheses` move machine
with its maintained `Recension` read, PRDs 0020 to 0022, with the run-compressed snapshot
codec, PRD 0023, beside them). The _deinotēs_
resolver stays caller-gated, the layer's one deliberately unbuilt dimension.
|===
The dependency graph is a DAG rooted at `kairos`. `kairos` owns the `Kairos`
value and the `TimeSource` / `Backoff` seams (the ports) and depends only on the
traits it defines, never on another module. `chronos` is an adapter: it
implements the `kairos`-owned `TimeSource` port with concrete OS sources, so it
depends on `kairos` for the trait while `kairos`'s core logic depends only on the
abstraction, never on a concrete source. This is dependency inversion: the policy
(`kairos`) defines the port; the detail (`chronos`) plugs into it. `metis` likewise
depends on `kairos` (the `Kairos` stamp and the `station_id` space) and may later
consume `chronos` sources. Nothing depends on `metis`, and `kairos` depends on
nothing above it.
`metis`'s first primitive is a *version vector*
(xref:../prd/0004-metis-causal-ordering.adoc[PRD 0004], implemented in S10b). The
choice follows from what a `Kairos` cannot do. The stamp is an HLC scalar, so its
total order _respects_ causality (`after` and successive `now` always increase) but
cannot _detect_ concurrency: two stamps may compare under `Ord` yet be concurrent,
the order an artifact of the linearization. A version vector recovers exactly that
lost distinction (ordered versus concurrent) and is the lattice every
richer `metis` primitive (delivery buffer, stability watermark, conflict detection,
CRDT merge) builds on: a join-semilattice from S10b, completed to a distributive
lattice when S78 carved the meet
(xref:../prd/0011-metis-causal-stability-watermark.adoc[PRD 0011]). It is keyed by the same `station_id` space as `Kairos`, so the layers interlock
through identity without the vector redefining the stamp. The choice was a
public-contract decision, signed off before implementation (todos S10).
The second primitive is a *delivery buffer* (the order `Ideal`)
(xref:../prd/0005-metis-causal-order-buffer.adoc[PRD 0005], implemented in S14b). It is the
bridge where the vector and the stamp finally interlock: each event pairs its `Kairos`
stamp with a dependency version vector, and the buffer gates release on vector
stability (it has delivered everything the event depended on) while ordering the stable,
mutually concurrent frontier by `Kairos`. Stability is the question a scalar cannot
answer and the vector can, which is why the buffer is built on the vector rather than
beside it. The choice was a public-contract decision, signed off before implementation
(todos S14).
The buffer is the *receive* half of causal broadcast. The *send* half is the `Producer`
(xref:../prd/0006-metis-event-producer.adoc[PRD 0006], implemented in S15b): it mints events
(count its own event, snapshot its delivered-knowledge as the event's dependency vector,
mint a `Kairos` after everything observed), the BSS send rule and the inverse of the
buffer's gate. It composes with the buffer rather than owning it, so the two stay
orthogonal materials; together they are the end-to-end loop the layer was chartered for.
S15b also retired the S14b valid-history test generator's inline send step in favor of the
real `Producer`, so there is now one implementation of the send rule, exercised by both the
producer and buffer property suites.
The layer perceives concurrency (the version vector) and delivers it safely (the buffer), but
the buffer applies no resolution to a genuinely concurrent frontier:
`next_deliverable` flattens the frontier to `Kairos`-minimal order, a correct delivery
linearization but a silent shrug at the level of meaning. The *deinotēs* dimension
(xref:../prd/0008-metis-deinotes-concurrency-resolution.adoc[PRD 0008], chartered in S23a) names
that gap: a caller-defined, typed dimension for resolving concurrency (keep siblings, pick a
winner, fold a join, or distrust a lying peer), the decision-layer mirror of the kairotic and
the framing that unifies the "conflict detection" and "CRDT-style merge" this row lists. It is
the crate's most framework-shaped direction, so it is held more deliberately than any other
slice: design only, held for sign-off _and_ gated on a concrete caller drawing the boundary
(the kairotic precedent is double-edged, `pinax` opts out of it). No resolver code exists; the
one caller-owned step that did land is the frontier's read-only exposure as the *antichain*
(`Ideal::frontier`, S25), the material such resolution consumes.
The buffer's _other_ axis, the *gate* that decides stability, is a caller-parameterized seam
(xref:../prd/0009-metis-ideal-gate-generic.adoc[PRD 0009], implemented in S27b): the same `Ideal`
machine over a `Gate` trait, with two shipped gates as *peers*, the causal `VersionVector` rule
(`Causal`, aliased `CausalIdeal`) and a scalar per-source FIFO watermark (`Fifo`, `Dep = u64`,
aliased `FifoIdeal`). The gate is *named* at every buffer, never a silent default, so a non-causal
gate (a retrodictive reading of the same data, say) is a peer of `Causal` rather than awkward
beside it. The gate sits _below_ the frontier, the resolver _above_; both are caller dimensions,
and the `Kairos`-minimal linearization is the floor `Ideal` keeps between them. The motivating
non-causal participation watermark stays a caller's gate (consumed as a fold); a test-only `Quorum`
proves the seam carries the threshold shape.
The layer's fourth primitive is the *causal-stability watermark*
(xref:../prd/0011-metis-causal-stability-watermark.adoc[PRD 0011], S78): `VersionVector::meet`, the
greatest lower bound that completes the vector's lattice, and the roster-fixed `Stability`
tracker, whose `watermark()` is the n-ary meet of every declared member's delivered cut, the
greatest cut all have passed, hence delivered everywhere, hence safe to forget. It is the
retention face of the bounded-resources boundary
(xref:boundaries.adoc#_capability_and_effect_boundaries[the capability boundaries]) and the
model instance of the crate's
division of labor: maximal capability (know exactly what may be forgotten), zero policy (forget
nothing). The roster is a caller argument, non-roster reporters are refused with a typed error,
and reclamation, membership change, and report transport stay caller-side.
The layer's fifth primitive is the *exact have-set*
(xref:../prd/0012-metis-dot-set-exact-have-set.adoc[PRD 0012], S83, owner ruling R-7): `DotSet`,
recording per station exactly which dots have been received, however disordered the arrival,
the receipt-side half of this row's chartered "dotted-version vectors" (the production-side
half fired in S96, below). It exists because the watermark's input contract (PRD
0011 R8: a report is a gap-free *cut claim*) is unverifiable from a bare vector and, under
out-of-order receipt, was previously unconstructible: an upper bound of a cut and a cut are
the same type, and meeting upper bounds fails in the unrecoverable direction. The have-set's
`floor()` (the greatest gap-free prefix it contains, its lattice interior) is a genuine cut by
construction, so the honest report becomes a read; `high_water()` is the liveness bound the
report must never be; `holes()` names the difference, the repair fetch list. Pure join
material (set union), no policy, no wire frame, basis mapping caller-side; held in reserve
until a reordering-receipt consumer fires (both field consumers' cuts are gap-free by
construction today).
The layer's sixth primitive is the *causal store algebra*
(xref:../prd/0015-metis-causal-store-algebra.adoc[PRD 0015], S96, owner ruling R-12): the
production side of the chartered "dotted-version vectors", built ahead of its named
prospective consumer (a multiplayer editor) under an owner directive. `Dotted<S>` brackets a
store of dot-tagged content with the causal context of everything ever seen; its merge, the
pair's only write, runs the *survivor law* (a dot survives iff no side that saw it has
dropped it), which is replicated removal without tombstones, resurrection, or lost concurrent
writes. `DotStore` is the layer's second open axis after the `Gate`: minerva ships the
dot-shaped instances (`DotSet` as presence, `DotMap<K, S>` as caller-keyed composition) and
the boundary is redrawn by R-12 at *payloads and application semantics*: value-carrying
stores are caller implementations of the axis, named CRDT types are recipes rather than
exports, add-wins versus remove-wins is which deltas a caller constructs, and dot assignment
(`next_dot`) reads only the never-forgetting context (the doomed-dot trap made
unrepresentable).
== The trajectory past the sixth primitive, in three movements
The narrative above deliberately stops where the layer's *causal-broadcast*
era ended, because from there the growth is owned by other documents and
re-deriving it here would only drift. The shape, concisely, with the owners:
. *The sixth primitive seeded a foundation* (S96 to S127): the causal
store algebra grew into the store family, one kernel (`Dotted<S>`, the
survivor law carried once) with everything else an instance or a read of
the open `DotStore` axis (`DotSet` as presence, `DotMap` and `DotFun` as
composition and payload, `Rhapsody` as sequence), the sequence store
gaining its canonical wire frame (S117) and sided anchor (S127) as the
foundation matured; the delivery and stability primitives stand beside
the family, sharing the dot and station vocabulary rather than composing
into it. Owned by
xref:../crdt-vision.adoc[the CRDT vision], whose witness ledger records
the traps closed by construction rather than discipline.
. *The foundation grew structure* (S184 to S203): the structured-document
stages of xref:../prd/0019-metis-structured-document-horizon.adoc[PRD
0019], each through its own gate: the `Node` kind closure fired by stage
A's recorded probe evidence (PRD 0020), the `Scholia` mark store and the
`Metatheses` move machine each fired by the named consumer's filed ask
or field-pinned defect (PRDs 0021 and 0022), ending in the maintained
recension (PRD 0022 R7, S203); the snapshot codec (PRD 0023) shipped
beside them on the recorded bootstrap numbers. The consumer record lives
in xref:../consumer-guide.adoc[the consumer guide].
. *The representation went honest at scale*: the substructure program
(arcs 10 and 11 of the vision, S191 to S202) re-realized every derived
plane as a cost shell under one law per shell (exact agreement with its
contract form), the identity plane speaking the snapshot wire's own
maximal chain-run factoring and the other planes coalescing on the same
honest-traffic runs, taking the whole ordering state to roughly 6 bytes
per character at 65k chars (about 393 KiB, where the S194 identity plane
alone had stood at 68 bytes per character); the maintained collation's
own residuals were then cured in the same spirit (S203 to S205: the
region splice making replay fragment-priced, the paged possession pass
making the visibility comparison page-priced, with the linear
surviving-testimony record scan the residual PRD 0022 still records).
Owned by xref:../metis-shell-discipline.adoc[the shell-discipline note],
whose table is the shipped-instances index.
The constant across all three movements is the pull, not the push: every
firing was a recorded measurement, a field defect, or a filed ask, read
against a standing ruling (the R-6 discretion test, then the vision's
four-sentence standard). The layer's next growth is expected through the
same gate, and the live pressures are always the tracker's posture
paragraph (https://github.com/OwlRoute/minerva/blob/main/todos.adoc[`todos.adoc`],
repository only), never this file.