@cleocode/core 2026.10.4 → 2026.10.5-rc.ci.672

package/dist/store/row-identity.js

@@ -62,11 +62,15 @@
  * @epic T12323
  */
 import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { resolveNexusVaultStatePath } from '@cleocode/paths';
 import { uuidv7 } from '../cloud/uuidv7.js';
 import { getLogger } from '../logger.js';
-import { acTextHash } from '../tasks/ac-table.js';
+import { acTextHash } from '../tasks/ac-identity.js';
 import { rowUidFillEnabled } from './row-identity-flag.js';
 import { BIRTH_FP_COLUMN, ROW_IDENTITY, rowIdentityColumns, rowIdentitySpec, UID_COLUMN, } from './row-identity-registry.js';
+import { readSyncFlags } from './sync/flags.js';
 import { hasTriggerSuspendTable, ownedTriggerDdl, TRIGGER_SUSPEND_TABLE_DDL, } from './sync/trigger-classes.js';
 import { schemaWritesAllowed } from './worktree-build-guard.js';
 export { BIRTH_FP_COLUMN, ROW_IDENTITY, rowIdentityColumns, rowIdentitySpec, UID_COLUMN };
@@ -1163,90 +1167,338 @@ export function preReleaseBirthFp(db, table, row) {
         .slice(0, 32);
 }
 /**
- * Birth fingerprints a pre-release build derived (e.g. a worktree CLI that
- * opened live cleocode, 2026-09-28) are cleared, so the fill re-derives them
- * with the release recipe. Targeted: a value is cleared ONLY when it equals
- * {@link preReleaseBirthFp} of its row, or hashes a fingerprint cleared here
- * (@ownerFp / @refFp; T12801); values from any other source (a
- * device that received them by sync, a store whose meta table was lost) are
- * kept, and alias rows are never touched. The uid recipe did not change, so
- * uids are kept. Runs only while the recipe marker is missing or stale, and
- * never once uids have synced ({@link ROW_IDENTITY_SYNCED_KEY}): `refused`.
+ * `_sync_*` tables whose rows do NOT make a store shared: the flags and
+ * bookkeeping (`_sync_meta`, read key by key below), the replica binding
+ * (`_sync_replica`, judged for a rebind below) and the clock. Every other
+ * journal table keys its rows by uid, so a refill would orphan them, and a
+ * journal table added later refuses by default (T13231).
  */
