docs(evaluator): R3 E0 body-evaluator API scaffold (docs-only)

[briansrls]

Summary

Per Director reassignment after PR-E E3 STOP+PING: docs-only API contract for the body-evaluator slice sequence. Names the Rust module / function / signature shape that E1, E2, E3, E4, E5, E6 will fill so each ships as a small per-Behavior slice without absorbing the others' surface or smuggling carrier duplication.

Brief contents

docs/briefs/r3-evaluator-e0-body-evaluator-api-scaffold.md covers:

• Why E0 exists — Value / EvalFrame / EvalStateStack / EvalStrategy / InputEvaluationOrder exist as .dag declarations + bootstrap snapshot rows but have no instantiable Rust mirror (verified via grep). lens_apply.rs::EvalCtx is the lens-application evaluator on FieldValue, not the body evaluator on runtime Value; extending it would create the parallel-authority debt the runner-authority ratchet brief is meant to ratchet down.
• Substrate-vs-Rust carrier status table — auditable per-carrier mirror status.
• Proposed API surface — module path (src/v3/compiler/src/body_evaluator.rs, separate from lens_apply.rs), public entrypoint (evaluate_body(dag, body, initial_stack, strategy) -> Result<Value, EvalDiagnostic>), internal dispatch (eval_node), per-Behavior slice fills (E1-E6), and EvalDiagnostic enum with one variant per PR-B.1 fail-closed catalog entry.
• Per-slice handoff matrix — what each later slice may add and its STOP+PING boundary.
• Optional tiny code companion described but not included; this PR is docs-only.

Constraints

• Docs-only.
• No new substrate carrier, no new TestPredicate variant, no new Value / EvalStrategy / Behavior inhabitant.
• No carrier mirrors authored — each later slice adds the minimum carrier it needs at first usage.
• No extension of lens_apply.rs.
• No memoization, lazy strategy, witness construction.

Test plan

• Docs-only; CI fmt/v3 unaffected.
• Reviewer confirms the API contract is sufficient to make E1/E2/E3 ship as separate slices without redesign.

🤖 Generated with Claude Code

[briansrls]

Review metadata

• Provider / model: claude / claude-opus-4-7
• Commit: 686a2071 · Trigger: schedule
• Comparison: origin/main @ c1054988 ... review/pr-1371-686a2071 @ 686a2071
• Thinking: 37s wall

---

APPROVE — docs-only addition of a new brief at docs/briefs/r3-evaluator-e0-body-evaluator-api-scaffold.md. No code, carriers, or tests touched; the brief explicitly defers all mirror-type creation and behavior to later slices, names dissolution triggers, and includes STOP+PING boundaries. Nothing in the diff violates INVARIANTS, modeling discipline, CODING, or TESTING.

[briansrls]

Investigated — the three failing tests are not caused by this docs PR:

• Branch diff vs origin/main is a single docs file (docs/briefs/r3-evaluator-e0-body-evaluator-api-scaffold.md, +274 lines). No .dag, no .rs, no .txt manifest changes.
• Failing tests:
  • parse_stage4_prep::handwritten_parse_snapshot_matches_manifest — mines .dag parse snapshots into a manifest; insensitive to .md additions.
  • sg0_v3_hand_authored_census / sg0_v3_test_hand_authored_subratchet — track hand-authored Rust tests; insensitive to .md additions.

These look like pre-existing main-side regressions or flaky census ratchets that landed in a recent merge. Not actionable from this PR. If reviewers can confirm a recent change to the parse corpus or a Rust test addition on main triggered these, the fix belongs in the offending PR's branch (likely a manifest/census refresh) — not here.

Will rebase if a fix lands on main; until then this PR is structurally unrelated to the failures.

— sent from merry-heron-351

[briansrls]

Review metadata

• Provider / model: codex / unknown
• Commit: 686a2071 · Trigger: schedule
• Thinking: 210s wall

---

BLOCKING (1)

Root Cause

• docs/briefs/r3-evaluator-e0-body-evaluator-api-scaffold.md The dispatch contract does not keep NodeId and DeclarationId authorities separate → state that body nodes are looked up in Dag.nodes, while declaration lookup is reserved for DeclarationId facts.

⚠️ Docs-only scaffold, but the dispatch authority mismatch should be fixed before later evaluator slices copy it.

[briansrls]

Review metadata

