@tpsdev-ai/flair 0.21.0 → 0.22.1

package/dist/resources/migrations/runner.js

@@ -0,0 +1,455 @@
+/**
+ * runner.ts — the migration cycle orchestrator. One call to
+ * `runMigrationCycle()` = one full pass: detect pending migrations → (if
+ * any) one shared async pre-hash → per-migration pre-flight ladder →
+ * risk-scoped snapshot → throttled batches with per-row markers →
+ * risk-scoped completion gate → post-hash comparison → ledger OrgEvent →
+ * state-file update → snapshot prune.
+ *
+ * Halt-don't-brick everywhere (flair#695 invariant
+ * II): this function NEVER throws — every failure mode (space-blocked,
+ * snapshot-failed, pre-hash-failed, gate-failed, an unexpected exception)
+ * resolves to a halted/failed progress entry + (where applicable) a ledger
+ * event, and the loop moves on to the next migration rather than
+ * propagating. The caller (resources/MigrationBoot.ts) is the boot path —
+ * an exception escaping this function would risk destabilizing an
+ * already-serving process, which is exactly what invariant II forbids.
+ */
+import { acquireMigrationLock } from "./lock.js";
+import { checkSpace, defaultSpaceProbe } from "./space.js";
+import { createMigrationSnapshot, pruneMigrationSnapshots } from "./snapshot.js";
+import { createContentOnlyExport } from "./export.js";
+import { computeCorpusEnvelope } from "./envelope.js";
+import { hashSourceFields, sourceFieldsFor } from "./source-fields.js";
+import { postureFor } from "./risk-policy.js";
+import { readMigrationState, writeMigrationStateEntry, isShortCircuited, defaultStatePath } from "./state.js";
+import { writeLedgerEvent } from "./ledger.js";
+import { setCyclePhase, setMigrationProgress, seedIdleProgress } from "./progress.js";
+import { shouldRegisterSyntheticMigration } from "./synthetic-test-migration.js";
+import { join } from "node:path";
+/**
+ * Test-only batch-throttle override, mirroring space.ts's
+ * FLAIR_MIGRATION_TEST_FREE_BYTES pattern (real Harper is a spawned child
+ * process in the integration tests — an env var propagated at spawn time is
+ * the only injection lever available there). Used by
+ * test/integration/migrations-resume-after-kill.test.ts to WIDEN the
+ * per-batch delay so the migration's running phase spans seconds instead of
+ * a few hundred milliseconds, making "kill it mid-flight" deterministic
+ * rather than a poll-timing race (the CI failure mode this fixes: on a slow
+ * shared runner, the whole running phase fit between two health polls).
+ *
+ * DOUBLE-GATED: honored ONLY when the synthetic CI-migration gate
+ * (FLAIR_ENABLE_TEST_MIGRATIONS === "1", the same exact-match opt-in that
+ * admits the synthetic migration itself) is active — a stray env var on a
+ * production deployment (gate off) can never alter the real 100ms throttle.
+ */
+export const TEST_BATCH_DELAY_ENV = "FLAIR_MIGRATION_TEST_BATCH_DELAY_MS";
+function resolveTestBatchDelayMs(env = process.env) {
+    if (!shouldRegisterSyntheticMigration(env))
+        return undefined;
+    const raw = env[TEST_BATCH_DELAY_ENV];
+    if (raw === undefined)
+        return undefined;
+    const n = Number(raw);
+    return Number.isFinite(n) && n >= 0 ? n : undefined;
+}
+function resolveDeps(deps) {
+    const dataDir = deps.dataDir;
+    return {
+        registry: deps.registry,
+        getTable: deps.getTable,
+        dataDir,
+        runningVersion: deps.runningVersion,
+        statePath: deps.statePath ?? defaultStatePath(dataDir),
+        lockPath: deps.lockPath ?? join(dataDir, ".migrations", "lock"),
+        snapshotRoot: deps.snapshotRoot ?? join(dataDir, ".migrations", "snapshots"),
+        exportRoot: deps.exportRoot ?? join(dataDir, ".migrations", "exports"),
+        spaceProbe: deps.spaceProbe ?? defaultSpaceProbe,
+        now: deps.now ?? (() => new Date()),
+        sleep: deps.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms))),
+        ledgerDeps: deps.ledgerDeps ?? {},
+        batchDelayMs: deps.batchDelayMs ?? resolveTestBatchDelayMs() ?? 100,
+        initiator: deps.initiator ?? "auto",
+    };
+}
+// ─── space/snapshot sizing heuristics (overridable via RunnerDeps in future if ever needed) ──
+function estimateSnapshotBytes(scope, pendingCount) {
+    switch (scope) {
+        case "metadata-only":
+            return 4096;
+        case "schema+metadata":
+            return 8192;
+        case "pointers+metadata":
+            return 256 * Math.max(pendingCount, 1);
+    }
+}
+/**
+ * Kern verdict: "Space estimate includes HNSW rebuild overhead (re-embed
+ * rewrites every vector → index rebuild can be 2–3× raw vector size)." Uses
+ * a fixed per-row estimate (~6KB raw nomic-embed-text vector * 3) — a real
+ * per-corpus vector-size probe would be more precise but isn't needed for a
+ * conservative pre-flight gate; overestimating just makes the halt fire
+ * slightly earlier, which is the safe direction.
+ */
+function estimateWorkingSetBytes(riskClass, pendingCount) {
+    switch (riskClass) {
+        case "derived-only":
+            return 18 * 1024 * pendingCount; // ~3x a 768-dim float32 vector (~6KB) per touched row
+        case "schema-additive":
+            return 0; // additive-only — no row rewrites of source fields
+        case "content-transform":
+            return 4 * 1024 * pendingCount; // old+new temporarily coexist for touched rows
+    }
+}
+/**
+ * Runs one full migration cycle. Safe to call repeatedly (e.g. once per
+ * boot) — a cycle with nothing pending returns immediately without taking
+ * the lock's file-write cost or computing the envelope.
+ */
+export async function runMigrationCycle(rawDeps) {
+    const deps = resolveDeps(rawDeps);
+    const allIds = deps.registry.list().map((m) => m.id);
+    seedIdleProgress(allIds);
+    let lock;
+    try {
+        lock = acquireMigrationLock({ lockPath: deps.lockPath });
+    }
+    catch (err) {
+        // Even the lock's own filesystem calls must never crash the boot path.
+        return { ran: false, reason: `lock error: ${err?.message ?? String(err)}` };
+    }
+    if (!lock.acquired) {
+        return { ran: false, reason: `single-flight: ${lock.reason}` };
+    }
+    try {
+        return await runCycleLocked(deps, lock);
+    }
+    catch (err) {
+        // Belt-and-suspenders: runCycleLocked already halts individual
+        // migrations internally, but an error escaping it entirely (e.g. a bug)
+        // must still never propagate out of the boot path.
+        setCyclePhase("done", `unexpected cycle error: ${err?.message ?? String(err)}`);
+        return { ran: false, reason: `unexpected error: ${err?.message ?? String(err)}` };
+    }
+    finally {
+        lock.release();
+    }
+}
+async function runCycleLocked(deps, lock) {
+    const state = readMigrationState(deps.statePath);
+    const candidates = [];
+    for (const migration of deps.registry.list()) {
+        if (isShortCircuited(state, migration.id, deps.runningVersion)) {
+            setMigrationProgress({ id: migration.id, rowsDone: 0, rowsRemaining: 0, state: "completed" });
+            continue;
+        }
+        setMigrationProgress({ id: migration.id, rowsDone: 0, rowsRemaining: 0, state: "checking" });
+        let pending;
+        try {
+            pending = await migration.detect();
+        }
+        catch (err) {
+            setMigrationProgress({
+                id: migration.id,
+                rowsDone: 0,
+                rowsRemaining: 0,
+                state: "failed",
+                reason: `detect() threw: ${err?.message ?? String(err)}`,
+            });
+            continue;
+        }
+        if (!pending) {
+            setMigrationProgress({ id: migration.id, rowsDone: 0, rowsRemaining: 0, state: "completed" });
+            continue;
+        }
+        candidates.push(migration);
+    }
+    if (candidates.length === 0) {
+        return { ran: false, reason: "nothing pending" };
+    }
+    // ── ONE shared async pre-hash for the whole cycle (K&S: computed once,
+    // after ready, before any migration's first write; failure → halt all
+    // pending candidates rather than guessing which ones are safe). ──
+    setCyclePhase("pre-hash");
+    let envelope;
+    try {
+        envelope = await computeCorpusEnvelope(deps.getTable, deps.now);
+    }
+    catch (err) {
+        const reason = `pre-flight integrity check failed: ${err?.message ?? String(err)}`;
+        for (const migration of candidates) {
+            setMigrationProgress({ id: migration.id, rowsDone: 0, rowsRemaining: 0, state: "halted", reason });
+        }
+        setCyclePhase("done", reason);
+        return { ran: false, reason };
+    }
+    setCyclePhase("running");
+    for (const migration of candidates) {
+        await runOneMigration(migration, envelope, deps, lock);
+    }
+    setCyclePhase("done");
+    return { ran: true };
+}
+async function haltMigration(migration, reason, ctx) {
+    const { deps, startedAt, rowsDone, rowsRemaining, hashEnvelopeMatch, state } = ctx;
+    const endedAt = deps.now().toISOString();
+    setMigrationProgress({ id: migration.id, rowsDone, rowsRemaining, state: "halted", reason });
+    const fromVersion = state[migration.id]?.completedAtVersion ?? "unknown";
+    const evt = {
+        migrationId: migration.id,
+        initiator: deps.initiator,
+        fromVersion,
+        toVersion: deps.runningVersion,
+        scope: "full",
+        startedAt,
+        endedAt,
+        outcome: "halted",
+        rowsProcessed: rowsDone,
+        rowsRemaining,
+        hashEnvelopeMatch,
+        error: reason,
+    };
+    try {
+        await writeLedgerEvent(evt, deps.ledgerDeps);
+    }
+    catch {
+        // A ledger-write failure must not compound the halt — the migration is
+        // already safely stopped on the pre-migration shape either way.
+    }
+    // Deliberately NOT calling writeMigrationStateEntry with lastOutcome
+    // "halted" as completedAtVersion-bearing — isShortCircuited() only fires
+    // on lastOutcome === "success", so a halted migration is retried on every
+    // subsequent boot until it clears, never permanently stuck.
+    try {
+        writeMigrationStateEntry(deps.statePath, migration.id, {
+            lastOutcome: "halted",
+            reason,
+            rowsProcessed: rowsDone,
+            rowsRemaining,
+        });
+    }
+    catch {
+        /* best-effort — the in-memory progress + ledger event already recorded the halt */
+    }
+}
+async function runOneMigration(migration, envelope, deps, lock) {
+    const startedAt = deps.now().toISOString();
+    const state = readMigrationState(deps.statePath);
+    const posture = postureFor(migration.riskClass);
+    setMigrationProgress({ id: migration.id, rowsDone: 0, rowsRemaining: 0, state: "preflight" });
+    // ── Ladder step 1: space check (with HNSW/working-set overhead) ──
+    let initialRemaining;
+    try {
+        initialRemaining = await migration.countPending();
+    }
+    catch (err) {
+        await haltMigration(migration, `countPending() threw: ${err?.message ?? String(err)}`, {
+            deps,
+            startedAt,
+            rowsDone: 0,
+            rowsRemaining: 0,
+            hashEnvelopeMatch: null,
+            state,
+        });
+        return;
+    }
+    const estSnapshot = estimateSnapshotBytes(posture.snapshotScope, initialRemaining);
+    const estWorkingSet = estimateWorkingSetBytes(migration.riskClass, initialRemaining);
+    let space = checkSpace({ dataDir: deps.dataDir, estimatedSnapshotBytes: estSnapshot, estimatedWorkingSetBytes: estWorkingSet }, deps.spaceProbe);
+    if (!space.ok) {
+        // ── Ladder step 2: prune snapshots, then retry ──
+        pruneMigrationSnapshots(deps.snapshotRoot);
+        space = checkSpace({ dataDir: deps.dataDir, estimatedSnapshotBytes: estSnapshot, estimatedWorkingSetBytes: estWorkingSet }, deps.spaceProbe);
+    }
+    if (!space.ok) {
+        // ── Ladder step 5: no safe path → halt-don't-brick ──
+        await haltMigration(migration, `blocked on disk: ${space.reason}`, {
+            deps,
+            startedAt,
+            rowsDone: 0,
+            rowsRemaining: initialRemaining,
+            hashEnvelopeMatch: null,
+            state,
+        });
+        return;
+    }
+    // ── Ladder step 3 (+ step 4 fallback): risk-scoped snapshot, or a
+    // content-only export if the snapshot mechanism itself fails. ──
+    setMigrationProgress({ id: migration.id, rowsDone: 0, rowsRemaining: initialRemaining, state: "snapshotting" });
+    try {
+        createMigrationSnapshot({
+            migrationId: migration.id,
+            scope: posture.snapshotScope,
+            rowCounts: { [migration.affectsTables[0] ?? "Memory"]: initialRemaining },
+            fromVersion: state[migration.id]?.completedAtVersion ?? "unknown",
+            toVersion: deps.runningVersion,
+        }, { snapshotRoot: deps.snapshotRoot, now: deps.now });
+    }
+    catch (snapErr) {
+        try {
+            const table = migration.affectsTables[0] ?? "Memory";
+            const accessor = deps.getTable(table);
+            const rows = [];
+            for await (const row of accessor.search({}))
+                rows.push(row);
+            createContentOnlyExport({ migrationId: migration.id, table, rows, fromVersion: state[migration.id]?.completedAtVersion ?? "unknown" }, { exportRoot: deps.exportRoot, now: deps.now });
+        }
+        catch (expErr) {
+            await haltMigration(migration, `snapshot failed (${snapErr?.message ?? String(snapErr)}) and the content-only export fallback also failed (${expErr?.message ?? String(expErr)})`, { deps, startedAt, rowsDone: 0, rowsRemaining: initialRemaining, hashEnvelopeMatch: null, state });
+            return;
+        }
+    }
+    // ── Execution: throttled batches, resumable via per-row markers ──
+    setMigrationProgress({ id: migration.id, rowsDone: 0, rowsRemaining: initialRemaining, state: "running" });
+    let rowsDone = 0;
+    const oldRowHashes = new Map();
+    const newRowIds = [];
+    try {
+        for (;;) {
+            const result = await migration.run(posture.batchSize);
+            rowsDone += result.processed;
+            if (result.oldRowSourceHashes) {
+                for (const [k, v] of Object.entries(result.oldRowSourceHashes))
+                    oldRowHashes.set(k, v);
+            }
+            if (result.newRowIds)
+                newRowIds.push(...result.newRowIds);
+            setMigrationProgress({
+                id: migration.id,
+                rowsDone,
+                rowsRemaining: Math.max(0, initialRemaining - rowsDone),
+                state: "running",
+            });
+            lock.touch();
+            if (result.processed === 0)
+                break;
+            await deps.sleep(deps.batchDelayMs);
+        }
+    }
+    catch (err) {
+        await haltMigration(migration, `run() threw mid-batch: ${err?.message ?? String(err)}`, {
+            deps,
+            startedAt,
+            rowsDone,
+            rowsRemaining: Math.max(0, initialRemaining - rowsDone),
+            hashEnvelopeMatch: null,
+            state,
+        });
+        return;
+    }
+    // ── Completion gate — strictness per risk class ──
+    setMigrationProgress({ id: migration.id, rowsDone, rowsRemaining: 0, state: "completing" });
+    let finalRemaining;
+    try {
+        finalRemaining = await migration.countPending();
+    }
+    catch (err) {
+        await haltMigration(migration, `post-batch countPending() threw: ${err?.message ?? String(err)}`, {
+            deps,
+            startedAt,
+            rowsDone,
+            rowsRemaining: 0,
+            hashEnvelopeMatch: null,
+            state,
+        });
+        return;
+    }
+    let hashEnvelopeMatch = null;
+    let gateOk = finalRemaining === 0;
+    if (gateOk && posture.gate === "count+full-envelope") {
+        try {
+            const postEnvelope = await computeCorpusEnvelope(deps.getTable, deps.now);
+            hashEnvelopeMatch = postEnvelope.corpusHash === envelope.corpusHash;
+            gateOk = gateOk && hashEnvelopeMatch;
+        }
+        catch (err) {
+            hashEnvelopeMatch = false;
+            gateOk = false;
+            await haltMigration(migration, `post-hash computation failed: ${err?.message ?? String(err)}`, {
+                deps,
+                startedAt,
+                rowsDone,
+                rowsRemaining: finalRemaining,
+                hashEnvelopeMatch,
+                state,
+            });
+            return;
+        }
+    }
+    else if (gateOk && posture.gate === "count+old-row-envelope+new-row-presence") {
+        let allMatch = true;
+        for (const [key, preHash] of oldRowHashes) {
+            const sepIdx = key.indexOf(":");
+            const table = key.slice(0, sepIdx);
+            const id = key.slice(sepIdx + 1);
+            let current = null;
+            try {
+                current = await deps.getTable(table).get(id);
+            }
+            catch {
+                allMatch = false;
+                break;
+            }
+            const currentHash = current ? hashSourceFields(current, sourceFieldsFor(table)) : null;
+            if (currentHash !== preHash) {
+                allMatch = false;
+                break;
+            }
+        }
+        const presenceOk = newRowIds.length === oldRowHashes.size;
+        hashEnvelopeMatch = allMatch && presenceOk;
+        gateOk = gateOk && hashEnvelopeMatch;
+    }
+    // "count+marker" (derived-only): gateOk already reflects finalRemaining === 0;
+    // no content-hash comparison — recomputable by definition (Kern verdict).
+    const endedAt = deps.now().toISOString();
+    if (!gateOk) {
+        const reasonParts = [`rowsRemaining=${finalRemaining}`];
+        if (hashEnvelopeMatch === false)
+            reasonParts.push("hash envelope mismatch");
+        await haltMigration(migration, `completion gate failed: ${reasonParts.join(", ")}`, {
+            deps,
+            startedAt,
+            rowsDone,
+            rowsRemaining: finalRemaining,
+            hashEnvelopeMatch,
+            state,
+        });
+        return;
+    }
+    // ── Success: ledger → state → prune ──
+    const evt = {
+        migrationId: migration.id,
+        initiator: deps.initiator,
+        fromVersion: state[migration.id]?.completedAtVersion ?? "unknown",
+        toVersion: deps.runningVersion,
+        scope: "full",
+        startedAt,
+        endedAt,
+        outcome: "success",
+        rowsProcessed: rowsDone,
+        rowsRemaining: 0,
+        hashEnvelopeMatch,
+    };
+    try {
+        await writeLedgerEvent(evt, deps.ledgerDeps);
+    }
+    catch {
+        // A ledger-write failure after a genuinely successful migration must not
+        // flip the outcome to failed — the data-safety work already completed.
+    }
+    try {
+        writeMigrationStateEntry(deps.statePath, migration.id, {
+            completedAtVersion: deps.runningVersion,
+            completedAt: endedAt,
+            lastOutcome: "success",
+            rowsProcessed: rowsDone,
+            rowsRemaining: 0,
+        });
+    }
+    catch {
+        /* best-effort — worst case this migration's detect() runs (cheaply) again next boot */
+    }
+    pruneMigrationSnapshots(deps.snapshotRoot);
+    setMigrationProgress({ id: migration.id, rowsDone, rowsRemaining: 0, state: "completed" });
+}

