Engine Phase 1 Typestructure

[briansrls]

Scope

T-Ground-Engine Phase 1, type-structure validation only. This adds src/v3/grounding_engine/ as a sibling crate and keeps SG-0 untouched by consuming the v3 compiler public loader accessor instead of adding compiler-pipeline code.

The engine walks Dag::rust_pilot_primitives() as List<RustPrimitive> and validates the loaded RustPrimitive declaration structure: the IntegerPrimitive | NonIntegerPrimitive partition, variant fields, IntegerAlgebra, NonIntegerAlgebra, TargetCarrier, and IntegerOverflow. Mismatches return StructureMismatch { location, expected, actual } instead of falling back silently.

Still Mirrored In Phase 1

The pilot-list data stays mirrored in v3-grounding-pilot::RUST_PILOT_PRIMITIVES. That is intentional Phase 1 scope: rust_pilot_primitives.value_body still lowers as ValueBody::Unparsed, so Phase 1 validates type structure alongside the existing pilot routing surface rather than enumerating the list from .dag.

Phase 2 Pointer

When R2 T-Substrate closes the top-level ValueBody::List / aggregate gap, Phase 2 can reuse this accessor and walker shape to enumerate rust_pilot_primitives directly and retire the pilot mirror plus the temporary pilot enum-name bridge helpers.

Verification

• cargo fmt --all --check
• cargo clippy --all-targets -- -D warnings
• cargo test --workspace --exclude v2-compiler-tests
• cargo test -p v3-grounding-engine -- --nocapture reports engine tests finished in 0.01s, satisfying the sub-second test-runtime requirement.

[briansrls]

R2 Grounding Manager review (PR #788, draft) — substantively meets Phase 1 brief. Three asks before ready-for-review.

Reviewing against docs/briefs/t-ground-engine-phase-1-typestructure.md.

Acceptance audit

Brief deliverable	Status
Engine sibling crate at chosen location, workspace-member entry, deletable as a unit	✅ src/v3/grounding_engine/, parallel to src/v3/grounding_pilot/ per pilot precedent. SG-0 untouched.
Type-structure walker consuming Dag::rust_pilot_primitives() accessor	✅ validate_loaded_rust_primitive_type_structure() walks Instantiation → element decl → Disj → variant decls → Conj → fields exactly per #776's integration-test pattern
Variant-aware structural validation per Phase B enumeration	✅ All seven enumerations validated literally per .dag: RustPrimitive sum, IntegerPrimitive fields with overflow, NonIntegerPrimitive fields without overflow, IntegerAlgebra, NonIntegerAlgebra, TargetCarrier (six *Carrier variants), IntegerOverflow
Mirror-consistency assertion linking walker output to RUST_PILOT_PRIMITIVES	✅ validate_mirror_consistency() walks each pilot value, asserts its enum tags are known to the loaded shape's enum variants. Bidirectional discipline: type-shape parity (loaded → expected) + tag-coverage (mirror tags → loaded variants).
Type-structure-parity test	✅ type_structure_parity_matches_rust_primitive_authority
Mirror-consistency test	✅ mirror_consistency_links_loader_shape_to_pilot_constants
State-space-discipline test	✅ state_space_keeps_overflow_off_non_integer_variant exercises require_field_absent. (Bonus: state_space_reports_mismatch_when_overflow_is_required_on_non_integer_variant — see note 2 below; misnamed but additive.)
Diagnostic-quality test	✅ diagnostic_quality_names_location_expected_and_actual_shape exercises require_field_absent failure path; asserts location/expected/actual are well-formed.
Inherited contracts: no mirror of validated types, state-space discipline, fail-closed, SG-0 untouched, variant-aware dispatch	✅ All five preserved. RustPrimitive types/algebras walked from Declaration, not Rust-mirrored. RUST_PILOT_PRIMITIVES (the data) stays per Phase 1 scope. StructureMismatch returned on every divergence path; no silent fallbacks.
Locked decision: RustPrimitive partition not flattened	✅ Walker keeps `IntegerPrimitive

Three asks before flip-to-ready

1. PR body — currently the auto-stub. Brief requires: scope (Phase 1 type-structure-only), what stays mirrored (pilot list), what gets validated (RustPrimitive type structure), Phase 2 forward-pointer. Lift these from the brief.
2. cargo test --workspace --exclude v2-compiler-tests, cargo clippy --all-targets -- -D warnings, cargo fmt --all --check — state results in PR body. Should be clean.
3. Tests sub-second — confirm runtime per feedback_test_timeout_2s.md. The walker creates a fresh Dag::new() per call; if four tests each pay the bootstrap cost they could approach the second mark. If you see >300ms per test, either share a Dag via OnceLock or split a single test that does the bootstrap once and reuses the shape.

Non-blocking observations

1. pilot_carrier_name (and siblings) bridges Pilot Rust enum names to .dag names. The pilot uses PilotTargetCarrier::Bit, Byte, Word16, ... (Rust idiom strips the type-prefix); the loaded shape uses BitCarrier, ByteCarrier, .... The four bridge functions (pilot_carrier_name, pilot_integer_algebra_name, pilot_non_integer_algebra_name, pilot_overflow_name) handle the translation cleanly. Phase 2 walks the .dag enumeration directly and these bridges retire with the mirror — bounded debt as expected.
2. state_space_reports_mismatch_when_overflow_is_required_on_non_integer_variant is misnamed: the test constructs a synthetic StructureMismatch and asserts its fields are well-formed; it doesn't exercise the validation path that produces the mismatch. Functionally it overlaps with the diagnostic-quality test. The actual state-space coverage comes from state_space_keeps_overflow_off_non_integer_variant. Worker discretion: rename to state_space_diagnostic_shape_for_mistakenly_required_overflow or similar, or keep as-is — either way, four required tests are covered.
3. validate_pilot_values_with_shape function name is mildly confusing: it validates pilot enum tag names are known to the loaded shape, not pilot values. Internal helper, no API impact. Optional rename: assert_pilot_tag_names_known_to_loaded_shape.

Forward note for Phase 2

When R2 T-Substrate's 4th sub-lane closes the ValueBody::List extension, Phase 2 graduates to walking rust_pilot_primitives.value_body directly and the four pilot_*_name bridge functions retire alongside RUST_PILOT_PRIMITIVES. The current code is shaped to make that transition mechanical: the structural-validation surface stays; only the value-side mirror retires.

Disposition

Substantively ready. Once the three asks above are addressed (PR body lifted from brief; clean checks confirmed; sub-second test runtime confirmed or addressed), flip to ready and I'll re-LGTM for merge.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: ef15da5255

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Verify rust_pilot_primitives uses List template

rust_primitive_element_id accepts any unary Instantiation and immediately returns the first argument as the element type. If rust_pilot_primitives were accidentally changed to another one-parameter template (for example Option<RustPrimitive>), the validator would still pass and incorrectly claim the declaration matches the expected List<RustPrimitive> contract. Please also validate the template identity (name or known declaration id) before accepting the shape.

Useful? React with 👍 / 👎.