-function resetStaleIdentity(db, scope, writers) {
-    if (scope !== 'project' || !hasTable(db, ROW_IDENTITY_META_TABLE))
-        return 'none';
+const JOURNAL_TABLES_NOT_SHARING = new Set([
+    '_sync_meta',
+    '_sync_replica',
+    '_sync_clock',
+]);
+/** `_sync_meta` key prefixes that record journal state about this store (exact prefixes). */
+const JOURNAL_META_PREFIXES = ['suspect:', 'baseline:'];
+/**
+ * Alias tables: their rows point at uids (a re-key, a re-mint, a split-brain
+ * import). A store holding any is never refilled from scratch: the rewrite
+ * would leave the aliases pointing at uids no row carries.
+ */
+const IDENTITY_ALIAS_TABLES = ['tasks_display_id_aliases', 'tasks_uid_aliases'];
+/** Whether `table` holds at least one row. */
+function hasRows(db, table) {
+    return db.prepare(`SELECT 1 FROM main.${q(table)} LIMIT 1`).get() !== undefined;
+}
+/**
+ * Decide, strictly, whether a project store's row identity is unshared
+ * (T13231). Every signal that the uids may have left the store, or that
+ * local journal state references them, makes it `shared`; any record that
+ * cannot be read makes it `unknown`:
+ *
+ * - the shared marker (`row_identity_synced`: a receive or a send happened);
+ * - `sync.seal`/`sync.push`/`sync.pull` on;
+ * - rows in any `_sync_*` table except `_sync_meta`, `_sync_replica` and
+ *   `_sync_clock` (captures, frames, row meta and repair baselines, undo
+ *   images, sealed ops, the ledger, inbox, conflicts: all keyed by uid; a
+ *   table added later counts by default);
+ * - `suspect:` or `baseline:` keys in `_sync_meta` (journal state about this
+ *   store a refill would invalidate);
+ * - identity aliases exist (a re-key, re-mint or split-brain import pointed
+ *   at uids);
+ * - the store was rebound: a `_sync_replica` row not bound at `genesis`, or
+ *   more than one row (a copy, move or restore);
+ * - a vault snapshot of this store root was pushed or restored (an entry in
+ *   `<CLEO_HOME>/nexus-vault.json` with a checkpoint or a push in flight);
+ * - the project is linked to Cleo Nexus with no local vault entry for this
+ *   root: the path-keyed vault state cannot rule out a push from a moved path
+ *   or another CLEO_HOME, so this is `unknown` (resolved only by asking
+ *   Nexus: {@link RowIdentityShareOptions.nexusCheckedNone}).
+ *
+ * @param db - Connection on a project `cleo.db` (its file locates the root).
+ * @param options - Whether Cleo Nexus was asked and answered "none".
+ * @returns The state and the signals behind it.
+ * @task T13231
+ */
+export function rowIdentityShareState(db, options = {}) {
+    const signals = [];
+    const shared = (code, detail) => signals.push({ code, kind: 'shared', detail });
+    const unknown = (code, detail) => signals.push({ code, kind: 'unknown', detail });
+    if (readMeta(db, ROW_IDENTITY_SYNCED_KEY) !== undefined)
+        shared('synced-marker', 'row_identity_synced is set');
+    const flags = readSyncFlags(db);
+    for (const flag of ['sync.seal', 'sync.push', 'sync.pull']) {
+        if (flags[flag])
+            shared('sync-flag', `${flag} is on`);
+    }
+    // Exact prefix match: `_` is a LIKE wildcard.
+    const journal = db
+        .prepare("SELECT name FROM main.sqlite_master WHERE type = 'table' AND substr(name, 1, 6) = '_sync_' ORDER BY name")
+        .all();
+    for (const { name } of journal) {
+        if (!JOURNAL_TABLES_NOT_SHARING.has(name) && hasRows(db, name)) {
+            shared('journal-rows', `${name} holds rows (journal state keyed by uid)`);
+        }
+    }
+    if (hasTable(db, '_sync_meta')) {
+        for (const prefix of JOURNAL_META_PREFIXES) {
+            const n = db
+                .prepare('SELECT count(*) AS n FROM main._sync_meta WHERE substr(key, 1, ?) = ?')
+                .get(prefix.length, prefix).n;
+            if (n > 0)
+                shared('journal-meta', `_sync_meta holds ${n} ${prefix} key(s)`);
+        }
+    }
+    for (const table of IDENTITY_ALIAS_TABLES) {
+        if (hasTable(db, table) && hasRows(db, table)) {
+            shared('identity-aliases', `${table} holds rows (uids were re-keyed, re-minted or imported)`);
+        }
+    }
+    if (hasTable(db, '_sync_replica')) {
+        const rows = db.prepare('SELECT bound_why AS why FROM main._sync_replica').all();
+        if (rows.length > 1 || rows.some((r) => r.why !== 'genesis')) {
+            shared('rebound', 'the store was rebound (copied, moved or restored)');
+        }
+    }
+    const location = db.location();
+    if (!location) {
+        unknown('unreadable', 'the store file has no location (in-memory)');
+    }
+    else {
+        const root = resolve(dirname(dirname(location)));
+        let linked = false;
+        const linkFile = join(root, '.cleo', 'nexus-link.json');
+        if (existsSync(linkFile)) {
+            try {
+                const parsed = JSON.parse(readFileSync(linkFile, 'utf8'));
+                linked = Object.keys(parsed.links ?? {}).length > 0;
+            }
+            catch {
+                unknown('unreadable', `${linkFile} is unreadable`);
+            }
+        }
+        let vaultEntry = false;
+        const stateFile = resolveNexusVaultStatePath();
+        if (existsSync(stateFile)) {
+            try {
+                const parsed = JSON.parse(readFileSync(stateFile, 'utf8'));
+                for (const account of Object.values(parsed.accounts ?? {})) {
+                    for (const [key, stream] of Object.entries(account.streams ?? {})) {
+                        if (!key.endsWith(`|${root}`))
+                            continue;
+                        vaultEntry = true;
+                        if (stream.lastCheckpointId || stream.pushInFlight) {
+                            shared('vault-pushed', 'a vault snapshot of this project was pushed or restored');
+                        }
+                    }
+                }
+            }
+            catch {
+                unknown('unreadable', `${stateFile} is unreadable`);
+            }
+        }
+        if (linked && !vaultEntry && options.nexusCheckedNone !== true) {
+            unknown('nexus-linked-no-vault', 'the project is linked to Cleo Nexus and no local vault record proves it was never pushed');
+        }
+    }
+    return shareStateOf(signals);
+}
+/**
+ * Fold signals into a verdict: any `shared` signal makes it `shared`, else any
+ * `unknown` one makes it `unknown`, else `unshared`.
+ *
+ * @param signals - Every signal found.
+ * @returns The verdict.
+ * @task T13231
+ */
+export function shareStateOf(signals) {
+    const ordered = [
+        ...signals.filter((s) => s.kind === 'shared'),
+        ...signals.filter((s) => s.kind === 'unknown'),
+    ];
+    const state = ordered.length === 0 ? 'unshared' : ordered[0]?.kind === 'shared' ? 'shared' : 'unknown';
+    return { state, signals: ordered, reasons: ordered.map((s) => s.detail) };
+}
+/** Meta key recording the snapshot taken before the last full identity refill (T13231). */
+export const ROW_IDENTITY_REFILL_SNAPSHOT_KEY = 'row_identity_refill_snapshot';
+/**
+ * Snapshot the store before a full identity refill, so a rollback can restore
+ * the old uids: `VACUUM INTO <project>/.cleo/backups/sqlite/cleo-identity-refill-<ts>.db`.
+ *
+ * @returns The snapshot path.
+ */
+function snapshotBeforeRefill(db) {
+    const location = db.location();
+    // @sync-invariant none:local-only the local store has no file to snapshot; nothing is written
+    if (!location)
+        throw new Error('row identity refill: the store has no file to snapshot');
+    const dir = join(dirname(location), 'backups', 'sqlite');
+    mkdirSync(dir, { recursive: true });
+    const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+    const file = join(dir, `cleo-identity-refill-${stamp}.db`);
+    db.exec(`VACUUM INTO '${file.replaceAll("'", "''")}'`);
+    return file;
+}
+/**
+ * Take the pre-refill snapshot when this open's refill will re-derive the
+ * store from scratch (stale marker, identity values present, provably
+ * unshared). A `VACUUM INTO` cannot run inside a transaction, so a caller that
+ * runs the fill inside a bracket (identity-fill.ts) takes it first and passes
+ * it in through `prepareRowIdentity`'s `refillSnapshot` option.
+ *
+ * @param db - Connection on a project `cleo.db`, outside any transaction.
+ * @param scope - The store's scope.
+ * @param share - Share-state options (whether Cleo Nexus answered "none").
+ * @returns The snapshot path, or `null` when no full refill is due.
+ * @task T13231
+ */
+export function snapshotIfFullRefillDue(db, scope, share = {}) {
+    if (scope !== 'project' || !rowUidFillEnabled() || !hasTable(db, ROW_IDENTITY_META_TABLE))
+        return null;
     if (readMeta(db, ROW_IDENTITY_RECIPE_KEY) === ROW_IDENTITY_RECIPE)
-        return 'none';
-    const minted = fingerprintOrder('project', ROW_IDENTITY.project).filter((spec) => hasTable(db, spec.table) && columnsOf(db, spec.table).has(BIRTH_FP_COLUMN));
-    // A value is stale when it equals the pre-release recipe of its row, OR when
-    // it was derived from a stale value: a fingerprint that hashes its owner's
-    // or its criterion's fingerprint (@ownerFp / @refFp) whose source is being
-    // cleared. That covers a criterion whose uid and fingerprint an edit carried
-    // onto a new row (the pre-release recipe cannot be recomputed from the new
-    // row, T12801). Tables are visited owners first.
-    const stale = [];
-    const cleared = new Map(); // `${table}.${column}` → cleared values
-    const mark = (table, column, value) => {
-        if (value === null || value === undefined)
-            return;
-        const key = `${table}.${column}`;
-        const set = cleared.get(key) ?? new Set();
-        set.add(String(value));
-        cleared.set(key, set);
-    };
-    for (const spec of minted) {
-        const deps = (spec.birthFacts ?? [])
-            .map((fact) => fingerprintRef('project', spec, fact))
-            .filter((d) => d !== null);
-        const keyColumn = targetKey('project', spec.table);
-        const rows = db
-            .prepare(`SELECT rowid AS _rowid, * FROM main.${q(spec.table)} WHERE ${q(BIRTH_FP_COLUMN)} IS NOT NULL`)
-            .all();
-        for (const row of rows) {
-            const derivedFromStale = deps.some((d) => cleared.get(`${d.table}.${d.key}`)?.has(String(row[d.column] ?? '')));
-            // Three sources of a stale value, all kept (T12801 x T12802): derived
-            // from a value cleared in this pass, the pre-release recipe, or the
-            // 9.25 (v1) recipe.
-            if (derivedFromStale ||
-                row[BIRTH_FP_COLUMN] === preReleaseBirthFp(db, spec.table, row) ||
-                row[BIRTH_FP_COLUMN] === v1ReleaseBirthFp(db, spec.table, row)) {
-                stale.push({ table: spec.table, rowid: row._rowid });
-                mark(spec.table, keyColumn, row[keyColumn]);
-                mark(spec.table, UID_COLUMN, row[UID_COLUMN]);
+        return null;
+    const graveyard = hasTable(db, AC_UID_GRAVEYARD) &&
+        db.prepare(`SELECT 1 FROM main.${AC_UID_GRAVEYARD} LIMIT 1`).get() !== undefined;
+    if (!anyIdentityValue(db, scope) && !graveyard)
+        return null;
+    if (rowIdentityShareState(db, share).state !== 'unshared')
+        return null;
+    return snapshotBeforeRefill(db);
+}
+/**
+ * Whether the store's identity follows the current recipe (its marker is
+ * {@link ROW_IDENTITY_RECIPE}): no refill is due. Read-only.
+ *
+ * @param db - Connection on a project `cleo.db` (read-only is fine).
+ * @returns `true` when the marker is current.
+ * @task T13231
+ */
+export function rowIdentityRecipeCurrent(db) {
+    return (hasTable(db, ROW_IDENTITY_META_TABLE) &&
+        readMeta(db, ROW_IDENTITY_RECIPE_KEY) === ROW_IDENTITY_RECIPE);
+}
+/**
+ * What a full from-scratch refill clears: per declared table (alias tables
+ * excluded), the rows carrying any identity value, plus the AC uid graveyard
+ * rows under its table name. Read-only.
+ *
+ * @param db - Connection on a project `cleo.db` (read-only is fine).
+ * @returns Row count per table; tables with nothing to clear are omitted.
+ * @task T13231
+ */
+export function fullRefillPlan(db) {
+    const out = {};
+    for (const spec of ROW_IDENTITY.project) {
+        if (!hasTable(db, spec.table) ||
+            IDENTITY_ALIAS_TABLES.includes(spec.table)) {
+            continue;
+        }
+        const cols = columnsOf(db, spec.table);
+        const present = rowIdentityColumns('project', spec.table).filter((c) => cols.has(c));
+        if (present.length === 0)
+            continue;
+        const where = present.map((c) => `${q(c)} IS NOT NULL`).join(' OR ');
+        const n = db.prepare(`SELECT count(*) AS n FROM main.${q(spec.table)} WHERE ${where}`).get().n;
+        if (n > 0)
+            out[spec.table] = n;
+    }
+    if (hasTable(db, AC_UID_GRAVEYARD)) {
+        const n = db.prepare(`SELECT count(*) AS n FROM main.${AC_UID_GRAVEYARD}`).get().n;
+        if (n > 0)
+            out[AC_UID_GRAVEYARD] = n;
+    }
+    return out;
+}
+/** Whether any identity column of any declared table holds a value. */
+function anyIdentityValue(db, scope) {
+    for (const spec of ROW_IDENTITY[scope]) {
+        if (!hasTable(db, spec.table))
+            continue;
+        const cols = columnsOf(db, spec.table);
+        for (const column of rowIdentityColumns(scope, spec.table)) {
+            if (!cols.has(column))
+                continue;
+            if (db
+                .prepare(`SELECT 1 FROM main.${q(spec.table)} WHERE ${q(column)} IS NOT NULL LIMIT 1`)
+                .get()) {
+                return true;
             }
         }
     }
-    // The AC uid graveyard records deletions made while the recipe marker was
-    // missing or stale: with the fill off, the schema heal (T12878) restores
-    // its trigger, which then records the stale pre-release uid and birth_fp of
-    // every criterion deleted since. Relinking those would carry a stale
-    // fingerprint into the release recipe and, through the ordinal fallback,
-    // hand a deleted criterion's uid to an unrelated new one. They are not an
-    // older build's delete-and-recreate of one edit, so they are dropped in
-    // this same step, before the fill relinks anything (T12878 review F1).
-    const graveyardRows = scope === 'project' && hasTable(db, AC_UID_GRAVEYARD)
+    return false;
+}
+/**
+ * Reset identity derived under an older recipe (T13231). Runs only while the
+ * recipe marker is missing or stale:
+ *
+ * - no identity value and no graveyard row (a store the fill never ran on):
+ *   `none`, and the fill writes the marker;
+ * - provably unshared ({@link rowIdentityShareState}): a pre-refill snapshot
+ *   (taken by the caller outside its transaction, or here when the fill runs
+ *   bare), then every identity column of every declared table except the
+ *   alias tables is cleared, so the fill re-derives the store from scratch:
+ *   `cleared`;
+ * - shared or unknown: every value is kept and the reasons are logged:
+ *   `refused` (the marker is not written, so a later open, or
+ *   `cleo doctor row-identity --refill`, can still decide).
+ */
+function resetStaleIdentity(db, scope, writers, refillSnapshot, shareOptions = {}) {
+    if (scope !== 'project' || !hasTable(db, ROW_IDENTITY_META_TABLE))
+        return 'none';
+    if (readMeta(db, ROW_IDENTITY_RECIPE_KEY) === ROW_IDENTITY_RECIPE)
+        return 'none';
+    // T13231: a provably unshared store re-derives ALL of its identity from
+    // scratch. The targeted pass below kept uids "because the uid recipe did not
+    // change", which was false for symmetric relation edges and criteria: a
+    // device filling the same data from nothing derived different uids. Values
+    // that may have left the store are never rewritten here.
+    // Nothing to re-derive (a store the fill never ran on): the marker is
+    // simply written, whatever the share state.
+    const graveyardRows = hasTable(db, AC_UID_GRAVEYARD)
         ? db.prepare(`SELECT count(*) AS n FROM main.${AC_UID_GRAVEYARD}`).get().n
         : 0;
-    if (stale.length === 0 && graveyardRows === 0)
+    if (!anyIdentityValue(db, scope) && graveyardRows === 0)
         return 'none';
-    if (readMeta(db, ROW_IDENTITY_SYNCED_KEY) !== undefined)
-        return 'refused';
-    db.exec('SAVEPOINT row_identity_reset');
-    try {
-        if (graveyardRows > 0)
-            writers.clearAcUidGraveyardNative(db);
-        for (const { table, rowid } of stale) {
-            writers.clearBirthFpNative(db, table, rowid);
+    const share = rowIdentityShareState(db, shareOptions);
+    if (share.state === 'unshared') {
+        // The snapshot is taken outside any transaction: by the caller of a
+        // bracketed fill, or here when the fill runs bare.
+        const snapshot = refillSnapshot ?? (db.isTransaction ? null : snapshotBeforeRefill(db));
+        if (!snapshot) {
+            getLogger('row-identity').error({ scope }, 'a full identity refill is due but no pre-refill snapshot could be taken (inside a transaction); kept as they are');
+            return 'refused';
         }
-        db.exec('RELEASE SAVEPOINT row_identity_reset');
-    }
-    catch (error) {
-        db.exec('ROLLBACK TO SAVEPOINT row_identity_reset');
-        db.exec('RELEASE SAVEPOINT row_identity_reset');
-        throw error;
+        db.exec('SAVEPOINT row_identity_full_refill');
+        try {
+            if (graveyardRows > 0)
+                writers.clearAcUidGraveyardNative(db);
+            for (const spec of ROW_IDENTITY[scope]) {
+                // The alias tables are empty here (non-empty is `shared`); never cleared.
+                if (!hasTable(db, spec.table) ||
+                    IDENTITY_ALIAS_TABLES.includes(spec.table)) {
+                    continue;
+                }
+                const cols = columnsOf(db, spec.table);
+                const present = rowIdentityColumns(scope, spec.table).filter((c) => cols.has(c));
+                if (present.length > 0)
+                    writers.clearIdentityColumnsNative(db, spec.table, present);
+            }
+            writers.writeRowIdentityMetaNative(db, ROW_IDENTITY_REFILL_SNAPSHOT_KEY, snapshot);
+            db.exec('RELEASE SAVEPOINT row_identity_full_refill');
+        }
+        catch (error) {
+            db.exec('ROLLBACK TO SAVEPOINT row_identity_full_refill');
+            db.exec('RELEASE SAVEPOINT row_identity_full_refill');
+            throw error;
+        }
+        getLogger('row-identity').info({ scope, snapshot }, 'stale identity on an unshared store: every identity value cleared for a from-scratch refill');
+        return 'cleared';
     }
-    return 'cleared';
+    getLogger('row-identity').error({ scope, state: share.state, reasons: share.reasons }, share.state === 'shared'
+        ? 'identity values predate the current recipe but may have left this store; kept as they are'
+        : 'identity values predate the current recipe and the store cannot be proven unshared; kept as they are. ' +
+            'Remedy: `cleo doctor row-identity --refill` asks Cleo Nexus and shows the plan');
+    return 'refused';
 }
 /**
  * Record that the store's identity values follow {@link ROW_IDENTITY_RECIPE}.
@@ -1468,6 +1720,121 @@ export function missingRowIdentitySchema(db) {
     }
     return missing;
 }
+/**
+ * Create the fill's partial indexes: per minted table, the rows still without
+ * a birth fingerprint, so the open's pending probe finds them by index, not a
+ * scan (T12341 C1). Fill-on only: they serve the fill and nothing else, so a
+ * store the fill never ran on (the default) keeps exactly the identity schema
+ * of the migration, and its opens heal nothing new.
+ *
+ * @returns The statements run (empty when every index exists).
+ */
+function ensureFillIndexes(db, scope) {
+    const run = [];
+    for (const spec of ROW_IDENTITY[scope]) {
+        if (spec.kind !== 'minted' || !hasTable(db, spec.table))
+            continue;
+        if (hasObject(db, 'index', birthFpNullIndex(spec.table)))
+            continue;
+        const stmt = `CREATE INDEX IF NOT EXISTS main.${q(birthFpNullIndex(spec.table))} ON ${q(spec.table)} (${q(BIRTH_FP_COLUMN)}) WHERE ${q(BIRTH_FP_COLUMN)} IS NULL`;
+        db.exec(stmt);
+        run.push(stmt);
+    }
+    return run;
+}
+/** Whether every fill partial index ({@link ensureFillIndexes}) exists. */
+function fillIndexesPresent(db, scope) {
+    return ROW_IDENTITY[scope].every((spec) => spec.kind !== 'minted' ||
+        !hasTable(db, spec.table) ||
+        hasObject(db, 'index', birthFpNullIndex(spec.table)));
+}
+/** Name of a minted table's partial index over rows with a NULL birth fingerprint (T12341 C1). */
+function birthFpNullIndex(table) {
+    // `idx_<table>_<column>`, the convention of the identity indexes, so a
+    // rollback (spec §13) or a pre-migration fixture that drops each identity
+    // column's index before the column drops this one too.
+    return `idx_${table}_${BIRTH_FP_COLUMN}`;
+}
+/**
+ * What the fill would do on this open, found by index probes alone (T12341
+ * C1). A store the fill has already run on answers `[]` and the open skips the
+ * fill pass (and never loads its writers). Every probe is correct regardless
+ * of rowid reuse: it looks for the rows themselves, never a rowid watermark.
+ *
+ * - `schema`: part of the identity schema, or a fill partial index, is missing
+ *   (the full pass creates it);
+ * - `recipe`: the recipe marker is missing or stale (the refill runs, or is
+ *   refused and reported once uids have synced);
+ * - `graveyard:<n>`: an older build deleted acceptance criteria whose uids wait
+ *   to be re-linked;
+ * - `uid:<table>`: a row without a uid (the unique uid index, or the uid
+ *   primary key, holds the NULLs);
+ * - `birth_fp:<table>`: a minted row without a birth fingerprint (the partial
+ *   index {@link birthFpNullIndex});
+ * - `ref:<table>.<column>`: a NULL stored reference fact that now resolves
+ *   (its column index holds the NULLs; a reference that still dangles is not
+ *   work).
+ *
+ * Requires {@link registerRowUidFunction} on the connection (the stored
+ * reference probe evaluates the AC text hash).
+ *
+ * @param db - Connection on a `cleo.db`.
+ * @param scope - The store's scope.
+ * @returns The pending work, `[]` when the identity is complete.
+ * @task T12341
+ */
+export function rowIdentityFillPending(db, scope) {
+    if (ROW_IDENTITY[scope].length === 0)
+        return [];
+    // The probes name identity columns: a store missing any of its identity
+    // schema is pending the full pass, which heals it first.
+    if (scope === 'project' &&
+        (missingRowIdentitySchema(db).length > 0 || !fillIndexesPresent(db, scope))) {
+        return ['schema'];
+    }
+    const pending = [];
+    // A stale marker is work even when the identity has synced: the pass then
+    // refuses the refill and says so (refill 'refused'), every open, until the
+    // store is repaired — that anomaly must stay loud, not become a fast path.
+    if (scope === 'project' && readMeta(db, ROW_IDENTITY_RECIPE_KEY) !== ROW_IDENTITY_RECIPE) {
+        pending.push('recipe');
+    }
+    if (scope === 'project' &&
+        hasTable(db, AC_UID_GRAVEYARD) &&
+        db.prepare(`SELECT 1 FROM main.${AC_UID_GRAVEYARD} LIMIT 1`).get() !== undefined) {
+        pending.push('graveyard');
+    }
+    const any = (table, where) => db.prepare(`SELECT 1 FROM main.${q(table)} WHERE ${where} LIMIT 1`).get() !== undefined;
+    for (const spec of ROW_IDENTITY[scope]) {
+        if (!hasTable(db, spec.table))
+            continue;
+        if (any(spec.table, `${q(UID_COLUMN)} IS NULL`))
+            pending.push(`uid:${spec.table}`);
+        if (spec.kind === 'minted' && any(spec.table, `${q(BIRTH_FP_COLUMN)} IS NULL`)) {
+            pending.push(`birth_fp:${spec.table}`);
+        }
+        const row = `main.${q(spec.table)}`;
+        for (const ref of spec.storedRefUids ?? []) {
+            if (any(spec.table, `${q(ref.column)} IS NULL AND (${storedRefSql(scope, ref, row)}) IS NOT NULL`)) {
+                pending.push(`ref:${spec.table}.${ref.column}`);
+            }
+        }
+    }
+    return pending;
+}
+/** The report of an open whose identity was already complete (nothing written). */
+function steadyReport() {
+    return {
+        filled: {},
+        refsFilled: {},
+        fingerprinted: {},
+        relinked: 0,
+        unfilled: {},
+        findings: { unknownBirth: {}, danglingRefs: {}, mirrorEdges: {} },
+        healed: [],
+        refill: 'none',
+    };
+}
 export function prepareRowIdentity(db, scope, options = {}) {
     if (ROW_IDENTITY[scope].length === 0)
         return null;
@@ -1475,16 +1842,23 @@ export function prepareRowIdentity(db, scope, options = {}) {
         return null;
     const log = getLogger('row-identity');
     try {
+        // T12341 C1: a store whose identity is already complete (and whose schema
+        // is whole) gets only this connection's uid triggers. No table is scanned,
+        // nothing is written, and the writers are never needed.
+        registerRowUidFunction(db, scope);
+        const pending = options.pending ?? rowIdentityFillPending(db, scope);
+        if (pending.length === 0) {
+            if (options.triggers !== false)
+                installRowUidTriggers(db, scope);
+            return steadyReport();
+        }
         const healed = [
             ...(scope === 'project' ? ensureIdentityTables(db) : []),
             ...ensureRowIdentitySchema(db, scope),
+            ...ensureFillIndexes(db, scope),
         ];
-        registerRowUidFunction(db, scope);
         const writers = options.writers ?? requireWriters();
-        const refill = resetStaleIdentity(db, scope, writers);
-        if (refill === 'refused') {
-            log.error({ scope, marker: readMeta(db, ROW_IDENTITY_RECIPE_KEY) }, 'identity values predate the current recipe but uids have synced; kept as they are');
-        }
+        const refill = resetStaleIdentity(db, scope, writers, options.refillSnapshot, options.share);
         const filled = fillRowUids(db, scope, writers);
         if (refill !== 'refused')
             writeRecipeMarker(db, writers);