simcon-toolkit 0.1.0__py3-none-any.whl

simcon_toolkit/_kit/templates/process-window/process_window/guardrails.py

@@ -0,0 +1,153 @@
+"""Guardrail enforcement. These raise; they are not warnings.
+
+The brief asks for a lint that **fails the run** if an absolute pressure threshold appears in a
+screening criterion. The reason is specific and quantitative: on multi-gate parts the AI solver
+under-predicts absolute cavity pressure by roughly a factor of three (~0.3x measured on an
+8-gate part). This campaign models 1 of a real 32 cavities. A criterion of the form
+`p80 < 250 bar` is therefore comparing a number known to be wrong against a number believed to
+be right — it will happily pass or fail points for reasons that have nothing to do with the
+mould.
+
+Ranks, ratios and comparisons survive that bias because a monotone distortion preserves
+ordering. So the rule is not "be careful with pressure", it is "pressure may only ever be
+*compared*, never *thresholded*", and a comment cannot enforce that.
+
+Note the deliberate exception: a **machine limit** (1500 bar, 1000 kN) is a constraint, not a
+criterion. It may annotate the final recommendation, where it is tagged `absolute: true` and
+carries the caveats. `check_absolute_claim_has_caveats` enforces that side.
+"""
+
+from __future__ import annotations
+
+import re
+
+# Units that carry an absolute pressure scale. Dimensionless ratios and rank fractions do not.
+_PRESSURE_UNITS = r"(?:bar|mbar|kpa|mpa|psi|pa)\b"
+
+# A number next to a pressure unit, e.g. "250 bar", "1.5e7 Pa", "p80<250bar".
+_ABS_PRESSURE = re.compile(rf"\d+(?:\.\d+)?(?:[eE][+-]?\d+)?\s*{_PRESSURE_UNITS}", re.I)
+
+# A comparison against a bare number involving a pressure-named quantity, e.g. "p80 <= 250",
+# "max_pressure_bar > 300". Catches the case where the unit is in the variable name instead.
+_PRESSURE_NAME = r"(?:p80|p_?max|peak_?pressure|max_?pressure|cavity_?pressure|pressure)"
+_NAMED_CMP = re.compile(rf"{_PRESSURE_NAME}\w*\s*(?:<=|>=|<|>|==)\s*[-+]?\d", re.I)
+
+# Forms that are legitimate because they are relative, not absolute.
+_RELATIVE_OK = re.compile(
+    r"_rank\b|_ratio\b|_pct\b|_percentile\b|_quantile\b|_norm\b|_rel\b|_share\b"
+    r"|rank\(|percentile\(|quantile\(|_z\b",
+    re.I,
+)
+
+# One pressure divided by another is dimensionless, so it is a ratio and permitted — e.g.
+# `p80 / p80_centre < 1.15`. Dividing by an absolute instead (`p80 / 250 bar`) is still caught
+# by _ABS_PRESSURE, so this cannot be used to smuggle a threshold in.
+_PRESSURE_RATIO = re.compile(rf"{_PRESSURE_NAME}\w*\s*/\s*{_PRESSURE_NAME}\w*", re.I)
+
+
+class GuardrailViolation(AssertionError):
+    """A criterion or claim broke a guardrail. Fails the run by design."""
+
+
+def check_criterion(name: str, expression: str) -> None:
+    """Raise if ``expression`` thresholds an absolute pressure.
+
+    Applied to every entry of `acceptance_criteria` before it can filter anything.
+    """
+    expr = str(expression)
+    relative = bool(_RELATIVE_OK.search(expr)) or bool(_PRESSURE_RATIO.search(expr))
+
+    if _ABS_PRESSURE.search(expr):
+        raise GuardrailViolation(
+            f"criterion '{name}' contains an absolute pressure threshold: {expr!r}\n"
+            "  Guardrail 1: the AI solver under-predicts absolute pressure on multi-gate parts "
+            "(~0.3x on 8 gates); this campaign models 1 of 32 cavities with no runner system.\n"
+            "  Use a rank, ratio or comparison instead, e.g. 'p80_rank <= 0.70'."
+        )
+    if _NAMED_CMP.search(expr) and not relative:
+        raise GuardrailViolation(
+            f"criterion '{name}' compares a pressure quantity to a bare number: {expr!r}\n"
+            "  Guardrail 1: pressure may be ordered, never thresholded. If this really is a "
+            "rank or ratio, name it so (…_rank, …_ratio) — the name is the audit trail."
+        )
+
+
+def check_criteria(criteria: list[dict]) -> None:
+    """Lint a whole `acceptance_criteria` list. Raises on the first violation."""
+    for c in criteria:
+        check_criterion(c.get("name", "<unnamed>"), c.get("expression", ""))
+        kind = c.get("kind")
+        if kind not in ("rank", "ratio", "comparison"):
+            raise GuardrailViolation(
+                f"criterion '{c.get('name')}' has kind={kind!r}; guardrail 1 allows only "
+                "'rank', 'ratio' or 'comparison'."
+            )
+        if c.get("absolute"):
+            raise GuardrailViolation(
+                f"criterion '{c.get('name')}' is marked absolute:true. Absolute values may "
+                "annotate the final recommendation but may never screen a point."
+            )
+
+
+def check_absolute_claim_has_caveats(key: str, block: dict) -> None:
+    """The other side of the rule: an absolute-valued claim must carry its caveats.
+
+    Machine limits and any reported pressure in bar are allowed *as annotations*, but only if
+    they state what they rest on. An uncaveated absolute number is how "147 bar is comfortable"
+    escapes into a slide deck without its 1-of-32-cavities asterisk.
+    """
+    if not block.get("absolute"):
+        return
+    if not block.get("caveats"):
+        raise GuardrailViolation(
+            f"'{key}' is marked absolute:true but carries no caveats. Required: the "
+            "multi-gate pressure under-prediction, the 1-of-32-cavities limitation, and the "
+            "absence of any runner system."
+        )
+
+
+def check_noise_floor_derived(floor: dict) -> None:
+    """Guardrail 2: the floor must come from this part, not from the reference campaign."""
+    if not floor:
+        raise GuardrailViolation("no noise floor recorded; guardrail 2 requires one per KPI.")
+    for kpi, d in floor.items():
+        if d.get("basis") != "derived":
+            raise GuardrailViolation(
+                f"noise floor for '{kpi}' has basis={d.get('basis')!r}, expected 'derived'. "
+                "The reference part's +/-1.2 bar / 2 bar figures are part-specific and must "
+                "not be imported."
+            )
+        if not d.get("n_runs"):
+            raise GuardrailViolation(f"noise floor for '{kpi}' records no run count.")
+
+
+def check_forbidden_kpi(criteria: list[dict]) -> None:
+    """Fill-race metrics are measured not to transfer (Spearman 0.10-0.23).
+
+    Allowed as a labelled anomaly detector, never as a screening criterion.
+    """
+    for c in criteria:
+        blob = f"{c.get('name', '')} {c.get('kpi', '')} {c.get('expression', '')}".lower()
+        if "race" in blob or "fill_time_diff" in blob or "filltimediff" in blob:
+            raise GuardrailViolation(
+                f"criterion '{c.get('name')}' screens on a fill-race metric. Measured not to "
+                "transfer (Spearman 0.10-0.23); permitted only as a labelled anomaly detector."
+            )
+
+
+def lint_spec(spec: dict) -> list[str]:
+    """Run every guardrail over a doe_spec dict. Returns the passed checks; raises on failure."""
+    passed = []
+    criteria = spec.get("acceptance_criteria", []) or []
+    check_criteria(criteria)
+    passed.append(f"acceptance_criteria: {len(criteria)} checked, none absolute")
+    check_forbidden_kpi(criteria)
+    passed.append("no fill-race metric used as a screening criterion")
+    check_noise_floor_derived((spec.get("noise_floor") or {}).get("per_kpi", {}))
+    passed.append("noise floor derived per KPI, not imported")
+    for key in ("machine_limits",):
+        blk = (spec.get("provenance") or {}).get(key)
+        if isinstance(blk, dict):
+            check_absolute_claim_has_caveats(key, blk)
+            passed.append(f"{key}: absolute claim carries caveats")
+    return passed

