Architecture validation and qualification plan

This plan maps each requirement to an owner, an interface-level observation, an acceptance criterion, and honest evidence status. A scenario definition, source inspection, compiling harness, or passing unit test is not production qualification for a network. Results change only through immutable run manifests that meet section 10.

The specification and companions define behavior. Architecture defines modules and semantic interfaces. Operations defines persistent ownership and Q1 crash cuts. Repository defines dependency, local-gate, deferred hosted-CI, and release rules. The canonical vector and fixture formats remain owned by encoding, with their inventory in data contracts.

1. Evidence vocabulary and module keys

Source review supports the stated external contract only. It does not establish Makechain assembly, correctness, crash safety, performance, or production readiness. In the tables, a reference such as SRC-CW; NOT RUN means exactly that.

Tests observe these interfaces and their durable/public outcomes. They do not assert private helper calls or require a generic mock wall around Commonware. Production adapters are replaced only at real external seams: transport, filesystem/crash control, cloud/object/query storage, Tempo fixture acquisition, and the deferred client journal.

2. Common harness contract

Every deterministic or persistent harness uses:

• canonical frozen inputs and the production codecs/verifiers for the enabled profile;
• explicit chain/genesis/profile/ruleset, seed, consensus time, runtime, pin set, and fault schedule;
• actual Commonware actors and the exact three-member database adapter when the claim crosses those seams; finality is a real threshold certificate, never a harness flag;
• real captured Tempo evidence for a positive import. Dev/test uses Moderato; mainnet uses Mainnet;
• bounded inputs, queues, clocks, work, and observation periods;
• typed invalid, pending, fatal-local, and service outcomes without conflation;
• an immutable result manifest on pass, failure, or inconclusive termination.

Deterministic Q1/Q2 harnesses may consume published reproducible synthetic shares/seeds only from the repository's exact TEST ONLY fixture allowlist. Persistent devnet/testnet/mainnet runs use operator-provisioned custody material that is never committed. Both paths use real threshold operations; neither permits a harness finality flag.

The smallest local stand-ins are allowed only where the architecture has a real adapter seam. An in-memory journal may test Client workflow; an in-memory transport may test a service protocol; a fake finality certificate, permissive settlement verifier, generic in-memory database replacing a QMDB durability claim, or edited recovery journal cannot earn qualification credit.

3. Staged qualification experiments

All six experiments are NOT RUN. “Smallest harness” describes the first useful experiment, not an implemented test.

Architecture-gate correspondence is explicit: Q1 supplies slices of G1–G4 and G7; Q2 supplies G5a/G5b; Q3 supplies G6; Q4 supplies portable portions of G1/G7; Q5 supplies recovery portions of G3/G7; and Q6 supplies G8. A Q result earns credit only for the rows listed in its manifest.

Q1 may run as a private partial-slice harness and establishes only its enabled command path and crash cuts; by itself it is not shared-devnet ruleset conformance. Q2 is required because the first devnet omits continuous reshare. Q3 does not prove every future release. Q4 proves parity only for its exact corpus/pins. Q5 proves the configured retention/recovery envelope. Q6 proves one chosen deployment path, not arbitrary Internet or cloud behavior.

4. Specification invariant matrix

Acceptance is evaluated through the named module interface even when several modules participate. “Evidence / limitation” always includes the current executable status. “Defines” is the specification section that states the invariant; section 20 of the specification indexes all 71 by identifier.

5. Application scenario matrix

6. Client/API scenario matrix

The Client workflow rows specify the future reusable Rust module and reference harness. They do not authorize a product SDK, CLI, explorer, website, or consuming application.

7. Properties, fuzzing, and security tests

Example-based APP/API scenarios are necessary but do not cover adversarial combinations. The first implementation plan must include the following minimal property/fuzz targets at the owning module interface.

Parser fuzzing covers every externally supplied canonical envelope, genesis/release artifact, signature presentation, WebAuthn JSON grammar, Commonware proof wrapper, Tempo account/storage proof, RPC byte wrapper, chainspec, and public network manifest. Seeds include the encoding-owner positive, boundary, and negative corpus. Fuzz findings become permanent regression cases with the exact pin and sanitized input digest.

Security-focused suites additionally cover algorithm/profile confusion, domain/chain/ruleset substitution, high-S and malformed signatures, recursive witness bombs, decompression/length/allocation bombs, duplicate-key JSON, invalid UTF-8, proof count/index mismatch, path/symlink traversal in local artifact tooling, unauthenticated configuration/trust-anchor injection, secret material in logs/run artifacts, queue exhaustion, and cancellation races. Native and wasm run the same portable subset.

7.1 Formal model-checking gates

Use TLA+ and TLC for these bounded state-machine checks. Tools are pinned by digest in formal/tools/pins.toml (decision D48); models live under formal/tla/ and run with formal/check.sh; TLC is the stable release v1.7.4. Lean 4 proofs under formal/lean/ complement the bounded search with unbounded results for the same rules; they are a separate evidence entry and never replace a model gate. Implementation linkage is trace validation in both directions: model witnesses and counterexamples replayed against the executor, as this section already required, and, by decisions D48 and D49, executor trace records (per the trace design record docs/execution/design/vp-02-trace-emission.md, with the post-state read back from storage) checked against the model by TLC (formal verification plan). Each model records finite bounds, symmetry and state constraints, constants, fairness assumptions, model/config/tool hashes, and the requirements it covers. Safety and liveness are separate checks. Liveness results name the fairness and environment assumptions that make progress possible; safety may permit a fail-closed halt.

Every campaign includes reachability and nonvacuity checks for its success, rejection, crash, and recovery paths. An incomplete state-space search, an omitted required path, or an assumption that asserts the desired invariant is never PASS. A minimized counterexample becomes a permanent implementation regression case. Qualification also requires a reviewed mapping from model state and actions to named implementation interfaces, plus representative successful, rejected, and recovery traces replayed against the real implementation. Record model-search and implementation-linkage results separately; both must pass. A failure blocks only its dependent claim and reopens the owning design. A model-search pass proves the declared abstract finite model only: it does not prove Rust code, Commonware, BFT, cryptography, native/wasm parity, vectors, or Q1–Q6. Implementation and campaign harness work may proceed while a model is built, but the affected qualification claim waits for the model gate. These are focused gates, not a blanket pre-code gate.

Crash-cut tests stop processes or abort owned storage handles at named barriers. They may not edit WALs, QMDB state, sync markers, certificates, or DKG journals to manufacture recovery. Each cut is a fresh seeded run and must observe fencing before the identity votes again.

