5. Domain model

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 types below use a schematic notation, not an implementation language. Names bind where a requirement says so. Widths, numeric types and syntax do not bind: Count means “a count”. No invariant in §9 implies a representation.

5.1 Identity

Identity {
    id:       IdentityId
    kind:     Person | Organisation | Agent
    status:   Active | Restricted | Closed
    acts_for: Option<IdentityId>   // agents only — see REQ-AG-1
}

REQ-ID-1 Every identifier aledgent mints:

MUST come from a closed registry of kinds.
MUST have a fixed number of parts for its kind.
MUST be validated both when it is minted and when it is parsed.
MUST NOT contain personal data.
MUST be immutable once minted.

A parser MUST NOT read a part of an identifier by its position without first validating the identifier’s kind.

REQ-ID-2 An identifier MUST NOT encode how its subject authenticates, which environment it lives in, or any other property that can change during the subject’s life. Those are properties of a credential or of a deployment, not of the identity.

REQ-ID-5 An identity’s identifier MUST NOT be an input when deriving any address on the settlement layer or any other long-lived external name. This way an identity can be merged, renamed or moved without changing what the outside world holds.

REQ-ID-6 Identities MUST be opened only by the identities principal: the operator, or the principal that plays that role in a deployment. The role is an operator authority of its own kind, open_identity (REQ-OS-1), granted alone: only the operator grants and revokes it, with a justification, and the operator keeps it while another principal holds it. At most one principal besides the operator holds it at a time: granting it to another revokes it from the holder in the same operation. An opening under the role MAY carry the opener’s own justification as pass-through data (REQ-PO-5). A ledger account is opened by the identities principal, for any identity; by the identity that will own it: an identity MAY open further accounts of its own, under its own authority (US-A2); or by a principal holding a delegated grant over that identity that names open_account. Such a grant is made by the identity itself or by the identities principal, is never narrowed into another grant over an identity, and opens only customer accounts in delegated custody for that identity; no other grant names open_account (§5.9). It reaches no account by itself. It MAY also name the operation kinds its holder delegates over that identity’s accounts in delegated custody: its holder grants delegated authority over such an account only as a narrowing of it, never wider in kind or bound, and its revocation stops every grant made under it (REQ-AU-3, REQ-AU-4). The identities principal MAY grant delegated authority over an account in delegated custody of an identity it manages (REQ-AU-20) directly. A book founded from a seed (REQ-RC-6) carries these grants for the identities and accounts it loads, as grants of the seed. The authority to open identities is split by kind, attributed and audited, like every operator authority (REQ-OS-1, REQ-AU-7, REQ-AT-1). Amendment 0025. An integrating party keeps its own record of the identifiers of the identities and ledger accounts it serves, and maps them to its customer facts (§1.3). aledgent does not hold or need that record, and nothing in it decides whether an identity or an account exists (REQ-ID-7).

REQ-ID-7 aledgent is its own authority for identity: its book is the authoritative registry of which identities and ledger accounts exist (§4.2). The integrating party remains the authority for who a holder is (§4.2, §13). A deployment is not permissionless. Most operations are carried out by the principals they concern, under their own authority (§5.9). The operations that configure the deployment itself are the operator’s alone, and no grant can give them to another principal: registering an integrating party, and deciding which identity providers the deployment accepts and on what terms. Registering an integrating party is an operator operation (§7.D): it records the party’s identifier and the principals tied to it. Only the operator ties a principal to a party, when it registers the party or later, and a principal is tied to at most one party; tying it to a second is refused with ERR-NotAuthorised. A principal tied to none, such as the operator’s own, is a client-key domain by itself (REQ-OP-10). Which identity providers the deployment accepts, and on what terms, is the deployment’s configuration, set by the operator alone.

REQ-ID-8 An identity without a credential. An identity MAY be opened with an empty credential set, only by a principal holding the operator’s authority to open identities (REQ-ID-6, REQ-OS-1). Any other principal that opens an identity MUST give it a first credential.

While an identity’s set is empty:

every account it owns MUST be in delegated custody. Opening an owned-custody account for it, or changing one of its accounts to owned custody, MUST be refused with ERR-NotAuthorised (REQ-AU-6, REQ-AU-13);
no one exercises owner authority over its accounts. They are operated under operator authority and under the authorities granted over them (REQ-AU-5, §5.9);
its first credential joins the set only by enrolment (REQ-AU-22), by import (REQ-MG-7), or by a completed recovery.

An identity opened with a credential, or whose set has ever held one, never returns to an empty set (REQ-AU-20).

5.2 Ledger account

LedgerAccount {
    id:          AccountId
    owner:       IdentityId
    kind:        Customer | Treasury | Issuance | Suspense
    custody:     Delegated | Owned
    status:      Active | Frozen | Closing | Closed
    opened_at:   Time
}

REQ-LA-1 A ledger account has exactly one owning identity. An identity MAY own many accounts.

REQ-LA-2 kind sets the negative-balance policy and nothing else:

Customer MUST NOT be negative in any balance kind, in any asset, at any instant.
Treasury MAY be negative up to a declared limit per asset.
Issuance has no limit. It is the counterparty whenever value enters or leaves the book.
Suspense holds value whose correct destination is not yet known. It MUST be reconciled to zero on a stated cadence.

REQ-LA-3 Authority over an account is separate from ownership of it (§5.9). More than one principal MAY hold authority over one account.

