phase-loop-runtime 0.2.0__py3-none-any.whl

phase_loop_runtime/runtime_paths.py

@@ -0,0 +1,225 @@
+from __future__ import annotations
+
+import subprocess
+import re
+from pathlib import Path
+
+
+PHASE_LOOP_DIRNAME = ".phase-loop"
+LEGACY_PHASE_LOOP_PARENT = ".codex"
+LEGACY_PHASE_LOOP_DIRNAME = "phase-loop"
+EXCLUDE_ENTRIES = (".phase-loop/", ".codex/phase-loop/")
+
+
+def phase_loop_dir(repo: Path) -> Path:
+    return repo / PHASE_LOOP_DIRNAME
+
+
+def legacy_phase_loop_dir(repo: Path) -> Path:
+    return repo / LEGACY_PHASE_LOOP_PARENT / LEGACY_PHASE_LOOP_DIRNAME
+
+
+def phase_loop_read_dir(repo: Path) -> Path:
+    canonical = phase_loop_dir(repo)
+    if canonical.exists():
+        return canonical
+    legacy = legacy_phase_loop_dir(repo)
+    return legacy if legacy.exists() else canonical
+
+
+def phase_loop_read_dirs(repo: Path) -> tuple[Path, ...]:
+    canonical = phase_loop_dir(repo)
+    legacy = legacy_phase_loop_dir(repo)
+    dirs = []
+    if canonical.exists():
+        dirs.append(canonical)
+    if legacy.exists():
+        dirs.append(legacy)
+    return tuple(dirs or (canonical,))
+
+
+def phase_loop_runs_dir(repo: Path) -> Path:
+    return phase_loop_dir(repo) / "runs"
+
+
+def lane_worktree_root(repo: Path, *, workspace_mount: Path | None = None) -> Path:
+    mount = workspace_mount or Path("/mnt/workspace")
+    if mount.exists():
+        return mount / "worktrees"
+    return repo.parent
+
+
+def lane_worktree_path(
+    repo: Path,
+    *,
+    branch: str,
+    lane_id: str,
+    project: str | None = None,
+    workspace_mount: Path | None = None,
+) -> Path:
+    project_slug = _path_slug(project or repo.name)
+    branch_slug = _path_slug(branch)
+    lane_slug = _path_slug(lane_id)
+    return lane_worktree_root(repo, workspace_mount=workspace_mount) / f"{project_slug}-{branch_slug}-{lane_slug}"
+
+
+def phase_loop_runs_dirs(repo: Path) -> tuple[Path, ...]:
+    dirs = tuple(path / "runs" for path in phase_loop_read_dirs(repo))
+    existing = tuple(path for path in dirs if path.exists())
+    return existing or (phase_loop_runs_dir(repo),)
+
+
+def phase_loop_run_context_file(run_root: Path) -> Path:
+    return run_root / "context.md"
+
+
+def phase_loop_claude_bundle_root(run_root: Path) -> Path:
+    return run_root / "claude-bundle"
+
+
+def phase_loop_claude_plugin_dir(run_root: Path) -> Path:
+    return phase_loop_claude_bundle_root(run_root) / "plugin"
+
+
+def phase_loop_claude_settings_file(run_root: Path) -> Path:
+    return phase_loop_claude_bundle_root(run_root) / "settings.json"
+
+
+def phase_loop_claude_agents_file(run_root: Path) -> Path:
+    return phase_loop_claude_bundle_root(run_root) / "agents.json"
+
+
+def phase_loop_claude_mcp_config_file(run_root: Path) -> Path:
+    return phase_loop_claude_bundle_root(run_root) / "mcp.json"
+
+
+def phase_loop_stop_file(repo: Path) -> Path:
+    return phase_loop_dir(repo) / "stop"
+
+
+def phase_loop_stop_files(repo: Path) -> tuple[Path, ...]:
+    canonical = phase_loop_stop_file(repo)
+    legacy = legacy_phase_loop_dir(repo) / "stop"
+    files = [canonical]
+    if legacy.exists():
+        files.append(legacy)
+    return tuple(files)
+
+
+def phase_loop_tui_handoff_file(repo: Path) -> Path:
+    return phase_loop_dir(repo) / "tui-handoff.md"
+
+
+def phase_loop_tui_handoff_read_file(repo: Path) -> Path:
+    canonical = phase_loop_tui_handoff_file(repo)
+    if canonical.exists():
+        return canonical
+    legacy = legacy_phase_loop_dir(repo) / "tui-handoff.md"
+    return legacy if legacy.exists() else canonical
+
+
+def phase_loop_state_file(repo: Path) -> Path:
+    return phase_loop_dir(repo) / "state.json"
+
+
+def phase_loop_executor_degradation_file(repo: Path) -> Path:
+    return phase_loop_dir(repo) / "executor-degradation.json"
+
+
+def phase_loop_state_read_file(repo: Path) -> Path:
+    canonical = phase_loop_state_file(repo)
+    if canonical.exists():
+        return canonical
+    legacy = legacy_phase_loop_dir(repo) / "state.json"
+    return legacy if legacy.exists() else canonical
+
+
+def phase_loop_event_file(repo: Path) -> Path:
+    return phase_loop_dir(repo) / "events.jsonl"
+
+
+def phase_loop_event_read_files(repo: Path) -> tuple[Path, ...]:
+    legacy = legacy_phase_loop_dir(repo) / "events.jsonl"
+    canonical = phase_loop_event_file(repo)
+    if canonical.exists():
+        return (canonical,)
+    if legacy.exists():
+        return (legacy,)
+    return (canonical,)
+
+
+def phase_loop_fleet_metrics_file(repo: Path) -> Path:
+    """Append-only sibling ledger for CS-2.1 SA fleet-metric events.
+
+    Kept as a SEPARATE file from ``events.jsonl`` so the existing event ledger's
+    bytes and reconcile/fold semantics are provably untouched by this additive
+    observability slice. Enforcement-owned (inside ``.phase-loop/``); the Portal
+    wall forbids Portal from ever reading it — the sanitized aggregates are
+    PUSHED to Portal, never pulled.
+    """
+    return phase_loop_dir(repo) / "fleet-metrics.jsonl"
+
+
+def phase_loop_fleet_metrics_read_files(repo: Path) -> tuple[Path, ...]:
+    canonical = phase_loop_fleet_metrics_file(repo)
+    legacy = legacy_phase_loop_dir(repo) / "fleet-metrics.jsonl"
+    if canonical.exists():
+        return (canonical,)
+    if legacy.exists():
+        return (legacy,)
+    return (canonical,)
+
+
+def phase_loop_active_loop_file(repo: Path) -> Path:
+    return phase_loop_dir(repo) / "active-loop.json"
+
+
+def phase_loop_active_loop_read_files(repo: Path) -> tuple[Path, ...]:
+    canonical = phase_loop_active_loop_file(repo)
+    legacy = legacy_phase_loop_dir(repo) / "active-loop.json"
+    if canonical.exists():
+        return (canonical,)
+    if legacy.exists():
+        return (legacy,)
+    return (canonical,)
+
+
+def git_info_exclude(repo: Path) -> Path | None:
+    try:
+        path_text = subprocess.check_output(
+            ["git", "-C", str(repo), "rev-parse", "--git-path", "info/exclude"],
+            text=True,
+            stderr=subprocess.DEVNULL,
+        ).strip()
+    except Exception:
+        return None
+    if not path_text:
+        return None
+    path = Path(path_text)
+    if not path.is_absolute():
+        path = repo / path
+    return path
+
+
+def ensure_phase_loop_excluded(repo: Path) -> None:
+    exclude = git_info_exclude(repo)
+    if exclude is None:
+        return
+    try:
+        exclude.parent.mkdir(parents=True, exist_ok=True)
+        text = exclude.read_text() if exclude.exists() else ""
+        existing = {line.strip() for line in text.splitlines()}
+        missing = [entry for entry in EXCLUDE_ENTRIES if entry not in existing]
+        if not missing:
+            return
+        prefix = "" if not text or text.endswith("\n") else "\n"
+        with exclude.open("a", encoding="utf-8") as handle:
+            handle.write(prefix + "\n".join(missing) + "\n")
+    except OSError:
+        return
+
+
+def _path_slug(value: str) -> str:
+    slug = re.sub(r"[^A-Za-z0-9._-]+", "-", value.strip())
+    slug = re.sub(r"-+", "-", slug).strip("-._")
+    return slug or "unknown"

