@isaacriehm/cairn-core 0.19.1 → 0.22.0

package/dist/migrate/gitignore.js

@@ -0,0 +1,82 @@
+/**
+ * Shared `.cairn/.gitignore` remediation — used by `cairn fix gitignore` AND
+ * the `0002-backfill-gitignore` migration.
+ *
+ * Cairn added gitignored derived/per-clone state across several releases
+ * (v0.11.3 tasks/missions, v0.15.0 derived ground indexes, v0.18.0 component
+ * index). A repo adopted before an entry landed both (a) lacks the ignore line
+ * and (b) may have COMMITTED the derived state, which then churns on every
+ * clone. Remediation = bring `.cairn/.gitignore` current (merge — never clobber
+ * operator lines) and `git rm --cached` any now-ignored, already-tracked paths.
+ * Idempotent: a second run adds nothing and untracks nothing.
+ */
+import { execFileSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { cairnDir, writeFileSafe } from "@isaacriehm/cairn-state";
+import { templatesRoot } from "../init/seed.js";
+/** Non-comment, non-blank trimmed lines. */
+function entryLines(text) {
+    return text
+        .split("\n")
+        .map((l) => l.trim())
+        .filter((l) => l.length > 0 && !l.startsWith("#"));
+}
+/** Of the template entries, the tracked-in-git file paths under them. */
+function trackedUnder(repoRoot, entries) {
+    if (entries.length === 0)
+        return [];
+    const targets = entries.map((e) => join(".cairn", e));
+    try {
+        const out = execFileSync("git", ["ls-files", "-z", "--", ...targets], {
+            cwd: repoRoot,
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+        });
+        return out.split("\0").filter((p) => p.length > 0);
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Bring `.cairn/.gitignore` current with the bundled template and (apply mode)
+ * untrack any now-ignored committed state. `apply: false` is a pure read used
+ * by the migration's `detect()`.
+ */
+export function remediateGitignore(repoRoot, opts) {
+    const result = { changed: false, addedEntries: [], untracked: [] };
+    const templatePath = join(templatesRoot(), ".cairn", ".gitignore");
+    const gitignorePath = cairnDir(repoRoot, ".gitignore");
+    if (!existsSync(templatePath) || !existsSync(gitignorePath))
+        return result;
+    const template = readFileSync(templatePath, "utf8");
+    const current = readFileSync(gitignorePath, "utf8");
+    const have = new Set(entryLines(current));
+    const templateEntries = entryLines(template);
+    result.addedEntries = templateEntries.filter((e) => !have.has(e));
+    result.untracked = trackedUnder(repoRoot, templateEntries);
+    result.changed = result.addedEntries.length > 0 || result.untracked.length > 0;
+    if (!opts.apply || !result.changed)
+        return result;
+    if (result.addedEntries.length > 0) {
+        const sep = current.endsWith("\n") ? "" : "\n";
+        const block = `${sep}\n# --- backfilled by cairn migrate (0002-backfill-gitignore) ---\n` +
+            `${result.addedEntries.join("\n")}\n`;
+        writeFileSafe(gitignorePath, current + block);
+    }
+    if (result.untracked.length > 0) {
+        // Untrack so the committed derived state drops out of the index. The
+        // working-tree copy stays (rebuildDerived rewrites it); only the tracking
+        // is removed. Best-effort — a git failure leaves the file ignored anyway.
+        const targets = result.untracked.slice();
+        try {
+            execFileSync("git", ["rm", "--cached", "-r", "--ignore-unmatch", "--", ...targets], { cwd: repoRoot, encoding: "utf8", stdio: ["ignore", "ignore", "ignore"] });
+        }
+        catch {
+            /* best-effort */
+        }
+    }
+    return result;
+}
+//# sourceMappingURL=gitignore.js.map

package/dist/migrate/gitignore.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gitignore.js","sourceRoot":"","sources":["../../src/migrate/gitignore.ts"],"names":[],"mappings":"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"}

package/dist/migrate/index.d.ts

@@ -0,0 +1,6 @@
+export type { Migration, MigrationClass, MigrationResult } from "./types.js";
+export { MIGRATIONS } from "./registry.js";
+export { runMigrations, type RunMigrationsArgs, type RunMigrationsResult, type MigrationOutcome, type MigrationStatus, } from "./runner.js";
+export { readConfigPin } from "./config-io.js";
+export { remediateGitignore, type GitignoreRemediation } from "./gitignore.js";
+export { semverCmp, semverGt, semverLte } from "./semver.js";

package/dist/migrate/index.js

@@ -0,0 +1,6 @@
+export { MIGRATIONS } from "./registry.js";
+export { runMigrations, } from "./runner.js";
+export { readConfigPin } from "./config-io.js";
+export { remediateGitignore } from "./gitignore.js";
+export { semverCmp, semverGt, semverLte } from "./semver.js";
+//# sourceMappingURL=index.js.map

package/dist/migrate/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/migrate/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAC3C,OAAO,EACL,aAAa,GAKd,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAC/C,OAAO,EAAE,kBAAkB,EAA6B,MAAM,gBAAgB,CAAC;AAC/E,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC"}

package/dist/migrate/migrations/0001-drop-dead-config-fields.d.ts

@@ -0,0 +1,12 @@
+/**
+ * 0001 — drop dead `config.yaml` fields.
+ *
+ * These keys were written at adoption but have no runtime reader (audit
+ * Tier 2 + the proposed-sensors GUT). Removing them from existing adopters
+ * is value-preserving (nothing consumes them), so this is a `safe` migration.
+ * New adoptions stop emitting them at the source (init/overlay.ts).
+ */
+import type { Migration } from "../types.js";
+/** Top-level config keys with no runtime consumer. */
+export declare const DEAD_CONFIG_KEYS: readonly ["detected_sensor_commands", "mapper_proposed_sensors", "mapper_notes", "key_modules", "stack_signatures", "hook_capability", "start_command", "origin_url"];
+export declare const dropDeadConfigFields: Migration;

package/dist/migrate/migrations/0001-drop-dead-config-fields.js

@@ -0,0 +1,39 @@
+/**
+ * 0001 — drop dead `config.yaml` fields.
+ *
+ * These keys were written at adoption but have no runtime reader (audit
+ * Tier 2 + the proposed-sensors GUT). Removing them from existing adopters
+ * is value-preserving (nothing consumes them), so this is a `safe` migration.
+ * New adoptions stop emitting them at the source (init/overlay.ts).
+ */
+import { configHasKeys, deleteConfigKeys } from "../config-io.js";
+/** Top-level config keys with no runtime consumer. */
+export const DEAD_CONFIG_KEYS = [
+    "detected_sensor_commands",
+    "mapper_proposed_sensors",
+    "mapper_notes",
+    "key_modules",
+    "stack_signatures",
+    "hook_capability",
+    "start_command",
+    "origin_url",
+];
+export const dropDeadConfigFields = {
+    id: "0001-drop-dead-config-fields",
+    introducedIn: "0.21.0",
+    describe: "Remove unconsumed config.yaml keys (detected_sensor_commands, mapper_proposed_sensors, mapper_notes, key_modules, stack_signatures, hook_capability, start_command, origin_url)",
+    class: "safe",
+    detect(repoRoot, doc) {
+        return configHasKeys(repoRoot, DEAD_CONFIG_KEYS, doc).length > 0;
+    },
+    apply(repoRoot) {
+        const removed = deleteConfigKeys(repoRoot, DEAD_CONFIG_KEYS);
+        return {
+            changed: removed.length > 0,
+            detail: removed.length > 0
+                ? `removed ${removed.length} dead config key(s): ${removed.join(", ")}`
+                : "no dead config keys present",
+        };
+    },
+};
+//# sourceMappingURL=0001-drop-dead-config-fields.js.map

package/dist/migrate/migrations/0001-drop-dead-config-fields.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"0001-drop-dead-config-fields.js","sourceRoot":"","sources":["../../../src/migrate/migrations/0001-drop-dead-config-fields.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAElE,sDAAsD;AACtD,MAAM,CAAC,MAAM,gBAAgB,GAAG;IAC9B,0BAA0B;IAC1B,yBAAyB;IACzB,cAAc;IACd,aAAa;IACb,kBAAkB;IAClB,iBAAiB;IACjB,eAAe;IACf,YAAY;CACJ,CAAC;AAEX,MAAM,CAAC,MAAM,oBAAoB,GAAc;IAC7C,EAAE,EAAE,8BAA8B;IAClC,YAAY,EAAE,QAAQ;IACtB,QAAQ,EAAE,iLAAiL;IAC3L,KAAK,EAAE,MAAM;IACb,MAAM,CAAC,QAAgB,EAAE,GAAsB;QAC7C,OAAO,aAAa,CAAC,QAAQ,EAAE,gBAAgB,EAAE,GAAG,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC;IACnE,CAAC;IACD,KAAK,CAAC,QAAgB;QACpB,MAAM,OAAO,GAAG,gBAAgB,CAAC,QAAQ,EAAE,gBAAgB,CAAC,CAAC;QAC7D,OAAO;YACL,OAAO,EAAE,OAAO,CAAC,MAAM,GAAG,CAAC;YAC3B,MAAM,EACJ,OAAO,CAAC,MAAM,GAAG,CAAC;gBAChB,CAAC,CAAC,WAAW,OAAO,CAAC,MAAM,wBAAwB,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE;gBACvE,CAAC,CAAC,6BAA6B;SACpC,CAAC;IACJ,CAAC;CACF,CAAC"}

package/dist/migrate/migrations/0002-backfill-gitignore.d.ts

@@ -0,0 +1,14 @@
+/**
+ * 0002 — backfill `.cairn/.gitignore` + untrack committed derived state.
+ *
+ * Repos adopted before the relevant releases (tasks/missions v0.11.3, derived
+ * ground indexes v0.15.0, component index v0.18.0) lack the ignore lines and
+ * may have COMMITTED per-clone derived state that then churns across clones.
+ *
+ * `review` (not `safe`): apply runs `git rm --cached`, mutating the git index —
+ * a VCS change the operator confirms via `cairn migrate --all`, never silently
+ * at SessionStart. Detect/apply share `remediateGitignore` with the
+ * `cairn fix gitignore` CLI, and both are idempotent.
+ */
+import type { Migration } from "../types.js";
+export declare const backfillGitignore: Migration;

package/dist/migrate/migrations/0002-backfill-gitignore.js

@@ -0,0 +1,40 @@
+/**
+ * 0002 — backfill `.cairn/.gitignore` + untrack committed derived state.
+ *
+ * Repos adopted before the relevant releases (tasks/missions v0.11.3, derived
+ * ground indexes v0.15.0, component index v0.18.0) lack the ignore lines and
+ * may have COMMITTED per-clone derived state that then churns across clones.
+ *
+ * `review` (not `safe`): apply runs `git rm --cached`, mutating the git index —
+ * a VCS change the operator confirms via `cairn migrate --all`, never silently
+ * at SessionStart. Detect/apply share `remediateGitignore` with the
+ * `cairn fix gitignore` CLI, and both are idempotent.
+ */
+import { remediateGitignore } from "../gitignore.js";
+export const backfillGitignore = {
+    id: "0002-backfill-gitignore",
+    // Ships in 0.22.0 → runs for every pin < 0.22.0 (catches 0.21 adopters who
+    // upgraded from <0.15 and got 0001 but never a gitignore backfill). Bump in
+    // lockstep with the release that lands this.
+    introducedIn: "0.22.0",
+    describe: "Backfill .cairn/.gitignore (derived ground indexes, component index, per-clone state) and untrack derived state committed before it was gitignored — repos adopted before v0.15.0/v0.18.0",
+    class: "review",
+    detect(repoRoot) {
+        return remediateGitignore(repoRoot, { apply: false }).changed;
+    },
+    apply(repoRoot) {
+        const r = remediateGitignore(repoRoot, { apply: true });
+        const parts = [];
+        if (r.addedEntries.length > 0) {
+            parts.push(`added ${r.addedEntries.length} ignore entr${r.addedEntries.length === 1 ? "y" : "ies"}`);
+        }
+        if (r.untracked.length > 0) {
+            parts.push(`untracked ${r.untracked.length} committed derived file(s)`);
+        }
+        return {
+            changed: r.changed,
+            detail: r.changed ? parts.join("; ") : "nothing to backfill",
+        };
+    },
+};
+//# sourceMappingURL=0002-backfill-gitignore.js.map

package/dist/migrate/migrations/0002-backfill-gitignore.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"0002-backfill-gitignore.js","sourceRoot":"","sources":["../../../src/migrate/migrations/0002-backfill-gitignore.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAErD,MAAM,CAAC,MAAM,iBAAiB,GAAc;IAC1C,EAAE,EAAE,yBAAyB;IAC7B,2EAA2E;IAC3E,4EAA4E;IAC5E,6CAA6C;IAC7C,YAAY,EAAE,QAAQ;IACtB,QAAQ,EACN,2LAA2L;IAC7L,KAAK,EAAE,QAAQ;IACf,MAAM,CAAC,QAAgB;QACrB,OAAO,kBAAkB,CAAC,QAAQ,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC,OAAO,CAAC;IAChE,CAAC;IACD,KAAK,CAAC,QAAgB;QACpB,MAAM,CAAC,GAAG,kBAAkB,CAAC,QAAQ,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;QACxD,MAAM,KAAK,GAAa,EAAE,CAAC;QAC3B,IAAI,CAAC,CAAC,YAAY,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC9B,KAAK,CAAC,IAAI,CACR,SAAS,CAAC,CAAC,YAAY,CAAC,MAAM,eAAe,CAAC,CAAC,YAAY,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,KAAK,EAAE,CACzF,CAAC;QACJ,CAAC;QACD,IAAI,CAAC,CAAC,SAAS,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC3B,KAAK,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,SAAS,CAAC,MAAM,4BAA4B,CAAC,CAAC;QAC1E,CAAC;QACD,OAAO;YACL,OAAO,EAAE,CAAC,CAAC,OAAO;YAClB,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,qBAAqB;SAC7D,CAAC;IACJ,CAAC;CACF,CAAC"}

package/dist/migrate/registry.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Ordered migration registry. New migrations append here, tagged with the
+ * `introducedIn` version that requires their state shape.
+ *
+ * Release gate: any release that changes the `.cairn/` contract must ship a
+ * migration here and link it from CHANGELOG.
+ */
+import type { Migration } from "./types.js";
+export declare const MIGRATIONS: readonly Migration[];

package/dist/migrate/registry.js

@@ -0,0 +1,11 @@
+/**
+ * Ordered migration registry. New migrations append here, tagged with the
+ * `introducedIn` version that requires their state shape.
+ *
+ * Release gate: any release that changes the `.cairn/` contract must ship a
+ * migration here and link it from CHANGELOG.
+ */
+import { dropDeadConfigFields } from "./migrations/0001-drop-dead-config-fields.js";
+import { backfillGitignore } from "./migrations/0002-backfill-gitignore.js";
+export const MIGRATIONS = [dropDeadConfigFields, backfillGitignore];
+//# sourceMappingURL=registry.js.map

package/dist/migrate/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../src/migrate/registry.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,EAAE,oBAAoB,EAAE,MAAM,8CAA8C,CAAC;AACpF,OAAO,EAAE,iBAAiB,EAAE,MAAM,yCAAyC,CAAC;AAE5E,MAAM,CAAC,MAAM,UAAU,GAAyB,CAAC,oBAAoB,EAAE,iBAAiB,CAAC,CAAC"}

package/dist/migrate/runner.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Migration runner — select, apply, stamp.
+ *
+ * Selection: migrations whose `introducedIn` is in `(pin, current]` and whose
+ * `detect()` still reports the repo needs them. `safe` migrations auto-apply;
+ * `review` migrations are queued for the operator unless `includeReview`.
+ *
+ * The `cairn_version` pin is an optimization, not the source of truth —
+ * `detect()` carries correctness, so a wrong/absent pin never causes a
+ * re-mutation. On success the pin advances to the highest fully-applied
+ * version (and all the way to `current` when nothing is left pending), which
+ * is what turns the frozen `cairn_version` pin into a live one.
+ *
+ * Concurrency: the apply phase holds `.migrate-lock`; a second session bails
+ * cleanly (`ran: false`) rather than racing.
+ */
+import type { MigrationClass } from "./types.js";
+export type MigrationStatus = "applied" | "noop" | "queued" | "failed" | "would-apply" | "would-queue";
+export interface MigrationOutcome {
+    id: string;
+    class: MigrationClass;
+    status: MigrationStatus;
+    detail: string;
+}
+export interface RunMigrationsArgs {
+    repoRoot: string;
+    /** Report what would run; apply nothing, write nothing. */
+    dryRun?: boolean;
+    /** Auto-apply `review`-class too (operator-confirmed `cairn migrate --all`). */
+    includeReview?: boolean;
+}
+export interface RunMigrationsResult {
+    /** False only when another process held the migrate lock. */
+    ran: boolean;
+    /** Pin before the run (`0.0.0` when absent). */
+    pin: string;
+    /** Current CLI version. */
+    current: string;
+    /** Pin after the run, or null when unchanged / not written. */
+    newPin: string | null;
+    outcomes: MigrationOutcome[];
+    /** `review`-class migration ids that still need the operator. */
+    pendingReview: string[];
+}
+export declare function runMigrations(args: RunMigrationsArgs): Promise<RunMigrationsResult>;

package/dist/migrate/runner.js

@@ -0,0 +1,177 @@
+/**
+ * Migration runner — select, apply, stamp.
+ *
+ * Selection: migrations whose `introducedIn` is in `(pin, current]` and whose
+ * `detect()` still reports the repo needs them. `safe` migrations auto-apply;
+ * `review` migrations are queued for the operator unless `includeReview`.
+ *
+ * The `cairn_version` pin is an optimization, not the source of truth —
+ * `detect()` carries correctness, so a wrong/absent pin never causes a
+ * re-mutation. On success the pin advances to the highest fully-applied
+ * version (and all the way to `current` when nothing is left pending), which
+ * is what turns the frozen `cairn_version` pin into a live one.
+ *
+ * Concurrency: the apply phase holds `.migrate-lock`; a second session bails
+ * cleanly (`ran: false`) rather than racing.
+ */
+import { existsSync } from "node:fs";
+import { VERSION } from "../index.js";
+import { logger } from "../logger.js";
+import { acquireOperationLock, OperationLockHeldError } from "../lock.js";
+import { loadConfigDoc, readConfigPin, writeConfigPin } from "./config-io.js";
+import { MIGRATIONS } from "./registry.js";
+import { semverCmp, semverGt, semverLte } from "./semver.js";
+import { cairnDir } from "@isaacriehm/cairn-state";
+const log = logger("migrate.runner");
+function needs(m, repoRoot, doc) {
+    try {
+        return m.detect(repoRoot, doc);
+    }
+    catch (err) {
+        log.warn({ migration: m.id, err: err instanceof Error ? err.message : String(err) }, "migration detect() threw — skipping");
+        return false;
+    }
+}
+/**
+ * Migrations introduced in `(pin, current]` that still report needed. `doc` is
+ * the once-parsed `config.yaml` shared across this read-only selection pass.
+ */
+function selectCandidates(repoRoot, pin, current, doc) {
+    return MIGRATIONS.filter((m) => semverGt(m.introducedIn, pin) && semverLte(m.introducedIn, current))
+        .filter((m) => needs(m, repoRoot, doc))
+        .slice()
+        .sort((a, b) => semverCmp(a.introducedIn, b.introducedIn) || a.id.localeCompare(b.id));
+}
+export async function runMigrations(args) {
+    const { repoRoot } = args;
+    const current = VERSION;
+    const dryRun = args.dryRun === true;
+    const includeReview = args.includeReview === true;
+    // Never act on an unadopted repo — guards against any caller (notably the
+    // defensive MCP-boot run) creating `.cairn/` via the lock's mkdir.
+    if (!existsSync(cairnDir(repoRoot, "config.yaml"))) {
+        return { ran: true, pin: "0.0.0", current, newPin: null, outcomes: [], pendingReview: [] };
+    }
+    // Parse config.yaml once for the whole read-only selection phase (pin read +
+    // each candidate's detect). The apply phase re-reads fresh, since a migration
+    // may mutate the file mid-run.
+    const doc = loadConfigDoc(repoRoot);
+    const pin = readConfigPin(repoRoot, doc) ?? "0.0.0";
+    const candidates = selectCandidates(repoRoot, pin, current, doc);
+    // Nothing pending: make the pin live if it's merely stale, else no-op.
+    if (candidates.length === 0) {
+        if (semverCmp(pin, current) >= 0) {
+            return { ran: true, pin, current, newPin: null, outcomes: [], pendingReview: [] };
+        }
+        if (dryRun) {
+            return { ran: true, pin, current, newPin: current, outcomes: [], pendingReview: [] };
+        }
+        try {
+            const wrote = await acquireOperationLock(repoRoot, ".migrate-lock", () => writeConfigPin(repoRoot, current));
+            return {
+                ran: true,
+                pin,
+                current,
+                newPin: wrote ? current : null,
+                outcomes: [],
+                pendingReview: [],
+            };
+        }
+        catch (err) {
+            if (err instanceof OperationLockHeldError) {
+                return { ran: false, pin, current, newPin: null, outcomes: [], pendingReview: [] };
+            }
+            throw err;
+        }
+    }
+    if (dryRun) {
+        const outcomes = candidates.map((m) => ({
+            id: m.id,
+            class: m.class,
+            status: m.class === "review" && !includeReview ? "would-queue" : "would-apply",
+            detail: m.describe,
+        }));
+        const pendingReview = candidates
+            .filter((m) => m.class === "review" && !includeReview)
+            .map((m) => m.id);
+        return { ran: true, pin, current, newPin: null, outcomes, pendingReview };
+    }
+    try {
+        return await acquireOperationLock(repoRoot, ".migrate-lock", () => applyCandidates({ repoRoot, pin, current, candidates, includeReview }));
+    }
+    catch (err) {
+        if (err instanceof OperationLockHeldError) {
+            return { ran: false, pin, current, newPin: null, outcomes: [], pendingReview: [] };
+        }
+        throw err;
+    }
+}
+function applyCandidates(args) {
+    const { repoRoot, pin, current, candidates, includeReview } = args;
+    const outcomes = [];
+    const pendingReview = [];
+    let firstUnresolved = -1;
+    for (let i = 0; i < candidates.length; i++) {
+        const m = candidates[i];
+        if (m === undefined)
+            continue;
+        // Re-check under the lock for idempotency under concurrency.
+        if (!needs(m, repoRoot)) {
+            outcomes.push({ id: m.id, class: m.class, status: "noop", detail: "already satisfied" });
+            continue;
+        }
+        if (m.class === "review" && !includeReview) {
+            outcomes.push({ id: m.id, class: m.class, status: "queued", detail: m.describe });
+            pendingReview.push(m.id);
+            if (firstUnresolved === -1)
+                firstUnresolved = i;
+            continue;
+        }
+        try {
+            const r = m.apply(repoRoot);
+            outcomes.push({
+                id: m.id,
+                class: m.class,
+                status: r.changed ? "applied" : "noop",
+                detail: r.detail,
+            });
+        }
+        catch (err) {
+            outcomes.push({
+                id: m.id,
+                class: m.class,
+                status: "failed",
+                detail: err instanceof Error ? err.message : String(err),
+            });
+            if (firstUnresolved === -1)
+                firstUnresolved = i;
+        }
+    }
+    // Advance the pin to the highest version with no unresolved predecessor.
+    let target = pin;
+    if (firstUnresolved === -1) {
+        target = current;
+    }
+    else {
+        for (let i = 0; i < firstUnresolved; i++) {
+            const m = candidates[i];
+            if (m !== undefined && semverGt(m.introducedIn, target))
+                target = m.introducedIn;
+        }
+    }
+    let newPin = null;
+    if (semverCmp(target, pin) > 0) {
+        if (writeConfigPin(repoRoot, target))
+            newPin = target;
+    }
+    log.info({
+        pin,
+        current,
+        new_pin: newPin,
+        applied: outcomes.filter((o) => o.status === "applied").length,
+        queued: pendingReview.length,
+        failed: outcomes.filter((o) => o.status === "failed").length,
+    }, "migrations run");
+    return { ran: true, pin, current, newPin, outcomes, pendingReview };
+}
+//# sourceMappingURL=runner.js.map

package/dist/migrate/runner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runner.js","sourceRoot":"","sources":["../../src/migrate/runner.ts"],"names":[],"mappings":"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"}

package/dist/migrate/semver.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Minimal semver comparison for migration selection. No external dep.
+ *
+ * Parses `MAJOR.MINOR.PATCH` (ignoring any `-prerelease` / `+build` suffix)
+ * and compares numerically. Non-conforming strings sort as `0.0.0`, which is
+ * the conservative choice for an absent / malformed pin (everything pending).
+ */
+/** -1 if a<b, 0 if equal, 1 if a>b. */
+export declare function semverCmp(a: string, b: string): number;
+export declare function semverGt(a: string, b: string): boolean;
+export declare function semverLte(a: string, b: string): boolean;

package/dist/migrate/semver.js

@@ -0,0 +1,35 @@
+/**
+ * Minimal semver comparison for migration selection. No external dep.
+ *
+ * Parses `MAJOR.MINOR.PATCH` (ignoring any `-prerelease` / `+build` suffix)
+ * and compares numerically. Non-conforming strings sort as `0.0.0`, which is
+ * the conservative choice for an absent / malformed pin (everything pending).
+ */
+function parse(v) {
+    const core = v.trim().split(/[-+]/)[0] ?? "";
+    const parts = core.split(".");
+    const n = (i) => {
+        const x = Number.parseInt(parts[i] ?? "0", 10);
+        return Number.isFinite(x) ? x : 0;
+    };
+    return [n(0), n(1), n(2)];
+}
+/** -1 if a<b, 0 if equal, 1 if a>b. */
+export function semverCmp(a, b) {
+    const pa = parse(a);
+    const pb = parse(b);
+    for (let i = 0; i < 3; i++) {
+        const x = pa[i] ?? 0;
+        const y = pb[i] ?? 0;
+        if (x !== y)
+            return x < y ? -1 : 1;
+    }
+    return 0;
+}
+export function semverGt(a, b) {
+    return semverCmp(a, b) > 0;
+}
+export function semverLte(a, b) {
+    return semverCmp(a, b) <= 0;
+}
+//# sourceMappingURL=semver.js.map

package/dist/migrate/semver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"semver.js","sourceRoot":"","sources":["../../src/migrate/semver.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,SAAS,KAAK,CAAC,CAAS;IACtB,MAAM,IAAI,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IAC7C,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC9B,MAAM,CAAC,GAAG,CAAC,CAAS,EAAU,EAAE;QAC9B,MAAM,CAAC,GAAG,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,GAAG,EAAE,EAAE,CAAC,CAAC;QAC/C,OAAO,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACpC,CAAC,CAAC;IACF,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAC5B,CAAC;AAED,uCAAuC;AACvC,MAAM,UAAU,SAAS,CAAC,CAAS,EAAE,CAAS;IAC5C,MAAM,EAAE,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;IACpB,MAAM,EAAE,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;IACpB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;QAC3B,MAAM,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;QACrB,MAAM,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;QACrB,IAAI,CAAC,KAAK,CAAC;YAAE,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACrC,CAAC;IACD,OAAO,CAAC,CAAC;AACX,CAAC;AAED,MAAM,UAAU,QAAQ,CAAC,CAAS,EAAE,CAAS;IAC3C,OAAO,SAAS,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC;AAC7B,CAAC;AAED,MAAM,UAAU,SAAS,CAAC,CAAS,EAAE,CAAS;IAC5C,OAAO,SAAS,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC;AAC9B,CAAC"}

package/dist/migrate/types.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Coded `.cairn/` migration registry — types.
+ *
+ * Cairn upgrades constantly but on-disk `.cairn/` state does not move with
+ * it. A migration is a versioned, idempotent repair: detect whether a repo
+ * still needs the new state shape, then apply it. The runner selects pending
+ * migrations by semver against the `cairn_version` pin, applies the `safe`
+ * class automatically, and surfaces the `review` class for operator triage.
+ *
+ * See docs/MIGRATION_FEATURE_EVAL.md.
+ */
+export interface MigrationResult {
+    /** True when apply() actually mutated `.cairn/`. */
+    changed: boolean;
+    /** One-line human summary of what changed (or why nothing did). */
+    detail: string;
+}
+/**
+ * `safe`   — additive or derived-only: add a missing default key, drop an
+ *            unconsumed key, rebuild a gitignored derived index, stamp a
+ *            marker. Auto-applied silently (incl. at SessionStart).
+ * `review` — rewrites source, drops data, or makes a judgement call (brand
+ *            re-derive, source strip). Never auto-applied; surfaced for the
+ *            operator to run via `cairn migrate`.
+ */
+export type MigrationClass = "safe" | "review";
+export interface Migration {
+    /** Stable id, e.g. "0001-drop-dead-config-fields". */
+    id: string;
+    /** Semver of the Cairn release that REQUIRES this state shape. */
+    introducedIn: string;
+    /** One-line description, surfaced to the operator + linkable from CHANGELOG. */
+    describe: string;
+    class: MigrationClass;
+    /**
+     * Idempotent: true when this repo still needs the migration. The runner may
+     * pass `doc` — `config.yaml` parsed once for the whole selection phase — so a
+     * config-shape detect can skip re-parsing. Migrations that read other state
+     * ignore it. Never passed during the post-apply re-check (the file may have
+     * changed), so a detect handed no `doc` must read fresh.
+     */
+    detect(repoRoot: string, doc?: ConfigDoc | null): boolean;
+    /** Apply. Must be idempotent and atomic per migration. */
+    apply(repoRoot: string): MigrationResult;
+}
+/** Opaque parsed-`config.yaml` handle threaded through `detect` (yaml Document). */
+export type ConfigDoc = import("yaml").Document;

package/dist/migrate/types.js

@@ -0,0 +1,13 @@
+/**
+ * Coded `.cairn/` migration registry — types.
+ *
+ * Cairn upgrades constantly but on-disk `.cairn/` state does not move with
+ * it. A migration is a versioned, idempotent repair: detect whether a repo
+ * still needs the new state shape, then apply it. The runner selects pending
+ * migrations by semver against the `cairn_version` pin, applies the `safe`
+ * class automatically, and surfaces the `review` class for operator triage.
+ *
+ * See docs/MIGRATION_FEATURE_EVAL.md.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/migrate/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/migrate/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG"}