@namewta/speculo 0.8.9 → 0.8.11

package/template/workflows/ops/common/schemas/promotion-manifest.schema.json

@@ -0,0 +1,22 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "urn:speculo:ops:promotion-manifest:v1",
+  "title": "Ops Promotion Manifest",
+  "type": "object",
+  "required": ["schema_version", "artifact", "scope", "project_id", "change", "created_at", "source_path", "archive_path", "retrospective_path", "writes", "archive_only", "summary"],
+  "properties": {
+    "schema_version": {"const": 1},
+    "artifact": {"const": "ops-promotion-manifest"},
+    "scope": {"enum": ["global", "project"]},
+    "project_id": {"type": ["string", "null"], "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$"},
+    "change": {"type": "string"},
+    "created_at": {"type": "string", "format": "date-time"},
+    "source_path": {"type": "string", "minLength": 1},
+    "archive_path": {"type": "string", "minLength": 1},
+    "retrospective_path": {"const": "RETROSPECTIVE.md"},
+    "writes": {"type": "array", "items": {"type": "object", "required": ["stable_key", "knowledge_scope", "action", "staging_path", "target_path", "content_digest", "expected_target_digest", "evidence"], "properties": {"stable_key": {"type": "string", "minLength": 1}, "knowledge_scope": {"enum": ["project-context", "project-adr", "project-runbook", "global-context", "global-adr", "global-runbook"]}, "action": {"enum": ["create", "merge", "supersede"]}, "staging_path": {"type": "string", "minLength": 1}, "target_path": {"type": "string", "minLength": 1}, "content_digest": {"type": "string", "pattern": "^[a-f0-9]{64}$"}, "expected_target_digest": {"type": ["string", "null"], "pattern": "^[a-f0-9]{64}$"}, "evidence": {"type": "array", "items": {"type": "string", "minLength": 1}, "minItems": 1, "uniqueItems": true}}, "additionalProperties": false}},
+    "archive_only": {"type": "array", "items": {"type": "string", "minLength": 1}, "uniqueItems": true},
+    "summary": {"type": "string", "minLength": 1}
+  },
+  "additionalProperties": false
+}

package/template/workflows/ops/common/schemas/status.schema.json

@@ -0,0 +1,30 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "urn:speculo:ops:status:v2",
+  "title": "Ops Global Status",
+  "type": "object",
+  "required": ["schema_version", "workflow", "active", "archived"],
+  "properties": {
+    "schema_version": {"const": 2},
+    "workflow": {"const": "ops"},
+    "active": {"type": "array", "items": {"$ref": "#/$defs/entry"}, "uniqueItems": true},
+    "archived": {"type": "array", "items": {"$ref": "#/$defs/entry"}, "uniqueItems": true}
+  },
+  "$defs": {
+    "entry": {
+      "type": "object",
+      "required": ["scope", "project_id", "change"],
+      "properties": {
+        "scope": {"enum": ["global", "project"]},
+        "project_id": {"type": ["string", "null"], "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$"},
+        "change": {"type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}-[a-z0-9]+(?:-[a-z0-9]+)*$"}
+      },
+      "allOf": [
+        {"if": {"properties": {"scope": {"const": "global"}}}, "then": {"properties": {"project_id": {"const": null}}}},
+        {"if": {"properties": {"scope": {"const": "project"}}}, "then": {"properties": {"project_id": {"type": "string"}}}}
+      ],
+      "additionalProperties": false
+    }
+  },
+  "additionalProperties": false
+}

package/template/workflows/ops/common/schemas/target-profile.schema.json

