simcon-toolkit 0.1.0__py3-none-any.whl

simcon_toolkit/_kit/templates/quoting/quoting/geometry.py

@@ -0,0 +1,398 @@
+"""Everything a moldmaker reads off the geometry before quoting - offline, no cloud, no licence.
+
+The quote's biggest cost drivers are decided here, not in the simulation:
+
+  * **projected area** in the draw direction -> clamp force -> which press -> the hourly rate.
+  * **wall thickness** -> cooling time -> cycle time -> the piece price.
+  * **undercuts** -> slides and lifters -> a four-figure line each on the tool.
+  * **part volume** -> shot size, material cost, and the press's shot-capacity window.
+
+All of it is geometric, all of it is free, and all of it is wrong often enough that the numbers
+are reported with their spread rather than as single values. Run this first: it costs seconds
+and it tells you whether the part is even quotable before a single cloud run is spent.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+
+import numpy as np
+import trimesh
+
+from cadmould_geometry.stl import open_edge_count, read_stl, surface_area_mm2, volume_mm3
+
+AXES = "xyz"
+
+
+# ==========================================================================
+# the mesh
+# ==========================================================================
+def load_mesh(stl_path: str | Path) -> trimesh.Trimesh:
+    """Read an STL into the triangle soup every measurement below works from.
+
+    Read through ``cadmould_geometry.stl``, the kit's one STL reader, so a gate index
+    here means the same vertex it means everywhere else. ``process=False`` keeps that
+    guarantee: trimesh would otherwise merge and reorder vertices on load.
+
+    An STL's winding decides which way a normal points, and every measurement below
+    asks "is this facet's outward side", so a file wound inside-out is corrected once
+    here rather than inverting undercuts and wall thickness silently. Measured on the
+    sample part, an uncorrected inside-out file reads a 3.21 mm median wall against the
+    true 1.33 mm, and 14 side actions against 4 - a quote inflated at both ends.
+
+    ⚠️ The test must use trimesh's SIGNED ``volume``. ``cadmould_geometry``'s
+    ``volume_mm3`` applies ``abs()`` deliberately, because its other callers want a
+    positive number, so comparing it against zero can never be true. Only a closed
+    surface has a meaningful sign; an open one is left alone and already carries a note
+    saying its measurements are estimates.
+    """
+    vertices, faces = read_stl(stl_path)
+    mesh = trimesh.Trimesh(vertices=vertices, faces=faces, process=False)
+    if open_edge_count(vertices, faces) == 0 and mesh.volume < 0:
+        mesh.invert()
+    return mesh
+
+
+def _facets(mesh: trimesh.Trimesh) -> tuple[np.ndarray, np.ndarray, np.ndarray]:
+    """Triangle centres, unit outward normals and areas."""
+    return (
+        np.asarray(mesh.triangles_center, dtype=np.float64),
+        np.asarray(mesh.face_normals, dtype=np.float64),
+        np.asarray(mesh.area_faces, dtype=np.float64),
+    )
+
+
+def through_hole_count(mesh: trimesh.Trimesh) -> int:
+    """Number of through-holes, from the surface genus (Euler characteristic).
+
+    For a closed triangulated surface every edge is shared by two faces, so E = 3F/2 and
+    ``chi = V - E + F``; the genus ``(2 - chi)/2`` is the number of handles, which for a moulded
+    part is the number of holes the melt has to flow around.
+
+    This matters twice on a quote, and neither is obvious from looking at the part list: each hole
+    needs a **core pin** in every cavity, and each hole **splits the flow front**, which knits back
+    together downstream and leaves a weld line there. Returns 0 for an open (non-watertight) mesh,
+    where the count would be meaningless.
+    """
+    if open_edge_count(mesh.vertices, mesh.faces) != 0:
+        return 0
+    faces, verts = int(len(mesh.faces)), int(len(mesh.vertices))
+    chi = verts - (3 * faces) // 2 + faces
+    return max(0, (2 - chi) // 2)
+
+
+def _area_weighted_sample(areas: np.ndarray, n: int, rng: np.random.Generator) -> np.ndarray:
+    """Sample facets in proportion to their area.
+
+    Uniform-by-facet sampling is the trap here: an STL's rim is meshed with many tiny triangles,
+    and a ray cast inward from a rim facet measures the part's *span*, not its wall. Weighting by
+    area makes every mm2 of surface equally likely, which is also the quantity we actually want -
+    "how much of the part is thin" rather than "how many triangles are thin".
+    """
+    p = areas / max(float(areas.sum()), 1e-12)
+    return rng.choice(len(areas), size=min(n, len(areas) * 4), replace=True, p=p)
+
+
+# ==========================================================================
+# the part
+# ==========================================================================
+@dataclass
+class PartGeometry:
+    """Geometric facts about one part, in mm / cm3 / cm2."""
+
+    path: Path
+    bbox_mm: tuple[float, float, float]
+    volume_cm3: float
+    surface_area_cm2: float
+    draw_axis: int
+    projected_area_cm2: float  # shadow in the draw direction (per cavity)
+    draw_depth_mm: float
+    wall_mm: dict  # min / p05 / median / mean / p95 / max
+    undercut_area_mm2: float
+    side_actions: int
+    zero_draft_area_pct: float
+    watertight: bool
+    n_triangles: int
+    through_holes: int = 0
+    notes: list[str] = field(default_factory=list)
+
+    # -- derived -----------------------------------------------------------
+    @property
+    def nominal_wall_mm(self) -> float:
+        """The wall the part *flows* through - median is robust to ribs and slivers."""
+        return float(self.wall_mm["median"])
+
+    @property
+    def governing_wall_mm(self) -> float:
+        """The wall that governs **ejection**: the slowest-cooling section (p95, not max).
+
+        The maximum sits on a boss or a sliver and would inflate the cycle; the 95th percentile
+        is the same physical quantity without the outlier. See the cooling model in costing.py.
+        """
+        return float(self.wall_mm["p95"])
+
+    @property
+    def flow_length_ratio(self) -> float:
+        """L/t on the longest bbox edge - the classic fillability screen."""
+        return float(max(self.bbox_mm) / max(self.nominal_wall_mm, 1e-6))
+
+    @property
+    def surface_to_volume(self) -> float:
+        """cm^-1. Informative, but do not price with it - it mostly measures wall thinness."""
+        return float(self.surface_area_cm2 / max(self.volume_cm3, 1e-9))
+
+    @property
+    def shape_factor(self) -> float:
+        """Surface area relative to the bounding box's - "how much shape is in there".
+
+        This is the honest complexity proxy for a cavity-machining estimate. Surface-to-volume
+        looks like one and is not: a plain 1.5 mm plate scores 15 cm^-1 on it purely for being
+        thin, which would price a trivial cavity as a hard one. A flat part sits near or below
+        1.0 here; ribs, bosses and pockets push it above 1.
+        """
+        a, b, c = self.bbox_mm
+        bbox_cm2 = 2.0 * (a * b + b * c + a * c) / 100.0
+        return float(self.surface_area_cm2 / max(bbox_cm2, 1e-9))
+
+    def as_dict(self) -> dict:
+        return {
+            "path": str(self.path),
+            "bbox_mm": [round(v, 2) for v in self.bbox_mm],
+            "volume_cm3": round(self.volume_cm3, 3),
+            "surface_area_cm2": round(self.surface_area_cm2, 2),
+            "draw_axis": AXES[self.draw_axis],
+            "projected_area_cm2": round(self.projected_area_cm2, 2),
+            "draw_depth_mm": round(self.draw_depth_mm, 2),
+            "wall_mm": {k: round(v, 3) for k, v in self.wall_mm.items()},
+            "nominal_wall_mm": round(self.nominal_wall_mm, 3),
+            "governing_wall_mm": round(self.governing_wall_mm, 3),
+            "flow_length_ratio": round(self.flow_length_ratio, 1),
+            "surface_to_volume_cm-1": round(self.surface_to_volume, 2),
+            "shape_factor": round(self.shape_factor, 2),
+            "undercut_area_mm2": round(self.undercut_area_mm2, 1),
+            "side_actions": self.side_actions,
+            "zero_draft_area_pct": round(self.zero_draft_area_pct, 1),
+            "through_holes": self.through_holes,
+            "watertight": self.watertight,
+            "n_triangles": self.n_triangles,
+            "notes": self.notes,
+        }
+
+    def report(self) -> str:
+        w = self.wall_mm
+        lines = [
+            f"  part            {self.path.name}",
+            f"  bbox            {self.bbox_mm[0]:.1f} x {self.bbox_mm[1]:.1f} x {self.bbox_mm[2]:.1f} mm",
+            f"  volume          {self.volume_cm3:.2f} cm3   surface {self.surface_area_cm2:.1f} cm2",
+            f"  draw direction  {AXES[self.draw_axis]}  (depth {self.draw_depth_mm:.1f} mm)",
+            f"  projected area  {self.projected_area_cm2:.2f} cm2  <- clamp force basis",
+            f"  wall thickness  median {w['median']:.2f}  mean {w['mean']:.2f}  "
+            f"p05 {w['p05']:.2f}  p95 {w['p95']:.2f} mm",
+            f"  flow length/t   {self.flow_length_ratio:.0f}      shape factor {self.shape_factor:.2f} "
+            f"(surface/volume {self.surface_to_volume:.2f} cm-1)",
+            f"  undercuts       {self.undercut_area_mm2:.0f} mm2 -> {self.side_actions} side action(s)",
+            f"  through-holes   {self.through_holes}  (core pins per cavity; each knits a weld behind it)",
+            f"  zero-draft area {self.zero_draft_area_pct:.1f} %   watertight: {self.watertight}",
+        ]
+        lines += [f"  ! {n}" for n in self.notes]
+        return "\n".join(lines)
+
+
+# ==========================================================================
+# analysis
+# ==========================================================================
+def _projected_area_mm2(mesh: trimesh.Trimesh, axis: int) -> float:
+    """Shadow area along ``axis``.
+
+    For a closed surface every ray crosses the body an even number of times, so the summed
+    |projected| facet area is exactly twice the silhouette area. Robust, and far cheaper than
+    rasterising the silhouette.
+    """
+    _, normals, areas = _facets(mesh)
+    return float(0.5 * np.sum(areas * np.abs(normals[:, axis])))
+
+
+def _wall_thickness(mesh: trimesh.Trimesh, idx: np.ndarray) -> np.ndarray:
+    """Local wall thickness at each sampled facet: the largest sphere that fits inside.
+
+    The inscribed-sphere measure is the one a moldmaker means by "wall": at a point on the
+    surface it is the biggest ball that fits in the material touching there, so it reads a
+    1.5 mm plate as 1.5 mm from the face and from the rim alike. That last part is why it
+    replaced a bundle of inward rays - a ray cast inward from a rim facet measures the
+    plate's *span*, and no amount of tilting the bundle fixes the general case.
+
+    It is also the reason this module no longer builds a VTK OBB tree. That tree came out
+    different on every build from the same file, so the same part measured between 1 and
+    461 usable samples run to run, and reported a 31 mm median wall on a part 21.9 mm deep.
+    Both numbers feed cooling time, and through it the piece price.
+    """
+    _, normals, _ = _facets(mesh)
+    thickness = trimesh.proximity.thickness(
+        mesh,
+        mesh.triangles_center[idx],
+        exterior=False,
+        normals=normals[idx],
+        method="max_sphere",
+    )
+    thickness = np.asarray(thickness, dtype=np.float64)
+    return thickness[np.isfinite(thickness) & (thickness > 0)]
+
+
+def _undercuts(mesh: trimesh.Trimesh, idx: np.ndarray, axis: int) -> tuple[float, int, float, np.ndarray]:
+    """Facet area that releases in neither draw direction, clustered into side actions.
+
+    A facet releases along +d if its normal points that way *and* nothing blocks the path out.
+    Facets nearly parallel to the draw (|n.d| < 0.05) are near-zero-draft walls - a draft problem,
+    not an undercut - and are counted separately. Sampling is area-weighted, so the undercut
+    *fraction* of the samples is an unbiased estimate of the undercut *fraction of the surface*.
+
+    Every ray is cast in one vectorised call rather than one at a time, which is both faster
+    and what keeps the answer identical run to run.
+    """
+    centers, normals, areas = _facets(mesh)
+    total = float(areas.sum())
+    eps = max(float(np.linalg.norm(mesh.bounds[1] - mesh.bounds[0])) * 1e-5, 1e-4)
+
+    d = np.zeros(3)
+    d[axis] = 1.0
+    nd = normals[idx] @ d
+    drafted = np.abs(nd) >= 0.05
+    n_zero_draft = int((~drafted).sum())
+
+    stuck = np.zeros((0, 3))
+    if drafted.any():
+        out_dirs = np.where(nd[drafted, None] > 0, d, -d)
+        origins = centers[idx][drafted] + out_dirs * eps
+        blocked = np.asarray(mesh.ray.intersects_any(origins, out_dirs), dtype=bool)
+        stuck = origins[blocked] - out_dirs[blocked] * eps
+
+    n = max(len(idx), 1)
+    return total * len(stuck) / n, len(stuck), 100.0 * n_zero_draft / n, stuck
+
+
+def _cluster(points: np.ndarray, radius: float) -> int:
+    """Greedy spatial clustering - one cluster is one side action."""
+    if len(points) == 0:
+        return 0
+    unassigned = list(range(len(points)))
+    clusters = 0
+    while unassigned:
+        seed = unassigned.pop(0)
+        members = [seed]
+        grew = True
+        while grew:
+            grew = False
+            for j in list(unassigned):
+                if np.min(np.linalg.norm(points[members] - points[j], axis=1)) <= radius:
+                    members.append(j)
+                    unassigned.remove(j)
+                    grew = True
+        clusters += 1
+    return clusters
+
+
+def analyse(
+    stl_path: str | Path,
+    *,
+    draw_axis: int | None = None,
+    samples: int = 900,
+    undercut_area_per_action_mm2: float = 400.0,
+    seed: int = 7,
+    logger=print,
+) -> PartGeometry:
+    """Read the STL and derive everything the quote needs from the shape alone."""
+    stl_path = Path(stl_path)
+    mesh = load_mesh(stl_path)
+    rng = np.random.default_rng(seed)
+    lo, hi = mesh.bounds
+    dims = tuple(float(v) for v in (hi - lo))
+    volume_cm3 = abs(volume_mm3(mesh.vertices, mesh.faces)) / 1000.0
+    surface_cm2 = surface_area_mm2(mesh.vertices, mesh.faces) / 100.0
+    notes: list[str] = []
+
+    open_edges = open_edge_count(mesh.vertices, mesh.faces)
+    watertight = open_edges == 0
+    if not watertight:
+        notes.append(
+            f"the STL is not watertight ({open_edges} open edges) - volume, wall thickness "
+            "and undercuts are estimates; ask for a clean solid before the quote is binding"
+        )
+
+    # Draw direction: the axis whose shadow is largest. That is the plate face on almost every
+    # technical part, and it is the conservative choice for clamp force. Override when the
+    # customer's drawing shows the parting line elsewhere.
+    projected = [_projected_area_mm2(mesh, a) for a in range(3)]
+    auto_axis = int(np.argmax(projected))
+    if draw_axis is None:
+        draw_axis = auto_axis
+    elif int(draw_axis) != auto_axis:
+        notes.append(f"draw direction forced to {AXES[draw_axis]}; the largest shadow is on {AXES[auto_axis]}")
+
+    # One area-weighted sample drives both measurements, so the undercut fraction and the
+    # wall spread describe the same set of facets rather than two different draws.
+    idx = _area_weighted_sample(np.asarray(mesh.area_faces, dtype=np.float64), samples, rng)
+    logger(f"  measuring {len(idx)} samples for wall thickness and undercuts ...")
+    thickness = _wall_thickness(mesh, idx)
+    if len(thickness) < 10:
+        raise RuntimeError("wall-thickness sampling failed - is the STL a closed solid?")
+    wall = {
+        "min": float(np.min(thickness)),
+        "p05": float(np.percentile(thickness, 5)),
+        "median": float(np.median(thickness)),
+        "mean": float(np.mean(thickness)),
+        "p95": float(np.percentile(thickness, 95)),
+        "max": float(np.max(thickness)),
+    }
+
+    uc_area, n_stuck, zero_draft_pct, uc_pts = _undercuts(mesh, idx, draw_axis)
+    # Cluster at a tenth of the part's longest edge: separate features, not separate facets.
+    n_clusters = _cluster(uc_pts, radius=max(dims) * 0.10) if n_stuck else 0
+    # Two independent estimates of the side-action count; take the larger, because a missed
+    # slide is a five-figure surprise and an extra one is a four-figure conservatism.
+    by_area = int(np.ceil(uc_area / undercut_area_per_action_mm2)) if uc_area > 0 else 0
+    side_actions = max(n_clusters, by_area)
+
+    if wall["median"] < 0.8:
+        notes.append(f"nominal wall {wall['median']:.2f} mm is below the 0.8 mm we are cautious about")
+    if wall["p95"] / max(wall["median"], 1e-6) > 2.5:
+        notes.append(
+            f"wall varies strongly ({wall['p05']:.2f}-{wall['p95']:.2f} mm) - sink marks and "
+            "differential shrinkage are a real risk; cooling time is set by the thick sections"
+        )
+    if side_actions:
+        notes.append(
+            f"{side_actions} side action(s) estimated from {uc_area:.0f} mm2 of undercut - verify against the drawing"
+        )
+    holes = through_hole_count(mesh)
+    if holes:
+        notes.append(
+            f"{holes} through-hole(s): each needs a core pin per cavity, and each splits the flow "
+            "front so a weld line knits behind it. The weld detector resolves head-on front "
+            "collisions and under-reports these, so treat the predicted weld count as a LOWER BOUND"
+        )
+
+    return PartGeometry(
+        path=stl_path,
+        bbox_mm=dims,
+        volume_cm3=volume_cm3,
+        surface_area_cm2=surface_cm2,
+        draw_axis=int(draw_axis),
+        projected_area_cm2=projected[draw_axis] / 100.0,
+        draw_depth_mm=dims[draw_axis],
+        wall_mm=wall,
+        undercut_area_mm2=uc_area,
+        side_actions=side_actions,
+        zero_draft_area_pct=zero_draft_pct,
+        watertight=watertight,
+        n_triangles=int(len(mesh.faces)),
+        through_holes=holes,
+        notes=notes,
+    )
+
+
+if __name__ == "__main__":
+    import sys
+
+    geo = analyse(sys.argv[1] if len(sys.argv) > 1 else "../../assets/parts/clip_frame.stl")
+    print(geo.report())

simcon_toolkit/_kit/templates/quoting/quoting/shop.py

@@ -0,0 +1,193 @@
+"""Read the shop's own context out of ``shop/*.md``.
+
+The shop files are markdown for the agent (prose, judgement, house rules) with one fenced
+JSON block per file for the code::
+
+    ```json machines
+    {"machines": [...]}
+    ```
+
+Prose and block are the same source of truth, kept side by side deliberately: the agent needs
+the reasoning, the cost model needs the numbers, and splitting them into a separate config file
+is how the two drift apart.
+
+Only the fenced blocks are parsed. The block's name is the word after ``json`` on the opening
+fence; everything else in the file is ignored by the code and read by the agent.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+SHOP_DIR = Path(__file__).resolve().parents[1] / "shop"
+
+# Defaults for the lessons.md calibration block. Every key here is a knob the review-and-learn
+# loop is allowed to move; anything not in this dict is a typo, not a new knob (load() says so).
+EXAMPLE_SHOP_NAME = "Feldmann Formenbau & Spritzguss GmbH"
+
+CALIBRATION_DEFAULTS: dict[str, Any] = {
+    "clamp_safety_factor": 1.25,
+    "use_simulated_clamp_pressure": True,
+    "sim_peak_to_mean_pressure": 0.50,
+    "cooling_time_factor": 1.00,
+    "pack_time_s_per_mm_wall": 2.0,
+    "cycle_time_factor": 1.00,
+    "complexity_bonus": 0.0,
+    "tooling_price_factor": 1.00,
+    "piece_price_factor": 1.00,
+}
+
+# file stem -> the block names expected in it
+_BLOCKS = {
+    "shop-profile": ["shop"],
+    "machines": ["machines", "cycle"],
+    "materials": ["materials"],
+    "tooling": ["tooling"],
+    "commercial": ["commercial"],
+    "lessons": ["calibration"],
+}
+
+
+def read_block(md_path: Path, name: str) -> dict:
+    """Parse the ```` ```json <name> ```` fenced block out of a markdown file."""
+    text = Path(md_path).read_text(encoding="utf-8")
+    pat = re.compile(r"^```json[ \t]+" + re.escape(name) + r"[ \t]*\r?\n(.*?)^```", re.S | re.M)
+    m = pat.search(text)
+    if not m:
+        raise ValueError(f"{md_path.name}: no ```json {name} block found")
+    try:
+        return json.loads(m.group(1))
+    except json.JSONDecodeError as exc:
+        raise ValueError(f"{md_path.name}: the '{name}' block is not valid JSON — {exc}") from exc
+
+
+def write_block(md_path: Path, name: str, data: dict) -> None:
+    """Replace a fenced JSON block in place, keeping the surrounding prose untouched."""
+    path = Path(md_path)
+    text = path.read_text(encoding="utf-8")
+    body = json.dumps(data, indent=2, ensure_ascii=False)
+    pat = re.compile(r"(^```json[ \t]+" + re.escape(name) + r"[ \t]*\r?\n)(.*?)(^```)", re.S | re.M)
+    if not pat.search(text):
+        raise ValueError(f"{md_path.name}: no ```json {name} block found")
+    path.write_text(pat.sub(lambda m: m.group(1) + body + "\n" + m.group(3), text, count=1), encoding="utf-8")
+
+
+@dataclass
+class ShopContext:
+    """Everything the quote needs to know about this shop."""
+
+    root: Path
+    shop: dict
+    machines: dict
+    cycle: dict
+    materials: dict
+    tooling: dict
+    commercial: dict
+    calibration: dict[str, Any]
+    sources: list[Path]
+
+    # -- lookups ------------------------------------------------------------
+    def cal(self, key: str) -> Any:
+        """A calibration value (lessons.md), falling back to the shipped default."""
+        return self.calibration.get(key, CALIBRATION_DEFAULTS[key])
+
+    def grades(self) -> list[dict]:
+        return list(self.materials.get("grades", []))
+
+    def find_grade(self, name: str | None) -> dict:
+        """Resolve a house grade by name (exact, then partial); default grade if None."""
+        grades = self.grades()
+        if not grades:
+            raise ValueError("shop/materials.md lists no grades")
+        if not name:
+            name = self.materials.get("default_grade") or grades[0]["name"]
+        low = name.lower()
+        for g in grades:
+            if g["name"].lower() == low:
+                return g
+        partial = [g for g in grades if low in g["name"].lower() or g["name"].lower() in low]
+        if partial:
+            return partial[0]
+        raise ValueError(
+            f"'{name}' is not a house grade. Known: {', '.join(g['name'] for g in grades)}. "
+            "Add it to shop/materials.md (with a price) before quoting it."
+        )
+
+    def volume_ladder(self) -> list[int]:
+        return list(self.shop.get("volume_ladder_parts_per_year", [10000, 50000, 250000]))
+
+    def currency(self) -> str:
+        return str(self.shop.get("currency", "EUR"))
+
+    @property
+    def is_example(self) -> bool:
+        """True while the shop context is still the shipped fictional shop.
+
+        Quoting a real part against invented presses and rates produces a confident, precise,
+        completely wrong number - the worst possible output. Every stage checks this and says so,
+        and it rides in ``quote.json`` as an assumption, until the interview replaces the values and
+        sets ``provenance`` to the real shop's name.
+        """
+        return str(self.shop.get("provenance", "example")).strip().lower() == "example"
+
+    def example_warning(self) -> str:
+        return (
+            "!! shop/ is still the SHIPPED EXAMPLE (a fictional shop): its presses, rates, "
+            "material prices and mould cost model are invented. Any quote from it is a format "
+            "demonstration, not a price. Run `python main.py setup` and work through INTERVIEW.md "
+            "before quoting anything real."
+        )
+
+    def summary(self) -> str:
+        return (
+            f"{self.shop.get('name', 'shop')} - {len(self.machines.get('machines', []))} presses, "
+            f"{len(self.grades())} house grades, {len(self.calibration)} calibration keys "
+            f"(read {len(self.sources)} files from {self.root.name}/)"
+        )
+
+
+def load(root: Path = SHOP_DIR) -> ShopContext:
+    """Load every shop file. Fails loudly — a missing file means an unpriced quote."""
+    root = Path(root)
+    blocks: dict[str, dict] = {}
+    sources: list[Path] = []
+    for stem, names in _BLOCKS.items():
+        path = root / f"{stem}.md"
+        if not path.exists():
+            raise FileNotFoundError(f"missing shop context file: {path}")
+        sources.append(path)
+        for name in names:
+            blocks[name] = read_block(path, name)
+
+    calibration = dict(blocks["calibration"])
+    unknown = sorted(set(calibration) - set(CALIBRATION_DEFAULTS))
+    if unknown:
+        raise ValueError(
+            f"shop/lessons.md calibration has unknown key(s): {', '.join(unknown)}. "
+            f"Known knobs: {', '.join(sorted(CALIBRATION_DEFAULTS))}. "
+            "A knob the cost model doesn't read would silently do nothing."
+        )
+    merged = dict(CALIBRATION_DEFAULTS)
+    merged.update(calibration)
+
+    return ShopContext(
+        root=root,
+        shop=blocks["shop"],
+        machines=blocks["machines"],
+        cycle=blocks["cycle"],
+        materials=blocks["materials"],
+        tooling=blocks["tooling"],
+        commercial=blocks["commercial"],
+        calibration=merged,
+        sources=sources,
+    )
+
+
+if __name__ == "__main__":
+    ctx = load()
+    print(ctx.summary())
+    print("  calibration:", json.dumps(ctx.calibration, indent=2))