REQ-LA-4 A ledger account MUST NOT be deleted. An account can close only when its balances are zero in every asset and every balance kind, or after an explicit, posted operation moves them to a named destination.

REQ-LA-5 aledgent MUST NOT assume, require or record how an account is presented. An identity owns an account, and it is used under authority. How many products, cards, handles or addresses present it is not a ledger fact.

REQ-LA-6 When many identities draw on one account, in a pooled or omnibus arrangement, that arrangement MUST be expressed as explicit, bounded authority that each drawing identity holds over the account (§5.9). It is never a shared identifier or a shared credential.

Trade-off, stated plainly. REQ-LA-6 turns a pooled account into a set of authority grants. That is more to administer than one shared address. But it is the only form in which “who drew on the pool, and within what limit” is a ledger fact, and not a note in someone else’s system. OQ-5 asks whether the drawing identities of one pool may belong to different integrating parties, and what that means for REQ-PV-2.

REQ-LA-7 A freeze is a status of the account, not a balance kind. A frozen account MUST refuse every operation that debits it, with ERR-AccountFrozen, and MUST accept credits (INV-9). Freezing and unfreezing move no value: the account’s balances do not change, and its value stays available. A restriction on a specific amount is an encumbrance (§5.4), not a freeze.

5.3 Asset

Asset {
    id:         AssetId         // closed registry, case-normalised at the boundary
    precision:  Count           // minor units per unit; lives here and nowhere else
    kind:       Fiat | Stable | Native | Other
    status:     Active | Deprecated
    binding:    BookOnly | Binding | Bound(SettlementAsset)   // REQ-AS-7, REQ-AS-8
}

REQ-AS-1 There MUST be exactly one asset registry. Precision MUST be recorded there. It MUST NOT be derivable from, or carried by, an asset’s name, an account, a settlement-layer configuration or a caller’s input.

REQ-AS-2 Adding or changing an asset MUST be a reviewed, recorded change, never a side effect at runtime. The settlement layer’s view of an asset MUST be checked against the registry when the asset is bound (REQ-AS-8), and a mismatch MUST refuse the binding, never become a silent divergence. After the binding, the registry is the only authority on the asset (REQ-AS-9).

REQ-AS-3 Asset identity MUST be normalised at every boundary. Two spellings of one asset MUST NOT be able to exist as two assets.

REQ-AS-4 An amount MUST be an exact integer count of minor units of a named asset, from the caller’s boundary to the book and back. There MUST be exactly one conversion between a human-readable decimal and minor units, at exactly one boundary. That conversion MUST NOT round. Excess precision from a caller is rejected, not truncated.

REQ-AS-5 Withdrawn by amendment 0012 (OQ-17 closed): aledgent does not convert between assets (§13). The identifier is not reused.

REQ-AS-6 Issuance and redemption of an asset means value entering or leaving the book other than through the settlement layer. They MUST be possible only under an issuance authority for that asset (§5.9), held by the operator or by an identity the operator granted it to. Every issuance and redemption is a posting against the issuance counterparty, visible in the trial balance (INV-5).

REQ-AS-7 Book-only assets. An asset is registered book-only: in the registry, with its precision, and bound to nothing on the settlement layer. Its value enters and leaves the book only by issuance and redemption (REQ-AS-6), and moves inside it like any other asset’s. An external leg in a book-only asset MUST be refused at submission with ERR-UnsupportedLeg (REQ-SA-1).

REQ-AS-8 Binding. A book-only asset MAY be bound to the settlement layer, once, after its registration, by a principal holding issuance authority for it (§5.9). Binding is a reviewed, recorded change with a justification and an audit record (REQ-AT-1), and is visible to every authority holder of the asset (REQ-OS-4). It names the asset’s identity on the settlement layer. It succeeds only if all of these hold:

the settlement layer describes an asset there, live, whose symbol, normalised (REQ-AS-3), is the asset’s id, and whose precision is the registry’s. Both are read from the layer’s own fields for them. A name or any other text is never parsed for either. A layer that describes no asset there, or describes it otherwise, refuses the binding with ERR-UnsupportedLeg;
no other asset is bound, or being bound, to the same identity on the layer (REQ-AS-3), and this asset is book-only. Otherwise ERR-NotAuthorised;
zero divergence: what the settlement layer holds for aledgent in the asset equals, to the minor unit, the book’s outstanding balance of the asset, which is the negation of what the issuance counterparty holds in it (INV-5). The equality MUST be established by the settlement layer, at the point it records the binding, and become final there (REQ-SL-3). A binding that does not establish it is refused, and the asset stays book-only.

When the book is held in partitions (REQ-RT-9), the asset’s Binding state reaches every partition as a message from the registry (REQ-RT-13). Each partition refuses the asset’s issuance and redemption from the commit in which it applies that state, and in that commit reports its issuance counterparty’s position in the asset. The outstanding balance is taken at the latest consistent cut (REQ-RT-14) in which every partition has applied the state, and is the negation of the sum of those positions: equal, to the minor unit, to the sum of every holder’s balance in the asset at that cut plus the value in transit at it. The binding asks the settlement layer to hold that amount.

Trade-off, stated plainly. Between the registry recording Binding and the last partition applying it, the partitions that have not yet applied it can still issue and redeem. Those operations are decided, final and included in the amount: nothing is lost and nothing is counted twice. But “issuance is refused while the asset is Binding” takes effect partition by partition, within NFR-20’s bound, as a revocation does.