@@ -0,0 +1,32 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "urn:speculo:ops:target-profile:v1",
+  "title": "Ops Target Profile",
+  "type": "object",
+  "required": ["schema_version", "artifact", "scope", "project_id", "change", "created_at", "operation_mode", "environment_class", "deployment_root", "existing_state", "identity_confirmed", "identity_confirmation_evidence", "identity_assertions", "ownership", "differences", "secret_requirements", "readiness", "blockers"],
+  "properties": {
+    "schema_version": {"const": 1},
+    "artifact": {"const": "ops-target-profile"},
+    "scope": {"enum": ["global", "project"]},
+    "project_id": {"type": ["string", "null"], "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$"},
+    "change": {"type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}-[a-z0-9]+(?:-[a-z0-9]+)*$"},
+    "created_at": {"type": "string", "format": "date-time"},
+    "operation_mode": {"enum": ["audit", "takeover", "fresh", "release", "upgrade", "rollback"]},
+    "environment_class": {"enum": ["local", "shared-nonprod", "production"]},
+    "deployment_root": {"type": "string", "minLength": 1},
+    "existing_state": {"enum": ["absent", "present", "unknown"]},
+    "identity_confirmed": {"type": "boolean"},
+    "identity_confirmation_evidence": {"type": ["string", "null"]},
+    "identity_assertions": {"type": "array", "items": {"type": "object", "required": ["id", "provider", "key", "comparison", "expected", "evidence"], "properties": {"id": {"type": "string", "pattern": "^ID[0-9]{3}$"}, "provider": {"type": "string", "minLength": 1}, "key": {"type": "string", "minLength": 1}, "comparison": {"enum": ["exact", "ordered-list", "set", "digest"]}, "expected": {"anyOf": [{"type": "string", "minLength": 1}, {"type": "array", "items": {"type": "string", "minLength": 1}, "minItems": 1, "uniqueItems": true}]}, "evidence": {"type": "array", "items": {"type": "string", "minLength": 1}, "minItems": 1, "uniqueItems": true}}, "additionalProperties": false}, "minItems": 1},
+    "ownership": {"type": "object", "required": ["owned_targets", "protected_targets", "unknown_targets"], "properties": {"owned_targets": {"type": "array", "items": {"type": "string", "minLength": 1}, "uniqueItems": true}, "protected_targets": {"type": "array", "items": {"type": "string", "minLength": 1}, "uniqueItems": true}, "unknown_targets": {"type": "array", "items": {"type": "string", "minLength": 1}, "uniqueItems": true}}, "additionalProperties": false},
+    "differences": {"type": "array", "items": {"type": "object", "required": ["id", "target", "classification", "evidence"], "properties": {"id": {"type": "string", "pattern": "^DF[0-9]{3}$"}, "target": {"type": "string", "minLength": 1}, "classification": {"enum": ["expected", "safe-reconcile", "requires-backup", "ownership-conflict", "unknown"]}, "evidence": {"type": "array", "items": {"type": "string", "minLength": 1}, "minItems": 1, "uniqueItems": true}}, "additionalProperties": false}},
+    "secret_requirements": {"type": "array", "items": {"type": "object", "required": ["key", "source_ref", "presence_required", "version_ref"], "properties": {"key": {"type": "string", "minLength": 1}, "source_ref": {"type": "string", "minLength": 1}, "presence_required": {"type": "boolean"}, "version_ref": {"type": ["string", "null"]}}, "additionalProperties": false}},
+    "readiness": {"enum": ["blocked", "ready"]},
+    "blockers": {"type": "array", "items": {"type": "string", "minLength": 1}, "uniqueItems": true}
+  },
+  "allOf": [
+    {"if": {"properties": {"scope": {"const": "global"}}}, "then": {"properties": {"project_id": {"const": null}}}},
+    {"if": {"properties": {"scope": {"const": "project"}}}, "then": {"properties": {"project_id": {"type": "string"}}}}
+  ],
+  "additionalProperties": false
+}

package/template/workflows/ops/common/schemas/verification-state.schema.json

