@tpsdev-ai/flair 0.20.1 → 0.22.0

package/dist/resources/migration-boot.js

@@ -0,0 +1,143 @@
+/**
+ * migration-boot.ts — the boot-keyed trigger (flair#695
+ * §A, Kern verdict): "Envelope ASYNC after ready — boot serves immediately
+ * on the old shape; pre-hash runs async; migration deferred until it
+ * completes; health shows 'pre-flight integrity check in progress'."
+ *
+ * This is a plain (non-Resource) module — same shape as
+ * resources/embeddings-provider.ts / resources/table-helpers.ts / etc. — so
+ * Harper's `jsResource: files: dist/resources/*.js` loader (config.yaml)
+ * imports it at boot like every other flat file under resources/, running
+ * its top-level side effect exactly once per process. It exports no
+ * Resource subclass — there is no HTTP endpoint here, only the trigger.
+ *
+ * Timing: `scheduleMigrationBoot()` defers the actual cycle via
+ * `setImmediate`, which runs after the current synchronous phase (module
+ * loading / resource registration) yields to the event loop — in practice,
+ * after Harper's HTTP listener is already accepting connections, so the
+ * server is serving on the OLD shape before any migration write happens
+ * (the #687 boot-win property this preserves). As an additional guard
+ * against Harper-internal load-ordering this file has no visibility into,
+ * the deferred callback ALSO polls for `databases.flair.Memory`/`Relationship`
+ * actually being live table accessors before invoking the runner — cheap,
+ * bounded, and self-healing if the very first check is too early.
+ *
+ * `runMigrationCycle` itself never throws (see runner.ts's module doc) —
+ * the `.catch()` below is pure defense-in-depth so a bug there can never
+ * take down the process either.
+ */
+import { databases } from "@harperfast/harper";
+import { homedir } from "node:os";
+import { existsSync, readFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { buildRegistry } from "./migrations/registry.js";
+import { runMigrationCycle } from "./migrations/runner.js";
+import { seedIdleProgress } from "./migrations/progress.js";
+import { getMode } from "./embeddings-provider.js";
+/** Same dataDir resolution as resources/health.ts's disk section. */
+export function resolveMigrationDataDir() {
+    return process.env.HDB_ROOT ?? join(homedir(), ".flair", "data");
+}
+/** Same "resolve the running package's own version" idiom as resources/health.ts. */
+export function resolveRunningVersion() {
+    try {
+        const here = dirname(fileURLToPath(import.meta.url));
+        const candidates = [join(here, "..", "..", "package.json"), join(here, "..", "package.json")];
+        for (const p of candidates) {
+            if (existsSync(p)) {
+                const pkg = JSON.parse(readFileSync(p, "utf-8"));
+                if (pkg.version)
+                    return pkg.version;
+            }
+        }
+    }
+    catch {
+        /* fall through */
+    }
+    return process.env.npm_package_version ?? "dev";
+}
+function getTable(table) {
+    return databases.flair[table];
+}
+async function waitForTablesReady(maxWaitMs = 30_000, intervalMs = 200) {
+    const deadline = Date.now() + maxWaitMs;
+    for (;;) {
+        try {
+            const flair = databases?.flair;
+            const mem = flair?.Memory;
+            const rel = flair?.Relationship;
+            if (typeof mem?.search === "function" && typeof rel?.search === "function")
+                return true;
+        }
+        catch {
+            /* keep polling */
+        }
+        if (Date.now() >= deadline)
+            return false;
+        await new Promise((r) => setTimeout(r, intervalMs));
+    }
+}
+/**
+ * Gives the embeddings engine a bounded window to finish its own boot probe
+ * (resources/embeddings-provider.ts: PROBE_TIMEOUT_MS = 8s) before running
+ * migrations. Root-cause fix for a real race found while building the
+ * embedding-stamp integration test: this trigger fires very early (right
+ * after the Memory/Relationship tables exist), which can beat the
+ * embeddings engine's own async model-load — a Memory.put() regen attempted
+ * during that window silently fails (getEmbedding() catches and returns
+ * null), leaving a row's embeddingModel null instead of freshly stamped.
+ * `getMode()==="local"` breaks out early on the common case (embeddings
+ * already warm); otherwise this waits up to ~8.5s (a hair over the probe's
+ * own timeout, so whatever getMode() reports by then is genuinely settled,
+ * not just "haven't checked yet") and proceeds regardless — a migration
+ * must never block boot indefinitely on this, and embedding-stamp's own
+ * pending-condition (OR of not_equal + equals-null — see that file) still
+ * self-heals a stray null on the NEXT boot even if this window isn't enough.
+ */
+async function waitForEmbeddingsSettled(maxWaitMs = 8_500, intervalMs = 150) {
+    const deadline = Date.now() + maxWaitMs;
+    while (Date.now() < deadline) {
+        if (getMode() === "local")
+            return;
+        await new Promise((r) => setTimeout(r, intervalMs));
+    }
+}
+let scheduled = false;
+export function scheduleMigrationBoot() {
+    if (scheduled)
+        return;
+    scheduled = true;
+    const registry = buildRegistry();
+    seedIdleProgress(registry.list().map((m) => m.id));
+    setImmediate(() => {
+        void (async () => {
+            const ready = await waitForTablesReady();
+            if (!ready) {
+                console.error("[flair-migrations] Memory/Relationship tables never became ready — skipping this boot's migration cycle (will retry next boot)");
+                return;
+            }
+            await waitForEmbeddingsSettled();
+            try {
+                await runMigrationCycle({
+                    registry,
+                    getTable,
+                    dataDir: resolveMigrationDataDir(),
+                    runningVersion: resolveRunningVersion(),
+                });
+            }
+            catch (err) {
+                // Defense-in-depth only — runMigrationCycle is documented to never
+                // throw. A boot-path exception must never surface here regardless.
+                console.error(`[flair-migrations] unexpected error from runMigrationCycle: ${err?.message ?? String(err)}`);
+            }
+        })();
+    });
+}
+// Test-only reset so a unit/integration test can re-trigger scheduling
+// within the same process (never used in production — a real process only
+// ever boots once).
+export function _resetMigrationBootForTests() {
+    scheduled = false;
+}
+scheduleMigrationBoot();

package/dist/resources/migrations/dir-safety.js

@@ -0,0 +1,71 @@
+/**
+ * dir-safety.ts — 0700 directory enforcement for migration snapshot/export
+ * dirs (Sherlock verdict: "0700 via stat-verify after creation (umask can
+ * override mkdir mode) and before writes; refuse with the path + actual
+ * perms named in the error." — "the safety mechanism must not become the
+ * exfil surface... export dir = highest-value target on the system.")
+ *
+ * `ensureSecureDir` creates-or-verifies a directory is 0700: it mkdirs with
+ * mode 0700, then explicitly `chmodSync`s to 0700 (covers a permissive
+ * umask silently widening mkdir's mode argument), then stat-verifies the
+ * result. If the directory STILL isn't 0700 after the explicit chmod
+ * (unusual filesystem/ACL), it refuses loudly rather than silently
+ * proceeding into a world-readable directory — naming the exact path and
+ * actual octal perms in the thrown error, per Sherlock's wording.
+ *
+ * `verifySecureDir` is exported separately so callers can (and must)
+ * re-verify immediately before EACH write inside the directory, not only at
+ * creation time (Kern: "Perms re-verified at write time, not only
+ * creation.") — a directory can be re-permissioned by something else on the
+ * host between creation and a later write in a long-running batch loop.
+ */
+import { existsSync, mkdirSync, chmodSync, statSync, writeFileSync } from "node:fs";
+export class UnsafeDirectoryError extends Error {
+    path;
+    actualMode;
+    constructor(path, actualMode) {
+        super(`refusing to use ${path}: expected 0700, found ${actualMode.toString(8).padStart(4, "0")} ` +
+            `(group/other-accessible) — fix permissions (chmod 700 ${path}) or point the migration ` +
+            `at a different directory`);
+        this.path = path;
+        this.actualMode = actualMode;
+        this.name = "UnsafeDirectoryError";
+    }
+}
+/** Throws UnsafeDirectoryError if `dir`'s mode has any group/other bits set. */
+export function verifySecureDir(dir) {
+    const st = statSync(dir);
+    const mode = st.mode & 0o777;
+    if ((mode & 0o077) !== 0) {
+        throw new UnsafeDirectoryError(dir, mode);
+    }
+}
+/**
+ * Ensures `dir` exists and is 0700. Idempotent — safe to call before every
+ * write. Never silently tolerates a world/group-readable result: attempts
+ * one explicit chmod(0700) remediation (covers the umask-widened-mkdir
+ * case), then re-verifies and throws if it's still not compliant.
+ */
+export function ensureSecureDir(dir) {
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true, mode: 0o700 });
+    }
+    try {
+        verifySecureDir(dir);
+    }
+    catch (err) {
+        if (!(err instanceof UnsafeDirectoryError))
+            throw err;
+        chmodSync(dir, 0o700);
+        verifySecureDir(dir); // throws again (loudly) if the chmod didn't stick
+    }
+}
+/**
+ * Writes `contents` to `path` at 0600, re-verifying the CONTAINING
+ * directory is still 0700 immediately before the write (per Kern's
+ * write-time re-verification requirement above).
+ */
+export function writeSecureFile(path, contents, dir) {
+    verifySecureDir(dir);
+    writeFileSync(path, contents, { mode: 0o600 });
+}

package/dist/resources/migrations/embedding-stamp.js

@@ -0,0 +1,178 @@
+/**
+ * embedding-stamp.ts — the first registered migration (per the spec):
+ * re-embeds every Memory row whose `embeddingModel` doesn't match
+ * `getModelId()`. riskClass 'derived-only' — embeddings are recomputable
+ * from `content` (SOURCE_FIELDS), never the only copy of anything
+ * (invariant I), so this is the cheapest posture: metadata-only snapshot,
+ * no content-hash gate (row-count + stamp convergence only).
+ *
+ * THE GATE (`EMBEDDING_PREFIXES_ENABLED` in resources/embeddings-provider.ts)
+ * is now ON (flair#504, flipped and re-baselined through the ratchet gate),
+ * so `getModelId()` returns `<base>+searchprefix` — every row written before
+ * this flip was stamped with the bare base id, so it now reads as stale and
+ * gets picked up by this migration on the next boot that reaches it. This is
+ * this migration's first real payload: before the flip, `getModelId()`
+ * returned the bare base id unconditionally, so this migration — live and
+ * always-registered from the day it shipped — had nothing to detect. That
+ * was intentional groundwork, not dead code: proving the detect/re-embed
+ * mechanism end-to-end (this file, `test/integration/
+ * migrations-embedding-stamp-e2e.test.ts`) before it ever had real work to
+ * do was the point.
+ *
+ * Reuses Memory's OWN regen branch — never duplicates embedding logic —
+ * via the SAME mechanism `flair reembed` (src/cli.ts) already uses in
+ * production: a genuine `PUT /Memory/:id` HTTP request (admin-authenticated
+ * loopback), not an in-process call on `databases.flair.Memory` directly.
+ *
+ * THIS IS LOAD-BEARING, confirmed empirically while building
+ * test/integration/migrations-embedding-stamp-e2e.test.ts against real
+ * Harper: `databases.flair.Memory` (the property Harper exposes to OTHER
+ * modules, imported the same way resources/health.ts / MemoryReindex.ts /
+ * etc. already do for READS) resolves to the RAW underlying table, not the
+ * resources/Memory.ts SUBCLASS that carries the actual regen/dedup/auth
+ * logic — that subclass is only reachable via Harper's own REST dispatch
+ * for a genuine `/Memory` request. Calling `.put()` on the raw reference
+ * writes the record fine (confirmed: fields land exactly as passed) but
+ * silently skips every override in resources/Memory.ts, INCLUDING the
+ * `if (content.content && !content.embedding) { regenerate } ` branch this
+ * migration exists to trigger. Reads (`.search()`/`.get()`, used below for
+ * detect/countPending/candidate-selection) are unaffected by this — only
+ * `.put()` needs the real dispatch, hence the loopback HTTP call for
+ * exactly that one step.
+ *
+ * Query correctness (also verified against real Harper): Harper's
+ * `not_equal` comparator only matches rows where the attribute holds an
+ * EXPLICIT value (including explicit `null`) — a row where the attribute
+ * was NEVER SET AT ALL (`getIndexedValues()` returns `undefined` for a
+ * truly-absent property, never indexed regardless of `indexNulls`) is
+ * invisible to ANY condition-based query, not just `not_equal`. Clearing to
+ * `null` (never `undefined`) on write is therefore load-bearing: if the
+ * regen HTTP call fails (engine not yet warmed up, transient failure,
+ * admin credential unavailable this cycle), the row must land back in an
+ * EXPLICIT-null state — queryable and retried on the next boot — never a
+ * truly-absent one that would be permanently invisible to this migration
+ * again. The pending condition is an OR of `not_equal <current>` (catches a
+ * stale non-null model string) and `equals null` (catches that
+ * explicit-null state) — together they catch every state this migration's
+ * OWN writes can ever produce. A row whose `embeddingModel` was NEVER
+ * touched by anything (truly absent from its very first write — only
+ * possible if the embeddings engine was down for that entire write) is a
+ * known, narrow gap this bounded query cannot see;
+ * resources/migration-boot.ts mitigates the common case by waiting for the
+ * embeddings engine to settle before running migrations at all.
+ */
+import { databases } from "@harperfast/harper";
+import { getModelId } from "../embeddings-provider.js";
+function defaultMemoryTable() {
+    return databases.flair.Memory;
+}
+export const EMBEDDING_STAMP_ID = "embedding-stamp";
+const REGEN_HTTP_TIMEOUT_MS = 20_000; // a real embedding compute can be slow on constrained hardware
+/** Same admin-password resolution as resources/auth-middleware.ts's getAdminPass(). */
+function resolveAdminAuthHeader() {
+    const pass = process.env.HDB_ADMIN_PASSWORD ?? process.env.FLAIR_ADMIN_PASSWORD;
+    if (!pass)
+        return null;
+    return "Basic " + Buffer.from(`admin:${pass}`).toString("base64");
+}
+/** Same HTTP_PORT env resolution src/cli.ts sets on every Harper spawn (see that file's grep for HTTP_PORT). */
+function resolveSelfBaseUrl() {
+    const port = process.env.HTTP_PORT ?? "9926";
+    return `http://127.0.0.1:${port}`;
+}
+/**
+ * Triggers Memory.put()'s regen branch via a genuine loopback HTTP PUT —
+ * the ONLY reliable way to reach resources/Memory.ts's subclass logic (see
+ * module doc). Returns true iff the request succeeded (2xx); NEVER throws
+ * — a failure just leaves the row in its current (queryable, explicit-null
+ * or stale-string) state for the next attempt.
+ */
+async function regenViaHttpPut(id, existing, fetchImpl) {
+    const authHeader = resolveAdminAuthHeader();
+    if (!authHeader)
+        return false; // no admin credential available this cycle — retried next boot
+    try {
+        const res = await fetchImpl(`${resolveSelfBaseUrl()}/Memory/${encodeURIComponent(id)}`, {
+            method: "PUT",
+            headers: { "Content-Type": "application/json", Authorization: authHeader },
+            body: JSON.stringify({ ...existing, embedding: null, embeddingModel: null }),
+            signal: AbortSignal.timeout(REGEN_HTTP_TIMEOUT_MS),
+        });
+        return res.ok;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * `getTable`/`getCurrentModelId`/`regen` are injectable so unit tests can
+ * exercise this migration's full detect/countPending/run logic against an
+ * in-memory fake table and a fake regen function (no real Harper, no real
+ * HTTP needed) — matching the mocking technique used throughout
+ * test/unit/*.ts (e.g. test/unit/instance-identity.test.ts). The real
+ * loopback-HTTP regen path is exercised for real in
+ * test/integration/migrations-embedding-stamp-e2e.test.ts.
+ */
+export function createEmbeddingStampMigration(getTable = defaultMemoryTable, getCurrentModelId = getModelId, regen = (id, existing) => regenViaHttpPut(id, existing, fetch)) {
+    function staleCondition() {
+        // OR-combined: `not_equal <current>` catches a stale non-null model
+        // string; `equals null` catches the explicit-null state this
+        // migration's own writes leave behind on a failed regen (see the
+        // module doc above — Harper's index never sees a TRULY ABSENT
+        // property, only an explicit null).
+        return [
+            {
+                operator: "or",
+                conditions: [
+                    { attribute: "embeddingModel", comparator: "not_equal", value: getCurrentModelId() },
+                    { attribute: "embeddingModel", comparator: "equals", value: null },
+                ],
+            },
+        ];
+    }
+    return {
+        id: EMBEDDING_STAMP_ID,
+        riskClass: "derived-only",
+        affectsTables: ["Memory"],
+        async detect() {
+            const table = getTable();
+            for await (const _row of table.search({ conditions: staleCondition(), limit: 1 })) {
+                return true;
+            }
+            return false;
+        },
+        async countPending() {
+            const table = getTable();
+            let n = 0;
+            for await (const _row of table.search({ conditions: staleCondition() }))
+                n++;
+            return n;
+        },
+        async run(batchSize) {
+            const table = getTable();
+            const current = getCurrentModelId();
+            const candidates = [];
+            for await (const row of table.search({ conditions: staleCondition(), limit: batchSize })) {
+                candidates.push(row);
+            }
+            const touchedIds = [];
+            for (const row of candidates) {
+                const id = String(row.id ?? "");
+                if (!id)
+                    continue;
+                const existing = await table.get(id);
+                if (!existing)
+                    continue; // deleted since the search above — nothing to fix
+                if (existing.embeddingModel === current)
+                    continue; // already stamped by a concurrent runner — idempotent skip
+                const ok = await regen(id, existing);
+                if (ok)
+                    touchedIds.push(id);
+                // A failed regen leaves the row untouched (still matching
+                // staleCondition — retried next batch/boot), never partially
+                // written or marked done.
+            }
+            return { processed: touchedIds.length, touchedIds };
+        },
+    };
+}

package/dist/resources/migrations/envelope.js

@@ -0,0 +1,43 @@
+/**
+ * envelope.ts — the corpus-wide integrity envelope: "full-corpus
+ * hash-of-source-field-hashes computed before first write and after
+ * completion; must match" (flair#695 invariant IV /
+ * Kern verdict), computed ONCE per boot cycle (K&S: "Envelope ASYNC after
+ * ready — boot serves immediately on the old shape; pre-hash runs async;
+ * migration deferred until it completes").
+ *
+ * `computeCorpusEnvelope` walks BOTH SOURCE_FIELDS tables (Memory,
+ * Relationship) once and returns both the single aggregate `corpusHash`
+ * (what schema-additive's full-envelope gate compares pre/post) AND the
+ * full `perRowHash` breakdown (`${table}:${id}` -> hash) — the latter isn't
+ * used by this module directly, but keeping the breakdown around lets a
+ * caller answer "did THIS specific row's source fields change" without a
+ * second full-corpus pass, if ever needed for diagnostics.
+ *
+ * Deliberately NOT scoped by risk class — this is the one integrity
+ * computation the whole cycle shares; risk-class-specific gate strictness
+ * (runner.ts) decides HOW MUCH of it each migration's completion gate
+ * actually checks.
+ */
+import { createHash } from "node:crypto";
+import { hashSourceFields, sourceFieldsFor } from "./source-fields.js";
+export const ENVELOPE_TABLES = ["Memory", "Relationship"];
+export async function computeCorpusEnvelope(getTable, now) {
+    const perRowHash = new Map();
+    const parts = [];
+    for (const table of ENVELOPE_TABLES) {
+        const fields = sourceFieldsFor(table);
+        const accessor = getTable(table);
+        for await (const row of accessor.search({})) {
+            const id = String(row.id ?? "");
+            if (!id)
+                continue;
+            const h = hashSourceFields(row, fields);
+            perRowHash.set(`${table}:${id}`, h);
+            parts.push(`${table}:${id}:${h}`);
+        }
+    }
+    parts.sort();
+    const corpusHash = createHash("sha256").update(parts.join("|")).digest("hex");
+    return { perRowHash, corpusHash, computedAt: now().toISOString() };
+}

package/dist/resources/migrations/export.js

@@ -0,0 +1,38 @@
+/**
+ * export.ts — content-only logical export fallback (ladder step 4):
+ * "Content-only logical export fallback: embeddings/indexes dominate
+ * data-dir size; the irreplaceable part (memory content + provenance)
+ * exports far smaller. If the physical snapshot doesn't fit but the content
+ * export does → export content, proceed (derived is recomputable by
+ * definition)." (flair#695, space-pressure step 4)
+ *
+ * Exports SOURCE_FIELDS ONLY (+id) — never derived fields (embedding is the
+ * dominant size driver this exists to skip) — as JSONL, one row per line,
+ * under the SAME 0700/0600 discipline as snapshot.ts.
+ */
+import { statSync } from "node:fs";
+import { join } from "node:path";
+import { ensureSecureDir, writeSecureFile } from "./dir-safety.js";
+import { sourceFieldsFor } from "./source-fields.js";
+function sanitizeIdPart(s) {
+    return s.replace(/[^a-zA-Z0-9_-]/g, "_");
+}
+export function createContentOnlyExport(opts, deps) {
+    const now = deps.now();
+    const iso = now.toISOString().replace(/[:.]/g, "-");
+    const dir = join(deps.exportRoot, `${sanitizeIdPart(opts.migrationId)}-${opts.table}-${iso}`);
+    ensureSecureDir(dir);
+    const fields = sourceFieldsFor(opts.table);
+    const lines = opts.rows.map((row) => {
+        const picked = { id: row.id };
+        for (const f of fields)
+            picked[f] = row[f] ?? null;
+        return JSON.stringify(picked);
+    });
+    const body = lines.join("\n") + (lines.length ? "\n" : "");
+    const path = join(dir, `${opts.table}.jsonl`);
+    writeSecureFile(path, body, dir);
+    const metaPath = join(dir, "manifest.json");
+    writeSecureFile(metaPath, JSON.stringify({ migrationId: opts.migrationId, table: opts.table, fromVersion: opts.fromVersion, createdAt: now.toISOString(), rowCount: opts.rows.length }, null, 2) + "\n", dir);
+    return { dir, path, bytes: statSync(path).size, rowCount: opts.rows.length };
+}

package/dist/resources/migrations/ledger.js

@@ -0,0 +1,55 @@
+/**
+ * ledger.ts — the migration ledger OrgEvent (invariant IV: "every migration
+ * records an OrgEvent (initiator, versions, scope, outcome, duration) —
+ * migrations get decision provenance. Dogfood.")
+ *
+ * Sherlock verdict: "Ledger discloses structural metadata only — versions,
+ * counts, outcome, duration; never memory IDs or content summaries." The
+ * shape below is EXACTLY the Kern-verdict field list (migration id,
+ * initiator, from/to version, scope, start/end, outcome, rows
+ * processed/remaining, error if halted, hash envelope) — nothing else is
+ * ever written into `detail`.
+ *
+ * Written via an internal (no-HTTP-context) call to
+ * `databases.flair.OrgEvent.put()` — resolveAgentAuth(undefined) resolves
+ * to `{kind: "internal"}` (trusted; see resources/agent-auth.ts), the same
+ * pattern resources/auth-middleware.ts's backfillEmbedding() and
+ * resources/MemoryReindex.ts's `_reindex` path already rely on for
+ * server-internal writes with no HTTP caller behind them.
+ */
+import { databases } from "@harperfast/harper";
+function defaultOrgEventTable() {
+    return databases.flair.OrgEvent;
+}
+/** Structural-only detail blob — see the module doc; never memory IDs/content. */
+export function buildLedgerDetail(evt) {
+    return JSON.stringify({
+        migrationId: evt.migrationId,
+        initiator: evt.initiator,
+        fromVersion: evt.fromVersion,
+        toVersion: evt.toVersion,
+        scope: evt.scope,
+        startedAt: evt.startedAt,
+        endedAt: evt.endedAt,
+        outcome: evt.outcome,
+        rowsProcessed: evt.rowsProcessed,
+        rowsRemaining: evt.rowsRemaining,
+        hashEnvelopeMatch: evt.hashEnvelopeMatch,
+        ...(evt.error ? { error: evt.error } : {}),
+    });
+}
+export async function writeLedgerEvent(evt, deps = {}) {
+    const table = deps.orgEventTable ?? defaultOrgEventTable();
+    const id = `migration-${evt.migrationId}-${evt.endedAt}`;
+    const remainingNote = evt.rowsRemaining > 0 ? `, ${evt.rowsRemaining} remaining` : "";
+    await table.put({
+        id,
+        authorId: "flair-migrations",
+        kind: "migration",
+        scope: evt.scope,
+        summary: `migration ${evt.migrationId} ${evt.outcome} (${evt.rowsProcessed} row${evt.rowsProcessed === 1 ? "" : "s"} processed${remainingNote})`,
+        detail: buildLedgerDetail(evt),
+        refId: evt.migrationId,
+        createdAt: evt.endedAt,
+    });
+}