Repository navigation
docs: v3 lens capability register + Band C honesty-pass - #634
Conversation
…pass 2026-04-21 audit (prompted by the complexity-v2-v3-comparison-receipt brief dispatch) found that v3's complexity lens does not subsume v2's complexity analysis. v2 produces symbolic CostExpr/SizeExpr with work/span/certainty/asymptotic-class; v3 produces a single integer depth per port. The "~13× LOC reduction" framing in the brief and ROADMAP was comparing different functions of the program, not equivalent ones. Extending the audit to all ten lenses under src/v3/lenses/ surfaced the same pattern in three more files (cost.dag PROXY, idempotency.dag and parallelism.dag STUBs dispatching to Rust oracles). Common root causes: v3 substrate missing DescentEvidence/CallPattern/ SubValueRelation/MethodSemantics carriers; v3 emitter unable to lower match on user-defined sums. The pattern was invisible at the file level because "TERMINAL" reads as both structural (pure catamorphism, fail-closed) and behavioral (subsumes the named analysis) — but only the first was ever load-bearing for the marker. This reconcile PR separates the two axes so the gap is legible without another audit. Changes: 1. NEW docs/v3-lens-capability-register.md — canonical table of what every registered .dag lens actually computes, keyed against v2 counterparts where they exist. Two-axis status system: STRUCTURALLY (TERMINAL|PARTIAL|UNSOUND) + BEHAVIORALLY (COMPLETE|PROXY|STUB|N/A). Discipline section: every new registry entry requires a register row; every "v3 replaces v2 X" claim requires a behavioral cementing test; review at every ROADMAP dispatch. 2. Honesty-pass on all ten lens headers. Band C (complexity, cost, idempotency, parallelism) gets sharp correction distinguishing structural from behavioral status. Band A (provenance, unused_parameters, variant_payload, structural_resolution) and Band B (infer_helpers, lower_helpers) get consistent Status: lines pointing at the register. 3. ROADMAP.md: register linked at top of file alongside spec/ validation/lineage. The 2026-04-21 complexity-receipt debt row rewritten — retracts the "~13× LOC reduction" framing, widens the brief scope from "complexity receipt + registry rename" to "Band C honesty pass", names the substrate + emit dissolution paths. Follow-ups (separate lanes, not in this PR): - Rewrite docs/briefs/complexity-v2-v3-comparison-receipt.md against the register (scope widens per the ROADMAP entry). - Port DescentEvidence/CallPattern/SubValueRelation/MethodSemantics into the v3 substrate (program of work, not a lane). - Generalize the behavioral-cementing-test discipline to every regen.dag entry. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
|
Review metadata
This is a docs-only PR: a new capability register document, ROADMAP row rewrite, and comment-header status markers added to nine The diff directly improves faithfulness (INVARIANTS P1) by retracting the earlier "v3 complexity subsumes v2 with 13× LOC reduction" claim that was comparing different functions of the program, and by separating "structurally terminal" from "behaviorally complete" as two orthogonal axes. The register's root-cause analysis (missing substrate carriers blocks complexity/cost; missing Spot checks:
One small observation, not a finding: the register says (§Discipline #1) "every registry entry in VerdictAPPROVE — docs-only honesty pass. Retracting an overclaim and installing a two-axis status vocabulary is exactly the kind of authored-faithfulness move INVARIANTS P1 calls for, and the debt it surfaces is routed to existing ROADMAP entries rather than forked into parallel tracking. |
|
Review metadata
ReviewThis is a documentation honesty-pass. The diff:
No Rust or Verification of factual claims in the register
Alignment with the rubricThe change is squarely in service of P1 Modeling Faithfulness: a lens labeled 🟢 TERMINAL while computing a weaker function than its name implies is exactly the "name overclaims what the construct grounds in" failure mode P1 names. The two-axis marker separates structural well-formedness from behavioral subsumption, which is the right cut — a catamorphism is not automatically a complete replacement for what it claims to replace. The change is also aligned with P5 Progress Is Dissolution. Each of the three non-trivial scaffolds (complexity PROXY, cost PROXY, idempotency/parallelism STUB) now has (1) documented state, (2) bounded scope via the header, and (3) named dissolution triggers (substrate carriers for DescentEvidence/CallPattern/SubValueRelation/MethodSemantics; emit-level No findings. VerdictAPPROVE — this is a retraction + register that makes the repo more honest, not less. The claims in the register check out against the tree, the discipline rules are consistent with the regen registry, and the ROADMAP row rewrite accurately describes the scope widening. Net epistemic gain with zero code risk. Exploratory observations (optional)
|
|
Review metadata
Verdict: APPROVE. This looks like an honest documentation/status correction, not a shape regression: the new register and per-lens headers downgrade the proxy/stub lenses instead of overclaiming equivalence, which is aligned with P1's live-state/documentation discipline. I did not find a concrete diff-grounded violation of the pinned invariants, coding discipline, or testing discipline. |
|
Review metadata
Verdict: APPROVE — docs-only honesty pass. Claims match the actual lens code (verified This directly supports INVARIANTS P1 (Modeling Faithfulness) — it makes a latent overclaim visible and names the substrate ( Exploratory observations (non-blocking):
|
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 0f2209e7f6
ℹ️ 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".
| |---|---|---|---|---|---| | ||
| | `complexity.dag` | TERMINAL | **PROXY** | `src/v2/complexity.dag` (5488L) | `CostLookup = FoundCost(Int) \| MissingCost` per port | `CostExpr` (Sum/Mul/Log/Const), `SizeExpr`, work/span split, `Certainty`, asymptotic classification, recurrence bounds | | ||
| | `cost.dag` | TERMINAL | **PROXY** | v2 `CostExpr` (embedded in `complexity.dag`) | `SymbolicCostLookup = FoundCost(SymbolicCost) \| MissingCost` per port | Named `SizeVar` with value semantics (v3's `SizeVariable` carries only `source_port: PortId`). `Dimension<SymbolicCost>` wiring deferred on grammar gaps. No cementing test. | | ||
| | `idempotency.dag` | PARTIAL | **STUB** | None (v3-native) | `WorkflowIdempotencyReport` via dispatch | — (analysis lives in `src/v3/compiler/src/workflow_idempotency.rs`; the `.dag` is a registration shim) | |
There was a problem hiding this comment.
The register marks idempotency.dag as a Rust-oracle stub, but the lens actually delegates to std.effects::lane2_workflow_idempotency_report, whose analysis is implemented in src/v3/std/effects.dag (lane2_workflow_idempotency_report), while workflow_idempotency.rs is documented as a mirror/projection path. Because this register is explicitly used to gate roadmap/brief dispatch, this misclassification can cause planning decisions to treat an existing DAG analysis as unavailable and incorrectly defer work.
Useful? React with 👍 / 👎.
|
Review: APPROVE — high-leverage single artifact, scope-correct, discipline-section makes it operational. This is exactly the durable output the audit needed. The register converts dispersed signal (scattered ROADMAP debt rows + per-file headers + memory entries) into one structured view that's checkable per-lens before any future brief claims "v3 replaces v2 X." What's load-bearingTwo-axis status system. "What v2 has that v3 drops" column. Per-row, per-file gap visibility. This is the column that makes overclaiming in a brief mechanically harder — a future me/SG-manager/worker has to look at the row, see the column populated, and then either fill it with "N/A" (claiming completeness) or work the gap. That's the failure mode that produced my brief, structurally prevented. Common root causes section. Naming the substrate gap ( Discipline section makes the register operational. Five rules including:
ROADMAP integration is exactly right
Reviewer-sanity questions answered
Yes, definitively. The capability table reads top-down without prose: a reader sees
Strictly separate. The row already encodes that: "brief rewrite queues for after the 2026-04-21 wave's 5 lanes land and this register is in tree." Right call. The brief's new scope (Band C honesty pass) needs the register as input, so the dependency is naturally sequenced. Don't bundle. One non-blocking observationThe register's discipline rule #3 ("review at every ROADMAP dispatch") is procedural — relies on humans/AI consulting the doc. The top-of-ROADMAP callout reinforces this. A possible follow-up (separate PR, not this one): add a one-line pointer to the register from No changes requestedReady to merge. This is the kind of artifact that'd be cited in retrospectives as the moment when v3-lens claims became reviewable rather than narrative. 🤖 Director review |
|
Review metadata
Docs-only PR. The diff: (1) a new Checks performed
Exploratory observations (non-blocking)
Verdict: APPROVE. Honest retraction of a prior overclaim, adds a named diagnostic frame (two-axis status) that maps cleanly onto existing modeling-faithfulness principles, and propagates the frame to every relevant file in a single pass. No violations of INVARIANTS/CODING/TESTING in the diff. |
|
Review metadata
Findings
Verdict: APPROVE_WITH_COMMENTS. The two-axis status pass is otherwise clean and materially improves honesty around the lens surface, but I would drop or rewrite the stale |
|
Review metadata
Findings None that block. Two minor observations:
Neither rises to a violation — both are comment hygiene. Verdict: APPROVE This is a documentation-only honesty pass. No substrate changes, no code changes — the Exploratory observation (optional) The register's discipline item #1 ("Every registry entry in |
|
Review metadata
Findings
Verdict: APPROVE_WITH_COMMENTS. The honesty-pass itself looks clean and directionally correct, and I did not find a substantive modeling/coding/testing violation in the changed lens headers. I would fix the broken ROADMAP reference before treating the new register as canonical. |
|
Review metadata
Findings
Verdict |
|
Review metadata
Verdict: APPROVE This looks clean. The diff is an honesty/documentation pass plus header annotations; it removes overclaim rather than introducing new modeled authority, and the remaining gaps are documented, bounded, and given concrete blockers/triggers. I didn’t find a concrete violation of the pinned invariants, coding discipline, or testing discipline in the changed lines. |
|
Review metadata
This is a pure documentation PR: one new register file, status-marker headers added to nine Spot checks against the diff's claims:
Verdict: APPROVE. This is a textbook honesty-pass — it retracts a prior overclaim ("~13× LOC reduction with structurally stronger fail-closed guarantees"), separates structural-vs-behavioral status into two orthogonal axes so that Exploratory observation (not an ask): the register puts the two unblockers — (a) carrying |
|
Review metadata
Verdict: APPROVE — honest, well-scoped docs-only correction. This is a docs-only PR that retracts a previously overclaimed thesis ("~13× LOC reduction with structurally stronger fail-closed guarantees") and introduces a two-axis capability register (structural × behavioral) so the same class of overclaim is harder to re-introduce. No code under review. Spot-checks against the diff:
This is exactly the work INVARIANTS P1 (Modeling Faithfulness) asks for when names overclaim relative to what code produces. The discipline section of the new doc also gives it dissolution leverage: future PRs claiming "v3 subsumes v2 X" must update a row, and the register is cross-linked from ROADMAP so it's in the dispatch path. No findings. |
|
Review metadata
Verdict: APPROVE. This reads as an honesty-pass rather than a semantic change, and the diff stays consistent with the pinned rubric: the new register matches the current lens set, the per-file status headers are aligned across |
|
Review metadata
Findings
Verdict |
briansrls
left a comment
briansrls
left a comment
There was a problem hiding this comment.
Review metadata
- Provider / model:
codex/gpt-5.4 - Commit:
0f2209e7· Trigger:schedule - Thinking:
378s wall
Non-blocking — Strengths
docs/v3-lens-capability-register.mdThe new two-axis register is honest against the live code: the Band C rows match the actual v2 surface, the current v3 lens bodies, and the Rust-backed authority split.
ROADMAP — Verified
- Band C honesty pass: The register covers all ten
src/v3/lenses/*.dagfiles and every currentLensRegistryEntryinsrc/v3/compiler/regen.dag, so the new pre-dispatch check is mechanically grounded.
✅ I checked the changed claims against the lens sources, src/v2/complexity.dag, the Rust oracle modules, and the existing lens migration/integration tests, and I do not have concerns.
|
Review metadata
1. Story of the diffThis PR is a documentation honesty-pass, not a semantic compiler change. It adds a central 2. Invariant categories
N/A — diff is docs/comment-only; it does not change substrate types, Dag fields, or cross-pass authorities.
Finding (NON-BLOCKING) — P2 Boundary Discipline / single-authority metadata; Practice 5 + Practice 6.
N/A — no Rust implementation, helper placement, naming surface, or error-carrier code changed.
Compliant — no executable behavior changed, so new tests were not required here; instead the diff tightens the contract around testing by defining
N/A — this PR does not alter a locked design decision; it retracts equivalence overclaims and documents current blockers instead.
Compliant — the incomplete lenses are explicitly classified as 3. VerdictAPPROVE_WITH_COMMENTS This is a useful and materially more honest PR: it separates “structurally clean” from “behaviorally equivalent,” retracts the old complexity overclaim, and names the actual substrate/emit work that remains. I would not block the docs correction, but I do think the new status scheme should eventually collapse to one authority instead of being hand-authored in both the central register and each lens header. Exploratory observations
|
1 participant
Summary
docs/v3-lens-capability-register.md— canonical table of what every registered.daglens actually computes, keyed against v2 counterparts where they exist. Two-axis status system (STRUCTURALLY × BEHAVIORALLY) with discipline rules for how to keep it current.Context — why this PR exists
During dispatch of
docs/briefs/complexity-v2-v3-comparison-receipt.mdon this worker, I started reading v2's complexity authority (src/v2/complexity.dag, 5488 lines) to prepare a fixture/golden comparison. v2 producesComplexitySummary { work: CostExpr, span: CostExpr, output_size: Map<String, CostExpr>, certainty }with symbolic size variables, work/span split, and asymptotic classification (classify_complexity -> "O(n log m)"). v3'ssrc/v3/lenses/complexity.dagproducesCostLookup = FoundCost(Int) | MissingCostper port — a structural-depth proxy.The two lenses compute different functions of the program. The brief's three possible outcomes ("identical / v3 richer / v3 misses X") didn't apply; none of them captures "v3 is a weaker function, rebranded."
Extending the audit to the other 9 lenses under
src/v3/lenses/surfaced the same pattern in three more:cost.dag— PROXY. Richer symbolic shape thancomplexity.dag, butSizeVariablecarries onlysource_port: PortId(no name, no value semantics). Dimension wiring deferred. No cementing test.idempotency.dag(28 lines) — STUB. Header says "Rust entryv3_compiler::analyze_workflowre-exports the Rust oracle." The.dagis a dispatch shim; the analysis lives insrc/v3/compiler/src/workflow_idempotency.rs.parallelism.dag(18 lines) — STUB. Body unconditionally returnsreport_parallelism_unsupported(LensSurfacePending, …). Real analysis insrc/v3/compiler/src/workflow_parallelism.rs.Common root cause: v3 substrate does not yet carry
DescentEvidence/CallPattern/SubValueRelation/MethodSemantics(which v2's complexity analysis depends on), and the v3 emitter cannot yet lowermatchon user-defined sums (which forces idempotency/parallelism to live in Rust).Why the gap was invisible
"🟢 TERMINAL" on a lens file reads as both structural (pure catamorphism, fail-closed, bounded) and behavioral (subsumes the named analysis). Only the first was ever load-bearing for the marker. This PR splits the axes and makes the distinction explicit in every lens header. A lens is only "done" when both axes are at their strongest grade.
Not in this PR (follow-ups)
docs/briefs/complexity-v2-v3-comparison-receipt.mdagainst the register (scope widens per the ROADMAP entry).DescentEvidence/CallPattern/SubValueRelation/MethodSemanticsinto the v3 substrate (program of work).regen.dagentry.Test plan
cargo fmt --all --check(runs in pre-push hook) — passed.dagfile headers (comments only, no structural changes to lens bodies)docs/v3-lens-capability-register.mdend-to-end — does the two-axis status system make the 4 Band C gaps legible without additional context?🤖 Generated with Claude Code