4. Architecture

Repository: bloque-app/aledgent
Commit: 5ca6b8a
Version: 0.4.27
Status: draft
Rendered: 2026-10-17T19:30:18Z
Source: SPEC.md, last changed in 5ca6b8a

4.1 Components

flowchart TB
    subgraph H["Identity holders"]
        H1["People"] ~~~ H2["Organisations"] ~~~ H3["Agents"]
    end
    subgraph A["aledgent — the ledger of record"]
        A1["Command surface"] --> A3["Operation lifecycle"] --> A4["Book — confidential double-entry"]
        A2["Query surface"] ~~~ A5["Observation & evidence"]
        A6["Disclosure & proof"] ~~~ A7["Anchoring"]
    end
    S["Settlement adapter — custody-isolated"]
    L["Settlement layer"]
    V["Verifiers"]
    H --> A1
    H --> A2
    A5 --> A3
    A3 --> S
    S --> A5
    S --> L
    A7 --> L
    A6 -. "disclosures, checked against anchors" .-> V
    L -. "public record" .-> V

Three rules define the architecture. A fourth keeps it deployable:

REQ-AR-1 Identity holders call aledgent. aledgent MUST NOT call a holder back to decide an outcome. Every operation MUST reach a terminal state even when every caller is unavailable (REQ-EV-5).

REQ-AR-2 The settlement adapter submits evidence and executes instructions. It MUST NOT write the book and MUST NOT declare an outcome. aledgent derives every outcome from evidence it recorded (INV-11).

REQ-AR-3 Key material for the settlement layer MUST NOT reside in the component that holds the book (NFR-8). If one process holds both, nothing else in the design can reduce the blast radius.

REQ-AR-7 The component that receives commands MUST be deployable and restartable independently of the component that decides them. It MUST NOT lose a received command while the deciding component is unavailable (REQ-CS-7, NFR-5).

4.2 Responsibility allocation

The table below is normative. A capability MUST NOT be implemented at any layer other than the one named.

Capability	Where	Rationale
Existence of an identity and its accounts: the authoritative registry	aledgent	Everything else attaches to it (`REQ-ID-7`)
Opening identities and accounts	aledgent. An identity only under the identities principal’s authority; an account under that principal’s, or under the authority of the identity that will own it	The operator is the identities principal unless another principal plays that role (`REQ-ID-6`)
Which identity owns an account	aledgent	Ownership is a ledger fact
Who may act on an account, and within what limits	aledgent	Authority decides whether value moves
Balances of every balance kind, in every asset	aledgent	The only authoritative copy
Every entry, its order, and its immutability	aledgent	The book is the record
Reservation, capture, release	aledgent	This is where value stops being spendable
Operation state, deadlines and outcomes	aledgent	The design exists to prevent splitting this from the book
Asset registry, identity and precision	aledgent	One registry. Precision lives in exactly one place
Deciding an external leg’s outcome from evidence	aledgent	A caller may state what it saw, never what happened
Producing disclosures and proofs	aledgent	Only the holder of the facts can attest them
Choosing what is anchored, and when	aledgent	Anchoring is a property of the book
Bearing settlement-layer costs	aledgent (as sponsor)	No identity holder holds or funds such a cost
Signing and submitting an external leg	Settlement adapter	Custody isolation
Observing the settlement layer and reporting coordinates	Settlement adapter	Needs network-specific knowledge
Public, unforgeable record of external value movement	Settlement layer	Needs a neutral third party
Public, unforgeable anchor of book state	Settlement layer	Same
How an account is presented, who a holder is as a legal person, whether they may transact, and prices and fees	The integrating party	Customer facts (§1.3)
Its own record of the identifiers of the identities and accounts it serves	The integrating party	It maps them to its customer facts. It has no standing on existence (`REQ-ID-6`)

Existence and who a holder is are two facts, with two authorities. aledgent is the authority for an identity’s existence: that it exists, its identifier, its kind and status, and the accounts it owns (REQ-ID-7). The integrating party is the authority for who that identity is as a person or an organisation, and whether it may transact. Each side keeps the identifiers; neither fact can be read from the other (REQ-PV-3).

4.3 Trust model — stated plainly

Question	Answer
Can the operator move a holder’s value?	In delegated custody, yes. That is what delegated custody means. In owned custody, no. `REQ-AU-5` limits it. `REQ-AU-7` makes every use of it traceable to who did it. `INV-20` makes it visible to the holder.
Can the operator change a recorded entry?	No. The book is append-only. A correction is a new, compensating posting, and that posting is itself an entry (`INV-2`).
Can the operator hide an entry from an account’s authority holders?	No. Whoever holds authority over an account sees every entry against it (`REQ-QR-4`).
Can the operator revise history after the fact?	Not undetectably. Anchors commit to book state. Anyone holding an earlier anchor can detect a revision of anchored history (`REQ-PR-4`). Between anchors, at most an hour apart (`REQ-PR-1`), a revision is not detectable.
Can the operator create value from nothing?	Not without it showing. For every asset, entries sum to zero across the whole book. Any issuance is an entry against the issuance counterparty (`INV-4`, `INV-5`). What the operator can do is issue, and the trial balance makes exactly that measurable.
Can the settlement adapter move value?	No. It can execute an instruction it was given and report what it saw. It cannot create, decide or settle (`INV-11`).
What can a verifier check?	Whatever a disclosure asserts, and nothing more. The check needs no further cooperation from aledgent (§7.E, `REQ-PV-6`).
What can a holder prove?	That they hold at least an amount. That a given operation occurred. That a given amount moved. Aggregate flow over a window. Each to a recipient they choose (`US-I2`).
What can the public see?	The existence and order of anchors. External value movements to and from aledgent, in aggregate. Not accounts, balances or counterparties, and not the amounts of internal movements (`REQ-PV-2`).
Who is the custodian?	In a single deployment, the operator, in both custody modes. Value sits in positions the operator controls on the settlement layer (`REQ-SL-5`). So a holder’s balance is a claim on the operator. Owned custody removes only the operator’s power to initiate. In a federation (§1.7, assumption 4), each deployment’s operator is custodian for its own holders. The operator that issues an asset is its issuer. It is not the custodian of value that other deployments hold.
Who can violate an invariant?	§9 names the enforcing layer for each. An invariant enforced by the store survives an application bug. One enforced by application code does not. `REQ-AR-4` forbids moving an invariant down to a weaker layer.

REQ-AR-4 Each invariant in §9 names the layer that enforces it. An implementation MUST NOT satisfy an invariant at a weaker layer than the one named. In particular, an invariant named as enforced by the store MUST NOT be downgraded to an application check. Any weakening is a specification amendment.

REQ-AR-5 A deployment MUST declare, in machine-readable form, which invariants of §9 it enforces and which it only attests. aledgent MUST show this as an assurance level on any disclosure it issues.

REQ-AR-6 The first release’s assurance level MUST declare every invariant at the layer §9’s V0 column names, or at a stronger one. Where the V0 column names a weaker layer than the target column, the difference is recorded by amendment, as REQ-AR-4 requires. At least, it MUST declare:

INV-1–INV-4, INV-7 and INV-12 as kernel- or store-enforced;
INV-15, INV-16, INV-20 and INV-22 as service-enforced;
every disclosure as a signed assertion (REQ-PR-6), until an independently checkable construction ships (DEF-3).

A later release MAY strengthen any entry. No release may weaken one without an amendment (REQ-AR-4).

Trade-off, stated plainly. aledgent stores balances instead of summing entries on every read. That is right at the volumes of §11. But it creates a failure class that a sum-on-read ledger cannot have: drift between a stored balance and the entries behind it. INV-6 requires the two to be provably equal. NFR-9 checks this continuously at zero tolerance. The alternative is a read that touches every entry of a large account, and that does not meet NFR-3.

4.4 Capability contracts

aledgent is built from exactly four external capabilities. Nothing in §5–§8 may require more than these. No requirement in this document names what supplies one.

(a) The ledger kernel

REQ-KER-1 The kernel MUST make an unbalanced posting impossible to represent. For every posting and every asset, the sum of debits MUST equal the sum of credits. A single-legged posting MUST NOT be expressible at all. A code path that rejects it is not enough.

REQ-KER-2 The kernel MUST support an atomically committed posting that spans more than two entries and more than one asset, balanced independently per asset.

REQ-KER-3 The kernel MUST be able to represent, per account and per asset, three kinds of value that are each separately readable and that sum to the total:

value that is available;
value that is reserved to one named operation;
value that is encumbered under a standing rule (§5.4).

Every movement among the three MUST be expressed as balanced entries in the book (INV-1). The three can be partitions of one account, or positions the account draws on. That is an implementation choice. Either MUST satisfy REQ-BA-1–REQ-BA-4.

REQ-KER-4 For accounts so designated, the kernel MUST enforce that no balance kind’s net is ever negative, at any instant and under any concurrency.

REQ-KER-5 The kernel MUST be append-only. It MUST NOT offer a way to change or delete a committed entry or posting. A correction MUST be a new posting.

REQ-KER-6 The kernel MUST refuse a posting it has already accepted, keyed on an identity the submitter supplies. The refusal is permanent and does not expire.

REQ-KER-7 The kernel MUST keep amounts as exact integer counts of an asset’s minor units, with a range that fits the largest holdings in §11 with room to spare. Floating-point MUST NOT touch a monetary value at any layer.

REQ-KER-8 The kernel MUST conceal entry amounts from any party not entitled to them, and still enforce REQ-KER-1 and REQ-KER-4 over the concealed values.

REQ-KER-9 The kernel MUST support an authority model in which the right to cause an entry against an account can be separated from possession of one credential. Under that model, owner authority, delegated authority and operator authority are distinguishable at the point an entry is made. The audit trail records which one acted. Where the kernel’s native model cannot express this, the gap MUST be closed above the kernel, and REQ-AU-7 MUST still hold.

REQ-KER-10 The kernel MUST offer atomic, all-or-nothing composition of several postings. A multi-step operation then either applies completely or not at all. When the debit legs of one composition are in more than one partition (REQ-RT-9), it MUST still apply completely or not at all.

Trade-off, stated plainly. REQ-KER-8 and REQ-KER-9 are the two requirements most likely to go beyond what a kernel offers natively. Suppose a kernel’s only authority is possession of an account’s credential. Then a custodial operator is forced to hold every holder’s credential. The answer to who authorised then collapses into “the operator, as always”. If that gap is closed above the kernel, the kernel’s own record is weaker than the service’s. That is acceptable, and it MUST be declared in the assurance level (REQ-AR-5). Silently pretending otherwise is not acceptable.

(b) The runtime

REQ-RT-1 The runtime MUST provide, for each partition (REQ-RT-9), a single durable commit boundary that encloses:

