Application state-machine companion

Status

Draft normative refinement

Specification

Revision 14, 2026-09-22

Library baseline

Commonware v2026.9.0

This companion refines SPECIFICATION.md, especially sections 5, 7–13, 16, and 18. The specification takes precedence. These are semantic transition tables, not a second command catalog or wire format. The seventeen command tags remain unchanged. Canonical discriminants, field encodings, cryptographic profiles, and byte vectors belong to the encoding artifact; measured limits and prices belong to calibration. No implementation may invent those values from these tables. The client API companion describes how clients prepare and reconcile these transitions.

1. Execution contract

All guards evaluate under the executing block's Rules, consensus timestamp, and branch state. The block overlay initially reflects the supplied parent batches plus any activation installer. Commands execute in flat order. Every table row below also inherits the following steps:

1. Bound and decode the complete envelope with exact consumption; check chain, command variant, ruleset, price schedule, and payload limits. Reserve worst-case bytes, work, and gross creations before expensive verification. A reservation includes indirect reads, refund ledgers, and every replaceable proof. A pause flag is evaluated from Rules, never from a local service setting.
2. Create an isolated command change set over the block overlay. Read each key at most once from the underlying branch, then use the overlay for subsequent reads. Raw records remain available even when an effective read treats them as unauthorized, non-resolving, or expired.
3. Authenticate the actor and required capability. Root witnesses use the account's current commitment and version; every approval is a key approval. Delegates must match generation, issuing epoch, class, scope, and time window. Check sequence strictly above its slot's high-water mark and any signed deadline. System commands instead use their settlement or governance guards, not an account replay slot.
4. Check project control/grant context and parent-counter guards at command entry. Apply the variant's guards and operations in the order specified below. Repeated ref operations see earlier operations in this command. Root authorization never bypasses project authority.
5. Accumulate non-refundable fees, new deposit locks, and stored-payer discharges by ledger key. Require gross fees plus new locks ≤ signed max_charge for charged account commands. Netting a discharge is permitted only for the resulting balance of its own payer; every final ledger must satisfy spent + locked ≤ credited. Neither refunds nor collapsed writes reduce resource reservations. System exceptions follow specification section 10.3.
6. On success, advance the applicable replay mark, produce bounded event data, and merge all writes, counters, ledger deltas, membership appends, and events into the block overlay together. On failure, discard all of them. A proposer can skip a failed candidate; a verifier rejects a block containing one. Transient source failures stay pending; corruption is fatal-local.

The consensus_profile comes from the authenticated GenesisChainSpec, never from a process flag, RPC claim, or command. The two known semantic variants are FixedEpochZeroV1 and DynamicReshareV1; canonical field layout and discriminants remain format-contract work. For the fixed profile, every execution entry point first requires the block, round, proposal, vote, certificate, recovered context, and certified ancestry to name epoch zero and a height in 0..=u64::MAX - 1. It rejects a nonzero epoch before any signing-scheme lookup; a constant-provider success cannot authorize the scope. DynamicReshareV1 retains the production epoch, DKG, membership, and release behavior specified elsewhere.

At block completion, submit final writes and staged indices to QMDB and merkleize each of the three members once, including empty membership batches. Append the history leaf and use the specified metadata and membership floor. Re-derive all header fields, including the canonical current root. Never persist, publish events, or make external calls with side effects during speculative execution. Durability barriers, marshal acknowledgements, and restart reconciliation belong to glue.

valid_before_timestamp_ms, when present, is an exclusive bound: execution at or after it is invalid. This uses consensus time, just like key and offer expiry. All counter and timestamp arithmetic is checked, and the forbidden maximum is rejected before effects merge.

Launch duration arithmetic uses fixed elapsed time, never calendar arithmetic: one day is 86,400,000 milliseconds and one year is 365 days. Thus the key term is 730 days, the username term is 365 days, the rename cooldown is 28 days, and both username grace and offer expiry are 30 days. The username horizon remains a calibrated parameter; the companion fixes no price or work weight.

2. Record access notation and bounds

The notation below names semantic identities; actual state keys use the family's registered digest formula from specification section 9.2. Every loaded value must carry the matching identity.

Every account command has a common access set: L(actor), A(actor), the signing K when applicable. The replay write is to A(actor) for root or to its signing K for a delegate. System commands omit this set unless a row explicitly names a beneficiary ledger. INIT_ACCOUNT uses its special genesis witness.

Every operation authorized over an existing project adds P(p) and, for a non-controller actor, G(p,actor); metadata or slug work adds M(p). PROJECT_CREATE uses its absence checks instead of authority over an existing project. Acceptance uses the named destination's authority, not a writer role in the source project. Read/write sets in the next tables are additional to these common sets. All price, capability, signature, and pause checks are inherited even when not repeated in a row.

A deletion/replacement additionally reads and writes L(raw.deposit_payer) for each deposited record it consumes. These ledgers may coincide with each other or the actor's ledger; deltas must accumulate, not overwrite. Replacement always reserves one gross creation and charges the current creation fee/deposit, while discharging exactly the old stored amount. A read-only expiry test never deletes or unlocks anything.

Let r be the bounded number of ref operations, c the commitment count, and w the number of CREATE/SET operations (w ≤ r). PUSH reads at most r distinct ref keys and at most r additional payer ledgers; it appends c membership leaves and verifies w witnesses. No row discovers children by enumerating a project, account, history log, or database index. Each witness has its own bounded proof-node budget; source reads do not create validity-state keys.

The creation bounds below count gross creations, including same-key replacements. Base byte and work reservations are compositional: the common access set plus every optional branch's maximum, not the branch observed after execution. Calibration assigns weights; it cannot omit a branch.

3. Account and delegated-key transitions

INIT initializes counters/epochs at their specified bases and records the accepted root sequence; subsequent configuration preserves them. Authorize consumes the account's next key allocation value and advances it. Its fresh generation cannot inherit the predecessor's replay mark. Renew preserves its mark. All leaves every raw key and its locked deposit resident; it emits only the old/new epoch. Cleanup never reduces the permanent counters. AccountUsername is initialized lazily on the first operation that needs to mutate that account's name allocation/pointer state, counted and priced as a permanent creation in section 6 below.

3.1 Initial values

Initial values are protocol rules, never Rust defaults. Every increment rejects exhaustion before mutation. The generic bases below do not replace a specifically allocated predecessor revision.

Makechain persists its own genesis configuration commitment as an authorization commitment. It does not copy Tempo's storage layout or its counterfactual no-record convention. Address derivation, configuration preimages, owner ordering and upgrade salt still follow the pinned account reference.

4. Project transitions

Project mutation-counter allocations supply fresh ref revisions, grant generations, offer revisions, and slug incarnations. Every allocation consumes then advances the counter; no child operation resets it. Parent absence guards are checked once at command entry. Controller authority comes from P.owner, never a role record. Grants issued before a transfer remain physically resident but confer no authority; neither transfer nor its event enumerates them. Their deposits remain with their payers. A grant's individual generation and its issuing control generation are different fields.

Metadata is last-write-wins under the signed authority context; there is no implicit metadata CAS. The old slug key comes from the executing M/P records. Transfer may choose a replacement slug when the old spelling is taken in the destination namespace. The acting destination pays the new claim. Project creation's origin is an assertion only and neither appends membership nor establishes a source project's endorsement. Roles, status, and transfers never confer object-retrieval rights.

5. PUSH transitions

PUSH is one account command, regardless of its number of commitment entries or ref operations. Resolve project authority and scope, require ACTIVE, and check the command-entry parent guard if any CREATE exists. All commitments and non-delete targets must match the project's fixed scheme and registered native id length. Validate signed RefNames as specified in specification section 8.3; derive digest keys locally. Do not accept an independently supplied name digest or display name as authority.

Unsigned evidence has exactly w witnesses, paired with CREATE/SET in operation order. DELETE consumes none. No surplus, missing, or reordered evidence is accepted. A SameCommand witness must index this command's commitment array, even if another command earlier in the block appended the same leaf. Location/Proof eligibility uses the executing parent's canonical window/ancestry, not a node's current retained bytes or another command's new append. Validate every target witness against Keccak256(project_id || scheme_id || native_id) under specification section 8.3.

Append commitments in array order, tentatively assigning locations after all earlier successful commands' appends. Then process refs in list order:

Repeated names are legal and their operations are sequential; delete-then-create allocates a new revision and pays a new fee/deposit. A later operation on a revision allocated earlier in the command must name that actual revision; execution never repairs signed expectations. A SET no-op still pays ordinary bytes/work and advances the command replay mark. Commitment-only and ref-only pushes are supported. Each commitment occurrence is retained, including duplicates. No scan checks ancestry, fast-forward, deduplication, object availability, or object signatures.

Failure anywhere discards all tentative appends, allocations, refunds, writes, and events. Success emits CommandFinalized, CommitmentAdded in commitment order, and RefsChanged, with bounded deposit lists from logical execution. A publication receipt exists only for a commitment array entry; ref operations alone are proven through ordinary command inclusion or current-state proofs.

6. Username transitions

Every USERNAME_CLAIM variant first rejects when resolved username_claims_paused is true. USERNAME_RELEASE is unaffected. Every row uses root or unscoped ACCOUNT capability. A resident lease guard is its full incarnation (owner_account, allocated_counter) plus revision, including post-reservation replacement. A fresh claim also binds the actor's name allocation counter. A missing N is interpreted at its initial counter base solely for this guard, and created atomically with its first mutation. No absence proof is implied; a stale service lookup loses at execution.

Common additional access set: requested U; actor N; the U named by actor N, if any, to decide whether another name resolves; the former owner's N when replacing a lease; and stored-payer ledgers when replacing. Rename may touch a source and destination U but never searches for other owned names. At most two U keys and two N keys are involved, plus at most one old-payer ledger. The actor's N creation, if required, adds one permanent gross creation to the row's bound.