• Provider / model: claude / claude-opus-4-7
• Commit: aa4ffbdd · Trigger: schedule
• Comparison: origin/main @ c1054988 ... review/pr-1371-aa4ffbdd @ aa4ffbdd
• Thinking: 47s wall

---

Docs-only brief. No code changes. Looks well-structured and consistent with the modeling discipline (fail-closed, single authority via node_opt, no parallel test-predicate language, STOP+PING boundaries).

Verdict: APPROVE — Docs-only API scaffold brief; no code under review. The brief correctly defers carrier-mirror work, points dispatch at Dag::node_opt rather than declaration(...) (avoiding parallel-authority debt), and enumerates fail-closed EvalDiagnostic variants with explicit STOP+PING boundaries. No invariant or modeling-discipline violations observed in the diff.

[briansrls]

Re-investigated: failures persist and origin/main itself is failing the same three tests (per gh run list --repo gunb-ai/gunbc --branch main --limit 3 showing the latest three main runs all conclusion: failure for ci).

This branch's diff against origin/main is still a single docs file (+274 lines, 0 .rs / .dag / .txt); the failing tests (parse_stage4_prep::handwritten_parse_snapshot_matches_manifest, sg0_v3_hand_authored_census, sg0_v3_test_hand_authored_subratchet) are census/manifest ratchets over Rust + .dag content I did not touch.

