8. Normative behaviour

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

Behavioural contracts only. Names are examples. Pre- and post-conditions bind. Every command is subject to:

REQ-AU-1 (authority);
REQ-OP-10 and REQ-OP-11 (idempotency);
REQ-PN-1 (attribution);
REQ-CS-4 (refusals).

8.1 Commands

Command	Pre-conditions	Post-conditions
`open_identity`	Kind stated. For an agent, the identity it acts for. A first credential, unless the opener holds the operator’s authority to open identities, which MAY open it with an empty set (`REQ-ID-8`)	Identity exists (`REQ-AG-1` for agents). Its set holds the first credential, or is empty. Otherwise `ERR-NotAuthorised` or `ERR-CredentialInvalid`
`open_account`	Identity active; kind and custody stated. Opened by the identities principal, by the identity itself, or under a delegated grant over the identity naming `open_account`, which opens a customer account in delegated custody only (`REQ-ID-6`). Owned custody only for an identity whose credential set is not empty (`REQ-ID-8`)	Account exists, is addressable and can be credited at once (`INV-9`). A repeat with the same client key returns the same account
`close_account`	All balances zero, in every asset and balance kind	Account `Closed`, never deleted (`REQ-LA-4`). Otherwise `ERR-AccountNotEmpty`
`grant_authority`	Grantor holds the authority being granted, or owns the account. At least one bound stated. A grant over an identity is delegated, names `open_account` (and MAY name the kinds its holder delegates over that identity’s accounts), and is made by the identity or the identities principal; a grant over an account MAY narrow one over its owner (`REQ-ID-6`)	Authority exists, is bounded and can be revoked (`REQ-AU-2`). Otherwise `ERR-UnboundedGrant`
`delegate_custody`	Account owned. Started with the holder’s own credential	Custody `Delegated`. Operator authority exists after that (`REQ-AU-12`). Otherwise `ERR-NotAuthorised`
`reclaim_custody`	Account delegated. Holder credential proven	Custody `Owned`. No operator authority remains. In-flight operations finish (`REQ-AU-13`). Otherwise `ERR-CredentialInvalid`
`initiate_recovery`	Account owned. Requested by the holder out of band, or by the recovery authority	Pending recovery recorded with its delay, and visible to authority holders (`REQ-AU-16`)
`cancel_recovery`	A pending recovery. The holder’s existing credential	Recovery cancelled and audited
`complete_recovery`	Delay elapsed. Recovery authority approved	New holder credential issued; the old one stops working. Attributed to every approver (`REQ-AU-15`, `REQ-AU-16`). Otherwise `ERR-RecoveryNotElapsed` or `ERR-NotAuthorised`
`name_successor` / `claim_succession`	Holder credential. Then the delay elapsed without cancellation	Successor recorded. On claim, owner authority passes to the successor (`REQ-AU-17`)
`register_credential` / `remove_credential`	An existing credential of the identity, or a completed recovery. `register_credential` also by the identities principal acting for an identity it manages (`REQ-AU-20`, amendment 0025 R2)	The identity’s credential set changes. Its scope to accounts MAY be stated (`REQ-AU-20`). Otherwise `ERR-NotAuthorised`
`import_credentials`	Operator authority for imports; a justification; the identity active, and none of its accounts in owned custody; each credential’s public material of a kind the deployment accepts, not already in the set, scoped within the identity’s accounts	Each credential a member of the set, marked imported. Audit record. Shown to every authority holder (`REQ-MG-7`, `REQ-MG-8`). Otherwise `ERR-NotAuthorised`, `ERR-CredentialInvalid` or `ERR-JustificationRequired`
`open_enrolment` / `cancel_enrolment`	Operator authority to enrol; a justification; the identity active, with an empty credential set; accepted credential kinds among the deployment’s	An enrolment open until it expires, with its secret returned once; or cancelled. Audit record (`REQ-AU-22`). Otherwise `ERR-NotAuthorised` or `ERR-JustificationRequired`
`complete_enrolment`	An open enrolment’s secret; a proof of possession of a credential of an accepted kind, over the enrolment’s challenge	The credential a member of the set, marked enrolled, with the enrolment’s scope. The enrolment closed. Attributed, audited, notified and shown to every authority holder (`REQ-AU-22`). Otherwise `ERR-CredentialInvalid` or `ERR-NotAuthorised`
`set_answering`	The principal itself, or another principal of its integrating party. A wait within the bound of `REQ-CS-7`	The principal’s `transfer` and `reserve` taken in from now on are answered as the setting says (`REQ-CS-9`). Otherwise `ERR-NotAuthorised`
`set_report_cadence`	The recipient’s own authority; a cadence between one hour and one day, or none	Reservation reports delivered at that cadence from the next period, or no longer (`REQ-EV-8`)
`revoke_authority`	Authority exists	Authority and every credential derived from it stop immediately (`REQ-AU-3`)
`transfer`	Both accounts active; available ≥ amount; asset registered	One posting, final on acceptance. Available reduced atomically (`INV-1`, `INV-3`)
`reserve`	Account active; available ≥ amount	`Reserve` posting; available reduced. Operation `Reserved` with a deadline (`REQ-OP-5`)
`capture`	Operation `Reserved` or `Final`; amount ≤ reserved	`Capture` posting. Any difference returns to available (`REQ-OP-2`). Otherwise `ERR-AmountMismatch`
`release`	A reservation of this operation is open. With an external leg: proof that it cannot take effect, by non-inclusion or a proved rejection	`Release` posting; operation terminal (`REQ-OP-9`). Otherwise `ERR-ReleaseUnsafe`; where the external leg may still execute, the operation moves to `Needs-Review`, and no value moves (`AC-C3.2`)
`encumber` / `disencumber`	Operator authority; account active	Value moves between available and encumbered as a posting (`REQ-BA-1`)
`issue`	Issuance authority for the asset, within its bounds	`Issue` posting against the issuance counterparty. Trial balance unchanged (`REQ-AS-6`, `INV-5`)
`redeem`	Issuance authority for the asset; available ≥ amount	`Redeem` posting against the issuance counterparty (`REQ-AS-6`)
`submit_outbound`	A reservation exists for this operation; the adapter declares support	Instruction handed to the adapter with an expiry. Operation `Submitted` (`REQ-SO-1`, `REQ-SA-1`). Otherwise `ERR-UnsupportedLeg`
`record_observation`	Coordinate not seen before	Observation stored. aledgent derives the resulting state (`REQ-IN-2`); a proved rejection releases at once (`REQ-OP-9`). A duplicate coordinate is `ERR-ObservationDuplicate`
`resolve_operation`	Operation `Needs-Review`; operator authority; justification supplied; a proof the settlement adapter verified (`REQ-RC-5` steps 1 and 2), or, once the adapter found no proof in submitted evidence, a release that a second, distinct principal agrees to (step 3)	Operation `Settled` or `Released`; audit record written (`REQ-AT-3`). Without the proof: `ERR-ReleaseUnsafe` for a release, `ERR-EvidenceInsufficient` for a settlement, and the operation stays in `Needs-Review`. In step 3 the first principal’s proposal moves nothing. The second principal’s agreement releases the operation and raises an incident. The same principal twice is `ERR-ApprovalRequired`
`submit_evidence`	Operation `Needs-Review` with an external leg; resolution authority; justification supplied; a block and a transaction hash of the settlement layer	Audit record written (`REQ-AT-3`). Nothing moves. The settlement adapter fetches and verifies the evidence on its own. If it proves the outcome, aledgent applies it (`REQ-RC-5` step 2). If not, step 3 is open
`propose_reversal` / `approve_reversal`	Posting final. A proposer and a different approver, each holding its own reversal authority; a justification; the check of `REQ-RC-5`	A reversal operation: `Accepted` with a deadline when proposed, `Settled` with one `Reversal` posting that mirrors and references the reversed postings when approved. The reversed operation stays `Settled`. Incident raised (`REQ-RC-2`, `REQ-OS-3`, `REQ-PO-3`). An approval by the proposer is `ERR-ApprovalRequired`; a posting that fails the check is `ERR-EvidenceInsufficient`
`issue_disclosure`	The subject authorises it, or a legal obligation applies. The assertion is locally true	Disclosure issued, verifiable against a checkpoint (`REQ-DS-3`, `REQ-DS-4`)
`anchor_checkpoint`	Entries exist since the last checkpoint	Checkpoint committed and submitted. Cited only once final (`REQ-PR-8`)
`register_asset`	Operator authority; reviewed change	Asset registered with exactly one precision, book-only (`REQ-AS-1`, `REQ-AS-7`)
`bind_asset`	Issuance authority for the asset; a justification; the asset book-only; its identity on the settlement layer named	Asset `Binding`; the settlement layer asked to record the binding against the book’s outstanding balance. Once that is final, `Bound` (`REQ-AS-8`). Otherwise `ERR-NotAuthorised`, `ERR-UnsupportedLeg`, `ERR-SettlementLayerUnavailable` or `ERR-JustificationRequired`; a binding the layer refuses returns the asset to book-only
`register_integrating_party`	Operator authority; a justification; a party identifier not registered before; principals tied to no party	Party registered with its principals (`REQ-ID-7`). Audit record. Otherwise `ERR-NotAuthorised` or `ERR-JustificationRequired`
`register_alias`	Operator authority; a justification; the account held and not closed; an alias not registered before; a name that is not an archived identifier	The alias names the account, for good (`REQ-RC-7`). Audit record. Otherwise `ERR-NotAuthorised`, `ERR-UnknownAccount`, `ERR-AccountClosed`, `ERR-IdentifierArchived` or `ERR-JustificationRequired`
`tie_principal`	Operator authority; a justification; the party registered; the principal tied to no party	Principal tied to the party; from then on its client keys are the party’s (`REQ-OP-10`). Otherwise `ERR-NotAuthorised`
`load_opening_balances`	Operator authority; reconciliation to zero divergence recorded	One `Opening` posting per (account, asset) (`REQ-RC-4`)