package/dist/resources/migrations/snapshot.js

@@ -0,0 +1,127 @@
+/**
+ * snapshot.ts — risk-scoped pre-flight snapshot (ladder step 3) + retention
+ * pruning (ladder... well, invariant III's retention rule, applied after a
+ * successful completion gate).
+ *
+ * This is a LOGICAL, in-process snapshot — deliberately NOT the same
+ * mechanism as `flair snapshot create` (src/cli.ts's createDataSnapshot),
+ * which takes a byte-exact tar.gz of the whole data directory but requires
+ * STOPPING Harper first for consistency. The zero-touch runner executes
+ * INSIDE the live-serving Harper process (boot-keyed, server ready first —
+ * see resources/MigrationBoot.ts), so stopping the server to snapshot
+ * itself is a non-starter; this writes a small, risk-class-scoped JSON/JSONL
+ * manifest instead, using the same file-safety discipline (0700 dirs, 0600
+ * files, stat-verified — see dir-safety.ts) as the rest of Flair's snapshot
+ * machinery.
+ *
+ * Scope per risk class (flair#695, space-pressure
+ * step 3 / resources/migrations/risk-policy.ts):
+ *   - metadata-only:      manifest only (row counts, versions) — no corpus
+ *                          snapshot needed; derived data is recomputable by
+ *                          definition (invariant I).
+ *   - schema+metadata:    manifest + a schema summary (table/field names,
+ *                          never row data) — no row rewrites happen, so
+ *                          there's nothing to snapshot beyond proving what
+ *                          shape existed before the migration.
+ *   - pointers+metadata:  manifest + a JSONL of POINTER fields only (id,
+ *                          supersedes, validFrom, validTo) for touched rows
+ *                          — never content. Content-transform migrations use
+ *                          native supersession (old rows retained in-store,
+ *                          never mutated), so the corpus itself doesn't need
+ *                          snapshotting; only the pointer state that proves
+ *                          which rows were touched and how they chain.
+ */
+import { statSync, readdirSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { ensureSecureDir, writeSecureFile } from "./dir-safety.js";
+function sanitizeIdPart(s) {
+    return s.replace(/[^a-zA-Z0-9_-]/g, "_");
+}
+/** Creates the risk-scoped snapshot under `deps.snapshotRoot/<migrationId>-<iso>/`. */
+export function createMigrationSnapshot(opts, deps) {
+    const now = deps.now();
+    const iso = now.toISOString().replace(/[:.]/g, "-");
+    const dir = join(deps.snapshotRoot, `${sanitizeIdPart(opts.migrationId)}-${iso}`);
+    ensureSecureDir(dir);
+    const manifest = {
+        migrationId: opts.migrationId,
+        scope: opts.scope,
+        createdAt: now.toISOString(),
+        fromVersion: opts.fromVersion,
+        toVersion: opts.toVersion,
+        rowCounts: opts.rowCounts,
+    };
+    const manifestPath = join(dir, "manifest.json");
+    writeSecureFile(manifestPath, JSON.stringify(manifest, null, 2) + "\n", dir);
+    let bytes = statSync(manifestPath).size;
+    if (opts.scope === "schema+metadata" && opts.schema) {
+        const p = join(dir, "schema.json");
+        writeSecureFile(p, JSON.stringify(opts.schema, null, 2) + "\n", dir);
+        bytes += statSync(p).size;
+    }
+    if (opts.scope === "pointers+metadata" && opts.pointers) {
+        const p = join(dir, "pointers.jsonl");
+        const body = opts.pointers.map((r) => JSON.stringify(r)).join("\n") + (opts.pointers.length ? "\n" : "");
+        writeSecureFile(p, body, dir);
+        bytes += statSync(p).size;
+    }
+    return { dir, manifestPath, bytes };
+}
+function listMigrationSnapshotDirs(snapshotRoot) {
+    let names;
+    try {
+        names = readdirSync(snapshotRoot);
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const name of names) {
+        const path = join(snapshotRoot, name);
+        try {
+            const st = statSync(path);
+            if (st.isDirectory())
+                out.push({ path, mtimeMs: st.mtimeMs });
+        }
+        catch {
+            /* vanished between readdir and stat — skip */
+        }
+    }
+    return out;
+}
+export const DEFAULT_SNAPSHOT_KEEP_LAST = 3;
+export const DEFAULT_SNAPSHOT_MAX_AGE_MS = 30 * 24 * 3600 * 1000;
+/**
+ * Retention (Kern verdict): "keep-last-3 floor AND 30-day age ceiling, more
+ * permissive wins." Implemented as a UNION of both rules — a snapshot
+ * survives if EITHER "among the 3 most recent" OR "younger than 30 days" is
+ * true; only a snapshot that fails BOTH gets pruned. This is the
+ * more-permissive (keeps more, never less) interpretation: the last-3 floor
+ * alone would prune a 2-day-old 4th snapshot; the union keeps it.
+ */
+export function pruneMigrationSnapshots(snapshotRoot, opts = {}) {
+    const keepLast = opts.keepLast ?? DEFAULT_SNAPSHOT_KEEP_LAST;
+    const maxAgeMs = opts.maxAgeMs ?? DEFAULT_SNAPSHOT_MAX_AGE_MS;
+    const nowMs = (opts.now ?? Date.now)();
+    const all = listMigrationSnapshotDirs(snapshotRoot).sort((a, b) => b.mtimeMs - a.mtimeMs);
+    const keep = new Set();
+    for (const e of all.slice(0, keepLast))
+        keep.add(e.path);
+    for (const e of all) {
+        if (nowMs - e.mtimeMs <= maxAgeMs)
+            keep.add(e.path);
+    }
+    const removed = [];
+    for (const e of all) {
+        if (!keep.has(e.path)) {
+            try {
+                rmSync(e.path, { recursive: true, force: true });
+                removed.push(e.path);
+            }
+            catch {
+                /* best-effort — a prune failure must never fail an otherwise-successful migration */
+            }
+        }
+    }
+    return removed;
+}

package/dist/resources/migrations/source-fields.js

@@ -0,0 +1,93 @@
+/**
+ * source-fields.ts — SOURCE_FIELDS enumerations + the integrity envelope
+ * hash (flair#695 invariant I + Kern verdict).
+ *
+ * "SOURCE_FIELDS constant per resource — enumerate source vs derived per
+ * table, mechanically checked by the hash gate." The exact enumerations
+ * below are copied verbatim from the Kern verdict (2026-07-11):
+ *
+ *   Memory source = content, agentId, durability, visibility, tags,
+ *     createdAt, supersedes
+ *     (derived: embedding, embeddingModel, retrievalCount, usageCount,
+ *      lastRetrieved, provenance, originatorInstanceId)
+ *   Relationship source = subject, predicate, object, agentId, validFrom,
+ *     validTo
+ *
+ * "Pre+post content-hash ENVELOPE ... full-corpus hash-of-source-field-hashes
+ * computed before first write and after completion; must match." — hashCorpus
+ * below is exactly that: a per-row hash over ONLY the source fields, combined
+ * (sorted by id, so iteration order never perturbs the result) into one
+ * corpus-level hash.
+ */
+import { createHash } from "node:crypto";
+export const MEMORY_SOURCE_FIELDS = [
+    "content",
+    "agentId",
+    "durability",
+    "visibility",
+    "tags",
+    "createdAt",
+    "supersedes",
+];
+/** Not hashed — recomputable/mutable-by-design; listed for documentation + the mechanical-check tests. */
+export const MEMORY_DERIVED_FIELDS = [
+    "embedding",
+    "embeddingModel",
+    "retrievalCount",
+    "usageCount",
+    "lastRetrieved",
+    "provenance",
+    "originatorInstanceId",
+];
+export const RELATIONSHIP_SOURCE_FIELDS = [
+    "subject",
+    "predicate",
+    "object",
+    "agentId",
+    "validFrom",
+    "validTo",
+];
+export function sourceFieldsFor(table) {
+    return table === "Memory" ? MEMORY_SOURCE_FIELDS : RELATIONSHIP_SOURCE_FIELDS;
+}
+/**
+ * Deterministic canonicalization: sorts object keys recursively so the same
+ * logical value always serializes identically regardless of property
+ * insertion order (Harper doesn't guarantee field order is stable across
+ * reads). `undefined` normalizes to `null` — a missing/undefined source
+ * field and an explicit `null` must hash identically (both mean "no value"),
+ * otherwise a legitimate no-op re-fetch could flip the corpus hash.
+ */
+function canonicalize(value) {
+    if (Array.isArray(value))
+        return value.map(canonicalize);
+    if (value && typeof value === "object") {
+        const out = {};
+        for (const k of Object.keys(value).sort()) {
+            out[k] = canonicalize(value[k]);
+        }
+        return out;
+    }
+    return value === undefined ? null : value;
+}
+/** Hash of ONLY the listed fields off one row. Order-independent, missing-vs-null-independent. */
+export function hashSourceFields(row, fields) {
+    const picked = {};
+    for (const f of fields)
+        picked[f] = row[f] ?? null;
+    return createHash("sha256").update(JSON.stringify(canonicalize(picked))).digest("hex");
+}
+/**
+ * Hash-of-source-field-hashes over a corpus (or any subset of rows a caller
+ * passes in — the content-transform gate calls this over just the touched
+ * old rows, not the whole table). Rows are sorted by `id` before combining
+ * so the result is independent of read/iteration order — two reads of the
+ * same logical corpus in different order must hash identically.
+ */
+export function hashCorpus(rows, fields) {
+    const perRow = rows
+        .map((r) => ({ id: String(r.id ?? ""), h: hashSourceFields(r, fields) }))
+        .sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+    const combined = perRow.map((r) => `${r.id}:${r.h}`).join("|");
+    return createHash("sha256").update(combined).digest("hex");
+}