@@ -0,0 +1,30 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "urn:speculo:ops:verification-state:v1",
+  "title": "Ops Verification State",
+  "type": "object",
+  "required": ["schema_version", "artifact", "scope", "project_id", "change", "attempt_id", "captured_at", "target_profile_path", "target_profile_digest", "identity_results", "gates", "artifacts", "services", "probes", "convergence", "data_protection", "recovery", "retained_artifacts", "risks", "verdict"],
+  "properties": {
+    "schema_version": {"const": 1},
+    "artifact": {"const": "ops-verification-state"},
+    "scope": {"enum": ["global", "project"]},
+    "project_id": {"type": ["string", "null"], "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$"},
+    "change": {"type": "string"},
+    "attempt_id": {"type": "string", "pattern": "^ATTEMPT-[0-9]{3}$"},
+    "captured_at": {"type": "string", "format": "date-time"},
+    "target_profile_path": {"type": ["string", "null"]},
+    "target_profile_digest": {"type": ["string", "null"], "pattern": "^[a-f0-9]{64}$"},
+    "identity_results": {"type": "array", "items": {"type": "object", "required": ["assertion_id", "comparison", "actual", "matched", "evidence"], "properties": {"assertion_id": {"type": "string", "pattern": "^ID[0-9]{3}$"}, "comparison": {"enum": ["exact", "ordered-list", "set", "digest"]}, "actual": {"anyOf": [{"type": "string", "minLength": 1}, {"type": "array", "items": {"type": "string", "minLength": 1}, "minItems": 1, "uniqueItems": true}]}, "matched": {"type": "boolean"}, "evidence": {"type": "array", "items": {"type": "string", "minLength": 1}, "minItems": 1, "uniqueItems": true}}, "additionalProperties": false}},
+    "gates": {"type": "array", "items": {"type": "object", "required": ["id", "sequence", "status", "started_at", "ended_at", "evidence"], "properties": {"id": {"type": "string", "pattern": "^G[0-9]{2}$"}, "sequence": {"type": "integer", "minimum": 1}, "status": {"enum": ["passed", "failed", "blocked", "skipped"]}, "started_at": {"type": "string", "format": "date-time"}, "ended_at": {"type": "string", "format": "date-time"}, "evidence": {"type": "array", "items": {"type": "string", "minLength": 1}, "uniqueItems": true}}, "additionalProperties": false}},
+    "artifacts": {"type": "array", "items": {"type": "object", "required": ["requirement_id", "immutable_digest", "target_ref", "server_verified", "matched", "evidence"], "properties": {"requirement_id": {"type": "string", "pattern": "^AR[0-9]{3}$"}, "immutable_digest": {"type": "string", "pattern": "^(?:sha256:)?[a-f0-9]{64}$"}, "target_ref": {"type": "string", "minLength": 1}, "server_verified": {"type": "boolean"}, "matched": {"type": "boolean"}, "evidence": {"type": "array", "items": {"type": "string", "minLength": 1}, "uniqueItems": true}}, "additionalProperties": false}},
+    "services": {"type": "array", "items": {"type": "object", "required": ["id", "status", "immutable_ref", "restart_count", "runtime_digest", "evidence"], "properties": {"id": {"type": "string", "minLength": 1}, "status": {"enum": ["healthy", "running", "degraded", "failed", "absent"]}, "immutable_ref": {"type": ["string", "null"]}, "restart_count": {"type": "integer", "minimum": 0}, "runtime_digest": {"type": ["string", "null"]}, "evidence": {"type": "array", "items": {"type": "string", "minLength": 1}, "uniqueItems": true}}, "additionalProperties": false}},
+    "probes": {"type": "array", "items": {"type": "object", "required": ["verification_id", "ok", "http_status", "business_code", "authenticated", "consecutive_successes", "elapsed_seconds", "transient_failures", "evidence"], "properties": {"verification_id": {"type": "string", "pattern": "^VR[0-9]{3}$"}, "ok": {"type": "boolean"}, "http_status": {"type": ["integer", "null"]}, "business_code": {"type": ["integer", "string", "null"]}, "authenticated": {"type": ["boolean", "null"]}, "consecutive_successes": {"type": "integer", "minimum": 0}, "elapsed_seconds": {"type": "number", "minimum": 0}, "transient_failures": {"type": "array", "items": {"type": "string"}}, "evidence": {"type": "array", "items": {"type": "string", "minLength": 1}, "uniqueItems": true}}, "additionalProperties": false}},
+    "convergence": {"type": "array", "items": {"type": "object", "required": ["group", "member_ids", "digests", "matched", "evidence"], "properties": {"group": {"type": "string", "minLength": 1}, "member_ids": {"type": "array", "items": {"type": "string", "minLength": 1}, "minItems": 2, "uniqueItems": true}, "digests": {"type": "array", "items": {"type": "string", "minLength": 1}, "minItems": 2}, "matched": {"type": "boolean"}, "evidence": {"type": "array", "items": {"type": "string", "minLength": 1}, "uniqueItems": true}}, "additionalProperties": false}},
+    "data_protection": {"type": "array", "items": {"type": "object", "required": ["protection_id", "status", "evidence_path", "evidence_digest", "readability_verified", "restore_verified"], "properties": {"protection_id": {"type": "string", "pattern": "^DP[0-9]{3}$"}, "status": {"enum": ["verified", "waived", "not-required", "failed"]}, "evidence_path": {"type": ["string", "null"]}, "evidence_digest": {"type": ["string", "null"], "pattern": "^[a-f0-9]{64}$"}, "readability_verified": {"type": "boolean"}, "restore_verified": {"type": "boolean"}}, "additionalProperties": false}},
+    "recovery": {"type": "object", "required": ["strategy", "previous_release_ref", "rollback_operation_refs", "material_refs", "compatibility_verified", "data_restore_authorized", "evidence"], "properties": {"strategy": {"enum": ["restore-previous", "reverse-change", "forward-fix", "not-applicable"]}, "previous_release_ref": {"type": ["string", "null"]}, "rollback_operation_refs": {"type": "array", "items": {"type": "string", "pattern": "^OP[0-9]{3}$"}, "uniqueItems": true}, "material_refs": {"type": "array", "items": {"type": "string", "minLength": 1}, "uniqueItems": true}, "compatibility_verified": {"type": "boolean"}, "data_restore_authorized": {"type": ["boolean", "null"]}, "evidence": {"type": "array", "items": {"type": "string", "minLength": 1}, "uniqueItems": true}}, "additionalProperties": false},
+    "retained_artifacts": {"type": "array", "items": {"type": "object", "required": ["id", "kind", "locator", "reason"], "properties": {"id": {"type": "string", "minLength": 1}, "kind": {"type": "string", "minLength": 1}, "locator": {"type": "string", "minLength": 1}, "reason": {"type": "string", "minLength": 1}}, "additionalProperties": false}},
+    "risks": {"type": "array", "items": {"type": "string", "minLength": 1}, "uniqueItems": true},
+    "verdict": {"enum": ["passed", "failed", "blocked"]}
+  },
+  "additionalProperties": false
+}

