Repository structure and engineering contract

This document fixes where future work belongs and which dependencies may cross each seam. It is a design contract, not an instruction to create the folders now. The initial implementation is the protocol and its smallest qualification harnesses. A product SDK, user CLI, explorer, documentation site, Cloudflare application, and the owner's consuming application are not initial implementation tracks.

The specification and its companions own protocol meaning. Architecture owns semantic module interfaces. Encoding owns the proposed vector/fixture format and data contracts owns the canonical-format inventory. Validation owns the evidence gates. If this layout conflicts with one of those authorities, change the layout; do not duplicate the rule in a convenient crate.

1. Repository boundary

The Makechain repository owns:

• canonical Makechain data, rules, authorization, deterministic execution, state integration, and proof verification;
• Commonware assembly without a Commonware fork;
• native node and off-chain service composition roots;
• native/wasm verifier packaging and protocol conformance harnesses;
• public network artifacts, release manifests, and later GCP/GKE and Cloudflare deployment code.

The following remain separate repositories or systems:

The repository may later contain first-party gateway, exporter, relayer, query, verifier packaging, Cloudflare, and GKE deployment work. Their inclusion does not turn external contracts, mkit, or the consuming application into workspace members.

2. Planned top-level layout

Cargo.toml                 Rust workspace and shared dependency/lint policy
Cargo.lock                 committed lock for every native/wasm/release build
rust-toolchain.toml        exact Rust 1.95.0 pin and required targets/components
Justfile                   documented command aliases only
spec/                      normative specification, encoding, state-machine, and settlement interface
docs/                      architecture, client API, contracts, operations, validation, decisions
crates/                    reusable Rust modules described in section 3
bin/                       thin native composition roots described in section 5
packages/                  minimal Q4 wasm verifier packaging; TypeScript product packages later
apps/                      later Cloudflare applications; no protocol rules
schemas/                   generated public transport descriptions/metadata, never canonical source
conformance/               encoding-owner vectors, fixture manifests, compatibility/pin manifests
tests/                     cross-crate deterministic, persistent, and network qualification harnesses
benchmarks/                accepted workloads and measurement harnesses
spikes/                    disposable feasibility probes; never a dependency of any member
networks/                  public chainspec/genesis/release artifacts, never private shares
infra/                     later GCP/GKE and Cloudflare deployment definitions
tools/xtask/               small repeatable workspace/release automation binary

Folders are created only when their first owned artifact is implemented. Empty future directories and placeholder packages provide no architectural value. Secret shares, operator credentials, private DKG material, live kube credentials, and unpublished settlement evidence never enter the repository.

3. Rust crate map

Eight reusable crates are the proposed complete native-system split, plus the verification crate makechain-trace, on which no production crate depends and which depends on no node crate. The first implementation slice needs only protocol, execution, state, proof, node, the node binary, and qualification harnesses. Crates are grouped around deep interfaces and dependency constraints, not around every label in the architecture.

makechain-protocol is deliberately broader than a type crate: deleting it would spread canonical bytes, release selection, authentication, domains, and external proof rules into every caller. makechain-node is more than a pass-through binary library: it buries Commonware lifecycle, readiness, sync-plan, profile, and cancellation rules behind one role assembly interface.

There is no proof-generation crate. The proof service is the operated exoware operation-log service, so makechain-history writes to it and checks it but never reproduces its proof construction.

makechain-gateway, makechain-history, and makechain-query are deferred until the protocol slice needs their narrow diagnostic adapters. Admission has latency/bounded-pool dependencies, history has durable queue, watermark and store-client dependencies, and query has exoware-sql client dependencies. Keeping the three seams prevents validator and exporter builds from inheriting public-service or query-tier dependencies.

3.1 Deferred client workflow

The later Client workflow module owns preparation, the durable signing-slot journal, submission and reconciliation state machine, and complete-push composition. It depends on Canonical schema, Release evaluator/profile data, Proof verifier, and injected transport/storage ports. It does not belong in makechain-proof, because proof verification remains pure and status-agnostic.

Before a product SDK exists, tests/client-reference may exercise the same interface with in-memory and filesystem journal adapters. When product work begins, the reusable Rust implementation should become crates/makechain-client. The early packages/wasm-verifier exposes only portable canonical decode and evidence verification needed by Q4; preparation enters only with the reviewed Client workflow. A later TypeScript SDK wraps rather than reimplements them. This future client crate is not required for the first executor/node implementation.

4. Dependency and target rules

                         makechain-gateway (native, deferred)
                        /                              \
makechain-node (native) ──> makechain-state ──> makechain-execution
        |                         |                         |
        |                         +-------------------------+
        |                                                   |
        +──────────────> makechain-proof ────────────────> makechain-protocol
                                  ^                         ^
                                  |                         |
                    wasm verifier package -----------------+

