draftwright 0.3.5__tar.gz → 0.3.6__tar.gz

{draftwright-0.3.5 → draftwright-0.3.6}/CHANGELOG.md

@@ -1,6 +1,49 @@
 # Changelog
 
-## Unreleased
+## v0.3.6 — 2026-07-21
+
+### Fixed
+
+- **`Sheet.step(boss)` on a prismatic part fails loudly instead of silently
+  dropping the height** (#631): declaring a turned `.step()` at a cylinder that is
+  really an external boss set `orientation="z"`, which made `render_height_ladder`
+  suppress the overall-height dim on the assumption the OD/step chain conveyed it —
+  but on a prismatic box that chain never renders, so the height vanished and
+  nothing replaced it (11 → 10 annotations). The build now detects a `StepFeature`
+  coincident with a `BossFeature` (same axis, origin, diameter) — a combination
+  that can never be legitimate — and raises a clear `ValueError` pointing to
+  `.boss()` (which renders its own ø and height per #632). Legitimate turned shafts
+  have steps but no coincident boss, so they are unaffected.
+- **`detail_view=True` no longer a silent no-op when the detail can't be placed**
+  (#630): a part whose lint recommends a detail view (`step_dim_dropped`) but whose
+  crowded band is full-width (e.g. a shelled cover's stacked face levels) can't be
+  enlarged legibly *and* still fit alongside the main views — so `detail_view=True`
+  produced a drawing byte-identical to `False`, silently ignoring the opt-in. It
+  now records a `detail_unplaceable` warning naming the reason and an actionable
+  remedy (dimension manually / move onto its own sheet), so the opt-in is
+  observable. Parts whose detail *does* fit are unchanged.
+- **Imperative `--script` round-trips the title-block fields + sheet furniture**
+  (#775): the imperative flavour reproduced only title/number/tolerance/drawn_by/
+  scale/page, dropping the `material`/`date`/`revision`/`company` fields (#766) and
+  the `frame`/`zones`/`projection` furniture (#767/#768/#769) — so a regenerated
+  imperative script didn't match the direct CLI. They now ride the emitted script's
+  cog config block and its `build_drawing(...)` call (the Sheet flavour already
+  round-tripped them), and the CLI forwards them to `generate_script`.
+
+### Internal
+
+- **Fast-tier dense-sheet canary for the #733/#734 strip-pressure regression**
+  (#737): a synthetic contended-front-strip fixture that drops a step-height
+  principal dim on the pre-#734 commit and stays clean on `main` — closing the
+  fast-tier gap the #733 regression fell through (only the CI-only slow CTC
+  fixtures exercised real strip pressure before).
+- **Layout-hypothesis fuzz tier is now a reproducible PR gate** (#692):
+  `derandomize=True` makes every run generate the same fixed example set (with
+  `print_blob` for paste-able reproduction), so a failure recurs deterministically
+  instead of surfacing on a seed-dependent minority of runs; exploratory fuzzing
+  moves behind `DRAFTWRIGHT_FUZZ_EXPLORE=1`. The two `test_make_drawing.py` xdist
+  observations (#669) were investigated and found non-reproducible — both tests are
+  non-flaky by construction/measurement on current `main`.
 
 ## v0.3.5 — 2026-07-20
 

{draftwright-0.3.5 → draftwright-0.3.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: draftwright
-Version: 0.3.5
+Version: 0.3.6
 Summary: Automated technical-drawing generation for build123d
 Project-URL: Homepage, https://github.com/pzfreo/draftwright
 Project-URL: Repository, https://github.com/pzfreo/draftwright

{draftwright-0.3.5 → draftwright-0.3.6}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "draftwright"
-version = "0.3.5"
+version = "0.3.6"
 description = "Automated technical-drawing generation for build123d"
 readme = "README.md"
 license = { file = "LICENSE" }

{draftwright-0.3.5 → draftwright-0.3.6}/src/draftwright/annotations/sections.py

@@ -597,6 +597,23 @@ def _resolve_details(dwg, a: Analysis, *, ctx) -> None:
                     dwg.pin(hname)
         if placed:
             n_placed += 1
+        elif req.kind == "prismatic-steps":
+            # (#630) The prismatic-steps request is the one queued only under the
+            # build_drawing(detail_view=True) opt-in (_request_prismatic_detail's gate),
+            # so a bail-out here means that opt-in produced nothing. Say so — with an
+            # actionable remedy — rather than returning a drawing byte-identical to
+            # detail_view=False (a full-width crowded band, e.g. a shelled cover's stacked
+            # face levels, can't be enlarged legibly and still fit alongside the main views).
+            # The automatic turned-head requests (queued unconditionally by
+            # render_step_lengths) are NOT opt-in — their bail-out is the normal path (the
+            # main view locates the head/block inline), so they stay silent.
+            ctx.record_issue(
+                "warning",
+                "detail_unplaceable",
+                f"{req.kind} detail view requested but could not be placed legibly on this "
+                "sheet (the crowded band is too wide to enlarge and still fit); dimension the "
+                "feature manually or move it onto its own sheet",
+            )
 
 
 def _overall_height_name(dwg, a: Analysis) -> str | None:

{draftwright-0.3.5 → draftwright-0.3.6}/src/draftwright/builder.py

@@ -287,6 +287,33 @@ def _assemble(
             rot = build_rotational_feature(a)
             if rot is not None:
                 pm = replace(pm, features=[*pm.features, rot])
+        # A z step declares a segment of a z-turned profile; the height ladder then suppresses
+        # the overall height on the premise the step-length chain conveys it (from_model
+        # render_height_ladder). That premise holds only if the declared steps span the part's
+        # FULL z-extent — a boss, or even a stepped boss on a plate, declared via .step()
+        # leaves the bulk unspanned, so suppression silently drops the overall height (#631).
+        # Guard on that exact condition rather than a classifier proxy (is_rotational / prof
+        # both have blind spots): raise when the z-steps don't reach both ends of the part.
+        z_steps = [f for f in pm.features if isinstance(f, StepFeature) and f.frame.axis == "z"]
+        if pm.orientation == "z" and z_steps:
+            tol = 1e-3 * max(a.z_size, 1.0)  # small absolute float epsilon, floored
+            # The step lengths convey the overall height only if the steps TILE the z-extent
+            # contiguously — a single reach to each end isn't enough (an interior gap would
+            # still leave height unconveyed). Walk the spans low→high, extending coverage.
+            spans = sorted(
+                (min(p0[2], p1[2]), max(p0[2], p1[2])) for f in z_steps for (p0, p1) in [f.span]
+            )
+            covered = a.bb.min.Z
+            for lo, hi in spans:
+                if lo <= covered + tol:
+                    covered = max(covered, hi)
+            if spans[0][0] > a.bb.min.Z + tol or covered < a.bb.max.Z - tol:
+                raise ValueError(
+                    "step() declares a segment of a turned profile, but the declared steps "
+                    "don't span this part's full height — it is not a turned (rotational) "
+                    "body. For a boss (an external cylinder on a prismatic part) use .boss() "
+                    "— it renders its own ø and height."
+                )
         # PMI (STEP AP242) is likewise detection-sourced, so a declared / emitted-script model
         # carries none. When PMI annotation is on, synthesise the same imported drafting
         # annotations detection would (render_pmi reads them off the model, gated on a.pmi_mode)
@@ -975,6 +1002,13 @@ def _write_script(
             f"NUMBER = {a.number!r}",
             f"TOLERANCE = {a.tolerance!r}",
             f"DRAWN_BY = {a.drawn_by!r}",
+            f"MATERIAL = {a.material!r}",
+            f"DATE = {a.date!r}",
+            f"REVISION = {a.revision!r}",
+            f"COMPANY = {a.company!r}",
+            f"FRAME = {a.frame!r}",
+            f"ZONES = {a.zones!r}",
+            f"PROJECTION = {a.projection!r}",
             f"PMI = {a.pmi_mode!r}",
             f"SCALE = {scale!r}",
             f"PAGE = {page!r}",
@@ -989,6 +1023,13 @@ def _write_script(
         f"_NUMBER    = {a.number!r}\n"
         f"_TOLERANCE = {a.tolerance!r}\n"
         f"_DRAWN_BY  = {a.drawn_by!r}\n"
+        f"_MATERIAL  = {a.material!r}\n"
+        f"_DATE      = {a.date!r}\n"
+        f"_REVISION  = {a.revision!r}\n"
+        f"_COMPANY   = {a.company!r}\n"
+        f"_FRAME     = {a.frame!r}   # draw a sheet border (#767)\n"
+        f"_ZONES     = {a.zones!r}   # ISO 5457 zone ruler (implies frame, #768)\n"
+        f"_PROJECTION = {a.projection!r}   # 'third' | 'first' | None (#769)\n"
         f"_PMI       = {a.pmi_mode!r}   # 'off' | 'report' | 'annotate'\n"
         f"_SCALE     = {scale!r}   # None = auto; e.g. 5 for 5:1, 0.5 for 1:2\n"
         f"_PAGE      = {page!r}   # None = auto; e.g. 'A3' or (297, 210)\n"
@@ -997,7 +1038,11 @@ def _write_script(
         "    for _k, _v in [\n"
         "        ('STEP_FILE', repr(_STEP_FILE)), ('TITLE', repr(_TITLE)),\n"
         "        ('NUMBER', repr(_NUMBER)), ('TOLERANCE', repr(_TOLERANCE)),\n"
-        "        ('DRAWN_BY', repr(_DRAWN_BY)), ('PMI', repr(_PMI)),\n"
+        "        ('DRAWN_BY', repr(_DRAWN_BY)), ('MATERIAL', repr(_MATERIAL)),\n"
+        "        ('DATE', repr(_DATE)), ('REVISION', repr(_REVISION)),\n"
+        "        ('COMPANY', repr(_COMPANY)), ('FRAME', repr(_FRAME)),\n"
+        "        ('ZONES', repr(_ZONES)), ('PROJECTION', repr(_PROJECTION)),\n"
+        "        ('PMI', repr(_PMI)),\n"
         "        ('SCALE', repr(_SCALE)), ('PAGE', repr(_PAGE)),\n"
         "    ]:\n"
         "        cog.outl(f'{_k} = {_v}')\n"
@@ -1042,6 +1087,13 @@ def _write_script(
         "    number=NUMBER,\n"
         "    tolerance=TOLERANCE,\n"
         "    drawn_by=DRAWN_BY,\n"
+        "    material=MATERIAL,\n"
+        "    date=DATE,\n"
+        "    revision=REVISION,\n"
+        "    company=COMPANY,\n"
+        "    frame=FRAME,\n"
+        "    zones=ZONES,\n"
+        "    projection=PROJECTION,\n"
         "    pmi=PMI,\n"
         "    scale=SCALE,\n"
         "    page=PAGE,\n"
@@ -1103,6 +1155,13 @@ def generate_script(
     pmi: Literal["off", "report", "annotate"] = "off",
     scale: float | None = None,
     page: str | None = None,
+    material: str = "",
+    date: str = "",
+    revision: str = "A",
+    company: str = "",
+    frame: bool = False,
+    zones: bool = False,
+    projection: str | None = None,
     formats: Sequence[str] = ("pdf",),
 ) -> str:
     """Generate an editable Cog-enabled drawing script from a STEP file.
@@ -1131,7 +1190,22 @@ def generate_script(
     # here too would crash generation on an out-of-range value (e.g. --script --scale
     # 0.001 / --page A9) instead of writing the script and deferring — inconsistent with
     # a large unfittable scale, which already defers (review #401).
-    a = _analyse(step_file, title, number, tolerance, drawn_by, out, pmi=pmi)
+    a = _analyse(
+        step_file,
+        title,
+        number,
+        tolerance,
+        drawn_by,
+        out,
+        pmi=pmi,
+        material=material,
+        date=date,
+        revision=revision,
+        company=company,
+        frame=frame,
+        zones=zones,
+        projection=projection,
+    )
     return _write_script(a, scale=scale, page=page, formats=formats)
 
 

{draftwright-0.3.5 → draftwright-0.3.6}/src/draftwright/cli.py

@@ -235,6 +235,13 @@ def main(
                 number=number,
                 tolerance=tolerance,
                 drawn_by=drawn_by,
+                material=material,
+                date=date,
+                revision=revision,
+                company=company,
+                frame=frame,
+                zones=zones,
+                projection=projection or None,
                 pmi=pmi.value,
                 scale=scale,
                 page=page,

draftwright-0.3.6/tests/test_dense_sheet_canary.py

@@ -0,0 +1,99 @@
+"""Fast-tier dense-sheet canary for the #733 strip-pressure regression class (#737).
+
+#733 (the #636 regression, PR #689 "height ladder joins the corridor solve") dropped the
+step-height and overall-height **principal** dimensions on the NIST CTC-02/04 fixtures —
+``placement_unsatisfiable`` **error** lint, *"front-view right strip full"* — and sat on
+``main`` for 12 hours because only the **slow** CTC fixtures exercise real strip pressure,
+and the slow tier runs post-merge only (#153). The PR gate never saw it.
+
+PR #734 fixed it *by construction*: **decoration places after the drain, so principal
+dims win** — on an over-full front-view right strip the height/step chain is placed first
+and the decoration (pocket/fillet dims) is what gets shed, never a principal.
+
+This is the fast-tier tripwire for that guarantee. The synthetic part below double-loads
+the same strip the CTC cases do: a four-step tower stacks a step-height chain + overall
+height on the front-view right strip, and blind pockets milled into the **front face** put
+competing pocket callouts on the same view. Pre-#734 the register-then-drain ordering let
+an immediate pocket callout claim strip room a principal needed, so a step-height dim was
+dropped (``placement_unsatisfiable``); post-#734 the principals drain and place first, so
+every principal survives and the sheet stays free of error-severity lint. Build time is a
+couple of seconds, so it runs on every PR.
+
+It is a genuine regression test, empirically calibrated against the fix, not a smoke test:
+run against the pre-#734 commit ``190e9ba`` (#636/PR #689) this exact part drops a
+step-height dimension — ``placement_unsatisfiable`` "front-view right strip full", the #733
+error — while on ``main`` (post-#734) every principal survives and only pocket decoration
+is shed. So a revert of #734's drain-ordering (or any change that lets decoration outrank a
+principal on a full strip) trips this test on the PR gate instead of post-merge.
+
+Scope (ADR 0014; #735 — test-only, no solve rewrite): the slow CTC pair + golden corpus
+remain the authoritative oracle; this narrows the *fast-tier* gap #733 fell through. The
+build is a pure function of its input (guarded by ``test_layout_cleanliness``) and fonts
+are path-pinned (ADR 0006), so the placed set is deterministic across the CI matrix.
+"""
+
+from __future__ import annotations
+
+import pytest
+from build123d import Box, Pos
+
+from draftwright import build_drawing
+
+_N_POCKETS = 8
+
+
+def _contended_front_strip_part():
+    """A part whose front-view right strip is contended: a step-height chain + overall
+    height (the principals) competing with front-face pocket callouts (decoration).
+
+    The four-step tower stacks the height chain on the front-right strip; the blind pockets
+    milled into the front face (``-Y``) add competing pocket callouts to the same view.
+    Pre-#734 the greedy register-then-drain ordering let a pocket callout claim strip room a
+    principal needed, dropping a step-height dim; post-#734 the principals place first and
+    all survive (#734: principals win by construction)."""
+    part = Box(60, 40, 60)
+    z, w = 60, 50
+    for _ in range(4):  # step tower → the front-right step-height chain
+        part += Pos(0, 0, z + 3) * Box(w, 40, 6)
+        z += 6
+        w -= 9
+    zs = [6 + i * (48 / (_N_POCKETS - 1)) for i in range(_N_POCKETS)]
+    for i, zz in enumerate(zs):  # blind pockets in the front face → competing decoration
+        x = -18 if i % 2 == 0 else 18
+        part -= Pos(x, -20, zz) * Box(9, 10, 4)
+    return part
+
+
+@pytest.mark.timeout(120)
+def test_full_front_strip_sheds_decoration_not_principal_dims():
+    # The #733 canary — the #734 "principals win by construction" guarantee, in the fast
+    # tier. Empirically calibrated: this exact part drops a step-height dim
+    # (placement_unsatisfiable, "front-view right strip full") on the pre-#734 commit
+    # 190e9ba, and is clean here on main.
+    dwg = build_drawing(_contended_front_strip_part())
+    anns = set(dwg.annotations())
+
+    # 1. No error-severity lint — directly catches the #733 `placement_unsatisfiable`
+    #    "front-view right strip full" drop.
+    errors = [(i.code, i.message) for i in dwg.lint() if i.severity == "error"]
+    assert not errors, f"a principal dim was dropped from the full strip (#733 class): {errors}"
+
+    # 2. The principal chain is intact: overall height + the full step-height ladder, all
+    #    on the front view. (The pre-#734 commit drops one of these — see the docstring.)
+    assert "dim_height" in anns, "overall-height dim dropped (front-right strip regression)"
+    steps = sorted(n for n in anns if n.startswith("dim_step_"))
+    assert len(steps) >= 5, f"step-height chain thinned out — expected >=5, got {steps}"
+    assert all(dwg.view_of(n) == "front" for n in ["dim_height", *steps])
+
+    # 3. Non-vacuous: the competing pocket decoration really is present, and on the SAME
+    #    (front) view as the height chain — so guards 1–2 aren't trivially met by a part
+    #    with no strip contention. (The decoration is not itself shed on main; the pre-#734
+    #    ordering is what dropped a principal — see the docstring.) Fails closed: a future
+    #    geometry change that removes the competing load would quietly turn this back into a
+    #    smoke test, and this guard trips instead.
+    pockets = [n for n in anns if n.startswith("m_pocket")]
+    assert pockets, "no competing pocket decoration placed — the front strip is not contended"
+    assert all(dwg.view_of(n) == "front" for n in pockets), (
+        f"pocket decoration landed off the front view — not contending the height chain: "
+        f"{[(n, dwg.view_of(n)) for n in pockets]}"
+    )

{draftwright-0.3.5 → draftwright-0.3.6}/tests/test_layout_hypothesis.py

@@ -15,11 +15,33 @@ from a bounded strategy so shrinking reduces real geometry.
 Budget: each example is one real OCC build (~3-6 s), so the example count is
 deliberately small and the per-example deadline is disabled. This is a bounded CI
 tier, not an exhaustive sweep — the seeded tier remains the determinism gate.
+
+Reproducibility (#692): the tier is ``derandomize=True`` by default, so every run
+generates the *same* fixed 25-example set of input parts rather than a fresh random
+draw. This is the same fixed-seed philosophy as the seeded `test_layout_property.py`
+tier, and it fixes the #692 defect: previously the tier drew random examples with no
+persisted example database, so a failure surfaced on a seed-dependent *minority* of
+runs and never replayed on the next — untrustworthy as a PR gate. Now the search is
+deterministic, so within a build environment a failure recurs on every run; the input
+is also reproducible from the ``@reproduce_failure`` blob ``print_blob=True`` emits
+(the geometry it replays into is a pure function of that input — guarded by
+``test_layout_cleanliness`` — with fonts path-pinned per ADR 0006). Derandomising
+fixes input *generation*, not the OCC build result, so a genuine layout defect may
+still surface on one matrix leg (build123d/OCP versions differ across the Python legs)
+before another — the pre-existing cross-config property the seeded tier shares, not
+new flakiness this introduces.
+
+Genuine exploratory fuzzing — the shrink-and-find value that once surfaced the
+diameter-row shelf-flip bug — is opted into with ``DRAFTWRIGHT_FUZZ_EXPLORE=1 pytest
+tests/test_layout_hypothesis.py`` (``--hypothesis-seed`` does *not* override
+``derandomize``), which draws a fresh random set and can be scheduled as a nightly
+job; pin any failure it minimises as an ``@example`` here.
 """
 
 from __future__ import annotations
 
 import math
+import os
 
 import pytest
 from build123d import Align, Box, Cylinder, Pos, Rotation
@@ -46,10 +68,17 @@ _DEFECTS = {
 
 # Each example is a full build; keep the count small and disable the per-example
 # deadline (OCC builds blow any millisecond budget). too_slow/filter health checks
-# are expected here for the same reason.
+# are expected here for the same reason. `derandomize` + `print_blob` (#692) make the
+# tier a reproducible PR gate: the same fixed example set every run, and any failure
+# prints a paste-able `@reproduce_failure` blob (see the module docstring). Set
+# DRAFTWRIGHT_FUZZ_EXPLORE=1 to draw a fresh random set instead (`--hypothesis-seed`
+# does not override derandomize, so the env var is the exploration opt-in).
+_EXPLORE = os.environ.get("DRAFTWRIGHT_FUZZ_EXPLORE") == "1"
 _LAYOUT_SETTINGS = settings(
     max_examples=25,
     deadline=None,
+    derandomize=not _EXPLORE,
+    print_blob=True,
     suppress_health_check=[HealthCheck.too_slow, HealthCheck.filter_too_much],
 )
 

{draftwright-0.3.5 → draftwright-0.3.6}/tests/test_make_drawing.py

@@ -3671,6 +3671,47 @@ def test_generate_script_preserves_pmi_scale_page(tmp_path):
     assert "pmi=PMI," in content and "scale=SCALE," in content and "page=PAGE," in content
 
 
+def test_generate_script_preserves_title_block_and_furniture(tmp_path):
+    # #775: the imperative script must round-trip the standing title-block fields (#766) and
+    # the sheet furniture (frame #767 / zones #768 / projection #769) — as config fields AND
+    # threaded into the emitted build_drawing() call — so running it reproduces the CLI's
+    # drawing (the sheet flavour already round-trips these; this closes the imperative gap).
+    step = tmp_path / "p.step"
+    export_step(Box(30, 20, 10), str(step))
+    py = generate_script(
+        str(step),
+        out=str(tmp_path / "p"),
+        material="STEEL",
+        date="2026-07-20",
+        revision="B",
+        company="ACME",
+        frame=True,
+        zones=True,
+        projection="third",
+    )
+    content = Path(py).read_text(encoding="utf-8")
+    for cfg in (
+        "MATERIAL = 'STEEL'",
+        "DATE = '2026-07-20'",
+        "REVISION = 'B'",
+        "COMPANY = 'ACME'",
+        "FRAME = True",
+        "ZONES = True",
+        "PROJECTION = 'third'",
+    ):
+        assert cfg in content, cfg
+    for threaded in (
+        "material=MATERIAL,",
+        "date=DATE,",
+        "revision=REVISION,",
+        "company=COMPANY,",
+        "frame=FRAME,",
+        "zones=ZONES,",
+        "projection=PROJECTION,",
+    ):
+        assert threaded in content, threaded
+
+
 def test_generate_script_uses_modern_dict_export(tmp_path):
     # #709: the emitted export is the modern {format: path} dict form (default pdf,
     # matching the CLI / sheet flavour) — never the deprecated legacy tuple path.
@@ -5635,6 +5676,23 @@ class TestDetailView:
         _request_prismatic_detail(None, a, ctx=with_escalation)
         assert len(with_escalation.detail_requests) == 1
 
+    def test_unplaceable_detail_is_reported_not_silently_dropped(self):
+        # #630: on a shelled cover the crowded step band is full-width (stacked face
+        # levels), so a detail can't be enlarged legibly AND still fit — detail_view=True
+        # used to be a silent no-op (output byte-identical to False). It must now SAY SO:
+        # a `detail_unplaceable` warning that False does not carry.
+        cover = (
+            Box(90, 64, 38)
+            - Pos(0, 0, -3) * Box(84, 58, 38)
+            + Pos(0, 0, 24) * Cylinder(14, 10)
+            - Pos(0, 0, 15) * Cylinder(6, 40)
+        )
+        off = build_drawing(cover, title="Cover", detail_view=False)
+        on = build_drawing(cover, title="Cover", detail_view=True)
+        assert off.lint_summary()["by_code"].get("detail_unplaceable", 0) == 0
+        assert on.lint_summary()["by_code"].get("detail_unplaceable", 0) == 1
+        assert "detail_a" not in on.views  # genuinely couldn't place, so no empty box
+
     def test_plain_part_gets_no_detail_view(self):
         dwg = build_drawing(Box(60, 40, 20))
         assert "detail_a" not in dwg.views
@@ -8486,6 +8544,56 @@ class TestPrismaticBossDiameter:
         dwg.remove(height_name)
         assert dwg.lint_summary()["by_code"]["boss_height_missing"] == 1
 
+    def test_issue_631_step_on_boss_raises(self):
+        # #631: reaching for .step(boss) declared a z-turned segment at the boss cylinder,
+        # which flipped the height ladder into turned-suppression and silently dropped the
+        # overall height (net −1 annotation, no height dim). The wrong-verb misuse must fail
+        # loudly instead — .boss() is the verb for a boss. Covers both the lone .step(boss)
+        # and the .boss(boss)+.step(boss) collision (both z-oriented on a prismatic body).
+        from draftwright import Sheet
+
+        boss = Pos(0, 0, 24) * Cylinder(14, 10)
+        part = Box(90, 64, 38) + boss
+        for extra_boss in (False, True):
+            sheet = Sheet(part, title="C")
+            sheet.envelope()
+            if extra_boss:
+                sheet.boss(boss)
+            sheet.step(boss)
+            with pytest.raises(ValueError, match="don't span this part's full height"):
+                sheet.build()
+
+    def test_issue_631_stepped_boss_on_plate_raises(self):
+        # The guard keys on the exact suppression premise (do the steps span the full
+        # height?), not a rotational classifier — so even a stepped boss whose two stacked
+        # cylinders read as a turned PROFILE, sat on a square plate, is caught: the steps
+        # cover only the boss, not the plate below, so the overall height would be dropped.
+        from draftwright import Sheet
+
+        lower = Pos(0, 0, 25) * Cylinder(35, 10)
+        upper = Pos(0, 0, 35) * Cylinder(25, 10)
+        part = Box(100, 100, 20) + lower + upper
+        sheet = Sheet(part, title="C")
+        sheet.envelope()
+        sheet.step(lower)
+        sheet.step(upper)
+        with pytest.raises(ValueError, match="don't span this part's full height"):
+            sheet.build()
+
+    def test_issue_631_interior_gap_between_steps_raises(self):
+        # Coverage is a union tiling, not a reach-to-each-end check: two z-steps that touch
+        # both ends of a z=[0,40] body but leave a 15..25 interior gap do NOT convey the
+        # full height (the gap length is unmeasured), so this must still raise.
+        from draftwright.model.declare import step
+
+        part = Pos(0, 0, 20) * Cylinder(10, 40)  # z-extent [0, 40]
+        model = [
+            step(diameter=20, length=15, at=(0, 0, 7.5), axis="z"),  # z [0, 15]
+            step(diameter=20, length=15, at=(0, 0, 32.5), axis="z"),  # z [25, 40]
+        ]
+        with pytest.raises(ValueError, match="don't span this part's full height"):
+            build_drawing(part, model=model, number="X")
+
     def test_shelled_cover_boss_diameter_not_dropped(self):
         # The regression: even forced onto A4 (scale 0.5, front view against the left
         # margin) the boss ø28 places into the clear sheet, so it never lints uncovered.