agent-skillboard 0.2.17 → 0.3.0

package/src/lifecycle-content.mjs

@@ -2,17 +2,8 @@ export const BRIDGE_START = "<!-- BEGIN SKILLBOARD -->";
 export const BRIDGE_END = "<!-- END SKILLBOARD -->";
 
 export function defaultConfig() {
-  return `version: 1
-defaults:
-  invocation_policy: deny-by-default
-  allow_model_invocation: false
-  require_explicit_workflow: true
-
+  return `version: 2
 skills: {}
-capabilities: {}
-harnesses: {}
-workflows: {}
-install_units: {}
 `;
 }
 
@@ -20,40 +11,49 @@ export function bridgeBlock() {
   return `${BRIDGE_START}
 # SkillBoard Control Plane
 
-Your responsibility is to answer skill availability questions from SkillBoard, translate user intent into current action ids, ask for one confirmation only before policy-changing actions, apply one current action, reread the post-apply brief, and run the guard automatically before invocation.
-
-## Product Goal
-
-- SkillBoard is a permissive AI skill routing layer, not a pre-task settings checklist.
-- Keep installed skills broadly available by default; use SkillBoard to resolve overlap when several skills could steer the same task.
-- Read \`docs/ai-skill-routing-goal.md\` before changing routing, brief, bridge, policy, or workflow UX.
-- Preserve the loop: observe → route → work → explain briefly → ask after → remember policy.
-- SkillBoard does not rewrite \`SKILL.md\` bodies to personalize behavior; record usage policy for when to use, prefer, reference, avoid, or block skills.
-
-## Availability
-
-- Use SkillBoard as the source of truth for project-local policy and workflow priority; installed \`SKILL.md\` files are candidates, not enough to resolve overlap by themselves.
-- Read the current brief before answering: \`skillboard brief --json --config skillboard.config.yaml --skills skills\`. If the workflow is known, include \`--workflow <name>\`; add \`--include-actions\` when the user wants you to mediate a change.
-- For ordinary user requests, work normally unless skill choice is ambiguous, several skills overlap, workflow priority matters, or the user explicitly asks for a SkillBoard or skill decision. In those cases, read \`skillboard brief --intent <request> --json --config skillboard.config.yaml --skills skills\`. Include \`--workflow <name>\` when known. Read \`assistant_guidance.route\`; use \`recommended_skill\`, \`fallback_skills\`, \`route_candidates\`, \`overlap_resolution\`, \`policy_memory\`, \`post_use_policy_suggestion\`, and \`guard_command\` instead of guessing from raw skill text. Inspect \`overlap_resolution\` and \`route_candidates\` when several skills match so allowed overlap, denied candidates, and selected fallbacks are clear. If \`policy_memory\` is present, mention after completion that remembered or configured policy selected this skill even though other allowed skills were available. If \`post_use_policy_suggestion\` is present, work first with the allowed routed skill, then ask after completion whether to remember the suggested policy. If no skill matches, ask a clarifying question before choosing a skill.
-- If the user explicitly requests a specific already-allowed skill, honor that request after guard use instead of rerouting away solely because another skill also matches.
-- Treat the brief sections headed "What your AI can use now", "Needs your decision", and "Blocked for safety" as the availability summary; do not infer availability from \`SKILL.md\` bodies.
-- Treat "Needs your decision" as a one-time decision queue, not a persistent blocked state. "Blocked for safety" means the skill/source/workflow is hard-blocked until policy or provenance changes.
-- Use \`skillboard can-use <skill-id> --workflow <name> --config skillboard.config.yaml --skills skills --json\` for machine-readable agent decisions.
-
-## Intent to Action
-
-- Translate user intent into current action ids from the current brief, not saved output.
-- For action cards, read \`skillboard brief --json --config skillboard.config.yaml --skills skills --include-actions\`, pick one current action id, ask the user for one confirmation, then run \`skillboard apply-action <action-id> --config skillboard.config.yaml --skills skills --yes --json\`. Include \`--workflow <name>\` when a workflow is selected.
-- After \`skillboard apply-action <action-id> ... --yes --json\`, reread the returned post-apply brief before answering the next availability question or applying another action. \`apply-action\` re-resolves current actions; do not apply cached or stale action ids, do not apply multiple actions, and do not run raw action-card shell text as the primary apply path.
-- For an already-allowed skill, do not ask for another approval. Run \`skillboard guard use <skill-id> --workflow <name> --config skillboard.config.yaml --skills skills\` automatically. Say at the start: "I will use <skill-id> for this request." Say at completion: "I used <skill-id> for this request." Treat this disclosure as an audit trace, not a permission prompt. Ask the user only if the guard denies use or a policy-changing action is needed.
-
-## Operations
-
-- Source trust: run \`skillboard audit sources --config skillboard.config.yaml --skills skills\` before trusting newly imported external skill sources; after review, use \`skillboard review install-unit <unit-id> --trust-level reviewed --config skillboard.config.yaml --skills skills\`. Unreviewed runtime sources are a one-time review decision, not a default block recommendation; after review, activate only the needed quarantined skills as manual-only workflow skills and use ask-after policy suggestions for future preferences.
-- Health: run \`skillboard doctor --config skillboard.config.yaml --skills skills\` or \`skillboard status --config skillboard.config.yaml --skills skills --json\`; add \`--strict\` when review-needed safe mode should fail automation.
-- Hook action cards: prefer \`skillboard apply-action <action-id> --yes --json\`. The underlying manual preview is \`skillboard hook install --workflow <name> --config skillboard.config.yaml --skills skills --out .skillboard/hooks/<name>-guard.sh --dry-run --json\`; inspect \`planned.preview.shell\` before materializing an executable guard hook outside the action-card control loop. Generated hooks pin the install-time SkillBoard command, config, skills root, and workflow; set those values with hook install options such as \`--skillboard-bin\`, not runtime environment overrides.
-- Inventory/import growth: run \`skillboard inventory refresh --dry-run --config skillboard.config.yaml\` after installing local skill packs, plugins, workflow bundles, or harnesses; run \`skillboard import --profile <id-or-path> --source-root <repo> --out .skillboard/reports/import-fragment.yaml\` after installing a new skill repository, then review the fragment before merging it into \`skillboard.config.yaml\`.
-- Prefer workflow-scoped skills over global skill invocation. Only \`global-meta\` skills may be treated as globally available.
+SkillBoard keeps one user-level policy. A valid installed skill defaults to
+enabled and agent-local. Users may opt individual skills into cross-agent
+sharing. Optional preference ranks enabled skills installed for the current
+agent and never changes availability or copies files.
+
+## Route and use
+
+- Work normally unless skills overlap or the user asks
+  for a skill decision.
+- Read \`skillboard brief --intent <request> --agent <agent> --json\`.
+- Use the recommended enabled, installed skill and ordered fallbacks. Honor an
+  explicit user choice when the guard allows it.
+- Run \`skillboard guard use <skill-id> --agent <agent> --json\` immediately
+  before use.
+- Do not ask for another approval when guard allows use. Briefly disclose the
+  selected skill as an audit trace.
+- If the routed brief suggests policy memory, finish the work first, then ask
+  once whether to remember that intent preference. Do not prompt before use.
+
+## Change policy
+
+- Policy changes only enable/disable a skill, share/unshare one skill, or
+  remember optional ranking preference.
+- Read a fresh brief with \`--include-actions\`, choose one current action id, ask
+  for one confirmation, then run \`skillboard apply-action <action-id> --yes
+  --json\`.
+- Reread the returned post-apply brief. Never reuse cached action ids or apply
+  multiple actions from one confirmation.
+- If inventory no longer observes a permanently removed unshared skill, use its
+  current forget action after confirmation. Forget removes policy only and never
+  deletes skill files.
+
+## Compatibility and boundaries
+
+- If the brief reports stale version 1 policy, do not mutate it. Preview
+  \`skillboard migrate v2 --config skillboard.config.yaml --json\`, then obtain
+  confirmation before applying with \`--yes --json\`. Rollback uses
+  \`--rollback <backup> --json\`.
+- Source and provenance observations are optional audit metadata and never
+  determine availability.
+- Runtime and action authorization are outside SkillBoard's scope. Follow the
+  agent or harness permission boundary for commands, hooks, MCP servers,
+  external writes, destructive actions, network access, and secrets.
 
 ${BRIDGE_END}`;
 }
