Skip to content

Perf: lint each drawing state at most once (12 lint passes on grm03) #1945

Description

@pzfreo

Originally tracked in code-health epic #1939; now an open performance follow-up. Profiled on main @ 71b8c94 with py-spy and call-count wrappers on a 4-core box (timings ±20%). The parts were a build123d box with five holes, evaluation/blind-hole.step, grm03_thumbwheel_drive_screw_ap242_pmi.step and nist_ctc_02_asme1_ap203.stp, all built through build_drawing(src) with defaults. On simple parts about 90% of build time is build123d/OCC work on annotation, text and title-block geometry. HLR is 1–3% and recognition 0.3–5%.

Problem

Lint runs 4–5 times on simple parts and 12 times on grm03 (5.0 s):

  • layout_selection.py:366–368 calls drawing.lint() and then drawing.lint_summary(), which lints the same drawing again straight away.
  • repair.py:134/181/204 runs a full lint after every attempted repair.

Proposal

  • Reuse lint results within a build attempt only while the internal drawing state and critique mode are unchanged. Public lint after return must reflect later edits.
  • Have lint_summary take the issues it is given instead of re-linting.
  • Consider incremental re-lint in repair, limited to the touched annotations. That is a larger change; decide after the memoisation lands.

Acceptance

  • During a build attempt, each unchanged drawing state is linted at most once per critique mode (physical=False and physical=True). A counted-call test of actual Drawing.lint calls fails if duplicate passes return. State changes permit fresh lint; public edits after return must still receive fresh findings.
  • Lint output is identical.
  • The ADR 5 independence of lint is preserved: memoisation must not let lint read placement internals.

2026-09-30 local assessment

The literal at-most-once acceptance remains open. A local structural-stage/cache candidate reduced counted traversals on the exercised Box and GRM03 paths and preserved 17 CAD/STEP drawing, lint, decision, and trace signatures, but its 554 inserted versus 75 deleted lines across source and tests added substantial state bookkeeping. Fresh reviews found stale safety evidence when _post_build returned an edited alternate Drawing, and duplicate traversal for an unchanged hook result. The measured build-time effect was near natural noise. The candidate was kept local and removed from the next aggregate. A read-only audit also found that its new tests count _lint_structure traversals while the stated acceptance requires counted lint calls; it cannot close this issue. The next attempt needs a smaller design, a demonstrated timing benefit, and a guard that measures the literal requirement. No ADR changed.

2026-09-30 no-table Sheet follow-up (local, partial)

A reviewed local slice (1c097806, later integrated as 58c85427) omits the no-op Sheet table hook when there are no tables and passes the build-local placement critique into final automatic-plan checking. A named test counts literal Drawing.lint(physical=False) calls on the returned declared Sheet: one after the change, versus three and two when the two source seams are independently reversed. Declared recognition stays lazy, real table hooks stay active, 17 CAD/STEP and Sheet parity matched the reviewed base, focused/static checks passed, and independent review found no blocking issue. It has not been published or merged.

The full acceptance remains open. On the reviewed base, a normal Box still receives structural and physical critique on one returned object. ADR 3 delays physical recognition for a declared render, and public Drawing lists/dicts/annotations remain mutable; a persistent cross-call cache needs complete invalidation or an immutable/versioned state contract to preserve fresh lint findings. Counting only _lint_structure traversals would not prove the issue's literal requirement. Do not close #1945 for this partial slice.

2026-09-30 exact local design audit

On unpublished 0f9534c9, counted Drawing.lint calls for a returned automatic Box are [physical=False, physical=True]: the first is placement critique in the repair/build flow; the second is final physical safety/report evidence. A declared no-table Sheet has [False] during build, and its first public physical lint triggers the ADR 3 lazy recognition transition. Moving a live dimension after lint changed a later structural result from no findings to two annotation_out_of_bounds; appending a registry issue also changes the result. Thus a persistent public cache needs reliable mutation detection across exposed drawing collections, registry, model, page fields, and live shapes, plus separate critique modes and safe result ownership.

In 20 local runs, medians were Box build 164.3 ms, in-build placement critique 13.9 ms, in-build physical critique 2.09 ms, and unchanged public full lint 1.50 ms; declared Sheet's first physical lint was 23.8 ms including recognition. These are machine-local timing observations, not a claimed general speedup. Existing caches remain scoped to a stable build attempt. The literal once-per-drawing-state acceptance is not met; a complete solution needs either an orchestrated build critique across modes or a larger mutation-tracking contract. The maintainer's choice on whether literal acceptance includes public post-return edits is pending. No ADR or public behavior changed in this audit.

2026-09-30 fresh literal-acceptance design check