From the request until the binding is final or refused, the asset is Binding. While it is Binding, issuance and redemption of the asset are refused with ERR-NotAuthorised, so that the outstanding balance the settlement layer is checking cannot move. A refused binding returns the asset to book-only. Once the binding is final, the asset is Bound: external legs in it are supported as the adapter declares (REQ-SA-1); issuance and redemption go on under issuance authority, as for any asset (REQ-AS-6); and the settlement layer’s holding in it is reconciled with the book on NFR-9’s third axis from that point, the binding’s amount its starting position. A binding is never undone.

REQ-AS-9 After binding. Once an asset is bound, its record in the registry MUST NOT change because the settlement layer’s description of the asset changed. Such a change is ignored: it holds nothing, refuses nothing, and is not a divergence. The precision stays the registry’s (REQ-AS-1).

5.4 Balance kinds

Each account and asset has three separately readable amounts: available, reserved and encumbered. The total is their sum. How they are implemented is not fixed (REQ-KER-3). A freeze is not one of them: it is a status of the account (REQ-LA-7).

REQ-BA-1 Movement among the three kinds MUST be expressed as ordinary entries. It is then visible in the book and subject to INV-1.

REQ-BA-2 available is the only number used to decide a spend. Every surface that shows a balance MUST show available and MUST label total as total.

REQ-BA-3 The number shown to a holder and the number a spend is checked against MUST be the same number, read from the same view. Two numbers that can disagree cause a known class of double-spend. aledgent MUST NOT reproduce that design.

REQ-BA-4 A reservation MUST reduce available at the instant it is accepted, in the same atomic step as the check that there was enough. A reservation whose balance effect is delayed is not a reservation.

REQ-BA-5 aledgent MUST answer a balance read for an identity, across all its accounts and assets, as one query. A caller MUST NOT need to query each account separately. Each account’s balances MUST come from one consistent view of that account (REQ-BA-3). Value moving between two of the identity’s own accounts in different partitions (REQ-RT-11) MUST be shown as in transit, never as missing or counted twice.

REQ-BA-6 reserved MAY be a derived number, the sum of the account’s open reservations, provided it is read from the same consistent view as available (REQ-BA-3, REQ-QR-2).

5.5 Entries and postings

Entry {
    account:   AccountId
    asset:     AssetId
    kind:      Available | Reserved | Encumbered
    direction: Debit | Credit
    amount:    Amount        // strictly positive
}

Posting {
    id:        PostingId
    kind:      Reserve | Capture | Release | Transfer | Issue | Redeem
             | Conversion | Encumber | Disencumber | Reversal | Opening
    entries:   [Entry]       // at least two
    operation: OperationRef
    sequence:  Sequence      // globally monotonic
    at:        Time
}

REQ-PO-1 A posting’s kind is the authoritative statement of what the posting did. A posting’s meaning MUST NOT be recoverable by parsing any string. No identifier may carry lifecycle state.

REQ-PO-2 Entries MUST be ordered by a global, monotonic, gapless sequence. Every paged read of entries MUST page on that sequence. Paging on time is unsafe, because different entries can share the same time.

REQ-PO-3 A reversal MUST reference the posting it reverses. It MUST be complete, not partial. There MUST be at most one reversal per posting. Only a reversal operation (§5.6) appends a Reversal posting. A correction that is not a complete reversal is a reversal followed by a new operation (US-K4).

REQ-PO-4 Structured facts that a decision branches on MUST be recorded as structured fields. Opaque pass-through data MAY be unstructured, and MUST NOT be branched on.

REQ-PO-5 Pass-through data. A command that submits an operation MAY carry pass-through data: one JSON value, encoded in UTF-8, of at most 1 KiB. So MAY open_identity and open_account (amendment 0025). aledgent records it with the operation and never branches on it (REQ-PO-4).

It is part of the request. A repeat under the same client key with different pass-through data is a different request, refused with ERR-ClientKeyReused (REQ-OP-10).
It comes back to its owner. It is echoed in the command’s reply, whether acknowledgement or decision; in operation(reference); in every notification of the operation’s transitions (REQ-EV-1); and in the operation’s movements (REQ-QR-1). It is shown only to principals of the integrating party whose principal submitted it (REQ-ID-7). A principal tied to no party is its own party here.
Nobody else sees it. It is not in a credit notification to another party (REQ-EV-9), in a movement read by another party, in a disclosure, or in an anchored value (INV-17).
Over the bound, or not one JSON value, the command is refused and nothing is taken in. It fails closed, as any command whose shape is not one aledgent accepts, with ERR-MalformedCommand (REQ-ER-3).
It is part of the operation’s record. An export carries it, and an import restores it (REQ-RC-3).

The caller MUST NOT put personal data in it. aledgent cannot check this and does not try. Because it anchors none of it and shows it to no other party, a caller that does is exposed only to itself.

5.6 Operations and their lifecycle

Operation {
    reference:      OperationReference   // service-derived, permanently unique
    client_key:     Option<ClientKey>    // caller-supplied, opaque
    kind:           OperationKind
    initiator:      PrincipalRef
    on_behalf_of:   Option<PrincipalRef>
    state:          OperationState
    deadline:       Time
    evidence:       [Observation]
    outcome:        Option<Outcome>
}

States: Received, Accepted, Reserved, Submitted, Observed, Final, Settled, Released, Rejected, Expired, Orphaned, Needs-Review. The transitions below are normative. No other transition exists.