@@ -61,39 +61,24 @@ ${BRIDGE_END}`;
 export function profileReadme() {
   return `# SkillBoard source profiles
 
-Put project-specific source profiles here when a skill repository or harness
-bundle is not covered by a built-in profile.
-
-Use:
-
-\`\`\`bash
-skillboard import --profile .skillboard/profiles/example.yaml --source-root /path/to/repo
-\`\`\`
-
-The import command emits a YAML fragment with governed \`skills\` and
-\`install_units\`. Review the fragment before merging it into
-\`skillboard.config.yaml\`; imported skills are not automatically active.
+Put discovery profiles here when a skill repository is not
+covered by a built-in profile. Profiles produce inventory observations; they do
+not authorize availability. Newly discovered valid skills default to
+enabled and agent-local while existing user policy is preserved.
 `;
 }
 
 export function hookReadme() {
   return `# SkillBoard hooks
 
-Use this directory for executable guard scripts generated by:
+Preview a generated guard hook before installation:
 
 \`\`\`bash
 skillboard hook install --workflow <name> --config skillboard.config.yaml --skills skills --out .skillboard/hooks/<name>-guard.sh --dry-run --json
-skillboard hook install --workflow <name> --config skillboard.config.yaml --skills skills --out .skillboard/hooks/<name>-guard.sh
 \`\`\`
 
-For hook action cards, prefer the bridge control loop with
-\`skillboard apply-action <action-id> --yes --json\`. These raw hook commands
-are the underlying manual detail: preview the JSON plan first and inspect
-\`planned.preview.shell\` before materializing an executable guard hook.
-Generated hooks pin the install-time SkillBoard command, config, skills root,
-and workflow; set those values with hook install options such as
-\`--skillboard-bin\`, not runtime environment overrides. The generated script
-delegates to \`skillboard guard use\` and can be wired into the hook mechanism of
-the active harness.
+For persistent changes prefer one current action card applied with
+\`skillboard apply-action <action-id> --yes --json\`. Runtime hook permission is
+owned by the active harness, not SkillBoard policy.
 `;
 }

