engineering-platform 2.2.0__py3-none-any.whl

engineering_platform/host_admin.py

@@ -0,0 +1,199 @@
+"""Server-owned, containment-safe Host Admin observations and mutation gate.
+
+Host Admin never discovers a target from a request, project, checkout, CWD,
+remote, browser, or Finder. Deployments provide an explicit registry; this
+module resolves opaque identifiers from that registry only.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+import re
+import shutil
+import subprocess
+from typing import Iterable
+
+from . import managed_codex_runtime
+from .component_logging import component_logger, log_event
+
+_TARGET_ID = re.compile(r"[a-z][a-z0-9-]{0,63}")
+
+
+class HostAdminTargetError(ValueError):
+    """A requested Host Admin target is absent, stale, or unsafe."""
+
+
+def _resolved(path: Path) -> Path:
+    try:
+        return path.resolve(strict=True)
+    except OSError as error:
+        raise HostAdminTargetError("HOST_ADMIN_TARGET_STALE") from error
+
+
+def _contained(path: Path, root: Path) -> bool:
+    try:
+        path.relative_to(root)
+    except ValueError:
+        return False
+    return True
+
+
+@dataclass(frozen=True)
+class HostAdminTarget:
+    """A deployment-approved Git/worktree boundary, never request-derived."""
+
+    target_id: str
+    containment_root: Path
+    primary_worktree: Path
+    worktrees: tuple[tuple[str, Path], ...] = ()
+
+    def validated(self) -> "HostAdminTarget":
+        if not _TARGET_ID.fullmatch(self.target_id):
+            raise HostAdminTargetError("HOST_ADMIN_TARGET_INVALID")
+        root, primary = _resolved(self.containment_root), _resolved(self.primary_worktree)
+        if not root.is_dir() or not primary.is_dir() or not _contained(primary, root):
+            raise HostAdminTargetError("HOST_ADMIN_TARGET_OUTSIDE_CONTAINMENT")
+        seen: set[str] = set(); approved: list[tuple[str, Path]] = []
+        for worktree_id, worktree in self.worktrees:
+            if not _TARGET_ID.fullmatch(worktree_id) or worktree_id in seen:
+                raise HostAdminTargetError("HOST_ADMIN_WORKTREE_TARGET_INVALID")
+            candidate = _resolved(worktree)
+            if not candidate.is_dir() or not _contained(candidate, root):
+                raise HostAdminTargetError("HOST_ADMIN_WORKTREE_ESCAPE")
+            seen.add(worktree_id); approved.append((worktree_id, candidate))
+        return HostAdminTarget(self.target_id, root, primary, tuple(approved))
+
+
+class HostAdminTargetRegistry:
+    """The only source of mutable Host Admin target identity."""
+
+    def __init__(self, targets: Iterable[HostAdminTarget] = ()) -> None:
+        values = [target.validated() for target in targets]
+        if len({target.target_id for target in values}) != len(values):
+            raise HostAdminTargetError("HOST_ADMIN_TARGET_DUPLICATE")
+        self._targets = {target.target_id: target for target in values}
+
+    def target(self, target_id: object) -> HostAdminTarget:
+        if not isinstance(target_id, str) or target_id not in self._targets:
+            raise HostAdminTargetError("HOST_ADMIN_TARGET_UNKNOWN")
+        return self._targets[target_id].validated()
+
+    def worktree(self, target_id: object, worktree_id: object) -> Path:
+        target = self.target(target_id)
+        if not isinstance(worktree_id, str):
+            raise HostAdminTargetError("HOST_ADMIN_WORKTREE_TARGET_UNKNOWN")
+        for registered_id, path in target.worktrees:
+            if registered_id == worktree_id:
+                return path
+        raise HostAdminTargetError("HOST_ADMIN_WORKTREE_TARGET_UNKNOWN")
+
+
+def installation_root(data_root: Path) -> Path:
+    return data_root.resolve()
+
+
+def registry(_data_root: Path) -> HostAdminTargetRegistry:
+    """Fail closed until deployment provisions explicit targets outside HTTP."""
+    return HostAdminTargetRegistry()
+
+
+def _audit(data_root: Path, event: str, *, target_id: object, outcome: str) -> None:
+    log_event(component_logger(data_root, "ep_server"), 20, event,
+              diagnostic=f"target_id={target_id!r}; outcome={outcome}")
+
+
+def worktree_inventory(targets: HostAdminTargetRegistry, target_id: object) -> dict[str, object]:
+    """Return registered worktrees that Git currently reports, in containment."""
+    target = targets.target(target_id)
+    try:
+        result = subprocess.run(("git", "-C", str(target.primary_worktree), "worktree", "list", "--porcelain"),
+                                check=False, capture_output=True, text=True)
+    except OSError as error:
+        raise HostAdminTargetError("HOST_ADMIN_WORKTREE_INVENTORY_UNAVAILABLE") from error
+    if result.returncode != 0:
+        raise HostAdminTargetError("HOST_ADMIN_WORKTREE_INVENTORY_UNAVAILABLE")
+    observed = {line.split(" ", 1)[1] for line in result.stdout.splitlines() if line.startswith("worktree ")}
+    rows = []
+    for worktree_id, path in target.worktrees:
+        current = _resolved(path)
+        rows.append({"worktree_id": worktree_id, "registered": True,
+                     "present": str(current) in observed,
+                     "primary": current == target.primary_worktree, "path": str(current)})
+    return {"target_id": target.target_id, "worktrees": rows}
+
+
+def diagnose_git_lock(targets: HostAdminTargetRegistry, target_id: object) -> dict[str, object]:
+    """Diagnose exactly the primary index lock; never accept a lock pathname."""
+    target = targets.target(target_id)
+    lock = target.primary_worktree / ".git" / "index.lock"
+    if not lock.parent.is_dir() or not _contained(_resolved(lock.parent), target.containment_root):
+        raise HostAdminTargetError("HOST_ADMIN_GIT_LOCK_AMBIGUOUS")
+    if lock.is_symlink():
+        raise HostAdminTargetError("HOST_ADMIN_GIT_LOCK_ESCAPE")
+    active_owner = False
+    if lock.exists():
+        try:
+            probe = subprocess.run(("lsof", "--", str(lock)), check=False,
+                                   capture_output=True, text=True)
+            active_owner = probe.returncode == 0 and bool(probe.stdout.strip())
+        except OSError:
+            # No owner probe never authorizes a mutation; repair remains
+            # removed, while this bounded diagnostic remains available.
+            active_owner = False
+    return {"target_id": target.target_id, "lock": str(lock), "exists": lock.exists(),
+            "active_owner": active_owner, "repairable": False}
+
+
+def remove_worktree(data_root: Path, targets: HostAdminTargetRegistry,
+                    target_id: object, worktree_id: object) -> dict[str, object]:
+    """Gate legacy removal after registration/inventory checks; deletion is removed."""
+    try:
+        target = targets.target(target_id); worktree = targets.worktree(target_id, worktree_id)
+        inventory = worktree_inventory(targets, target_id)
+        row = next((item for item in inventory["worktrees"] if item["worktree_id"] == worktree_id), None)
+        if not isinstance(row, dict) or not row["present"]:
+            raise HostAdminTargetError("HOST_ADMIN_WORKTREE_TARGET_STALE")
+        if worktree == target.primary_worktree or row["primary"]:
+            raise HostAdminTargetError("HOST_ADMIN_WORKTREE_PRIMARY_PROTECTED")
+        # A dirty worktree is never an administrative cleanup candidate. A
+        # Git index lock is the bounded active-owner signal available without
+        # process discovery; ambiguity fails closed.
+        status = subprocess.run(("git", "-C", str(worktree), "status", "--porcelain"),
+                                check=False, capture_output=True, text=True)
+        if status.returncode != 0:
+            raise HostAdminTargetError("HOST_ADMIN_WORKTREE_STATUS_UNAVAILABLE")
+        if status.stdout.strip():
+            raise HostAdminTargetError("HOST_ADMIN_WORKTREE_DIRTY")
+        if (worktree / ".git" / "index.lock").exists():
+            raise HostAdminTargetError("HOST_ADMIN_WORKTREE_ACTIVE")
+        _audit(data_root, "host_admin_worktree_removal_refused", target_id=target_id, outcome="UNSUPPORTED_REMOVED")
+        return {"outcome": "UNSUPPORTED_REMOVED", "worktree_id": worktree_id}
+    except HostAdminTargetError as error:
+        _audit(data_root, "host_admin_worktree_removal_rejected", target_id=target_id, outcome=str(error))
+        raise
+
+
+def repair_git_lock(data_root: Path, targets: HostAdminTargetRegistry, target_id: object) -> dict[str, object]:
+    """Gate legacy repair after exact diagnosis; arbitrary lock deletion is removed."""
+    try:
+        diagnosis = diagnose_git_lock(targets, target_id)
+        if not diagnosis["exists"]:
+            raise HostAdminTargetError("HOST_ADMIN_GIT_LOCK_ABSENT")
+        if diagnosis["active_owner"]:
+            raise HostAdminTargetError("HOST_ADMIN_GIT_LOCK_ACTIVE")
+        _audit(data_root, "host_admin_git_lock_repair_refused", target_id=target_id, outcome="UNSUPPORTED_REMOVED")
+        return {"outcome": "UNSUPPORTED_REMOVED", "target_id": target_id}
+    except HostAdminTargetError as error:
+        _audit(data_root, "host_admin_git_lock_repair_rejected", target_id=target_id, outcome=str(error))
+        raise
+
+
+def diagnostics(data_root: Path) -> dict[str, object]:
+    root = installation_root(data_root); usage = shutil.disk_usage(root)
+    runtime = managed_codex_runtime.inspect(root)
+    state = runtime.get("state") if isinstance(runtime, dict) else "UNKNOWN"
+    return {"scope": "HOST_ADMIN", "root_kind": "EP_SERVER_INSTALLATION",
+            "disk": {"total_bytes": usage.total, "used_bytes": usage.used, "free_bytes": usage.free},
+            "managed_codex_runtime": {"state": state}, "registered_targets": 0,
+            "mutations_supported": False, "project_authority": False,
+            "execution_authority": False, "queue_authority": False}

engineering_platform/host_preflight.py

@@ -0,0 +1,231 @@
+"""Fail-closed Level 1 health checks for the local Engineering Execution Host.
+
+This module intentionally validates only the host's own configuration, runtime
+and evidence services.  It never inspects a target repository or prompt.
+"""
+
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass
+from datetime import datetime, timezone
+import json
+import os
+from pathlib import Path
+import re
+import shutil
+import sqlite3
+import tempfile
+from time import monotonic
+
+from .component_logging import component_logger
+from .platform_api import PlatformConfiguration, PlatformConfigurationError
+from .platform_version import EngineeringPlatformManifest
+from .storage import open_storage
+from .drift_diagnostics import evidence_for_checks, guidance, persist as persist_drift_evidence
+from .providers import LocalProcessProvider
+
+
+DEFAULT_MINIMUM_FREE_BYTES = 1_073_741_824
+MINIMUM_FREE_BYTES_ENVIRONMENT = "ENGINEERING_PLATFORM_PREFLIGHT_MIN_FREE_BYTES"
+TELEMETRY_ENABLED_ENVIRONMENT = "ENGINEERING_PLATFORM_TELEMETRY_PERSISTENCE"
+
+
+@dataclass(frozen=True)
+class HostPreflightCheck:
+    identifier: str
+    outcome: str
+    reason: str
+    recovery: str
+
+
+@dataclass(frozen=True)
+class HostPreflightResult:
+    outcome: str
+    execution_host: str
+    version: str
+    bootstrap_contract: str
+    runtime_path: str | None
+    runtime_version: str | None
+    timestamp: str
+    duration_ms: int
+    checks: tuple[HostPreflightCheck, ...]
+    drift_evidence: tuple[dict[str, str], ...] = ()
+    resume_guidance: dict[str, object] | None = None
+
+    def payload(self, run_id: str | None = None) -> dict[str, object]:
+        result = asdict(self)
+        result["checks"] = [asdict(check) for check in self.checks]
+        result["run_id"] = run_id
+        return result
+
+
+def _check(identifier: str, passed: bool, reason: str, recovery: str) -> HostPreflightCheck:
+    return HostPreflightCheck(identifier, "PASS" if passed else "FAIL", reason, recovery)
+
+
+_RUNTIME_VERSION = re.compile(r"\d+\.\d+(?:\.\d+)?(?:[-+][0-9A-Za-z.-]+)?")
+
+
+def _runtime_version(output: str) -> str | None:
+    """Keep only the compact version token reported by the managed runtime."""
+    match = _RUNTIME_VERSION.search(output.strip())
+    return match.group(0) if match else None
+
+
+def _minimum_free_bytes() -> int:
+    value = os.environ.get(MINIMUM_FREE_BYTES_ENVIRONMENT, str(DEFAULT_MINIMUM_FREE_BYTES))
+    try:
+        parsed = int(value)
+    except ValueError:
+        return -1
+    return parsed if parsed >= 0 else -1
+
+
+def _telemetry_enabled() -> bool:
+    return os.environ.get(TELEMETRY_ENABLED_ENVIRONMENT, "true").strip().casefold() not in {"0", "false", "no"}
+
+
+def _writable(path: Path) -> bool:
+    if not path.is_dir():
+        return False
+    try:
+        descriptor, temporary = tempfile.mkstemp(prefix=".preflight-", dir=path)
+        os.close(descriptor)
+        Path(temporary).unlink(missing_ok=True)
+        return True
+    except OSError:
+        return False
+
+
+def _persist(root: Path, result: HostPreflightResult, run_id: str | None) -> None:
+    directory = root / ".engineering" / "status"
+    if not directory.is_dir() or not _writable(directory):
+        return
+    payload = json.dumps(result.payload(run_id), separators=(",", ":"), sort_keys=True) + "\n"
+    try:
+        descriptor, temporary = tempfile.mkstemp(prefix=".host-preflight-", dir=directory)
+        with os.fdopen(descriptor, "w", encoding="utf-8") as handle:
+            handle.write(payload)
+            handle.flush()
+            os.fsync(handle.fileno())
+        os.replace(temporary, directory / "host_preflight.json")
+    except OSError:
+        try:
+            Path(temporary).unlink(missing_ok=True)
+        except UnboundLocalError:
+            pass
+
+
+def execute(root: Path, *, run_id: str | None = None) -> HostPreflightResult:
+    """Run Level 1 checks and persist bounded evidence without claiming work."""
+    started = monotonic()
+    timestamp = datetime.now(timezone.utc).isoformat()
+    checks: list[HostPreflightCheck] = []
+    configuration = None
+    try:
+        configuration = PlatformConfiguration.load(root)
+        checks.append(_check("configuration", True, "Required host configuration is readable.", "No action required."))
+    except PlatformConfigurationError:
+        checks.append(_check("configuration", False, "Required host configuration is unavailable.", "Restore a valid Engineering Platform configuration."))
+
+    manifest: EngineeringPlatformManifest | None = None
+    try:
+        manifest = EngineeringPlatformManifest.load(Path(__file__).with_name("ENGINEERING_PLATFORM_VERSION.json"))
+        checks.append(_check("host_identity", True, "Execution Host identity, version and bootstrap contract are available.", "No action required."))
+    except Exception:
+        checks.append(_check("host_identity", False, "Execution Host identity or bootstrap contract is unavailable.", "Restore the Engineering Platform version manifest."))
+
+    directories = (
+        ("status", configuration.resolver(root).resolve_status_store() if configuration else None),
+        ("reports", configuration.resolver(root).resolve_report_store() if configuration else None),
+        ("logs", configuration.resolver(root).resolve_log_store() if configuration else None),
+        ("inbox-processing", configuration.resolver(root).resolve_workspace_store() / "inbox-processing" if configuration else None),
+    )
+    for name, path in directories:
+        path = path if path is not None else root / ".engineering" / name
+        checks.append(_check(f"directory_{name}", path.is_dir(), f"Runtime directory {name} is available." if path.is_dir() else f"Runtime directory {name} is missing.", f"Create and secure .engineering/{name} before accepting work."))
+        if path.is_dir():
+            writable = _writable(path)
+            checks.append(_check(f"writable_{name}", writable, f"Runtime directory {name} is writable." if writable else f"Runtime directory {name} is not writable.", f"Restore write access to .engineering/{name}."))
+
+    threshold = _minimum_free_bytes()
+    if threshold < 0:
+        checks.append(_check("disk_space", False, "Configured free-disk threshold is invalid.", f"Set {MINIMUM_FREE_BYTES_ENVIRONMENT} to a non-negative byte value."))
+    else:
+        free = shutil.disk_usage(root).free
+        checks.append(_check("disk_space", free >= threshold, "Sufficient free disk space is available." if free >= threshold else "Free disk space is below the configured host threshold.", "Free disk space or lower the configured host preflight threshold."))
+
+    runtime_path: str | None = None
+    runtime_version: str | None = None
+    try:
+        executable = str(configuration.resolver(root).resolve_runtime()) if configuration is not None else None
+        runtime_path = executable
+    except PlatformConfigurationError:
+        executable = None
+    checks.append(_check("runtime_executable", bool(executable), "Configured runtime executable is available." if executable else "Configured runtime executable is unavailable.", "Install or expose the Codex CLI on the Execution Host PATH."))
+    if executable:
+        try:
+            invoked = LocalProcessProvider().execute(root, (executable, "--version"))
+            available = invoked.returncode == 0
+            if available:
+                runtime_version = _runtime_version(invoked.stdout)
+        except OSError:
+            available = False
+        checks.append(_check("runtime_invocation", available, "Configured runtime executable is invokable." if available else "Configured runtime executable cannot be invoked.", "Repair the Codex CLI installation before accepting work."))
+
+    if _telemetry_enabled():
+        try:
+            connection = open_storage(root)
+            try:
+                connection.execute("BEGIN IMMEDIATE")
+                connection.rollback()
+            finally:
+                connection.close()
+            checks.append(_check("telemetry_storage", True, "Telemetry SQLite storage is accessible and writable.", "No action required."))
+        except (OSError, sqlite3.DatabaseError, RuntimeError):
+            checks.append(_check("telemetry_storage", False, "Telemetry SQLite storage is unavailable.", "Restore local SQLite evidence storage before accepting work."))
+
+    try:
+        # Preflight has no legacy watcher logger.  File Inbox is the canonical
+        # transport identity when the Server publishes a CENTRAL log binding.
+        component_logger(root, "file_inbox_ingress")
+        checks.append(_check("structured_logging", True, "Structured logging initializes successfully.", "No action required."))
+    except Exception:
+        checks.append(_check("structured_logging", False, "Structured logging cannot initialize.", "Restore the local logging destination before accepting work."))
+
+    outcome = (
+        "FAIL"
+        if any(check.outcome == "FAIL" for check in checks)
+        else "WARNING"
+        if any(check.outcome == "WARNING" for check in checks)
+        else "PASS"
+    )
+    drift_evidence = persist_drift_evidence(root, evidence_for_checks(
+        checks, stage="Execution Host Preflight", repository=str(root.resolve())
+    ))
+    result = HostPreflightResult(
+        outcome,
+        configuration.platform.name if configuration else "Engineering Platform",
+        manifest.platform_version if manifest else "unavailable",
+        manifest.bootstrap_contract if manifest else "unavailable",
+        runtime_path,
+        runtime_version,
+        timestamp,
+        round((monotonic() - started) * 1000),
+        tuple(checks),
+        drift_evidence,
+        guidance(drift_evidence),
+    )
+    _persist(root, result, run_id)
+    return result
+
+
+def latest(root: Path) -> dict[str, object]:
+    """Return only safe, compact preflight evidence for the dashboard/report."""
+    try:
+        payload = json.loads((root / ".engineering" / "status" / "host_preflight.json").read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return {}
+    if not isinstance(payload, dict):
+        return {}
+    return {key: payload[key] for key in ("outcome", "timestamp", "duration_ms", "execution_host", "version", "bootstrap_contract", "runtime_path", "runtime_version", "checks", "drift_evidence", "resume_guidance", "run_id") if key in payload}

engineering_platform/installation_relocation.py

@@ -0,0 +1,122 @@
+"""Crash-safe relocation of the one canonical platform-data directory.
+
+The data root is one unit of persistence. Splitting the database and File
+Inbox across arbitrary folders made a restore impossible to reason about, so
+the legacy per-resource relocation requests are deliberately retired.
+"""
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+from uuid import uuid4
+
+
+class RelocationError(ValueError):
+    """A requested local relocation cannot be safely completed."""
+
+
+_PENDING = "runtime/pending-platform-data-relocation.json"
+
+
+def _directory(value: object) -> Path:
+    if not isinstance(value, str) or not value.strip():
+        raise RelocationError("LOCATION_REQUIRED")
+    path = Path(value).expanduser()
+    if not path.is_absolute() or not path.is_dir() or not os.access(path, os.W_OK | os.X_OK):
+        raise RelocationError("LOCATION_NOT_WRITABLE")
+    return path.resolve()
+
+
+def _write_json_atomically(path: Path, value: dict[str, str]) -> None:
+    path.parent.mkdir(mode=0o700, parents=True, exist_ok=True)
+    candidate = path.with_name(f".{path.name}.{uuid4().hex}")
+    try:
+        candidate.write_text(json.dumps(value, sort_keys=True), encoding="utf-8")
+        candidate.chmod(0o600)
+        os.replace(candidate, path)
+    finally:
+        candidate.unlink(missing_ok=True)
+
+
+def _pending_path(data_root: Path) -> Path:
+    return data_root.resolve() / _PENDING
+
+
+def _destination(root: Path, directory: object) -> Path:
+    parent = _directory(directory)
+    target = parent / root.name
+    if target == root or root in target.parents or target in root.parents:
+        raise RelocationError("PLATFORM_DATA_DESTINATION_INVALID")
+    return target
+
+
+def request(data_root: Path, kind: str, directory: object) -> dict[str, str]:
+    """Persist one whole-platform move for the next clean Server startup."""
+    if kind != "PLATFORM_DATA":
+        raise RelocationError("RELOCATION_KIND_RETIRED")
+    root = data_root.resolve()
+    if not (root / "engineering.db").is_file():
+        raise RelocationError("PLATFORM_DATA_UNAVAILABLE")
+    destination = _destination(root, directory)
+    if destination.exists() and destination.resolve() != root:
+        raise RelocationError("PLATFORM_DATA_DESTINATION_EXISTS")
+    pending = _pending_path(root)
+    if pending.exists():
+        raise RelocationError("RELOCATION_ALREADY_PENDING")
+    _write_json_atomically(pending, {"kind": kind, "directory": str(_directory(directory))})
+    return {"previous": str(root), "value": str(destination)}
+
+
+def relocate_platform_data(data_root: Path, directory: object) -> dict[str, str]:
+    """Move the entire data root, retaining its stable launchd entry path.
+
+    launchd continues to start the stable original path. That path becomes a
+    symlink only after the complete directory rename succeeds, so the DB,
+    inbox, artifacts and configuration never end up on different volumes.
+    """
+    original = Path(data_root).expanduser()
+    root = original.resolve()
+    parent = _directory(directory)
+    # A repeated restart may replay the same request through the stable
+    # launchd symlink.  Recognize that exact completed move before applying
+    # the nested-destination guard below.
+    destination = parent / original.name
+    if original.is_symlink() and destination.exists() and original.resolve() == destination.resolve():
+        return {"previous": str(root), "value": str(destination.resolve())}
+    if destination == root or root in destination.parents or destination in root.parents:
+        raise RelocationError("PLATFORM_DATA_DESTINATION_INVALID")
+    if not root.is_dir() or not (root / "engineering.db").is_file():
+        raise RelocationError("PLATFORM_DATA_UNAVAILABLE")
+    if destination.exists():
+        raise RelocationError("PLATFORM_DATA_DESTINATION_EXISTS")
+    destination.parent.mkdir(mode=0o700, parents=True, exist_ok=True)
+    try:
+        os.replace(root, destination)
+        # A later relocation starts through the stable, already-symlinked
+        # launch path.  Its old link is now dangling and must be replaced.
+        if original.is_symlink():
+            original.unlink()
+        original.symlink_to(destination, target_is_directory=True)
+    except Exception:
+        if destination.exists() and not original.exists():
+            os.replace(destination, original)
+        raise
+    return {"previous": str(root), "value": str(destination.resolve())}
+
+
+def apply_pending(data_root: Path) -> dict[str, str] | None:
+    """Perform a durable whole-directory request before writers are started."""
+    pending = _pending_path(data_root)
+    if not pending.exists():
+        return None
+    try:
+        request_data = json.loads(pending.read_text(encoding="utf-8"))
+        kind, directory = request_data["kind"], request_data["directory"]
+        if kind != "PLATFORM_DATA":
+            raise RelocationError("RELOCATION_KIND_RETIRED")
+        result = relocate_platform_data(data_root, directory)
+    except (KeyError, TypeError, json.JSONDecodeError) as error:
+        raise RelocationError("RELOCATION_REQUEST_INVALID") from error
+    _pending_path(data_root).unlink(missing_ok=True)
+    return {**result, "kind": "PLATFORM_DATA"}

engineering_platform/investigation_ledger.py

@@ -0,0 +1,89 @@
+"""Ephemeral factual-deduplication rules for one primary provider invocation.
+
+The ledger deliberately contains fact identifiers and freshness only.  It never
+accepts source text, paths, command arguments, tool output, conclusions, or
+reviewer advice, and is rendered only into the primary-provider prompt.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+RUN_STABLE = "RUN-STABLE"
+MUTABLE = "MUTABLE"
+BOUNDARY_SENSITIVE = "BOUNDARY-SENSITIVE"
+
+_FACT_FRESHNESS = {
+    "repository_identity": RUN_STABLE,
+    "repository_status": MUTABLE,
+    "git_ancestry": MUTABLE,
+    "pull_request_state": BOUNDARY_SENSITIVE,
+    "source_inspection": MUTABLE,
+    "test_surface": MUTABLE,
+    "validation_surface": BOUNDARY_SENSITIVE,
+    "finalization_state": BOUNDARY_SENSITIVE,
+    "reconciliation_state": BOUNDARY_SENSITIVE,
+}
+
+
+@dataclass(frozen=True)
+class InvocationInvestigationLedger:
+    """A small, non-persistent checklist of facts usable in one invocation."""
+
+    completed: frozenset[str] = frozenset()
+
+    def record(self, *facts: str) -> "InvocationInvestigationLedger":
+        """Record only known fact identifiers after a real narrow check."""
+        unknown = set(facts).difference(_FACT_FRESHNESS)
+        if unknown:
+            raise ValueError("Unknown investigation fact identifier.")
+        return InvocationInvestigationLedger(self.completed.union(facts))
+
+    def reusable(self, fact: str) -> bool:
+        """Return whether the fact is currently established in this invocation."""
+        if fact not in _FACT_FRESHNESS:
+            raise ValueError("Unknown investigation fact identifier.")
+        return fact in self.completed
+
+    def invalidate(self, boundary: str) -> "InvocationInvestigationLedger":
+        """Fail closed at mutation and lifecycle boundaries.
+
+        RUN-STABLE identity remains valid.  Every other fact must be checked
+        again after any boundary that could have changed repository or remote
+        state.  This is intentionally conservative: a caller may always do a
+        real check sooner when freshness is uncertain.
+        """
+        if boundary not in {
+            "repository_mutation",
+            "validation",
+            "pull_request_mutation",
+            "merge",
+            "finalization",
+            "repository_cleanup",
+            "freshness_uncertain",
+        }:
+            raise ValueError("Unknown freshness boundary.")
+        return InvocationInvestigationLedger(
+            frozenset(
+                fact for fact in self.completed if _FACT_FRESHNESS[fact] == RUN_STABLE
+            )
+        )
+
+    def to_prompt_dict(self) -> dict[str, object]:
+        """Return an identifier-only primary prompt projection."""
+        return {
+            "scope": "one_primary_provider_invocation",
+            "persistence": "none",
+            "completed_fact_ids": sorted(self.completed),
+            "fact_freshness": dict(_FACT_FRESHNESS),
+            "invalidating_boundaries": [
+                "repository_mutation",
+                "validation",
+                "pull_request_mutation",
+                "merge",
+                "finalization",
+                "repository_cleanup",
+                "freshness_uncertain",
+            ],
+        }