phase_loop_runtime/runtime_projection.py

@@ -0,0 +1,113 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+from . import __version__
+from .baml_modular import parse_baml_response
+from .events import read_events
+from .install_status import build_install_status
+from .models import PIPELINE_MODE_LITERALS, StateSnapshot, require_literal, utc_now
+from .plan_manifest import read_manifest
+from .reconcile import reconcile
+from .skill_paths import current_harness
+
+
+def build_runtime_projection(
+    repo: Path,
+    roadmap: Path,
+    snapshot: StateSnapshot | None = None,
+    pipeline_mode: str = "standalone",
+) -> dict[str, object]:
+    require_literal(pipeline_mode, PIPELINE_MODE_LITERALS, "pipeline mode")
+    resolved = snapshot or reconcile(repo, roadmap)
+    install = build_install_status(repo)
+    plan_activity = _plan_activity(repo)
+    payload: dict[str, object] = {
+        "runtime_version": __version__,
+        "protocol_version": "phase-loop-protocol-v1",
+        "harness": current_harness(),
+        "source_bundle_digest": _source_bundle_digest(repo),
+        "closeout_status": _closeout_status(resolved),
+        "handoff_status": "written" if (repo / ".phase-loop" / "tui-handoff.md").is_file() else "missing",
+        "current_phase_boundary": resolved.current_phase or "none",
+        "last_event_iso": _last_event_iso(repo) or resolved.timestamp or utc_now(),
+        "plans_in_flight": plan_activity["plans_in_flight"],
+        "plans_executing": plan_activity["plans_executing"],
+        "last_plan_event_iso": plan_activity["last_plan_event_iso"],
+        "install_status": str(install.get("summary") or "unknown"),
+        "gitignore_init_status": _gitignore_init_status(repo),
+        "operating_mode": pipeline_mode,
+    }
+    _assert_redacted(payload)
+    parse_baml_response("DotfilesRuntimeProjection", json.dumps(payload))
+    return payload
+
+
+def _source_bundle_digest(repo: Path) -> str:
+    for event in reversed(read_events(repo)):
+        metadata = event.get("metadata")
+        if not isinstance(metadata, dict):
+            continue
+        bundle = metadata.get("pipeline_source_bundle")
+        if isinstance(bundle, dict) and isinstance(bundle.get("sha256"), str) and bundle["sha256"]:
+            return f"sha256:{bundle['sha256']}"
+    return "none"
+
+
+def _closeout_status(snapshot: StateSnapshot) -> str:
+    if snapshot.closeout_terminal_status:
+        return snapshot.closeout_terminal_status
+    if isinstance(snapshot.terminal_summary, dict):
+        status = snapshot.terminal_summary.get("terminal_status")
+        if isinstance(status, str) and status:
+            return status
+    if snapshot.current_phase and snapshot.current_phase in snapshot.phases:
+        return snapshot.phases[snapshot.current_phase]
+    return "unknown"
+
+
+def _last_event_iso(repo: Path) -> str | None:
+    events = read_events(repo)
+    if not events:
+        return None
+    timestamp = events[-1].get("timestamp")
+    return str(timestamp) if timestamp else None
+
+
+def _plan_activity(repo: Path) -> dict[str, object]:
+    try:
+        manifest = read_manifest(repo)
+    except (OSError, ValueError):
+        return {"plans_in_flight": 0, "plans_executing": [], "last_plan_event_iso": "none"}
+    in_flight_statuses = {"committed", "executing"}
+    plans_in_flight = sum(1 for entry in manifest.plans if entry.status in in_flight_statuses)
+    plans_executing = sorted(entry.slug for entry in manifest.plans if entry.status == "executing")
+    lifecycle_timestamps: list[str] = []
+    updated_timestamps: list[str] = []
+    for entry in manifest.plans:
+        lifecycle_timestamps.extend(event.at for event in entry.lifecycle if event.at)
+        if entry.updated_at:
+            updated_timestamps.append(entry.updated_at)
+    return {
+        "plans_in_flight": plans_in_flight,
+        "plans_executing": plans_executing,
+        "last_plan_event_iso": max(lifecycle_timestamps) if lifecycle_timestamps else max(updated_timestamps, default="none"),
+    }
+
+
+def _gitignore_init_status(repo: Path) -> str:
+    gitignore = repo / ".gitignore"
+    if not gitignore.is_file():
+        return "missing"
+    lines = gitignore.read_text(encoding="utf-8").splitlines()
+    return "present" if "/.dev-skills/" in lines or ".dev-skills/" in lines else "missing"
+
+
+def _assert_redacted(payload: dict[str, Any]) -> None:
+    serialized = json.dumps(payload, sort_keys=True)
+    forbidden = ("/home/", "/Users/", "/mnt/", "op://", "sk-", "AKIA", "ghp_")
+    leaked = [token for token in forbidden if token in serialized]
+    if leaked:
+        raise ValueError(f"runtime projection contains forbidden metadata token: {leaked[0]}")