Independent read-only review on unpublished a2588358 followed the counted Drawing.lint call graph. An automatic build needs lint(physical=False) during placement/repair, then lint(physical=True) through finished safety/report evidence; declared builds must keep physical recognition lazy under ADR 3. Routing placement through a private lint function would only hide a counted call and bypass public subclass dispatch (guarded by test_build_local_placement_critique_keeps_subclass_lint_dispatch). A persistent cache cannot identify an unchanged public Drawing reliably while its items, views, registry issues, annotation objects, scale and page remain directly mutable; existing tests require fresh results after public edits. Therefore no small correct slice meets the literal “at most once per drawing state” criterion under current public mutation semantics. The already merged build-local reuse remains a valid narrower optimization. Closing literal acceptance needs a public immutable/versioned state boundary with complete invalidation and its own ADR review, or maintainer approval to restate the criterion per finished attempt and critique mode. No code, ADR or issue acceptance wording changed in this audit; the earlier async scope question remains pending.

Maintainer acceptance decision (2026-09-30)

The maintainer accepted build-attempt-and-mode scope for the lint-reuse target. Persistent caching across public edits is outside this issue. Keep ADR 3 declared recognition lazy and ADR 5 lint independent, preserve lint output, and require measured no-regression evidence before closing.

2026-09-30 maintainer disposition

The maintainer chose to close #1939 promptly and keep this issue open as a separate measured performance follow-up. The accepted build-attempt, per-mode counted-call acceptance is not met for the Sheet table and opaque post-build hook paths. Existing reuse remains merged, but the small table-only experiment had no reliable useful timing gain and did not handle an unchanged arbitrary hook. An opaque hook can return the same Drawing identity after either no change or a lint-relevant in-place edit, so reuse without a reliable change contract risks stale findings. No new cache, changed public behavior, or ADR change is claimed by this disposition. Resume only with a simpler design that passes literal counted-call, output-parity, and no-regression gates.

