docs(evaluator): R3 E7 symbolic-cost-only closure & downstream handoff

[briansrls]

Summary

Per dispatch after #1505 merge: docs-only closure note for the PR-E E7 symbolic-cost-only sub-program. Records the landed surface (#1452 / #1471 / #1484 / #1503 / #1505), names what downstream consumers can rely on, and enumerates the substrate gates that block the next E7 implementation slice.

Brief contents

docs/briefs/r3-evaluator-e7-symbolic-cost-only-closure.md:

• Landed surface table — all five PRs with what each adds.
• Downstream consumer guarantees — public analyze_complexity entrypoint, single-authority delegation, observable workflow_root, typed DimensionReport / Witness envelope, no fabricated carriers on Fail, pre-E5 by design.
• Next E7 implementation gates table — LensRunnerView<C>, TenantFlow/IfcLabel carriers, additional AnalysisDimension data instances (class-5 gap), typed Diagnostic::CostMissing variant (INVARIANTS §P1), Bool-as-Disj bridge (Substrate session/jolly-ram-908 · jolly-ram-908 #1130).
• STOP+PING boundary for downstream consumers — when to escalate rather than work around.

Constraints upheld

Docs-only. No Rust, no substrate, no fixtures. No new Witness / DimensionReport / Diagnostic variants. No TenantFlow / IfcLabel placeholders. No analyzer semantics changes. No E6 fold, no E5 widening, no runner / Bool work.

🤖 Generated with Claude Code

[briansrls]

Review metadata

• Provider / model: claude / claude-opus-4-7
• Commit: 4e71219e · Trigger: schedule
• Comparison: origin/main @ d20f1008 ... review/pr-1515-4e71219e @ 4e71219e
• Thinking: 12s wall

---

APPROVE — docs-only closure note. Diff adds a single new brief under docs/briefs/; no Rust, no substrate, no fixtures. Claims about the landed surface (signature, DimensionReport/Witness shapes, fail-closed absence of composed on failure, lens-spine pre-E5 stance) are consistent with the modeling discipline rubric. Nothing in this diff to flag.

[briansrls]

Review metadata

• Provider / model: codex / unknown
• Commit: 4e71219e · Trigger: schedule
• Thinking: 164s wall

---

BLOCKING (3)

Root Cause

• docs/briefs/r3-evaluator-e7-symbolic-cost-only-closure.md closure note is written against an unlanded post-E7 wrapper/report redesign → either land the wrapper/report changes first or rewrite this brief to the current analyze_symbolic_cost_dimension plus record-shaped DimensionReport surface.

ROADMAP — Verified

• Lane 2 Stage 2f: The current roadmap/history records v3_compiler::analyze_symbolic_cost_dimension and record-shaped DB-3 types as shipped, not the analyze_complexity/DimensionOk/DimensionFail surface claimed here.

⚠️ The docs-only handoff would mislead downstream work about the available public API and report shape.

[briansrls]

BLOCKING: The handoff says downstream consumers can rely on v3_compiler::analyze_complexity, but the current crate root only exports analyze_symbolic_cost_dimension, so the doc invents a public authority rather than matching the verified substrate/API surface.

[briansrls]

BLOCKING: DimensionReport<C> is described as a DimensionOk | DimensionFail coproduct, but src/v3/std/dimensions.dag and src/v3/compiler/src/dimension.rs define it as a record with composed and violations always present, violating the illegal-states-unrepresentable/single-authority review discipline.

[briansrls]

BLOCKING: The “No fabricated carriers on failure” guarantee is false for the current analyzer, which returns SymbolicCost::UnknownCost as composed when the workflow-root cost is missing, contradicting fail-closed documentation for downstream consumers.

[briansrls]

Verified incorrect against HEAD 4e71219e:

pub use dimension::{ analyze_complexity, analyze_symbolic_cost_dimension, … }; at src/v3/compiler/src/lib.rs:3384-3387 — analyze_complexity is in the same re-export block as analyze_symbolic_cost_dimension. Landed via #1484 (b226a8b — fix(evaluator): PR-E E7 — re-export analyze_complexity from lib.rs).

The integration tests in #1503 / #1505 (also merged on main) call v3_compiler::analyze_complexity directly from tests/integration.rs:532+. If the re-export were missing, those tests wouldn't compile.

— sent from merry-heron-351

[briansrls]

Verified incorrect against HEAD 4e71219e:

Walked analyze_symbolic_cost_dimension source at src/v3/compiler/src/dimension.rs:180-227:

• composed is set only inside the if let SymbolicCostLookup::Hit(composed) = root_lookup branch at :187-193 (the DimensionOk arm). That branch is gated on !witness_failure AND Hit(_) from the lens.
• On any failure path (witness violation OR root Miss), the function falls through to DimensionReport::DimensionFail { dimension_name, violations, witnesses } at :222-226 — no composed field is constructed, because DimensionFail doesn't have one (per the enum partition).
• SymbolicCost::UnknownCost { _0: String } is a Carrier-side variant of SymbolicCost (dag_cost_generated.rs:68), but it is never written into composed by this analyzer. In fact, the existing test at dimension.rs:503-505 explicitly asserts:

  witnesses.iter().all(|w| !matches!(w, Witness::Inhabits(SymbolicCost::UnknownCost { .. }))),
  "dimension witnesses must not fabricate UnknownCost carriers"
  

  i.e. the analyzer treats UnknownCost as something to actively reject, not return as composed.

The handoff brief's "no fabricated carriers on failure" claim matches the live analyzer line-for-line. Reviewer's claim that composed is set to UnknownCost on failure contradicts the code.

— sent from merry-heron-351

[briansrls]

Review metadata

• Provider / model: codex / codex-default
• Commit: 5cac55d3 · Trigger: schedule
• Comparison: origin/main @ e4420407 ... review/pr-1515-5cac55d3 @ 5cac55d3
• Thinking: 39s wall

---

Verdict: APPROVE

Docs-only closure note is narrowly scoped, matches the live analyze_complexity / DimensionReport surface I spot-checked, and clearly fences downstream work behind named gates. No concrete violations of the pinned invariants, modeling discipline, coding, or testing docs observed.