@cleocode/core 2026.9.24 → 2026.9.26

package/dist/store/sqlite-data-accessor.js

@@ -16,16 +16,21 @@ import { ARCHIVE_REASON_TOMBSTONE, ExitCode, } from '@cleocode/contracts';
 import { and, eq, getTableColumns, inArray, isNull, like, lte, ne, notInArray, or, sql, } from 'drizzle-orm';
 import { CleoError } from '../errors.js';
 import { captureProjectScope as captureTaskAccessorScope, getProjectRoot, worktreeScope, } from '../project-scope.js';
+import { acTextHash, buildAcRowId } from '../tasks/ac-table.js';
+import { generateAuditLogId, pruneAcBindingsForAcIds, pruneAcBindingsForTask, pruneOrphanAcBindings, selectOrphanAcBindings, } from './ac-binding-prune.js';
 import { withBackgroundOpCommitBoundary } from './background-ops.js';
 import { archivedTaskToRow, rowToSession, rowToTask, taskToRow } from './converters.js';
 import { cleanupBrainRefsOnSessionDelete } from './cross-db-cleanup.js';
 import { batchUpdateDependencies, insertNewTask, loadDependenciesForTasks, loadRelationsForTasks, parseLabels, updateDependencies, updateTaskLabels, upsertSession, upsertTask, } from './db-helpers.js';
+import { fillRowUids, parseStoreTimestamp, registerRowIdentityWriters, rowIdentityShared, } from './row-identity.js';
+import { rowUidFillEnabled } from './row-identity-flag.js';
+import { ROW_IDENTITY } from './row-identity-registry.js';
 import { tasksAuditLog } from './schema/cleo-project/audit.js';
 import { resolveCurrentSession } from './session-store.js';
 import { closeDb, getDb, getNativeTasksDb } from './sqlite.js';
 import { TERMINAL_TASK_STATUSES } from './status-registry.js';
 import { claimAllows, claimColumnsOf, claimFromColumns, isClaimExpired, leaseExpiresAtFrom, taskClaimedError, taskClaimLeaseMs, } from './task-claim.js';
-import { nextTaskVersion, taskConflictError, taskVersion } from './task-version.js';
+import { nextTaskVersion, taskConflictError, taskVersion, } from './task-version.js';
 import * as schema from './tasks-schema.js';
 import { assertTwinCollapseWritable, bareCounterOf, mirrorCounterToBare } from './twin-collapse.js';
 import { runHeartbeatWrite, withWriteRetry } from './with-retry.js';
@@ -37,13 +42,67 @@ import { runHeartbeatWrite, withWriteRetry } from './with-retry.js';
  */
 let _txSavepointCounter = 0;
 /**
- * Generate a unique audit log entry ID.
- * @task T4837
+ * Evidence bindings for a set of CURRENT AC ids (T12341).
+ *
+ * A binding is matched through the criterion's uid (`ac_uid`), which survives
+ * an AC edit, and falls back to `ac_id` for a binding whose uid is not filled.
+ * A binding recorded against an older text of a criterion is reported under
+ * the criterion's current id, so callers keyed by AC id keep working, and is
+ * marked `stale` when the text hash it recorded (`ac_text_hash`) differs from
+ * the criterion's current text: evidence for different text never satisfies a
+ * gate (spec §8.2).
  */
