@cleocode/core 2026.9.24 → 2026.9.25

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

@@ -16,10 +16,13 @@ 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 { registerRowIdentityWriters } from './row-identity.js';
 import { tasksAuditLog } from './schema/cleo-project/audit.js';
 import { resolveCurrentSession } from './session-store.js';
 import { closeDb, getDb, getNativeTasksDb } from './sqlite.js';
@@ -37,13 +40,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 +189,398 @@ 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);
+    }
+    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).
+ *
+ * @param nativeDb - The project `cleo.db` handle.
+ * @param row - The alias.
+ * @task T12341
+ */
+export function insertDisplayIdAliasNative(nativeDb, row) {
+    nativeDb
+        .prepare(`INSERT OR IGNORE 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);
+}
+/**
+ * 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');
+}
+/** 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();
@@ -607,6 +1056,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 +1075,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 +1132,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();
                 });
@@ -1242,6 +1685,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 +1766,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 +1788,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 +1807,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 +1883,7 @@ async function createOwnedSqliteDataAccessor(cwd, accessorScope) {
                                             acId: r.acId,
                                             previousText: r.previousText,
                                             reason: r.reason,
+                                            ...(r.acUid ? { acUid: r.acUid } : {}),
                                         })))
                                             .run();
                                     });
@@ -1388,26 +1891,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 +1920,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 +2116,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