A released or naturally expired name never resolves during grace. At the reservation deadline a new owner may claim and RECLAIM may remove it. Extension is not restoration: a third party cannot re-enable a name in grace. Release already in grace is invalid and cannot extend its reservation. Rename forfeits the source's unused term; there is no credit refund. Replacing/reclaiming a lease clears the old owner's pointer only when both the name and incarnation match. Allocation counters and cooldown metadata always survive.

7. RECLAIM

RECLAIM first rejects when resolved reclaims_paused is true. It is one account command targeting exactly one stale record. The caller uses root or an unscoped key of WRITE or above; no target authority is required. Read one raw target and require its expected incarnation, plus revision for UsernameLease. Reclaim enabled under Rules and the following stale predicate are both required:

All four discharge the stored amount to the stored payer. Missing target, moved incarnation, non-stale target, Ref, SlugClaim, or a permanent family is invalid. Caller pays bytes/work, receives no bounty, and cannot choose the refund recipient. The target's parent and payer are taken from the raw verified identity, not unchecked request fields. No row allocates a new record. If the target is the caller's own invalid key, it cannot authenticate this reclaim; another usable signing slot is required. Reclaim does not update the target's keychain revision.

8. System commands and block transitions

These rows incorporate the exact guards of specification sections 13, 16, and 18 by reference; this companion does not create an alternate governance, DKG, or settlement state machine.

Governance nonce/revision checks and updates are in the governed schedule's state, never an account replay slot. The canonical schema must expose directly addressable tail, pending, and reserved-key records so these guards are point reads with bounded participants; a history search is not an implementation of validity. Schedule entry creation counts are reserved from the bounded entry shape. Root computations, DKG payloads, activation installers/markers, and epoch lock-in remain block-level effects, not extra command tags. An installer runs before commands and its marker and writes share the validity batch; resources are reserved before command selection. Every monetary frontier survives settlement anchor replacement.

In FixedEpochZeroV1, the chainspec commits the public trusted-dealer output, normal epoch-zero EpochInfo, and ordered seven-validator committee; the genesis block reproduces that public output and binds its digest. The output names those seven players with total = 7 and required = quorum<N3f1>(7) = 5. Startup requires the selected share to match that output and participant position. Every header and body, including genesis where those options occur, must encode dealer_log, dkg_outcome, and their commitments as canonical None; Some(empty) is invalid. The DKG bootstrap/orchestrator/reshare transitions do not run. This removes only DKG boundary-history retention; ordinary marshal, execution, restart, proof, exporter, and recovery retention remain unchanged.

The fixed profile's release overrides apply to every scheduling path: ordinary activation, deferral, cancellation, and emergency activation cannot introduce a consensus-critical release. EMERGENCY_ACTIVATE already rejects that class under its ordinary rules. Non-critical parameter, format-preserving, and versioned-state releases keep the normal guards and activation-height semantics in the table. A profile, epoch construction, committee, threshold output/group key, canonical-encoding, or chain-identity change is reset-class and cannot be described as non-critical.

No profile has genesis credit allocations. Every deployed devnet and qualification testnet pins a complete Tempo Moderato settlement profile; mainnet under DynamicReshareV1 pins the complete Tempo Mainnet profile. IMPORT_CREDITS.Credit always verifies a real certified Tempo header and storage proof through the production verifier; Refresh verifies a real strictly newer certified header and carries no storage proof. The selected contract is a dedicated beneficiary-cumulative immutable, non-proxy deployment on each network, leaving the existing deployment intact; its slot-zero uint256 mapping and ABI are defined in settlement interface, while deployment runtime code hashes and authentic fixtures remain external inputs. The existing global-issuance contract cannot satisfy this row. Consequently, the first funded flow is IMPORT_CREDITS.Credit, which creates the ledger, followed by INIT_ACCOUNT; a missing settlement deployment or proof blocks this flow rather than enabling a Makechain-side faucet or mint, mock proof, test-credit realm, or genesis-funded exception. Acquiring the accepted asset from a Tempo Moderato faucet and depositing it into the pinned contract still uses the normal external deposit and proof path.

All monetary fields use unsigned 256-bit Amount, exactly 32 big-endian bytes on the Makechain wire. Checked arithmetic covers fees, deposits, totals, and the conservation sum spent + locked. Credit and refresh certificates must satisfy the installed identity's from_epoch; only bootstrap or release activation replaces that floor, never a submitted proof or refresh.

9. Commonware integration and qualification

The following source contracts were checked at tag v2026.9.0 (paths relative to Commonware):

First qualification milestone: use the same rules executor through propose, verify, and apply under the deterministic runtime and real database adapters. Start without genesis credits, apply a real certified Tempo Moderato cumulative-deposit fixture through IMPORT_CREDITS.Credit, and only then run INIT_ACCOUNT and the application slice. Produce a real receipt checked by the reference verifier. Persist and restart using glue's database-set barriers and SyncPlan, including a restart with members at different durable progress points. The funded slice remains blocked until the settlement layout, code-identity policy, deployment, and captured proof exist; no synthetic substitute earns conformance credit. Broader services follow this slice.

Required scenarios, to become executable tests when code exists:

No test result is claimed by this table. Encoding conformance and numeric qualification remain required before implementation can be considered launch-ready.