Skip to content

Code health: decide whether hole and feature leader placement should share one engine (ADR 2) #1937

Open

Description

@pzfreo

Deferred follow-up from code-health epic #1939. Evidence pinned to main @ 71b8c94. The maintainer deferred hole/feature leader convergence until after #1939 so that this goal remains limited to refactors that preserve successful drawing output. This issue remains open but is not an exit criterion for #1939.

Question

There are two leader-placement engines:

  • Hole callouts go through holes._place_queue, a strip-candidate queue built on _common.place_strip_candidates and PAVA.
  • Other machined-feature leaders go through leaders.place_feature_leader_jobs, a search plus a 407-line greedy, reached from from_model.py:3196.

holes.py never calls the leaders engine. ADR 2 says to extend a shared pass rather than add a copy.

Task

Investigate whether the split is justified, for example by something hole-specific such as tabulation or bolt circles, or whether it is historical.

  • If historical, propose a convergence plan.
  • If justified, write the reason in docs/architecture.md.

This is a maintainer decision before any code moves, because it may touch ADR 2.

Investigation and agreed direction (2026-09-28)

A fresh read-only agent found no hole-specific drafting rule that requires a permanent second leader engine. Sparse ordinary and pattern holes already use the late FeatureLeaderJob inventory. The remaining split preserves plan/side PAVA row order, binding authored side, physical rim tips, pre-staged bolt-circle furniture, and dense-hole table escalation/rollback. Those are producer and transaction contracts to carry into the shared solve. The maintainer has already authorised convergence in small verified PRs if no hole-specific reason exists; no ADR text change is authorised without sign-off on exact wording.

Progress: #1974 added the candidate-stream adapter. #1989 moved front/rear hole leader rim-tip, elbow and Leader construction into FrontHoleLeaderCandidateAdapter with exact live corpus parity and CI; row selection and strip commit still use the existing engine. Dense/profiled migration and final convergence remain open. ADR 2 text is unchanged.

Migration worklist:

  • Extract a reusable hole candidate adapter for row, side, rim-tip and fallback candidates without changing commit behavior.
  • Migrate front/rear and profiled holes separately; retain PAVA row seeds and physical-tip constraints.
  • Migrate dense scattered holes last, preserving table escalation, grouped balloon and furniture rollback after the final leader outcome.
  • Remove the duplicate commit engine only after placed/dropped measurement IDs, labels, owners, furniture, tables, authored-side refusal, lint and live corpus signatures match. Include forced budget/failure cases and no benchmark regression.

2026-09-30 next-seam audit on unpublished 0f9534c9

No small direct reroute of remaining hole paths through place_feature_leader_jobs was found that preserves successful drawings. Sparse plan/side jobs already share a HoleStripPlan and late candidate inventory. Dense/profiled _place_immediate_queue commits only final PAVA survivors, assigns hc_* names after drops in natural-Y order, and adds furniture after placement; the shared path reserves names and stages furniture before a late solve that can choose alternate rows/sides. Front callouts use a distinct below-view strip, approved-X-witness text side, and front_hole_callouts trace. producer_floor=True still applies different validation/drop rules, so a direct route can change identity, furniture, trace, or placement.

The next staged step is an exact, preconditioned behavior guard across immediate/front, dense/profiled, authored-side and deferred-replay cases, including name, owner/measurement, geometry, issue/drop, furniture and trace signatures. Only then should an ordered preselected-PAVA survivor transaction be considered for the shared rank-4 commit owner, without rerunning joint assignment. The intended deletion target is the 104-line immediate emitter, but a net reduction is a design target, not a proved patch. No production code or ADR text changed in this audit; full convergence and no-behavior-change acceptance remain open.

2026-09-30 local pre-convergence guard

The test-only slice b5badaf9 in /private/tmp/dw1937-hole-outcome-guard records existing immediate dense hole callout name/order, owner and measurement identities, profiled bore routing, front below-view placement and trace linkage, and pattern furniture rollback on an immediate drop. It stays in behavior-owned test modules and does not change production or ADRs. Fourteen focused/shape/clone cases passed; an immediate emitter-order mutation and a front producer-order mutation each failed named assertions after substitution was confirmed, and a provenance mutation failed the dense owner guard. Fresh independent review found no P0–P3 issue after fixed front Y coordinates were replaced with legal-bounds and trace-to-rendered-elbow checks. This guard is local and not merged; it does not by itself prove parity for a future engine migration. It will accompany the next actual #1937 convergence slice rather than trigger a separate CI cycle.

2026-09-30 preselected-commit design check