simcon_toolkit/_kit/templates/process-window/process_window/harness.py

@@ -0,0 +1,360 @@
+"""Campaign harness: submit, score, discard, resume.
+
+One object that every stage (epsilon floor, G1 sweep, G3 refinement) drives. What it
+guarantees, and why each one is load-bearing:
+
+**Resume, not restart.** Every run's identity is a deterministic hash of its inputs, so
+"already done" is a file-existence check. Re-running the command picks up exactly where it
+stopped. Assume the session dies mid-sweep — over ~1 000 runs it will.
+
+**Never repeat a configuration.** The solver is deterministic: an identical request returns an
+identical result. So a repeat buys literally nothing — not confidence, not an error bar. The
+run id *is* the config hash, which makes duplicate submission structurally impossible rather
+than merely discouraged.
+
+**Score then discard.** Results are ~29 MB each; 1 024 of them is 30 GB, and the project folder
+is inside OneDrive. Each result is downloaded to a scratch path **outside** OneDrive, scored to
+a ~2 KB json, and deleted — unless it is flagged worth keeping (boundary, anomaly, anchor), in
+which case it is moved into `cache/runs/` deliberately.
+
+**Bounded concurrency with backoff.** The endpoint sheds load; 429/5xx are expected, not
+exceptional. One warm-up request goes out before the fan-out, because a cold model 504s.
+"""
+
+from __future__ import annotations
+
+import concurrent.futures as cf
+import hashlib
+import json
+import os
+import shutil
+import tempfile
+import threading
+import time
+from dataclasses import asdict, dataclass, field
+from datetime import UTC, datetime
+from pathlib import Path
+
+import httpx
+
+from . import kpis as K
+from .units import Process
+
+RETRY_STATUS = (429, 500, 502, 503, 504)
+
+
+@dataclass(frozen=True)
+class RunSpec:
+    """One process point. ``run_id`` is derived, so identity == configuration."""
+
+    melt_C: float
+    wall_C: float
+    flow_cm3_s: float
+    stage: str
+    label: str = ""
+    keep_h5: bool = False
+    meta: dict = field(default_factory=dict)
+    # Hidden-deviation overrides for the feedback loop: what is ACTUALLY submitted may differ
+    # from what the DOE side believes it asked for. Both are part of the run identity, or a
+    # deviated run would collide with its own baseline.
+    material_id_override: str | None = None
+    gates_mm_override: tuple | None = None
+
+    def process(self, volume_cm3: float) -> Process:
+        return Process(melt_C=self.melt_C, wall_C=self.wall_C, flow_cm3_s=self.flow_cm3_s, volume_cm3=volume_cm3)
+
+    def run_id(self, *, geometry_id: str, model_version: str, num_timesteps: int, material_id: str) -> str:
+        """Deterministic id over everything that can change the record.
+
+        Includes geometry and solver settings, not just the process point: the same melt/wall/flow
+        on a different mesh or a different model version is a *different* run, and collapsing them
+        would silently reuse a stale result.
+
+        It also includes ``kpis.KPI_VERSION``, because a record is (inputs -> KPIs). Redefining a
+        KPI changes what the record *means*, so old records must be invalidated rather than reused;
+        without this, adding a KPI would leave every existing run permanently missing it while the
+        resume logic reported them as done.
+
+        ``material_id`` is the campaign's own material, not just the per-run override. Without it,
+        changing the material in the config left every run id unchanged, so the campaign resumed
+        onto the previous material's results and reported them as the new material's.
+        """
+        canon = (
+            f"{self.melt_C:.6f}|{self.wall_C:.6f}|{self.flow_cm3_s:.6f}"
+            f"|{geometry_id}|{model_version}|{num_timesteps}|{K.KPI_VERSION}"
+            f"|{material_id}"
+            f"|{self.material_id_override or '-'}|{self.gates_mm_override or '-'}"
+        )
+        return hashlib.sha1(canon.encode()).hexdigest()[:12]
+
+
+@dataclass
+class RunRecord:
+    run_id: str
+    spec: dict
+    simulation_id: str = ""
+    kpis: dict | None = None
+    h5_kept: str | None = None
+    error: str = ""
+    wall_clock_s: float = 0.0
+    submitted_at: str = ""
+    # Records from superseded KPI definitions stay on disk as history, so every record must say
+    # which definition produced it — otherwise a reader silently mixes incompatible generations.
+    kpi_version: str = ""
+
+    @property
+    def ok(self) -> bool:
+        return self.kpis is not None and not self.error
+
+
+def scratch_root() -> Path:
+    """A download area OUTSIDE OneDrive.
+
+    Downloading 30 GB into a synced folder only to delete it again would push every byte
+    through OneDrive's uploader. The kept results are moved into the project deliberately;
+    the transient ones never touch it.
+    """
+    base = os.environ.get("LOCALAPPDATA") or tempfile.gettempdir()
+    p = Path(base) / "doe_runs_scratch"
+    p.mkdir(parents=True, exist_ok=True)
+    return p
+
+
+class Campaign:
+    """One part + one material + one cloud project; many staged, resumable batches."""
+
+    def __init__(
+        self,
+        *,
+        api,
+        project_id: str,
+        geometry_id: str,
+        material_id: str,
+        volume_cm3: float,
+        card,
+        long_axis: int,
+        gates_mm: list[list[float]],
+        runs_dir: Path,
+        model_version: str,
+        num_timesteps: int,
+        htc_W_m2K: float,
+        switchover_phi: tuple[float, ...],
+        logger=print,
+    ):
+        self.api = api
+        self.project_id = project_id
+        self.geometry_id = geometry_id
+        self.material_id = material_id
+        self.volume_cm3 = volume_cm3
+        self.card = card
+        self.long_axis = long_axis
+        self.gates_mm = gates_mm
+        self.runs_dir = Path(runs_dir)
+        self.model_version = model_version
+        self.num_timesteps = num_timesteps
+        self.htc_W_m2K = htc_W_m2K
+        self.switchover_phi = switchover_phi
+        self.logger = logger
+        self._lock = threading.Lock()
+        self._warm = False
+        self._groups: dict[str, str] = {}
+
+    # -- persistence ---------------------------------------------------------
+    def record_path(self, stage: str, run_id: str) -> Path:
+        return self.runs_dir / stage / f"{run_id}.json"
+
+    def load_record(self, stage: str, run_id: str) -> RunRecord | None:
+        p = self.record_path(stage, run_id)
+        if not p.exists():
+            return None
+        try:
+            d = json.loads(p.read_text())
+        except (OSError, ValueError):
+            return None
+        # A record that failed is not "done" — retry it on the next pass.
+        if d.get("kpis") is None:
+            return None
+        return RunRecord(**d)
+
+    def save_record(self, stage: str, rec: RunRecord) -> None:
+        p = self.record_path(stage, rec.run_id)
+        p.parent.mkdir(parents=True, exist_ok=True)
+        tmp = p.with_suffix(".tmp")
+        tmp.write_text(json.dumps(asdict(rec), indent=2, default=str))
+        tmp.replace(p)  # atomic: a killed process never leaves a half-written record
+
+    # -- cloud ---------------------------------------------------------------
+    def group_for(self, stage: str, description: str = "") -> str:
+        with self._lock:
+            if stage not in self._groups:
+                grp = self.api.create_group(
+                    self.project_id, stage, description=description or f"{stage} (frontloaded DOE POC)"
+                )
+                self._groups[stage] = grp["id"]
+        return self._groups[stage]
+
+    def note(self, text: str) -> None:
+        """Append to the cloud-side decision log; never let it break a run."""
+        try:
+            self.api.add_note(self.project_id, text)
+        except Exception as exc:
+            self.logger(f"    (cloud note skipped: {type(exc).__name__}: {exc})")
+
+    def _submit_with_retry(self, spec: RunSpec, group_id: str, *, attempts: int = 4, backoff: float = 2.0) -> dict:
+        proc = spec.process(self.volume_cm3)
+        last: Exception | None = None
+        for i in range(attempts + 1):
+            try:
+                return self.api.run_filling(
+                    geometry_id=self.geometry_id,
+                    material_id=spec.material_id_override or self.material_id,
+                    gate_positions_mm=(
+                        [list(g) for g in spec.gates_mm_override] if spec.gates_mm_override else self.gates_mm
+                    ),
+                    model_version=self.model_version,
+                    num_timesteps=self.num_timesteps,
+                    htc_W_m2K=self.htc_W_m2K,
+                    label=spec.label or proc.label(),
+                    project_id=self.project_id,
+                    group_id=group_id,
+                    solver_type="ai",
+                    **proc.api_kwargs(),
+                )
+            except httpx.HTTPStatusError as exc:
+                last = exc
+                if exc.response.status_code not in RETRY_STATUS:
+                    raise
+            except (httpx.TimeoutException, httpx.TransportError) as exc:
+                last = exc
+            if i < attempts:
+                time.sleep(backoff * (i + 1))
+        raise last  # type: ignore[misc]
+
+    def warm_up(self, spec: RunSpec) -> None:
+        """One lone request before fanning out — a cold model 504s under a burst."""
+        if self._warm:
+            return
+        self.logger("  warming the model with a single request ...")
+        try:
+            self._run_one(spec, self.group_for(spec.stage))
+        except Exception as exc:
+            self.logger(f"    warm-up failed ({type(exc).__name__}); continuing anyway")
+        self._warm = True
+
+    # -- one run -------------------------------------------------------------
+    def _run_one(self, spec: RunSpec, group_id: str) -> RunRecord:
+        run_id = spec.run_id(
+            geometry_id=self.geometry_id,
+            model_version=self.model_version,
+            num_timesteps=self.num_timesteps,
+            material_id=self.material_id,
+        )
+        rec = RunRecord(
+            run_id=run_id,
+            spec=asdict(spec),
+            submitted_at=datetime.now(UTC).isoformat(),
+            kpi_version=K.KPI_VERSION,
+        )
+        h5 = scratch_root() / f"{run_id}.h5"
+        try:
+            t0 = time.time()
+            res = self._submit_with_retry(spec, group_id)
+            rec.simulation_id = res["simulation_id"]
+            self.api.download_to(res["result"]["download"]["url"], h5)
+            rec.wall_clock_s = round(time.time() - t0, 2)
+
+            proc = spec.process(self.volume_cm3)
+            k = K.extract(
+                h5,
+                melt_K=proc.melt_K,
+                wall_K=proc.wall_K,
+                no_flow_K=self.card.no_flow_K,
+                switchover_phi=self.switchover_phi,
+                long_axis=self.long_axis,
+            )
+            rec.kpis = k.as_dict()
+
+            if spec.keep_h5:
+                dest = self.runs_dir / spec.stage / f"{run_id}.h5"
+                dest.parent.mkdir(parents=True, exist_ok=True)
+                shutil.move(str(h5), str(dest))
+                rec.h5_kept = str(dest.relative_to(self.runs_dir))
+        except Exception as exc:
+            rec.error = f"{type(exc).__name__}: {exc}"
+        finally:
+            h5.unlink(missing_ok=True)  # score-then-discard
+        self.save_record(spec.stage, rec)
+        return rec
+
+    # -- a batch -------------------------------------------------------------
+    def run_batch(
+        self, specs: list[RunSpec], *, stage: str, max_workers: int = 4, description: str = ""
+    ) -> list[RunRecord]:
+        """Run every spec not already recorded. Returns records for the whole batch."""
+        done: list[RunRecord] = []
+        todo: list[RunSpec] = []
+        for s in specs:
+            rid = s.run_id(
+                geometry_id=self.geometry_id,
+                model_version=self.model_version,
+                num_timesteps=self.num_timesteps,
+                material_id=self.material_id,
+            )
+            existing = self.load_record(stage, rid)
+            if existing:
+                done.append(existing)
+            else:
+                todo.append(s)
+
+        self.logger(f"\n  stage '{stage}': {len(specs)} specs -> {len(done)} already done, {len(todo)} to run")
+        if not todo:
+            return done
+
+        group_id = self.group_for(stage, description)
+        self.warm_up(todo[0])
+        # warm_up ran todo[0] and saved its record; skip it in the fan-out.
+        remaining = [
+            s
+            for s in todo
+            if not self.load_record(
+                stage,
+                s.run_id(
+                    geometry_id=self.geometry_id,
+                    model_version=self.model_version,
+                    num_timesteps=self.num_timesteps,
+                    material_id=self.material_id,
+                ),
+            )
+        ]
+
+        results: list[RunRecord] = []
+        t0 = time.time()
+        with cf.ThreadPoolExecutor(max_workers=max(1, min(max_workers, len(remaining) or 1))) as pool:
+            futs = {pool.submit(self._run_one, s, group_id): s for s in remaining}
+            for n, fut in enumerate(cf.as_completed(futs), 1):
+                rec = fut.result()
+                results.append(rec)
+                if rec.ok:
+                    self.logger(
+                        f"    [{n}/{len(remaining)}] {rec.spec['label'] or rec.run_id}  "
+                        f"p80={rec.kpis['p80_bar']}bar  "
+                        f"noflow={rec.kpis['no_flow_margin']}  ({rec.wall_clock_s}s)"
+                    )
+                else:
+                    self.logger(f"    [{n}/{len(remaining)}] {rec.run_id}  FAILED {rec.error}")
+        ok = sum(1 for r in results if r.ok)
+        self.logger(f"  stage '{stage}': {ok}/{len(remaining)} succeeded in {time.time() - t0:.0f}s")
+
+        # Re-read everything so the caller gets one consistent view including the warm-up run.
+        out: list[RunRecord] = []
+        for s in specs:
+            rid = s.run_id(
+                geometry_id=self.geometry_id,
+                model_version=self.model_version,
+                num_timesteps=self.num_timesteps,
+                material_id=self.material_id,
+            )
+            r = self.load_record(stage, rid)
+            if r:
+                out.append(r)
+        return out

