draftwright 0.3.9__tar.gz → 0.4.1__tar.gz

{draftwright-0.3.9 → draftwright-0.4.1}/CHANGELOG.md

@@ -1,5 +1,252 @@
 # Changelog
 
+## Unreleased
+
+## v0.4.1 — 2026-08-07
+
+**The recognition trust release.** Automatic drawings now fail closed on unsupported inner
+profiles, prove semantic coverage for flats, slots and patterns, and retain the measurement
+identity needed to explain placed, suppressed, dropped and missing definitions. Several real
+STEP case studies also move from clean-looking but incomplete output to complete drawings or
+actionable lint.
+
+### Discouraged (supported)
+
+- **`Sheet.auto_dimensions()` and `Sheet.add_dimension()` now emit
+  `SoftDeprecationWarning`** (#1043). They remain supported with no removal planned; the
+  warning steers declared scripts toward `authored_dimensions()` plus explicit
+  `dimension(feature, parameter_id)` lines, where omission can mean suppression. Automatic
+  `build_drawing(part)` and the `Sheet.from_part(part)` on-ramp remain silent. See
+  `docs/deprecations.md` for filtering and migration guidance.
+
+### Added
+
+- **Finished drawings expose why measurements were omitted and, on covered placement paths,
+  what an annotation measures** (#996/#1002). `Drawing.suppressions()` returns the compiler's
+  omission ledger, `Drawing.measurement_keys(name)` exposes recorded measurement provenance, and
+  `draftwright.audit.diff_builds(before, after)` reports losses, substitutions and candidate
+  suppression explanations. The differential is deliberately a triage aid, not a proof where
+  renderer identity remains incomplete.
+
+- **Physical-completeness lint now follows semantic correspondence for flats, lone slots and
+  slot patterns** (#1018). Coverage is joined through recognition, IR and compiler identities
+  rather than inferred from label text or page geometry, and distinguishes authored
+  suppression, placement drops, missing definitions and unverifiable provenance.
+
+- **Full-span floored open channels are recognised and dimensioned as first-class features**
+  (#917). Automatic and declared drawings state the independent overall extent, one wall and
+  channel width, suppress the derived opposite wall, and report any missing member of that
+  defining chain.
+
+### Fixed
+
+- **Square and near-square parts retain both independent planar extents** (#997). A plain
+  square plate could previously lose both plan dimensions, while parts up to five percent off
+  square could lose one and be silently represented as square. The unsafe suppression rule is
+  removed; explicit square notation remains tracked separately in #918.
+
+- **Machined flats retain their physical stock identity from recognition through placement
+  and completeness lint** (#1013/#1015/#1034/#1036). Flats on separate parallel, coaxial or
+  slanted stock no longer collapse into one definition or borrow an opposite face from another
+  stock region. Independent callouts receive clear-margin candidates, while double-D faces on
+  one stock still form one A/F requirement.
+
+- **Dense callout and step-detail cases keep their complete defining set** (#915). Hole
+  callout batches are reconciled as a queue, detail views fit their actual aspect, step levels
+  retain the supporting-face correspondence needed for truthful crops, and a detail redraws
+  only rungs omitted from its parent view.
+
+- **Pocket leaders start on the physical opening rim** (#916), removing the spurious inner
+  silhouette crossing while preserving the solved label corridor and approved dimensions on
+  X-, Y- and Z-depth pockets.
+
+- **Wedge-mounted raised pads survive recognition** (#909). Lower ledges that touch only in
+  plan no longer make the recogniser discard a valid upper pad; true staircase tiers remain
+  excluded.
+
+- **Annotation-dense detail placement no longer stalls the build** (#1065). Detail views
+  avoid every decomposed annotation shaft, witness, label and item footprint; CTC-02
+  supplies 571 such boxes. The free-rectangle search previously treated that set as tiny
+  and admitted roughly 34 billion candidate rectangles, exhausting the slow tier's
+  ten-minute test budget before export. A compressed-coordinate sweep preserves the same
+  deterministic winning rectangle while completing the real search in seconds.
+
+- **Through double-D bores are recognised and called out as first-class hole profiles**
+  (#1061). Automatic and declared builds preserve the parent-circle diameter, A/F size,
+  orientation and depth, and render one compound `DOUBLE-D ... A/F` bore callout. Physical
+  critique now accepts that supported inner profile while retaining a separate warning for
+  13 evenly spaced common-circle arcs on the unresolved outer boundary; it does not infer a
+  repeating full profile or a gear standard.
+
+- **Unsupported internal profiles no longer pass physical-completeness lint silently**
+  (#1058). Inner loops on principal boundary faces are checked against the current
+  circular-hole, rectangular-opening, true-obround, and proven through-double-D vocabulary.
+  Profiles outside it now produce
+  `unrecognised_defining_geometry` and reduce the lint score instead of allowing an
+  envelope-only drawing to score 1.0.
+
+### Changed
+
+- **Crowded prismatic step dimensions recover into an enlarged detail view by default**
+  (#909). The automatic `build_drawing` / `make_drawing` / CLI paths and generated
+  `Sheet` scripts now preserve the omitted dimensions instead of returning
+  `step_dim_dropped` unless the caller remembered `detail_view=True`. Pass
+  `detail_view=False` to retain the parent-view-only behavior and its lint warning.
+
+## v0.4.0 — 2026-08-02
+
+**The compat-exit release.** Every surface whose documented removal target was 0.4.0 is gone,
+and every deprecation that remains now says when it goes — in the message the caller sees, not
+only in a release note. ADR 0005 §4's rule is that an alias carries a tracking issue *and* a
+removal date, because "a facade with no exit date is a failure mode"; this release is that rule
+being kept rather than restated. `docs/deprecations.md` is the new index, and
+`tests/test_deprecation_dates.py` fails any deprecation that names no removal.
+
+Also lands ADR 0016's declared-dimensioning work (#867): a `dimension(feature, role)` is
+referential — it names a measurement and carries no number — and an authored set means omission
+is suppression, enforced at the compiled-plan boundary rather than by a flag renderers check.
+
+**Read this before upgrading:** two removals break *without a release that warned you*, because
+their deprecation never appeared in a shipped version. See *Removed (breaking)* below and
+`docs/deprecations.md`.
+
+### Removed (breaking)
+
+Compat surfaces whose documented removal target was 0.4.0 (#720, ADR 0005 §4 — every alias
+carries a tracking issue *and* a removal date, or the facade is permanent by accident):
+
+- **The seven `Drawing` compat aliases** — `_named` / `_anno_view` / `_pinned` /
+  `_build_issues`, and `_pattern_callouts` / `_patterned_holes` / `_dropped_callout_diams`.
+  These were private, and the public reads have existed since #699: use `dwg.registry`
+  (`in reg`, `names()`, `issues`, `pinned_names()`) and `dwg.coverage`, or the `Drawing` verbs
+  `annotations()` / `iter_annotations()` / `get_annotation()` / `view_of()`.
+  **Note the asymmetry.** A *read* — `dwg._named` — now raises `AttributeError`. A *write* —
+  `dwg._pinned = {...}` — does **not**: these were properties with setters, and `Drawing` has
+  no `__slots__`, so assignment now quietly creates an unrelated instance attribute that no
+  longer reaches the registry or coverage owner. Writes therefore fail silently rather than
+  loudly. Grep for `\._(named|anno_view|pinned|build_issues|pattern_callouts|patterned_holes|dropped_callout_diams)\b`
+  before upgrading; mutate through `registry.add()` / `pin()` / `record_issue()` /
+  `restore_issues()` and the `CoverageState` methods instead.
+- **The `draftwright.sheet_dsl` module** — an import alias for `draftwright.sheet` since the
+  #640 rename. Import `Sheet` from `draftwright` or `draftwright.sheet`.
+- **`generate_script`**, including its `draftwright.__all__` entry. It has raised since #940
+  retired the imperative emitter; it is now simply absent, so the failure is an `ImportError`
+  at the top of a script rather than a `RuntimeError` part-way through one. Use
+  `--script` / `emit_sheet_script`.
+- **The bespoke `--style imperative` error message.** `--style` itself is unchanged and still
+  accepts its sole value `sheet`; `imperative` is now an unrecognised value like any typo,
+  rather than one carrying its own explanation of the #940 retirement.
+
+- **Bare dimension-role spellings** — `sheet.dimension(f, "width")`. Use the parameter id,
+  `"width.length"`; `dimension_ids()` on a handle lists the valid ones. The bare role is the
+  *family* spelling: it selects every parameter carrying it, which is how
+  `dimension(step, "step")` quietly declared two measurements. In an authored set, where
+  omission means suppression, silently declaring an extra one is the mirror image of the rule
+  — so it now raises rather than resolving. (A *discriminated* bare role, used with `axis=`,
+  is unaffected: that is how variants like `grid_pitch.length.row` are addressed, and it never
+  warned.)
+- **The `Sheet.dimension(kind=…, value=…)` call shape** — use `Sheet.measured_dimension(...)`.
+  `dimension` is now solely the ADR 0016 referential verb: it names a feature and a parameter
+  id and reads the value off the geometry.
+
+Those last two break **without a release that warns you**. They were deprecated after v0.3.9
+and removed in 0.4.0, so the `DeprecationWarning` never appeared in a released version —
+upgrading from v0.3.9 or earlier goes straight from working to a raise. That is deliberate
+(ADR 0016); this entry and `docs/deprecations.md` are the only notice you get, so both
+failures name their replacement rather than raising about argument counts.
+
+### Deprecated
+
+- **The legacy `Drawing.export` shapes now emit `DeprecationWarning`** (#987) — they were
+  announced as deprecated in v0.3.1 and then said nothing at runtime for four minor releases,
+  which would have made their 0.5.0 removal a silent break. Three cases warn:
+  - `export()` with `formats=` **omitted or `None`** — the legacy default, which writes
+    SVG + DXF and returns an `(svg, dxf)` **tuple** rather than the `{format: path}` dict.
+  - the **`svg=` / `dxf=` booleans**. The suggested replacement names the formats *that call*
+    selected, so following it cannot change what gets written.
+  - passing a boolean **alongside** `formats=`, where it is silently ignored — `formats` wins,
+    and now says so.
+
+  **If you promote `DeprecationWarning` to an error, previously-passing exports will now
+  raise.** Migration: `export(out, formats=("svg", "dxf"))` and read the dict. `make_drawing`
+  is unaffected — it returns the same tuple and does not warn.
+
+### Added
+
+- **`sheet.add_dimension(feature, role)` — ask the planner to carry one more
+  measurement** (ADR 0016 / #872). Referential: it names a feature and a role and
+  carries **no number**, so the value still comes from the geometry and a size lives in
+  exactly one place. It changes *selection*, not derivation — a request can never
+  introduce a number the part does not have. Requesting something the planner already
+  emits is a deliberate no-op, so a script can ask without first knowing the rule set's
+  mind. `sheet.auto_dimensions()` states the source explicitly (optional in this
+  release; #874 makes it mandatory).
+- **Suppressing a dimension marks it; it no longer leaks into the callout** (ADR 0016 /
+  #875). `PlannedDimension.suppressed` was honoured at thirteen render sites but not by
+  the compound hole-callout path, so a suppressed counterbore still printed. The group
+  keeps its engineering data either way — what changes is whether a value reaches the
+  page. Suppressing the bore ⌀ while a counterbore, spotface or countersink segment
+  remains now **raises** and names the orphan: `⌀20 THRU ⌴ ⌀32 ↓ 1.5` has no reading with
+  its leading term removed, and silently dropping the segments would discard authored
+  intent while silently restoring the head would make the drawing say something the
+  script does not.
+- **Addressable dimension identity** (#869/#870/#871): every planned measurement now has
+  a stable `DimensionId(feature, parameter)`, and correlated measurements that must be
+  named as one — a grid pattern's row and column pitch, a step ladder — group into an
+  `AddressableDimension`. This is what a `dimension(...)` line will name, and what
+  suppression and provenance key on.
+
+### Changed
+
+- **`Sheet.dimension(kind=…, value=…)` is now `Sheet.measured_dimension(...)`**
+  (ADR 0016 / #873), and `model.declare.authored_dimension` is
+  `model.declare.measured_dimension` to match. This **reserves** the name `dimension` for
+  the referential verb ADR 0016 defines — name a feature and a role, carry no number, let
+  the engine read the value off the geometry — which `Drawing.dimension` already is and
+  `Sheet.dimension` will become. The verb that carries an explicit number needed a name
+  saying so first. The old spelling was a transitional overload during development and is
+  **removed in this same release** (#720) rather than shipping — `Sheet.dimension` is solely
+  the referential verb, and the old keyword call raises with `measured_dimension` named. See
+  *Removed (breaking)* above. Generated AP242 scripts emit `measured_dimension` and so arrive
+  un-deprecated.
+- **`Sheet` handles address features by identity, not position** (#908/#910/#912). A
+  handle, tolerance, GD&T origin, section request or dimension intent now follows *its*
+  feature through a `features` reorder instead of naming whatever took the slot.
+  Reordering with `reverse()`/`sort()` preserves every reference; deleting or replacing
+  a referenced feature raises rather than silently retargeting a neighbour. `of()` now
+  accepts a handle, and negative indices resolve uniformly across `of()`,
+  `add_dimension()` and the GD&T verbs.
+
+### Fixed
+
+- **`sheet.envelope()` measured the file, not the part** (#977). An AP242 STEP import is a
+  compound of the solid *plus its PMI presentation geometry* — annotation planes, leader
+  curves — and the declared verb measured all of it. On the NIST CTC-01 fixture it declared
+  1170 × 650 where the part is 800 × 450: an envelope 370 mm too wide, silently, in anything
+  declared by hand. `step_level()` had the same exposure, offsetting every step position by
+  the annotation overhang. Both now measure the solid body, sharing the helper the engine
+  already used for exactly this (`_analyse` and `Sheet.model`).
+- **A declared envelope's frame origin sat a half-height below a detected one** (#977). It
+  used `bbox_min.Z` where the detector uses the bbox centre. **Dimension output is unchanged** —
+  envelope sizes derive from `bbox_min`/`bbox_max`, and the overall height is compiled from the
+  model bbox — but `frame.origin` is the generic feature *site*, so **a GD&T control frame,
+  surface finish or note targeting a hand-declared `sheet.envelope()` was anchored at the
+  bottom face rather than the centre, and its leader now moves to the centre**. That is a
+  visible change on drawings carrying such an annotation; drawings without one are unaffected.
+  Scripts generated by `--script` were never affected either way: they bake the detected frame
+  explicitly rather than calling the verb.
+
+
+- **Front-view dimensions join the placement solve instead of committing to the strip**
+  (#894): they previously took strip space before the global solve ran, so a
+  higher-ranked dimension could find its space already gone. Priority only ranks
+  candidates that are *in* the solve.
+- **A hole callout reads the feature's own `through` fact** (#868) rather than inferring
+  it from whether a depth parameter happens to be present — so a suppressed depth can no
+  longer make a blind hole print `THRU`.
+- **The balloon ring clears the view it annotates after a hole-table escalation**
+  (#901/#903).
+
 ## v0.3.9 — 2026-07-26
 
 ### Added

{draftwright-0.3.9 → draftwright-0.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: draftwright
-Version: 0.3.9
+Version: 0.4.1
 Summary: Automated technical-drawing generation for build123d
 Project-URL: Homepage, https://github.com/pzfreo/draftwright
 Project-URL: Repository, https://github.com/pzfreo/draftwright
@@ -771,9 +771,12 @@ from draftwright import build_drawing
 
 dwg = build_drawing(part, title="Mounting Plate")
 issues = dwg.lint()                       # list[LintIssue] — coverage, page bounds, ISO
-svg_path, dxf_path = dwg.export("my_part")
+paths = dwg.export("my_part", formats=("svg", "dxf"))   # {"svg": ..., "dxf": ...}
 ```
 
+`export()` with no `formats=` returns the old `(svg, dxf)` tuple; that shape is deprecated
+and removed in 0.5.0 (see [docs/deprecations.md](docs/deprecations.md)).
+
 ### Declarative drawings — reference features, declare intent
 
 Instead of relying on detection, **reference the build123d objects you built** and declare
@@ -789,10 +792,16 @@ plate = Box(120, 80, 20)
 bore = Pos(0, 0, 0) * Cylinder(4, 20)
 
 sheet = Sheet(plate - bore, title="Plate", number="DWG-002")
-sheet.envelope()
+env = sheet.envelope()
 sheet.datum("A", plate.faces().sort_by()[-1])             # datum A on the top face
 hole = sheet.hole(bore).finish("1.6").note("M3x0.5 TAP")  # ⌀8 bore, Ra 1.6, tapped
 sheet.control(hole).position(0.1, to="A", diameter=True)  # ⌀0.1 position wrt A
+
+sheet.authored_dimensions()                               # THIS is the complete set
+sheet.dimension(env, "width.length")                      # (ADR 0016: a build says where
+sheet.dimension(env, "height.length")                     #  its dimensions come from, and
+sheet.dimension(hole, "bore.diameter")                    #  omitting one means suppress it)
+
 sheet.export("plate")                                     # writes plate.pdf
 ```
 
@@ -834,6 +843,20 @@ sheet.hole(features.m3_bore).thread("M3x0.5").finish("1.6")   # tapped + Ra on t
 An object-sourced script carries an inline tip pointing at exactly this edit; a STEP-sourced
 script keeps the detected numbers (there's no object to reference).
 
+Every generated script ends by naming the drawing it built, so you can critique or inspect it
+before (or instead of) exporting — one build, not two:
+
+```python
+drawing = sheet.build()
+
+for issue in drawing.lint():                  # ISO/coverage critique of THIS drawing
+    print(issue.severity, issue.code, issue.message)
+
+drawing.export("part", formats=("pdf",))
+```
+
+`sheet.export(...)` remains the one-liner for handwritten scripts that just want the file.
+
 See [`docs/multi-feature-object-reference-workflow.md`](docs/multi-feature-object-reference-workflow.md)
 for a complete, runnable walkthrough of this pattern on a multi-feature turned part —
 including the backward-compatible refactor, external threads (no `.thread()` on a step —

{draftwright-0.3.9 → draftwright-0.4.1}/README.md

@@ -75,9 +75,12 @@ from draftwright import build_drawing
 
 dwg = build_drawing(part, title="Mounting Plate")
 issues = dwg.lint()                       # list[LintIssue] — coverage, page bounds, ISO
-svg_path, dxf_path = dwg.export("my_part")
+paths = dwg.export("my_part", formats=("svg", "dxf"))   # {"svg": ..., "dxf": ...}
 ```
 
+`export()` with no `formats=` returns the old `(svg, dxf)` tuple; that shape is deprecated
+and removed in 0.5.0 (see [docs/deprecations.md](docs/deprecations.md)).
+
 ### Declarative drawings — reference features, declare intent
 
 Instead of relying on detection, **reference the build123d objects you built** and declare
@@ -93,10 +96,16 @@ plate = Box(120, 80, 20)
 bore = Pos(0, 0, 0) * Cylinder(4, 20)
 
 sheet = Sheet(plate - bore, title="Plate", number="DWG-002")
-sheet.envelope()
+env = sheet.envelope()
 sheet.datum("A", plate.faces().sort_by()[-1])             # datum A on the top face
 hole = sheet.hole(bore).finish("1.6").note("M3x0.5 TAP")  # ⌀8 bore, Ra 1.6, tapped
 sheet.control(hole).position(0.1, to="A", diameter=True)  # ⌀0.1 position wrt A
+
+sheet.authored_dimensions()                               # THIS is the complete set
+sheet.dimension(env, "width.length")                      # (ADR 0016: a build says where
+sheet.dimension(env, "height.length")                     #  its dimensions come from, and
+sheet.dimension(hole, "bore.diameter")                    #  omitting one means suppress it)
+
 sheet.export("plate")                                     # writes plate.pdf
 ```
 
@@ -138,6 +147,20 @@ sheet.hole(features.m3_bore).thread("M3x0.5").finish("1.6")   # tapped + Ra on t
 An object-sourced script carries an inline tip pointing at exactly this edit; a STEP-sourced
 script keeps the detected numbers (there's no object to reference).
 
+Every generated script ends by naming the drawing it built, so you can critique or inspect it
+before (or instead of) exporting — one build, not two:
+
+```python
+drawing = sheet.build()
+
+for issue in drawing.lint():                  # ISO/coverage critique of THIS drawing
+    print(issue.severity, issue.code, issue.message)
+
+drawing.export("part", formats=("pdf",))
+```
+
+`sheet.export(...)` remains the one-liner for handwritten scripts that just want the file.
+
 See [`docs/multi-feature-object-reference-workflow.md`](docs/multi-feature-object-reference-workflow.md)
 for a complete, runnable walkthrough of this pattern on a multi-feature turned part —
 including the backward-compatible refactor, external threads (no `.thread()` on a step —

{draftwright-0.3.9 → draftwright-0.4.1}/docs/adr/README.md

@@ -32,6 +32,8 @@ architecture** table; open retired or superseded records only for design history
 | [0013](0013-uniform-recognition-and-shared-package.md) | A uniform recogniser/feature contract (with `b123d-recognisers` as its deferred shared deployment) | Enforce a uniform geometry-only recogniser contract internally; defer package extraction until there is a second consumer. | Accepted; Phase 1 in progress; extraction deferred | `test_recogniser_contract.py`, `test_import_boundaries.py` |
 | [0014](0014-collect-then-solve-annotation-placement.md) | Collect-then-solve annotation placement (as built) | Collect, select, assign, and deterministically solve annotations per corridor before rendering. | Accepted; supersedes 0009 | `test_carve_free_position_callers.py`, `test_strip_layout.py`, `test_layout_property.py`, `test_import_boundaries.py` |
 | [0015](0015-part-drawing-compiler-as-built.md) | The part-drawing compiler, as built | Use one detected-or-declared feature IR and planner-fed dimension groups as the compiler waist. | Accepted; supersedes 0008 | `test_part_model.py`, `test_detect_once.py`, `test_import_boundaries.py` |
+| [0016](0016-declared-dimensioning-intent.md) | Declared dimensioning intent: capture what to measure, let the engine place it | Declare which measurements matter as scale-independent intent routed through the planner and corridor solve; never hardcode dimension geometry. | Accepted; epic #867 complete; phase 6 landed (#940) | `test_compiled_plan_boundary.py`, `test_label_provenance.py`, `test_sheet_emit.py`, `test_add_dimension.py` |
+| [0017](0017-recognition-inventory-correspondence-and-measurement-provenance.md) | One recognition result per run; correspondence is evidence-gated | Produce one explicit recognition result owned by `BuildState`; require vertical-slice evidence before generalising correspondence, identity, requirements, outcomes, or reconciliation. | Accepted; ownership phase landed, extensions gated by #1018 | `test_recognition_manifest.py`, `test_recognition_result.py`, `test_declared_recognition_gate.py` |
 
 ## Historical records
 
@@ -46,6 +48,8 @@ architecture** table; open retired or superseded records only for design history
 - Compiler and state ownership: 0001 → 0005 → 0015.
 - Recognition and public declaration: 0007 → 0013 → 0011 → 0015.
 - Layout and placement: 0004 → 0014 → 0012.
+- Declared intent and the editable surface: 0001 → 0011 → 0012 → 0016.
 - Quality and correction: 0002, with provenance from 0010.
+- Recognition correspondence and completeness: 0007 → 0013 → 0015 → 0017.
 
 Tracking issue: #745.

{draftwright-0.3.9 → draftwright-0.4.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "draftwright"
-version = "0.3.9"
+version = "0.4.1"
 description = "Automated technical-drawing generation for build123d"
 readme = "README.md"
 license = { file = "LICENSE" }
@@ -80,6 +80,18 @@ markers = [
     "slow: heavy end-to-end CTC fixture builds (deselected by default)",
     "smoke: curated build-light subset for a fast local check (~30 s)",
 ]
+# `SoftDeprecationWarning` marks a surface that is discouraged but SUPPORTED and not going
+# away (#1043). The suite exercises `Sheet.auto_dimensions()` in ~170 places, deliberately —
+# it is still a supported path and its behaviour must keep being tested. Migrating those to
+# authored dimensions would be churn that tests less, so the category is silenced here rather
+# than at ~170 call sites.
+#
+# This does NOT weaken the guard: `tests/test_soft_deprecation.py` asserts the warning with
+# `pytest.warns`, which fires regardless of this filter. Real `DeprecationWarning`s are
+# untouched and still carry removal dates (`tests/test_deprecation_dates.py`).
+filterwarnings = [
+    "ignore::draftwright.SoftDeprecationWarning",
+]
 # Coverage is a CI concern (it adds ~13% locally and instruments every line); the
 # CI workflow passes the --cov flags explicitly. Keep the local default lean.
 addopts = "--tb=short -m 'not slow'"
@@ -87,6 +99,9 @@ addopts = "--tb=short -m 'not slow'"
 [tool.coverage.run]
 source = ["src/draftwright"]
 omit = ["src/draftwright/__init__.py"]
+# Keep XML paths anchored at the repository root so local diff coverage and Codecov
+# measure the same changed source lines rather than relying on runner-specific paths.
+relative_files = true
 # Branch coverage makes the regression gate sensitive to untested decision paths,
 # which matter more than raw statement execution in the recognition/layout code.
 branch = true
@@ -94,13 +109,16 @@ branch = true
 [tool.coverage.report]
 # Baseline measured on the full fast tier on Linux/Python 3.13 (#825):
 # 92.05% combined line+branch coverage (93.90% statements, 86.89% branches).
-# Keep two points of cross-platform/kernel headroom; ratchet upward only after the
-# lowest CI matrix result has stayed above the proposed floor.
+# Keep two points of headroom; ratchet upward only after the canonical coverage job
+# has stayed above the proposed floor.
 fail_under = 90
 precision = 1
 exclude_lines = [
     "pragma: no cover",
     "if TYPE_CHECKING:",
+    # `@overload` stubs are typing declarations: Python discards the bodies, so they can
+    # never execute and counting them as missed coverage measures nothing (#963).
+    "@overload",
 ]
 
 [tool.mypy]