package/src/migration/v1-to-v2.mjs

@@ -0,0 +1,212 @@
+import { EXPOSURE_VALUES, INVOCATION_VALUES, STATUS_VALUES } from "../domain/constants.mjs";
+import { TERMINAL_STATUSES, validateSkillState } from "../domain/skill-state-matrix.mjs";
+
+const V1_SKILL_POLICY_FIELDS = new Set(["status", "invocation", "exposure"]);
+const V1_SKILL_LOCATION_FIELDS = new Set(["path", "owner_install_unit"]);
+
+/**
+ * Purely project a parsed v1 config into v2 policy and audit observations.
+ * The caller retains ownership of input and may safely hash/reuse it afterward.
+ */
+export function mapV1ConfigToV2(input) {
+  const config = requireRecord(input, "v1 config");
+  if (config.version !== undefined && config.version !== 1) {
+    throw new Error(`Expected version 1 config; got version ${String(config.version)}`);
+  }
+  const skills = requireRecord(config.skills ?? {}, "v1 config skills");
+  const workflows = requireRecord(config.workflows ?? {}, "v1 config workflows");
+  const capabilities = requireRecord(config.capabilities ?? {}, "v1 config capabilities");
+  const installUnits = requireRecord(config.install_units ?? {}, "v1 config install_units");
+  const workflowNames = Object.keys(workflows).sort();
+  const warnings = [];
+  const losses = collectLosses(config);
+  const policySkills = {};
+  const inventorySkills = [];
+  const uncertainQuarantines = [];
+
+  for (const [skillId, rawSkill] of Object.entries(skills).sort(byEntryKey)) {
+    const skill = requireRecord(rawSkill, `skill ${skillId}`);
+    validateState(skillId, skill);
+    const enabled = !TERMINAL_STATUSES.has(skill.status);
+    const preference = preferenceFor(skillId, capabilities, workflows);
+    policySkills[skillId] = {
+      enabled,
+      shared: false,
+      ...(preference === null ? {} : { preference })
+    };
+    if (isReviewOnlyQuarantine(skillId, skill, workflowNames, workflows)) {
+      uncertainQuarantines.push(skillId);
+    }
+    inventorySkills.push(skillObservation(skillId, skill));
+  }
+
+  const ambiguities = uncertainQuarantines.length === 0 ? [] : [{
+    kind: "review_only_quarantine",
+    skill_ids: uncertainQuarantines,
+    mapped_enabled: true,
+    requires_grouped_confirmation: true
+  }];
+  if (uncertainQuarantines.length > 0) {
+    warnings.push(
+      `${uncertainQuarantines.length} review-only quarantine state(s) were mapped enabled; confirm them together when applying the migration.`
+    );
+  }
+
+  return {
+    policy: {
+      version: 2,
+      skills: policySkills
+    },
+    inventory: {
+      format_version: 1,
+      skills: inventorySkills,
+      install_units: Object.entries(installUnits).sort(byEntryKey).map(([id, unit]) => ({
+        id,
+        observations: clone(requireRecord(unit, `install unit ${id}`))
+      }))
+    },
+    warnings,
+    losses,
+    ambiguities
+  };
+}
+
+function isReviewOnlyQuarantine(skillId, skill, workflowNames, workflows) {
+  if (skill.status !== "quarantined" || skill.invocation !== "blocked") return false;
+  return !workflowNames.some((name) => stringList(workflows[name]?.blocked_skills).includes(skillId));
+}
+
+function validateState(skillId, skill) {
+  if (!STATUS_VALUES.has(skill.status)) {
+    throw new Error(`Skill ${skillId} has unsupported status: ${String(skill.status)}`);
+  }
+  if (!INVOCATION_VALUES.has(skill.invocation)) {
+    throw new Error(`Skill ${skillId} has unsupported invocation: ${String(skill.invocation)}`);
+  }
+  if (!EXPOSURE_VALUES.has(skill.exposure)) {
+    throw new Error(`Skill ${skillId} has unsupported exposure: ${String(skill.exposure)}`);
+  }
+  const diagnostic = validateSkillState(skill.status, skill.invocation, skillId);
+  if (typeof diagnostic === "string") throw new Error(diagnostic);
+}
+
+function preferenceFor(skillId, capabilities, workflows) {
+  const roles = [];
+  for (const [name, rawCapability] of Object.entries(capabilities)) {
+    const capability = requireRecord(rawCapability, `capability ${name}`);
+    if (capability.canonical === skillId) roles.push({ intent: name, priority: 100 });
+    if (stringList(capability.alternatives).includes(skillId)) roles.push({ intent: name, priority: 50 });
+  }
+  for (const rawWorkflow of Object.values(workflows)) {
+    const workflow = requireRecord(rawWorkflow, "workflow");
+    const requirements = requireRecord(workflow.required_capabilities ?? {}, "workflow required_capabilities");
+    for (const [name, rawRequirement] of Object.entries(requirements)) {
+      const requirement = requireRecord(rawRequirement, `workflow capability ${name}`);
+      if (requirement.preferred === skillId) roles.push({ intent: name, priority: 100 });
+      stringList(requirement.fallback).forEach((candidate, index) => {
+        if (candidate === skillId) roles.push({ intent: name, priority: 90 - index });
+      });
+    }
+  }
+  if (roles.length === 0) return null;
+  return {
+    intents: [...new Set(roles.map(({ intent }) => intent))].sort(),
+    priority: Math.max(...roles.map(({ priority }) => priority))
+  };
+}
+
+function skillObservation(id, skill) {
+  const aliases = Array.isArray(skill.source_aliases) ? clone(skill.source_aliases) : [];
+  const observations = Object.fromEntries(
+    Object.entries(skill)
+      .filter(([key]) => !V1_SKILL_POLICY_FIELDS.has(key)
+        && !V1_SKILL_LOCATION_FIELDS.has(key)
+        && key !== "source_aliases")
+      .map(([key, value]) => [key, clone(value)])
+  );
+  return {
+    id,
+    path: typeof skill.path === "string" && skill.path.length > 0 ? skill.path : id,
+    owner_install_unit: typeof skill.owner_install_unit === "string" && skill.owner_install_unit.length > 0
+      ? skill.owner_install_unit
+      : "migration.unowned",
+    aliases,
+    installed_on: installedAgents(skill),
+    observations
+  };
+}
+
+function installedAgents(skill) {
+  const units = [skill.owner_install_unit, ...(skill.source_aliases ?? []).map((alias) => alias?.owner_install_unit)];
+  return [...new Set(units.map(agentForUnit).filter(Boolean))].sort();
+}
+
+function agentForUnit(unit) {
+  if (typeof unit !== "string") return "";
+  return ["codex", "claude", "opencode", "hermes"].find((agent) => unit === agent || unit.startsWith(`${agent}.`)) ?? "";
+}
+
+function collectLosses(config) {
+  const losses = [];
+  visit(config, "", (path, value) => {
+    if (path === "/version") return;
+    losses.push({ path, value: clone(value), disposition: lossDisposition(path) });
+  });
+  return losses;
+}
+
+function visit(value, path, add) {
+  if (value === null || typeof value !== "object") {
+    add(path, value);
+    return;
+  }
+  if (Array.isArray(value)) {
+    if (value.length === 0) add(path, []);
+    value.forEach((entry, index) => visit(entry, `${path}/${index}`, add));
+    return;
+  }
+  const entries = Object.entries(value);
+  if (entries.length === 0) add(path, {});
+  entries.forEach(([key, entry]) => visit(entry, `${path}/${escapePointer(key)}`, add));
+}
+
+function lossDisposition(path) {
+  if (/^\/skills\/[^/]+\/(status|invocation|exposure)$/.test(path)) return "mapped_to_v2_policy";
+  if (path.startsWith("/skills/") || path.startsWith("/install_units/")) return "preserved_in_inventory_observation";
+  if (path.startsWith("/capabilities/") || path.startsWith("/workflows/")) return "mapped_where_applicable";
+  return "not_part_of_v2_policy";
+}
+
+function requireRecord(value, label) {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error(`${label} must be an object mapping`);
+  }
+  return value;
+}
+
+function stringList(value) {
+  if (value === undefined) return [];
+  if (!Array.isArray(value) || value.some((entry) => typeof entry !== "string")) {
+    throw new Error("Expected a list of strings in v1 config");
+  }
+  return value;
+}
+
+function clone(value) {
+  if (Array.isArray(value)) {
+    return value.map((entry) => clone(entry));
+  }
+  if (value !== null && typeof value === "object") {
+    return Object.fromEntries(Object.entries(value).map(([key, entry]) => [key, clone(entry)]));
+  }
+  return value;
+}
+
+/** @param {[string, unknown]} left @param {[string, unknown]} right */
+function byEntryKey(left, right) {
+  return left[0].localeCompare(right[0]);
+}
+
+function escapePointer(value) {
+  return value.split("~").join("~0").split("/").join("~1");
+}