makechain-trace (native, verification only) --> makechain-state + makechain-execution + makechain-protocol
tests/trace-sim (harness) --> makechain-node + makechain-trace
makechain-history (native, deferred) --> core crates + pinned exoware client crates
makechain-query (native, deferred) --> protocol + certified history outputs
Client workflow (portable, deferred) --> protocol + proof + injected ports

Every arrow points toward a dependency. The graph is enforced from package metadata, not reviewer memory.

• makechain-protocol, makechain-execution, and makechain-proof must compile without Tokio, filesystem, sockets, cloud SDKs, or platform clocks. Their portable feature set must compile for wasm32-unknown-unknown where used by the verifier package.
• Pinned source places BMT outside commonware-storage's std gate but places QMDB under it; storage std also enables commonware-runtime, futures, tracing, and zstd. The verifier therefore selects commonware-storage with default-features = false and only the minimum exact features required by its native proof types, and its wasm build runs as a separate package/target invocation so workspace-wide native feature unification cannot masquerade as portability. That gate records the resolved graph, compiles the complete selected proof/crypto closure, and checks the emitted wasm/import graph has no reachable filesystem, socket, clock, or other native I/O path. It does not reject an otherwise portable build merely because an unused transitive runtime trait crate is present. This feasibility check is NOT RUN; failure blocks the crate split and triggers pin/interface review, never a hand-written replacement proof format.
• makechain-state is native because it binds exact Commonware QMDB/glue contracts.
• makechain-node, makechain-gateway, makechain-history, makechain-query, and the verification crate makechain-trace are native. Only they may own asynchronous runtime and process-lifecycle dependencies.
• No crate wraps all Commonware primitives behind a generic framework. The selected codec, BMT, QMDB, Simplex, marshal, Stateful, DKG, and mesh types stay visible at the module that must preserve their consensus contract.
• Feature flags may choose adapters or instrumentation. They may not change canonical bytes, command validity, release rules, roots, profile semantics, or error classification.
• Production crates do not depend on tests/, benchmarks/, spikes/, tools/xtask, Cloudflare packages, or deployment definitions. Test utilities live under the owning crate unless reused by two or more qualification harnesses.

spikes/exoware-spike (package makechain-exoware-spike, publish = false) is the workspace member of the SB-16 exoware spike and the SB-15 per-tree hash microbenchmark. Its allowed dependency edges are the exoware client crates at =2026.9.0 (exoware-qmdb, exoware-simplex, exoware-sql, exoware-sdk); tokio =1.53.1 with rt-multi-thread only; the crates exoware uses at 2026.9.0, bytes =1.12.1, datafusion =55.0.0, connectrpc =0.9.0 (client), and futures =0.3.34; the pinned commonware-* crates it exercises, commonware-math included; and makechain-protocol for the per-tree hasher aliases (decision D52). It is the only member allowed tokio or an exoware-* crate before makechain-history and makechain-query exist, and no member may depend on it under any dependency kind; workspace validation enforces both. The store it talks to is a separately installed exoware-simulator process, never a dependency. Its results feed IP-06C and the SB-15 decision point and carry no production claim.

crates/makechain-trace holds the trace record schema (src/schema.rs, a ruler path), the generated model-action match, the post-state abstraction adapter and the offline replay driver of the trace design record (docs/execution/design/vp-02-trace-emission.md, TE-19). The dependency rule: the RecordSink trait and DiscardSink live in makechain-execution (a trait over the immutable outcome, no runtime dependency); makechain-node installs DiscardSink and never depends on makechain-trace; makechain-trace (verification only, publish = false) depends on makechain-protocol, makechain-execution, makechain-state and the pinned commonware crates, never on makechain-node; the simulation StashSink and the engine wiring live in the tests/trace-sim harness, which depends on both makechain-node and makechain-trace; workspace validation fails if any production crate depends on makechain-trace under any dependency kind.

Dependency policy is deny-by-default at the workspace root. A new dependency needs the owning module, reason, feature/default-feature decision, license/security review, target support, and an explanation of why an existing pinned dependency is insufficient. Duplicate cryptographic, serialization, HTTP, runtime, database, or command-line stacks require architecture review.

5. Thin binaries and process assembly

Binaries parse configuration, open concrete adapters, call one library composition function, map typed startup errors to diagnostics, and own shutdown. They contain no command handler, encoding, release selection, proof decision, state transition, or retry state machine.

The first deployment may co-locate adapters, but persistence directories, watermarks, readiness, identity, and authority remain explicit. Placement rules that follow from the roles:

• Production validators run on GKE/GCP and run no publication.
• One exporter process is active and one runs as standby with publication off; both are ordinary followers of the same binary and non-voting mesh peers from the governed chainspec roster, and the standby resumes from the store's publication watermark. The standby keeps its own durable publication queue of every finalized block and releases an entry only when it observes the store and the mirror watermark past that height, so it is deployed failure-isolated from the active: separate disk, host, and zone.
• Either state-syncs at its first installation only and follows marshal thereafter. That one installation records its sync anchor A durably and begins its own queue coverage at A + 1. Until A is recorded it re-evaluates, at every retargeting of its sync, that every height in (W, current target] is durable elsewhere, W being the publication watermark observed in both the store and the mirror at the start of the installation: either the publication watermark has reached the current target, or the other roster member's queue coverage is at least the current target and its watermark advances within the publish-lag bound. If neither holds, it aborts the installation and alerts (R-17.21). The finalization pinned as the sync target is read from the store's finalized-by-height record and certificate-verified before use. One for which max(own queue coverage, publication watermark) is below the validators' retained window stops and alerts instead of syncing.
• The store runs as its own service on a persistent disk, reachable only over a private network from the exporter, the standby, the proof service, the indexer and the gateway; it carries no authentication of its own, so network reachability plus an authenticating proxy that admits writes only from the two exporter identities is the whole of its access control.
• Cloudflare Workers are later edge/application adapters and never host validator identity, QMDB state, consensus logic, or the source of protocol truth.

Validator operators are permanently permissioned and explicitly trusted: the owner's team operates the initial seven, and later members enter only through governed scheduling and real DKG/reshare. No repository package provides permissionless validator discovery or admission.

6. Generated artifacts and fixtures

Canonical vectors and fixture formats are owned by encoding, with the inventory in data contracts. Before code, the reviewed encoding contract is the normative wire design. Once implemented, reviewed Rust canonical types/codecs are the executable authority. The format manifest records version, tags, domains, pins, and artifact digests; it is not a custom schema DSL or a compiler that generates the Rust implementation. Repository rules are:

1. The reviewed canonical Rust schema/domain/discriminant implementation has one owner and names the encoding revision. Expected vectors independently pin literal bytes/digests/results.
2. A small deterministic xtask command validates the owned vectors against Rust, emits public descriptions/metadata/bindings from Rust into a temporary tree, and compares derivable outputs byte-for-byte with committed outputs. There is no second schema compiler. Generation never depends on network access, wall clock, filesystem order, locale, or random seed.
3. Generated files declare their source and are not hand edited. A source change and all affected outputs land in one review.
4. Authentic external fixtures record provenance and hashes. Real-network private keys, shares, dealer seeds, and custody material are never fixture data. A narrowly allowlisted deterministic harness directory may publish synthetic seeds/shares only when every file and derived chainspec is marked TEST ONLY, reproducible, bound to a disposable chain identity, excluded from release images/network artifacts, and covered by a secret-scan exception for that exact path. A positive Tempo fixture is captured from Moderato or Mainnet and verified by the production verifier; no generator can synthesize one.
5. Cargo.lock, public chainspec/genesis bytes, release manifests, conformance outputs, and release checksums are reviewed artifacts. Ordinary build products are not committed.

7. Toolchain and dependency pins

The initial workspace pin is Rust 1.95.0: Commonware v2026.9.0 declares rust-version = "1.95.0", edition 2024, and that exact toolchain is locally installed. The local default observed on 2026-09-19 is Rust 1.96.0; it is not the repository baseline. rust-toolchain.toml will pin 1.95.0 with a minimal profile, rustfmt, clippy, and wasm32-unknown-unknown. Shipped artifacts are built only by 1.95.0. Every verification tool has its own digest-pinned toolchain recorded in conformance/toolchains.toml: lean, charon-rust, aeneas and tlc are pinned, and kani, dylint and cargo-fuzz are pending until the task that adopts each pins it. No nightly builds anything that ships, and a toolchain bump is a ruler change with a full re-run (decision D49).

Pin changes are isolated from feature work unless the dependency change is the feature. The PR states the old/new pin, upstream diff range, consensus/storage/codec surfaces touched, reused evidence, invalidated evidence, and rollback/reset consequence. A Commonware bump never silently inherits new marshal, state, proof, codec, consensus, or DKG behavior.

8. Developer command surface

just is a discoverable alias layer over standard tools; tools/xtask handles repository-specific deterministic checks. Neither becomes a build framework. The maintainer runs the complete local gate before each direct main push.

Commands accept explicit paths and profiles. They never select a network from ambient cloud credentials, fetch a trust anchor from an RPC response, generate same-chain signer material, or fall back to synthetic settlement evidence.

