cairn-ai 0.2.5 → 0.2.7

package/scripts/cairn-lifecycle-commands.mjs

@@ -0,0 +1,200 @@
+import { spawnSync } from "node:child_process";
+import { lstat, mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { hasSetting, readSharedConfigSnapshot, removeCairnConfig, splitSections } from "./cairn-lifecycle-config.mjs";
+import {
+  installedSkillLocatorPath, validRuntimeLocator, validateAntigravitySkills,
+} from "./cairn-lifecycle-mirror.mjs";
+
+export function createCommands(context) {
+  const {
+    antigravityCliHome, antigravityHome, claudeRuntimeLocatorPath,
+    codexHome, configPath, installedPluginRoot, installedRuntimeLocatorPath,
+    marketplaceJsonPath, ownershipPath, phases, pluginName, pluginRoot,
+    pruneUninstallScaffolds, releaseVersion, samePath, skillNames, t, transaction,
+    versionedPluginRoot, staging, integrity,
+  } = context;
+  const {
+    createTransaction, finishTransaction, recoverInterruptedTransaction,
+    removeManagedTarget, replaceTarget, rollback,
+  } = transaction;
+  const { legacyMigrationTargets, stageInstall } = staging;
+  const {
+    adoptLegacy, anyManagedArtifactExists, assertOwnershipDigests,
+    assertTargetsReplaceable, ownershipDigestsValid, readOwnership, targetDigest,
+    targetRecord, validateOwnershipShape, versionedRuntimeRoot,
+  } = integrity;
+async function install(mode) {
+  if (samePath(pluginRoot, installedPluginRoot) || samePath(pluginRoot, versionedPluginRoot)) {
+    throw new Error("Run install or upgrade from the Cairn package/global source, not from the installed cache.");
+  }
+  await recoverInterruptedTransaction();
+  const transaction = await createTransaction();
+  try {
+    const targets = await stageInstall(transaction.stageRoot);
+    if (process.env.CAIRN_TEST_CRASH_AFTER_STAGE === "1") process.exit(87);
+    targets.push(...await legacyMigrationTargets());
+    let ownership = await readOwnership();
+    if (ownership) {
+      validateOwnershipShape(ownership);
+      await assertOwnershipDigests(ownership);
+      if (ownership.version !== releaseVersion) {
+        targets.push({
+          id: "previous-codex-runtime",
+          phase: "cleanup",
+          path: versionedRuntimeRoot(ownership.version),
+          type: "tree",
+          operation: "remove",
+        });
+      }
+    }
+    else if (await anyManagedArtifactExists(targets)) ownership = await adoptLegacy(targets, transaction);
+    await assertTargetsReplaceable(targets, ownership);
+    for (const phase of phases) {
+      for (const target of targets.filter((candidate) => candidate.phase === phase)) {
+        if (target.operation === "remove") await removeManagedTarget(target, transaction);
+        else await replaceTarget(target, transaction);
+      }
+      injectFailure(`after-${phase}`);
+    }
+    const records = [];
+    for (const target of targets.filter((candidate) => candidate.operation !== "remove")) records.push(await targetRecord(target));
+    const nextOwnership = {
+      schemaVersion: 1,
+      plugin: pluginName,
+      version: releaseVersion,
+      transactionId: transaction.id,
+      installedAt: new Date().toISOString(),
+      targets: records,
+    };
+    const ownershipStage = join(transaction.stageRoot, "lifecycle.json");
+    await mkdir(dirname(ownershipStage), { recursive: true });
+    await writeFile(ownershipStage, `${JSON.stringify(nextOwnership, null, 2)}\n`);
+    await replaceTarget({ id: "ownership", phase: "manifest", path: ownershipPath, staged: ownershipStage, type: "file" }, transaction);
+    await finishTransaction(transaction);
+    console.log(t(mode === "upgrade" ? "upgradeComplete" : "installComplete"));
+    console.log(`Codex plugin source: ${installedPluginRoot}`);
+    console.log(`Codex versioned runtime: ${versionedPluginRoot}`);
+    console.log(`Ownership manifest: ${ownershipPath}`);
+  } catch (error) {
+    if (transaction.state !== "committed") await rollback(transaction);
+    throw error;
+  }
+}
+
+async function uninstall() {
+  await recoverInterruptedTransaction();
+  const ownership = await readOwnership({ required: true });
+  validateOwnershipShape(ownership, { required: true });
+  const conflicts = [];
+  for (const record of ownership.targets) {
+    const current = await targetDigest(record.path, record.type);
+    if (record.type !== "config" && current !== record.installedDigest) conflicts.push(record.path);
+  }
+  if (conflicts.length > 0) throw new Error(`Refusing to uninstall modified managed artifacts: ${conflicts.join(", ")}`);
+  const transaction = await createTransaction();
+  try {
+    const configRecord = ownership.targets.find((record) => record.type === "config");
+    if (configRecord && await exists(configRecord.path)) {
+      const snapshot = await readSharedConfigSnapshot(configRecord.path);
+      const staged = join(transaction.stageRoot, "uninstall-config.toml");
+      await mkdir(dirname(staged), { recursive: true });
+      await writeFile(staged, removeCairnConfig(snapshot.text));
+      await replaceTarget({ ...configRecord, staged, configSourceDigest: snapshot.digest }, transaction);
+    }
+    injectFailure("uninstall-after-config");
+    for (const phase of ["antigravity", "claude"]) {
+      for (const record of ownership.targets.filter((candidate) => candidate.phase === phase).reverse()) await removeManagedTarget(record, transaction);
+    }
+    injectFailure("uninstall-after-external");
+    for (const record of ownership.targets.filter((candidate) => candidate.phase === "codex").reverse()) await removeManagedTarget(record, transaction);
+    injectFailure("uninstall-after-codex");
+    await removeManagedTarget({ id: "ownership", phase: "manifest", path: ownershipPath, type: "file" }, transaction);
+    injectFailure("uninstall-after-ownership");
+    await finishTransaction(transaction);
+    injectFailure("uninstall-after-commit");
+  } catch (error) {
+    if (transaction.state !== "committed") await rollback(transaction);
+    throw error;
+  }
+  await pruneUninstallScaffolds();
+  console.log(t("uninstallComplete"));
+}
+
+async function doctor() {
+  const checks = [];
+  const ownership = await readOwnership();
+  checks.push(["source", await exists(join(pluginRoot, ".codex-plugin", "plugin.json"))]);
+  checks.push(["ownership manifest", Boolean(ownership)]);
+  checks.push(["ownership digests", await ownershipDigestsValid(ownership)]);
+  checks.push(["custom marketplace source", await exists(join(installedPluginRoot, ".codex-plugin", "plugin.json"))]);
+  checks.push(["versioned runtime", await exists(join(versionedPluginRoot, ".codex-plugin", "plugin.json"))]);
+  checks.push(["marketplace", await exists(marketplaceJsonPath)]);
+  checks.push(["installed hooks manifest field", (await readJson(join(versionedPluginRoot, ".codex-plugin", "plugin.json")))?.hooks === "./hooks/hooks.json"]);
+  checks.push(["hooks file", await exists(join(versionedPluginRoot, "hooks", "hooks.json"))]);
+  checks.push(["installed runtime locator", await validRuntimeLocator(installedRuntimeLocatorPath, versionedPluginRoot)]);
+  checks.push(["installed skill locators", (await Promise.all(skillNames().map((name) => validRuntimeLocator(installedSkillLocatorPath(versionedPluginRoot, name), versionedPluginRoot)))).every(Boolean)]);
+  checks.push(["installed CLI script", await exists(join(versionedPluginRoot, "scripts", "cairn.mjs"))]);
+  checks.push(["installed plan template", await exists(join(versionedPluginRoot, "templates", "work-plan.md"))]);
+  checks.push(["installed model guidance", await exists(join(versionedPluginRoot, "docs", "model-guidance", "codex.md"))]);
+  const config = (await readSharedConfigSnapshot(configPath)).text;
+  checks.push(["config marketplace", splitSections(config).some((section) => section.header === "marketplaces.cairn")]);
+  checks.push(["config plugin enabled", hasSetting(config, 'plugins."cairn@cairn"', "enabled", "true")]);
+  checks.push(["Claude runtime locator", await validRuntimeLocator(claudeRuntimeLocatorPath, versionedPluginRoot)]);
+  checks.push(["Antigravity IDE skills", await exists(join(antigravityHome, "skills", "cairn-plan", "SKILL.md"))]);
+  checks.push(["Antigravity CLI flat skills", await exists(join(antigravityCliHome, "skills", "cairn-plan.md"))]);
+
+  const codexStatus = hostJson(["plugin", "list", "--json"], { CODEX_HOME: codexHome });
+  const codexEntry = findPluginStatus(codexStatus, "cairn@cairn");
+  checks.push(["Codex plugin installed", Boolean(codexEntry?.installed)]);
+  checks.push(["Codex plugin enabled", Boolean(codexEntry?.enabled)]);
+  checks.push(["Codex plugin version", codexEntry?.version === releaseVersion]);
+
+  const featureResult = spawnSync("codex", ["features", "list"], { encoding: "utf8", env: { ...process.env, CODEX_HOME: codexHome } });
+  const featureStates = featureResult.status === 0 && !featureResult.error ? parseCodexFeatureList(featureResult.stdout) : null;
+  checks.push(["Codex feature plugins", featureStates?.plugins === true]);
+  checks.push(["Codex feature hooks", featureStates?.hooks === true]);
+  checks.push(["Codex feature multi_agent", featureStates?.multi_agent === true]);
+
+  const agy = spawnSync("agy", ["--version"], { encoding: "utf8", env: process.env });
+  checks.push(["Antigravity CLI readiness", !agy.error && agy.status === 0 && /^\d+\.\d+\.\d+/.test(agy.stdout.trim())]);
+  checks.push(["Antigravity CLI skill validation", await validateAntigravitySkills(antigravityCliHome, skillNames(), versionedPluginRoot)]);
+  for (const [name, ok] of checks) console.log(`${ok ? "OK" : "FAIL"} ${name}`);
+  if (checks.some(([, ok]) => !ok)) process.exitCode = 1;
+}
+
+
+  function injectFailure(point) {
+    if (process.env.CAIRN_TEST_FAIL_PHASE === point) throw new Error(`Injected lifecycle failure: ${point}`);
+  }
+
+function hostJson(args, extraEnv = {}) {
+  const result = spawnSync("codex", args, { encoding: "utf8", env: { ...process.env, ...extraEnv } });
+  if (result.error || result.status !== 0) return null;
+  try { return JSON.parse(result.stdout); } catch { return null; }
+}
+
+function findPluginStatus(value, id) {
+  const entries = Array.isArray(value) ? value : value?.installed ?? value?.plugins ?? value?.data ?? [];
+  return entries.find((entry) => entry.pluginId === id || entry.id === id || entry.name === id || `${entry.name}@${entry.marketplaceName ?? entry.marketplace}` === id) ?? null;
+}
+
+function parseCodexFeatureList(output) {
+  if (typeof output !== "string" || output.trim().length === 0) return null;
+  const features = {};
+  for (const line of output.split(/\r?\n/)) {
+    const match = line.trim().match(/^([A-Za-z0-9_]+)\s+.+?\s+(true|false)$/);
+    if (match) features[match[1]] = match[2] === "true";
+  }
+  return Object.keys(features).length > 0 ? features : null;
+}
+
+async function readJson(path) { if (!(await exists(path))) return null; return JSON.parse(await readFile(path, "utf8")); }
+
+  return { doctor, install, uninstall };
+
+  async function exists(path) {
+    try { await lstat(path); return true; }
+    catch (error) { if (error?.code === "ENOENT") return false; throw error; }
+  }
+}

package/scripts/cairn-lifecycle-config.mjs

@@ -0,0 +1,149 @@
+import { createHash } from "node:crypto";
+import { constants as fsConstants } from "node:fs";
+import { lstat, open, readFile } from "node:fs/promises";
+import { join } from "node:path";
+
+export function updateConfig(config, hookStates, { marketplacePath } = {}) {
+  if (marketplacePath === undefined) throw new Error("Cairn marketplace path is required");
+  let next = removeCairnConfig(config);
+  next = append(next, `[marketplaces.cairn]\nlast_updated = ${JSON.stringify(new Date().toISOString().replace(/\.\d{3}Z$/, "Z"))}\nsource_type = "local"\nsource = ${JSON.stringify(marketplacePath)}\n`);
+  next = append(next, '[plugins."cairn@cairn"]\nenabled = true\n');
+  for (const state of hookStates) next = append(next, `[hooks.state.${JSON.stringify(state.key)}]\ntrusted_hash = ${JSON.stringify(state.trustedHash)}\n`);
+  return next;
+}
+
+export function removeCairnConfig(config) {
+  return splitSections(config).map((section) => isCairnConfigSection(section)
+    ? splitTrailingTomlTrivia(section.text).trivia
+    : section.text).join("");
+}
+
+export function cairnConfigProjection(config) {
+  return splitSections(config).filter(isCairnConfigSection)
+    .map((section) => splitTrailingTomlTrivia(section.text).body).join("");
+}
+
+function isCairnConfigSection(section) {
+  return section.header === "marketplaces.cairn"
+    || section.header === 'plugins."cairn@cairn"'
+    || (section.header?.startsWith("hooks.state.") && section.header.includes("cairn@cairn:"));
+}
+
+function splitTrailingTomlTrivia(text) {
+  const lines = text.split(/(?<=\n)/);
+  let boundary = lines.length;
+  while (boundary > 0) {
+    const line = lines[boundary - 1];
+    if (line.length === 0 || line.trim().length === 0 || line.trimStart().startsWith("#")) boundary -= 1;
+    else break;
+  }
+  return { body: lines.slice(0, boundary).join(""), trivia: lines.slice(boundary).join("") };
+}
+
+export async function readSharedConfigSnapshot(path) {
+  let pathInfo;
+  try {
+    pathInfo = await lstat(path);
+  } catch (error) {
+    if (error?.code === "ENOENT") return { exists: false, text: "", digest: "missing" };
+    throw error;
+  }
+  if (pathInfo.isSymbolicLink() || !pathInfo.isFile()) throw new Error(`Managed config is not a regular file: ${path}`);
+  let handle;
+  try {
+    const flags = fsConstants.O_RDONLY | (fsConstants.O_NOFOLLOW ?? 0) | (fsConstants.O_NONBLOCK ?? 0);
+    handle = await open(path, flags);
+  } catch (error) {
+    if (["ELOOP", "EFTYPE", "ENXIO"].includes(error?.code)) throw new Error(`Managed config is not a regular file: ${path}`);
+    throw error;
+  }
+  try {
+    const openedInfo = await handle.stat();
+    if (!openedInfo.isFile() || openedInfo.dev !== pathInfo.dev || openedInfo.ino !== pathInfo.ino) {
+      throw new Error(`Managed config changed identity while opening: ${path}`);
+    }
+    const text = await handle.readFile("utf8");
+    return { exists: true, text, digest: sha(text) };
+  } finally {
+    await handle.close();
+  }
+}
+
+export function ensureSetting(config, sectionName, key, value) {
+  const sections = splitSections(config);
+  const index = sections.findIndex((section) => section.header === sectionName);
+  if (index === -1) return append(config, `[${sectionName}]\n${key} = ${value}\n`);
+  const lines = sections[index].text.trimEnd().split("\n");
+  const settingIndex = lines.findIndex((line) => line.trim().startsWith(`${key} =`));
+  if (settingIndex === -1) lines.push(`${key} = ${value}`);
+  else lines[settingIndex] = `${key} = ${value}`;
+  sections[index].text = `${lines.join("\n")}\n`;
+  return sections.map((section) => section.text).join("");
+}
+
+export function hasSetting(config, sectionName, key, value) {
+  const section = splitSections(config).find((candidate) => candidate.header === sectionName);
+  return section?.text.split("\n").some((line) => line.trim() === `${key} = ${value}`) ?? false;
+}
+
+export function splitSections(config) {
+  const result = [];
+  let current = { header: null, text: "" };
+  let multiline = null;
+  for (const line of config.split(/(?<=\n)/)) {
+    const delimiterCount = (delimiter) => line.split(delimiter).length - 1;
+    if (multiline) {
+      current.text += line;
+      if (delimiterCount(multiline) % 2 === 1) multiline = null;
+      continue;
+    }
+    const doubleCount = delimiterCount('"""');
+    const singleCount = delimiterCount("'''");
+    const match = line.trim().match(/^\[([^\]]+)\]$/);
+    if (match) {
+      if (current.text.length > 0) result.push(current);
+      current = { header: match[1], text: line };
+    } else current.text += line;
+    if (doubleCount % 2 === 1) multiline = '"""';
+    else if (singleCount % 2 === 1) multiline = "'''";
+  }
+  if (current.text.length > 0) result.push(current);
+  return result;
+}
+
+export async function trustedHookStates(root) {
+  const parsed = JSON.parse(await readFile(join(root, "hooks", "hooks.json"), "utf8"));
+  const states = [];
+  const labels = { SessionStart: "session_start", UserPromptSubmit: "user_prompt_submit", PostToolUse: "post_tool_use", Stop: "stop", SubagentStop: "subagent_stop" };
+  for (const [eventName, groups] of Object.entries(parsed?.hooks ?? {})) {
+    const eventLabel = labels[eventName];
+    if (!eventLabel || !Array.isArray(groups)) continue;
+    for (const [groupIndex, group] of groups.entries()) for (const [handlerIndex, handler] of (group.hooks ?? []).entries()) {
+      states.push({ key: `cairn@cairn:hooks/hooks.json:${eventLabel}:${groupIndex}:${handlerIndex}`, trustedHash: hookHash(eventLabel, group.matcher, handler) });
+    }
+  }
+  return states;
+}
+
+export function hookHash(eventName, matcher, handler) {
+  const normalized = { type: "command", command: handler.command, timeout: Math.max(Number(handler.timeout ?? 600), 1), async: false };
+  if (typeof handler.statusMessage === "string") normalized.statusMessage = handler.statusMessage;
+  const identity = { event_name: eventName, hooks: [normalized] };
+  if (typeof matcher === "string") identity.matcher = matcher;
+  return sha(JSON.stringify(canonical(identity)));
+}
+
+export function canonical(value) {
+  if (Array.isArray(value)) return value.map(canonical);
+  if (value === null || typeof value !== "object") return value;
+  return Object.fromEntries(Object.keys(value).sort().map((key) => [key, canonical(value[key])]));
+}
+
+function append(config, block) {
+  if (config.length === 0) return `${block.trimEnd()}\n`;
+  return `${config}${config.endsWith("\n") ? "" : "\n"}${block.trimEnd()}\n`;
+}
+
+function sha(value) {
+  return `sha256:${createHash("sha256").update(value).digest("hex")}`;
+}