the entries of a posting;
the operation record’s state change;
the evidence that caused it;
the enqueuing of any notification;
the enqueuing of every message the commit owes another of the book’s writers (REQ-RT-13), a credit to another partition (REQ-RT-11) among them.

Nothing in that set may commit without the rest. When the book has one partition, this is the single boundary for the whole book.

REQ-RT-2 For an accepted submission keyed on a caller-supplied client key, the runtime MUST guarantee that:

it takes effect at most once;
a repeat returns the original outcome instead of doing new work.

REQ-RT-3 The runtime MUST provide deterministic, replayable execution of the book’s state transitions, so that a third party given the inputs can reproduce the resulting state exactly. The inputs include the book’s genesis and its upgrades; replay executes each input under the code that executed it (REQ-RT-17).

REQ-RT-4 The runtime MUST provide durable, at-least-once delivery of outbound instructions and notifications, and record each delivery durably. After a restart, storage alone can then answer “did we tell them?”. Ordering is not required. A recipient MUST NOT rely on it (REQ-EV-2).

REQ-RT-5 The runtime MUST provide a scheduled-work facility that can act on an operation at a deadline, survives restart, and keeps the schedule itself durable.

REQ-RT-6 The runtime MUST provide a private-input facility. A private input is a value that takes part in a computation without entering replicated state, logs, snapshots or any exported record.

REQ-RT-7 Inside the boundary of REQ-RT-1, the runtime MUST NOT require aledgent to read a clock, draw randomness, or perform network input/output. Time, randomness and external results come in as inputs.

REQ-RT-8 An upgrade of aledgent MUST preserve the book and every balance it implies. Some runtimes can only replace state by re-creating it from exports. Such a runtime is acceptable only if the export and re-import of REQ-RC-3 is first proven at production volume.

REQ-RT-9 Partitions. The book’s state MAY be held in partitions. Each ledger account belongs to exactly one partition, fixed by a deterministic function of the account’s identifier when it is opened.

Everything that is ordered against an account lives in its partition: its balances in every asset and kind, its reservations, and every operation it pays.
The partition is part of the identifiers of what it holds, so that a change in how many partitions there are moves state and never renames it. No identifier changes when the book is re-partitioned.
Holding the book in partitions does not split it (INV-25). The registry, the roles, the trial balance, the anchors and the audit trail are the book’s, not a partition’s.

REQ-RT-10 Ordering per payer. Every operation that debits an account, or takes, captures or releases a reservation on it, MUST be ordered against every other such operation on that account: their effects are those of some serial order, and each sees the effects of those before it. Operations on different accounts need no order. A credit needs no order: credits to one account MAY apply in any order.

REQ-RT-11 A transfer is final when its payer’s partition commits it; its credit is guaranteed. When the payer and the payee of a transfer, or of a capture, are in different partitions:

The payer’s partition decides the transfer and commits the debit. The posting moves the value from the payer to the book’s in-transit position for the asset, and enqueues the credit (REQ-RT-1). From that commit the transfer is final: its operation reaches its terminal state, and nothing undoes it except a new operation (INV-2, INV-21).
The credit MUST then be applied in the payee’s partition exactly once (INV-18), within the bound of NFR-19. Its posting moves the value from the in-transit position to the payee. It MUST NOT be refused: an account that exists can be credited (INV-9), and every check the transfer needs is made by the payer’s partition before the debit commits.
The in-transit position is part of the book. The trial balance includes it and is exactly zero at every commit of every partition (INV-5). Its balance for an asset is the sum of the credits enqueued and not yet applied.
The payee’s view, its statement and its notification follow the credit, not the debit. The payer’s follow the debit.

Before a debit commits, the payer’s partition checks that the payee exists and can hold the asset. An account’s existence and an asset’s registration only ever become true and stay true (REQ-LA-4, REQ-AS-1), so a partition MAY check them against a copy of the book’s directory that lags behind it: a lagging copy can refuse a transfer to an account just opened (ERR-UnknownAccount), and can never accept a transfer whose credit will fail. An asset’s deprecation and an account’s closure take effect in a partition when its copy shows them; a credit already enqueued still applies (INV-9). An account in Closing refuses debits and new transfers to it and still accepts credits in transit; it reaches Closed only when every partition has confirmed that it holds no credit to it in transit.

Trade-off, stated plainly. For up to NFR-19’s bound, the value is neither the payer’s nor the payee’s: it is in transit, and both can see that. A payee cannot spend a credit before it applies. “Final” means final for the payer and for the book; it does not mean that the payee can already spend it. When payer and payee share a partition, both sides commit in one posting, as they always did.

REQ-RT-12 Pools for hot accounts. An account whose debits arrive faster than one partition can order them, such as an issuer’s escrow, a fee collector or a treasury, MAY be held as a pool of member positions in several partitions.

The pool is one ledger account. Its owner, its authority holders, its statement and its balance are the account’s. Its balance is the sum of its members’, read from one consistent view (REQ-BA-3).
Each debit draws on one member, in that member’s partition, and is ordered against that member only.
A debit that the pool’s balance covers MUST NOT be refused because no single member covers it. Such a debit is served atomically across members, as a composition (REQ-KER-10).
A credit MAY land on any member.
Moving value between members of one pool is a rebalancing by the operator: an ordinary, posted, audited operation (REQ-AT-3) that changes no balance of the account.
An account of kind Issuance has no limit (REQ-LA-2). Its debits need no check, so they commute, and its pool’s members need no balance of their own.