glue::simulate cannot stop a validator at a named barrier. It crashes a validator by aborting its task at a scheduled time or inside a processed-height window (Crash::DelayRound only delays a validator's start and crashes nothing), and it injects storage faults (glue/src/simulate/action.rs:9-44, :81-102; glue/src/simulate/team.rs:142-151). A barrier cut such as C4 is therefore reached in simulation only by a seed sweep over height windows that records which cut each run hit, and otherwise by the crash-cut tests above or by runtime storage-fault injection; a simulated run is credited to a cut only when its record shows the cut. Whether a task abort in the deterministic runtime drops a validator's unsynced writes, as MC-02 contract K1 permits, is UNVERIFIED. By reading, a blob's unsynced content lives in its handle until sync copies it into the partition and a dropped handle does not flush (runtime/src/storage/memory.rs:241-252, :287-306), while the seeded partial-retention crash model runs only at the whole-runtime crash boundary (runtime/src/deterministic.rs:716-721, runtime/src/storage/faulty.rs:479-528). VP-07 settles it with a test before any simulated crash is credited to MC-02 linkage.

8. Dependency pin and update qualification

The baseline itself needs a proof package before code claims compatibility:

1. Record exact Rust/Cargo, Commonware crates/versions/checksums, enabled features, target triples, lockfile digest, and all directly used source paths/types.
2. Compile the selected primitives on their required native/wasm targets and run the owned expected vectors. Source review alone does not pass this step.
3. Run Q1/Q4 subsets sufficient to bind codec, BMT, QMDB, certificate, Stateful/marshal, and profile wiring. Settlement-positive rows remain blocked rather than mocked.
4. Store an evidence manifest with reviewer and limitations; until then the baseline is selected and source-reviewed, not qualified.

For every Commonware, Rust, cryptography, proof, database, or canonical dependency update:

• diff old/new upstream sources for codec, proof, crypto, persistence, consensus, marshal, Stateful, DKG, runtime, and feature changes actually in the dependency closure;
• regenerate and byte-compare every affected canonical artifact; run old and new corpora against the candidate and explicitly classify intended incompatibilities;
• rerun affected property/fuzz targets and Q experiments, including crash cuts for persistence or actor changes and Q4 for portable/crypto/codec changes;
• prove a mixed-version rollout only when the release plan allows it; otherwise require a reset or coordinated non-voting boundary and state that consequence;
• update the support matrix, SBOM/provenance, and evidence limitations in the same change.

For a protocol rule, model bound, abstraction mapping, fairness assumption, or relevant source pin change, rerun each affected MC gate or justify reuse per claim through reviewed unchanged-surface evidence. A prior model result is not globally current after its assumptions change.

An update cannot inherit the old PASS merely because public type names compile. Evidence reuse is per row and justified by an unchanged transitive behavior surface. Commonware remains upstream and unforked; a required local patch blocks the update until accepted upstream or the architecture is revised.

9. Gates and implementation order

These gates separate design readiness, runnable devnet, and production qualification. They do not require already-implemented evidence before independent implementation starts.

The fixed devnet is disposable and epoch-zero only. Moving to Q2/T0 is an explicit reset with new genesis and chain_id; it is not an in-place upgrade. A fixed-profile pass cannot satisfy a dynamic gate. Dev/test Moderato evidence cannot satisfy a Mainnet settlement gate. A production binary may be promoted unchanged across environments only when it supports the environment's authenticated profiles and all required gates pass.

10. Result and coverage records

Every run emits the immutable manifest required by operations §5, plus: requirement/scenario IDs; module/interface revision; exact command; host/container/target; toolchain/lock/SBOM digests; source pins; generated/vector/fixture hashes; seed and minimized failing input; topology and fault schedule; per-case outcome; artifact/checksum links; reviewer; and explicit remaining limitation. Secrets and private DKG material are represented only by public identifiers/digests allowed by custody policy. Lean records include the toolchain, the digest of every proof file, and the axiom-audit output. Model records additionally include the exact TLA+/TLC version, specification and configuration hashes, finite bounds and constraints, fairness assumptions, explored-state/completeness result, reachability/nonvacuity witnesses, counterexample-to-regression links, reviewed abstraction/action mapping, and representative implementation trace results. Model search and implementation linkage remain separate evidence entries.

A machine-readable coverage map may be embedded as a fenced YAML or JSON block in this Markdown file when automation exists; it must be generated from or checked against the tables above and may not become a second authority. conformance/rule-assurance.toml (VP-09) is that map for the rules each brief puts in scope: every property: and sim: class of an invariant entry names only vehicles the invariant's section 4 row names, and xtask coverage-matrix checks that and each entry's evidence; section 5 is not yet consulted. The local gate (and future hosted CI) fails for an unknown invariant/scenario, missing owner/interface, missing acceptance criterion, stale artifact digest, or PASS without a complete manifest.

Current evidence disposition:

• Commonware, Tempo, Constantinople, and the existing settlement-contract sources have been inspected only as cited by the architecture/operations/data-contract documents.
• FB-01–FB-12 provide bounded native/wasm primitive harnesses, canonical scalar/collection source, and a reviewed 100-case primitive corpus. No complete application schema/executor, Q1–Q6 experiment, fuzz campaign, benchmark, reproducible release, devnet, testnet, or mainnet described here exists or has run.
• MC-04 and the MC-02 export installation extension are PLANNED (D50): no model exists.
• MC-01 (slices A, B and C), MC-02, and MC-03 are DRAFT MODEL: bounded safety searches, witnesses, and mutation campaigns run under the pinned TLC in formal/, with no reviewer verdict and no implementation linkage, so no MC claim is supported. A trace-validation harness runs in both directions against a reference executor only. Lean proofs of the ledger accounting, release dispatch, and canonical codecs exist under formal/lean/ with the same status.
• The dedicated immutable beneficiary-cumulative contract profile/deployment and authentic positive proof do not yet exist in the evidence set. Settlement-positive rows remain BLOCKED-SETTLEMENT; they are never replaced by genesis credit, a faucet bypass, existing-contract evidence, or a mock.

11. Assurance layers and release qualification

This section holds material formerly stated in the specification and is not normative: it names qualification work, and no item below decides whether a block, a command, or a release is valid. It supports specification chapter 18 (releases and hardforks) and chapter 19 (parameters), whose calibration items are only fixed by a recorded measurement.

Each item is marked new to validation.md or already covered at section N. An item marked as covered is repeated here only by its identifier, not restated.

11.1 The first qualification milestone

The first implementation qualification milestone is a deterministic end-to-end application slice, reached before the broader service surface. Its funded path, Q1, imports credits with a real certified Tempo proof to create the ledger, initializes that funded account, delegates a key, creates a project, publishes a commit, verifies a publication receipt, and restarts through the three-member database set. The ref move, stale CAS, delete and recreate accounting, and authority revocation are carried by APP-03, APP-04, and APP-06 against the same executor, and the milestone is Q1 plus those three rows.

The same rules executor passes propose/verify/apply parity, command rollback, speculative cancellation, and recovery checks.

• Already covered at section 3 (Q1) and section 9 (gate D0), with the crash cuts in section 4 of operations.md.
• Already covered at section 4 for executor parity: INV-CONS-01, INV-CONS-02, INV-CONS-03, and INV-STATE-11; and at section 5 for APP-01 and APP-11.
• Decided, 2026-09-22. Q1 stays the five-command slice of section 4.1 of operations.md: IMPORT_CREDITS.Credit, INIT_ACCOUNT, KEY_AUTHORIZE.Authorize, PROJECT_CREATE, and PUSH. The milestone is Q1 plus APP-03, APP-04, and APP-06, which carry the ref move, stale CAS, delete and recreate accounting, and authority revocation. The milestone is reached when the Q1 manifest and those three scenario rows are all recorded; Q1 alone does not reach it, and neither does a scenario row without Q1's persistent path. No transition moves into the Q1 command subset, so the operations crash cuts and the Q1 acceptance criterion are unchanged.

The required scenarios are listed by state-machine.md; retry and proof-substitution scenarios are added by client-api.md. Already covered at section 6 (API-03, API-04, API-07, API-12).

11.2 Profile-scoped qualification

FixedEpochZeroV1 qualification additionally requires:

• byte-identical profile and genesis derivation across all seven validators;
• signer and share validation;
• deterministic rejection of every nonzero-epoch context, every present DKG payload, every validator-schedule variant, and every consensus-critical release path;
• restart and reset-isolation tests.

Its workload, proof, and recovery results do not qualify bootstrap DKG, reshare, epoch or membership transitions, production custody, or the dynamic engine handoff.

Already covered at section 5 (APP-15, APP-16, APP-17, APP-19, APP-20), section 6 (API-17, API-18, API-20), section 4 (INV-CONS-07, INV-CONS-08, INV-GOV-12), and section 9 (gate G4 in architecture.md, gate D0 here).

Mainnet requires separate DynamicReshareV1 evidence for the all-party bootstrap ceremony, repeated same-set reshare, DkgFailed carry-over, membership changes, boundary restart, late join and state sync, secret handoff and erasure, and every consensus-critical surface the release intends to schedule.

Already covered at section 3 (Q2, Q3), section 4 (INV-GOV-03, INV-GOV-04, INV-GOV-05), and section 9 (gates T0 and M1).

Enablement gate for VALIDATOR_SET_SCHEDULE

New to validation.md as a gate. A deterministic simulation of "set change plus DkgFailed carry-over in the same epoch" is required before the command is enabled on any non-devnet chainspec.

Three properties of the gate are load-bearing and are not satisfied by the rows that resemble it:

• the scenario is combined: one set change and one DkgFailed carry-over, in the same epoch, not two separately passing scenarios;
• the gate is a precondition for enabling the command, not evidence collected afterwards;
• it binds any non-devnet chainspec, testnet included, not only mainnet.

Section 3 (Q2) exercises a set change and an injected DkgFailed and section 11.3 lists set change with carry-over as a simulation property, but neither states the conjunction, the epoch scope, or the enablement precondition. Until the gate is recorded, a testnet chainspec that enables VALIDATOR_SET_SCHEDULE is outside the qualification plan.

11.3 The six assurance layers

Each layer has an owner and a trigger; a qualification gate that no one owns is not a gate. Owner roles follow the campaign table in implementation-plan.md ↗ (external site) section 12.

Two properties hold across the layers:

• Application and engine crates are generic over the runtime, so the same assembled engine runs under production and deterministic runtimes. Already covered at section 2.
• Deposit conservation across delete/recreate cycles is an invariant-test target, not only an example scenario. Already covered at section 4 (INV-STATE-05, INV-STATE-07) and section 5 (APP-03, APP-05); the combinatorial framing is new to validation.md.

11.4 Speculative-memory gate

New to validation.md. The engine is qualified under delayed finalization, repeated view changes, and cancelled verification. The gate accounts for:

• pending merkleized batches across all three members, which glue caps only by branch compatibility and not by count or bytes;
• retained ancestry;
• decoded blocks;
• worker jobs that keep running after their future is dropped, with worker permits charged until the work finishes.

Resource exhaustion produces backpressure or pending work, never an invalidity verdict. The invalidity boundary itself is already covered at section 4 (INV-FAULT-01).

11.5 ALPHA pin-bump re-run set

Every pin bump of an ALPHA dependency re-runs:

1. root parity;
2. compact-versus-full parity;
3. crash and rewind;
4. state sync;
5. the wasm verifier vectors.

The exoware crates at 2026.9.0 are ALPHA members of this set and carry their own Commonware pins at 2026.9.0; the simplex crate publishes no status line and is treated as ALPHA with the rest. A bump of an exoware pin also re-runs the Q5 checker and the store rebuild from the mirror, because the store's persisted node layout is what those two items exercise.

Partly covered at section 8, whose dependency-update rules already require regenerated canonical artifacts, affected property and fuzz targets, crash cuts for persistence or actor changes, and Q4 for portable, crypto, or codec changes. The five-item set as the named minimum for an ALPHA bump is new to validation.md, as is its coupling to step 1.4 of release-process.md: a Commonware pin bump inside a release re-runs this set.

The ALPHA members are listed in the primitive map in section 10 of architecture.md.

11.6 Release assurance additions

These run in addition to sections 11.3 through 11.5, once per release.

Regenerating a vector is an explicit format approval carrying a breaking-format label on the change, never a way to make a test pass. Already covered at section 8, which forbids inheriting a prior PASS on a changed behavior surface.

Two different class checks exist and only one decides validity.

• The structural check is R-18.3 over the descriptor's own manifest: the declared class admits every declared surface, consensus_critical is set exactly when a consensus-critical surface is declared, and the ruleset identity conditions hold. Every validator runs it under the current rules, and specification section 18.2 makes it the whole of the class check inside SCHEDULE_RELEASE validity. It stays in the specification, and a descriptor it rejects cannot be scheduled.
• The conformance-based check derives the class and the flag from the conformance run of the release process step 1.4 and compares them with the declaration. It is governance tooling and a qualification gate, never a validity rule, because a validator whose binary lacks the ruleset cannot run the conformance corpus that the derivation needs. Its two obligations, that the shipped code matches its manifest and that a release stays inside its class, are recorded here and in release process section 1.2.

11.7 Proof-path hash re-measurement

Tracked as SB-15 in implementation-second-batch.md ↗ (external site), in two parts.

The microbenchmark runs beside SB-16 and waits on nothing: it merkleizes QMDB current and keyless batches under Keccak256, SHA-256, and BLAKE3 and reports hash calls and time per tree. The sizes are the medium and high bands of section 4.1 of operating-envelope.md, 16.7 and 100 distinct PUSH per second at 8 and 16 mean commitments per PUSH, which remain synthetic planning bands rather than a forecast. Its Keccak256 is Makechain's own Hasher implementation against the pinned library trait, follow-up F13, so the measurement needs neither a library release nor a pin move; a main-branch pin would split the dependency graph from exoware 2026.9.0 and is excluded for that reason.

The whole-block measurement runs at SB-13, where a real MerkleizeBlock exists:

1. re-run the storage, history, and command-root probes;
2. measure merkleization throughput of the three databases and the command root at the target throughput under each candidate hash, reported per tree: hash calls per block and merkleization time for the validity state, the membership log, the block-history accumulator, and the command root separately.

Acceptance is per tree against the round budget with the stated margin. The recorded outcome selects one of the four options of SB-15's decision point (all Keccak256, BLAKE3 for the validity state only, SHA-256 across the proof path, or all BLAKE3), and that selection is an owner decision, F11, recorded in the decision register before the first non-disposable genesis. SHA-256 is a genuine option rather than a formality: it is in the pinned tag at BETA, the EVM has a precompile for it, and the library's Solidity MMR, keyless-MMR, and BMT verifiers ship SHA-256 variants.

The proof-path hash choice is final only when that measurement passes, so no conformance claim that depends on the proof-path hash is complete before it is recorded. The measurement is a calibration item in the specification's parameter chapter; no target value is stated here.

The affected rows are the proof-path members and the command root in the primitive map in section 10 of architecture.md.

11.8 Application conformance coverage

The application conformance program covers the following transitions. Per-variant read, write, and resource bounds live in state-machine.md, and each transition carries the relevant invariant identifiers.

The coverage above is a mapping, not a new claim: every executable row it names keeps the status recorded in sections 3 through 7.

11.9 Key-family freeze gate

New to validation.md. Signer-generated vectors from real tools and authenticators, including negative origin, challenge, flag, and malformed-signature cases, are required before any key family is frozen.

The gate covers the families verified with external standard verifiers: SSHSIG, WebAuthn, and P256-direct. It is separate from, and stricter than, the requirement that native and wasm verification agree on every vector, which section 3 (Q4) already covers and which says nothing about real authenticators or negative cases. Section 7 already covers WebAuthn grammar fuzzing and malformed-signature cases as adversarial input; the addition here is that a family may not be frozen until the signer-generated corpus, including its negative cases, passes.

11.10 Genesis path qualification

New to validation.md. Genesis and header reproduction vectors, plus crash-cut vectors, must qualify the genesis seeding path.

The path has no block to re-execute against, so no propose/verify/apply parity run covers it. Calling ordinary block execution on genesis would incorrectly append extra log commits, which is why the path is seeded separately and why its own vectors are the only stated check that an implementation reproduces genesis correctly.

Partly covered at section 5 (APP-15, APP-11 for C10 and C11) and at section 4 of operations.md, whose cuts C10 and C11 exercise the durable genesis target. The vector requirement itself, covering genesis and header reproduction rather than restart behaviour, is new here.

11.11 Settlement profile completeness gate

New to validation.md. No network may claim a complete settlement profile, or run the positive funded qualification slice, until the deployment inputs are fixed and a compatible deployment exists.

The deployment inputs are compiler artifacts, runtime code hashes, deployment addresses and checkpoints, and fixture-qualified proof bounds. The settlement interface's provisional devnet bounds are not measured limits and are not a mainnet calibration.

Section 3 and section 10 already mark every settlement-positive row BLOCKED-SETTLEMENT, and section 7 of operations.md records QP-1 as the external prerequisite. What is new is the completeness predicate: BLOCKED-SETTLEMENT states that authentic evidence is missing, while this gate states when a profile may be called complete at all.

11.12 Separately qualified cost items

Five cost behaviours are named as their own qualification items because no scenario row covers them.

The index-bucket item is measured on the reference validator profile under section 11.3's qualification layer; the four publication and history items are measured on the exporter and store profile under the same layer. The derived sizing figures they attach to are in section 8.5 of operations.md; no such figure is a measurement, and none is normative until a gate records a measured value.