phase_loop_runtime/runtime_resources.py

@@ -0,0 +1,36 @@
+"""Locate package-data shipped inside the ``phase_loop_runtime`` wheel.
+
+Single home for the ``importlib.resources`` wheel-anchor idiom that was triplicated
+across ``baml_modular``/``schema_export``/``skill_inventory`` (#12 CR). Returns a real
+on-disk ``Path``.
+
+Limitation (consistent with the prior per-module helpers): under a zip-imported app
+(PEX/shiv/zipapp) ``importlib.resources.files`` yields a non-filesystem ``Traversable``
+whose ``str()`` is not a real directory, so these return ``None``. ``pip install``
+(extracted ``site-packages``) is the supported mode.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+
+def package_root() -> Path | None:
+    """The extracted on-disk root of the installed ``phase_loop_runtime`` package, or
+    ``None`` when it can't be resolved to a real directory."""
+    try:
+        import importlib.resources
+
+        root = Path(str(importlib.resources.files("phase_loop_runtime")))
+    except (ModuleNotFoundError, TypeError, FileNotFoundError):
+        return None
+    return root if root.is_dir() else None
+
+
+def packaged_resource_dir(name: str) -> Path | None:
+    """A package-data subdirectory shipped in the wheel (e.g. ``"skills_bundle"``), or
+    ``None`` if the package root or the subdirectory is unavailable."""
+    root = package_root()
+    if root is None:
+        return None
+    candidate = root / name
+    return candidate if candidate.is_dir() else None

phase_loop_runtime/schema_export.py

@@ -0,0 +1,292 @@
+"""Canonical phase-loop closeout schema export (SCHEMA SL-1).
+
+The ONE canonical closeout shape is the nested :class:`PhaseLoopCloseout`
+dataclass (``models.py``). This module *derives* a declared JSON-Schema and a flat
+field-list FROM that dataclass — walking ``dataclasses.fields`` +
+``typing.get_type_hints`` and RECURSING into the nested sub-dataclasses
+(``PhaseLoopAutomation``/``Artifacts``/``Verification``/``Blocker``/``SourceBundle``/
+``SourceTruthImpact``/``SpecDeltaCloseout``). Scalar types, nested required-sets,
+nullable unions, and enums all come from the dataclass, so "single source of
+truth" is real: a dataclass change that isn't regenerated fails ``--check`` and the
+committed-artifact drift test.
+
+The generated artifact is committed at ``schemas/phase_loop_closeout.schema.json``
+and bundled as package-data; :func:`canonical_schema` resolves it via
+``importlib.resources`` (the post-DECOUPLE pattern, mirroring ``baml_modular``)
+so the bundled-artifact path works from a wheel-installed venv. :func:`check`
+builds the canonical schema *fresh* from the live dataclass, so a stale committed
+artifact cannot mask drift.
+
+``required`` semantics: a field is optional iff its resolved annotation is a union
+containing ``None`` AND it is not part of the closeout validator's mandatory set.
+The runtime's malformed-closeout validator (``closeout.py``) is the ground truth for
+the top-level required set; this module exposes that set as the single source the
+validator consumes, killing the duplicate hand-maintained tuple.
+
+Generation is deterministic (sorted keys, explicitly sorted lists, no volatile
+content) so the byte-stable artifact is a meaningful parity baseline.
+"""
+
+from __future__ import annotations
+
+import dataclasses
+import importlib.resources
+import json
+import types
+import typing
+from pathlib import Path
+from typing import Any
+
+from .models import (
+    PIPELINE_CLOSEOUT_OUTCOMES,
+    PIPELINE_CLOSEOUT_SCHEMA,
+    PhaseLoopCloseout,
+)
+
+#: Repo-relative location of the committed/bundled artifact (resolved via
+#: importlib.resources at runtime; this constant is for docs/diagnostics).
+SCHEMA_RESOURCE = "schemas/phase_loop_closeout.schema.json"
+
+#: Static provenance recorded INSIDE the JSON (never a // comment — the artifact
+#: must remain valid JSON for json.load + --check). No timestamps/abs paths so it
+#: stays byte-stable and metadata_only.
+_PROVENANCE = (
+    "GENERATED from phase_loop_runtime.models.PhaseLoopCloseout by "
+    "`phase-loop export-schema`. Do not hand-edit; regenerate instead."
+)
+
+#: The top-level closeout fields the runtime's malformed-closeout validator
+#: requires present-and-non-null (closeout.py:phase_loop_closeout_diagnostic).
+#: `schema` is validated separately (it is a fixed literal), and
+#: `spec_delta_closeout` is genuinely optional, so neither appears here. This is
+#: the SINGLE SOURCE the validator consumes — do not maintain a second copy.
+CLOSEOUT_REQUIRED_NESTED_FIELDS: tuple[str, ...] = (
+    "phase",
+    "terminal_status",
+    "automation",
+    "artifacts",
+    "verification",
+    "blocker",
+    "source_bundle",
+    "source_truth_impact",
+)
+
+
+def _strip_optional(annotation: Any) -> tuple[Any, bool]:
+    """Return ``(inner_type, is_optional)`` for a possibly-``X | None`` annotation."""
+    origin = typing.get_origin(annotation)
+    if origin in (typing.Union, types.UnionType):
+        args = tuple(a for a in typing.get_args(annotation) if a is not type(None))
+        is_optional = len(args) != len(typing.get_args(annotation))
+        inner = args[0] if len(args) == 1 else annotation
+        return inner, is_optional
+    return annotation, False
+
+
+def _scalar_schema(tp: Any) -> dict[str, Any] | None:
+    """Map a scalar Python type to its JSON-Schema type, else ``None``."""
+    # bool is a subclass of int — check it first.
+    if tp is bool:
+        return {"type": "boolean"}
+    if tp is int:
+        return {"type": "integer"}
+    if tp is float:
+        return {"type": "number"}
+    if tp is str:
+        return {"type": "string"}
+    return None
+
+
+def _annotation_schema(annotation: Any) -> dict[str, Any]:
+    """Derive a JSON-Schema fragment from a (non-optional) resolved annotation."""
+    inner, _ = _strip_optional(annotation)
+    origin = typing.get_origin(inner)
+    scalar = _scalar_schema(inner)
+    if scalar is not None:
+        return scalar
+    if dataclasses.is_dataclass(inner):
+        return _dataclass_schema(inner)
+    if origin in (tuple, list):
+        args = typing.get_args(inner)
+        # tuple[X, ...] / list[X]; freeform `dict[..., Any]` items collapse to object.
+        item = args[0] if args else Any
+        item_inner, _ = _strip_optional(item)
+        if dataclasses.is_dataclass(item_inner):
+            return {"type": "array", "items": _dataclass_schema(item_inner)}
+        item_scalar = _scalar_schema(item_inner)
+        if item_scalar is not None:
+            return {"type": "array", "items": item_scalar}
+        return {"type": "array", "items": {"type": "object"}}
+    if origin is dict:
+        return {"type": "object"}
+    # Any / unrecognised -> permissive object (don't over-specify freeform shapes).
+    return {"type": "object"}
+
+
+def _dataclass_schema(cls: Any) -> dict[str, Any]:
+    """Recursively build a JSON-Schema `object` for a dataclass.
+
+    A nested field is treated as required iff its annotation is NOT a
+    union-with-None — a conservative contract convention. (It is not a guarantee of
+    presence in every emitted instance: a few fields with custom `to_json` `or None`
+    emit logic, e.g. an empty `protected_sources` tuple, may be absent in practice.
+    Nothing validates live instances against this artifact, so the convention is the
+    declared shape, not an instance invariant.) Nullable fields get a
+    `["...","null"]` union type and are excluded from `required`.
+    """
+    hints = typing.get_type_hints(cls)
+    properties: dict[str, dict[str, Any]] = {}
+    required: list[str] = []
+    for fld in dataclasses.fields(cls):
+        annotation = hints[fld.name]
+        _, is_optional = _strip_optional(annotation)
+        prop = _annotation_schema(annotation)
+        if is_optional:
+            base_type = prop.get("type", "object")
+            if isinstance(base_type, str):
+                prop = {**prop, "type": [base_type, "null"]}
+        else:
+            required.append(fld.name)
+        properties[fld.name] = prop
+    return {
+        "type": "object",
+        "additionalProperties": False,
+        "required": sorted(required),
+        "properties": {name: properties[name] for name in sorted(properties)},
+    }
+
+
+def field_names() -> tuple[str, ...]:
+    """The declared field set of :class:`PhaseLoopCloseout`, in declaration order."""
+    return tuple(f.name for f in dataclasses.fields(PhaseLoopCloseout))
+
+
+def required_closeout_fields() -> tuple[str, ...]:
+    """Single source for the closeout validator's mandatory nested fields.
+
+    Consumed by ``closeout.py``'s malformed-closeout diagnostic so the required
+    set is not maintained in two places.
+    """
+    return CLOSEOUT_REQUIRED_NESTED_FIELDS
+
+
+def _top_level_property(name: str, annotation: Any) -> dict[str, Any]:
+    """Property entry for a top-level closeout field (with closeout-specific consts).
+
+    A top-level field is null-allowed only when it is BOTH annotated nullable AND
+    not in the validator's mandatory set. ``source_truth_impact`` is annotated
+    ``... | None`` (the builder always populates it) but the validator requires it
+    present-and-non-null, so it stays non-null here — matching what consumers
+    actually enforce.
+    """
+    if name == "schema":
+        return {"type": "string", "const": PIPELINE_CLOSEOUT_SCHEMA}
+    if name == "terminal_status":
+        return {"type": "string", "enum": sorted(PIPELINE_CLOSEOUT_OUTCOMES)}
+    _, is_optional = _strip_optional(annotation)
+    prop = _annotation_schema(annotation)
+    null_allowed = is_optional and name not in CLOSEOUT_REQUIRED_NESTED_FIELDS
+    if null_allowed:
+        base_type = prop.get("type", "object")
+        if isinstance(base_type, str):
+            prop = {**prop, "type": [base_type, "null"]}
+    return prop
+
+
+def build_schema() -> dict[str, Any]:
+    """Build the canonical JSON-Schema FROM the dataclass (single source of truth)."""
+    hints = typing.get_type_hints(PhaseLoopCloseout)
+    fields = dataclasses.fields(PhaseLoopCloseout)
+    properties = {f.name: _top_level_property(f.name, hints[f.name]) for f in fields}
+    # Required = the validator's mandatory nested fields + the `schema` literal.
+    # `spec_delta_closeout` is the only genuinely optional top-level field.
+    required = sorted({*CLOSEOUT_REQUIRED_NESTED_FIELDS, "schema"})
+    return {
+        "$schema": "https://json-schema.org/draft/2020-12/schema",
+        "$id": PIPELINE_CLOSEOUT_SCHEMA,
+        "title": "phase_loop_closeout",
+        "$comment": _PROVENANCE,
+        "type": "object",
+        "required": required,
+        "additionalProperties": False,
+        "properties": {name: properties[name] for name in sorted(properties)},
+    }
+
+
+def build_field_list() -> dict[str, Any]:
+    """Build the flat field-list payload gp consumes (all declared fields)."""
+    return {
+        "schema_id": PIPELINE_CLOSEOUT_SCHEMA,
+        "source": "phase_loop_runtime.models.PhaseLoopCloseout",
+        "fields": sorted(field_names()),
+        "required": sorted({*CLOSEOUT_REQUIRED_NESTED_FIELDS, "schema"}),
+    }
+
+
+def render(schema: dict[str, Any]) -> str:
+    """Deterministic serialization: sorted keys, trailing newline, no volatile data."""
+    return json.dumps(schema, indent=2, sort_keys=True) + "\n"
+
+
+def _resource_path() -> Path:
+    """Resolve the bundled artifact via importlib.resources (wheel-safe)."""
+    from .runtime_resources import package_root
+
+    root = package_root()
+    if root is not None:
+        packaged = root / SCHEMA_RESOURCE
+        if packaged.is_file():
+            return packaged
+    # Editable/source-layout fallback (same dir importlib.resources resolves once
+    # installed from a wheel).
+    fallback = Path(__file__).resolve().parent / SCHEMA_RESOURCE
+    if fallback.is_file():
+        return fallback
+    raise FileNotFoundError(
+        f"bundled closeout schema not found ({SCHEMA_RESOURCE}); regenerate via "
+        "`phase-loop export-schema --output <artifact>`"
+    )
+
+
+def canonical_schema() -> dict[str, Any]:
+    """Load the bundled canonical schema artifact (the in-package, wheel-resolved copy)."""
+    return json.loads(_resource_path().read_text(encoding="utf-8"))
+
+
+def _diff_json(canonical: Any, supplied: Any, path: str = "") -> list[str]:
+    """Recursively diff two JSON values, naming the actual differing paths."""
+    if isinstance(canonical, dict) and isinstance(supplied, dict):
+        diffs: list[str] = []
+        for key in sorted(set(canonical) | set(supplied)):
+            here = f"{path}.{key}" if path else key
+            if key not in supplied:
+                diffs.append(f"{here}: missing (canonical={canonical[key]!r})")
+            elif key not in canonical:
+                diffs.append(f"{here}: unexpected (supplied={supplied[key]!r})")
+            else:
+                diffs.extend(_diff_json(canonical[key], supplied[key], here))
+        return diffs
+    if isinstance(canonical, list) and isinstance(supplied, list):
+        if canonical != supplied:
+            return [f"{path or '<root>'}: list differs (canonical={canonical!r} supplied={supplied!r})"]
+        return []
+    if canonical != supplied:
+        return [f"{path or '<root>'}: canonical={canonical!r} supplied={supplied!r}"]
+    return []
+
+
+def check(path: Path) -> list[str]:
+    """Compare a supplied artifact against the canonical schema built FRESH from the
+    live dataclass.
+
+    Building fresh (not loading the committed artifact) means a stale committed
+    artifact cannot mask a dataclass change — ``--check`` fails on any divergence
+    between the supplied artifact and the current dataclass-derived shape. Returns a
+    list of human-readable diffs naming the differing fields; empty means parity.
+    """
+    canonical = build_schema()
+    try:
+        supplied = json.loads(Path(path).read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as exc:
+        return [f"could not read/parse supplied artifact: {exc}"]
+    return _diff_json(canonical, supplied)