Trade-off, stated plainly. A pool’s members can drift apart, so that one runs dry while others hold value. Rebalancing keeps them level; it is an operation to run, watch and pay for. A large debit that has to gather from several members takes two rounds. DEF-8 is not reopened: a holder never sees a member, and a member is not an account.

REQ-RT-13 The book’s writers and the messages between them. When the book’s state is held by more than one writer (each partition’s (REQ-RT-9), the registry of identities, credentials and grants, the record of settlement instructions and their observations, and the audit trail with its anchors), a message from one writer to another:

is enqueued in the sender’s commit (REQ-RT-1), numbered in sequence per sender, receiver and kind;
MUST be applied by its receiver exactly once and in its sequence: a repeat changes nothing, and a message after a gap waits until the gap is filled (INV-18);
is applied inside the receiver’s own commit boundary, together with everything it causes there;
is dropped by its sender only after the receiver has applied it.

A writer decides from its own state and the messages it has applied, never by reading another writer’s state. Each kind’s delay, from the sender’s commit to the receiver’s, is bounded where this specification bounds it (NFR-19, NFR-20) and is otherwise measured and reported with NFR-18.

Trade-off, stated plainly. Between two writers there is always a delay: the receiver acts on what the sender decided some time ago. A partition refuses a revoked grant only once the revocation has reached it (NFR-20); a settlement instruction leaves only once the settlement record has applied it; the audit trail holds a partition’s record only once it has arrived. The spec bounds the delays that a holder can feel, and the rest are measured.

REQ-RT-14 A consistent cut. When the book has more than one writer (REQ-RT-13), a cut names one commit of each writer. In the commit it names, each writer’s audit record carries its stream heads: for each other writer and each kind of message between them, the last sequence it has enqueued for that writer, the last it has applied from it, and the last that writer has acknowledged, up to which it has dropped what it sent.

A cut is consistent when, for every ordered pair of writers and every kind of message from the first to the second:

the receiver’s commit in the cut has applied no message that the sender’s commit in the cut had not enqueued; and
the sender’s commit in the cut still holds every message that the receiver’s commit in the cut had not applied.

The messages enqueued in a consistent cut and not applied in it are in transit at the cut. A credit in transit is counted once, in the in-transit position (REQ-RT-11), and nowhere else.

An anchor (INV-19), the second axis of reconciliation (NFR-9) and a binding’s zero divergence (REQ-AS-8) are each taken at a consistent cut. A cut MUST be decidable from the stream heads alone, and taking one MUST NOT require any writer to stop, drain, wait or be idle. Of the consistent cuts available, the one used is the latest, so that a cut trails the writers’ newest commits by about one message delay.

Trade-off, stated plainly. A cut is a little behind now: under load, about one message delay (NFR-19’s order). An anchor therefore commits to a state some seconds old, which hourly anchoring makes immaterial. A writer whose audit records stop arriving holds every later cut back to its last record: the trail shows it as a gap (REQ-AT-2), and the anchor’s lag grows until it reaches NFR-11’s alert. That is the price of never stopping the book to anchor it.

REQ-RT-15 The active code is book state. Each of the book’s writers (REQ-RT-13) MUST hold, in its committed state, the code version that executes its next input, and the construction of its state commitment (REQ-PR-10). Every checkpoint MUST carry both, and its anchor MUST bind both, so that a recipient of an anchor knows which code produced the anchored state as well as how it is committed.

REQ-RT-16 An upgrade is an input. The code version of a writer MUST change only through an input in that writer’s own sequence: an upgrade, which names the new code version by its digest and the input number from which it applies.

It is an operator intervention (REQ-AT-3) with its own authority (REQ-OS-1), attributed, audited and visible as REQ-OS-4 requires. It is authorised under the upgrade-authority mode in force when it is decided (REQ-RT-18).
It applies forward only. No input before the named number is executed again, re-interpreted or re-decided; every outcome already given stands.
It MUST be refused, with nothing changed, unless the new code version’s artefacts are retrievable and match their digests at the time it is taken.
A change of build settings alone is an upgrade (§2, Code version).
A change of the platform that executes a writer is an upgrade too, and it MAY be made by founding a continuation of the writer on the new platform (REQ-RT-21). Amendment 0033.
It is made online (NFR-17), and it preserves the book in place (REQ-RT-8), without an export.
Where an upgrade changes what the writers exchange (REQ-RT-13), each receiver MUST accept the new form before any sender emits it.

REQ-RT-17 Code history. Every code version that has executed an input of the book MUST be kept, retrievable by its digest, for as long as the book exists (NFR-22). The code map MUST be derivable from the book’s inputs alone. Replay (REQ-RT-3) and every restore MUST execute each input under the code version the code map names for it. Code MAY be retrieved from any source, trusted or not: its bytes MUST be checked against the digest before they are used, and bytes that do not match MUST NOT be used.

Trade-off, stated plainly. An upgrade is the most powerful thing the operator can do: new code can decide differently from the old, including about value. These requirements do not prevent that; they make it recorded, attributable and replayable, so that a third party holding the archive can see exactly which code decided which input and check it. Guardrail 7 (no administrative path that moves value) still holds for every input, because every input is decided by code the book names, but the review of that code is the operator’s, until the deployment is federated or the code is published and reproducibly built.

REQ-RT-18 The upgrade-authority mode. Each writer MUST hold, in its committed state, the mode that decides who may authorise an upgrade (REQ-RT-16), a migration of construction (REQ-PR-11) and a change of mode.

The book’s genesis MUST fix the initial mode (in the seed, where there is one, REQ-RC-6).
The mode MUST change only through an input of its own in the writer’s sequence. That input names the new mode and the input number from which it applies, and it is authorised under the mode in force when it is decided. It applies forward only, like an upgrade.
A new mode MUST be refused, with nothing changed, unless it can be satisfied: every principal it names exists and can hold the authority, and every threshold can be met.
A mode MUST be one that the writer’s current code version can enforce. A kind of mode that the current code does not know needs an upgrade first.
A change of mode cancels every upgrade or migration that has been proposed but not yet authorised. An upgrade already authorised and scheduled stands: it was authorised under the mode then in force.
Every checkpoint MUST carry the mode in force, and its anchor MUST bind it (REQ-RT-15).

REQ-RT-15 to REQ-RT-18 ruled by the owner on 2026-10-08 (amendment 0023, a0023-q1, a0023-q2).

Limits, stated plainly. A mode is only as strong as the code that enforces it: an upgrade authorised under the current mode can install code that interprets modes differently from then on. The book records it, and replay shows it, but nothing stops it. The mode is held per writer, not in the registry, so authority over a writer’s code is checked in that writer’s own order, with no feed lag (NFR-20); a deployment-wide change of mode is one input per writer, and the writers may differ until each has applied it. The mode names principals; their credentials and revocations still come from the registry’s feed, so a revoked approver is refused within NFR-20’s bound, not at once. A lost key under “one principal” blocks upgrades until that principal’s credentials are recovered (REQ-AU-15). There is no bypass, by design (guardrail 7).

REQ-RT-19 The code history does not depend on the platform. A book MUST be able to change the platform its writers run on through upgrades alone, with no new genesis and no export (REQ-RT-8). To that end:

A code version MUST name the platform it runs on, and list, for each of its artefacts, every identity under which that platform knows the artefact, beside the artefact’s own digest. An artefact that one platform needs and another provides itself MAY be absent from a code version.
A value that a platform supplies MUST NOT enter anything that a root, a log hash, a checkpoint or an anchor covers, except through the code version that names the platform. Such values include the platform’s clock, its slot or block number, its identities for principals and programs, and its encoding of state. The host-local fields of a writer (§2, Writer state) are such values. Time enters the book only in inputs (REQ-RT-7).
A checkpoint, and every snapshot that is archived or transferred to restore a writer elsewhere, MUST hold the writer state (§2) and the book’s leaves, in a form that aledgent defines and that no platform defines. A copy that an execution node keeps only for itself, to restart faster, need not. A snapshot taken on one platform MUST restore a writer on any platform that a later code version of that writer names.
Replaying the book’s state (REQ-RT-3) MUST NOT need the platform that executed an input. For every range of the code map, the book’s transitions MUST be reproducible from the inputs by aledgent’s own code, under the range’s code generation. Where a replay also checks that the platform executed each input as archived, the code archive MUST keep, for that range, everything the check needs to run the range as it ran (its replayer), retrievable by digest and indexed by the range’s code version (REQ-RT-17). A replayer is not part of the code version: replacing it changes no code version.

Trade-off, stated plainly. Keeping the code history free of the platform costs a little now, for a move that may never be made. Checkpoints need a format of aledgent’s own instead of the runtime’s image, and every code version carries a list of identities where one would do today. The gain is that a later change of runtime is an upgrade, which the book records and replay crosses, instead of a new genesis and a second book.

REQ-RT-20 The switch of code is one step, and the old code fences it. Each writer holds, in its writer state, the code generation in force. When an upgrade names code version H from input n (REQ-RT-16):

H MUST name the generation one more than the writer’s. Every upgrade MUST raise the generation, and so change the bytes of the code that carries it, even an upgrade made to change only another of its artefacts, such as the runtime that executes that code. An upgrade whose code version names another generation, or whose code does not carry H’s generation in its bytes, MUST be refused with nothing changed, when its artefacts are checked (REQ-RT-16).
Before the upgrade is taken, the execution node that drives the writer MUST have fetched H’s artefacts and checked them against their digests and H’s generation. The switch MUST install only those checked bytes.
The code that executes a writer’s inputs MUST change from the old code version to H in one step, taken after input n − 1 has committed and before input n is executed. A step that fails leaves the old code in force, and is retried.
The switch is symmetric. Before each input, the execution node MUST have installed the code version that the code map, as derived from the inputs committed so far, names for that input. That is H from n after an upgrade, and the old code version again after a move or cancellation at n.
The fence. Code MUST refuse every input unless its own generation equals the writer’s generation in force, or, for an input numbered at or after a scheduled upgrade’s n, equals that generation plus one. The rule holds at every input, whether or not an upgrade is scheduled. A refused input changes nothing and does not take its number, so that the same input runs once the right code is in place. This MUST hold whatever the platform checks or does not check when the code changes. Code of H’s generation that takes input n makes H and its generation the ones in force, as its first effect, unless input n moves or cancels the upgrade.
The way out. A scheduled upgrade MAY be moved to a strictly later input, or cancelled, by an input of its own, authorised under the upgrade-authority mode in force (REQ-RT-18). One that is not so authorised MUST be refused with nothing changed. While the old code is fenced, such an input is the only one it takes, and it takes its input number like any other input. Such an input at or after n MUST be decided the same whichever of the two generations decides it: the upgrade does not take effect at that input, and the generation in force stays the old one. The execution node then installs the old generation’s code again before the next input.
The code map MUST be derived from the upgrade inputs and the inputs that move or cancel them, alone (REQ-RT-17), so that replay gives every input the generation that decided it.
What the fence cannot see. When it starts, and at every switch, the execution node that drives a writer MUST check every artefact it runs for the writer, by digest, against the code version the code map names for the next input. Where any differs, it MUST install that code version, and it MUST NOT drive the writer with anything else. If it cannot install it, it MUST refuse to drive the writer. This covers any part of the code that the platform supplies apart from the code that carries the generation, such as the runtime that executes it.
How long a writer has been fenced MUST be continuously observable (NFR-11), and an alert MUST be raised when it exceeds a bound that the deployment states.
The authority that decides an upgrade MUST be the writer’s upgrade-authority mode, checked by the writer in its own order (REQ-RT-18). Whatever authority a platform has to install or replace programs MUST NOT by itself authorise an upgrade. The execution node that drives the writer MUST install only the code version that the code map names for the next input, so that every install follows from an input the writer committed under that mode.

Limits, stated plainly. Someone who holds a platform’s own authority to install programs can still install other code than the book names. The book cannot stop that. What it guarantees is that every input is executed by the code the code map names, or is refused, and that replay under the code map shows any input whose archived outcome other code produced. The operator keeps the platform’s install authority as it keeps its other keys (NFR-8). The fence identifies code up to its generation only: two builds of one generation look the same to it. That the bytes running are the code version’s own is the execution node’s check, by digest, before the switch and when it starts. That a new code version decides a move or cancellation exactly as the old one does is a property of its code. It is checked on fixture inputs before the version is staged, and replay shows any deviation. The fence fails closed: a switch that cannot be made stops the writer until it is made, or until the upgrade is moved or cancelled.

REQ-RT-21 A continuation. A writer MAY be continued by another at input n: a continuation, founded from the first writer’s writer state (§2) after input n − 1, with its log head.

The continuation MUST be preceded by an upgrade of the first writer that names the continuation’s code version from input n (REQ-RT-16). The first writer’s own code is never switched to the continuation’s, so it refuses every input from n except a move or cancellation of the upgrade (REQ-RT-20), and takes no input at all from n once a founding record exists.
The continuation MUST be founded only from a first writer whose last committed input is n − 1, and whose committed state still schedules, unchanged, the upgrade that names the continuation’s code version from n. The checks made before the continuation is built and those made after it MUST both find so. Its writer state when it is founded MUST equal the first writer’s after input n − 1, field by field. Every check of the founding MUST pass before its founding record is written, and every replay checks it again. A founding that fails a check writes no record and founds nothing, and the first writer continues.
A founding MUST NOT be made while the next input queued for the writer moves or cancels the upgrade. The founding waits until the first writer has decided that input.
The founding record MUST be written before input n is sent to either writer. Each attempt to build the continuation MUST be numbered, from 0, and its instance recorded once, in a write-once record of its own beside the founding record. No such record may be kept only in one node’s own state. Every retry of the founding, by any execution node, MUST read the latest attempt first. It adopts that attempt’s instance if the instance passes the founding’s checks. Otherwise it MUST discard that instance and build a new attempt under a new name, never reusing a name. Where the platform lets the instance be named, its name MUST be derived from the founding record’s key and the attempt. The founding record MUST name the attempt and the instance that succeeded. From then on, every input from n goes to that instance alone. An instance whose founding failed or was abandoned MUST never receive an input. Before it sends an input numbered n or later to the first writer, the execution node MUST check that no founding record exists at n.
Once founded, the upgrade the continuation was founded for is final. The continuation’s writer state records the input number it was continued at (§2). An input that moves or cancels the upgrade scheduled from that number MUST be refused with ERR-InvalidTransition. The refusal changes nothing and does not take the input’s number, like the fence’s, so the upgrade takes effect at the next input that is not refused. The continuation’s refusal is the authority. The execution node MAY refuse such an input before sending it, with the same effect, as a fast path. A refused input, by this rule or by the fence, is recorded by the execution node outside the book and is never part of it. A move or cancellation of a later upgrade is taken as usual.
The input number it was continued at is the one field of the continuation’s writer state that the first writer’s state does not have. Equality covers every other field.
There MUST be at most one continuation of a writer at an input number. Its founding record MUST be written once, under a key derived from the book’s genesis, the writer and n. A write that finds the same record there, byte for byte, is a resume of the same founding and succeeds. One that finds a different record MUST be refused. A replay MUST refuse a log with two founding records at one n. Founding MUST be deterministic: the same writer state gives the same founding record. Only one execution node may feed a writer’s inputs at a time, so that a retried founding cannot run beside the first.
The archive MUST key a writer’s inputs by the logical writer, the identity the founding key uses, never by the instance that runs it, so that a first writer and its continuation share one sequence of input numbers. It MUST accept each input number of a logical writer once: an entry at a number it already holds MUST be refused.
The input number at which an upgrade is scheduled MUST be claimed once, for one writer. The founding record is the continuation’s claim. The first writer’s archive entry at that number MUST be preceded by the first writer’s claim at the same key. Each side’s claim MUST be a fixed function of the book’s genesis, the logical writer, the input number, the side, and the book’s committed inputs before that number, and, for the continuation’s, of the build attempt that succeeded, which is itself recorded once. A claim that finds the same side’s identical claim is a resume and succeeds. One that finds the other side’s claim has lost and MUST be refused. A founding refused this way founds nothing, and the first writer continues.
The archive MUST accept an entry of a continuation at or after a claimed input number only if the claim there is a founding record and the entry comes from the instance recorded beside it.
A replay MUST refuse a log that holds both a founding record and a first writer’s entry at one input number.
The continuation’s first input is n, and its log entry MUST chain to the log head of input n − 1. The book keeps its genesis, its construction and its anchor sequence. A continuation is not a new genesis (REQ-RC-6), not a migration of construction (REQ-PR-11), and not an export and import (REQ-RC-3).
The code map is derived from the upgrade inputs (REQ-RT-17). The founding record is archived with the inputs, as evidence that replay checks against the upgrade that named it.

REQ-RT-19 to REQ-RT-21 ruled by the owner on 2026-10-17 (amendment 0033).

(c) The settlement layer

REQ-SL-1 The settlement layer MUST be able to:

accept and durably record a commitment of bounded size submitted by aledgent, together with a per-deployment sequence;
make the commitment’s presence, and its order by that sequence, publicly checkable.

The settlement layer MAY hold only the latest commitment in its current state. An earlier commitment is then durably recorded in the layer’s finalized history, and checking its presence MAY require a reader that keeps that history; it MUST NOT require aledgent’s cooperation (REQ-PR-4). This assumes that such readers are available independently of the operator: parties other than the operator keep the layer’s finalized history. Amendment 0029.

Trade-off, stated plainly. A recipient who checks an anchor older than the latest needs a reader of the settlement layer that keeps its finalized history, or a read saved earlier; any reader serves the latest. A reader that cannot reach that history reports the anchor unreadable, never missing. If the only readers that keep the history were the operator’s, the check of an older anchor would in practice depend on the operator; the assumption above is what rules that out.

REQ-SL-2 The settlement layer MUST be able to:

hold and transfer value on aledgent’s behalf between aledgent and a counterparty;
report that a transfer occurred at a coordinate that is unique, stable and independently readable.

REQ-SL-3 The settlement layer MUST offer a point after which a recorded fact cannot be revised, and MUST make that point observable. aledgent MUST gate settlement on it. It MUST NOT approximate that point with a count of later records.

REQ-SL-4 Some instructions submitted to the settlement layer can expire. aledgent MUST submit those with an explicit expiry. Non-inclusion then becomes provable, not merely undetermined. Where an instruction cannot expire, REQ-OP-9 applies instead.

REQ-SL-5 aledgent MUST NOT require a settlement-layer record per operation, per account, or per identity. Settlement-layer usage MUST be proportional to external value movement and to anchoring, not to activity.

REQ-SL-6 Value moving between two deployments attached to the same settlement layer MUST settle through that layer as an external leg of each. Settlement is either immediate per operation, or netted over a stated window. A netted arrangement MUST bound the exposure that builds up inside the window. It MUST reconcile to zero when the window closes (DEF-1).

REQ-SL-7 The settlement layer MUST accept value addressed to a deployment together with an opaque account reference that the deployment resolves. It MUST NOT require a record per account.

REQ-SL-8 The settlement layer MUST record every value movement to or from a deployment under a coordinate that is native to the settlement layer and stable. For a movement the deployment originated, that record MUST carry the deployment’s operation reference. Each leg’s outcome can then be determined by identity (REQ-SO-3, REQ-IN-1).

REQ-SL-9 The settlement layer MUST expose the movements and anchors concerning a deployment as a sequenced record readable by position. Observation completeness (REQ-SA-7) is then a read over a contiguous range, and does not depend on a subscription.

REQ-SL-10 For a deployment, the settlement layer MUST hold nothing beyond its identity and settlement positions, its anchors, and the sequenced record of REQ-SL-9. In particular, it holds no balance, account or identity of any holder.

Trade-off, stated plainly. REQ-SL-5 removes per-operation cost and any throughput ceiling the settlement layer imposes. It also removes something real. With no record per holder on a public network, nobody can rebuild a holder’s balance from that network alone. aledgent offers provability (§4.6). It is not read off the settlement layer. REQ-SL-7 is how a counterparty addresses one specific account when sending value in.

(d) The settlement adapter

The settlement adapter is the one component of aledgent that touches the settlement layer. It holds the keys. It holds no authority over any account.

REQ-SA-1 The adapter MUST declare which operations it supports for which assets, in a form aledgent can check before accepting an operation. aledgent MUST refuse an unsupported operation at submission, not at execution.

REQ-SA-2 At start-up, the adapter MUST assert that the network it is connected to is the settlement layer the deployment declares. It MUST fail closed on a mismatch.

REQ-SA-3 The adapter MUST report an outcome only as an observation. An observation is a named event at a named coordinate, with the network’s own error text where one exists. The adapter MUST NOT report a status that aledgent did not derive (INV-11).

REQ-SA-4 The adapter MUST distinguish three dispositions, and aledgent MUST act differently on each:

executed: evidence exists;
provably not executed: the instruction can no longer take effect;
unknown: neither has been established.

The adapter MUST NOT collapse “unknown” into either of the others.

REQ-SA-5 The adapter MUST be able to state three things from durable state alone, at any later time: what it was asked to do, what the network did, and whether it told aledgent. All three MUST survive a restart.

REQ-SA-6 The adapter MUST persist the exact instruction it submits before it submits it. Recovery then replays that instruction instead of producing a second one with the same intent.

