claude
32f6be8552
Architect review over 024e865..HEAD (issues #296/#348/#297/#299). Holds confirmed: zero process::exit in the assembly crate with the milestone promise pinned in-process; C1/C18 record shapes untouched with guard and stamp sharing one label constructor; the C30/#348 re-arm transition-safe with no stale references. Drift resolved in this commit: the C14 contract now records the context-borne reproduce guard classes (#299), C30 carries the source-level-identity limit in the contract itself (not only in build.rs), the guide's exit-class prose no longer names the retired run verb, C28 durably enumerates the deliberate print residuum, and the pip_or_refuse doc names reproduce (not 'the CLI shell') as the from_choice home. Bench: all 5 fingerprints OK (engine/ingest/campaign_sweep/campaign_heavy/ cli_fixed_cost); metric deltas within load noise on a busy box (loadavg 12 warning), report-only, no baseline moved.
4.8 KiB
C30 — Stability discipline: artifacts are stable, code is movable
Guarantee. The project's compatibility promise attaches to recorded data, never to Rust API. Before 1.0 the workspace's library surface promises nothing between commits; every cargo consumer either moves with the engine checkout (path-dep node crates, staleness refused at the load handshake) or pins a rev deliberately (external embeddings). The one handshake guarding the ABI seam compares build identity, never a hand-maintained version.
-
No API stability before 1.0. Signatures, module homes, crate rosters, and trait shapes move freely, commit over commit — no deprecation cycles, no compat shims, no semver bumps. The workspace version (0.1.0) is not a communication channel; nothing downstream reads it. What a change may not silently break is behaviour pinned by the artifact plane (point 4).
-
Two consumer classes, two mechanisms.
- A native node crate (scaffolded by
aura nodes new) consumes the engine as a cargo path dependency into the local engine checkout — the scaffolder emits exactly this (crates/aura-cli/src/scaffold.rs, templateCARGO_TOML). Node crate and engine move together: cargo rebuilds the crate when aura-core changes, and a dylib from any other engine state is refused at load (point 3), never trusted. - An external embedding (a World program in its own repo) consumes the workspace crates as a cargo git dependency pinned to a rev. The pin is the whole contract: updating it is a deliberate act that accepts whatever moved, with the design ledger and commit bodies as the changelog.
- A native node crate (scaffolded by
-
The load handshake refuses non-identical builds. The cdylib handshake already refuses a rustc mismatch (
RUSTC_VERSION, emitted by build.rs). The aura-core stamp must be equally honest: a build-identity fingerprint derived mechanically from aura-core's sources, so a node dylib loads only against the aura-core it was built from — source-level identity, an accepted limit: the consuming build's lockfile and feature selection stay outside the stamp, so the seam refuses staleness of aura-core itself, never the full link graph. A hand-maintained version that never moves disarms the refusal (the pre-C30 state:CORE_VERSIONfrozen at 0.1.0 matched every stale dylib); a hand-bumped one re-arms it only between bumps — an implicit ABI promise this contract refuses to make. (Re-armed by #348: a source-derived fingerprint replaced the crate-version stamp.) -
The artifact plane is the stable tier. What was already law, stated as the positive promise: registered artifacts are never retroactively invalidated (C29); document format changes carry
format_versionwith readers keeping old forms readable (C18); deploy artifacts are frozen (C13, invariant 8). Compatibility work happens here: a change that would orphan recorded artifacts is a design decision for the ledger, never a refactor. -
The erosion guard. No doc, README, or scaffold may describe any Rust surface as "stable API" while this contract stands. Inviting a consumer means naming the point-2 mechanism (path or pin), never promising stillness. Amending this contract is the only way to promise more.
Rationale. #296 recorded the tension: an invited external consumer
(#295 deliberately enlarges the public library surface) versus a working
discipline of behaviour-preserving reshaping (C28
relocated whole rosters twice in one pass). The resolution promises where
the project can keep promises — the recorded-data plane, whose guarantees
already exist — and refuses to promise where it cannot. The empirical
ground at decision time: the one real downstream project is data-only (an
Aura.toml directory with no Cargo.toml, consuming the released binary
and documents), so the only cargo consumers are engine-scaffolded node
crates (path-dep by construction) and the engine's own fieldtest
fixtures. A stability promise to nobody would cost every cycle and inform
no one; hardening toward 1.0 stays available at any time, while stability
promised early is practically irrevocable.
See also
- C13 — frozen deploy artifacts (the promise at the deploy edge)
- C16 — engine/project split; reuse is cargo-native (invariant 9)
- C18 — the run registry and
format_version(the artifact plane's mechanics) - C28 — the movable crate ladder this contract licenses
- C29 — registered artifacts never retroactively invalidated
- Decision record: #296 (options weighed, skeptic findings); re-arming the handshake: #348