-function generateAuditLogId() {
-    const epoch = Math.floor(Date.now() / 1000);
-    const rand = Math.random().toString(36).slice(2, 8);
-    return `log-${epoch}-${rand}`;
+async function selectAcBindings(db, acIds) {
+    if (acIds.length === 0)
+        return [];
+    const b = schema.evidenceAcBindings;
+    const ac = schema.taskAcceptanceCriteria;
+    const ids = acIds;
+    const columns = {
+        id: b.id,
+        evidenceAtomId: b.evidenceAtomId,
+        acId: b.acId,
+        currentAcId: ac.id,
+        currentAcText: ac.text,
+        recordedTextHash: b.acTextHash,
+        bindingType: b.bindingType,
+        createdAt: b.createdAt,
+    };
+    // Two indexed lookups rather than one OR across the join: by the current
+    // criterion's uid, then by the recorded ac_id.
+    const byUid = await db
+        .select(columns)
+        .from(b)
+        .innerJoin(ac, eq(ac.uid, b.acUid))
+        .where(inArray(ac.id, ids))
+        .all();
+    const byId = await db
+        .select(columns)
+        .from(b)
+        .leftJoin(ac, eq(ac.uid, b.acUid))
+        .where(inArray(b.acId, ids))
+        .all();
+    const rows = [...byUid, ...byId];
+    const wanted = new Set(ids);
+    const seen = new Set();
+    const out = [];
+    for (const r of rows) {
+        if (seen.has(r.id))
+            continue;
+        seen.add(r.id);
+        const stale = r.recordedTextHash !== null &&
+            r.currentAcText !== null &&
+            acTextHash(r.currentAcText) !== r.recordedTextHash;
+        out.push({
+            id: r.id,
+            evidenceAtomId: r.evidenceAtomId,
+            acId: r.currentAcId && wanted.has(r.currentAcId) ? r.currentAcId : r.acId,
+            bindingType: r.bindingType,
+            createdAt: r.createdAt,
+            ...(stale ? { stale: true } : {}),
+        });
+    }
+    return out;
 }
 // ---- Schema meta helpers ----
 /** Read a JSON blob from the schema_meta table by key. */
@@ -132,6 +191,519 @@ export function advanceTaskIdSequence(nativeDb, floor) {
         .get();
     return row?.counter;
 }
+/**
+ * Give the task with `uid` the display id `toId`: a compare-and-set on the
+ * stored version AND claim lease that advances the version (so a stale
+ * `--if-match` writer fails, #1698), with the claim columns carried unchanged
+ * (#1701), then every local reference rewritten. Runs in the caller's
+ * transaction with foreign keys deferred to its commit.
+ *
+ * A collision re-mint is a system write: it passes no claim guard and never
+ * takes or drops a lease, but the version bump makes the lease holder's next
+ * guarded write re-read. A caller acting for a session (a manual rename)
+ * passes `guard`: `expectedUpdatedAt` fails with `E_CONFLICT` when the task
+ * moved on, `claim` fails with `E_TASK_CLAIMED` when another session holds it.
+ *
+ * @param nativeDb - The project `cleo.db` handle holding the transaction.
+ * @param uid - Uid of the task to rename.
+ * @param toId - Its new display id.
+ * @param refs - Columns that hold task display ids.
+ * @param guard - Optional version / claim guard.
+ * @returns The id it had and the rows rewritten per `table.column`.
+ * @task T12341
+ * @task T12748
+ */
+export function renameTaskDisplayIdNative(nativeDb, uid, toId, refs, guard = {}) {
+    const current = nativeDb
+        .prepare(`SELECT id, updated_at AS updatedAt, created_at AS createdAt,
+              claimed_by_session AS claimedBySession, claimed_by_agent AS claimedByAgent,
+              claimed_at AS claimedAt, lease_expires_at AS leaseExpiresAt
+         FROM tasks_tasks WHERE uid = ?`)
+        .get(uid);
+    if (!current)
+        throw new Error(`No task with uid ${uid}`);
+    if (guard.expectedUpdatedAt !== undefined && guard.expectedUpdatedAt !== taskVersion(current)) {
+        throw taskConflictError(current.id, guard.expectedUpdatedAt, current);
+    }
+    if (guard.claim)
+        assertClaimAllowed(current.id, current, guard.claim, []);
+    nativeDb.exec('PRAGMA defer_foreign_keys = ON');
+    const changed = nativeDb
+        .prepare(`UPDATE tasks_tasks SET id = ?, updated_at = ?
+        WHERE uid = ? AND id = ? AND updated_at IS ? AND claimed_by_session IS ?
+          AND lease_expires_at IS ?`)
+        .run(toId, nextTaskVersion(current), uid, current.id, current.updatedAt, current.claimedBySession, current.leaseExpiresAt).changes;
+    if (Number(changed) !== 1) {
+        throw taskConflictError(current.id, taskVersion(current), null);
+    }
+    recordLocalRename(nativeDb, uid, current.id, toId, taskVersion(current));
+    const rewritten = {};
+    const q = (name) => `"${name.replaceAll('"', '""')}"`;
+    for (const ref of refs) {
+        const table = `main.${q(ref.table)}`;
+        const col = q(ref.column);
+        const n = ref.jsonArray
+            ? nativeDb
+                .prepare(`UPDATE ${table} SET ${col} = (
+               SELECT json_group_array(CASE WHEN j.value = ? THEN ? ELSE j.value END)
+                 FROM json_each(${table}.${col}) j)
+             WHERE json_valid(${col}) AND EXISTS (
+               SELECT 1 FROM json_each(${table}.${col}) j WHERE j.value = ?)`)
+                .run(current.id, toId, current.id).changes
+            : nativeDb.prepare(`UPDATE ${table} SET ${col} = ? WHERE ${col} = ?`).run(toId, current.id)
+                .changes;
+        if (Number(n) > 0)
+            rewritten[`${ref.table}.${ref.column}`] = Number(n);
+    }
+    for (const [key, n] of Object.entries(rederiveAcIdsNative(nativeDb, current.id, toId))) {
+        if (n > 0)
+            rewritten[key] = n;
+    }
+    return { fromId: current.id, rewritten };
+}
+/**
+ * After a task's display id changed from `fromId` to `toId`, re-derive the
+ * ids of the acceptance criteria derived from it (`buildAcRowId(taskId,
+ * identity)`): the task's own criteria, and a parent's child-projection
+ * criteria (`child:<id>`, whose source key is rewritten too). The binding and
+ * history rows that point at a re-derived id follow. A criterion whose id was
+ * not derived from the old id (an explicit id) keeps it. Without this, two
+ * tasks that once shared a display id keep identical ids for same-text
+ * criteria ("tests pass") and collide on every merge (T12799).
+ *
+ * @param nativeDb - The project `cleo.db` handle, inside the rename's transaction.
+ * @param fromId - The task's old display id.
+ * @param toId - Its new display id (the task row already carries it).
+ * @returns Rows rewritten per `table.column`.
+ * @task T12799
+ */
+export function rederiveAcIdsNative(nativeDb, fromId, toId) {
+    const count = {};
+    const bump = (key, n) => {
+        count[key] = (count[key] ?? 0) + Number(n);
+    };
+    const has = (table) => nativeDb
+        .prepare("SELECT 1 AS x FROM sqlite_master WHERE type = 'table' AND name = ?")
+        .get(table) !== undefined;
+    if (!has('tasks_task_acceptance_criteria'))
+        return count;
+    const oldChild = `child:${fromId}`;
+    const rows = nativeDb
+        .prepare(`SELECT id, task_id AS taskId, kind, text, source_key AS sourceKey
+         FROM tasks_task_acceptance_criteria WHERE task_id = ? OR source_key = ?`)
+        .all(toId, oldChild);
+    const followers = ['tasks_evidence_ac_bindings', 'tasks_task_acceptance_criteria_history'].filter(has);
+    for (const row of rows) {
+        const ownerBefore = row.taskId === toId ? fromId : row.taskId;
+        const sourceAfter = row.sourceKey === oldChild ? `child:${toId}` : row.sourceKey;
+        const identity = (source) => (row.kind === 'text' ? row.text : (source ?? ''));
+        const derived = row.id === buildAcRowId(ownerBefore, identity(row.sourceKey));
+        const newId = derived ? buildAcRowId(row.taskId, identity(sourceAfter)) : row.id;
+        if (newId === row.id && sourceAfter === row.sourceKey)
+            continue;
+        bump('tasks_task_acceptance_criteria.id', nativeDb
+            .prepare('UPDATE tasks_task_acceptance_criteria SET id = ?, source_key = ? WHERE id = ?')
+            .run(newId, sourceAfter, row.id).changes);
+        if (newId === row.id)
+            continue;
+        for (const table of followers) {
+            bump(`${table}.ac_id`, nativeDb.prepare(`UPDATE ${table} SET ac_id = ? WHERE ac_id = ?`).run(newId, row.id)
+                .changes);
+        }
+    }
+    return count;
+}
+/**
+ * Insert a display-id alias row. Idempotent on its uid, and order-independent
+ * (T12800): when two displacements write one alias uid, the stored row is
+ * replaced only when `precedes(incoming, stored)` says the incoming one ranks
+ * first, so every replica keeps the same row whatever order the ops arrived
+ * in. The caller ranks by HLC order (`compareHlc`), never by text: stored
+ * values may be in either HLC format (T12802).
+ *
+ * @param nativeDb - The project `cleo.db` handle.
+ * @param row - The alias.
+ * @param precedes - Whether `incoming` ranks before the `stored` row of the same uid.
+ * @task T12341
+ */
+export function insertDisplayIdAliasNative(nativeDb, row, precedes) {
+    const stored = nativeDb
+        .prepare(`SELECT uid, entity_table AS entityTable, display_id AS displayId, entity_uid AS entityUid,
+              reason, origin, displaced_hlc AS displacedHlc, created_at AS createdAt,
+              entity_birth_fp AS entityBirthFp
+         FROM tasks_display_id_aliases WHERE uid = ?`)
+        .get(row.uid);
+    if (!stored) {
+        nativeDb
+            .prepare(`INSERT INTO tasks_display_id_aliases
+           (uid, entity_table, display_id, entity_uid, reason, origin, displaced_hlc, created_at,
+            entity_birth_fp)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`)
+            .run(row.uid, row.entityTable, row.displayId, row.entityUid, row.reason, row.origin, row.displacedHlc, row.createdAt, row.entityBirthFp);
+        return;
+    }
+    if (!precedes(row, stored))
+        return;
+    nativeDb
+        .prepare(`UPDATE tasks_display_id_aliases
+          SET origin = ?, displaced_hlc = ?, created_at = ?,
+              entity_birth_fp = coalesce(entity_birth_fp, ?)
+        WHERE uid = ?`)
+        .run(row.origin, row.displacedHlc, row.createdAt, row.entityBirthFp, row.uid);
+}
+/**
+ * Delete one display-id alias row (a local alias whose entity was re-keyed is
+ * re-inserted under its new entity uid by the caller).
+ *
+ * @param nativeDb - The project `cleo.db` handle.
+ * @param uid - The alias row's uid.
+ * @task T12341
+ */
+export function deleteDisplayIdAliasNative(nativeDb, uid) {
+    nativeDb.prepare('DELETE FROM tasks_display_id_aliases WHERE uid = ?').run(uid);
+}
+/**
+ * Insert a uid re-key alias row (idempotent on its uid).
+ *
+ * @param nativeDb - The project `cleo.db` handle.
+ * @param row - The alias.
+ * @task T12341
+ */
+export function insertUidAliasNative(nativeDb, row) {
+    nativeDb
+        .prepare(`INSERT OR IGNORE INTO tasks_uid_aliases
+         (uid, entity_table, old_uid, old_birth_fp, new_uid, origin, displaced_hlc, created_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?)`)
+        .run(row.uid, row.entityTable, row.oldUid, row.oldBirthFp, row.newUid, row.origin, row.displacedHlc, row.createdAt);
+}
+/**
+ * Hold an incoming row the merge cannot place yet (replacing an older hold of
+ * the same row).
+ *
+ * @param nativeDb - The project `cleo.db` handle.
+ * @param row - The held row.
+ * @task T12341
+ */
+export function insertQuarantineNative(nativeDb, row) {
+    nativeDb
+        .prepare(`INSERT INTO tasks_identity_quarantine
+         (entity_table, uid, birth_fp, reason, contested_id, row_json, received_hlc, created_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+       ON CONFLICT(entity_table, uid, birth_fp) DO UPDATE SET
+         reason = excluded.reason, contested_id = excluded.contested_id,
+         row_json = excluded.row_json, received_hlc = excluded.received_hlc,
+         created_at = excluded.created_at`)
+        .run(row.entityTable, row.uid, row.birthFp, row.reason, row.contestedId, row.rowJson, row.receivedHlc, row.createdAt);
+}
+/**
+ * Drop a held row (released or superseded).
+ *
+ * @param nativeDb - The project `cleo.db` handle.
+ * @param key - The held row's table, uid and birth fingerprint.
+ * @task T12341
+ */
+export function deleteQuarantineNative(nativeDb, key) {
+    nativeDb
+        .prepare('DELETE FROM tasks_identity_quarantine WHERE entity_table = ? AND uid = ? AND birth_fp = ?')
+        .run(key.entityTable, key.uid, key.birthFp);
+}
+/**
+ * Write a row-identity meta value (the recipe marker, a re-mint record).
+ *
+ * @param nativeDb - The project `cleo.db` handle.
+ * @param key - Meta key.
+ * @param value - Meta value.
+ * @task T12341
+ */
+export function writeRowIdentityMetaNative(nativeDb, key, value) {
+    nativeDb
+        .prepare(`INSERT INTO tasks_row_identity_meta (key, value) VALUES (?, ?)
+       ON CONFLICT(key) DO UPDATE SET value = excluded.value`)
+        .run(key, value);
+}
+/**
+ * Hand a criterion back the uid its deleted predecessor carried (AC uid
+ * graveyard re-link, spec §6.5), with that predecessor's birth fingerprint.
+ *
+ * @param nativeDb - The project `cleo.db` handle.
+ * @param acId - The criterion to re-link (its uid is NULL).
+ * @param uid - The uid to hand back.
+ * @param birthFp - The fingerprint that goes with it, when recorded.
+ * @returns Rows changed (0 or 1).
+ * @task T12341
+ */
+export function relinkAcUidNative(nativeDb, acId, uid, birthFp) {
+    return Number(nativeDb
+        .prepare('UPDATE tasks_task_acceptance_criteria SET uid = ?, birth_fp = COALESCE(?, birth_fp) WHERE id = ? AND uid IS NULL')
+        .run(uid, birthFp, acId).changes);
+}
+/**
+ * Empty the AC uid graveyard (after the open pass consumed it).
+ *
+ * @param nativeDb - The project `cleo.db` handle.
+ * @task T12341
+ */
+export function clearAcUidGraveyardNative(nativeDb) {
+    nativeDb.exec('DELETE FROM tasks_ac_uid_graveyard');
+}
+/**
+ * Read the birth of task `taskId` before an overwrite replaces it.
+ *
+ * @param nativeDb - The project `cleo.db` handle.
+ * @param taskId - The task about to be overwritten.
+ * @returns Its birth, or `undefined` when there is no such row.
+ * @task T12806
+ */
+export function readReplacedTaskBirthNative(nativeDb, taskId) {
+    return nativeDb
+        .prepare('SELECT created_at AS createdAt, uid FROM tasks_tasks WHERE id = ?')
+        .get(taskId);
+}
+/**
+ * After an overwrite import replaced task `taskId`, keep or re-key its
+ * identity (T12806 review):
+ *
+ * - the SAME task (same id, same birth instant as before the overwrite) keeps
+ *   its identity. Sameness is decided on the immutable birth facts, never on
+ *   the title or type: a task retitled here and re-imported unchanged stays
+ *   the same row;
+ * - refused once identity is shared: the overwrite would re-point a uid other
+ *   devices hold at different work;
+ * - otherwise the task, the natural rows keyed by it (dependencies,
+ *   relations, labels) and its criteria are re-derived from the new row, now,
+ *   and every AC history row and binding that pointed at one of those
+ *   criteria is RE-KEYED to the criterion's new uid, found by the criterion's
+ *   old uid as well as by its current id. A binding whose `ac_id` is stale
+ *   (#1731) keeps resolving: its evidence is kept, never dropped.
+ *
+ * @param nativeDb - The project `cleo.db` handle holding the transaction.
+ * @param taskId - The overwritten task.
+ * @param before - Its birth before the overwrite ({@link readReplacedTaskBirthNative}).
+ * @task T12806
+ */
+export function clearReplacedTaskIdentityNative(nativeDb, taskId, before) {
+    const row = nativeDb
+        .prepare('SELECT uid, birth_fp AS fp, created_at AS createdAt FROM tasks_tasks WHERE id = ?')
+        .get(taskId);
+    if (!row || (row.uid === null && row.fp === null))
+        return;
+    if (before) {
+        const was = parseStoreTimestamp(before.createdAt);
+        if (was !== null && was === parseStoreTimestamp(row.createdAt)) {
+            return; // the same task, re-imported: its identity stands
+        }
+    }
+    if (rowIdentityShared(nativeDb)) {
+        throw new CleoError(ExitCode.VALIDATION_ERROR, `Task ${taskId} cannot be overwritten by an import: its identity is shared with other devices`, {
+            fix: 'Import it under a new id (the default duplicate strategy), or edit the task instead of overwriting it.',
+            details: { field: 'taskId', actual: taskId },
+        });
+    }
+    const has = (table) => nativeDb
+        .prepare("SELECT 1 AS x FROM sqlite_master WHERE type = 'table' AND name = ?")
+        .get(table) !== undefined;
+    nativeDb.prepare('UPDATE tasks_tasks SET uid = NULL, birth_fp = NULL WHERE id = ?').run(taskId);
+    for (const spec of ROW_IDENTITY.project) {
+        if (spec.kind !== 'natural' || !has(spec.table))
+            continue;
+        const cols = (spec.keyRefs ?? []).filter((r) => r.table === 'tasks_tasks').map((r) => r.column);
+        if (cols.length === 0)
+            continue;
+        nativeDb
+            .prepare(`UPDATE main.${quoteIdent(spec.table)} SET uid = NULL WHERE ${cols.map((c) => `${quoteIdent(c)} = ?`).join(' OR ')}`)
+            .run(...cols.map(() => taskId));
+    }
+    const children = ['tasks_task_acceptance_criteria_history', 'tasks_evidence_ac_bindings'].filter(has);
+    const criteria = has('tasks_task_acceptance_criteria')
+        ? nativeDb
+            .prepare('SELECT id, uid FROM tasks_task_acceptance_criteria WHERE task_id = ?')
+            .all(taskId)
+        : [];
+    if (criteria.length > 0) {
+        nativeDb
+            .prepare('UPDATE tasks_task_acceptance_criteria SET uid = NULL, birth_fp = NULL WHERE task_id = ?')
+            .run(taskId);
+    }
+    // Re-derive the task, its natural rows and its criteria now, inside the
+    // import transaction, so the children can be re-keyed to the new uids.
+    fillRowUids(nativeDb, 'project');
+    const newUid = nativeDb.prepare('SELECT uid FROM tasks_task_acceptance_criteria WHERE id = ?');
+    let rekeyed = 0;
+    for (const ac of criteria) {
+        const now = newUid.get(ac.id)?.uid ?? null;
+        for (const table of children) {
+            // By the criterion's old uid (a stale ac_id keeps it) or its current id.
+            rekeyed += Number(nativeDb
+                .prepare(`UPDATE main.${quoteIdent(table)} SET ac_uid = ?, birth_fp = NULL
+              WHERE ac_id = ? OR (? IS NOT NULL AND ac_uid = ?)`)
+                .run(now, ac.id, ac.uid, ac.uid).changes);
+        }
+    }
+    // Their fingerprints hash the criterion's: re-derive them against the new one.
+    if (rekeyed > 0)
+        fillRowUids(nativeDb, 'project');
+}
+/** Quote an identifier for the dynamic row-identity writes below. */
+function quoteIdent(name) {
+    return `"${name.replaceAll('"', '""')}"`;
+}
+/**
+ * Fill a NULL identity column (`uid`, `birth_fp`, a stored reference uid) of a
+ * declared table from its recipe SQL (the row-uid open pass, spec §6.1).
+ *
+ * @param nativeDb - The `cleo.db` handle holding the cold-open lease.
+ * @param table - Declared table.
+ * @param column - Identity column.
+ * @param valueSql - Recipe expression over `main."<table>"` columns.
+ * @param rowid - One row only (the clash fallback); all NULL rows otherwise.
+ * @returns Rows written.
+ * @task T12341
+ */
+export function fillIdentityColumnNative(nativeDb, table, column, valueSql, rowid) {
+    const col = quoteIdent(column);
+    const sql = `UPDATE main.${quoteIdent(table)} SET ${col} = ${valueSql} WHERE ${col} IS NULL`;
+    const changes = rowid === undefined
+        ? nativeDb.prepare(sql).run().changes
+        : nativeDb.prepare(`${sql} AND rowid = ?`).run(rowid).changes;
+    return Number(changes);
+}
+/**
+ * Clear one pre-release birth fingerprint so the fill re-derives it (spec §12.1).
+ *
+ * @param nativeDb - The `cleo.db` handle holding the cold-open lease.
+ * @param table - Declared minted table.
+ * @param rowid - The row.
+ * @task T12341
+ */
+export function clearBirthFpNative(nativeDb, table, rowid) {
+    nativeDb
+        .prepare(`UPDATE main.${quoteIdent(table)} SET birth_fp = NULL WHERE rowid = ?`)
+        .run(rowid);
+}
+/**
+ * Insert one row into a declared identity table, with the columns the row
+ * carries that the table has (a row released from the identity quarantine).
+ *
+ * @param nativeDb - The project `cleo.db` handle.
+ * @param table - Declared table.
+ * @param row - Column → value.
+ * @task T12341
+ */
+export function insertIdentityRowNative(nativeDb, table, row) {
+    const have = new Set(nativeDb.prepare('SELECT name FROM pragma_table_info(?)').all(table).map((c) => c.name));
+    const cols = Object.keys(row).filter((c) => have.has(c));
+    nativeDb
+        .prepare(`INSERT INTO main.${quoteIdent(table)} (${cols.map(quoteIdent).join(', ')}) VALUES (${cols
+        .map(() => '?')
+        .join(', ')})`)
+        .run(...cols.map((c) => row[c] ?? null));
+}
+/**
+ * Give the row of `table` identified by (`oldUid`, `birthFp`) the uid
+ * `newUid` (a uid re-key; the birth fingerprint never changes).
+ *
+ * @param nativeDb - The project `cleo.db` handle.
+ * @param table - Declared minted table.
+ * @param oldUid - The colliding uid.
+ * @param birthFp - The row's birth fingerprint.
+ * @param newUid - Its new uid.
+ * @returns Rows changed (0 or 1).
+ * @task T12341
+ */
+export function setRowUidNative(nativeDb, table, oldUid, birthFp, newUid) {
+    return Number(nativeDb
+        .prepare(`UPDATE main.${quoteIdent(table)} SET uid = ? WHERE uid = ? AND birth_fp = ?`)
+        .run(newUid, oldUid, birthFp).changes);
+}
+/**
+ * Point a stored reference uid column (`ac_uid`) of the rows that reference
+ * the re-keyed row by key at its new uid. Scoped by the key column, so a row
+ * referencing the OTHER holder of a colliding uid is never touched.
+ *
+ * @param nativeDb - The project `cleo.db` handle.
+ * @param table - Table holding the column.
+ * @param column - The stored reference uid column.
+ * @param fromColumn - The column that references the row by key (`ac_id`).
+ * @param key - The re-keyed row's local key.
+ * @param oldUid - Old referenced uid.
+ * @param newUid - New referenced uid.
+ * @returns Rows changed.
+ * @task T12341
+ */
+export function rewriteStoredRefUidNative(nativeDb, table, column, fromColumn, key, oldUid, newUid) {
+    const col = quoteIdent(column);
+    return Number(nativeDb
+        .prepare(`UPDATE main.${quoteIdent(table)} SET ${col} = ? WHERE ${col} = ? AND ${quoteIdent(fromColumn)} = ?`)
+        .run(newUid, oldUid, key).changes);
+}
+/**
+ * Clear one row's uid so the natural recipe re-derives it (a uid re-key
+ * changed an endpoint's uid).
+ *
+ * @param nativeDb - The project `cleo.db` handle.
+ * @param table - Declared natural table.
+ * @param rowid - The row.
+ * @task T12341
+ */
+export function clearRowUidNative(nativeDb, table, rowid) {
+    nativeDb.prepare(`UPDATE main.${quoteIdent(table)} SET uid = NULL WHERE rowid = ?`).run(rowid);
+}
+/**
+ * Delete a row-identity meta value (a re-mint record that moved with a re-key).
+ *
+ * @param nativeDb - The project `cleo.db` handle.
+ * @param key - Meta key.
+ * @task T12341
+ */
+export function deleteRowIdentityMetaNative(nativeDb, key) {
+    nativeDb.prepare('DELETE FROM tasks_row_identity_meta WHERE key = ?').run(key);
+}
+/**
+ * Set a natural row's uid by its current uid (a re-key re-derives the natural
+ * uids keyed by the re-keyed row; a receiver applies the published values).
+ *
+ * @param nativeDb - The project `cleo.db` handle.
+ * @param table - Declared natural table.
+ * @param oldUid - Current uid.
+ * @param newUid - New uid.
+ * @returns Rows changed.
+ * @task T12341
+ */
+export function setNaturalUidNative(nativeDb, table, oldUid, newUid) {
+    return Number(nativeDb
+        .prepare(`UPDATE main.${quoteIdent(table)} SET uid = ? WHERE uid = ?`)
+        .run(newUid, oldUid).changes);
+}
+/**
+ * Rewrite a held row (identity quarantine) under a new uid: a uid re-key of a
+ * row this replica holds but has not placed.
+ *
+ * @param nativeDb - The project `cleo.db` handle.
+ * @param key - The held row's table, uid and birth fingerprint.
+ * @param newUid - Its new uid.
+ * @param rowJson - Its wire form with the new uid.
+ * @task T12341
+ */
+export function rekeyQuarantineNative(nativeDb, key, newUid, rowJson) {
+    nativeDb
+        .prepare(`UPDATE tasks_identity_quarantine SET uid = ?, row_json = ?
+        WHERE entity_table = ? AND uid = ? AND birth_fp = ?`)
+        .run(newUid, rowJson, key.entityTable, key.uid, key.birthFp);
+}
+/**
+ * Add labels to a task's label junction (idempotent), for writers that
+ * insert a task with raw SQL (the sentient proposal ticks).
+ *
+ * @param nativeDb - The project `cleo.db` handle.
+ * @param taskId - The task.
+ * @param labels - Labels to add.
+ * @task T12341
+ */
+export function addTaskLabelsNative(nativeDb, taskId, labels) {
+    const stmt = nativeDb.prepare('INSERT OR IGNORE INTO tasks_task_labels (task_id, label) VALUES (?, ?)');
+    for (const label of labels)
+        stmt.run(taskId, label);
+}
 // One queue per shared native handle, independent of accessor identity. These
 // hold coordination state only; the ProjectStore remains the owner of handles.
 const taskTransactionQueue = new WeakMap();
@@ -219,6 +791,83 @@ function claimPredicate(guard, allowedHolders) {
         : undefined;
     return or(isNull(holder), mine, related, expired);
 }
+/** How long after a local rename a write to the old id is still read as meant for the renamed task. */
+export const RENAMED_RECENT_MS = 24 * 60 * 60 * 1000;
+function renameRecordKey(fromId) {
+    return `renamed_from:tasks_tasks:${fromId}`;
+}
+function hasIdentityMeta(nativeDb) {
+    return (nativeDb
+        .prepare("SELECT 1 AS x FROM sqlite_master WHERE type = 'table' AND name = 'tasks_row_identity_meta'")
+        .get() !== undefined);
+}
+/**
+ * Remember, locally, that `fromId` named the task `uid` at version
+ * `fromVersion` until now (T12800). Local-only (`tasks_row_identity_meta`):
+ * it answers "what did a caller of THIS store mean by `fromId`", which only
+ * this store's history can.
+ */
+function recordLocalRename(nativeDb, uid, fromId, toId, fromVersion) {
+    if (!hasIdentityMeta(nativeDb))
+        return;
+    const record = { uid, fromVersion, toId, at: new Date().toISOString() };
+    writeRowIdentityMetaNative(nativeDb, renameRecordKey(fromId), JSON.stringify(record));
+}
+/**
+ * Refuse a guarded write that names a display id its task no longer carries
+ * (T12800), when the caller can only mean the renamed task:
+ *
+ * - it expects EXACTLY the version the renamed task had when it left the id
+ *   (the version the caller read under the old id), and that is not the
+ *   current holder's version: a stale write on the current holder stays a
+ *   plain `E_CONFLICT`;
+ * - or it renews or releases a claim the caller's session holds on the
+ *   renamed task (acquiring or taking over the new holder is legitimate: a
+ *   pivot claims its target before it releases its source);
+ * - or no row holds the old id any more.
+ *
+ * Only a RECENT rename counts ({@link RENAMED_RECENT_MS}), and only one this
+ * store performed (the local rename record). `E_TASK_RENAMED` carries the new
+ * id in its details.
+ */
+function assertNotRenamed(nativeDb, taskId, guard, current) {
+    if (!nativeDb || !hasIdentityMeta(nativeDb))
+        return;
+    const raw = nativeDb
+        .prepare('SELECT value FROM tasks_row_identity_meta WHERE key = ?')
+        .get(renameRecordKey(taskId));
+    if (!raw)
+        return;
+    let record;
+    try {
+        record = JSON.parse(raw.value);
+    }
+    catch {
+        return;
+    }
+    if (Date.now() - Date.parse(record.at) > RENAMED_RECENT_MS)
+        return;
+    const renamed = nativeDb
+        .prepare('SELECT id, claimed_by_session AS claimedBySession FROM tasks_tasks WHERE uid = ?')
+        .get(record.uid);
+    if (!renamed || renamed.id === taskId)
+        return;
+    const expected = guard.expectedUpdatedAt;
+    const session = guard.claim?.sessionId ?? null;
+    const holdsRenamedClaim = session !== null &&
+        (guard.claim?.mode === 'renew' || guard.claim?.mode === 'release') &&
+        renamed.claimedBySession === session &&
+        current?.claimedBySession !== session;
+    const readRenamed = expected !== undefined &&
+        expected === record.fromVersion &&
+        (current === undefined || taskVersion(current) !== expected);
+    if (!(current === undefined || holdsRenamedClaim || readRenamed))
+        return;
+    throw new CleoError(ExitCode.TASK_RENAMED, `Task ${taskId} is now ${renamed.id}: sync re-numbered it after a display-id collision, and ${taskId} ${current ? 'names another task' : 'names no task'}; nothing was written`, {
+        fix: `Re-read it with 'cleo show ${renamed.id}' and retry against ${renamed.id}.`,
+        details: { field: 'taskId', actual: taskId, expected: renamed.id },
+    });
+}
 /** Throw `E_TASK_CLAIMED` when the stored holder refuses this claim write. */
 function assertClaimAllowed(taskId, row, guard, allowedHolders) {
     const stored = claimFromColumns(row);
@@ -528,8 +1177,18 @@ async function createOwnedSqliteDataAccessor(cwd, accessorScope) {
         async upsertSingleTask(task) {
             await accessor.transaction((tx) => tx.upsertSingleTask(task));
         },
-        async insertNewTask(task) {
-            await accessor.transaction((tx) => tx.insertNewTask(task));
+        async insertNewTask(task, identity) {
+            await accessor.transaction((tx) => tx.insertNewTask(task, identity));
+        },
+        async getTaskIdentities(taskIds) {
+            if (taskIds.length === 0)
+                return [];
+            const db = await getDb(cwd);
+            return db
+                .select({ id: schema.tasks.id, uid: schema.tasks.uid, birthFp: schema.tasks.birthFp })
+                .from(schema.tasks)
+                .where(inArray(schema.tasks.id, taskIds))
+                .all();
         },
         async addRelation(taskId, relatedTo, relationType, reason) {
             return accessor.transaction(async () => {
@@ -607,6 +1266,8 @@ async function createOwnedSqliteDataAccessor(cwd, accessorScope) {
                 createdAt: schema.taskAcceptanceCriteria.createdAt,
                 updatedAt: schema.taskAcceptanceCriteria.updatedAt,
                 contentHash: schema.taskAcceptanceCriteria.contentHash,
+                uid: schema.taskAcceptanceCriteria.uid,
+                birthFp: schema.taskAcceptanceCriteria.birthFp,
             })
                 .from(schema.taskAcceptanceCriteria)
                 .where(eq(schema.taskAcceptanceCriteria.taskId, taskId))
@@ -624,31 +1285,20 @@ async function createOwnedSqliteDataAccessor(cwd, accessorScope) {
                 createdAt: r.createdAt,
                 updatedAt: r.updatedAt ?? null,
                 contentHash: r.contentHash ?? null,
+                uid: r.uid ?? null,
+                birthFp: r.birthFp ?? null,
             }));
         },
         // ---- AC bindings (T10509 — AC-coverage gate) ----
         async getAcBindings(acIds) {
             if (acIds.length === 0)
                 return [];
+            return selectAcBindings(await getDb(cwd), acIds);
+        },
+        // ---- AC bindings — orphan scan (T12790) ----
+        async findOrphanAcBindings() {
             const db = await getDb(cwd);
-            const rows = await db
-                .select({
-                id: schema.evidenceAcBindings.id,
-                evidenceAtomId: schema.evidenceAcBindings.evidenceAtomId,
-                acId: schema.evidenceAcBindings.acId,
-                bindingType: schema.evidenceAcBindings.bindingType,
-                createdAt: schema.evidenceAcBindings.createdAt,
-            })
-                .from(schema.evidenceAcBindings)
-                .where(inArray(schema.evidenceAcBindings.acId, acIds))
-                .all();
-            return rows.map((r) => ({
-                id: r.id,
-                evidenceAtomId: r.evidenceAtomId,
-                acId: r.acId,
-                bindingType: r.bindingType,
-                createdAt: r.createdAt,
-            }));
+            return selectOrphanAcBindings(db);
         },
         async archiveSingleTask(taskId, fields) {
             return accessor.transaction(async () => {
@@ -692,6 +1342,9 @@ async function createOwnedSqliteDataAccessor(cwd, accessorScope) {
                         .delete(schema.taskDependencies)
                         .where(eq(schema.taskDependencies.dependsOn, taskId))
                         .run();
+                    // T12790: the bindings table has no FK to the AC rows that cascade
+                    // from tasks_tasks — remove (and audit) them explicitly.
+                    await pruneAcBindingsForTask(db, taskId);
                     // Delete the task itself
                     await db.delete(schema.tasks).where(eq(schema.tasks.id, taskId)).run();
                 });
@@ -1113,6 +1766,11 @@ async function createOwnedSqliteDataAccessor(cwd, accessorScope) {
                     .where(eq(schema.tasks.id, taskId))
                     .limit(1)
                     .all();
+                // T12800: a guarded write aimed at a task that sync re-numbered must not
+                // land on whatever row holds the old id now.
+                if (guard?.claim || guard?.expectedUpdatedAt !== undefined) {
+                    assertNotRenamed(getNativeTasksDb(cwd), taskId, guard, current);
+                }
                 if (!current)
                     throw new Error(`Task not found: ${taskId}`);
                 // T12502: refuse a claim write the stored holder does not allow before
@@ -1195,24 +1853,42 @@ async function createOwnedSqliteDataAccessor(cwd, accessorScope) {
                             nativeDb.prepare(`SAVEPOINT ${spName}`).run();
                         }
                         try {
+                            // The birth of each task an upsert replaced, for clearTaskIdentity
+                            // (T12806): sameness is decided on the birth before the overwrite.
+                            const replacedBirths = new Map();
                             const tx = {
                                 async upsertSingleTask(task) {
                                     scope.assertActive();
                                     return accessor.transaction(async () => {
                                         scope.assertActive();
+                                        if (rowUidFillEnabled() && !replacedBirths.has(task.id)) {
+                                            const before = readReplacedTaskBirthNative(nativeDb, task.id);
+                                            if (before)
+                                                replacedBirths.set(task.id, before);
+                                        }
                                         const row = taskToRow(task);
                                         await upsertTask(db, row);
                                         await updateDependencies(db, task.id, task.depends ?? []);
                                     });
                                 },
-                                async insertNewTask(task) {
+                                async insertNewTask(task, identity) {
                                     scope.assertActive();
                                     return accessor.transaction(async () => {
                                         scope.assertActive();
-                                        await insertNewTask(db, taskToRow(task));
+                                        await insertNewTask(db, taskToRow(task), identity);
                                         await updateDependencies(db, task.id, task.depends ?? []);
                                     });
                                 },
+                                async clearTaskIdentity(taskId) {
+                                    scope.assertActive();
+                                    // Row uids off: an overwrite changes no identity value (T12806 review).
+                                    if (!rowUidFillEnabled())
+                                        return;
+                                    return accessor.transaction(async () => {
+                                        scope.assertActive();
+                                        clearReplacedTaskIdentityNative(nativeDb, taskId, replacedBirths.get(taskId));
+                                    });
+                                },
                                 async archiveSingleTask(taskId, fields) {
                                     scope.assertActive();
                                     return accessor.transaction(async () => {
@@ -1242,6 +1918,8 @@ async function createOwnedSqliteDataAccessor(cwd, accessorScope) {
                                             .delete(schema.taskDependencies)
                                             .where(eq(schema.taskDependencies.dependsOn, taskId))
                                             .run();
+                                        // T12790: bindings of the cascading AC rows (no FK).
+                                        await pruneAcBindingsForTask(db, taskId);
                                         await db.delete(schema.tasks).where(eq(schema.tasks.id, taskId)).run();
                                     });
                                 },
@@ -1321,6 +1999,9 @@ async function createOwnedSqliteDataAccessor(cwd, accessorScope) {
                                             projection: r.projection ?? 'legacy',
                                             text: r.text,
                                             contentHash: r.contentHash ?? null,
+                                            // A kept criterion keeps its uid (T12341); else one is minted.
+                                            ...(r.uid ? { uid: r.uid } : {}),
+                                            ...(r.uid && r.birthFp ? { birthFp: r.birthFp } : {}),
                                         })))
                                             .run();
                                     });
@@ -1340,6 +2021,8 @@ async function createOwnedSqliteDataAccessor(cwd, accessorScope) {
                                         createdAt: schema.taskAcceptanceCriteria.createdAt,
                                         updatedAt: schema.taskAcceptanceCriteria.updatedAt,
                                         contentHash: schema.taskAcceptanceCriteria.contentHash,
+                                        uid: schema.taskAcceptanceCriteria.uid,
+                                        birthFp: schema.taskAcceptanceCriteria.birthFp,
                                     })
                                         .from(schema.taskAcceptanceCriteria)
                                         .where(eq(schema.taskAcceptanceCriteria.taskId, taskId))
@@ -1357,18 +2040,70 @@ async function createOwnedSqliteDataAccessor(cwd, accessorScope) {
                                         createdAt: r.createdAt,
                                         updatedAt: r.updatedAt ?? null,
                                         contentHash: r.contentHash ?? null,
+                                        uid: r.uid ?? null,
+                                        birthFp: r.birthFp ?? null,
                                     }));
                                 },
                                 async deleteAcRowsForTask(taskId) {
                                     scope.assertActive();
                                     return accessor.transaction(async () => {
                                         scope.assertActive();
+                                        // T12790: remove (and audit) the departing rows' bindings.
+                                        await pruneAcBindingsForTask(db, taskId, 'ac-removed');
                                         await db
                                             .delete(schema.taskAcceptanceCriteria)
                                             .where(eq(schema.taskAcceptanceCriteria.taskId, taskId))
                                             .run();
                                     });
                                 },
+                                async deleteAcRowsByIds(taskId, ids, keepBindingsForUids = []) {
+                                    scope.assertActive();
+                                    if (ids.length === 0)
+                                        return;
+                                    return accessor.transaction(async () => {
+                                        scope.assertActive();
+                                        // T12790: only ids this task actually owns leave the set —
+                                        // prune (and audit) exactly their bindings.
+                                        const owned = await db
+                                            .select({ id: schema.taskAcceptanceCriteria.id })
+                                            .from(schema.taskAcceptanceCriteria)
+                                            .where(and(eq(schema.taskAcceptanceCriteria.taskId, taskId), inArray(schema.taskAcceptanceCriteria.id, ids)))
+                                            .all();
+                                        await pruneAcBindingsForAcIds(db, taskId, owned.map((r) => r.id), 'ac-removed', keepBindingsForUids);
+                                        await db
+                                            .delete(schema.taskAcceptanceCriteria)
+                                            .where(and(eq(schema.taskAcceptanceCriteria.taskId, taskId), inArray(schema.taskAcceptanceCriteria.id, ids)))
+                                            .run();
+                                    });
+                                },
+                                async updateAcRows(rows) {
+                                    scope.assertActive();
+                                    if (rows.length === 0)
+                                        return;
+                                    return accessor.transaction(async () => {
+                                        scope.assertActive();
+                                        const updatedAt = new Date().toISOString();
+                                        for (const r of rows) {
+                                            const result = await db
+                                                .update(schema.taskAcceptanceCriteria)
+                                                .set({
+                                                ordinal: r.ordinal,
+                                                kind: r.kind ?? 'text',
+                                                sourceKey: r.sourceKey ?? `text:${r.ordinal}`,
+                                                targetTaskId: r.targetTaskId ?? null,
+                                                projection: r.projection ?? 'legacy',
+                                                text: r.text,
+                                                contentHash: r.contentHash ?? null,
+                                                updatedAt,
+                                            })
+                                                .where(and(eq(schema.taskAcceptanceCriteria.id, r.id), eq(schema.taskAcceptanceCriteria.taskId, r.taskId)))
+                                                .run();
+                                            if (Number(result.changes) === 0) {
+                                                throw new CleoError(ExitCode.VALIDATION_ERROR, `Acceptance criterion ${r.id} does not exist on task ${r.taskId}; refusing to update it`);
+                                            }
+                                        }
+                                    });
+                                },
                                 async appendAcHistory(rows) {
                                     scope.assertActive();
                                     return accessor.transaction(async () => {
@@ -1381,6 +2116,7 @@ async function createOwnedSqliteDataAccessor(cwd, accessorScope) {
                                             acId: r.acId,
                                             previousText: r.previousText,
                                             reason: r.reason,
+                                            ...(r.acUid ? { acUid: r.acUid } : {}),
                                         })))
                                             .run();
                                     });