simcon_toolkit/_kit/templates/process-window/process_window/identity.py

@@ -0,0 +1,92 @@
+"""Which campaign a part belongs to.
+
+Deliberately free of the licensed SDK and of everything else heavy, for two reasons: it
+is the one thing every stage needs before it can find its own folder, and it is the part
+of the campaign whose failures are silent, so it has to be testable in the lane that
+gates merges.
+"""
+
+from __future__ import annotations
+
+import hashlib
+from functools import cache
+from pathlib import Path
+
+
+def slug(name: str) -> str:
+    return "".join(c if c.isalnum() else "_" for c in str(name).lower()).strip("_")
+
+
+@cache
+def _digest(part: Path, mtime_ns: int, size: int) -> str:
+    """Hash a part's contents. Cached per process; mtime and size keep the cache honest."""
+    h = hashlib.sha256()
+    with part.open("rb") as fh:
+        for chunk in iter(lambda: fh.read(1 << 20), b""):
+            h.update(chunk)
+    return h.hexdigest()[:12]
+
+
+def part_key(part: Path, scale: float = 1.0) -> str:
+    """Cache identity for a part: its name, plus enough of its content to be honest.
+
+    Neither the file name nor the `name:` in the config is an identity. Two customers'
+    parts can both be bracket.stl, and re-exporting a part changes its bytes but not its
+    path — the ordinary working loop here. Keyed on either of those, a campaign reuses the
+    previous part's mesh and uploaded geometry and reports a process window for a part
+    that no longer exists, with nothing anywhere to show that it happened.
+
+    The scale rides along because it changes what the mesh means without touching a byte
+    of the file: meshing at 0.1 and computing a volume at 1.0 disagree silently. It is
+    omitted at 1.0, which is nearly every campaign, so folder names stay readable.
+    """
+    try:
+        st = part.stat()
+    except FileNotFoundError:
+        raise SystemExit(
+            f"part not found: {part}\n"
+            "A campaign is filed under the part it describes, so the file the config's "
+            "`part.stl` names has to be present. Point `part.stl` at your geometry, or "
+            "restore it."
+        ) from None
+    suffix = "" if scale == 1.0 else f"-x{scale:g}"
+    return f"{slug(part.stem)}-{_digest(part, st.st_mtime_ns, st.st_size)}{suffix}"
+
+
+def find_existing_campaign(runs_root: Path, part: Path) -> Path | None:
+    """The campaign folder for a part whose file is gone, when there is exactly one.
+
+    Re-emitting a dossier from a kept `cache/` is a reasonable thing to want on a machine
+    that no longer has the geometry. One match is unambiguous; several are not, and
+    guessing between two versions of the same part is the failure this module exists to
+    prevent, so the caller is told to say which.
+    """
+    if not runs_root.is_dir():
+        return None
+    matches = sorted(d for d in runs_root.glob(f"{slug(part.stem)}-*") if d.is_dir())
+    if len(matches) == 1:
+        return matches[0]
+    if len(matches) > 1:
+        names = "\n  ".join(d.name for d in matches)
+        raise SystemExit(
+            f"part not found: {part}\n"
+            f"Several saved campaigns match that name, so which one you mean is a guess:\n  {names}\n"
+            "Restore the geometry, or point `part.stl` at the version you want."
+        )
+    return None
+
+
+def foreign_campaigns(runs_root: Path, default_key: str | None) -> list[str]:
+    """Saved campaigns that the bundled sample's config does not account for.
+
+    A stage run with no config falls back to the sample's. That is convenient and, once a
+    second campaign exists on disk, it is also a way to score the wrong part in silence:
+    the engineer runs one stage against their own config, then a bare one, and the bare
+    one reads and writes under the sample's key while appearing to continue their work.
+
+    An unknown ``default_key`` — the sample itself is missing, so its key cannot be
+    computed — makes every campaign foreign. Refusing costs a retype; guessing costs a run.
+    """
+    if not runs_root.is_dir():
+        return []
+    return sorted(d.name for d in runs_root.iterdir() if d.is_dir() and d.name != default_key)