REQ-SA-7 Observation of value arriving MUST be complete over a contiguous range. The adapter MUST NOT advance past a range it did not read successfully. It MUST record any range it was forced to skip as an explicit gap that the operator can see.

REQ-SA-8 The adapter MUST hold no authority over a ledger account and MUST NOT be able to cause an entry. Its credentials MUST be scoped to submitting evidence and executing the instructions it was given.

REQ-SA-9 When the settlement layer changes its rules, the adapter MUST decide whether it can keep serving from what an instruction it submits must carry under the new rules. That means the version of the instruction format the layer declares, the parts every instruction must carry and the types of their data, and the type of each call the adapter submits, all as the layer itself describes them. A version number of the layer’s rules alone MUST NOT decide it, either way. Before it signs the first instruction under rules it has not served before, the adapter MUST have the settlement layer itself confirm that an instruction it built and signed under them is valid, and it refuses to serve until the layer does. An operator MAY name in configuration the format to use for a set of rules. The layer’s confirmation is still required.

Trade-off, stated plainly. REQ-SA-7 conflicts with recovery. A settlement layer keeps recent history only for a bounded window. An observer that falls behind that window cannot read what it missed. The only way forward is to skip. Sometimes losing records is the only way forward. Losing them silently never is. REQ-SA-7 allows the skip but requires a visible mark of it. REQ-IN-5 requires the gap to be reconciled from an archive afterwards.

4.5 Privacy model

REQ-PV-1 Ledger facts are private by default. Every read MUST be authorised against an authority over the specific account or identity whose facts are read. No ledger fact can be read without authentication.

REQ-PV-2 Who sees what:

Party	Sees
An account’s authority holders	Everything about that account: balances in all layers, every entry, every operation, and every counterparty aledgent knows
The owning identity	All of the above, across all of its accounts
A principal holding authority over another identity’s accounts	Those accounts, only as far as the authority reaches. Never the rest of that identity’s facts
A settlement counterparty	Only what its external leg necessarily reveals on the settlement layer
The operator	What it needs to operate, subject to `REQ-PV-4`. Every access is traceable to who did it (`REQ-PV-5`)
A verifier	Exactly what a disclosure asserts (§7.E)
The public	The existence and order of anchors, and external value movements to and from aledgent in aggregate. Nothing about an identity, an account, a balance, an internal movement, or a counterparty pair

REQ-PV-3 Personal data MUST NOT appear in any identifier, in any anchored value, or in any disclosure that does not explicitly assert it.

REQ-PV-4 A privileged read path is one that bypasses the authority checks of REQ-PV-1. Such a path MUST be issued by exactly one instrumented mechanism. It MUST record the acting principal and a justification. The number of distinct places that use the mechanism MUST be asserted against a committed expected value. A new place then fails a build.

REQ-PV-5 Every access to a ledger fact MUST be traceable to a principal and a request. An access that cannot be attributed MUST be refused.

REQ-PV-6 A disclosure MUST reveal only what it asserts. Producing a disclosure MUST NOT require giving the recipient any ability to read anything else, now or later.

REQ-PV-7 aledgent MUST NOT rely on the secrecy of an identifier for any security property. Identifiers are assumed to leak.

Trade-off, stated plainly. Privacy and support pull against each other, and good intentions do not fix that. Under REQ-PV-4 and REQ-PV-5, every legitimate support action becomes a designed, named, audited operation. It is no longer a query someone already knew how to write. Support gets slower before it gets safer. That is the intended order.

4.6 Provability model

REQ-PR-1 aledgent MUST anchor the state of its book on the settlement layer every hour, and on demand. The anchored value commits to every entry recorded up to that point, and to nothing else. An hour is therefore the longest window in which a revision cannot be detected (REQ-PR-3). An on-demand anchor MUST be taken on either of two triggers: when the operator asks for one, with a justification (anchor_checkpoint, REQ-OS-1); and when a disclosure is requested whose assertion concerns entries that no final anchor covers yet. That disclosure is then issued against the new anchor, once it is final (REQ-DS-2, REQ-PR-8).

REQ-PR-2 An anchor MUST NOT reveal any account, identity, amount, counterparty or asset.

REQ-PR-3 An anchor establishes exactly this: aledgent held a particular book state at a particular time, and it cannot later claim to have held a different one. It establishes nothing about whether that state was correct, whether the value it records exists, or whether the operator is solvent.

REQ-PR-4 Given an anchor and a disclosure, a recipient MUST be able to check that the disclosed facts are consistent with the anchored state, without needing aledgent’s cooperation at verification time.

REQ-PR-5 aledgent MUST be able to prove that the value it records as held on the settlement layer matches what the settlement layer says it holds. aledgent MUST perform that comparison continuously. A divergence is an incident, not a report.

REQ-PR-6 A proof can be a signed assertion by aledgent, not a construction a recipient can check independently. In that case, the disclosure itself and the assurance level MUST say so. A signed assertion is evidence of aledgent’s claim, not of its truth.

Trade-off, stated plainly. REQ-PR-3 is deliberately modest, because the alternative is a claim that cannot be supported. An anchor plus a disclosure proves consistency with what aledgent committed to. It does not prove solvency, and no anchoring scheme does. A venue that checks that two parties’ books cancel is checking consistency, not solvency. It would be false to tell holders that anchoring makes the operator unable to cheat. OQ-31 asks what, if anything, is committed to on top of anchoring to make a solvency statement possible at all.