9. Local gates and deferred hosted CI

GitHub Actions is disabled for the current direct-main development phase. Each push follows a successful local just check-all plus any affected long-running campaign named by the change. Hosted CI is deferred until pull-request contributions begin; enabling it requires a reviewed workflow that invokes the same local commands with fully pinned actions and tools.

The required checks are small enough to diagnose independently:

Fuzz, prolonged deterministic schedules, Q2/Q3 recovery campaigns, load tests, and reproducibility rebuilds run on a schedule and on affected release candidates. A failure is attached to the exact seed, corpus digest, source revision, pin set, and artifact. Flaky retries do not turn a failure into a pass; the manifest records every attempt.

The initial supported release target is x86_64-unknown-linux-gnu for GKE/GCP node images. Developer builds on aarch64-apple-darwin are supported for feedback but are not release artifacts. The portable verifier target is wasm32-unknown-unknown. Adding or replacing a release target requires a reproducibility result, runtime/storage qualification, and deployment review.

10. Review ownership and change classes

Changes to anything under spec/, canonical schema inputs, conformance vectors, public network artifacts, and release/pin manifests require explicit ownership review rather than general code ownership alone. Automated agents follow the same placement and review rules; generated volume does not waive an owner or evidence mapping.

11. Reproducible releases and promotion

A release is one content-addressed source revision plus exact toolchain, lockfile, build recipe, network-independent binaries, SBOM, provenance, and checksums. Build environments set a stable SOURCE_DATE_EPOCH, contain no credentials, use pinned base images/package snapshots, disable incremental compilation, and remove path/time entropy. Two clean builders must produce equal bytes for the declared artifact or the result is INCONCLUSIVE/FAIL and cannot be promoted.

Promotion references the same immutable image and binary digests through development, qualification, and production. Environment-specific chainspecs, settlement profiles, addresses, and trust anchors are signed data inputs, not compile-time substitutions. Binary rollout is separate from protocol release activation. A binary must support every ruleset from genesis through the active release before it may vote; rollback may select an earlier compatible binary but may never revert an activated protocol release.

Promotion sequence:

1. Merge gates pass and provenance binds source, toolchain, lockfile, generated inputs, and targets.
2. Independent rebuild agrees on bytes; publish checksums, SBOM, and signatures/attestations.
3. Fixed-profile devnet uses the artifact only after its required gate in validation §9.
4. Dynamic qualification testnet starts from a new genesis/chain_id and requires Q2/Q3/Q5 evidence.
5. Mainnet promotion requires all mainnet gates, the dedicated immutable Tempo Mainnet contract profile, real Mainnet proof qualification, production topology/load evidence, and owner verdict.

Devnet/testnet use real Tempo Moderato proofs. Mainnet uses real Tempo Mainnet proofs. A captured fixture may make a deterministic run repeatable, but a fixture or devnet result cannot promote a Moderato settlement profile into Mainnet. Contract builds and deployments are released by the separate contracts repository, then imported here as reviewed immutable profile data.

12. P5 acceptance and unresolved choices

Independent implementation may begin after the relevant module's schema/interfaces, dependency edges, expected vectors, and validation rows are reviewed. It does not require every later package, cloud adapter, workload target, or external service to exist. Positive IMPORT_CREDITS execution remains blocked until the dedicated settlement contract profile and authentic Moderato fixture exist; this does not block independent codec, executor, state, proof, or harness work.

The disposable devnet has selected one GCP region, a self-hosted exoware store on a persistent disk in that region, and a same-region GCS Standard bucket as the mirror, written through create-if-absent generation preconditions and the makechain-history storage seam. A regional outage may stop this network. Exact region and machine shape are deployment-time quota/cost choices and convey no production qualification.

Production bucket replication/location/retention, the administrative independence of the two store copies, validator topology, store disk-snapshot cadence, recovery SLOs, Cloudflare application structure, and a TypeScript toolchain remain deliberately unselected. Each has a named downstream gate in architecture/operations/validation. Selecting one is not necessary to implement the protocol core, and implementing the core does not silently select one.

Source basis: Commonware v2026.9.0 workspace metadata and workflows establish Rust 1.95.0, edition 2024, the crate family, and deterministic/fuzz/conformance practices; owner direction prohibits a Makechain fork. Tempo commit 25b216a661c2cac72807174583371b582b75c286 informs only the separation of reusable crates, thin binaries, workspace automation, and reproducible release builds. Constantinople commit 42d0b3abfd89a3f6f31b1ee44f5f9f516a25bdc0 informs fixed-profile assembly wiring only. None is evidence that this proposed repository or a Makechain build has passed.