From	To	When
`Received`	`Accepted` or `Rejected`	The deciding component takes the command. This MUST happen within a stated bound (`REQ-CS-7`), which is `Received`’s deadline
`Accepted`	`Rejected`	Refused before any balance effect
`Accepted`	`Settled`	The operation has no external leg and needs no reservation. An internal transfer is final on acceptance. A reversal operation settles when a principal other than its proposer approves it (`REQ-OS-3`)
`Accepted`	`Reserved`	The reservation is posted (`REQ-BA-4`)
`Reserved`	`Settled`	Captured, with no external leg
`Reserved`	`Released`	Released, with no external leg, or with one that provably cannot execute: non-inclusion proven, or a proved rejection (`REQ-OP-9`)
`Reserved`	`Submitted`	The instruction is durably handed to the settlement adapter (`REQ-SO-2`)
`Submitted`	`Observed`	A provisional observation names the leg
`Submitted`	`Expired`	The instruction’s explicit expiry has passed with no observation (`REQ-SL-4`)
`Submitted`, `Observed`	`Released`	A proved rejection: a final observation shows that the settlement layer refused the leg, so it cannot take effect (`REQ-OP-9`)
`Observed`	`Final`	The settlement layer’s finality point has passed the observation, and the canonical record still matches (`REQ-IN-3`)
`Observed`	`Orphaned`	The canonical record no longer matches (`REQ-IN-4`)
`Orphaned`	`Submitted`	The same instruction can still be included. It is watched again until it is included or it expires
`Orphaned`	`Released`	It was an inbound arrival, so aledgent originated nothing, and the observation is withdrawn. Or an outbound leg meets a proved rejection (`REQ-OP-9`)
`Final`	`Settled`	The settling posting is appended
`Expired`	`Released`	Non-inclusion is proven (`REQ-SL-4`), or a proved rejection (`REQ-OP-9`)
`Received`, `Accepted`, `Final`	`Needs-Review`	The operation’s deadline has passed (`REQ-OP-5`). For `Received`, that deadline is the bound of `REQ-CS-7`, and passing it is also an incident
`Reserved`, `Submitted`, `Observed`, `Orphaned`	`Needs-Review`	The operation’s deadline has passed, and its outcome is neither established nor provably impossible (`REQ-OP-5`, `REQ-OP-6`). Or a release was requested while an external leg may still execute, without proof that it cannot, and was refused with `ERR-ReleaseUnsafe` (`REQ-OP-9`). The refusal and the move are recorded together. This edge moves no value
`Expired`	`Needs-Review`	Non-inclusion cannot be proven (`REQ-OP-9`), or either condition of the row above
`Needs-Review`	`Settled` or `Released`	Resolved in up to three steps (`REQ-RC-5`): on the settlement adapter’s proof alone, with no human; on evidence one authority submits and the adapter verifies on its own; or, only when the adapter finds no proof in that evidence, a release that two distinct principals agree on, which raises an incident. Settling an external leg always needs the proof: two principals only release (`INV-10`). A human step carries a justification (`REQ-AT-3`)

An inbound arrival that aledgent did not originate enters at Observed. Earlier states do not apply to it. Received is the state of a command that was durably taken in but not yet decided. It has no balance effect. Its deadline is the bound of REQ-CS-7: a Received operation past it is an incident, and moves to Needs-Review. An operation’s kind, as set in §8.1, decides whether it reserves at all. A transfer does not. A reservation does. An outbound leg always does (REQ-SO-1).

A proved rejection is a final observation that the settlement layer refused an external leg’s instruction, where the settlement layer also shows that the transaction carrying the instruction was included, so the instruction cannot take effect by any other route. It is the “provably not executed” disposition of REQ-SA-4. It releases the reservation at once, with no review (REQ-OP-9).

A reversal is an operation of its own. Proposing it takes it to Accepted, with a deadline. Approval by a principal other than its proposer settles it, with one Reversal posting that references the postings it reverses (REQ-PO-3, REQ-OS-3). The operation it reverses stays Settled: no state follows a terminal one (INV-21). If value must be returned from an operation that an operator resolved out of Needs-Review, that too is a reversal operation.

The book effects below are normative.

State	Posting appended
`Received`, `Accepted`	none
`Reserved`	`Reserve`: debit available, credit reserved
`Submitted`, `Observed`, `Final`, `Expired`, `Orphaned`	none
`Settled`	Exactly one of these. `Transfer`, with no reservation: debit and credit available. `Capture`: debit reserved, credit the destination account. `Redeem`, for an outbound leg: debit reserved, credit the issuance counterparty. `Issue`, for an inbound leg: debit the issuance counterparty, credit the destination. `Reversal`, for a reversal operation: the mirror of the postings it reverses
`Released`, `Rejected`	If a reservation exists, `Release`: debit reserved, credit available. Otherwise none
`Needs-Review`	none. The value stays reserved

REQ-OP-1 For an external leg, no entry is written against the issuance counterparty before Final. Before that, there is only a reservation against the payer’s own account. So a revision of the settlement layer’s record costs nothing. An Orphaned operation needs no reversal, because nothing was posted.

REQ-OP-2 A reservation and its release or capture are the same object, matched by identity. A capture MUST NOT take its amount from a confirming caller. When an external leg executed for an amount that differs from the reservation, that MUST be a named, detected condition (ERR-AmountMismatch) with the difference posted explicitly. It is never a conflict that leaves a silent residue.