Activity

  1. added
    tech-debtInternal maintainability or refactoring work
    area:lintLint, critique, reconciliation, suggestions
    on Sep 28, 2026
  2. pzfreo commented on Sep 29, 2026

    @pzfreo
    OwnerAuthor

    #2005 merged on main at f90e1ec. It reuses the finished placement critique across builder gates: counted full lint calls fell from 12 to 9 on GRM03 and from 5 to 3 on the blind-hole specimen. The new guard asserts the shared assessment snapshot, and live drawing/lint snapshots match its parent byte for byte. CI passed.

    This is a partial improvement. Repair still lints earlier drawing states, and the issue's each-state-at-most-once acceptance is not yet met; the issue stays open. The next slice is being scoped around the repair-to-builder handoff and mutation boundaries, with a counted-call regression test.

  3. pzfreo commented on Sep 29, 2026

    @pzfreo
    OwnerAuthor

    PR #2008 merged on main at ce3449de. It passes the build-local placement critique from repack and repair through builder trials, so the same returned drawing is not linted again at those handoffs. Counted GRM03 calls fell from 9 to 6 (placement calls 8 to 5); the blind-hole returned-drawing placement calls fell from 2 to 1. The 14-case live drawing and ordered-lint signature remained byte-identical to the parent, and the PR passed independent review, local gates, and CI.

    The issue remains open: these counts do not yet prove that every distinct physical drawing state is critiqued at most once, as the acceptance requires.

  4. pzfreo commented on Sep 29, 2026

    @pzfreo
    OwnerAuthor

    Fresh main @ 0e64c646 count audit for #1939:

    • build_drawing(path) on tests/fixtures/evaluation/blind-hole.step makes 2 Drawing.lint() calls: one placement critique and one physical critique.
    • GRM03 AP242 PMI makes 6: five placement critiques across changed repack states and one physical critique.
    • The remaining duplication is reproducible on build_drawing(Box(20, 10, 5), page="A4", scale=2): two full physical critiques of the same returned view/item/registry state, from explicit-scale blockers and final safety evidence. With annotation_layout="compare", the baseline gets two and the selected candidate three full physical critiques across scale, manifest, and report paths.

    The counted per-state tests pass, but the issue's once-per-state acceptance is still open. The current code has no mutation generation for public drawing state; items, views, and annotations can change directly. A persistent cache would risk stale ADR 5 evidence. A safe next slice must carry an exact state-scoped lint snapshot, including issues and pair aggregation, through the explicit-scale/selection/report consumers and invalidate on mutation. Reusing placement-only lint for scale blockers could change ADR 2's requirement decision, so this audit made no engine change.

  5. pzfreo commented on Sep 29, 2026

    @pzfreo
    OwnerAuthor

    Reopening for #1939 tracking. PR #2048 explicitly covered a partial placement-critique reuse slice and did not satisfy this issue’s once-per-distinct-drawing-state acceptance. The accepted main baseline still has a reproducible duplicate physical critique for an explicit-scale Box (documented in the 2026-09-29 count audit above). Draft PR #2085 is under local parity and paired performance review; it is not merged or counted as complete. Keep this issue open until a counted-call guard proves the acceptance on merged main, exact drawing/lint parity holds, and the measured benchmark gate passes.

  6. reopened this on Sep 29, 2026
  7. pzfreo commented on Sep 29, 2026

    @pzfreo
    OwnerAuthor

    #1939 acceptance audit on local aggregate eba73503 (2026-09-30): keep #1945 open. A direct counted build_drawing(Box(30, 20, 10)) call in default and explicit permissive modes makes Drawing.lint(physical=False) during _PlacementCritique.get, then Drawing.lint(physical=True) on the same unchanged drawing. Compare mode repeats that pair for each of two candidate drawings. The new partial slice counts only physical calls, so it does not prove this issue's literal once-per-state acceptance. The existing duplicate structural traversal was reproduced by execution, not inferred from call sites.

    The safe follow-up is sequenced: first split lint orchestration into an independently reviewable structural result with its _IssueAggregation plus ordered physical completion, without a cache. Then carry the structural result within one build attempt through _PlacementCritique into finished physical lint, with explicit discard on repack, repair, registry/advisory mutation, fallback issues, and post-build hooks. Preserve declared-build recognition laziness and public subclass dispatch. Add a counted structural-traversal guard for default, explicit, compare, declared, edits and invalidation paths; mutation-check both reuse and invalidation, require exact 17-case drawing/lint/summary/decision/trace parity and paired no-regression benchmarks before closure. A one-line reuse of placement issues would lose pair aggregation and could change ADR 5 summaries.

    The reviewed selective-scope cache from draft #2085 has local parity and no measured regression, but remains a partial improvement pending its aggregate PR gates. It must be described as continuing, not closing, #1945.

  8. reopened this on Sep 30, 2026
  9. pzfreo commented on Sep 30, 2026

    @pzfreo
    OwnerAuthor

    2026-09-30 local Sheet-table phase-boundary experiment (not shipped): isolated commit 5dbdb87b at /private/tmp/dw1945-sheet-table-lint reused the existing placement critique before an internal table hook, then discarded its pre-hook entry afterward. It reduced the actual returned-Drawing lint(physical=False) call count from 3 to 2 for a Sheet table with two distinct lint-relevant states, while preserving in-place edit, alternate-return and subclass behavior in focused tests. Two deliberate mutations made the new counted-call guard fail; 40 focused tests and static checks passed, and the representative Sheet SVG/lint/summary/decision signature matched merged main f4aa3214.

    Warm alternating 12-build timing showed Sheet medians of 0.12755/0.12678 s on base versus 0.12535/0.12587 s on the patch; Box medians were 0.15682/0.15668 s on base versus 0.15515/0.15585 s on the patch. Earlier pairs included a patched run about 1.5% slower, so these measurements establish no material regression but no reliable useful speedup. The patch adds 10 net production lines plus 64 test lines and still repeats lint for an unchanged arbitrary _post_build hook (2 calls on 1 state). It stays local and is excluded from the next PR. #1945 remains open under the maintainer's accepted within-build, per-mode criterion.

  10. pzfreo commented on Sep 30, 2026

    @pzfreo
    OwnerAuthor

    Fresh independent audit on merged main b5ba5564 counted actual Drawing.lint calls through the build entry points. Default Box: [physical=False, physical=True] on the returned drawing, one per mode. Declared Sheet without a table: [False]. Declared Sheet with notes(["DEBURR"]) (a table hook): [False, False, False], including one repeated placement call on the same post-table state. An unchanged arbitrary _post_build=lambda d:d hook produced [False, False, False, True], with two repeated placement calls on one state. An edited hook adding a registry issue also made four calls, with one duplicate on its post-edit state. A separate public lint after another registry edit saw the new finding, so freshness remains intact.

    The hook disables _PlacementCritique for the whole build attempt; the pre-hook repair call and later policy gates then each call lint directly. The local 10-net-source-line candidate 5dbdb87b restored the cache before the hook and discarded it afterward. It reduced the Sheet table to two placement calls on two distinct states and preserved output, but an unchanged opaque hook still repeated placement lint. Warm paired timing found no reliable material gain, so that candidate was kept local. A literal at-most-once guarantee for arbitrary unchanged hooks while also detecting in-place edits requires complete lint-relevant mutation tracking or a new explicit callback change contract; a shallow identity check is unsafe. No small solution consistent with the current simplicity and output-parity rules was found. #1945's accepted within-build, per-mode criterion remains unmet for these hook paths.

  11. pzfreo commented on Sep 30, 2026

    @pzfreo
    OwnerAuthor

    2026-09-30 status after #2108: draft PR #2085 was closed without merge. Its selective physical-lint cache had no reliable useful benchmark gain and did not satisfy the literal counted-call acceptance. A fresh independent read-only check on merged main reproduced the no-op versus in-place-edit _post_build ambiguity: both return the same Drawing identity, but reusing pre-hook lint is stale for the edited hook and discarding it repeats lint for the no-op hook. The tested phase-boundary patch remains local because it adds bookkeeping for about 2 ms of noisy savings while still missing the arbitrary-hook case. Existing public edit freshness and ADR 3/5 boundaries remain intact. #1945 stays open; no claimed acceptance or new CI gate.

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:lintLint, critique, reconciliation, suggestionstech-debtInternal maintainability or refactoring work

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions