0. How to read this document

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

This document specifies aledgent: what it is, what it guarantees, to whom, and under what conditions. It is normative and self-contained. It does not say how aledgent is built, which technologies implement it, or why the project exists. Those topics are outside this specification.

What each section answers

Section	Question it answers	Read it if you are…
§1 Purpose and scope	What problem aledgent solves, for whom, and where its boundary is	deciding whether aledgent fits a need
§2 Glossary	What each term used normatively means	anyone. Terms are used exactly as defined
§3 Parties	Who interacts with aledgent, in which role, with what powers	integrating, operating or auditing it
§4 Architecture	How responsibilities are separated, and what aledgent requires of its environment	implementing or reviewing the design
§5 Domain model	The objects aledgent holds and the rules that bind them	integrating or implementing
§6 User stories	What each party can do, with acceptance criteria	anyone. This is the behaviour, seen from outside
§7 Surface contracts	The boundaries other parties build against	integrating
§8 Normative behaviour	Every command and query, with pre- and post-conditions	integrating or implementing
§9 Invariants	What is true at all times, and which layer keeps it true	implementing. Read it twice
§10 Errors	Every named refusal	integrating
§11 Non-functional requirements	Latency, durability, privacy and operability bounds	implementing or operating
§12–§13 Deferred scope, non-goals	What is out, and why	anyone tempted to add something
§14 Open questions	What is undecided, and what each decision blocks	the owner
§15 Traceability and release scope	How stories, requirements and invariants map, and what the first release contains	planning

Normative language

The key words MUST, MUST NOT, SHOULD, SHOULD NOT and MAY are to be interpreted as described in RFC 2119. They have that meaning only in:

numbered requirements;
invariants;
contracts;
acceptance criteria;
tables marked normative.

Prose, rationale and “Trade-off, stated plainly” callouts explain a decision. They do not bind.

Identifiers

Prefix	Meaning
`US-*`	User story
`AC-*`	Acceptance criterion, scoped to its story
`REQ-*`	Normative requirement
`CTR-*`	Surface contract (§7)
`INV-*`	Invariant that MUST hold at all times
`ERR-*`	Named error condition
`NFR-*`	Non-functional requirement
`OQ-*`	Open question. One that blocks a V0 story or requirement MUST be closed before the V0 freeze, and any other before v1.0.0
`DEF-*`	Explicitly deferred scope

Identifiers are stable. Every family starts at 1 and is never renumbered. A withdrawn identifier is not reused. So a gap in a sequence means a withdrawal recorded in an amendment, never an omission.

The settlement layer

aledgent assumes exactly one external settlement layer. It is the network through which value enters and leaves aledgent, and on which aledgent anchors its state. This document defines the settlement layer only by the requirements it must satisfy (§4.4). In this text, “the settlement layer” means whatever satisfies those requirements, never a particular network.