A local production prototype on the reviewed guard branch preserved byte-identical 14 CAD plus three STEP drawing/lint/decision/trace signatures against 0f9534c9; four focused dense forced-text/Policy-B, profiled Double-D, and front-trace cases passed. It was discarded before commit: removing the 104-line immediate emitter required a 46-line generic coordinator and 68 new lines in the hole queue, added eight callback parameters, and saved only ten net production lines while enlarging _place_queue. This moved complexity rather than materially converging the engines. No benchmark was run for the rejected design. The clean local branch 6568df7a retains only the reviewed test guards; no production PR, CI, or ADR change followed. #1937 remains open for a simpler typed survivor transaction that preserves exact PAVA outcomes, identity, rollback, and trace.

2026-09-30 local architecture-map correction

Reviewed docs-only local commit 1d19f9c8 (after unpublished 636a34d4) records the current three placement paths in docs/architecture.md: sparse plan/side PAVA seeds followed by late joint inventory; front/rear below-view strip survivor commit; dense/profiled queue-wide immediate PAVA survivor commit. It names shared physical construction and the immediate/late commit_feature_leader seam, plus the ownership, furniture, indexing, authored-side, and trace contracts future convergence must preserve. Fresh review caught and fixed an incorrect front/rear shared-commit claim and an overstatement that would have treated the split as permanent; final review found no P0–P3 finding and static/docs gate passed. The document changes no ADR wording or production behavior. This is migration documentation, not acceptance of a permanent exception to ADR 2; #1937 remains open. No PR/CI or merge under the current branch-write approval block.

2026-09-30 dependent documentation integration

The corrected architecture note from isolated 1d19f9c8 is now incorporated unchanged as fb1a74d9 in the dependent /private/tmp/dw1939-fourth-local unit alongside a #1935 duration-data refresh. Exact-head static/docs gate and a fresh independent combined-head review passed with no P0–P3 finding. It describes the existing migration state; the engine convergence work and #1937 remain open. No PR/CI or merge under the current GitHub branch-write approval block.

2026-09-30 maintainer deferral

The maintainer chose to postpone this convergence until after epic #1939 and keep the current goal on output-preserving refactors. The existing architecture map documents the split; that does not waive ADR 2 or close this issue. A future solution needs either a simpler exact-parity convergence or maintainer sign-off on specific ADR 2 wording for a justified exception. No production code or ADR text changes under this decision.

Activity

  1. added
    questionFurther information is requested
    tech-debtInternal maintainability or refactoring work
    designArchitecture or API design work
    area:layoutLayout, placement, scale/page, strips, repack
    on Sep 28, 2026
  2. pzfreo commented on Sep 28, 2026

    @pzfreo
    OwnerAuthor

    First convergence slice merged in #1974 (321c95cc). Ordered physical candidate streams for sparse plan/side hole leaders now live in a rank-4 adapter feeding the existing shared late leader assignment. The hole pass still owns strip solve, table eligibility, furniture/coverage transaction, and immediate commit. Dense/profiled paths are unchanged.

    Independent review checked row order, authored side, physical tip ownership, fallback floors, and transaction behavior; its architecture-map finding was fixed. Focused tests, exact three-hole leader/lint parity, static checks, and all CI jobs passed. No ADR text changed. Remaining engine convergence stays open under this issue.

  3. pzfreo commented on Sep 29, 2026

    @pzfreo
    OwnerAuthor

    Fresh read-only investigation after #1974/#1989 found no safe small additional convergence slice that preserves exact drawing and solve-trace behavior. Sparse plan/side holes already enter FeatureLeaderJob. Front/rear holes still commit ranked PAVA rows through place_strip_candidates with the front_hole_callouts trace; moving that commit to the feature-leader search would change selection and event identity. Dense scattered and profiled holes keep an immediate _place_queue path whose final names and coverage govern table escalation and staged furniture rollback. #1989 already shares front physical leader construction.

    No source or ADR text was changed. #1937 remains open. A next migration needs explicit parity gates for PAVA survivors, trace events, measurement coverage, table escalation, and furniture rollback, including forced failure/budget cases. The active #2027/#2036 leader refactors should settle before attempting that transaction change.

  4. pzfreo commented on Sep 29, 2026

    @pzfreo
    OwnerAuthor

    Next convergence slice: #2098 is open against the reviewed #2084 stack tip. It shares physical hole-callout leader construction across direct, front-strip, sparse-shared, and immediate dense/profiled paths while preserving each path's selection, solve, rollback, and commit rules. A fresh independent review approved it; static/focused checks, a load-bearing mutation, exact 14 CAD + 3 STEP drawing/lint/decision/trace parity, and paired timings passed with no measured regression. Required GitHub CI is pending. The separate commit-engine convergence acceptance remains open.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    area:layoutLayout, placement, scale/page, strips, repackdesignArchitecture or API design workquestionFurther information is requestedtech-debtInternal maintainability or refactoring work

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions