draftwright 0.4.31__tar.gz → 0.4.32__tar.gz

{draftwright-0.4.31 → draftwright-0.4.32}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: draftwright
-Version: 0.4.31
+Version: 0.4.32
 Summary: Automated technical-drawing generation for build123d
 Project-URL: Homepage, https://github.com/pzfreo/draftwright
 Project-URL: Repository, https://github.com/pzfreo/draftwright
@@ -692,7 +692,7 @@ Requires-Dist: numpy>=1.24
 Requires-Dist: ocp-gordon<0.3
 Requires-Dist: pillow>=10
 Requires-Dist: pypdfium2>=4
-Requires-Dist: quiddity==0.3.2
+Requires-Dist: quiddity==0.3.3
 Requires-Dist: reportlab>=4.0
 Requires-Dist: rich>=10.11
 Requires-Dist: steputils==0.1

{draftwright-0.4.31 → draftwright-0.4.32}/docs/reference/recogniser-capabilities.md

@@ -70,11 +70,19 @@ issue. The contract test derives package record outputs, converter registries, l
 and emitter branches independently, so copying a new name into the declaration alone cannot make CI
 pass.
 
-### Quiddity 0.3.2 runtime contract
+### Quiddity 0.3.3 runtime contract
 
-The runtime pins the published `quiddity==0.3.2` package, following the 0.2.4 adoption in
+The runtime pins the published `quiddity==0.3.3` package. This release adds material-side
+reconstruction facts to fillets, planar chamfers and angled steps, paired ramps, and open-section
+profiles. Draftwright consumes these records to describe and annotate the recognised part; it does
+not reconstruct a cut solid from them, so the new `side`, `corner`, `opening_direction`,
+`half_width`, and `material_side` fields do not enter the drafting IR. The exact consumer schema
+declarations advance with the provider, and the section-recess adapter accepts document schema 4
+while continuing to reject unknown later schemas.
+
+Version 0.3.2 followed the 0.2.4 adoption in
 [#1486](https://github.com/pzfreo/draftwright/pull/1486) and the migration in
-[#1471](https://github.com/pzfreo/draftwright/issues/1471). Version 0.3.2 advances the public
+[#1471](https://github.com/pzfreo/draftwright/issues/1471). It advanced the public
 `Slot` record to schema 2: `end_radius` distinguishes two semicircular stadium ends and
 `corner_radius` distinguishes rounded rectangular corners. Draftwright consumes
 `end_radius` for through-slot radius requirements; rounded-corner rectangular slots remain a

{draftwright-0.4.31 → draftwright-0.4.32}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "draftwright"
-version = "0.4.31"
+version = "0.4.32"
 description = "Automated technical-drawing generation for build123d"
 readme = "README.md"
 license = { file = "LICENSE" }
@@ -23,7 +23,7 @@ dependencies = [
     # published wheels, not only uv's development resolver constraints.
     "cadquery-ocp-novtk!=7.9.3.1.1 ; python_full_version >= '3.13'",
     "build123d-drafting-helpers>=0.15.4",
-    "quiddity==0.3.2",
+    "quiddity==0.3.3",
     "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

{draftwright-0.4.31 → draftwright-0.4.32}/src/draftwright/_core.py

@@ -1689,7 +1689,13 @@ def _add_title_block(dwg, a: Analysis):
         bx + cell["max_x"],
         margins.bottom + cell["max_y"],
     )
-    place_annotation(dwg.registry, dwg.items, tb, "title_block")
+    place_annotation(
+        dwg.registry,
+        dwg.items,
+        tb,
+        "title_block",
+        feature=dwg._build.general_tolerance_source,
+    )
 
 
 def _make_sheet_frame(a: Analysis) -> Compound:
@@ -1768,6 +1774,60 @@ def _add_scale_note(dwg, a: Analysis):
     place_annotation(dwg.registry, dwg.items, note, "scale_note")
 
 
+def _add_default_surface_finish(dwg, a: Analysis):
+    """Draw an imported document-wide ISO 1302 requirement without a leader.
+
+    The reserved band above the title block is sheet furniture space.  A document default
+    belongs there: hanging it from model geometry would falsely narrow its scope to one face.
+    """
+    requirement = dwg._build.default_surface_finish_source
+    if requirement is None:
+        return
+
+    from build123d_drafting import SurfaceFinish
+
+    symbol = SurfaceFinish(
+        f"Ra {requirement.ra}",
+        (0, 0),
+        draft=draft_preset(
+            font_size=dwg.draft.font_size,
+            decimal_precision=dwg.draft.decimal_precision,
+            font_path=PLEX_SANS_CONDENSED,
+        ),
+    )
+    box = symbol.bounding_box()
+    width, height = box.max.X - box.min.X, box.max.Y - box.min.Y
+    label = symbol.label_bbox
+    label_x = (label[0] + label[2] - box.min.X - box.max.X) / 2
+    label_y = (label[1] + label[3] - box.min.Y - box.max.Y) / 2
+    # Occupy the left end of the title-block furniture band. Scale and projection method use
+    # its right end, leaving independent document controls readable on every standard sheet.
+    cx = a.PAGE_W - a.TB_W - _title_margins(a).right + width / 2
+    cy = _title_block_top(a) + _TB_FURNITURE_GAP + height / 2
+    symbol = symbol.locate(Location((cx - box.min.X - width / 2, cy - box.min.Y - height / 2, 0)))
+    symbol.pdf_text_relative_specs = (
+        (
+            symbol.label,
+            label_x,
+            label_y,
+            dwg.draft.font_size,
+            PLEX_SANS_CONDENSED,
+            "IBM Plex Sans Condensed",
+            "REGULAR",
+            "center",
+            "middle",
+        ),
+    )
+    symbol.is_default_surface_finish = True
+    place_annotation(
+        dwg.registry,
+        dwg.items,
+        symbol,
+        "default_surface_finish",
+        feature=requirement,
+    )
+
+
 def _add_projection_symbol(dwg, a: Analysis):
     """Place the ISO 5456-2 projection-method glyph (#769) in the reserved title-block band,
     just above the drawn title block (deterministic empty space — the block reserves _TB_H but

{draftwright-0.4.31 → draftwright-0.4.32}/src/draftwright/annotations/from_model.py

@@ -2704,6 +2704,7 @@ def place_machined_leader_jobs(
     expand_lanes=True,
     region_policy=LeaderRegionPolicy.EXTERIOR,
     source_ids_by_name=None,
+    source_drop_severity="warning",
     priority=0.0,
 ) -> int:
     """Lower every machined callout to the one shared ``FeatureLeaderJob`` path.
@@ -2819,8 +2820,25 @@ def place_machined_leader_jobs(
                         feature,
                     )
 
-        def _build(tip, elbow, _feature, *, _label=label):
-            return Leader(tip=(tip[0], tip[1], 0), elbow=elbow, label=_label, draft=dwg.draft)
+        source_features = tuple(
+            {
+                id(getattr(identity, "feature", None)): getattr(identity, "feature", None)
+                for identity in measurement
+                if getattr(identity, "feature", None) is not None
+            }.values()
+        )
+
+        def _build(
+            tip,
+            elbow,
+            _feature,
+            *,
+            _label=label,
+            _source_features=source_features,
+        ):
+            leader = Leader(tip=(tip[0], tip[1], 0), elbow=elbow, label=_label, draft=dwg.draft)
+            leader.source_features = _source_features
+            return leader
 
         def _fallback_accept(
             candidate,
@@ -2883,8 +2901,13 @@ def place_machined_leader_jobs(
         ):
             validation = reason == "geometry_validation"
             detail = "rendered geometry validation failed" if validation else "no clear room"
+            severity = (
+                ("error" if _source_ids else "warning")
+                if source_drop_severity == "source"
+                else source_drop_severity
+            )
             ctx.record_issue(
-                "warning",
+                severity,
                 drop_code,
                 f"{noun} callout {_label} not placed ({detail})",
                 measurement=_measurement,
@@ -2934,7 +2957,7 @@ def place_machined_leader_jobs(
                 fallback_accept=_fallback_accept,
                 interior_label_clear=interior_label_clear,
                 allow_policy_b_fixed=True,
-                on_drop=_on_drop if source_ids else None,
+                on_drop=(_on_drop if source_ids or source_drop_severity == "source" else None),
             )
         )
 
@@ -2996,6 +3019,7 @@ def render_chamfers(dwg, plan, a, *, ctx, only=None) -> int:
         collapse.setdefault(spec, []).append((g, pd))
 
     jobs = []
+    source_ids_by_name = {}
     for gi, (_spec, members) in enumerate(sorted(collapse.items())):
         if only is not None:
             # Filter after enumerating the full collapse so a surviving group keeps the same
@@ -3023,9 +3047,17 @@ def render_chamfers(dwg, plan, a, *, ctx, only=None) -> int:
         label = _chamfer_label(representative_pd.value_text, representative_pd.value, ch)
         if len(members) > 1:
             label = f"{len(members)}× {label}"
+        name = f"m_chamfer_{axis}{gi}"
+        source_ids_by_name[name] = tuple(
+            dict.fromkeys(
+                source_id
+                for member, _pd in members
+                for source_id in getattr(member.facts, "source_ids", ())
+            )
+        )
         jobs.append(
             (
-                f"m_chamfer_{axis}{gi}",
+                name,
                 view,
                 vb,
                 label + _tol_suffix(representative_pd.tolerance, draft),
@@ -3050,6 +3082,8 @@ def render_chamfers(dwg, plan, a, *, ctx, only=None) -> int:
         ctx=ctx,
         joint=True,
         region_policy=LeaderRegionPolicy.AUTO,
+        source_ids_by_name=source_ids_by_name,
+        source_drop_severity="source",
     )
 
 
@@ -8872,6 +8906,26 @@ def _pmi_source_ids(item) -> tuple[str, ...]:
     return tuple(dict.fromkeys(((singular,) if singular else ()) + plural))
 
 
+def render_document_notes(dwg, model) -> int:
+    """Place source-proven drawing-wide requirements in one solver-owned notes block."""
+    notes = [feature for feature in model.features if feature.kind == "document_note"]
+    if not notes:
+        return 0
+    rows = [("GENERAL NOTES",)] + [
+        (f"{index}  {_font_safe_text(note.text)}",) for index, note in enumerate(notes, 1)
+    ]
+    placed = dwg.add_table(
+        rows,
+        prefer="tr",
+        name="general_notes",
+        _source_ids=tuple(source_id for note in notes for source_id in _pmi_source_ids(note)),
+        _features=tuple(notes),
+        _drop_code="pmi_dropped",
+        _drop_severity="error",
+    )
+    return len(notes) if placed is not None else 0
+
+
 def _gdt_glyph(item, draft):
     """Build the ISO 1101/5459/1302 glyph sketch for one GD&T IR item at the origin
     (the :class:`Leader` repositions it). A fresh sketch per call — the leader translate

{draftwright-0.4.31 → draftwright-0.4.32}/src/draftwright/annotations/orchestrator.py

@@ -24,6 +24,7 @@ from draftwright._core import (
     Analysis,
     DetailRequest,
     HoleRef,
+    _add_default_surface_finish,
     _add_projection_symbol,
     _add_scale_note,
     _add_sheet_frame,
@@ -936,6 +937,7 @@ def _auto_annotate(dwg, a: Analysis, *, detail_view: bool = False):
         # ISO 5456-2 projection-method glyph (#769) in the reserved title-block band.
         _add_projection_symbol(dwg, a)
         _add_scale_note(dwg, a)
+        _add_default_surface_finish(dwg, a)
 
     def _s_tabulate():
         # Escalate to a hole table when the plan view is too dense to dimension

{draftwright-0.4.31 → draftwright-0.4.32}/src/draftwright/builder.py

@@ -34,6 +34,7 @@ from draftwright._core import (
     _LADDER,
     _PAGE_SIZES,
     _SCALES,
+    _add_default_surface_finish,
     _add_projection_symbol,
     _add_scale_note,
     _add_sheet_frame,
@@ -58,6 +59,7 @@ from draftwright.annotations._common import (
     annotation_ink_obstacles,
     place_iso_nts_note,
 )
+from draftwright.annotations.from_model import render_document_notes
 from draftwright.annotations.gears import render_gear_tables
 from draftwright.annotations.orchestrator import (
     _WITHHOLDING_CODES,
@@ -567,6 +569,7 @@ def _assemble(
                     features=[*pm.features, rot],
                     declaration_identities=(*identities, None) if identities else (),
                 )
+
         # A z step declares a segment of a z-turned profile. `.step()` on a BOSS — an external
         # cylinder on a prismatic part — is a misuse of the verb, and the symptom is that the
         # declared steps leave the bulk of the part unspanned (#631). This is a verb-misuse
@@ -586,13 +589,16 @@ def _assemble(
         # annotations detection would (render_pmi reads them off the model, gated on a.pmi_mode)
         # so a re-run reproduces the PMI dims (#472). Gated on the caller not having declared
         # imported authored annotations, so an explicit set wins.
+        def _declares_imported_pmi(feature) -> bool:
+            if feature.kind in ("authored_dimension", "pmi"):
+                return True
+            return bool(
+                getattr(feature, "source_id", "") or tuple(getattr(feature, "source_ids", ()))
+            )
+
         if (
             a.pmi_mode == "annotate"
-            and not any(
-                f.kind in ("authored_dimension", "pmi")
-                or (f.kind == "control_frame" and bool(getattr(f, "source_id", "")))
-                for f in pm.features
-            )
+            and not any(_declares_imported_pmi(feature) for feature in pm.features)
             and not any(
                 getattr(value, "source", "") == "ap242_pmi" and getattr(value, "source_ids", ())
                 for value in pm.decorations.values()
@@ -636,6 +642,15 @@ def _assemble(
                         else ()
                     ),
                 )
+    # A source-proven document default uses the existing title-block carrier when the caller
+    # did not explicitly author one. An explicit tolerance, including the blank string, wins.
+    general_tolerance_source = None
+    if a.tolerance is None:
+        defaults = [feature for feature in pm.features if feature.kind == "general_tolerance"]
+        if len(defaults) == 1:
+            general_tolerance_source = defaults[0]
+            a = replace(a, tolerance=getattr(general_tolerance_source, "designation"))
+
     # ADR 1 (was 0005 §2) (#639): the ONE build-context attachment — analysis + finished model
     # in a single typed BuildState; the compat properties on Drawing read through it.
     dwg._build.analysis = a
@@ -655,6 +670,13 @@ def _assemble(
         ownership=a.recognition_ownership,
     )
     dwg._build.part_model = pm
+    dwg._build.general_tolerance_source = general_tolerance_source
+    default_finishes = [
+        feature for feature in pm.features if feature.kind == "default_surface_finish"
+    ]
+    dwg._build.default_surface_finish_source = (
+        default_finishes[0] if len(default_finishes) == 1 else None
+    )
     # Persist the caller's detail-view setting: on the auto_dims=False path the flag
     # reaches no pass here, but the finalize drain gates the prismatic detail
     # request on it exactly as the auto pass does (#661).
@@ -784,6 +806,7 @@ def _assemble(
             _add_zone_grid(dwg, a)
         _add_projection_symbol(dwg, a)
         _add_scale_note(dwg, a)
+        _add_default_surface_finish(dwg, a)
 
     # The NTS caption is post-fit late furniture too, and goes FIRST: it is tied to the
     # iso block it labels, whereas a table may sit anywhere the sheet has room. Placing
@@ -796,6 +819,7 @@ def _assemble(
     # `_fit_iso_view`; placing a table there lets the subsequently fitted ISO view move into
     # it. Every initial/repacked assembly reaches this common point after its final ISO fit,
     # and `add_table()` now sees the settled views plus all earlier annotations as obstacles.
+    render_document_notes(dwg, pm)
     render_gear_tables(dwg, pm)
 
     # The audit ledger, filled at ONE site for both paths (#996 / ADR 1 (was 0005 §2)).

{draftwright-0.4.31 → draftwright-0.4.32}/src/draftwright/drawing.py

@@ -20,7 +20,7 @@ from contextvars import ContextVar
 from dataclasses import dataclass
 from dataclasses import field as dataclasses_field
 from itertools import permutations
-from typing import TYPE_CHECKING, Any, NamedTuple
+from typing import TYPE_CHECKING, Any, Literal, NamedTuple
 
 if TYPE_CHECKING:
     from quiddity import RecognitionResult
@@ -526,6 +526,11 @@ class BuildState:
     #: The title block's deterministic page-space footprint, measured before it is
     #: drawn so strip placement can avoid it (#1593). None until the builder sets it.
     pending_title_block_box: tuple | None = None
+    #: Imported document default selected as the title-block tolerance carrier. ``None``
+    #: when the caller supplied any explicit value, even identical display text.
+    general_tolerance_source: object | None = None
+    #: Imported document-wide surface finish rendered as title-block furniture.
+    default_surface_finish_source: object | None = None
     #: Per-view filled projected material (#798) as ``{id(view_shape): (shape, field)}``.
     #: Keyed by shape identity because the projected shapes carry no view label (lint
     #: takes their names from ``Drawing.views`` since #1196), and holding the shape
@@ -3804,6 +3809,10 @@ class Drawing:
         name="table",
         block_cols=None,
         _source_id: str | None = None,
+        _source_ids: tuple[str, ...] = (),
+        _features: tuple[object, ...] = (),
+        _drop_code: str = "table_dropped",
+        _drop_severity: Literal["error", "warning", "info"] = "warning",
         _cells=(),
     ):
         """Add a generic data table in the preferred available sheet region (#93/#1145).
@@ -3876,18 +3885,23 @@ class Drawing:
                 detail = "solver returned no placement trace"
             self._registry.record_issue(
                 LintIssue(
-                    severity="warning",
-                    code="table_dropped",
+                    severity=_drop_severity,
+                    code=_drop_code,
                     message=(
                         f"table {name!r} did not fit the sheet; measured page-space footprint "
                         f"{measured}; {detail}"
                     ),
-                    source_ids=(_source_id,) if _source_id is not None else (),
+                    source_ids=tuple(
+                        dict.fromkeys(
+                            ((_source_id,) if _source_id is not None else ()) + _source_ids
+                        )
+                    ),
                     measurement_ids=tuple(cell.measurement for cell in _cells),
                 )
             )
             return None
         placed = table.locate(Location((pos[0], pos[1], 0)))
+        placed.source_features = _features
         if not _cells:
             return self._add(placed, name)
         snapshot = self._registry.snapshot()

{draftwright-0.4.31 → draftwright-0.4.32}/src/draftwright/inspection_contract.py

@@ -17,7 +17,7 @@ from quiddity.inspection import inspection_api_manifest
 CONSUMER_INSPECTION_FORMAT = "draftwright-inspection-api"
 CONSUMER_INSPECTION_FORMAT_VERSION = 1
 SUPPORTED_INSPECTION_API_MAJOR = 1
-SUPPORTED_RECOGNISER_VERSION = "0.3.2"
+SUPPORTED_RECOGNISER_VERSION = "0.3.3"
 _DISTRIBUTION = "quiddity"
 _PROVIDER_FORMAT = "quiddity-inspection-api"
 _NAMESPACE = "quiddity.inspection"

{draftwright-0.4.31 → draftwright-0.4.32}/src/draftwright/model/__init__.py

@@ -82,8 +82,10 @@ from draftwright.model.ir import (
     Datum,
     DatumRef,
     DeclarationIdentity,
+    DefaultSurfaceFinish,
     DimensionParameterId,
     DimParameter,
+    DocumentNote,
     EnvelopeFeature,
     ExternalSpurGearFeature,
     Feature,
@@ -91,6 +93,7 @@ from draftwright.model.ir import (
     FilletFeature,
     FlatFeature,
     Frame,
+    GeneralTolerance,
     GrooveFeature,
     GussetRibFeature,
     HexPocketFeature,
@@ -165,8 +168,10 @@ __all__ = [
     "GussetRibFeature",
     "Datum",
     "DatumRef",
+    "DefaultSurfaceFinish",
     "DeclarationIdentity",
     "DimParameter",
+    "DocumentNote",
     "EnvelopeFeature",
     "ExternalSpurGearFeature",
     "AddressableDimension",
@@ -176,6 +181,7 @@ __all__ = [
     "ViewPlanIncomplete",
     "Feature",
     "Frame",
+    "GeneralTolerance",
     "HoleFeature",
     "KnurlRequirement",
     "LayoutOverride",

{draftwright-0.4.31 → draftwright-0.4.32}/src/draftwright/model/compiled.py

@@ -471,6 +471,9 @@ _FACTS: dict[str, tuple[str, ...]] = {
     "datum_ref": (),
     "finish": (),
     "note": (),
+    "general_tolerance": (),
+    "default_surface_finish": (),
+    "document_note": (),
 }
 
 

{draftwright-0.4.31 → draftwright-0.4.32}/src/draftwright/model/declare.py

@@ -603,6 +603,10 @@ def chamfer(
     angle=None,
     at=None,
     turned=False,
+    source_ids=(),
+    part21_id="",
+    shape_aspect_ids=(),
+    reference_item_ids=(),
 ) -> ChamferFeature:
     """A chamfer (bevelled edge, #560/#576). Either ``chamfer(bevel_face)`` — the oblique
     chamfer face supplies axis, both legs and a leader point **on the bevel** — or explicit
@@ -647,6 +651,10 @@ def chamfer(
         leg2=lo,
         angle=angle,
         turned=bool(turned),
+        source_ids=tuple(source_ids),
+        part21_id=str(part21_id),
+        shape_aspect_ids=tuple(shape_aspect_ids),
+        reference_item_ids=tuple(reference_item_ids),
     )
 
 

{draftwright-0.4.31 → draftwright-0.4.32}/src/draftwright/model/detect.py

@@ -487,6 +487,7 @@ def build_pmi_features(
             semantic_name=r.semantic_name,
             shape_aspect_ids=r.shape_aspect_ids,
             cylindrical_refs=r.cylindrical_refs,
+            reference_bboxes=r.reference_bboxes,
         )
         if r.source_category == "geometric_tolerance" and not r.lowering_blockers:
             material_modifier = None

{draftwright-0.4.31 → draftwright-0.4.32}/src/draftwright/model/ir.py

@@ -2393,6 +2393,10 @@ class ChamferFeature:
     # same ``axis`` field is the bevel-edge direction for a prismatic chamfer, so this semantic
     # discriminator is required for faithful view selection and Sheet round-trip (#1276).
     turned: bool = False
+    source_ids: tuple[str, ...] = ()
+    part21_id: str = ""
+    shape_aspect_ids: tuple[str, ...] = ()
+    reference_item_ids: tuple[str, ...] = ()
     kind: ClassVar[str] = "chamfer"
 
     def parameters(self) -> list[DimParameter]:
@@ -3687,6 +3691,7 @@ class PmiFeature:
     semantic_name: str = ""
     shape_aspect_ids: tuple[str, ...] = ()
     cylindrical_refs: tuple[CylindricalReference, ...] = ()
+    reference_bboxes: tuple[tuple[float, float, float, float, float, float], ...] = ()
     kind: ClassVar[str] = "pmi"
 
     def parameters(self) -> list[DimParameter]:
@@ -3696,6 +3701,87 @@ class PmiFeature:
         return []
 
 
+@dataclass(frozen=True)
+class GeneralTolerance:
+    """A document-wide dimensional tolerance requirement carried by the title block."""
+
+    frame: Frame
+    designation: str
+    statement: str = ""
+    source_id: str = ""
+    part21_id: str = ""
+    kind: ClassVar[str] = "general_tolerance"
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.designation, str) or not self.designation.strip():
+            raise ValueError("general tolerance needs a non-empty designation")
+        if self.designation != self.designation.strip():
+            raise ValueError("general tolerance designation cannot contain surrounding whitespace")
+
+    def parameters(self) -> list[DimParameter]:
+        return []
+
+    def references(self) -> list[Datum]:
+        return []
+
+
+@dataclass(frozen=True)
+class DefaultSurfaceFinish:
+    """A document-wide ISO 1302 surface-texture requirement.
+
+    Unlike :class:`Finish`, this requirement has no geometric target and therefore renders as
+    sheet furniture without a leader.  ``statement`` retains the source wording while ``ra`` is
+    the normalized micrometre value shown by the drafting symbol.
+    """
+
+    frame: Frame
+    ra: str
+    statement: str = ""
+    source_id: str = ""
+    part21_id: str = ""
+    kind: ClassVar[str] = "default_surface_finish"
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.ra, str) or not self.ra.strip():
+            raise ValueError("default surface finish needs a non-empty Ra value")
+        if self.ra != self.ra.strip():
+            raise ValueError(
+                "default surface finish Ra value cannot contain surrounding whitespace"
+            )
+
+    def parameters(self) -> list[DimParameter]:
+        return []
+
+    def references(self) -> list[Datum]:
+        return []
+
+
+@dataclass(frozen=True)
+class DocumentNote:
+    """A source-proven document requirement with no honest geometric attachment."""
+
+    frame: Frame
+    text: str
+    note_kind: str
+    source_id: str = ""
+    part21_id: str = ""
+    kind: ClassVar[str] = "document_note"
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.text, str) or not self.text.strip():
+            raise ValueError("document note needs non-empty text")
+        if self.text != self.text.strip():
+            raise ValueError("document note text cannot contain surrounding whitespace")
+        if self.note_kind not in ("datum_scheme", "model_representation"):
+            raise ValueError(f"unsupported document-note kind {self.note_kind!r}")
+
+    def parameters(self) -> list[DimParameter]:
+        return []
+
+    def references(self) -> list[Datum]:
+        return []
+
+
 @dataclass(frozen=True)
 class ControlFrame:
     """A geometric-tolerance feature control frame (ISO 1101) declared on the drawing