akm-cli 0.9.0-rc.1 → 0.9.0-rc.2

package/dist/core/redaction.js

@@ -0,0 +1,358 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+const ENV_PASSTHROUGH_REDACTION_POLICY = {
+    HOME: "path",
+    PATH: "path",
+    USER: "identifier",
+    LANG: "identifier",
+    LC_ALL: "identifier",
+    TERM: "identifier",
+    TMPDIR: "path",
+    SYSTEMROOT: "path",
+    COMSPEC: "path",
+    PATHEXT: "path",
+    WINDIR: "path",
+    TEMP: "path",
+    TMP: "path",
+    AKM_EVENT_SOURCE: "identifier",
+    OPENCODE_CONFIG: "path",
+    CLAUDE_CONFIG: "path",
+    CODEX_CONFIG: "path",
+    AWS_PROFILE: "identifier",
+    AWS_REGION: "identifier",
+    LLM_MODEL: "identifier",
+    LLM_BASE_URL: "url",
+};
+/** Environment names whose ordinary values identify runtime configuration rather than credentials. */
+export const ENV_PASSTHROUGH_REDACTION_ALLOWLIST = new Set(Object.keys(ENV_PASSTHROUGH_REDACTION_POLICY));
+const SIGNED_QUERY_KEYS = new Set([
+    "accesskey",
+    "accesskeyid",
+    "accesstoken",
+    "actortoken",
+    "apikey",
+    "assertion",
+    "authorization",
+    "authorizationcode",
+    "authreqid",
+    "clientassertion",
+    "clientsecret",
+    "code",
+    "codeverifier",
+    "credential",
+    "devicecode",
+    "googleaccessid",
+    "idtoken",
+    "idtokenhint",
+    "initialaccesstoken",
+    "key",
+    "loginhinttoken",
+    "logouthint",
+    "logouttoken",
+    "nonce",
+    "oauthcode",
+    "oauthtoken",
+    "oauthverifier",
+    "password",
+    "refreshtoken",
+    "registrationaccesstoken",
+    "requesturi",
+    "response",
+    "secret",
+    "sessiontoken",
+    "sharedaccesssignature",
+    "sig",
+    "signature",
+    "softwarestatement",
+    "state",
+    "subjecttoken",
+    "token",
+    "usercode",
+    "verifier",
+    "xamzcredential",
+    "xamzsecuritytoken",
+    "xamzsignature",
+    "xgoogcredential",
+    "xgoogsignature",
+]);
+function normalizedQueryKey(key) {
+    return key.toLowerCase().replaceAll(/[^a-z0-9]/g, "");
+}
+function collectCredentialParameters(params, values) {
+    let found = false;
+    for (const [key, value] of params) {
+        if (!SIGNED_QUERY_KEYS.has(normalizedQueryKey(key)))
+            continue;
+        found = true;
+        if (value)
+            values?.add(value);
+    }
+    return found;
+}
+function addEncodedCredentialVariants(rawValue, values) {
+    if (!rawValue || !values)
+        return;
+    values.add(rawValue);
+    let decoded;
+    try {
+        decoded = decodeURIComponent(rawValue.replaceAll("+", " "));
+    }
+    catch {
+        return;
+    }
+    if (!decoded)
+        return;
+    values.add(decoded);
+    const encoded = encodeURIComponent(decoded);
+    values.add(encoded);
+    values.add(encoded.replaceAll("%20", "+"));
+    values.add(encoded.replace(/%[0-9A-F]{2}/g, (sequence) => sequence.toLowerCase()));
+}
+function collectEncodedCredentialParameters(raw, values) {
+    let found = false;
+    for (const part of raw.split("&")) {
+        const separator = part.indexOf("=");
+        if (separator < 0)
+            continue;
+        const rawKey = part.slice(0, separator);
+        const rawValue = part.slice(separator + 1);
+        let key = rawKey;
+        try {
+            key = decodeURIComponent(rawKey.replaceAll("+", " "));
+        }
+        catch {
+            // Keep the raw key so malformed credential-shaped input still fails closed.
+        }
+        if (!SIGNED_QUERY_KEYS.has(normalizedQueryKey(key)))
+            continue;
+        found = true;
+        addEncodedCredentialVariants(rawValue, values);
+    }
+    return found;
+}
+function collectCredentialFragment(fragment, values) {
+    const directDecoded = fragment.includes("=") && collectCredentialParameters(new URLSearchParams(fragment), values);
+    const directEncoded = fragment.includes("=") && collectEncodedCredentialParameters(fragment, values);
+    let found = directDecoded || directEncoded;
+    const nestedQuery = fragment.indexOf("?");
+    if (nestedQuery >= 0) {
+        const query = fragment.slice(nestedQuery + 1);
+        const decoded = collectCredentialParameters(new URLSearchParams(query), values);
+        const encoded = collectEncodedCredentialParameters(query, values);
+        found = decoded || encoded || found;
+    }
+    return found;
+}
+function inspectCredentialBearingUrl(value, values) {
+    const trimmed = value.trim();
+    if (!trimmed)
+        return false;
+    try {
+        const url = new URL(trimmed);
+        let found = false;
+        for (const userInfo of [url.username, url.password]) {
+            if (!userInfo)
+                continue;
+            found = true;
+            values?.add(userInfo);
+            try {
+                values?.add(decodeURIComponent(userInfo));
+            }
+            catch {
+                values?.add(userInfo);
+            }
+        }
+        const decodedQuery = collectCredentialParameters(url.searchParams, values);
+        const encodedQuery = collectEncodedCredentialParameters(url.search.slice(1), values);
+        found = decodedQuery || encodedQuery || found;
+        return collectCredentialFragment(url.hash.slice(1), values) || found;
+    }
+    catch {
+        // Fail closed for malformed URL-like values carrying the same credential shapes.
+        let found = /^[a-z][a-z0-9+.-]*:\/\/[^/\s?#]*@/i.test(trimmed);
+        const query = trimmed.indexOf("?");
+        const fragment = trimmed.indexOf("#");
+        if (query >= 0) {
+            const queryText = trimmed.slice(query + 1, fragment >= 0 ? fragment : undefined);
+            const decodedQuery = collectCredentialParameters(new URLSearchParams(queryText), values);
+            const encodedQuery = collectEncodedCredentialParameters(queryText, values);
+            found = decodedQuery || encodedQuery || found;
+        }
+        if (fragment >= 0) {
+            const fragmentText = trimmed.slice(fragment + 1);
+            found = collectCredentialFragment(fragmentText, values) || found;
+        }
+        return found;
+    }
+}
+/** Collect exact secrets plus decoded values embedded in credential-bearing URLs. */
+export function collectSensitiveValues(rawValues) {
+    const values = new Set();
+    for (const value of rawValues) {
+        if (value === undefined || value.length === 0)
+            continue;
+        values.add(value);
+        const trimmed = value.trim();
+        if (inspectCredentialBearingUrl(value, values) && trimmed)
+            values.add(trimmed);
+    }
+    return [...values];
+}
+/**
+ * Decide whether an allowlisted passthrough value may cross an output boundary.
+ * The name allowlist never overrides value inspection: URL userinfo and signed
+ * query credentials remain secret even under ordinarily non-secret names.
+ */
+export function isEnvPassthroughValueSafeToExpose(name, value) {
+    if (value === undefined)
+        return true;
+    const policy = ENV_PASSTHROUGH_REDACTION_POLICY[name];
+    if (!policy)
+        return false;
+    const classifiedPolicy = policy;
+    switch (classifiedPolicy) {
+        case "identifier":
+        case "path":
+        case "url":
+            return !inspectCredentialBearingUrl(value);
+        default: {
+            const exhaustive = classifiedPolicy;
+            return exhaustive;
+        }
+    }
+}
+function utf8SequenceLength(firstByte) {
+    if (firstByte <= 0x7f)
+        return 1;
+    if (firstByte >= 0xc2 && firstByte <= 0xdf)
+        return 2;
+    if (firstByte >= 0xe0 && firstByte <= 0xef)
+        return 3;
+    if (firstByte >= 0xf0 && firstByte <= 0xf4)
+        return 4;
+    return 0;
+}
+function normalizeEncodedText(value, plusAsSpace) {
+    let text = "";
+    const starts = new Int32Array(value.length);
+    let mappingLength = 0;
+    const append = (decoded, start) => {
+        text += decoded;
+        for (let index = 0; index < decoded.length; index++) {
+            starts[mappingLength] = start;
+            mappingLength++;
+        }
+    };
+    for (let index = 0; index < value.length;) {
+        if (value[index] === "%" && /^[0-9a-f]{2}$/i.test(value.slice(index + 1, index + 3))) {
+            const start = index;
+            const firstByte = Number.parseInt(value.slice(index + 1, index + 3), 16);
+            const sequenceLength = utf8SequenceLength(firstByte);
+            if (sequenceLength > 0) {
+                const bytes = [firstByte];
+                let cursor = index + 3;
+                while (bytes.length < sequenceLength &&
+                    value[cursor] === "%" &&
+                    /^[0-9a-f]{2}$/i.test(value.slice(cursor + 1, cursor + 3))) {
+                    bytes.push(Number.parseInt(value.slice(cursor + 1, cursor + 3), 16));
+                    cursor += 3;
+                }
+                if (bytes.length === sequenceLength) {
+                    try {
+                        const decoded = new TextDecoder("utf-8", { fatal: true }).decode(Uint8Array.from(bytes));
+                        index = cursor;
+                        append(decoded, start);
+                        continue;
+                    }
+                    catch {
+                        // Treat invalid UTF-8 percent sequences as literal text.
+                    }
+                }
+            }
+        }
+        const start = index;
+        const codePoint = value.codePointAt(index);
+        if (codePoint === undefined)
+            break;
+        const character = String.fromCodePoint(codePoint);
+        index += character.length;
+        append(plusAsSpace && character === "+" ? " " : character, start);
+    }
+    return { text, starts, sourceLength: value.length };
+}
+function addMappedMatches(coverageDelta, haystack, needle) {
+    if (!needle)
+        return;
+    let offset = 0;
+    while (offset <= haystack.text.length - needle.length) {
+        const match = haystack.text.indexOf(needle, offset);
+        if (match < 0)
+            break;
+        const start = haystack.starts[match];
+        const normalizedEnd = match + needle.length;
+        const end = normalizedEnd < haystack.text.length ? haystack.starts[normalizedEnd] : haystack.sourceLength;
+        coverageDelta[start]++;
+        coverageDelta[end]--;
+        offset = match + Math.max(needle.length, 1);
+    }
+}
+/**
+ * Replace exact sensitive values in text. Longer values are replaced first so
+ * an overlapping prefix cannot expose the suffix of a longer credential.
+ */
+export function redactSensitiveText(text, sensitiveValues) {
+    const values = [...new Set(sensitiveValues)]
+        .filter((value) => value.length > 0)
+        .sort((a, b) => b.length - a.length || a.localeCompare(b));
+    if (values.length === 0)
+        return text;
+    if (!text.includes("%") && !text.includes("+")) {
+        let redacted = text;
+        for (const value of values)
+            redacted = redacted.replaceAll(value, "[REDACTED]");
+        return redacted;
+    }
+    const coverageDelta = new Int32Array(text.length + 1);
+    const addMatchesForMode = (plusAsSpace) => {
+        const haystack = normalizeEncodedText(text, plusAsSpace);
+        for (const value of values) {
+            addMappedMatches(coverageDelta, haystack, normalizeEncodedText(value, plusAsSpace).text);
+        }
+    };
+    addMatchesForMode(false);
+    if (text.includes("+"))
+        addMatchesForMode(true);
+    let redacted = "";
+    let coverage = 0;
+    let offset = 0;
+    let found = false;
+    for (let index = 0; index <= text.length; index++) {
+        const wasCovered = coverage > 0;
+        coverage += coverageDelta[index];
+        const isCovered = coverage > 0;
+        if (!wasCovered && isCovered) {
+            redacted += `${text.slice(offset, index)}[REDACTED]`;
+            found = true;
+        }
+        else if (wasCovered && !isCovered) {
+            offset = index;
+        }
+    }
+    return found ? redacted + text.slice(offset) : text;
+}
+/** Recursively redact string leaves before a structured value crosses a durable/output boundary. */
+export function redactSensitiveValue(value, sensitiveValues) {
+    const values = [...sensitiveValues];
+    const redact = (entry) => {
+        if (typeof entry === "string")
+            return redactSensitiveText(entry, values);
+        if (Array.isArray(entry))
+            return entry.map(redact);
+        if (entry && typeof entry === "object") {
+            return Object.fromEntries(Object.entries(entry).map(([key, child]) => [redactSensitiveText(key, values), redact(child)]));
+        }
+        return entry;
+    };
+    return redact(value);
+}

package/dist/core/state/migrations.js

@@ -2,6 +2,7 @@
 // License, v. 2.0. If a copy of the MPL was not distributed with this
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
 import { runMigrations as runSqliteMigrations } from "../../storage/engines/sqlite-migrations.js";
+import { ensureMigrationBackup } from "../migration-backup.js";
 const MIGRATIONS = [
     // ── Migration 001 — initial schema ──────────────────────────────────────────
     {
@@ -756,6 +757,15 @@ const MIGRATIONS = [
         ON improve_cycle_metrics(ts);
     `,
     },
+    // Keep the historical profile column untouched. New 0.9 runs identify the
+    // selected improve strategy in this additive column.
+    {
+        id: "017-improve-run-strategy",
+        up: `
+      ALTER TABLE improve_runs ADD COLUMN strategy TEXT;
+      CREATE INDEX IF NOT EXISTS idx_improve_runs_strategy_started ON improve_runs(strategy, started_at);
+    `,
+    },
 ];
 /**
  * Apply every pending migration in a single transaction per migration.
@@ -765,6 +775,11 @@ const MIGRATIONS = [
  *
  * Called automatically by `openStateDatabase()`.
  */
-export function runMigrations(db) {
-    runSqliteMigrations(db, MIGRATIONS);
+export function runMigrations(db, options) {
+    runSqliteMigrations(db, MIGRATIONS, {
+        beforeMigration(migration) {
+            if (options?.ensureCutoverBackup && migration.id === "017-improve-run-strategy")
+                ensureMigrationBackup();
+        },
+    });
 }

package/dist/core/state-db.js

@@ -55,8 +55,11 @@
  *
  * @module state-db
  */
+import fs from "node:fs";
 import path from "node:path";
 import { openManagedDatabase, withManagedDb, withManagedDbAsync } from "../storage/managed-db.js";
+import { acquireMaintenanceActivitySync } from "./maintenance-barrier.js";
+import { ensureMigrationBackup, getMigrationBackupDir } from "./migration-backup.js";
 import { getDataDir } from "./paths.js";
 // ── Path helper ──────────────────────────────────────────────────────────────
 /**
@@ -96,7 +99,47 @@ export function getStateDbPath() {
  *     narrow when a post-inference reindex overlapped a parallel event write.
  */
 export function openStateDatabase(dbPath) {
-    return openManagedDatabase({ path: dbPath ?? getStateDbPath(), init: runMigrations });
+    const canonicalPath = getStateDbPath();
+    const resolvedPath = dbPath ?? canonicalPath;
+    const isCanonical = path.resolve(resolvedPath) === path.resolve(canonicalPath);
+    const releaseActivity = isCanonical ? acquireMaintenanceActivitySync("state-db") : undefined;
+    try {
+        // This must precede mkdir/open: opening an absent SQLite path creates it and
+        // would make the recovery manifest falsely record a fresh DB as pre-existing.
+        if (isCanonical && !fs.existsSync(getMigrationBackupDir()))
+            ensureMigrationBackup();
+        const db = openManagedDatabase({
+            path: resolvedPath,
+            init: (db) => runMigrations(db, { ensureCutoverBackup: isCanonical }),
+        });
+        if (!releaseActivity)
+            return db;
+        let closed = false;
+        return {
+            prepare: db.prepare.bind(db),
+            exec: db.exec.bind(db),
+            run: db.run.bind(db),
+            transaction: db.transaction.bind(db),
+            get inTransaction() {
+                return db.inTransaction;
+            },
+            close() {
+                if (closed)
+                    return;
+                closed = true;
+                try {
+                    db.close();
+                }
+                finally {
+                    releaseActivity();
+                }
+            },
+        };
+    }
+    catch (error) {
+        releaseActivity?.();
+        throw error;
+    }
 }
 /**
  * Run `fn` against state.db, owning the handle unless one is borrowed. The loan

package/dist/indexer/db/db.js

@@ -1,6 +1,7 @@
 // This Source Code Form is subject to the terms of the Mozilla Public
 // License, v. 2.0. If a copy of the MPL was not distributed with this
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
+import fs from "node:fs";
 import { createRequire } from "node:module";
 import path from "node:path";
 import { parseAssetRef } from "../../core/asset/asset-ref.js";
@@ -9,10 +10,11 @@ import { getDbPath } from "../../core/paths.js";
 import { warn } from "../../core/warn.js";
 import { cosineSimilarity } from "../../llm/embedders/types.js";
 import { sha256Hex } from "../../runtime.js";
+import { openDatabase } from "../../storage/database.js";
 import { openManagedDatabase } from "../../storage/managed-db.js";
 import { computeNextUtility, HIGH_UTILITY_THRESHOLD, UTILITY_REVIEW_THRESHOLD, } from "../feedback/utility-policy.js";
 import { buildPrefixQuery, sanitizeFtsQuery } from "../search/fts-query.js";
-import { buildSearchFields } from "../search/search-fields.js";
+import { buildSearchFields, buildSearchText } from "../search/search-fields.js";
 import { ENTRY_COLUMNS, rowToIndexedEntry } from "./entry-mapper.js";
 import { ensureSchema } from "./schema.js";
 export { HIGH_UTILITY_THRESHOLD, sanitizeFtsQuery, UTILITY_REVIEW_THRESHOLD };
@@ -64,6 +66,16 @@ export function openExistingDatabase(dbPath) {
     // so init only loads the vec extension, it does not run ensureSchema.
     return openManagedDatabase({ path: dbPath ?? getDbPath(), init: loadVecExtension });
 }
+/**
+ * Open an existing index for queries without creating directories, a database
+ * file, journals, or running write-capable pragmas/schema initialization.
+ */
+export function openReadonlyExistingDatabase(dbPath) {
+    const resolvedPath = dbPath ?? getDbPath();
+    if (!fs.existsSync(resolvedPath))
+        return undefined;
+    return openDatabase(resolvedPath, { readonly: true, create: false });
+}
 export function closeDatabase(db) {
     db.close();
 }
@@ -301,6 +313,109 @@ export function getBaseBeliefStatesForDerivedTwins(db, twinIds) {
     }
     return out;
 }
+/**
+ * SPEC-7 (`akm mv`): re-key an entries row IN PLACE after an on-disk rename.
+ *
+ * The row id is preserved on purpose — `utility_scores`,
+ * `utility_scores_scoped`, and `embeddings` are keyed by `entry_id`, so an
+ * UPDATE (rather than a delete + insert under the new `entry_key`) is what
+ * keeps the asset's accumulated usage-ranking history attached across a
+ * rename. (`asset_salience` / `asset_outcome` live in state.db keyed by
+ * `asset_ref` TEXT and are re-keyed separately by `akm mv` — see
+ * mv-cli.ts `rekeyStateDbForMove`.) `entry_json.name` (and `filename`, when
+ * present) is patched and `search_text` rebuilt so search reflects the new
+ * name; the row is marked FTS-dirty for the caller's
+ * `rebuildFts({incremental: true})`.
+ *
+ * `usage_events.entry_ref` rows for the old ref are rewritten to the new ref
+ * in the same transaction — both the bare `type:name` spelling and the
+ * origin-qualified `origin//type:name` spelling (search/show writers persist
+ * either, see {@link getRetrievalCounts}). Without this, events keep the old
+ * ref, `relinkUsageEvents` finds no matching entry after the next full
+ * rebuild, and the utility history the re-key exists to preserve silently
+ * resets. DETACHED orphan events already sitting at the new ref (entry_id
+ * NULL — a deleted stranger's history) are deleted first, so the moved asset
+ * never adopts them (live asset's history wins, matching the stale-row
+ * eviction below).
+ *
+ * A stale row already occupying `newEntryKey` (the caller has verified no
+ * FILE exists at the target, so such a row can only be a leftover for a
+ * deleted file) is evicted first — through {@link deleteRelatedRows}, so its
+ * child rows (embeddings, entries_vec, utility scores, usage events) go with
+ * it. A bare `DELETE FROM entries` would trip the non-CASCADE `embeddings`
+ * FK under `PRAGMA foreign_keys = ON` and roll back the whole re-key.
+ * The moved row keeps its id.
+ *
+ * Returns the surviving row id, or `null` when no row matches `oldEntryKey`
+ * (nothing indexed under the old name — the caller falls open and the next
+ * full `akm index` picks the file up as a fresh entry).
+ */
+export function rekeyEntryInPlace(db, opts) {
+    const row = db.prepare("SELECT id, entry_json, search_text FROM entries WHERE entry_key = ?").get(opts.oldEntryKey);
+    if (!row)
+        return null;
+    // Patch the JSON payload. On corrupt entry_json still re-key key + paths so
+    // the utility history survives; the next full index heals the JSON.
+    let entryJson = row.entry_json;
+    let searchText = row.search_text;
+    try {
+        const entry = JSON.parse(row.entry_json);
+        entry.name = opts.newName;
+        if (typeof entry.filename === "string")
+            entry.filename = path.basename(opts.newFilePath);
+        if (opts.newDerivedFrom !== undefined)
+            entry.derivedFrom = opts.newDerivedFrom;
+        entryJson = JSON.stringify(entry);
+        searchText = buildSearchText(entry);
+    }
+    catch {
+        /* corrupt entry_json — key/path-only re-key */
+    }
+    db.transaction(() => {
+        const stale = db.prepare("SELECT id FROM entries WHERE entry_key = ?").get(opts.newEntryKey);
+        if (stale && stale.id !== row.id) {
+            // Full child-row cleanup (embeddings, entries_vec, utility scores,
+            // usage events, FTS + dirty marks) BEFORE the entries delete: the
+            // `embeddings` FK is non-CASCADE and `foreign_keys = ON`, so a bare
+            // entries delete would throw and roll back the entire re-key; and
+            // without it the FK-less child rows would orphan permanently.
+            deleteRelatedRows(db, [{ id: stale.id }]);
+            db.prepare("DELETE FROM entries WHERE id = ?").run(stale.id);
+        }
+        db.prepare("UPDATE entries SET entry_key = ?, dir_path = ?, file_path = ?, entry_json = ?, search_text = ? WHERE id = ?").run(opts.newEntryKey, path.dirname(opts.newFilePath), opts.newFilePath, entryJson, searchText, row.id);
+        if (opts.newDerivedFrom !== undefined) {
+            db.prepare("UPDATE entries SET derived_from = ? WHERE id = ?").run(opts.newDerivedFrom, row.id);
+        }
+        // Re-point usage history at the new ref (see the docstring): the bare
+        // spelling exactly, and the origin-qualified spelling by rewriting only
+        // the part after the last `//` (stored origins never contain `//`, so a
+        // qualified ref has exactly one — same normalization as
+        // getRetrievalCounts). Legacy DBs may predate usage_events.
+        bestEffort(() => {
+            // Live-asset-wins collision policy, mirroring the stale-entries eviction
+            // above and mv's state.db re-key: DETACHED orphan events (entry_id NULL
+            // — a deleted asset's history retained by a full rebuild) already
+            // sitting AT the new ref are evicted BEFORE the old→new rewrite. No
+            // stale entries row exists for them, so the deleteRelatedRows path
+            // never sees them (it deletes by entry_id only) — left in place, the
+            // moved asset would adopt the stranger's history: getRetrievalCounts
+            // reads by entry_ref immediately, and the next full rebuild's
+            // relinkUsageEvents would attach every stranger event by ref.
+            db.prepare("DELETE FROM usage_events WHERE entry_id IS NULL AND entry_ref = ?").run(opts.newRef);
+            db.prepare(`DELETE FROM usage_events
+          WHERE entry_id IS NULL
+            AND instr(entry_ref, '//') > 0
+            AND substr(entry_ref, instr(entry_ref, '//') + 2) = ?`).run(opts.newRef);
+            db.prepare("UPDATE usage_events SET entry_ref = ? WHERE entry_ref = ?").run(opts.newRef, opts.oldRef);
+            db.prepare(`UPDATE usage_events
+            SET entry_ref = substr(entry_ref, 1, instr(entry_ref, '//') + 1) || ?
+          WHERE instr(entry_ref, '//') > 0
+            AND substr(entry_ref, instr(entry_ref, '//') + 2) = ?`).run(opts.newRef, opts.oldRef);
+        }, "usage_events table may be missing on legacy DBs — no usage history to re-key");
+        db.prepare("INSERT OR IGNORE INTO entries_fts_dirty (entry_id) VALUES (?)").run(row.id);
+    })();
+    return row.id;
+}
 /**
  * Phase 2A / Rec 5: bulk-load positive feedback event counts for the given
  * entry ids. Used by the utility-decay forgetting curve to stabilize