REQ-OP-3 Every transition MUST be idempotent on the tuple (operation, from state, to state, evidence). A repeated transition MUST be a no-op, never a second state change.

REQ-OP-4 Settled, Released and Rejected are terminal. A terminal operation MUST NOT transition. Every operation kind MUST reach the same set of terminal states. A terminal state MUST NOT differ by operation kind.

REQ-OP-5 Every non-terminal state MUST carry a deadline, and an operator path past it. Past its deadline, an operation MUST move to Needs-Review, where an operator resolves it through an authenticated, audited interface (resolve_operation, REQ-RC-1). An operation without a deadline MUST NOT be acceptable. A terminal state carries no deadline. Needs-Review’s own deadline is its review service level (REQ-OP-6): past it, the operation stays in Needs-Review and is escalated.

REQ-OP-6 Absence of evidence is not evidence of failure. aledgent MUST NOT fail, release or retry an operation on silence alone. Needs-Review is the correct state for an operation whose outcome cannot be established. It acts as terminal until a human resolves it. It MUST be reachable, delivered to a queue with an owner and a service level, and visible on a dashboard.

REQ-OP-7 aledgent MUST show Needs-Review and every other non-terminal state to its callers as an explicit outcome that is non-refunding and non-terminal. A caller MUST NOT be able to read an ambiguous reply as success.

REQ-OP-12 Callers MUST see at least these three non-terminal states, by notification (REQ-EV-1, REQ-EV-7) and by query; Received is also the acknowledgement’s state (REQ-CS-2). For each, aledgent states what has and has not happened, and the caller is expected to act as the table says.

State	Its plain name	What has happened, and what has not	What the caller is expected to do
`Received`	accepted	The command is durably held (`REQ-CS-2`). Nothing is decided, and no balance has changed	Wait for the decision. Do not act on the operation: no capture, release or submission. A retry under the same client key is safe and changes nothing
`Reserved`	reserved	The value is held for this operation and is no longer available to spend (`REQ-BA-4`). Nothing has reached its destination	Proceed: capture or release it, or hand off its external leg. Do not treat it as a payment made
`Final`	confirmed	The settlement layer’s finality point has passed the external leg’s observation, and the canonical record still matches (`REQ-IN-3`): the leg can no longer be revised. The settling posting is not yet appended, so the operation is not yet `Settled`	Treat the external leg as executed and irreversible. Do not release it, or submit again on it. Wait for `Settled`, which follows

“Accepted” here means acknowledged, not the state Accepted of the table above. “Confirmed” here is the plain name for finality having passed, the state Final. It is not a confirmation in §2’s sense: that is what Observed records, and it can still be withdrawn (REQ-IN-7). Every other transition is pushed too (REQ-EV-1), and every state stays visible by query (REQ-OP-7); this table states what a caller is expected to do for these three only.

REQ-OP-8 The metric that MUST be operationally visible is the age of the oldest non-terminal operation.

REQ-OP-9 A reservation MUST NOT be released on a timer alone, nor on a request alone. Every release of a reservation that has an external leg MUST be backed by proof that the external instruction can no longer take effect: proof of non-inclusion (REQ-SL-4), or a proved rejection (§5.6). Where that proof exists, the reservation MUST be released at once, with no manual step. A release requested without it, while the external leg may still execute, MUST be refused with ERR-ReleaseUnsafe, and the operation moves to Needs-Review (AC-C3.2); that move releases nothing. If the settlement layer can provide neither proof, expiry MUST lead to Needs-Review. A reservation with no external leg is released on request. The one release without proof is the third step of REQ-RC-5. The settlement adapter must first have checked submitted evidence and found no proof in it. Then two distinct principals must agree, and an incident is raised.

Trade-off, stated plainly. REQ-OP-9 means some reservations wait until a human clears them. Holders experience this as stuck money. The alternative is worse, and it has a name. Releasing early, while the external instruction may still execute, is a double-spend. This specification keeps the safety. It requires the queue, the owner and the service level that make “stuck” a bounded condition.

REQ-OP-10 Idempotency uses two distinct keys that MUST NOT be conflated. The first is a caller-facing client key. Its uniqueness domain is the integrating party: it is unique within (integrating party, surface, key), where the integrating party is the one the initiating principal belongs to, or the principal itself, where it belongs to none (REQ-ID-7). It never expires, and it is stored with the canonical response. The second is a service-derived operation reference. It is permanently unique across the whole deployment. Callers never supply it, and nothing parses it. A client key MUST NOT be able to collide with another integrating party’s key. Within one integrating party, the request a key identifies includes its initiating principal: the same key from another of its principals is a different request. A repeat of the same key with a different request MUST be refused (ERR-ClientKeyReused); from another principal of the same integrating party it is refused too, and never answered with the first principal’s reply. Such a collision counts as an integration failure of the integrating party, which keeps its principals’ keys apart.

REQ-OP-11 Idempotency MUST be mandatory on every value-moving submission, and it MUST fail closed. If a caller supplies no key, aledgent MUST derive one from the semantic identity of the request and return it. A key MUST NOT contain a timestamp or any other value that changes between retries.

5.7 External legs: observation, confirmation, finality, settlement

Observation {
    coordinate:  Coordinate     // unique and stable within the settlement layer
    kind:        EventKind
    payload:     Evidence
    observed_at: Time
    finality:    Provisional | Final
}

REQ-IN-1 An observation is identified by its coordinate, and aledgent MUST deduplicate on the coordinate. It MUST NOT deduplicate on a hash of the submitted instruction. That hash stays the same when an instruction is re-included, so a re-included instruction would be counted twice.

REQ-IN-2 A caller, including the settlement adapter, MAY state that an event occurred at a coordinate. It MUST NOT state that an operation succeeded, failed or settled. aledgent derives the status.

REQ-IN-3 Promotion to Final requires two independent facts. First, the settlement layer’s finality point has passed the observation’s position. Second, its canonical record at that position still matches what was observed. Neither fact is enough alone. The second one catches an observation recorded before a fork resolved.

REQ-IN-4 A provisional observation MUST be re-verified on every later observation cycle until it is Final. On a mismatch, the operation becomes Orphaned.

REQ-IN-5 aledgent MUST monitor observation completeness, not only observation. A periodic re-scan MUST compare what the settlement layer recorded with what aledgent ingested. A difference MUST raise an incident.

REQ-IN-6 When two sources can observe the same external event, exactly one of them MUST be authoritative for aledgent’s book. A second source MAY corroborate and MUST NOT write.

REQ-IN-7 Confirmed, Final and Settled are three distinct conditions. They MUST NOT be conflated in any surface, status vocabulary or timestamp.

5.8 Outbound legs

REQ-SO-1 An outbound leg MUST NOT be executable on any path that has not reserved first. There MUST be exactly one route from intent to external execution, and it MUST pass through the reservation.

REQ-SO-2 aledgent MUST assemble its own external instructions. The composition submitted to the settlement layer MUST be aledgent’s. A caller never submits a composite external instruction: a multi-leg submission is internal (REQ-CS-10).

REQ-SO-3 When several legs share one external instruction, each leg’s outcome MUST be determinable on its own from the settlement layer’s own record, by identity and not by position. The failure reason reported MUST be the settlement layer’s own reason, never a placeholder.

REQ-SO-4 An outbound operation whose destination outcome is unknown MUST resolve as non-terminal, never as failed. A failure tells aledgent to release. Releasing value that is sitting on the settlement layer is wrong twice.

5.9 Authority

Authority {
    principal:  PrincipalRef
    account:    AccountId | Asset (for issuance authority) | IdentityId (to open its accounts)
    grants:     [OperationKind]
    bounds:     Bounds          // per-operation, per-window, per-asset, per-counterparty
    expires:    Option<Time>
    revoked:    Option<Time>
}

REQ-AU-1 An operation MUST be refused unless its initiating principal holds an authority that covers its kind, its account and its bounds. Authorisation MUST fail closed: an authority that cannot be evaluated counts as absent.

REQ-AU-2 Authority is scoped and bounded by construction. A grant that names an account but sets no bound on what may be done with it MUST NOT be expressible.

REQ-AU-3 Revocation MUST take effect for every credential derived from the revoked authority, including credentials already issued, within the bound of NFR-20, measured from the revocation’s commit. A revocation that waits for an expiry is not a revocation. The bound MUST be declared in the assurance level (REQ-AR-5).

Trade-off, stated plainly. For up to NFR-20’s bound after a revocation commits, the revoked authority can still be used. What it can do in that time is bounded by the grant itself, because every grant has a bound (REQ-AU-2). A holder who revokes an agent mid-spend should expect the agent’s last operations inside the bound to stand (amendment 0012).

REQ-AU-4 A credential MUST NOT be able to change its own kind or widen its own scope. Narrowing MUST be permitted. Widening MUST be structurally impossible, not merely checked.

REQ-AU-5 Operator authority MUST be bounded. It MUST NOT be a single capability that can do anything to any account. It MUST be split by operation kind. It MUST be usable only against accounts in delegated custody. A grant over every account in delegated custody MUST NOT cover an account the operator’s own identity owns: such an account is reached only by a grant that names it. Amendment 0025, clause R3 (ruling au4-q2). The bound MUST be enforced where the authority is checked, not declared in configuration.

REQ-AU-6 Custody mode is a property of the account. In owned custody, no operator authority exists over the account, and aledgent MUST NOT be able to move its value. In delegated custody, the operator can move it, under REQ-AU-5.

REQ-AU-7 Every use of authority MUST record which authority was used and by which principal. The authority is one of: owner, delegated, operator or issuance. “The operator acted” MUST be distinguishable from “the holder acted”.

REQ-AU-8 A credential MUST NOT appear in a log, a URL, a query string, an error message or a default in source code. A deployment MUST fail to start rather than fall back to a default credential.

REQ-AU-9 Every deployment that offers owned custody MUST have a way to recover authority over an owned-custody account. That recovery MUST be one of the mechanisms of REQ-AU-15–REQ-AU-18. If the operator can use a recovery mechanism alone, it is operator authority under another name. It MUST NOT be presented as owned custody. The holder MUST be shown which mechanisms apply to their account before they choose owned custody.

REQ-AU-15 Recovery authority. A deployment MUST designate a recovery authority, held by a principal distinct from the operator. A recovery MUST require that principal’s approval. The operator alone MUST NOT be able to complete a recovery. The recovery authority alone MUST NOT be able to move value or act on an account outside a recovery.

REQ-AU-16 Delay and cancellation. Every recovery and every succession MUST have a stated delay before it takes effect. During that delay the holder can cancel it with an existing credential, through cancel_recovery. Only that cancels it: ordinary use of a credential does not. The pending recovery MUST be visible to every authority holder of the account (INV-20). Completion MUST be an audited operation, attributed to every principal that approved it (REQ-AT-1, REQ-AU-7).

REQ-AU-17 Successor. A holder MAY name a successor, using their own credential. After a stated delay, the successor MAY claim the account, under REQ-AU-16. Naming and claiming are audited. A claim gives owner authority to the successor and ends the previous holder’s owner authority. A claim also revokes the delegated authorities the previous holder granted over the account; the successor grants again. A recovery, by contrast, keeps them (REQ-AU-14).

REQ-AU-18 Holder-held recovery credential. A deployment MAY let a holder register an extra credential, kept away from their everyday devices. Presenting it counts as owner authority and has no delay. It is a convenience, never the only recovery mechanism.

REQ-AU-19 Guardian-threshold recovery is NOT offered. In that model a holder chooses a set of principals, and a certain number of them have to agree. A recovery model that no holder can administer is not a recovery model.

REQ-AU-20 Credentials are a set, not a unit. An identity holds a set of credentials. Each credential belongs to exactly one identity. Owner authority over any account the identity owns MAY be exercised by any credential in the set. The exception: the holder MAY limit a credential to a subset of their accounts. Adding or removing a credential MUST require an existing credential of the set, or a completed recovery (REQ-AU-15, REQ-AU-16). A credential MAY also be added by an import (REQ-MG-7), and the first credential of an empty set by enrolment (REQ-AU-22). The identities principal MAY also add a credential to the set of an identity it manages, acting for it: an identity that is not the operator, not an agent, and holds no account in owned custody. It authorises the addition only: a credential that proves possession is proven by its own ceremony, and a holder-held recovery credential is never added this way. The addition is attributed to the identities principal’s authority and to the identity it acted for (REQ-AU-7). Amendment 0025, clause R2 (ruling pk-register). The challenge of a ceremony that adds a credential MAY name the identity whose set it is for; a proof over a challenge that names one identity MUST then be refused with ERR-CredentialInvalid for any other identity’s set, and a challenge that names none serves any set. Amendment 0027. An identity’s set is empty only from an opening under REQ-ID-8 until its first credential joins. Removing the identity’s last credential MUST be refused with ERR-NotAuthorised: outside a recovery, a holder cannot lock themselves out. A recovery reissues credentials into the set. A holder-held recovery credential (REQ-AU-18) is a member of the set, marked as such. Where a credential is stored, such as a device, a key file or a hardware token, is not a ledger fact.

REQ-AU-21 A credential held by an identity holder or by an agent MAY reach aledgent directly, as a service principal’s may. Every call, whoever holds its credential, enters through the one component that receives commands and queries (REQ-AR-7) and is authenticated there (NFR-7, REQ-AU-1). There is no other way in.

REQ-AU-22 Enrolment. An identity whose credential set is empty (REQ-ID-8) gains its first credential through an enrolment, in two steps.

The opener authorises it. A principal holding the operator’s authority to enrol opens an enrolment for the identity, with a justification (REQ-OS-1). It states which kinds of credential the enrolment accepts, among those the deployment accepts, and the accounts the credential will be scoped to, if not all the identity’s accounts. aledgent returns an enrolment secret, shown once and never again (REQ-AU-8). The integrating party hands it to the holder through its own client, after establishing who the holder is: that is the integrating party’s authority, not aledgent’s (§4.2).
The holder completes it. From their own device, the holder presents the enrolment secret and a proof of possession of the new credential, over a challenge aledgent issued for this enrolment. This step authenticates by what it carries. The holder needs no other credential.

On completion the credential joins the set, marked as enrolled, with the scope the enrolment stated. The completion is attributed to the opener’s authority and to the new credential (REQ-AU-7), audited (REQ-AT-1), notified to the opener (REQ-EV-1) and visible to every authority holder of the identity’s accounts (INV-20, REQ-OS-4).

Limits.

An enrolment is single-use. It expires at a time the deployment states, no later than one hour after it opens. An expired, used or cancelled enrolment completes nothing.
An identity has at most one open enrolment. Opening another cancels the first.
Each enrolment allows a bounded number of failed completions, stated by the deployment. Past it, the enrolment is cancelled.
Opening or completing an enrolment MUST be refused with ERR-NotAuthorised once the identity’s set holds any credential. From then on, credentials are added as REQ-AU-20 says.
A secret-shaped credential that aledgent itself draws is not enrolled: enrolment carries only credentials whose holder proves possession of a key aledgent never sees.
The opener MAY cancel an open enrolment.
An enrolled credential proves nothing about custody by being enrolled. Before it takes an account into owned custody, it MUST be proven to work (REQ-AU-13).

A refusal names ERR-NotAuthorised (no authority, a set not empty, an identity not active), ERR-CredentialInvalid (a secret or proof that does not verify, a credential of a kind the enrolment does not accept, an expired, used or cancelled enrolment) or ERR-JustificationRequired.

Trade-off, stated plainly. The first credential carries the trust of the enrolment’s opener, as an imported one carries the import’s (REQ-MG-8). aledgent proves that whoever completed the enrolment holds the credential. It cannot prove that this person is the holder the integrating party meant: the integrating party is the authority for that, and the enrolment’s record names who opened it.