package/template/workflows/ops/common/tools/close-change.mjs

@@ -0,0 +1,177 @@
+#!/usr/bin/env node
+
+import { createHash } from "node:crypto";
+import { existsSync, lstatSync, readFileSync, readdirSync } from "node:fs";
+import { mkdir, rename, rm, writeFile } from "node:fs/promises";
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+
+const CHANGE_NAME = /^[0-9]{4}-[0-9]{2}-[0-9]{2}-[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const PROJECT_ID = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const DIGEST = /^[a-f0-9]{64}$/;
+
+function parseArgs(argv) {
+  const options = { stateRoot: null, scope: null, project: null, change: null, apply: false, expectedDigest: null };
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === "--state-root") options.stateRoot = resolve(argv[++index] ?? "");
+    else if (arg === "--scope") options.scope = argv[++index] ?? null;
+    else if (arg === "--project") options.project = argv[++index] ?? null;
+    else if (arg === "--change") options.change = argv[++index] ?? null;
+    else if (arg === "--apply") options.apply = true;
+    else if (arg === "--expected-digest") options.expectedDigest = argv[++index] ?? null;
+    else throw new Error(`unknown option: ${arg}`);
+  }
+  if (!options.stateRoot || !["global", "project"].includes(options.scope) || !CHANGE_NAME.test(options.change ?? "")) throw new Error("--state-root, --scope and a valid --change are required");
+  if (options.scope === "project" && !PROJECT_ID.test(options.project ?? "")) throw new Error("project scope requires a valid --project");
+  if (options.scope === "global" && options.project) throw new Error("global scope cannot use --project");
+  if (options.apply && !DIGEST.test(options.expectedDigest ?? "")) throw new Error("--apply requires --expected-digest");
+  return options;
+}
+
+function canonicalize(value) {
+  if (Array.isArray(value)) return value.map(canonicalize);
+  if (value && typeof value === "object") return Object.fromEntries(Object.keys(value).sort().map((key) => [key, canonicalize(value[key])]));
+  return value;
+}
+function digestJson(value) { return createHash("sha256").update(JSON.stringify(canonicalize(value))).digest("hex"); }
+function digestBytes(value) { return createHash("sha256").update(value).digest("hex"); }
+function readJson(path, label) { try { return JSON.parse(readFileSync(path, "utf8")); } catch (error) { throw new Error(`${label}: invalid JSON (${error.message})`); } }
+function entryKey(entry) { return `${entry.scope}:${entry.project_id ?? "-"}:${entry.change}`; }
+function sameEntry(left, right) { return left?.scope === right.scope && left?.project_id === right.project_id && left?.change === right.change; }
+
+function roots(options) {
+  const entry = { scope: options.scope, project_id: options.scope === "project" ? options.project : null, change: options.change };
+  const prefix = entry.scope === "global" ? "" : `projects/${entry.project_id}/`;
+  const sourcePath = `${prefix}changes/${entry.change}`;
+  const archivePath = `${prefix}archive/${entry.change.slice(0, 7)}/${entry.change}`;
+  return { entry, sourcePath, archivePath, source: resolveState(options.stateRoot, sourcePath), archive: resolveState(options.stateRoot, archivePath) };
+}
+
+function resolveState(stateRoot, locator) {
+  if (typeof locator !== "string" || !locator || locator.startsWith("/") || locator.includes("\\") || locator.split("/").includes("..")) throw new Error(`invalid state-relative path: ${String(locator)}`);
+  const target = resolve(stateRoot, ...locator.split("/"));
+  const rel = relative(resolve(stateRoot), target);
+  if (rel === ".." || rel.startsWith(".." + sep) || isAbsolute(rel)) throw new Error(`state-relative path escapes Ops root: ${locator}`);
+  return target;
+}
+
+function resolveChange(changeRoot, locator) {
+  if (typeof locator !== "string" || !locator || locator.startsWith("/") || locator.includes("\\") || locator.split("/").includes("..")) throw new Error(`invalid change-relative path: ${String(locator)}`);
+  const target = resolve(changeRoot, ...locator.split("/"));
+  const rel = relative(resolve(changeRoot), target);
+  if (rel === ".." || rel.startsWith(".." + sep) || isAbsolute(rel)) throw new Error(`change-relative path escapes change root: ${locator}`);
+  return target;
+}
+
+function allowedTarget(entry, locator) {
+  const allowed = entry.scope === "project"
+    ? [`projects/${entry.project_id}/context/`, `projects/${entry.project_id}/adr/`, `projects/${entry.project_id}/runbooks/`, "context/", "adr/", "runbooks/"]
+    : ["context/", "adr/", "runbooks/"];
+  return allowed.some((root) => locator.startsWith(root));
+}
+
+function assertNoSymlinks(root) {
+  if (!existsSync(root)) return;
+  function visit(path) {
+    for (const entry of readdirSync(path, { withFileTypes: true })) {
+      const child = join(path, entry.name);
+      if (lstatSync(child).isSymbolicLink()) throw new Error(`Ops state contains symlink: ${relative(root, child)}`);
+      if (entry.isDirectory()) visit(child);
+    }
+  }
+  visit(root);
+}
+
+async function atomicWrite(path, bytes) {
+  await mkdir(dirname(path), { recursive: true });
+  const temp = join(dirname(path), `.${process.pid}-${Date.now()}-${Math.random().toString(16).slice(2)}.tmp`);
+  await writeFile(temp, bytes);
+  await rename(temp, path);
+}
+
+function validate(options) {
+  assertNoSymlinks(options.stateRoot);
+  const located = roots(options);
+  if (!existsSync(located.source)) throw new Error(`active change is missing: ${located.sourcePath}`);
+  if (existsSync(located.archive)) throw new Error(`archive target already exists: ${located.archivePath}`);
+  const statusPath = join(options.stateRoot, "status.json");
+  const globalStatus = readJson(statusPath, "status.json");
+  if (globalStatus.schema_version !== 2 || globalStatus.workflow !== "ops" || !Array.isArray(globalStatus.active) || !Array.isArray(globalStatus.archived)) throw new Error("status.json must use Ops schema v2");
+  if (globalStatus.active.filter((item) => sameEntry(item, located.entry)).length !== 1 || globalStatus.archived.some((item) => sameEntry(item, located.entry))) throw new Error("global status does not identify exactly one active tuple");
+  const changeStatusPath = join(located.source, ".status.json");
+  const changeStatus = readJson(changeStatusPath, ".status.json");
+  if (changeStatus.schema_version !== 2 || changeStatus.scope !== located.entry.scope || changeStatus.project_id !== located.entry.project_id || changeStatus.change !== located.entry.change || changeStatus.change_status !== "completed" || changeStatus.phase !== "ready_to_archive" || changeStatus.outcome === "pending" || changeStatus.blockers?.length) throw new Error("change is not ready to archive");
+  if (!existsSync(join(located.source, "RETROSPECTIVE.md"))) throw new Error("RETROSPECTIVE.md is required");
+  const manifestPath = join(located.source, "promotion", "manifest.json");
+  const manifest = readJson(manifestPath, "promotion/manifest.json");
+  const manifestDigest = digestJson(manifest);
+  if (manifest.schema_version !== 1 || manifest.artifact !== "ops-promotion-manifest" || manifest.scope !== located.entry.scope || manifest.project_id !== located.entry.project_id || manifest.change !== located.entry.change || manifest.source_path !== located.sourcePath || manifest.archive_path !== located.archivePath || manifest.retrospective_path !== "RETROSPECTIVE.md" || !Array.isArray(manifest.writes)) throw new Error("promotion manifest identity/path mismatch");
+  const targetSet = new Set();
+  const writes = manifest.writes.map((item, index) => {
+    if (!item || typeof item !== "object" || !item.staging_path?.startsWith("promotion/staging/") || !allowedTarget(located.entry, item.target_path) || !DIGEST.test(item.content_digest ?? "") || !(item.expected_target_digest === null || DIGEST.test(item.expected_target_digest))) throw new Error(`promotion write ${index} is invalid`);
+    if (targetSet.has(item.target_path)) throw new Error(`duplicate promotion target: ${item.target_path}`);
+    targetSet.add(item.target_path);
+    const staging = resolveChange(located.source, item.staging_path);
+    const target = resolveState(options.stateRoot, item.target_path);
+    if (!existsSync(staging) || digestBytes(readFileSync(staging)) !== item.content_digest) throw new Error(`staging digest mismatch: ${item.staging_path}`);
+    if (item.expected_target_digest === null ? existsSync(target) : !existsSync(target) || digestBytes(readFileSync(target)) !== item.expected_target_digest) throw new Error(`promotion target drift: ${item.target_path}`);
+    if ((item.action === "create") !== (item.expected_target_digest === null)) throw new Error(`promotion action/target expectation mismatch: ${item.target_path}`);
+    return { item, staging, target };
+  });
+  return { ...located, statusPath, globalStatus, changeStatusPath, changeStatus, manifest, manifestDigest, writes };
+}
+
+async function apply(options, context) {
+  if (context.manifestDigest !== options.expectedDigest) throw new Error("expected digest does not match promotion manifest");
+  const approval = readJson(join(context.source, "promotion", "approval.json"), "promotion/approval.json");
+  if (approval.schema_version !== 1 || approval.artifact !== "ops-promotion-approval" || approval.scope !== context.entry.scope || approval.project_id !== context.entry.project_id || approval.change !== context.entry.change || approval.manifest_path !== "promotion/manifest.json" || approval.manifest_digest !== context.manifestDigest || approval.decision !== "approved" || !approval.decision_summary || Number.isNaN(Date.parse(approval.decided_at))) throw new Error("promotion approval does not bind the current manifest");
+
+  const originalGlobal = readFileSync(context.statusPath);
+  const originalChange = readFileSync(context.changeStatusPath);
+  const originals = context.writes.map(({ target }) => existsSync(target) ? readFileSync(target) : null);
+  const rollbackRoot = join(context.source, "promotion", "rollback");
+  if (existsSync(rollbackRoot)) throw new Error("promotion rollback directory already exists");
+  await mkdir(rollbackRoot, { recursive: true });
+  const rollbackManifest = context.writes.map(({ item }, index) => ({ target_path: item.target_path, existed: originals[index] !== null, backup_path: originals[index] === null ? null : `promotion/rollback/${String(index + 1).padStart(3, "0")}.bak` }));
+  for (const [index, bytes] of originals.entries()) if (bytes !== null) await writeFile(join(rollbackRoot, `${String(index + 1).padStart(3, "0")}.bak`), bytes);
+  await writeFile(join(rollbackRoot, "manifest.json"), JSON.stringify({ schema_version: 1, writes: rollbackManifest }, null, 2) + "\n", "utf8");
+
+  let moved = false;
+  try {
+    for (const { item, staging, target } of context.writes) await atomicWrite(target, readFileSync(staging));
+    const archivedAt = new Date().toISOString();
+    const nextChange = { ...context.changeStatus, change_status: "archived", phase: "archived", current_work: null, works_run: [...new Set([...(context.changeStatus.works_run ?? []), "ops/archive-and-learn"])], updated_at: archivedAt, archived_at: archivedAt, archive_path: `<Path>{roots.state}/ops/${context.archivePath}</Path>` };
+    const nextGlobal = { ...context.globalStatus, active: context.globalStatus.active.filter((item) => !sameEntry(item, context.entry)), archived: [...context.globalStatus.archived, context.entry] };
+    await atomicWrite(context.changeStatusPath, JSON.stringify(nextChange, null, 2) + "\n");
+    await atomicWrite(context.statusPath, JSON.stringify(nextGlobal, null, 2) + "\n");
+    await mkdir(dirname(context.archive), { recursive: true });
+    await rename(context.source, context.archive);
+    moved = true;
+  } catch (error) {
+    if (moved && existsSync(context.archive) && !existsSync(context.source)) await rename(context.archive, context.source);
+    await atomicWrite(context.statusPath, originalGlobal);
+    await atomicWrite(join(context.source, ".status.json"), originalChange);
+    for (const [index, { target }] of context.writes.entries()) {
+      if (originals[index] === null) await rm(target, { force: true });
+      else await atomicWrite(target, originals[index]);
+    }
+    throw error;
+  }
+  if (!moved || existsSync(context.source) || !existsSync(context.archive)) throw new Error("archive move did not complete");
+  console.log(`Ops close applied: ${entryKey(context.entry)} -> ${context.archivePath}`);
+}
+
+async function main() {
+  const options = parseArgs(process.argv.slice(2));
+  const context = validate(options);
+  if (!options.apply) {
+    console.log(`Ops close dry-run: ${entryKey(context.entry)}`);
+    console.log(`Manifest digest: ${context.manifestDigest}`);
+    console.log(`Knowledge writes: ${context.writes.length}`);
+    console.log(`Archive target: ${context.archivePath}`);
+    return;
+  }
+  await apply(options, context);
+}
+
+main().catch((error) => { console.error(`Ops close failed: ${error.message}`); process.exitCode = 1; });