Operation kinds. A command that submits an operation names its kind (§2):

Kind	Commands
transfer	`transfer`
reservation, capture, release	`reserve`, `capture`, `release`
withdrawal, deposit	`submit_outbound` (an outbound leg); an inbound arrival, through `record_observation`
issuance, redemption	`issue`, `redeem`
reversal	`propose_reversal` / `approve_reversal`
custody change	`delegate_custody`, `reclaim_custody`
credential change	`register_credential` / `remove_credential`, `import_credentials`, `open_enrolment` / `cancel_enrolment` / `complete_enrolment`
recovery	`initiate_recovery`, `cancel_recovery`, `complete_recovery`, `name_successor` / `claim_succession`
opening load	`load_opening_balances`

The other commands open identities and accounts, manage authority and the asset registry, issue disclosures, anchor checkpoints, or resolve an existing operation. They submit no operation of their own. encumber and disencumber serve US-C5, beyond V0 (DEF-11): the release that ships it names their kind.

8.2 Queries

Query	Behaviour
`balances(subject, [asset])`	Available, reserved, encumbered and total, per asset, from one consistent view. Subject MAY be an account or an identity (`REQ-BA-5`, `REQ-QR-2`)
`movements(subject, filters, cursor)`	Movements in sequence order, paged by cursor. Status comes from the posting kind (`REQ-PO-1`, `REQ-QR-5`)
`statement(subject, period)`	Opening, movements, closing. It balances exactly (`INV-6`)
`operation(reference)`	State, deadline, evidence, outcome, and the named error condition where refused
`assets()`	The registry: identity, precision, kind, status (`REQ-AS-1`)
`limits()`	What this deployment accepts in one command: the most legs of a multi-leg submission, and the largest pass-through data (`REQ-CS-10`, `REQ-PO-5`)
`open_reservations(subject, [asset], [before], cursor)`	Open reservations of an account, an identity, or the calling principal: aggregated per (account, asset) and itemised, from one consistent view that names its position. Only what the caller may see (`REQ-QR-7`, `REQ-QR-4`)
`trial_balance([asset])`	Sum of all entries per asset. It is exactly zero (`INV-5`)
`verify(disclosure)`	Whether a disclosure is consistent with a checkpoint (`REQ-DS-3`)
`assurance()`	Which invariants this deployment enforces rather than attests (`REQ-AR-5`)
`can_spend(account, asset, amount)`	No side effects. Returns a reason on refusal, never a bare boolean (`REQ-QR-3`)
`alias(source, name)`	The account the alias names, to a principal that reaches it; `ERR-UnknownAccount` otherwise; `ERR-IdentifierArchived` for an archived identifier (`REQ-RC-7`)
`grants(account)`	Every grant over the account, live and revoked: grantor, holder, terms, bounds, when granted and revoked. The operator’s and the owner’s (`REQ-RC-7`)
`account(account)`	The account’s owner, kind, custody, status and opening time. To whoever reaches it, the operator, the identities principal, and a holder of a live grant over its owner; `ERR-UnknownAccount` otherwise (`REQ-RC-7`, amendment 0028)
`grants(identity)`	The grants over the identity, live and revoked: grantor, holder, terms, bounds, parent, when granted and revoked. Every one to the identity itself, the operator and the identities principal; a holder’s own to any other principal; `ERR-NotAuthorised` to a principal that holds none (`REQ-RC-7`, amendment 0026)