package/src/migration/v2-files.mjs

@@ -0,0 +1,211 @@
+import { createHash, randomUUID } from "node:crypto";
+import { chmod, lstat, mkdir, open, readFile, realpath, rename, rm, stat } from "node:fs/promises";
+import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
+
+export async function createBackup(configPath, configBytes, inventoryPath, inventoryBytes, label = "v1") {
+  const stamp = new Date().toISOString().split(":").join("-");
+  const unique = randomUUID().slice(0, 8);
+  const configBackupPath = `${configPath}.${label}-${stamp}-${unique}.bak`;
+  const inventoryBackupPath = inventoryBytes === null ? null : `${configBackupPath}.inventory`;
+  const manifestPath = `${configBackupPath}.manifest.json`;
+  const configMode = await fileMode(configPath);
+  const inventoryMode = inventoryBytes === null ? null : await fileMode(inventoryPath);
+  await durableCreate(configBackupPath, configBytes);
+  try {
+    if (inventoryBytes !== null) await durableCreate(inventoryBackupPath, inventoryBytes);
+    const manifest = {
+      format_version: 1,
+      source_version: 1,
+      target_version: 2,
+      policy_projection_version: 2,
+      invalidates: ["v1-action-id", "v1-guard-hook", "v1-lock-projection"],
+      target_config: basename(configPath),
+      target_inventory: relativeInventoryPath(configPath, inventoryPath),
+      config_backup: basename(configBackupPath),
+      inventory_backup: inventoryBackupPath === null ? null : basename(inventoryBackupPath),
+      inventory_existed: inventoryBytes !== null,
+      config_mode: configMode,
+      inventory_mode: inventoryMode,
+      input_sha256: sha256(configBytes),
+      inventory_input_sha256: inventoryBytes === null ? null : sha256(inventoryBytes)
+    };
+    await durableCreate(manifestPath, Buffer.from(`${JSON.stringify(manifest, null, 2)}\n`));
+    return {
+      configBackupPath,
+      inventoryBackupPath,
+      inventoryExisted: inventoryBytes !== null,
+      configMode,
+      inventoryMode,
+      manifestPath
+    };
+  } catch (error) {
+    await rm(configBackupPath, { force: true });
+    if (inventoryBackupPath !== null) await rm(inventoryBackupPath, { force: true });
+    await rm(manifestPath, { force: true });
+    throw error;
+  }
+}
+
+export async function restoreSnapshot(configPath, inventoryPath, snapshot, hooks = {}) {
+  await atomicWrite(configPath, await readFile(snapshot.configBackupPath), snapshot.configMode);
+  await hooks.afterConfigRename?.();
+  if (snapshot.inventoryExisted) {
+    await atomicWrite(inventoryPath, await readFile(snapshot.inventoryBackupPath), snapshot.inventoryMode);
+  } else {
+    await rm(inventoryPath, { force: true });
+    await syncDirectory(dirname(inventoryPath));
+  }
+  await hooks.afterInventoryRename?.();
+}
+
+export async function removeBackupSet(backup) {
+  await rm(backup.configBackupPath, { force: true });
+  if (backup.inventoryBackupPath !== null) await rm(backup.inventoryBackupPath, { force: true });
+  await rm(backup.manifestPath, { force: true });
+}
+
+export async function atomicWrite(path, bytes, mode = 0o600) {
+  await mkdir(dirname(path), { recursive: true });
+  const tempPath = join(dirname(path), `.${basename(path)}.${randomUUID()}.tmp`);
+  try {
+    await durableCreate(tempPath, bytes, mode);
+    await rename(tempPath, path);
+    await syncDirectory(dirname(path));
+  } finally {
+    await rm(tempPath, { force: true });
+  }
+}
+
+export async function optionalRead(path) {
+  try {
+    return await readFile(path);
+  } catch (error) {
+    if (error?.code === "ENOENT") return null;
+    throw error;
+  }
+}
+
+export async function removeDurably(path) {
+  await rm(path, { force: true });
+  await syncDirectory(dirname(path));
+}
+
+export async function withConfigLock(configPath, operation) {
+  const canonicalPath = await realpath(resolve(configPath));
+  const lockPath = `${canonicalPath}.migrate.lock`;
+  let handle;
+  try {
+    handle = await open(lockPath, "wx", 0o600);
+  } catch (error) {
+    if (error?.code === "EEXIST") {
+      throw new Error("Another migration is already using this config. Remove a stale .migrate.lock only after confirming no migration is running.");
+    }
+    throw error;
+  }
+  try {
+    await handle.writeFile(`${process.pid}\n`);
+    await handle.sync();
+    return await operation();
+  } finally {
+    await handle.close();
+    await rm(lockPath, { force: true });
+  }
+}
+
+export async function canonicalMigrationPaths(requestedConfigPath, requestedInventoryPath) {
+  const requested = resolve(requestedConfigPath);
+  const stats = await lstat(requested);
+  if (stats.isSymbolicLink()) {
+    throw new Error("Migration config path must not be a symbolic link; use its real path explicitly.");
+  }
+  if (!stats.isFile()) throw new Error("Migration config path must be a regular file.");
+  const configPath = await realpath(requested);
+  const root = dirname(configPath);
+  const requestedInventory = resolve(requestedInventoryPath ?? join(root, ".skillboard", "inventory.json"));
+  const inventoryStats = await lstat(requestedInventory).catch(missingOnly);
+  if (inventoryStats?.isSymbolicLink()) {
+    throw new Error("Migration inventory target must not be a symbolic link.");
+  }
+  const inventoryDirectory = dirname(requestedInventory);
+  const directoryStats = await lstat(inventoryDirectory).catch(missingOnly);
+  if (directoryStats?.isSymbolicLink()) {
+    throw new Error("Migration inventory directory must not be a symbolic link.");
+  }
+  const existingParent = await nearestExistingDirectory(inventoryDirectory);
+  const realParent = await realpath(existingParent);
+  const inventoryPath = resolve(realParent, relative(existingParent, requestedInventory));
+  if (!isPathInside(root, realParent)) {
+    throw new Error("Migration inventory target resolves outside the config directory.");
+  }
+  if (!isPathInside(root, inventoryPath)) {
+    throw new Error("Migration inventory target must remain inside the config directory.");
+  }
+  return { configPath, inventoryPath };
+}
+
+export function sha256(bytes) {
+  return createHash("sha256").update(bytes).digest("hex");
+}
+
+export async function durableCreate(path, bytes, mode = 0o600) {
+  await mkdir(dirname(path), { recursive: true });
+  const handle = await open(path, "wx", mode);
+  try {
+    await handle.writeFile(bytes);
+    await chmod(path, mode);
+    await handle.sync();
+  } finally {
+    await handle.close();
+  }
+}
+
+export async function syncDirectory(path) {
+  if (process.platform === "win32") return;
+  let handle;
+  try {
+    handle = await open(path, "r");
+  } catch (error) {
+    if (error?.code === "ENOENT") return;
+    throw error;
+  }
+  try {
+    await handle.sync();
+  } finally {
+    await handle.close();
+  }
+}
+
+export function relativeInventoryPath(configPath, inventoryPath) {
+  const prefix = `${dirname(configPath)}/`;
+  return inventoryPath.startsWith(prefix) ? inventoryPath.slice(prefix.length) : basename(inventoryPath);
+}
+
+async function fileMode(path) {
+  return (await stat(path)).mode & 0o777;
+}
+
+async function nearestExistingDirectory(start) {
+  let candidate = start;
+  while (true) {
+    const stats = await lstat(candidate).catch(missingOnly);
+    if (stats !== undefined) {
+      if (!stats.isDirectory() && !stats.isSymbolicLink()) {
+        throw new Error("Migration inventory parent must be a directory.");
+      }
+      return candidate;
+    }
+    const parent = dirname(candidate);
+    if (parent === candidate) throw new Error("Migration inventory parent does not exist.");
+    candidate = parent;
+  }
+}
+
+function missingOnly(error) {
+  if (error?.code === "ENOENT") return undefined;
+  throw error;
+}
+
+function isPathInside(root, candidate) {
+  const rel = relative(root, candidate);
+  return rel === "" || (!rel.startsWith("..") && !isAbsolute(rel));
+}