"""Local, offline lifecycle for vetted internal-test samples and batches. This module never connects to a cluster, object store, or database. Its records describe prepared artifacts and operator-supplied evidence, not remote state. """ from __future__ import annotations import fcntl import hashlib import json import math import os import re import shutil import stat import subprocess import tempfile from contextlib import contextmanager from datetime import datetime, timezone from pathlib import Path, PurePosixPath OWNER = "droboticflow-internal-test-lane" SEED_SCHEMA = "droboticflow.internal-test-seed/v1" SHA_RE = re.compile(r"^[0-9a-f]{64}$") BATCH_RE = re.compile(r"^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$") KEY_RE = re.compile(r"^[a-z][a-z0-9-]{0,39}$") MEDIA_REQUIRED = {"leftVideo", "rightVideo", "leftPTS", "rightPTS", "imu"} MEDIA_OPTIONAL = {"sourceManifest"} class LaneError(ValueError): """A refused lane operation with a safe, actionable explanation.""" def _canonical(data: object) -> bytes: return (json.dumps(data, sort_keys=True, ensure_ascii=False, separators=(",", ":")) + "\n").encode() def _digest(data: bytes) -> str: return hashlib.sha256(data).hexdigest() def _import_identity(manifest: dict, inventory: dict[str, tuple[str, int]]) -> str: stable_inventory = {path: {"sha256": digest, "size": size} for path, (digest, size) in sorted(inventory.items())} return _digest(_canonical({"manifest": manifest, "inventory": stable_inventory})) def _read_json(path: Path) -> dict: _check_no_symlink(Path(os.path.abspath(path))) try: with path.open("r", encoding="utf-8") as file: value = json.load(file) except (OSError, ValueError) as exc: raise LaneError(f"cannot read JSON at {path}: {exc}") from exc if not isinstance(value, dict): raise LaneError(f"JSON object required at {path}") return value def _read_json_and_hash(path: Path) -> tuple[dict, str]: path = Path(os.path.abspath(path)) _check_no_symlink(path) try: fd = os.open(path, os.O_RDONLY | getattr(os, "O_NOFOLLOW", 0)) with os.fdopen(fd, "rb") as file: info = os.fstat(file.fileno()) if not stat.S_ISREG(info.st_mode) or info.st_size > 10 * 1024 * 1024: raise LaneError("evidence input must be a regular JSON file of at most 10 MiB") contents = file.read() data = json.loads(contents) except (OSError, ValueError) as exc: raise LaneError(f"cannot read evidence JSON at {path}: {exc}") from exc if not isinstance(data, dict): raise LaneError("evidence JSON must be an object") return data, _digest(contents) def _atomic_json(path: Path, value: object) -> None: fd, name = tempfile.mkstemp(prefix=".writing-", dir=path.parent) try: os.fchmod(fd, 0o600) with os.fdopen(fd, "wb") as file: file.write(_canonical(value)) file.flush() os.fsync(file.fileno()) os.replace(name, path) finally: if os.path.exists(name): os.unlink(name) def _check_no_symlink(path: Path) -> None: current = Path(path.anchor) for part in path.parts[1:]: current /= part try: mode = current.lstat().st_mode except FileNotFoundError: continue if stat.S_ISLNK(mode): raise LaneError(f"symlink is forbidden in lane path: {current}") def _safe_relative(raw: object) -> Path: if not isinstance(raw, str) or not raw or "\\" in raw: raise LaneError("asset path must be a nonempty POSIX relative path") pure = PurePosixPath(raw) if pure.is_absolute() or any(part in {"", ".", ".."} for part in raw.split("/")): raise LaneError(f"unsafe asset path: {raw}") if any(part.startswith(".") for part in pure.parts): raise LaneError(f"hidden asset path is forbidden: {raw}") return Path(*pure.parts) def _valid_batch_id(batch_id: object) -> str: if not isinstance(batch_id, str) or len(batch_id) > 32 or not BATCH_RE.fullmatch(batch_id): raise LaneError("batch ID must be lowercase hyphenated, start with a letter, and be <=32 characters") return batch_id def _validate_observed_at(value: object) -> str: if not isinstance(value, str): raise LaneError("evidence observedAt must be an RFC3339 timestamp") try: parsed = datetime.fromisoformat(value.replace("Z", "+00:00")) except ValueError as exc: raise LaneError("evidence observedAt must be an RFC3339 timestamp") from exc if parsed.tzinfo is None or parsed.utcoffset() is None: raise LaneError("evidence observedAt must include a timezone") return value def _hash_file(path: Path) -> tuple[str, int]: _check_no_symlink(path) mode = path.stat().st_mode if not stat.S_ISREG(mode): raise LaneError(f"regular file required: {path}") digest = hashlib.sha256() size = 0 with path.open("rb") as file: while block := file.read(1024 * 1024): digest.update(block) size += len(block) return digest.hexdigest(), size def _validate_bundle(bundle: dict) -> tuple[dict, dict[str, tuple[str, int]]]: if bundle.get("schemaVersion") != SEED_SCHEMA: raise LaneError(f"bundle schemaVersion must be {SEED_SCHEMA}") if set(bundle) != {"schemaVersion", "dictionaries", "samples", "assets"}: raise LaneError("bundle permits only schemaVersion, dictionaries, samples, and assets") samples = bundle.get("samples") if not isinstance(samples, list) or len(samples) != 6: raise LaneError("bundle must contain exactly six samples") counts = {"BLF-data": 0, "SL-data": 0} keys: set[str] = set() refs: set[str] = set() modes: set[str] = set() for sample in samples: if not isinstance(sample, dict): raise LaneError("each sample must be an object") allowed_sample = {"key", "project", "mode", "source", "media", "durationSeconds", "snapshot"} if not set(sample) <= allowed_sample: raise LaneError("unrecognized sample fields are forbidden") key, project, mode = sample.get("key"), sample.get("project"), sample.get("mode") if not isinstance(key, str) or not KEY_RE.fullmatch(key) or key in keys: raise LaneError(f"invalid or duplicate sample key: {key}") keys.add(key) if project not in counts: raise LaneError(f"unapproved sample project: {project}") counts[project] += 1 if mode not in {"scratch", "snapshot"}: raise LaneError(f"invalid sample mode: {mode}") modes.add(mode) source = sample.get("source") if not isinstance(source, dict) or not isinstance(source.get("captureId"), str) or not source["captureId"]: raise LaneError(f"source captureId required for {key}") if not set(source) <= {"captureId", "taskId", "version"}: raise LaneError(f"unrecognized source fields for {key}") media = sample.get("media") if not isinstance(media, dict) or not MEDIA_REQUIRED <= media.keys() or not media.keys() <= MEDIA_REQUIRED | MEDIA_OPTIONAL: raise LaneError(f"five media fields required for {key}; only sourceManifest is optional") for field, raw_path in media.items(): rel = _safe_relative(raw_path) if len(rel.parts) < 3 or rel.parts[:2] != ("templates", key): raise LaneError(f"{key}.{field} must live below templates/{key}/") if rel.as_posix() in refs: raise LaneError(f"asset referenced more than once: {rel}") refs.add(rel.as_posix()) duration = sample.get("durationSeconds") if isinstance(duration, bool) or not isinstance(duration, (int, float)) or not math.isfinite(duration) or not 0 < duration <= 86400: raise LaneError(f"positive durationSeconds required for {key}") if mode == "snapshot" and not isinstance(sample.get("snapshot"), dict): raise LaneError(f"snapshot slices/actions required for {key}") if mode == "scratch" and sample.get("snapshot") is not None: raise LaneError(f"scratch sample cannot carry a snapshot: {key}") if mode == "snapshot" and not set(sample["snapshot"]) <= {"stage", "slices", "actions"}: raise LaneError(f"unrecognized snapshot fields for {key}") if counts != {"BLF-data": 3, "SL-data": 3} or modes != {"scratch", "snapshot"}: raise LaneError("bundle needs three samples per project and both template modes") dictionaries = bundle.get("dictionaries") if not isinstance(dictionaries, dict) or set(dictionaries) != set(counts): raise LaneError("both project dictionary snapshots are required") for project, dictionary in dictionaries.items(): if not isinstance(dictionary, dict) or set(dictionary) != {"sliceNames", "descriptions", "discardReasons"}: raise LaneError(f"dictionary snapshot incomplete for {project}") for entries in dictionary.values(): if not isinstance(entries, list) or not entries or any(not isinstance(entry, str) or not entry.strip() for entry in entries) or len(entries) != len(set(entries)): raise LaneError(f"dictionary entries invalid for {project}") assets = bundle.get("assets") if not isinstance(assets, list): raise LaneError("assets inventory with size and SHA256 is required") inventory: dict[str, tuple[str, int]] = {} for asset in assets: if not isinstance(asset, dict): raise LaneError("asset inventory entries must be objects") if set(asset) != {"path", "sha256", "size"}: raise LaneError("asset entries permit only path, sha256, and size") rel = _safe_relative(asset.get("path")).as_posix() sha, size = asset.get("sha256"), asset.get("size") if rel in inventory or not isinstance(sha, str) or not SHA_RE.fullmatch(sha) or isinstance(size, bool) or not isinstance(size, int) or size <= 0: raise LaneError(f"invalid asset inventory entry: {rel}") inventory[rel] = (sha, size) if set(inventory) != refs: raise LaneError("asset inventory must exactly match sample media references") normalized = {key: value for key, value in bundle.items() if key != "assets"} return normalized, inventory def _safe_tree_files(directory: Path) -> dict[str, tuple[str, int]]: _check_no_symlink(directory) result: dict[str, tuple[str, int]] = {} for parent, dirs, files in os.walk(directory, followlinks=False): for name in dirs: child = Path(parent, name) if not stat.S_ISDIR(child.lstat().st_mode): raise LaneError(f"unsafe directory in batch: {child}") for name in files: child = Path(parent, name) result[child.relative_to(directory).as_posix()] = _hash_file(child) return result def _remove_tree_no_follow(parent: Path, name: str) -> None: """Delete one validated directory using dirfds and O_NOFOLLOW.""" flags = os.O_RDONLY | os.O_DIRECTORY | getattr(os, "O_NOFOLLOW", 0) parent_fd = os.open(parent, flags) try: def visit(fd: int) -> None: with os.scandir(fd) as entries: children = list(entries) for entry in children: info = os.stat(entry.name, dir_fd=fd, follow_symlinks=False) if stat.S_ISDIR(info.st_mode): child_fd = os.open(entry.name, flags, dir_fd=fd) try: visit(child_fd) finally: os.close(child_fd) os.rmdir(entry.name, dir_fd=fd) elif stat.S_ISREG(info.st_mode): os.unlink(entry.name, dir_fd=fd) else: raise LaneError(f"refusing unsafe entry during cleanup: {entry.name}") child_fd = os.open(name, flags, dir_fd=parent_fd) try: visit(child_fd) finally: os.close(child_fd) os.rmdir(name, dir_fd=parent_fd) finally: os.close(parent_fd) class Lane: def __init__(self, root: Path): self.root = Path(os.path.abspath(root)) _check_no_symlink(self.root) @contextmanager def locked(self): self.root.mkdir(parents=True, exist_ok=True, mode=0o700) marker = self.root / ".internal-test-lane.json" if not marker.exists(): if any(self.root.iterdir()): raise LaneError("lane root must be empty before initialization") os.chmod(self.root, 0o700) _atomic_json(marker, {"schemaVersion": 1, "owner": OWNER, "root": str(self.root)}) record = _read_json(marker) if record != {"schemaVersion": 1, "owner": OWNER, "root": str(self.root)}: raise LaneError("lane ownership marker does not match this root") lock_path = self.root / ".lock" _check_no_symlink(lock_path) fd = os.open(lock_path, os.O_CREAT | os.O_RDWR | getattr(os, "O_NOFOLLOW", 0), 0o600) try: fcntl.flock(fd, fcntl.LOCK_EX) yield finally: fcntl.flock(fd, fcntl.LOCK_UN) os.close(fd) def import_bundle(self, bundle_path: Path) -> dict: bundle_path = Path(os.path.abspath(bundle_path)) bundle = _read_json(bundle_path) normalized, inventory = _validate_bundle(bundle) source_root = bundle_path.parent for rel, expected in inventory.items(): actual = _hash_file(source_root / rel) if actual != expected: raise LaneError(f"source asset hash/size mismatch: {rel}") digest = _import_identity(normalized, inventory) with self.locked(): imports = self.root / "imports" imports.mkdir(exist_ok=True, mode=0o700) target = imports / digest if target.exists(): self._verify_import(digest) return {"importId": digest, "samples": 6, "bytes": sum(size for _, size in inventory.values()), "reused": True} staging = Path(tempfile.mkdtemp(prefix=".pending-", dir=imports)) try: for rel, expected in inventory.items(): dst = staging / rel dst.parent.mkdir(parents=True, exist_ok=True, mode=0o700) with (source_root / rel).open("rb") as src, dst.open("xb") as out: os.chmod(dst, 0o600) shutil.copyfileobj(src, out, 1024 * 1024) if _hash_file(dst) != expected: raise LaneError(f"asset changed during import: {rel}") _atomic_json(staging / "manifest.json", normalized) _atomic_json(staging / "inventory.json", {k: {"sha256": v[0], "size": v[1]} for k, v in inventory.items()}) _atomic_json(staging / "import.json", {"importId": digest, "bytes": sum(size for _, size in inventory.values()), "createdAt": datetime.now(timezone.utc).isoformat(), "state": "imported"}) os.rename(staging, target) except BaseException: shutil.rmtree(staging) raise return {"importId": digest, "samples": 6, "bytes": sum(size for _, size in inventory.values()), "reused": False} def _verify_import(self, import_id: str) -> tuple[Path, dict]: if not SHA_RE.fullmatch(import_id): raise LaneError("import ID must be a SHA256 digest") directory = self.root / "imports" / import_id _check_no_symlink(directory) if not directory.is_dir(): raise LaneError(f"unknown import: {import_id}") manifest = _read_json(directory / "manifest.json") inventory = _read_json(directory / "inventory.json") if not isinstance(inventory, dict): raise LaneError("import inventory must be an object") bundle = {**manifest, "assets": [{"path": path, **value} for path, value in inventory.items() if isinstance(value, dict)]} normalized, refs = _validate_bundle(bundle) if normalized != manifest or _import_identity(normalized, refs) != import_id: raise LaneError("import manifest/inventory digest no longer matches import ID") import_record = _read_json(directory / "import.json") if import_record.get("importId") != import_id or import_record.get("state") != "imported": raise LaneError("import record does not match import ID") if set(_safe_tree_files(directory)) != set(refs) | {"manifest.json", "inventory.json", "import.json"}: raise LaneError("import has unexpected or missing files") for rel, expected in refs.items(): if _hash_file(directory / rel) != expected: raise LaneError(f"imported asset changed: {rel}") return directory, manifest def prepare(self, batch_id: str, import_id: str, config_path: Path, repo: Path) -> dict: _valid_batch_id(batch_id) from scripts.internal_test_lane.environment import render_environment, render_initializer, validate_config raw = _read_json(config_path) if raw.get("batchId") != batch_id: raise LaneError("config batchId must match requested batch") config = validate_config(raw) environment = render_environment(config) initializer = render_initializer(config) with self.locked(): source, _ = self._verify_import(import_id) batches = self.root / "batches" batches.mkdir(exist_ok=True, mode=0o700) if (batches / batch_id).exists(): raise LaneError("batch already exists; batch IDs are never overwritten") for child in batches.iterdir(): if child.name.startswith(".pending-"): raise LaneError("unfinished batch preparation needs operator review") if child.is_dir() and _read_json(child / "batch.json").get("state") != "archived": raise LaneError("one batch at a time: archive the current batch before preparing another") staging = Path(tempfile.mkdtemp(prefix=".pending-", dir=batches)) try: _atomic_json(staging / "environment.json", environment) _atomic_json(staging / "initializer.json", initializer) _atomic_json(staging / "config.json", config) plan_path = staging / "seed-plan.json" cmd = ["go", "run", "./cmd/internal-test-seed", "plan", "--manifest", str(source / "manifest.json"), "--assets-root", str(source), "--batch", batch_id, "--out", str(plan_path)] go_cache = self.root / "go-cache" go_cache.mkdir(exist_ok=True, mode=0o700) result = subprocess.run(cmd, cwd=repo, env={**os.environ, "GOPROXY": "off", "GOSUMDB": "off", "GOCACHE": str(go_cache)}, text=True, capture_output=True, check=False) if result.returncode: raise LaneError(f"offline seed planner rejected bundle: {result.stderr.strip() or result.stdout.strip()}") if not plan_path.is_file(): raise LaneError("seed planner did not write a plan") plan_hash, _ = _hash_file(plan_path) env_hash, _ = _hash_file(staging / "environment.json") initializer_hash, _ = _hash_file(staging / "initializer.json") record = {"batchId": batch_id, "importId": import_id, "state": "prepared", "preparedAt": datetime.now(timezone.utc).isoformat(), "buildCommit": config["buildCommit"], "image": config["image"], "mongoImage": config["mongoImage"], "configSha256": _digest(_canonical(config)), "environmentSha256": env_hash, "initializerSha256": initializer_hash, "seedPlanSha256": plan_hash, "remoteState": "unknown", "businessAcceptance": "not-recorded"} _atomic_json(staging / "batch.json", record) os.rename(staging, batches / batch_id) return record except BaseException: shutil.rmtree(staging) raise def status(self) -> dict: with self.locked(): imports = self.root / "imports" batches = self.root / "batches" import_ids = sorted(p.name for p in imports.iterdir() if p.is_dir() and not p.name.startswith(".pending-")) if imports.exists() else [] pending_imports = sorted(p.name for p in imports.iterdir() if p.name.startswith(".pending-")) if imports.exists() else [] records = [] pending = [] if batches.exists(): for child in sorted(batches.iterdir()): if child.name.startswith(".pending-"): pending.append(child.name) elif child.is_dir(): records.append(_read_json(child / "batch.json")) return {"owner": OWNER, "imports": import_ids, "batches": records, "unfinished": {"imports": pending_imports, "batches": pending}, "remoteState": "not-verified-by-this-tool"} def record_evidence(self, batch_id: str, evidence_path: Path, plan_path: Path, result_path: Path) -> dict: """Import a bounded operator report; never infer remote state ourselves.""" _valid_batch_id(batch_id) evidence = _read_json(evidence_path) required = {"schemaVersion", "batchId", "stage", "reviewer", "observedAt", "target", "buildCommit", "image", "configSha256", "approvedExecutionPlanSha256", "resultSha256"} if set(evidence) != required or evidence.get("schemaVersion") != 1 or evidence.get("batchId") != batch_id: raise LaneError("evidence metadata fields/schema/batch do not match") stage = evidence.get("stage") if not isinstance(stage, str) or stage not in {"seeded", "business-verified"}: raise LaneError("evidence stage must be seeded or business-verified") reviewer = evidence.get("reviewer") if not isinstance(reviewer, str) or not reviewer.strip() or len(reviewer) > 120 or any(ord(char) < 32 for char in reviewer): raise LaneError("evidence reviewer must be a short nonblank name") observed_at = _validate_observed_at(evidence.get("observedAt")) for field in ("configSha256", "approvedExecutionPlanSha256", "resultSha256"): if not isinstance(evidence.get(field), str) or not SHA_RE.fullmatch(evidence[field]): raise LaneError(f"evidence {field} must be a SHA256 digest") plan, plan_file_sha = _read_json_and_hash(plan_path) result, result_sha = _read_json_and_hash(result_path) if result_sha != evidence["resultSha256"] or plan.get("sha256") != evidence["approvedExecutionPlanSha256"]: raise LaneError("execution plan or result hash differs from reviewed evidence") with self.locked(): directory = self.root / "batches" / batch_id record = _read_json(directory / "batch.json") expected_state = "prepared" if stage == "seeded" else "seeded" if record.get("state") != expected_state: raise LaneError(f"{stage} evidence requires batch state {expected_state}") if evidence["buildCommit"] != record.get("buildCommit") or evidence["image"] != record.get("image") or evidence["configSha256"] != record.get("configSha256"): raise LaneError("evidence source, image, or config differs from prepared batch") config = _read_json(directory / "config.json") target = evidence.get("target") if not isinstance(target, dict) or target.get("databaseName") != config["databaseName"]: raise LaneError("evidence target database differs from prepared batch") if target.get("kind") == "local": if set(target) != {"kind", "databaseName", "hostname", "namespace"} or not isinstance(target["hostname"], str) or target["hostname"] not in {"localhost", "127.0.0.1"} or target["namespace"] != "local": raise LaneError("local evidence target must name a loopback host and local namespace") if plan.get("assetsRoot") == "/workspace" or plan.get("workspaceRoot") == "/workspace": raise LaneError("local evidence cannot use an in-cluster execution plan") elif target.get("kind") == "cluster": if set(target) != {"kind", "databaseName", "hostname", "namespace", "clusterContext"} or target["hostname"] != config["hostname"] or target["namespace"] != config["namespace"] or not isinstance(target["clusterContext"], str) or not re.fullmatch(r"[A-Za-z0-9._:/@-]{1,128}", target["clusterContext"]): raise LaneError("cluster evidence target must match dedicated config and name a context") if plan.get("assetsRoot") != "/workspace" or plan.get("workspaceRoot") != "/workspace": raise LaneError("cluster evidence requires an in-cluster /workspace execution plan") else: raise LaneError("evidence target kind must be local or cluster") preview = _read_json(directory / "seed-plan.json") if plan.get("batchId") != batch_id or plan.get("database") != config["databaseName"] or plan.get("manifestSha256") != preview.get("manifestSha256") or plan.get("assets") != preview.get("assets"): raise LaneError("execution plan source assets or database differ from prepared batch") plan_rows, preview_rows = plan.get("samples"), preview.get("samples") if not isinstance(plan_rows, list) or not isinstance(preview_rows, list) or len(plan_rows) != 6 or len(preview_rows) != 6 or any(not isinstance(item, dict) for item in plan_rows + preview_rows): raise LaneError("execution plan must contain six sample mappings") plan_samples = [(item.get("key"), item.get("project"), item.get("mode")) for item in plan_rows] preview_samples = [(item.get("key"), item.get("project"), item.get("mode")) for item in preview_rows] if plan_samples != preview_samples: raise LaneError("execution plan sample mapping differs from prepared batch") if stage == "seeded": if result.get("database") != config["databaseName"] or result.get("planSha256") != plan["sha256"] or type(result.get("created")) is not bool or any(type(result.get(name)) is not int or result[name] != expected for name, expected in (("projects", 2), ("samples", 6), ("accounts", 5))): raise LaneError("seed result is not a successful six-sample Go apply report") scope = "six-sample-seed-report" else: prior = record.get("evidence", {}).get("seeded", {}) if prior.get("approvedExecutionPlanSha256") != plan["sha256"] or prior.get("target") != target: raise LaneError("business report must use the seeded execution plan and target") sample_key = result.get("sampleKey") sample = next((item for item in plan_rows if item.get("key") == sample_key), None) acceptance_id = "human-item-fanyu-v5-prepackage-acceptance-" + str(sample.get("batchId")) if sample else None if result.get("batchId") != batch_id or result.get("status") != "accepted" or sample is None or result.get("taskId") != sample.get("taskId") or result.get("itemId") != sample.get("itemId") or result.get("acceptanceItemId") != acceptance_id: raise LaneError("HTTP result does not prove an accepted test workflow from this plan") checks = result.get("checks") if checks is not None and (not isinstance(checks, list) or not checks or any(not isinstance(check, dict) or check.get("status") != "passed" for check in checks)): raise LaneError("HTTP report checks must all be passed") scope = "single-sample-http-workflow" summary = {"stage": stage, "reviewer": reviewer, "observedAt": observed_at, "target": target, "approvedExecutionPlanSha256": plan["sha256"], "executionPlanFileSha256": plan_file_sha, "resultSha256": result_sha, "importedAt": datetime.now(timezone.utc).isoformat(), "scope": scope, "verificationSource": "operator-supplied-report"} record.setdefault("evidence", {})[stage] = summary record["state"] = stage record["remoteState"] = "not-verified-by-this-tool" record["businessAcceptance"] = "operator-report-imported" if stage == "business-verified" else "not-recorded" _atomic_json(directory / "batch.json", record) return summary def archive(self, batch_id: str, evidence_path: Path) -> dict: _valid_batch_id(batch_id) evidence = _read_json(evidence_path) if set(evidence) != {"batchId", "tasksComplete", "environmentStopped", "detached", "reviewer"}: raise LaneError("archive evidence permits only the five required fields") if evidence.get("batchId") != batch_id or evidence.get("tasksComplete") is not True or evidence.get("environmentStopped") is not True or evidence.get("detached") is not True or not isinstance(evidence.get("reviewer"), str) or not evidence["reviewer"].strip(): raise LaneError("archive evidence must bind batchId, confirm tasksComplete/environmentStopped/detached, and name reviewer") with self.locked(): directory = self.root / "batches" / batch_id _check_no_symlink(directory) record = _read_json(directory / "batch.json") if record.get("state") not in {"prepared", "seeded", "business-verified"}: raise LaneError("only a prepared, seeded, or business-verified batch can be archived") _atomic_json(directory / "archive-evidence.json", evidence) record.update({"state": "archived", "archivedAt": datetime.now(timezone.utc).isoformat(), "evidenceSha256": _digest(_canonical(evidence)), "remoteState": "operator-attested-stopped"}) _atomic_json(directory / "batch.json", record) return record def cleanup_plan(self, batch_id: str) -> dict: _valid_batch_id(batch_id) with self.locked(): batches = self.root / "batches" records = [_read_json(p / "batch.json") for p in batches.iterdir() if p.is_dir() and not p.name.startswith(".pending-")] archived = sorted((r for r in records if r.get("state") == "archived"), key=lambda r: (r["archivedAt"], r["batchId"]), reverse=True) if batch_id in {r["batchId"] for r in archived[:3]}: raise LaneError("the latest three completed batches are retained") if batch_id not in {r["batchId"] for r in archived}: raise LaneError("cleanup requires an archived, detached batch") directory = batches / batch_id files = _safe_tree_files(directory) files.pop("cleanup-plan.json", None) plan = {"schemaVersion": 1, "owner": OWNER, "batchId": batch_id, "scope": "local-batch-record-only", "clusterCleanup": "manual-not-performed", "files": [{"path": path, "sha256": digest, "size": size} for path, (digest, size) in sorted(files.items())]} plan["confirmSha256"] = _digest(_canonical(plan)) _atomic_json(directory / "cleanup-plan.json", plan) return plan def clean(self, batch_id: str, confirm: str) -> dict: _valid_batch_id(batch_id) if not SHA_RE.fullmatch(confirm): raise LaneError("--confirm requires the cleanup plan SHA256") with self.locked(): batches = self.root / "batches" directory = batches / batch_id _check_no_symlink(directory) plan = _read_json(directory / "cleanup-plan.json") if plan.get("confirmSha256") != confirm: raise LaneError("confirmation digest does not match cleanup plan") base = {k: v for k, v in plan.items() if k != "confirmSha256"} if _digest(_canonical(base)) != confirm or plan.get("batchId") != batch_id or plan.get("owner") != OWNER: raise LaneError("cleanup plan integrity check failed") records = [_read_json(p / "batch.json") for p in batches.iterdir() if p.is_dir() and not p.name.startswith(".pending-")] archived = sorted((r for r in records if r.get("state") == "archived"), key=lambda r: (r["archivedAt"], r["batchId"]), reverse=True) if batch_id in {r["batchId"] for r in archived[:3]} or batch_id not in {r["batchId"] for r in archived}: raise LaneError("batch is active or belongs to the latest three completed batches") expected = {entry["path"]: (entry["sha256"], entry["size"]) for entry in plan["files"]} actual = _safe_tree_files(directory) actual.pop("cleanup-plan.json", None) if actual != expected: raise LaneError("batch files changed after cleanup preview; create a new plan") _remove_tree_no_follow(batches, batch_id) return {"batchId": batch_id, "removed": True, "scope": "local-batch-record-only", "clusterCleanup": "manual-not-performed"}