draftwright 0.4.6__tar.gz → 0.4.7__tar.gz

{draftwright-0.4.6 → draftwright-0.4.7}/CHANGELOG.md

@@ -1,5 +1,52 @@
 # Changelog
 
+## Unreleased
+
+### Added
+
+- Recogniser co-development now has a one-command, wheel-based two-checkout check; an exact
+  registry-release evidence record; automated dependency PR preparation; and documented landing,
+  compatibility, deprecation, rollback, ownership, and CI-budget rules. Dependency PRs retain the
+  canonical coverage/Codecov gate while avoiding four duplicate platform suites and the slow tier
+  (#1170).
+- A versioned, independently authored STEP-analysis corpus and evaluator now report detection
+  recall/false positives, parameter fidelity, and downstream usefulness as separate evidence
+  layers. Hash-pinned positive, negative, ambiguous, compound, and topology-order-variant fixtures,
+  per-layer diagnostics, and an anti-self-validation mutation prevent recogniser output from
+  defining its own denominator (#1169).
+- Draftwright now validates the released `b123d-recognisers` 0.2.0 capability manifest against
+  an exhaustive consumer-owned declaration of IR, DSL, generated-code, drawing, completeness,
+  and documentation states. Unknown families, stale implementations, record-schema drift, and
+  unevidenced state transitions fail closed; intentionally geometry-only repeating-profile
+  evidence remains usable without acquiring invented drafting semantics.
+
+### Changed
+
+- Updated the exact `b123d-recognisers` production lock from 0.2.0 to 0.2.1.
+  The immutable PyPI wheel/sdist hashes and capability-manifest digest
+  `383a196329ed6a3d1bf88f18ae4ff75613c032f35d40f2b53302b6744da4d19e` are
+  recorded in `.github/recogniser-release.json`; focused compatibility evidence and the
+  normal consumer gates run on the generated PR.
+
+### Fixed
+
+- Stable release and TestPyPI snapshot builds now update package metadata and the independently
+  validated Draftwright consumer-contract identity atomically. This prevents stripped `.dev0`
+  and numbered development artifacts from failing their own capability-contract validation.
+- Installed wheels validate every portable recogniser-contract property without requiring the
+  repository-only behavior-test files whose existence remains a strict source/CI gate. This keeps
+  the packaged STEP-analysis evaluator usable without weakening evidence checks in development.
+- Post-release development-version bumps now update the consumer-contract identity on a branch,
+  open a protected PR, and dispatch the narrow maintenance gate instead of attempting a rejected
+  direct push to protected `main` (#1170).
+- Machined-feature leader callouts now collect all clear alternatives within each
+  post-drain pass and use a bounded maximum-cardinality, minimum-leader-length
+  assignment instead of taking corners greedily in feature order (#740). If a
+  deterministic alternative-count, pass-size, candidate-pair, or search budget is
+  reached, placement retains the legacy greedy result or a result no worse than it
+  rather than losing additional callouts. Pre-drain diameter clearance ranking and
+  its Policy-B fallback remain unchanged.
+
 ## v0.4.6 — 2026-08-15
 
 ### Changed

{draftwright-0.4.6 → draftwright-0.4.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: draftwright
-Version: 0.4.6
+Version: 0.4.7
 Summary: Automated technical-drawing generation for build123d
 Project-URL: Homepage, https://github.com/pzfreo/draftwright
 Project-URL: Repository, https://github.com/pzfreo/draftwright
@@ -684,7 +684,7 @@ Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Scientific/Engineering
 Requires-Python: <3.15,>=3.10
 Requires-Dist: antlr4-python3-runtime<4.10
-Requires-Dist: b123d-recognisers==0.1.0
+Requires-Dist: b123d-recognisers==0.2.1
 Requires-Dist: build123d-drafting-helpers>=0.14.1
 Requires-Dist: build123d<0.11,>=0.9.0; python_full_version < '3.13'
 Requires-Dist: build123d<0.12,>=0.11; python_full_version >= '3.13'

{draftwright-0.4.6 → draftwright-0.4.7}/docs/adr/README.md

@@ -30,7 +30,7 @@ architecture** table; open retired or superseded records only for design history
 | [0011](0011-ir-as-public-input.md) | The IR as a public input: declare features, don't only detect them | Accept the feature IR as public input through declarations and the `Sheet` façade. | Accepted; core landed; #62/#462/#495 remain | `test_declare.py`, `test_object_aspects.py`, `test_sheet_gdt.py` |
 | [0012](0012-edits-as-pinned-priority-candidates-in-the-global-solve.md) | User annotation edits are pinned, priority-ranked corridor candidates | Drain recorded semantic edits through corridor placement with pin and priority. | Accepted; partially landed; full recomposition/parity remains #426/#707 (#661 detail views landed) | `test_make_drawing.py`, `test_sheet_emit.py` |
 | [0013](0013-uniform-recognition-and-shared-package.md) | A uniform recogniser/feature contract and shared `b123d-recognisers` deployment | Enforce the geometry-only contract in the shared package and consume it through Draftwright's record→IR boundary. | Accepted; Phases 1–2 deployed | `test_external_recognition_boundary.py`, `test_detect_registry.py`, package semantic goldens |
-| [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` |
+| [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; post-drain feature leaders also assign jointly within each pass. | Accepted; supersedes 0009; #740 Amendment 1 | `test_carve_free_position_callers.py`, `test_strip_layout.py`, `test_layout_property.py`, `test_issue_740_leader_assignment.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 external immutable recognition result held by Draftwright's per-run cache; require vertical-slice evidence before generalising correspondence, identity, requirements, outcomes, or reconciliation. | Accepted; external cache ownership clarified, extensions gated by #1018 | `test_external_recognition_boundary.py`, `test_recognition_manifest.py`, `test_declared_recognition_gate.py` |

draftwright-0.4.7/docs/reference/recogniser-capabilities.md

@@ -0,0 +1,52 @@
+# Recogniser capability contract
+
+Draftwright consumes the public capability manifest installed with `b123d-recognisers`; it never
+reads a sibling checkout or a package-private file. The matching Draftwright-owned declaration is
+implemented in `draftwright.recogniser_contract` and validated in CI.
+
+The package manifest describes geometry evidence. Draftwright separately declares, for every
+package family, its IR adapter, fluent `Sheet` surface, generated-Sheet behavior, drawing consumer,
+completeness treatment, and documentation. A stage is either `supported`, `deferred`,
+`not-applicable`, or `unsupported`, with the evidence required by that state. This separation lets
+other CAD consumers apply different policy without making Draftwright policy part of the geometry
+library.
+
+## What failures mean
+
+Validation fails closed and names the family and boundary whenever possible:
+
+- **family inventory mismatch** — the installed package added, removed, or renamed a family.
+  Update the package pin deliberately, add or remove the Draftwright declaration, and provide the
+  downstream behavior or an explicit non-supported state.
+- **record schema mismatch** — a consumed record schema changed. Review the record fields and
+  compatibility notes, update the relevant adapter and tests, then pin the accepted schema version.
+- **stale implementation** — a declared adapter, `Sheet` method, emitter, renderer, or completeness
+  function no longer resolves. Repair the implementation reference and its independent behavior
+  evidence; do not merely rename the string.
+- **evidence is missing** — a supported claim points at a deleted test or document. Restore or
+  replace the behavior evidence before changing the path.
+- **unknown state or unsupported format** — the installed contract uses semantics this Draftwright
+  version does not understand. Upgrade the validator before accepting the package version.
+- **geometry-only family invents semantics** — geometry used for critique was incorrectly given an
+  inferred IR/DSL/code-generation/drawing path. Keep it geometry-only unless a separately reviewed
+  Draftwright feature introduces authored semantics and compatibility evidence.
+- **reserved family claims supported downstream semantics** — a family-level `deferred` or
+  `unsupported` disposition still advertises an implemented downstream stage. Either make the
+  family disposition supported with behavior evidence, or defer/disable every semantic stage and
+  retain its tracking issue.
+- **state transition lacks evidence** — a capability was strengthened or weakened without a named
+  Draftwright version, release notes, and compatibility tests. Supply all three as one reviewed
+  transition.
+
+## Adding or changing a recogniser
+
+Land the package record, independent geometry evidence, manifest update, and compatible package
+release first. Then update Draftwright against that immutable release. For each applicable stage,
+add the adapter, declaration, emitted-Sheet round trip, drawing behavior, and completeness evidence;
+for an inapplicable or deferred stage, state why and link its tracking issue. The contract test
+derives package record outputs, converter registries, live `Sheet` methods, and emitter branches
+independently, so copying a new name into the declaration alone cannot make CI pass.
+
+`bosses` is the fully consumed reference family. `repeating-radial-profiles` is the opposite
+reference: it remains geometry-only critique evidence for a separately authored gear declaration,
+with no inferred gear feature added to fill the table.

draftwright-0.4.7/docs/reference/sheet.md

@@ -0,0 +1,35 @@
+# Sheet and fluent handles
+
+`Sheet` is the declared authoring façade. Feature verbs return fluent handles; those handles
+are documented here because they are part of normal use even though their Python names begin
+with an underscore.
+
+## Sheet
+
+::: draftwright.sheet.Sheet
+    options:
+      filters: public
+
+## Hole handle
+
+::: draftwright.sheet._Hole
+    options:
+      filters: public
+
+## Diameter and step handle
+
+::: draftwright.sheet._Dim
+    options:
+      filters: public
+
+## Multi-parameter handle
+
+::: draftwright.sheet._Params
+    options:
+      filters: public
+
+## GD&T control builder
+
+::: draftwright.sheet._Control
+    options:
+      filters: public

draftwright-0.4.7/docs/research/1062-repeating-radial-profile-evidence.md

@@ -0,0 +1,102 @@
+# Repeating Radial Profile Evidence (#1062)
+
+> **Status:** productionised by #1087, 2026-08-09. The executable mutations remain in
+> `tests/test_issue_1058_wheel_profile.py`; the reusable evidence is owned by
+> `recognition/repeating_profiles.py`. No automatic gear semantics are approved by this note.
+
+## Decision
+
+The wheel fixture proves a **closed 13-fold repeating radial outer profile** about its Z
+axis. It does not prove that the profile is a gear, nor does it establish module, pressure
+angle, helix angle, backlash, tooth thickness, quality grade, or manufacturing process.
+
+Keep `unrecognised_defining_geometry` for this part. Do not add an automatic `GearFeature`,
+emit a gear callout, or treat outside/root diameters and repeat count as a complete
+manufacturing definition. The useful next boundary is:
+
+1. reusable geometry-only correspondence for a repeating radial profile; and
+2. a separately designed, explicit declaration of gear requirements and their drawing
+   presentation.
+
+The second may consume the first to check that declared tooth count and axis correspond to
+the solid. Recognition must not manufacture the declaration.
+
+## Pinned Evidence
+
+| Item | Observed fact |
+|---|---|
+| Fixture | `tests/fixtures/issue_1058_wheel_rh.step` |
+| SHA-256 | `4911c06426f0ceeedc198416e058aabc1c1a6a65e9e766eca7efed5484a27cda` |
+| STEP form | AP214, one solid, generic product name `SOLID` |
+| Overall bounds | X -3.8000001..3.7733322; Y -3.8000001..3.8000001; Z -3.8500001..3.8500001 mm |
+| Principal outer boundaries | two, at the opposed Z limits |
+| Boundary topology | one closed 52-edge outer wire on each end face |
+| Edge inventory | 13 circular edges and 39 B-splines |
+| Circular edges | radius 3.8 mm, common XY centre (0, 0) |
+| Rotational correspondence | four complete 13-edge orbits under `2*pi/13` rotation |
+| Orbit roles | one circular-tip orbit and three B-spline orbits |
+
+Both end faces prove the same correspondence despite different edge start and traversal.
+The STEP header and entities contain no gear name, PMI, standard, or parameter metadata.
+
+## What The Proof Establishes
+
+The test samples every curve in each outer wire, then requires a one-to-one mapping of every
+curve under one sector rotation. Curve type, length, and sampled geometry must agree within
+the fixed tolerance. The mapping must be bijective, each orbit must contain exactly 13
+curves, and every endpoint must belong to one connected degree-two cycle.
+
+This is stronger than the existing lint hint. `_radial_outer_arc_count` reports 13 equal,
+equally spaced arcs on a common circle, but explicitly does not claim that the 39 intervening
+B-splines repeat. The complete-wire proof closes that geometric gap without widening the
+semantic claim.
+
+The following mutations fail:
+
+- retaining only the 13 common-circle arcs;
+- altering one intervening B-spline sample while leaving all arcs unchanged;
+- breaking one endpoint so the outer wire is open;
+- changing one sector boundary while preserving a closed cycle; and
+- relying on the wire's original start edge or traversal direction.
+
+The changed-intervening-curve mutation is the decisive guard: an arc-count implementation
+would still pass it.
+
+## Why This Is Not Gear Recognition
+
+Many manufactured profiles can be cyclic without being gears. Even if a human recognises
+the fixture's purpose, the B-rep alone does not uniquely identify the generating standard or
+the requirements needed to reproduce and inspect it. Fitting a plausible standard from 13
+tips and a diameter would turn a guess into normative drawing output.
+
+A truthful technical drawing therefore needs explicit requirements supplied by the author,
+usually including at least the gear system/type, tooth count, module or diametral pitch,
+pressure angle, reference geometry, and the applicable accuracy or inspection requirement.
+The exact public surface and table/callout form need a standards-backed design slice; this
+discovery does not invent them.
+
+## ADR Fit
+
+- **ADR 0013:** the proven repeat is lower-tier, geometry-only evidence. `gear` is an
+  application semantic and must not be smuggled into the recognition record.
+- **ADR 0015:** any future automatic record must enter through the compiler's existing
+  recognition waist. A declared gear requirement belongs on the declared path.
+- **ADR 0017:** if productionised, one orchestration owns the correspondence evidence and
+  consumers project from it. The mutation precedes trust in the guard, and a new identity
+  scheme is not justified by this single case.
+- **ADR 0011:** explicit author intent is the appropriate source for requirements that the
+  B-rep cannot establish.
+
+No ADR amendment is required. No placement decision is made, so ADR 0014 is unaffected.
+
+## Follow-up Slices
+
+1. **Productionised in #1087.** The pure full-wire correspondence is owned by the one
+   recognition orchestration and consumed by physical critique for declared-profile
+   correspondence. It does not clear completeness merely because the repeat exists.
+2. **Design declared gear requirements.** Start from the applicable drawing/gear standards
+   and define the minimum honest declaration, validation, IR, and table/callout output. Include
+   a mismatch diagnostic when declared count or axis disagrees with geometric evidence.
+3. **Only then assess automatic assistance.** Recognition may prefill proven geometric facts
+   such as axis and repeat count for user confirmation. It may not infer the normative gear
+   specification.

{draftwright-0.4.6 → draftwright-0.4.7}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "draftwright"
-version = "0.4.6"
+version = "0.4.7"
 description = "Automated technical-drawing generation for build123d"
 readme = "README.md"
 license = { file = "LICENSE" }
@@ -18,7 +18,7 @@ dependencies = [
     "build123d>=0.9.0,<0.11 ; python_full_version < '3.13'",
     "build123d>=0.11,<0.12 ; python_full_version >= '3.13'",
     "build123d-drafting-helpers>=0.14.1",
-    "b123d-recognisers==0.1.0",
+    "b123d-recognisers==0.2.1",
     "numpy>=1.24",
     # PNG raster export (SVG→PDF→PNG). Both permissively licensed (Pillow HPND; pypdfium2
     # Apache-2.0 wrapping Google PDFium BSD-3) and ship pre-built wheels with NO native system
@@ -69,6 +69,9 @@ include = [
     "src/draftwright",
     "tests",
     "skills",
+    "docs/reference/recogniser-capabilities.md",
+    "docs/reference/sheet.md",
+    "docs/research/1062-repeating-radial-profile-evidence.md",
     "README.md",
     "LICENSE",
     "CHANGELOG.md",

{draftwright-0.4.6 → draftwright-0.4.7}/src/draftwright/analysis.py

@@ -630,7 +630,7 @@ def _analyse(
         # by #1025). Both callers deriving this separately let lint project over a different
         # ladder than the model was sized from — which is exactly the divergence one waist is
         # supposed to prevent.
-        step_zs = recognition.step_ladder(bb)
+        step_zs = recognition.step_ladder_for_z_span(bb.min.Z, bb.max.Z)
     # The aggregate owns the shared substrate from here on.  Rebind the local projection so
     # model construction, Analysis and the finished BuildState all consume the same inventory
     # object rather than parallel list/tuple wrappers that merely happen to contain equal data.

{draftwright-0.4.6 → draftwright-0.4.7}/src/draftwright/annotations/_common.py

@@ -970,6 +970,19 @@ def occupancy_boxes(o, stroke_pad=None):
 _STROKE_PAD = 1.2
 
 
+def annotation_obstacle_boxes(dwg, annotation):
+    """One annotation's obstacle boxes under the shared strip-occupancy policy.
+
+    Candidate-based placers use this before an annotation is registered; factoring
+    the preset-aware stroke pad here keeps those candidate conflicts identical to
+    the boxes :func:`strip_obstacles` will expose after placement (#740).
+    """
+
+    arrow_length = getattr(getattr(dwg, "draft", None), "arrow_length", None)
+    pad = max(_STROKE_PAD, arrow_length / 2) if arrow_length else _STROKE_PAD
+    return occupancy_boxes(annotation, stroke_pad=pad)
+
+
 def strip_obstacles(dwg, view=None, *, crossable=(), named=False):
     """The COMPLETE occupancy for strip placement (ADR 0009): every placed
     annotation's full rendered footprint, optionally restricted to *view*, minus
@@ -1005,9 +1018,6 @@ def strip_obstacles(dwg, view=None, *, crossable=(), named=False):
 
     The occupancy source for the collect-then-solve carve — every migrated renderer's
     ``place_strip_candidates`` call wires this in (#321/#150/P3)."""
-    # Preset-aware stroke pad (#688 review): arrowheads scale with font_size.
-    al = getattr(getattr(dwg, "draft", None), "arrow_length", None)
-    pad = max(_STROKE_PAD, al / 2) if al else _STROKE_PAD
     boxes: list = []
     for name, o in dwg.iter_annotations():
         if view is not None:
@@ -1016,7 +1026,7 @@ def strip_obstacles(dwg, view=None, *, crossable=(), named=False):
                 continue  # owned by a different ortho view → its own (disjoint) block
         if type(o).__name__ in crossable:
             continue  # this consumer may cross it (centre lines/marks for a dim)
-        occ = occupancy_boxes(o, stroke_pad=pad)  # decomposed, not one hull (#685)
+        occ = annotation_obstacle_boxes(dwg, o)  # decomposed, not one hull (#685/#740)
         boxes.extend(((name, b) for b in occ) if named else occ)
     return boxes