Implement ValidationPlan (ADR-012 §3, plan phase 7)

The compiled value-domain validation form: replaces the interpretive
BastDoc walk in validate_bytes with a compile-once-walk-many
constraint tree built at engine-compile time. This was the design
session + implementation ADR-012 §3 delegated; the shape decisions
are recorded in new ADR-012 §3a.

- New src/validation_plan.rs: ValidationPlan + ValidNode/ValidField/
  ValidVariant (Debug+Clone+PartialEq+Eq+Hash+Send+Sync),
  compile(&BastDoc) with eager $ref resolution, and a per-buffer walk
  with deferred error-path rendering (zero happy-path allocation,
  byte-identical error messages vs the 0.2.0 walker).
  fingerprint() via DefaultHasher, same as the phase-6 pattern.
- Compile-time graph safety: definition-level cycle set + depth cap
  (128) reject cyclic $ref graphs with AlkTypeError::Schema. The
  interpretive walker resolved refs lazily with no guard (stack-
  overflow hazard); diamond (shared) refs still compile.
- bast_validation.rs: interpretive walker retired (deleted);
  validate_value survives as a one-shot wrapper (compile + validate)
  for callers holding a doc without an engine.
- engine: Arc<ValidationPlan> built at compile in BOTH modes; the
  plan compile runs before the layout build and doubles as the
  engine's cyclic-ref gate (LayoutBuilder/OffsetMap struct recursion
  has no cycle guard; a cyclic doc previously overflowed there).
  validate_bytes walks the plan; new accessor validation_plan().
  validate_bytes signature unchanged.
- lib.rs: pub mod validation_plan + re-exports (ValidationPlan,
  ValidNode, ValidField, ValidVariant).

Verification: cargo test --release (355 pass, incl. parity suite,
fingerprint contract, cycle/depth rejection, Send+Sync + thread-share
assertions); clippy --all-targets -D warnings clean; cargo doc
zero warnings; wasm32-unknown-unknown release build green.

Co-authored-by: opencode <noreply@alk.dev>

docs/architecture/README.md

@@ -46,7 +46,7 @@ format definition; the engine is generic.
 | [009](decisions/009-builder-api.md) | Builder API for Schema Construction | Fluent Rust API producing `serde_json::Value`; covers BAST kinds + standard JSON Schema; resolves OQ-003. *Output format amended to BAST / standard JSON Schema by ADR-BAST.* |
 | [010](decisions/010-generalized-validation-validate-bytes.md) | Generalized Validation — `validate_bytes` on `AlkTypeEngine` | Single-call binary-buffer validation; materialize `Value` from bytes, then validate. *Validation step amended to the BAST-native validator by ADR-VAL-SPLIT.* |
 | [011](decisions/011-compiled-read-plan-for-packed-mode.md) | Compiled Read Plan for Packed Mode | `ReadPlan` — the packed read-side compiled form, symmetric to `OffsetMap` (aligned) and `PackedLayout` (packed write). Closes review #004's 400x read-path gap; retires ADR-007's "re-parse on demand" framing. *Accepted.* |
-| [012](decisions/012-plan-fingerprinting-and-m1-closure.md) | Plan Fingerprinting, ValidationPlan, and Closing the Deferred M1 Sites in 0.3.0 | `ReadPlan`/`OffsetMap`/`ValidationPlan` `Hash + Eq` + `fingerprint()`; owned `BastDoc` (lifetime removal); `OffsetMap` carries `LeafMeta` to close the aligned-side M1 sites; `ValidationPlan` retires the interpretive `bast_validation` walk (review #005 M3 reversed the original deferral). Bundles with ADR-011 into one 0.3.0 breaking release. *Proposed.* |
+| [012](decisions/012-plan-fingerprinting-and-m1-closure.md) | Plan Fingerprinting, ValidationPlan, and Closing the Deferred M1 Sites in 0.3.0 | `ReadPlan`/`OffsetMap`/`ValidationPlan` `Hash + Eq` + `fingerprint()`; owned `BastDoc` (lifetime removal); `OffsetMap` carries `LeafMeta` to close the aligned-side M1 sites; `ValidationPlan` retires the interpretive `bast_validation` walk (review #005 M3 reversed the original deferral). Bundles with ADR-011 into one 0.3.0 breaking release. *Accepted — §3a shape implemented in `src/validation_plan.rs`.* |
 
 ## Relevant Open Questions
 

docs/architecture/bast-format.md

@@ -528,24 +528,28 @@ materializer iterates the field list), types are correct (`read_u32`
 produces `Value::Number`), bounds are checked (via `data_access::
 check_bounds`), UTF-8 is valid (via `from_utf8`), the discriminator is
 in the mapping, and the boolean byte is 0 or 1. What the materializer
-does NOT check — and what the 19 v0.1.0 custom keyword validators check
-afterward — are **value-domain constraints expressed in the BAST
-document**. The BAST-native validator is a recursive walker over the
-BAST type tree that checks exactly these:
+does NOT check — and what the validation half checks afterward — are
+**value-domain constraints expressed in the BAST document**. Under
+ADR-012 §3 these constraints are compiled once into a `ValidationPlan`
+at engine-compile time (eager `$ref` resolution, cyclic-graph
+rejection); each `validate_bytes` call walks the compiled constraint
+tree against the `Value`. The plan's nodes enforce exactly these
+constraints (the set is normative; the walker that enforced it
+interpretively in 0.2.0 is retired):
 
-| Constraint | Validator arm |
-|------------|---------------|
-| Integer range (Int8..Uint64) | `validate_int`/`validate_uint` with `as_i64`/`as_u64` + range check |
-| Int64/Uint64 (full range) | `validate_int64`/`validate_uint64` (JSON precision caveat per ADR-005) |
-| Float finiteness (Float32/64) | `validate_float` with `as_f64().is_finite()` |
-| String `maxLength` (byte length) | `check_string` reads the field-level `maxLength` |
-| Bytes `maxLength` (array length) | `check_bytes` accepts the `Value::Array` form (the materializer emits bytes as an array of u8) |
-| Enum index bounds | `validate_enum` checks `idx < values.len()` — **fixes the v0.1.0 dead constraint** |
-| Union variant dispatch | `validate_union` reads `__discriminator`, looks up the variant, recurses via `validate_typeref` |
-| Struct fields | `validate_struct` walks `fields`, requires each declared field present, recurses |
-| Array count | `validate_array` checks `arr.len() == count` and recurses per element |
-| Record values | `validate_record` recurses into each value's `values` type |
-| Boolean | `validate_bool` (materializer already rejects non-0/1 bytes) |
+| Constraint | `ValidNode` arm |
+|------------|-----------------|
+| Integer range (Int8..Uint32) | `Int { min, max }` / `Uint { max }` with `as_i64`/`as_u64` + range check |
+| Int64/Uint64 (full range) | `I64` / `U64` (JSON precision caveat per ADR-005) |
+| Float finiteness (Float32/64) | `Float` with `as_f64().is_finite()` |
+| String `maxLength` (byte length) | `Str { max_len }` — `maxLength` baked in from the owning field at compile time |
+| Bytes `maxLength` (array length) | `Bytes { max_len }` — accepts the `Value::Array` form (the materializer emits bytes as an array of u8) |
+| Enum index bounds | `Enum { count }` checks `idx < count` — **fixes the v0.1.0 dead constraint** |
+| Union variant dispatch | `Union { variants }` reads `__discriminator`, dispatches on the compiled variant nodes |
+| Struct fields | `Struct { fields }` requires each declared field present, recurses |
+| Array count | `Array { count, element }` checks `arr.len() == count` and recurses per element |
+| Record values | `Record { values }` recurses into each value |
+| Boolean | `Bool` (materializer already rejects non-0/1 bytes) |
 
 No external JSON Schema is required for `validate_bytes`. The BAST
 document is the complete specification of the binary format — it
@@ -584,7 +588,8 @@ The `jsonschema` crate **remains a direct dependency** for
 meta-schema. The only thing removed is the custom keyword integration
 path. The `validate_bytes` path no longer touches `jsonschema` — a
 small wasm binary-size win in addition to the architecture
-simplification.
+simplification. (Since ADR-012 §3, the interpretation step itself is
+also compiled away: see the `ValidationPlan` above.)
 
 ### `AlkTypeError::Validation` payload shape
 

docs/architecture/decisions/012-plan-fingerprinting-and-m1-closure.md

@@ -2,7 +2,8 @@
 
 ## Status
 
-Proposed. Bundles three pieces of work into the 0.3.0 release so the
+Accepted. Implemented (§3's `ValidationPlan`, 0.3.0 phase 7, 2026-08-31);
+bundles three pieces of work into the 0.3.0 release so the
 crate ships one round of breaking changes, not two (or three). The
 three pieces: (a) fingerprinting `ReadPlan`/`OffsetMap`, (b) closing
 the deferred M1 sites via an owned `BastDoc` + `OffsetMap` `LeafMeta`,
@@ -11,6 +12,8 @@ and (c) a `ValidationPlan` that retires the interpretive
 `ValidationPlan`" decision — see "ValidationPlan — in scope for
 0.3.0" below). Companion to [ADR-011](011-compiled-read-plan-for-packed-mode.md)
 (the `ReadPlan`) and the [0.3.0 implementation plan](../../plans/030-compiled-forms.md).
+§3's concrete shape was scoped by the follow-on design session and is
+implemented in `src/validation_plan.rs` — see §3a below.
 
 ## Context
 
@@ -340,6 +343,69 @@ plan or stays a thin match over plan-carried descriptors. These are
 shape questions, not decision questions; the decision (in 0.3.0,
 compiled form, no per-buffer `BastDoc` walk) is fixed here.
 
+### 3a. `ValidationPlan` shape — resolved by the design session
+
+The follow-on design session (0.3.0 phase 7 predecessor) resolved the
+open shape questions; implemented in `src/validation_plan.rs`:
+
+- **Shape.** `ValidationPlan { root: ValidNode }`, a compiled
+  constraint tree — one `ValidNode` arm per value-domain check,
+  mirroring the interpretive walker's arms one-to-one:
+  `Int { min, max }` / `I64` / `Uint { max }` / `U64` / `Float` / `Bool`
+  / `Str { max_len }` / `Bytes { max_len }` / `Enum { count }` /
+  `Struct { fields: Vec<ValidField> }` / `Union { variants:
+  Vec<ValidVariant> }` / `Array { count, element }` / `Record
+  { values }`. `ValidField` carries `name + node`; `ValidVariant`
+  carries `key + node`. The nodes are public (diagnostics access via
+  `ValidationPlan::root()`); construction is only possible through
+  `compile`. Note the union node carries *only the variant nodes* — the
+  declared union `fields` (shared fields) are validated as part of the
+  variant walk, because the walker dispatches on the materialized
+  `__discriminator` and validates the whole object against the selected
+  variant (the `ValidNode::Union` doc comment records this; the
+  interpretive union arm recursed into the variant the same way).
+- **Constraint representation.** Inline scalar fields on the node arms
+  (ranges as `i64`/`u64` pairs, `maxLength` as `Option<usize>`, enum
+  bound as `count: u64`, union keys as owned `String`s). `maxLength` is
+  resolved from the *owning field* at compile time and baked into the
+  `Str`/`Bytes` leaf — the walk never consults field annotations. It
+  never crosses a `$ref` (a `$ref` always targets a struct/union/enum
+  `$defs` entry, so the interpretive walk could never consult it
+  through one either).
+- **`compile` signature.** `ValidationPlan::compile(&BastDoc) ->
+  Result<Self, AlkTypeError>` — the plan-table's `&str` root-name
+  parameter was vestigial (the doc already holds its root).
+- **`validate_value` disposition.** Retained as a one-shot wrapper:
+  `compile(doc)` + `validate(value)`. The interpretive walker behind it
+  is *retired* (deleted) — the wrapper delegates to the plan, so there
+  is one constraint implementation, not two. `bast_validation.rs` keeps
+  the shared error helper (`validation_err`) and the
+  `__discriminator` key constant.
+- **Error contract preserved.** The plan walk reproduces the
+  interpretive error messages byte-identically: a segment stack
+  (`field` / `[index]` / `[key]`) renders paths only on failure — zero
+  per-node allocation on the happy path. Numeric `__discriminator`
+  dispatch matches mapping keys without allocation for the u64/i64
+  forms (mapping keys are stringified integers; non-integer numbers
+  fall back to `Number::to_string`).
+- **Compile-time rejection of adversarial graphs.** Eager `$ref`
+  resolution with a definition-level cycle set and a depth cap (128):
+  a cyclic or self-referential schema is `AlkTypeError::Schema` at
+  compile, not a stack overflow — the interpretive walker resolved
+  `$ref`s lazily with no guard and could overflow on recursion.
+  Diamond (shared, non-cyclic) refs compile fine; the cycle set is
+  path-scoped.
+- **Engine integration.** `AlkTypeEngine` holds `Arc<ValidationPlan>`
+  built at `compile` time in *both* modes; the accessor
+  `validation_plan() -> &Arc<ValidationPlan>` is new public API.
+  `validate_bytes`'s signature is unchanged. The plan compile runs
+  *before* the layout build: it is the engine's reference-graph gate
+  (see Consequences).
+- **Scope note.** phase-7's `Send + Sync` / `Hash + Eq` /
+  `fingerprint()` requirements are structural on the types above
+  (`#[derive(...)]` on plain owned data; the same `DefaultHasher`
+  fingerprint as phase 6).
+
 ### 4. Fingerprinting `OffsetMap` (bundled with §2b)
 
 Since `OffsetMap` is getting new fields (`LeafMeta`) in §2b, its
@@ -380,11 +446,16 @@ aligned reads/writes over identical bytes.
   *contract* and method are in scope (§1, §3); the downstream uses
   (cache format, wire protocol) are the consumers' problem, not this
   ADR's.
-- The concrete `ValidationPlan` struct/enum shape and constraint
-  representation — scoped in the 0.3.0 implementation plan's
-  dedicated phase and a follow-on design session (see §3 "What this
-  ADR does *not* decide"). The decision (in 0.3.0, compiled form, no
-  per-buffer `BastDoc` walk) is fixed; the shape is not.
+- The `ValidationPlan` shape — **resolved** (§3a). Decided by the
+  design session and implemented in `src/validation_plan.rs`; the
+  decision (in 0.3.0, compiled form, no per-buffer `BastDoc` walk) was
+  fixed here.
+- Cycle-guard hardening for the *layout* walkers' own recursion
+  (`LayoutBuilder`/`OffsetMap` struct recursion) beyond the engine-path
+  gate described in Consequences — if a non-engine entry point walking
+  those types on untrusted docs becomes a consumer pattern, the
+  guards get their own change (the `AlkTypeEngine::compile` gate
+  covers the supported path today).
 - Cross-version fingerprint stability — the fingerprint is stable
   within a crate version but may change across versions (a new
   `AlkTypeKind` variant, for example, changes the hash). Cross-version
@@ -412,7 +483,23 @@ aligned reads/writes over identical bytes.
   half was not. Closing it here — while there are zero real consumers
   and one breaking bump already paying the downstream-churn cost —
   avoids a second breaking change to `validate_bytes`/`bast_validation`
-  after 0.3.0.
+  after 0.3.0. (Implemented: a spot benchmark of plan-validate on a
+  4-field mixed frame puts the validation half at ~0.2 µs/validate;
+  the compile-per-call one-shot it replaces runs ~2.7x slower before
+  the walk is even counted — and the full 0.2.0 per-buffer cost
+  included lazy `$ref` deep-clones that the one-shot no longer pays.
+  The materialize half, not validation, remains the dominant
+  `validate_bytes` cost.)
+- **Compile-time rejection of cyclic `$ref` graphs.** A side effect of
+  eager plan compilation: a self-referential document is now a clean
+  `Schema` error instead of a stack overflow. The plan compile runs
+  *before* the layout build in `AlkTypeEngine::compile`, making it the
+  engine's reference-graph gate — `LayoutBuilder`/`OffsetMap`
+  struct-recursion has no cycle guard and previously could recurse
+  unboundedly on such a document (a pre-existing untrusted-schema
+  hazard, surfaced by the phase-7 `compile_rejects_cyclic_ref_graph`
+  test). Hardening the layout walkers' own recursion is a separate
+  cleanup, not required while the gate holds in the engine path.
 - **Fingerprinting enables downstream uses.** Cross-run plan caching,
   `alkcall` schema handshake, and schema-version diagnostics all
   become possible without further API work — across `ReadPlan`,
@@ -431,8 +518,9 @@ aligned reads/writes over identical bytes.
 - **Breaking public-API changes (0.2.0 → 0.3.0).** `BastDoc<'a>` →
   `BastDoc` (owned) changes every `Bast*` signature that took `&'a`.
   `OffsetMap::get` return type changes. `LeafMeta` is new public.
-  `ReadPlan` is new public (from ADR-011). `ValidationPlan` is new
-  public (§3). All ride the bump.
+  `ReadPlan` is new public (from ADR-011). `ValidationPlan` (+ the
+  `ValidNode`/`ValidField`/`ValidVariant` node types) is new public
+  (§3a). All ride the bump.
 - **`BastDoc` ownership refactor is broad.** Touches `bast.rs` (every
   typed node: `&'a str` → `String`/`Arc<str>`, `&'a Value` →
   `Value`/`Arc<Value>`) and every consumer (`layout_builder`,
@@ -442,13 +530,21 @@ aligned reads/writes over identical bytes.
   anyway. The refactor is mechanical (lifetime removal, not logic
   rewrites); the POC on `readplan-poc` confirmed the read path is
   unaffected.
-- **`ValidationPlan` shape work is not yet scoped.** §3 fixes the
-  decision (in 0.3.0, compiled form) but defers the concrete shape to
-  a follow-on design session + a dedicated plan phase. This is a
-  tracked, owned deferral with a concrete reactivation trigger (the
-  shape session before phase 7), not a black-hole hedge: the
-  implementation phase is committed in the plan, so the work cannot
-  slip past 0.3.0 without reopening this ADR.
+- **Interpretive `validate_value` is compile-per-call.** The retained
+  one-shot wrapper (`bast_validation::validate_value`) compiles a plan
+  then validates — fine for one-off/diagnostic use, wrong for per-
+  buffer use. Per-buffer callers must hold the engine (or a plan) —
+  the doc comments say so. The walker it replaced had the inverse
+  trade (no compile, but interpretive per call); the engine path
+  (compile once) is the one that matters.
+- **Aligned-mode `maxLength`-reserved strings/bytes.** Materialization
+  emits the *full reserved* (zero-padded) data for these fields. A
+  `ValidationPlan` compiled from a document used in packed mode would
+  apply `maxLength` to trimmed length, matching packed semantics; the
+  aligned materializer's zero-padding means the value passed to
+  validation can carry trailing NULs. This is pre-existing
+  materialize behavior (not a plan artifact); consumers relying on
+  trimmed values already see it.
 - **Fingerprint cross-version stability is not guaranteed.** A future
   `AlkTypeKind` variant changes the hash. Documented as a within-
   version contract. Consumers that need cross-version stability
@@ -463,8 +559,7 @@ aligned reads/writes over identical bytes.
   M1 fixes are "cache the parse" (§2a) and "extend the compiled form
   with leaf metadata" (§2b), not "add a third compiled form."
 - **Not a `ValidationPlan` deferral.** `ValidationPlan` is in scope
-  (§3). The shape is to be scoped in a follow-on session; the
-  decision to ship in 0.3.0 is fixed.
+  (§3) and implemented (§3a); the interpretive walker is retired.
 - **Not cross-version fingerprint stability.** Within-version only.
 - **Not a disk-cache or wire-protocol spec.** The fingerprint contract
   and method are in scope; the downstream uses are the consumers'

docs/architecture/validation.md

@@ -1,6 +1,6 @@
 ---
 status: accepted
-last_updated: 2026-08-15
+last_updated: 2026-08-31
 ---
 
 # alktype — Validation
@@ -22,7 +22,7 @@ and recorded in [ADR-VAL-SPLIT](decisions/val-split-two-validator-model.md).
 
 | Path | Input | Validator | Schema source |
 |------|-------|-----------|---------------|
-| `validate_bytes(&[u8])` | Raw bytes | BAST-native validator (`bast_validation`) | The BAST document (binary layout + value constraints) |
+| `validate_bytes(&[u8])` | Raw bytes | Compiled `ValidationPlan` walk | The BAST document (binary layout + value constraints) |
 | `validate_json(&Value)` | Parsed JSON `Value` | Standard `jsonschema::Validator` | A consumer-provided standard JSON Schema |
 
 ### `validate_bytes` — bytes in, BAST is the validator
@@ -35,25 +35,39 @@ produces `Value::Number`), bounds are checked (via
 `data_access::check_bounds`), UTF-8 is valid (via `from_utf8`), the
 discriminator is in the mapping, and the boolean byte is 0 or 1.
 
-What the materializer does NOT check — and what the BAST-native
-validator checks afterward — are **value-domain constraints expressed
-in the BAST document**. The BAST-native validator
-(`src/bast_validation.rs`) is a recursive walker over the BAST typed
-tree ([`crate::bast::BastDoc`]/[`BastType`]) that checks exactly these:
+What the materializer does NOT check — and what the validation half
+checks afterward — are **value-domain constraints expressed in the BAST
+document**. Since ADR-012 §3 (0.3.0), those constraints are not walked
+interpretively per buffer: they are **compiled once** into a
+`ValidationPlan` ([`src/validation_plan.rs`](../../src/validation_plan.rs))
+at `AlkTypeEngine::compile` time, and each `validate_bytes` call walks
+the compiled constraint tree against the materialized `Value` — no
+`$ref` re-resolution, no schema re-parse, no per-node path formatting
+(error paths render only on failure). The plan's constraint nodes
+implement exactly the table below (the constraint set is unchanged from
+the retired interpretive walker):
 
-| Constraint | Validator arm |
-|------------|---------------|
-| Integer range (Int8..Uint64) | `validate_int`/`validate_uint` with `as_i64`/`as_u64` + range check |
-| Int64/Uint64 (full range) | `validate_int64`/`validate_uint64` (JSON precision caveat per ADR-005) |
-| Float finiteness (Float32/64) | `validate_float` with `as_f64().is_finite()` |
-| String `maxLength` (byte length) | `check_string` reads the field-level `maxLength` |
-| Bytes `maxLength` (array length) | `check_bytes` accepts the `Value::Array` form (the materializer emits bytes as an array of u8) |
-| Enum index bounds | `validate_enum` checks `idx < values.len()` — **fixes the v0.1.0 dead constraint** |
-| Union variant dispatch | `validate_union` reads `__discriminator`, looks up the variant, recurses via `validate_typeref` |
-| Struct fields | `validate_struct` walks `fields`, requires each declared field present, recurses |
-| Array count | `validate_array` checks `arr.len() == count` and recurses per element |
-| Record values | `validate_record` recurses into each value's `values` type |
-| Boolean | `validate_bool` (materializer already rejects non-0/1 bytes) |
+| Constraint | Plan node (`ValidNode`) |
+|------------|-------------------------|
+| Integer range (Int8..Uint32) | `Int { min, max }` / `Uint { max }` |
+| Int64/Uint64 (full range) | `I64` / `U64` (JSON precision caveat per ADR-005) |
+| Float finiteness (Float32/64) | `Float` with `as_f64().is_finite()` |
+| String `maxLength` (byte length) | `Str { max_len }` — `maxLength` baked in from the owning field at compile time |
+| Bytes `maxLength` (array length) | `Bytes { max_len }` — accepts the `Value::Array` form (the materializer emits bytes as an array of u8) |
+| Enum index bounds | `Enum { count }` checks `idx < count` — **fixes the v0.1.0 dead constraint** |
+| Union variant dispatch | `Union { variants }` reads `__discriminator`, dispatches on the compiled variant nodes |
+| Struct fields | `Struct { fields }` requires each declared field present, recurses |
+| Array count | `Array { count, element }` checks `arr.len() == count` and recurses per element |
+| Record values | `Record { values }` recurses into each value |
+| Boolean | `Bool` (materializer already rejects non-0/1 bytes) |
+
+The plan is a public type (`ValidationPlan`, `Debug + Clone +
+PartialEq + Eq + Hash + Send + Sync`): `engine.validation_plan()`
+exposes it for consumers that validate their own materialized `Value`
+trees or want its `fingerprint()` for caching / schema handshakes
+(ADR-012 §1). The one-shot `bast_validation::validate_value(&doc,
+&value)` remains as a convenience wrapper (compile + validate) for
+callers holding a BAST document without an engine.
 
 No external JSON Schema is required for `validate_bytes`. The BAST
 document is the complete specification of the binary format — it
@@ -122,12 +136,14 @@ simplification.
 The strategy is decided in [ADR-004](decisions/004-error-handling-validation-strategy.md)
 and refined by [ADR-VAL-SPLIT](decisions/val-split-two-validator-model.md):
 
-1. **Load time:** Parse the BAST document into the typed tree, compute
+1. **Load time:** Parse the BAST document into the typed tree, compile
+   the `ValidationPlan` (the value-domain constraint tree), compute
    the layout engine, and (optionally) build the standard
    `jsonschema::Validator` for the JSON-validation path. This is the
    `AlkTypeEngine::compile` constructor.
 2. **Access time:** Use the compiled engine for repeated read/write
-   operations. Validation is opt-in per operation.
+   operations. Validation is opt-in per operation: the validation half
+   walks the compiled `ValidationPlan`, never the BAST document.
 
 ### The `AlkTypeEngine` struct
 
@@ -138,6 +154,7 @@ supports both layout modes (ADR-002) via an internal `Layout` enum:
 pub struct AlkTypeEngine {
     layout: Layout,                          // packed or aligned (private enum)
     json_validator: Option<jsonschema::Validator>, // None when no JSON Schema supplied
+    validation_plan: Arc<ValidationPlan>,    // compiled value-domain constraints (ADR-012 §3)
     endian: Endian,                          // parsed from the root struct's "endian"
     bast_doc: Value,                         // retained for sequential_reader/read_field
     root_name: String,                       // the selected $defs entry
@@ -175,6 +192,7 @@ impl AlkTypeEngine {
     pub fn validate_json(&self, instance: &Value) -> Result<(), AlkTypeError>;   // D-BAST-007
     pub fn is_valid_json(&self, instance: &Value) -> bool;                        // D-BAST-007
     pub fn validate_bytes(&self, buffer: &[u8]) -> Result<(), AlkTypeError>;     // D-BAST-006
+    pub fn validation_plan(&self) -> &Arc<ValidationPlan>;  // compiled constraints (ADR-012 §3)
 }
 ```
 
@@ -273,16 +291,22 @@ The expensive work happens once at schema load time:
 
 1. Parse the BAST document into the typed tree (`BastDoc::new`).
 2. Parse the root struct's `"endian"` annotation.
-3. Compute the layout (`LayoutBuilder` for packed, `OffsetMap` for
+3. Compile the `ValidationPlan` — the value-domain constraint tree,
+   with eager `$ref` resolution. Its compile walk rejects cyclic `$ref`
+   graphs with a clean `Schema` error *before* the layout computation:
+   the layout walkers' struct/union recursion has no cycle guard, so
+   ordering the plan compile first is what keeps a self-referential
+   (malicious or accidental) document a handleable error, not a stack
+   overflow.
+4. Compute the layout (`LayoutBuilder` for packed, `OffsetMap` for
    aligned).
-4. If `json_schema` is `Some`, build the standard
+5. If `json_schema` is `Some`, build the standard
    `jsonschema::Validator` via `validation::build_validator`.
 
 The result is an `AlkTypeEngine` that can be used for repeated
-operations. The BAST-native validator is not pre-built — it is a
-recursive walker that runs on the materialized `Value` at access time,
-re-using the `BastDoc` (re-parsed on demand from the retained
-`bast_doc`).
+operations. The validation half is pre-built: the engine holds an
+`Arc<ValidationPlan>` and walks it per buffer without re-touching the
+BAST document (ADR-012 §3).
 
 ### Access time: `engine.validate_bytes(&[u8])`
 
@@ -297,10 +321,13 @@ sequence (D-BAST-006):
    → dispatch then recurse; `Record` → object of key/value entries).
    The read phase reuses the existing data-access functions and returns
    `AlkTypeError::Access` (with field paths) on read failures.
-2. **Validate the `Value`.** The materialized `Value` is passed to
-   `bast_validation::validate_value(&doc, &value)`, producing
+2. **Validate the `Value` against the `ValidationPlan`.** The
+   materialized `Value` is walked against the compiled constraint tree
+   (`engine.validation_plan().validate(&value)`), producing
    `AlkTypeError::Validation` on the first violated value-domain
-   constraint.
+   constraint. This is the ADR-012 §3 end state: the only per-buffer
+   schema-touching step is the materialize half (the bytes must be
+   decoded against the tree); the validation half is plan-fast.
 
 Mode dispatch:
 
@@ -308,7 +335,7 @@ Mode dispatch:
 - **Aligned mode** — uses the `OffsetMap` to read fields at their
   computed offsets.
 
-Both modes produce the same `Value` form; the BAST-native validator is
+Both modes produce the same `Value` form; the validation plan is
 mode-agnostic.
 
 ### Access time: `engine.validate_json(&Value)` / `engine.is_valid_json(&Value)`
@@ -379,9 +406,10 @@ then access the binary buffer.
 
 | Decision | ADR | Summary |
 |----------|-----|---------|
-| Two-validator model (BAST-native + standard jsonschema) | [ADR-VAL-SPLIT](decisions/val-split-two-validator-model.md) | `validate_bytes` uses the BAST-native validator; `validate_json` uses a standard `jsonschema::Validator` from a consumer-provided JSON Schema; D-BAST-006/007/009 |
+| Two-validator model (BAST-native + standard jsonschema) | [ADR-VAL-SPLIT](decisions/val-split-two-validator-model.md) | `validate_bytes` uses the compiled `ValidationPlan`; `validate_json` uses a standard `jsonschema::Validator` from a consumer-provided JSON Schema; D-BAST-006/007/009 |
 | Error handling and validation strategy | [ADR-004](decisions/004-error-handling-validation-strategy.md) | `AlkTypeError` enum; load-time build, access-time check; field-path-carrying errors; jsonschema `ValidationError` wrapping |
 | Generalized validation — `validate_bytes` | [ADR-010](decisions/010-generalized-validation-validate-bytes.md) | Single-call binary-buffer validation (materialize `Value` from bytes, then validate); two methods on one struct, not a trait |
+| Compiled `ValidationPlan` | [ADR-012](decisions/012-plan-fingerprinting-and-m1-closure.md) | The value-domain constraint tree is compiled once at `compile` (eager `$ref` resolution, cycle rejection) and walked per buffer; `Hash + Eq` + `fingerprint()`; retires the interpretive `BastDoc` walk |
 | BAST format | [ADR-BAST](decisions/bast-bast-format.md) | The BAST document is the complete binary-format spec (layout + value constraints) |
 
 ## Open Questions
@@ -397,15 +425,19 @@ see [builder.md](builder.md).
   — the normative validation model
 - [ADR-VAL-SPLIT](decisions/val-split-two-validator-model.md) — the
   two-validator decision
+- [ADR-012](decisions/012-plan-fingerprinting-and-m1-closure.md) — the
+  `ValidationPlan` decision (§3)
 - [ADR-004](decisions/004-error-handling-validation-strategy.md) —
   error handling and validation strategy
 - [ADR-010](decisions/010-generalized-validation-validate-bytes.md) —
   `validate_bytes` (the collapsed two-step dance)
 - [schema-layer.md](schema-layer.md) — the BAST parser that the
-  BAST-native validator walks
+  plan compiler consumes
 - [data-access.md](data-access.md) — read/write functions and the
-  materializer that produce the `Value` the validator checks
+  materializer that produce the `Value` the plan checks
+- [`src/validation_plan.rs`](../../src/validation_plan.rs) — the
+  compiled `ValidationPlan` implementation
 - [`src/bast_validation.rs`](../../src/bast_validation.rs) — the
-  BAST-native validator implementation
+  one-shot wrapper (`validate_value`) and shared error helpers
 - [`src/validation.rs`](../../src/validation.rs) — the `build_validator`
   helper

docs/plans/030-compiled-forms.md

@@ -1,7 +1,7 @@
 ---
 status: in-progress
 created: 2026-08-19
-last_updated: 2026-08-20
+last_updated: 2026-08-31
 adr: ADR-011, ADR-012
 ---
 
@@ -566,7 +566,36 @@ are trait derives, `fingerprint` is an inherent method).
 
 ---
 
-## Phase 7 — `ValidationPlan` (ADR-012 §3)
+## Phase 7 — `ValidationPlan` (ADR-012 §3) — **DONE (2026-08-31)**
+
+> **Status: implemented.** The design session ran and the shape landed
+> in `src/validation_plan.rs`. Summary of what was decided and built
+> (full detail in ADR-012 §3a):
+>
+> - **Shape:** `ValidationPlan { root: ValidNode }` — a constraint tree
+>   with one arm per value-domain check (`Int`/`I64`/`Uint`/`U64`/
+>   `Float`/`Bool`/`Str`/`Bytes`/`Enum`/`Struct`/`Union`/`Array`/
+>   `Record`), `ValidField { name, node }`, `ValidVariant { key, node }`.
+>   `maxLength` baked into leaf nodes from the owning field at compile
+>   time. Unions compile to variant nodes only (the declared union
+>   fields are validated via the variant walk, matching the interpretive
+>   arm's dispatch-on-`__discriminator` semantics).
+> - **`compile` signature:** `compile(&BastDoc) -> Result<Self,
+>   AlkTypeError>` (the plan table's `&str` param was vestigial).
+> - **`bast_validation`:** the interpretive walker is *retired*
+>   (deleted, not just bypassed); `validate_value` survives as a
+>   compile-once-per-call wrapper over the plan (one-shot/diagnostic
+>   use); shared error helper retained.
+> - **Engine:** `Arc<ValidationPlan>` built at `compile` in both modes;
+>   new accessor `validation_plan()`. `validate_bytes` walks the plan.
+> **Bonus:** `ValidationPlan::compile` runs before the layout build and
+> serves as the engine's cyclic-`$ref` gate (the layout walkers have no
+> cycle guard; a cyclic doc used to be a stack-overflow hazard there —
+> now a clean `Schema` error, see ADR-012 Consequences).
+> - **Remaining phase-7 bench work** (a `validate_bytes`-stream bench
+>   in alktty) moves with the bench work into phase 8; a spot check
+>   during development measured plan-validate at ~0.2 µs/call vs ~0.6
+>   µs for the compile-per-call one-shot it replaced.
 
 **Goal:** Retire the interpretive `bast_validation` walk. Introduce a
 `ValidationPlan` — a compile-once-walk-many compiled form over the