11. Non-functional requirements

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

The numeric targets in NFR-1–NFR-3, NFR-15 and NFR-16 bind from the first release in which they can be measured on the deployed host. Until then they are design targets. A plan MUST NOT relax them silently. Latency has three numbers and no fourth. A command that moves value is acknowledged within NFR-1. Every other command is answered with its decision within NFR-16 (REQ-CS-8). Every command completes within NFR-15. Deciding a reservation is part of its completion; it has no budget of its own. For a command with an external leg, completion ends at the leg’s inclusion; the settlement layer’s finality after it is measured and reported, not bounded (NFR-15). Losing an execution node is not a restore. NFR-21 keeps the book whole and online through the loss of any one node; a restore (NFR-4, NFR-10) is for the loss of a quorum, or of the whole deployment.

ID	Requirement
`NFR-1`	aledgent MUST acknowledge a command that moves value (`REQ-CS-8`: a transfer, a reservation, a withdrawal) within 50 ms at p99, measured inside aledgent: take it in durably and return its operation reference and the state `Received` (`REQ-CS-2`). Its decision is part of completion (`REQ-CS-3`, `NFR-15`). A command answered with its decision is bound by `NFR-16`, not by this requirement. A transfer or reservation of a principal answered with its decision (`REQ-CS-9`) is bound by `NFR-16`, not by this requirement.
`NFR-2`	aledgent MUST sustain, without redesign, 2.5 million operations a month and the postings and entries they imply. That is about five million postings and fifteen million entries.
`NFR-3`	A balance read MUST complete within 5 ms at p99 at 150 million entries. This includes an account holding a large fraction of them. The distribution of entries across accounts MUST be assumed to be extremely skewed.
`NFR-4`	No operation that aledgent has acknowledged, or answered with its decision, may be lost. Backups MUST exist and MUST be restorable. A restore MUST re-derive every balance from entries alone (`INV-6`).
`NFR-5`	aledgent MUST be deployable without an outage of the book.
`NFR-6`	The audit trail MUST be retained independently of operational storage, for at least as long as the longest applicable regulatory retention period. It MUST be queryable during that period.
`NFR-7`	There MUST be no unauthenticated route to any ledger fact. Every route MUST be covered by a default-deny mechanism. A missing check on a new route then fails closed.
`NFR-8`	No single process may be able to move value without bound. Settlement-layer key material MUST be held in a boundary that is separate from the book and can be audited separately. It MUST NOT be readable from a process environment. It MUST NOT appear in any log, URL or error.
`NFR-9`	Reconciliation MUST run at least daily on three axes. First: per (account, asset), against every independent source. Second: the per-asset trial balance, which MUST be exactly zero, and the in-transit position of each asset, which MUST equal the credits in transit at a consistent cut (`REQ-RT-11`, `REQ-RT-14`). Third: the book against the settlement layer’s view of what aledgent holds. The resolution MUST be one minor unit and the tolerance MUST be exactly zero. A failure MUST page a human, never open a ticket.
`NFR-10`	A restore-from-backup drill MUST be run before production use and at a stated cadence. It MUST reproduce the book and re-derive every balance.
`NFR-11`	The following MUST be continuously observable: age of the oldest non-terminal operation; observation completeness; count and age of undelivered notifications; anchor lag; reconciliation outcome per axis; and liquidity of every position that funds settlement-layer costs.
`NFR-14`	A conformance suite MUST exercise every invariant in §9 and every error in §10 before production use. It MUST be re-run against every deployment’s declared assurance level (`REQ-AR-5`).
`NFR-15`	A command MUST complete within 30 s at p99, measured inside aledgent from its acknowledgement, or from its arrival for a command answered with its decision (`REQ-CS-8`). It completes when its operation reaches the state the command asks for, or is refused: `Reserved` for a reservation, `Observed` for a command with an external leg, and a terminal state for every other command. For a command with an external leg, completion ends at inclusion: the leg is included on the settlement layer, the operation has reached `Observed` (a confirmation, §2), and that state has been relayed to the requester (`REQ-EV-1`). If the operation reaches a terminal state without its leg being included, it completes there. Inclusion is not finality (`REQ-IN-7`): nothing is posted against the issuance counterparty before the leg is final (`INV-10`), and the operation goes on to `Final` and `Settled`. The time from inclusion to the hand-off (the leg final on the settlement layer, the operation at its terminal state, and the outcome relayed to the requester) is not bounded by this requirement: most of it is the settlement layer’s finality, which aledgent cannot shorten. It is measured and reported on every release with `NFR-18`, split into the settlement layer’s time to finality and aledgent’s time from finality to the relayed outcome. Whatever follows the hand-off is outside aledgent. That includes any further movement of the value beyond the settlement layer, and the requester’s own processing. An operation in `Needs-Review` before it completes has not completed. 30 s is the ceiling: alerts and conformance breach on it. The target is 19 s at p99: it is tracked, and missing it is not a breach. Completion to inclusion ruled by the owner on 2026-10-04 (amendment 0018).
`NFR-16`	aledgent MUST answer a command that is answered with its decision (`REQ-CS-8`) within 1 s at p99, measured inside aledgent from the command’s arrival to the reply that carries its decision. A reply of `ERR-DecisionUnavailable` (`REQ-CS-7`) is measured the same way and counts against this bound. This includes a transfer or reservation of a principal answered with its decision (`REQ-CS-9`). Confirmed by the owner on 2026-10-02 (amendment 0011, R5).
`NFR-17`	One window. The load of a deployment’s initial state (`REQ-RC-4`) is the only period in which aledgent MAY refuse or defer holder operations for maintenance. After it closes, no change to the deployment MAY need such a period: not binding an asset to the settlement layer (`REQ-AS-8`), not starting or moving anchoring, not moving the deployment to another place on the settlement layer, not an upgrade (`NFR-5`). Each is made online, with every balance unchanged, and every operation either decided as usual or refused under its own named condition (§10). A change that cannot be made this way is not made.
`NFR-18`	Throughput, measured. aledgent’s sustained decision rate MUST be measured by the stress suite on every release and reported with the mix of commands and the number of concurrent principals it was measured at. The design MUST scale by adding partitions (`REQ-RT-9`), not by a faster single writer. No target figure is stated (the owner, 2026-10-03): the aim is the greatest throughput achievable, for a deployment whose principals include millions of concurrently active agents.
`NFR-19`	Credit lag. The credit of a transfer between partitions MUST be applied within 2 s at p99 of its debit’s commit (`REQ-RT-11`). Proposed; waits for the owner (amendment 0012).
`NFR-20`	Revocation lag. A revocation MUST take effect within 1 s at p99 of its commit (`REQ-AU-3`). Proposed; waits for the owner (amendment 0012).
`NFR-21`	Ephemeral horizontal scaling. aledgent runs on execution nodes that can be added, replaced and lost without an outage of the book. (a) Scale out. aledgent’s capacity MUST be increasable by adding execution nodes, with no change to the book, to any identifier in it or to any operation, and online as `NFR-17` requires: every balance unchanged, and every operation decided as usual or refused under its own named condition (§10). (b) Replace. Any execution node MUST be replaceable by a new one that starts with no local state. The new node is admitted online and brought up to date from the nodes already serving and from the deployment’s durable copies, with no operation that aledgent has acknowledged or answered with its decision lost (`NFR-4`) and no outage of the book (`NFR-5`): while a node is admitted, and after one is lost, every command is still acknowledged within `NFR-1` or answered within `NFR-16`, and completes within `NFR-15`. (c) Lose local storage. The loss of the local storage of any single execution node, at any instant, MUST NOT lose an operation that aledgent has acknowledged or answered with its decision. An operation is therefore acknowledged or answered only once the record it rests on (the command taken in, or the commit that decided it) is durable on a quorum of the nodes that hold that record: at least two of them, and a majority. Bounds, measured rather than committed (the owner, 2026-10-04). Each deployment states how many nodes hold each writer’s state and its quorum; the design value is three and two. The stress suite measures, and reports on every release with `NFR-18`: the time to admit a new node and bring it up to date at the book’s size (design value: 15 minutes at `NFR-2`’s volume); the time a writer takes to resume deciding after losing the node that orders its commands (design value: 10 s); and the decision rate while a node is admitted. Missing a design value is reported, not a breach; `NFR-1`, `NFR-15` and `NFR-16` still bind throughout. Ruled by the owner on 2026-10-04 (amendment 0016).
`NFR-22`	Retention of what replay needs. For as long as the book exists, aledgent MUST keep: its genesis (and any seed it committed, `REQ-RC-6`); every input of every writer, in order, with its reply; every code version in the code map (`REQ-RT-17`); every checkpoint an anchor bound, with the anchor’s record (`REQ-PR-8`); and the audit trail (`NFR-6`). Everything else MAY be pruned once it is re-derivable from these: snapshots of a writer’s state other than the latest one an anchor verified, indexes, the projections a node keeps to answer reads, proofs and witnesses. No proof is needed to bring a node up to date: state is re-derived from inputs, or taken from a snapshot and checked against an anchor. Ruled by the owner on 2026-10-08 (amendment 0023).

Trade-off, stated plainly. NFR-21 (c) puts a round trip between execution nodes inside every acknowledgement and every decided answer: NFR-1 and NFR-16 are spent partly on it. A node’s local storage is a cache, so a new node starts by copying its writer’s state from the others, and the book’s size sets how long that takes. And a quorum of two out of three tolerates the loss of one node at a time, not two: losing a quorum is a restore (NFR-10), with the outage that implies.