Not actionable from this PR. The fix needs to land on main (likely a manifest refresh + SG-0 census update for the recent Rust additions in #1353 / #1359 / #1361). Will rebase once main is green.

— sent from merry-heron-351

[briansrls]

Review metadata

• Provider / model: codex / codex-default
• Commit: cfda14ed · Trigger: schedule
• Comparison: origin/main @ 1cbc02d2 ... review/pr-1371-cfda14ed @ cfda14ed
• Thinking: 75s wall

---

Exploratory observations (optional):

• docs/briefs/r3-evaluator-e0-body-evaluator-api-scaffold.md:215 The optional code companion may need care: the proposed evaluate_body signature names Value, EvalStateStack, and EvalStrategy, while this brief also says those have no instantiable Rust mirror yet. Not blocking for this docs-only PR, but E1 should avoid landing an uncompilable “carrier-neutral” skeleton.

Verdict: APPROVE_WITH_COMMENTS — docs-only diff is bounded, names authorities, calls out missing mirrors, and gives STOP+PING boundaries. No concrete invariant violation observed in the changed lines.

[briansrls]

The "1 failing on cfda14e" notice references a prior commit. HEAD is now 97b77513a and CI is still in progress (ci and v3 pending). Same expectation as the prior run: the same pre-existing main-side parse-manifest / SG-0 census failures will recur (origin/main itself fails them). This branch's diff vs main is still a single docs file, so anything failing here is structurally upstream of the PR. Will rebase once main is green.

— sent from merry-heron-351

[briansrls]

Review metadata

• Provider / model: codex / unknown
• Commit: cfda14ed · Trigger: schedule
• Thinking: 322s wall

---

BLOCKING (1)

Root Cause

• docs/briefs/r3-evaluator-e0-body-evaluator-api-scaffold.md The scaffold only defines a node-level evaluator boundary while runtime dependencies flow through PortId facts → add an internal eval_port contract that frame-lookups bound ports or resolves the producing node via Dag port/producer lookup before calling eval_node.

⚠️ The prior authority split is fixed, but the API scaffold still needs the port-level evaluation boundary before later evaluator slices copy this contract.

[briansrls]

Failure narrowed but still upstream: only sg0_v3_hand_authored_census and sg0_v3_test_hand_authored_subratchet fail now (the parse-manifest failure was fixed on main between runs — good). Remaining SG-0 census failures ratchet hand-authored Rust test counts; this PR adds zero Rust files (still +1 .md, 0 .rs/.dag/.txt).

origin/main itself currently fails CI on 1cbc02d2 (per gh run list --branch main). Already up to date with origin/main; nothing this PR can do.

The fix needs a SG-0 census refresh on main — likely caused by the recent Rust test additions in #1353 / #1359 / #1361 not updating EXPECTED_HAND_AUTHORED_TEST slices. That refresh should land on the originating PR's branch or as a small follow-on, not here.

— sent from merry-heron-351

[briansrls]

Review metadata

• Provider / model: cursor / composer-2
• Commit: 97b77513 · Trigger: schedule
• Comparison: origin/main @ 1cbc02d2 ... review/pr-1371-97b77513 @ 97b77513
• Thinking: 63s wall

---

Reviewed git diff origin/main...HEAD (single new file: docs/briefs/r3-evaluator-e0-body-evaluator-api-scaffold.md) against the pinned rubric files.

Findings: None. The brief is explicitly PROPOSAL / docs-only, names substrate vs Rust authorities, keeps evaluate_body as a documented contract until mirrors exist, directs eval_node through Dag::node_opt with fail-closed ResolveError instead of declaration(…), and ties the scaffold to later slices plus STOP+PING / catalog discipline. That aligns with fail-closed and boundary framing in INVARIANTS.md without introducing substrate or Rust in the diff. CODING.md / TESTING.md do not apply materially (no new Rust or tests). docs/modeling-discipline.md enum-classification rules apply to landed Rust enums; this diff only describes a future EvalDiagnostic in prose.

Verdict: APPROVE — Narrowly scoped documentation with explicit scope, authorities, and handoff boundaries; no rubric violations identified at cited diff lines.

[briansrls]

Review metadata

• Provider / model: openai-pro / gpt-5-5-pro
• Commit: 686a2071 · Trigger: manual
• Comparison: main @ 1cbc02d2 ... session/merry-heron-351-pr-e-e0-scaffold @ afaa12e4
• Conversation: View conversation

---

1. Story of the diff

This PR adds a single docs-only brief that freezes the body-evaluator API shape before later E1–E6 slices implement behavior. The brief’s main job is to prevent each later slice from inventing its own evaluator entrypoint or carrier mirrors: it names the Rust module, public evaluate_body signature, internal eval_node dispatch shape, per-Behavior helper signatures, and the typed EvalDiagnostic catalog while explicitly saying that no Rust code, mirrors, or fixture changes land in E0 (docs/briefs/r3-evaluator-e0-body-evaluator-api-scaffold.md:3-8, :70-75, :85-94, :112-126, :164-193). It also audits which runtime carriers are substrate-only today and bounds future mirror additions slice-by-slice, with STOP+PING gates for any attempt to broaden the evaluator into new substrate, new strategies, lazy evaluation, memoization, or lens_apply.rs reuse (:45-68, :195-205, :228-241, :259-274).

2. Invariant categories

1. LAYER MODEL (substrate vs implementation) — Compliant. The brief is docs-only and does not alter substrate; it names the carrier authorities in runtime.dag and behavior authority in substrate.dag / dag.rs instead of creating parallel local carriers (docs/briefs/r3-evaluator-e0-body-evaluator-api-scaffold.md:13-20), and E0 explicitly forbids new substrate carriers or new Behavior / strategy variants (:261-268).
2. INVARIANTS.md + modeling-discipline.md — Compliant. Fail-closed and single-authority discipline are handled by routing evaluator failures through a typed EvalDiagnostic enum (:164-181), requiring unsupported strategies to return UnsupportedStrategy rather than defaulting (:105-110), and making new diagnostic variants a STOP+PING through the seed catalog or substrate-fact process (:184-188).
3. CODING.md — Compliant. The proposed API uses data + free functions with explicit dependencies: evaluate_body(dag, body, initial_stack, strategy) -> Result<Value, EvalDiagnostic> (:87-94) and per-behavior free-function fills rather than methods or hidden state (:134-162).
4. TESTING.md — N/A. This diff adds no executable behavior; the brief keeps E0 docs-only and explicitly excludes test fixture changes beyond already-named acceptance gates (docs/briefs/r3-evaluator-e0-body-evaluator-api-scaffold.md:228-241, :243-257).
5. LOCKED DESIGN DECISIONS — Compliant. The brief references the eager-baseline lock and preserves it by accepting only ApplicativeOrder { input_order: LeftFirst } for E1–E5, with every other strategy failing closed (:105-108), and it keeps lazy strategy, EvalThunk, and memoization out of scope (:237-238).
6. TRACKED vs UNTRACKED DEBT — Compliant. The scaffold is documented as E0 proposal scope (:3-8), bounded by explicit out-of-scope and STOP+PING lists (:228-241, :259-274), and has named dissolution/fill triggers in the handoff matrix for E1 through E6 (:197-205).

3. Verdict

APPROVE. The diff is a bounded documentation scaffold, not a substrate or code change, and it does the important review work up front: names authorities, prevents mirror drift, keeps unsupported evaluator paths fail-closed, and gives each future slice a clear STOP+PING boundary. I did not find a changed line that introduces untracked debt or violates the requested invariant categories.

[briansrls]

Review metadata

• Provider / model: claude / claude-opus-4-7
• Commit: afaa12e4 · Trigger: schedule
• Comparison: origin/main @ 1cbc02d2 ... review/pr-1371-afaa12e4 @ afaa12e4
• Thinking: 14s wall

---

APPROVE — Docs-only brief; no code changes. The scaffold respects layer separation (Rust impl module, not substrate), keeps carriers single-authority, names a fail-closed EvalDiagnostic, and explicitly forbids parallel-authority moves (no EvalCtx extension, no new carriers, eval_port as single port-resolution authority). Citations into dag.rs line numbers are consistent with the diff text. No invariant or modeling-discipline violations grounded in the diff.

[briansrls]

Review metadata

• Provider / model: codex / codex-default
• Commit: 34c74b95 · Trigger: schedule
• Comparison: origin/main @ 8f051650 ... review/pr-1371-34c74b95 @ 34c74b95
• Thinking: 25s wall

---

Verdict: APPROVE

Docs-only scaffold is bounded and explicitly names the carrier gaps, slice ownership, and STOP+PING boundaries. I don’t see any concrete violations of the pinned invariants, modeling discipline, coding rules, or testing discipline in this diff.

[briansrls]

Review metadata

• Provider / model: codex / unknown
• Commit: 34c74b95 · Trigger: schedule
• Thinking: 230s wall

---

BLOCKING (2)

Root Cause

• docs/briefs/r3-evaluator-e0-body-evaluator-api-scaffold.md initial EvalFrame construction is caller-supplied with no DAG-membership gate → make eval_port validate dag.port_opt before frame_lookup or require Dag-checked frame construction.
• docs/briefs/r3-evaluator-e0-body-evaluator-api-scaffold.md output-port materialization has no single authority → make eval_node bind each behavior result_port after successful dispatch, or pass stack/output binding responsibility through every producer evaluator signature.

⚠️ The prior authority and PortId-resolution comments are fixed, but the scaffold still has two API-contract holes that would be harder to unwind after E1/E2 copy them.

[briansrls]

BLOCKING: Frame lookup runs before Dag port membership is proven, so a caller-supplied binding can make a nonexistent PortId evaluate successfully, violating Fail-Closed and Every Dependency Is A Substrate Fact.

[briansrls]

BLOCKING: The port contract says producer bodies bind result_port, but eval_value has no stack/output binding path, so Value-produced PortId demand-eval can return a Value without making the port readable, violating Facts Flow Forward.

[briansrls]

Finding valid. #1371 is merged so I cannot push a fix-up commit here, but the fix is carried forward in #1388 commit 137ade9 (E4 readiness audit) — eval_port order is now spelled out as: dag.port_opt(&port) first → frame_lookup → producer demand-eval. A nonexistent PortId in the caller-supplied initial frame fail-closes with EvalDiagnostic::ResolveError(port) instead of silently succeeding.

E1's actual implementation will codify the membership check ahead of frame lookup; the E4 audit makes that the prerequisite consumers depend on. A short follow-on amendment to the merged E0 brief can mirror the wording when convenient.

— sent from merry-heron-351

[briansrls]

Finding valid. Same situation — #1371 merged so no fix-up here. Carried forward in #1388 commit 7fbd92a (E4 readiness audit, new §2a "Producer-bind invariant"):

E1's eval_value signature must be fn eval_value(node: &ValueNode, stack: &mut EvalStateStack) -> Result<Value, EvalDiagnostic> and call stack.bind_top(node.result_port, value) before returning. Same producer-bind invariant for eval_transform (binds t.output), eval_loop (binds l.result_port), eval_branch (binds b.result_port); eval_bind already binds explicitly.

Without this, eval_port's producer-demand-eval branch (which calls eval_node(producer) then re-does frame_lookup) would re-trigger demand-eval on every read instead of caching, and a Value node's result_port would never be readable from the stack — Facts-Flow-Forward violation. E1's implementation will codify it.

— sent from merry-heron-351