@@ -1388,26 +2124,7 @@ async function createOwnedSqliteDataAccessor(cwd, accessorScope) {
                                 // ---- AC bindings (T10509 — AC-coverage gate) ----
                                 async getAcBindings(acIds) {
                                     scope.assertActive();
-                                    if (acIds.length === 0)
-                                        return [];
-                                    const out = await db
-                                        .select({
-                                        id: schema.evidenceAcBindings.id,
-                                        evidenceAtomId: schema.evidenceAcBindings.evidenceAtomId,
-                                        acId: schema.evidenceAcBindings.acId,
-                                        bindingType: schema.evidenceAcBindings.bindingType,
-                                        createdAt: schema.evidenceAcBindings.createdAt,
-                                    })
-                                        .from(schema.evidenceAcBindings)
-                                        .where(inArray(schema.evidenceAcBindings.acId, acIds))
-                                        .all();
-                                    return out.map((r) => ({
-                                        id: r.id,
-                                        evidenceAtomId: r.evidenceAtomId,
-                                        acId: r.acId,
-                                        bindingType: r.bindingType,
-                                        createdAt: r.createdAt,
-                                    }));
+                                    return selectAcBindings(db, acIds);
                                 },
                                 // ---- AC bindings — writer (T10511, Validator SDK tools) ----
                                 async insertAcBindings(rows) {
@@ -1436,6 +2153,14 @@ async function createOwnedSqliteDataAccessor(cwd, accessorScope) {
                                             .run();
                                     });
                                 },
+                                // ---- AC bindings — orphan repair (T12790) ----
+                                async pruneOrphanAcBindings() {
+                                    scope.assertActive();
+                                    return accessor.transaction(async () => {
+                                        scope.assertActive();
+                                        return pruneOrphanAcBindings(db);
+                                    });
+                                },
                             };
                             const result = await fn(bindTaskAccessorScope(tx, accessorScope));
                             await scope.pending;
@@ -1624,4 +2349,12 @@ async function createOwnedSqliteDataAccessor(cwd, accessorScope) {
     };
     return accessor;
 }
+// T12341: the row-identity open pass writes through these chokepoint helpers.
+registerRowIdentityWriters({
+    relinkAcUidNative,
+    clearAcUidGraveyardNative,
+    writeRowIdentityMetaNative,
+    fillIdentityColumnNative,
+    clearBirthFpNative,
+});
 //# sourceMappingURL=sqlite-data-accessor.js.map