REQ-AU-10 Issuance authority (REQ-AS-6) is authority over an asset, not over an account. It MUST be bounded like any other authority, per window and per asset. It MUST be revocable. Every use of it MUST be traceable to who did it (REQ-AU-7).

REQ-AU-11 An account MAY change custody mode after opening, in either direction, without being closed and reopened. The change is an operation. It is:

idempotent on a client key (REQ-OP-11);
attributed (REQ-AU-7);
audited (REQ-AT-1);
visible to every authority holder of the account (INV-20).

REQ-AU-12 Owned → delegated gives the operator a power it did not have. It MUST be initiated with the holder’s own credential and MUST NOT be initiable by the operator.

REQ-AU-13 Delegated → owned removes operator authority. Before the change takes effect, it MUST require that a holder credential exists and has been proven to work. Operations already reserved run to a terminal state under the authority that started them (REQ-OP-9). A standing encumbrance placed under operator authority MUST be lifted before the change takes effect, or carried over explicitly with the holder’s consent.

REQ-AU-14 A custody-mode change does not affect delegated authorities that the holder granted, such as agents and members.

5.10 Anchoring and checkpoints

REQ-PR-7 A checkpoint MUST commit to every entry up to and including a stated sequence, and to nothing else. This makes “what was anchored” unambiguous.

REQ-PR-8 For every anchor, aledgent MUST record whether its publication reached finality. An anchor that was submitted but not observed as final MUST NOT be cited as establishing anything.

REQ-PR-9 Anchoring MUST NOT be on the critical path of any holder’s operation. An anchoring outage reduces provability. It MUST NOT reduce availability.

REQ-PR-10 Every checkpoint MUST name the construction of the state commitment it carries, and its anchor MUST bind that name, so that a recipient checking a disclosure against an anchor knows which construction a proof against the anchored state uses. A change of construction MUST NOT make an earlier anchor uncheckable: aledgent MUST keep the means to check a proof against every construction it has anchored in. Ruled by the owner on 2026-10-05 (amendment 0019).

REQ-PR-11 A change of construction is a migration. The construction of the state commitment MAY change only through an input of its own, made by a code version that knows both constructions. The migration MUST be deterministic: the same state in the old construction always gives the same state in the new. It changes no leaf, no balance and no identifier. The checkpoint at the migration’s input MUST carry the root in both constructions, and its anchor MUST bind both, so that the earlier anchors and the later ones are linked by one anchored fact. Every checkpoint before it names the old construction, every one after it the new. Ruled by the owner on 2026-10-08 (amendment 0023).

5.11 Audit trail

REQ-AT-1 Each of these MUST produce an audit record that names the principal, the time, the subject, and the justification where one is required:

every value-moving operation;
every authority change;
every privileged read;
every operator intervention;
every disclosure.

REQ-AT-2 The audit trail MUST be append-only. It MUST be retained separately from the service’s operational storage (NFR-6). Then a compromise of the service cannot silently erase the evidence of it.

When the book has more than one writer (REQ-RT-13), each writer’s audit records reach the one audit trail as messages, in that writer’s sequence. The trail records, for every writer, the last sequence it holds, so that a record not yet arrived is a visible gap, never a silent one. Each writer’s record of a commit carries its stream heads at that commit (REQ-RT-14).

REQ-AT-3 An operator intervention MUST be a first-class, authenticated, audited operation with its own authority. Direct changes to storage MUST NOT be a recovery mechanism. A control that seems to enforce something but does not is worse than no control, because it passes review.

5.12 Migration

REQ-MG-7 Credential import. A deployment that brings holders from a prior system MAY import their existing credentials into their identities’ sets. A holder then keeps proving possession with what they already hold.

An import is an operator operation (REQ-OS-1). It has its own authority, a required justification and an audit record (REQ-AT-1), and it is attributed to the operator (REQ-AU-7).
It carries public material only, never a secret (REQ-AU-8).
Each imported credential becomes a member of the identity’s set (REQ-AU-20), marked as imported. It has the scope the import states, which MUST name only accounts the identity owns.
The deployment MUST declare which credentials it accepts for import. Any other credential MUST be refused with ERR-CredentialInvalid. So MUST a credential already in the set.
The import MUST be visible to every authority holder of the identity’s accounts (INV-20, REQ-OS-4).

REQ-MG-8 An import MUST NOT give the operator a power it does not already hold.

It MUST be refused with ERR-NotAuthorised while any account of the identity is in owned custody (REQ-AU-6, REQ-AU-9).
An imported credential proves nothing by being imported. Before it takes an account into owned custody, it MUST be proven to work, like any other credential (REQ-AU-13).

Trade-off, stated plainly. An imported credential carries the trust of the import. In the same way, the first credential the operator gives an identity at open_identity carries the trust of the opening. Only the holder’s proof that it works (REQ-AU-13) shows that the holder holds it, not the operator.

REQ-MG-1 to REQ-MG-6 were withdrawn and are not reused:

ID	Withdrawn by	What survives of it
`REQ-MG-1`	Amendment 0001	The initial-state load (`REQ-RC-4`)
`REQ-MG-2`	Amendment 0001	—
`REQ-MG-3`	Amendment 0001	The initial-state load (`REQ-RC-4`)
`REQ-MG-4`	Amendment 0001	—
`REQ-MG-5`	Amendment 0001	Export and re-import (`REQ-RC-3`)
`REQ-MG-6`	Amendment 0001	—