package/scripts/cairn-lifecycle-integrity.mjs

@@ -0,0 +1,218 @@
+import { createHash } from "node:crypto";
+import { lstat, readFile, readdir } from "node:fs/promises";
+import { basename, join, relative, sep } from "node:path";
+import { cairnConfigProjection, readSharedConfigSnapshot } from "./cairn-lifecycle-config.mjs";
+import { createLegacyIntegrity } from "./cairn-lifecycle-legacy.mjs";
+import { antigravityRuntimeLocatorPath } from "./cairn-lifecycle-mirror.mjs";
+
+export function createIntegrity(context) {
+  const {
+    antigravityCliHome, antigravityHome, claudeHome, claudeRuntimeLocatorPath,
+    commandNames, configPath, installedPluginRoot, legacyAntigravityHome,
+    marketplaceJsonPath, marketplaceRoot, ownershipPath, phases, pluginName,
+    releaseVersion, skillNames,
+  } = context;
+async function assertTargetsReplaceable(targets, ownership) {
+  const records = new Map((ownership?.targets ?? []).map((record) => [record.id, record]));
+  for (const target of targets) {
+    if (!(await exists(target.path))) {
+      target.preflightDigest = "missing";
+      continue;
+    }
+    const current = await targetDigest(target.path, target.type);
+    target.preflightDigest = current;
+    if (target.id === "previous-codex-runtime") {
+      const previous = records.get("codex-runtime");
+      if (!previous || previous.path !== target.path || previous.type !== target.type) throw new Error("Previous runtime does not match ownership manifest.");
+      continue;
+    }
+    const record = records.get(target.id);
+    if (!record) {
+      if (target.type === "config" && cairnConfigProjection((await readSharedConfigSnapshot(target.path)).text).length === 0) continue;
+      throw new Error(`Refusing to overwrite unmanaged artifact: ${target.path}`);
+    }
+    if (target.id === "codex-runtime" && ownership?.version !== releaseVersion) {
+      throw new Error(`Refusing to overwrite unmanaged current-version runtime: ${target.path}`);
+    }
+    if (record.path !== target.path || record.type !== target.type) throw new Error(`Ownership manifest target mismatch: ${target.id}`);
+    if (target.type !== "config" && current !== record.installedDigest) throw new Error(`Managed artifact was modified: ${target.path}`);
+  }
+}
+
+async function assertOwnershipDigests(ownership) {
+  for (const record of ownership.targets) {
+    const current = await targetDigest(record.path, record.type);
+    if (record.type !== "config" && current !== record.installedDigest) {
+      throw new Error(`Managed artifact was modified: ${record.path}`);
+    }
+  }
+}
+
+async function targetRecord(target) {
+  return { id: target.id, phase: target.phase, path: target.path, type: target.type, installedDigest: await targetDigest(target.path, target.type), previous: null };
+}
+
+async function readOwnership({ required = false } = {}) {
+  if (!(await exists(ownershipPath))) {
+    if (required) throw new Error(`Ownership manifest is missing: ${ownershipPath}`);
+    return null;
+  }
+  try {
+    return JSON.parse(await readFile(ownershipPath, "utf8"));
+  } catch {
+    throw new Error(`Ownership manifest is invalid: ${ownershipPath}`);
+  }
+}
+
+function validateOwnershipShape(ownership, { required = false } = {}) {
+  if (!ownership) {
+    if (required) throw new Error("Ownership manifest is required.");
+    return;
+  }
+  if (!sameKeys(ownership, ["schemaVersion", "plugin", "version", "transactionId", "installedAt", "targets"])
+      || ownership.schemaVersion !== 1 || ownership.plugin !== pluginName
+      || typeof ownership.version !== "string" || !/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(ownership.version)
+      || typeof ownership.transactionId !== "string" || !/^[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$/i.test(ownership.transactionId)
+      || typeof ownership.installedAt !== "string" || Number.isNaN(Date.parse(ownership.installedAt))
+      || !Array.isArray(ownership.targets)) {
+    throw new Error("Ownership manifest schema or plugin identity is invalid.");
+  }
+  const ids = new Set();
+  const paths = new Set();
+  for (const record of ownership.targets) {
+    if (!record || !sameKeys(record, ["id", "phase", "path", "type", "installedDigest", "previous"])
+        || typeof record.id !== "string" || record.id.length === 0 || ids.has(record.id)
+        || typeof record.path !== "string" || record.path.length === 0 || paths.has(record.path)
+        || typeof record.phase !== "string" || !phases.includes(record.phase)
+        || typeof record.type !== "string" || !["file", "tree", "config"].includes(record.type)
+        || typeof record.installedDigest !== "string" || !/^sha256:[a-f0-9]{64}$/.test(record.installedDigest)
+        || record.previous !== null) {
+      throw new Error("Ownership manifest contains an invalid or duplicate target.");
+    }
+    const expected = expectedManagedTarget(record.id, ownership.version);
+    if (!expected || expected.path !== record.path || expected.phase !== record.phase || expected.type !== record.type) {
+      throw new Error(`Ownership manifest target is outside the Cairn allowlist: ${record.id}`);
+    }
+    ids.add(record.id);
+    paths.add(record.path);
+  }
+  const requiredTargets = requiredOwnershipTargets(ownership.version);
+  if (ids.size !== requiredTargets.size || [...requiredTargets.keys()].some((id) => !ids.has(id))) {
+    throw new Error("Ownership manifest does not contain the complete managed target set.");
+  }
+}
+
+function requiredOwnershipTargets(version = releaseVersion) {
+  const ids = ["codex-source", "codex-runtime", "marketplace", "claude-runtime", "ide-runtime", "cli-runtime", "codex-config"];
+  for (const name of commandNames()) ids.push(`claude-command-${name}`, `ide-workflow-${name}`, `cli-workflow-${name}`);
+  for (const name of ["explorer", "worker"]) ids.push(`claude-agent-${name}`);
+  for (const name of skillNames()) ids.push(`ide-skill-${name}`, `cli-skill-${name}`);
+  return new Map(ids.map((id) => [id, expectedManagedTarget(id, version)]));
+}
+
+function expectedManagedTarget(id, version = releaseVersion) {
+  const exact = {
+    "codex-source": { phase: "codex", path: installedPluginRoot, type: "tree" },
+    "codex-runtime": { phase: "codex", path: versionedRuntimeRoot(version), type: "tree" },
+    marketplace: { phase: "codex", path: marketplaceJsonPath, type: "file" },
+    "claude-runtime": { phase: "claude", path: claudeRuntimeLocatorPath, type: "file" },
+    "ide-runtime": { phase: "antigravity", path: antigravityRuntimeLocatorPath(antigravityHome), type: "file" },
+    "cli-runtime": { phase: "antigravity", path: antigravityRuntimeLocatorPath(antigravityCliHome), type: "file" },
+    "legacy-ide-runtime": { phase: "antigravity", path: antigravityRuntimeLocatorPath(legacyAntigravityHome), type: "file" },
+    "codex-config": { phase: "config", path: configPath, type: "config" },
+  };
+  if (exact[id]) return exact[id];
+  for (const name of commandNames()) {
+    if (id === `claude-command-${name}`) return { phase: "claude", path: join(claudeHome, "commands", `cairn-${name}.md`), type: "file" };
+    if (id === `ide-workflow-${name}`) return { phase: "antigravity", path: join(antigravityHome, "workflows", `cairn-${name}.md`), type: "file" };
+    if (id === `cli-workflow-${name}`) return { phase: "antigravity", path: join(antigravityCliHome, "workflows", `cairn-${name}.md`), type: "file" };
+    if (id === `legacy-ide-workflow-${name}`) return { phase: "antigravity", path: join(legacyAntigravityHome, "workflows", `cairn-${name}.md`), type: "file" };
+  }
+  for (const name of ["explorer", "worker"]) if (id === `claude-agent-${name}`) return { phase: "claude", path: join(claudeHome, "agents", `cairn-${name}.md`), type: "file" };
+  for (const name of skillNames()) {
+    if (id === `ide-skill-${name}`) return { phase: "antigravity", path: join(antigravityHome, "skills", name), type: "tree" };
+    if (id === `cli-skill-${name}`) return { phase: "antigravity", path: join(antigravityCliHome, "skills", `${name}.md`), type: "file" };
+    if (id === `legacy-ide-skill-${name}`) return { phase: "antigravity", path: join(legacyAntigravityHome, "skills", name), type: "tree" };
+    if (id === `legacy-cli-skill-${name}`) return { phase: "antigravity", path: join(antigravityCliHome, "skills", name), type: "tree" };
+  }
+  return null;
+}
+
+function versionedRuntimeRoot(version) {
+  if (typeof version !== "string" || !/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(version)) throw new Error(`Invalid Cairn runtime version: ${version}`);
+  return join(marketplaceRoot, pluginName, version);
+}
+
+async function anyManagedArtifactExists(targets) {
+  for (const target of targets) {
+    if (!(await exists(target.path))) continue;
+    if (target.type !== "config" || cairnConfigProjection((await readSharedConfigSnapshot(target.path)).text).length > 0) return true;
+  }
+  return false;
+}
+
+async function targetDigest(path, type) {
+  if (!(await exists(path))) return "missing";
+  if (type === "config") return sha(cairnConfigProjection((await readSharedConfigSnapshot(path)).text));
+  const info = await lstat(path);
+  if (info.isSymbolicLink() || (!info.isFile() && !info.isDirectory())) throw new Error(`Managed artifact is not a regular file/tree: ${path}`);
+  if (info.isFile()) return sha(await readFile(path));
+  const files = await regularFiles(path);
+  const hash = createHash("sha256");
+  for (const file of files) {
+    hash.update(file).update("\0").update(await readFile(join(path, file))).update("\0");
+  }
+  return `sha256:${hash.digest("hex")}`;
+}
+
+async function regularFiles(root) {
+  const output = [];
+  async function walk(directory) {
+    for (const entry of await readdir(directory, { withFileTypes: true })) {
+      const path = join(directory, entry.name);
+      if (entry.isSymbolicLink() || (!entry.isDirectory() && !entry.isFile())) throw new Error(`Symlink or special file is not allowed in managed tree: ${path}`);
+      if (entry.isDirectory()) await walk(path);
+      else output.push(relative(root, path).split(sep).join("/"));
+    }
+  }
+  const info = await lstat(root);
+  if (info.isSymbolicLink()) throw new Error(`Symlink is not allowed: ${root}`);
+  if (info.isFile()) return [basename(root)];
+  await walk(root);
+  return output.sort();
+}
+
+async function assertRegularTree(path) {
+  await regularFiles(path);
+}
+
+function sha(value) {
+  return `sha256:${createHash("sha256").update(value).digest("hex")}`;
+}
+
+  async function ownershipDigestsValid(ownership) {
+    try {
+      validateOwnershipShape(ownership, { required: true });
+      for (const record of ownership.targets) if (await targetDigest(record.path, record.type) !== record.installedDigest) return false;
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  const legacy = createLegacyIntegrity({ ...context, regularFiles, targetDigest });
+  return {
+    ...legacy, anyManagedArtifactExists, assertOwnershipDigests, assertRegularTree,
+    assertTargetsReplaceable, expectedManagedTarget, ownershipDigestsValid, readOwnership,
+    targetDigest, targetRecord, validateOwnershipShape, versionedRuntimeRoot,
+  };
+
+  function sameKeys(value, expected) {
+    return Object.keys(value).sort().join("\0") === [...expected].sort().join("\0");
+  }
+
+  async function exists(path) {
+    try { await lstat(path); return true; }
+    catch (error) { if (error?.code === "ENOENT") return false; throw error; }
+  }
+}