@cleocode/core 2026.9.24 → 2026.9.26

package/dist/store/display-id-alias.js

@@ -0,0 +1,1538 @@
+/**
+ * Display ids, uid re-keys, their aliases, and the identity quarantine (T12341).
+ *
+ * `T####` is a per-project DISPLAY id: unique inside one store at rest, typed
+ * by people and agents, but allocated locally, so two offline stores can
+ * allocate the same one for different work. The row's uid is its identity
+ * (`store/row-identity.ts`). Spec: `cleo docs fetch t12341-uid-scheme` §6.4, §9.
+ *
+ * ## Receiving a row: place it, or hold it
+ *
+ * An incoming row travels as a {@link WireRow}: its uid, its birth
+ * fingerprint, its values, and every reference as the referenced row's
+ * (uid, birth fingerprint) ({@link WireRef}). {@link receiveRow} places it in
+ * its table, or HOLDS it in `tasks_identity_quarantine` (local-only) when it
+ * cannot be placed yet:
+ *
+ * - `uid-collision`: a local row has its uid with a different birth
+ *   fingerprint. Neither row is re-keyed here unless this replica is the
+ *   authority ({@link rekeyRowUid}); the others wait for the published
+ *   {@link RekeyReceipt} ({@link applyRekey}).
+ * - `display-id-collision`: a local row holds its display id. The loser is
+ *   re-numbered only by its authority ({@link remintTaskDisplayId}); the
+ *   others wait for the {@link RemintOp} ({@link applyRemintOp}).
+ * - `key-collision`: another local row holds its local key (a key derived
+ *   from a local display id, such as an AC id); the merge engine re-derives
+ *   the key (T12344).
+ * - `ref-pending`: a reference does not resolve to a local row with the SAME
+ *   birth fingerprint ({@link resolveWireRef}), e.g. it names the loser of a
+ *   uid collision whose re-key has not arrived. It never resolves to the
+ *   other row that shares the uid.
+ *
+ * Held rows never enter the task tables, so no validator, parser or command
+ * ever sees an id that is not a `T####` (the round-1 provisional `prov-` ids
+ * are gone). Every op that could unblock a held row re-tries the held rows
+ * ({@link releaseHeld}).
+ *
+ * ## Display-id collision: one authority, ordered by HLC
+ *
+ * Every replica agrees on the loser ({@link collisionLoser}: the greater
+ * uid). {@link remintAuthority} is a pure function of synced inputs (cloud
+ * sync, the origin, replica membership with join / retire HLCs, the
+ * collision's HLC) and a point in HLC time: the origin first, then each
+ * active replica in turn for one takeover window, cycling, so a silent
+ * authority is always taken over and nothing waits forever. Two authorities
+ * may both re-mint around a window boundary: {@link applyRemintOp} keeps the
+ * op with the greater HLC on every replica, whatever the arrival order, and
+ * the other number becomes an alias.
+ *
+ * ## Uid collision: re-key the loser
+ *
+ * The loser is the greater birth fingerprint. {@link rekeyRowUid} asserts the
+ * row it re-keys carries that fingerprint (a replica holding the winner never
+ * re-keys it), gives it a random uid, and cascades from STORED identity:
+ * minted children get {@link rekeyedChildUid} of their old uid and the new
+ * owner uid, natural rows keyed by a re-keyed row are re-derived, stored uid
+ * copies (`ac_uid`) and display-id aliases follow. The receipt lists every
+ * value; receivers apply them ({@link applyRekey}) and never recompute.
+ *
+ * ## Gate 28
+ *
+ * Every write here goes through a chokepoint helper in
+ * `sqlite-data-accessor.ts`; this module only reads and decides.
+ *
+ * @module
+ * @task T12341
+ * @task T12744
+ * @task T12745
+ * @task T12748
+ * @task T12750
+ * @epic T12323
+ */
+import { ExitCode, } from '@cleocode/contracts';
+import { getTableColumns } from 'drizzle-orm';
+import { CleoError } from '../errors.js';
+import { exceedsMaxDepth } from '../tasks/hierarchy.js';
+import { resolveHierarchyPolicy } from '../tasks/hierarchy-policy.js';
+import { AC_UID_GRAVEYARD, BIRTH_FP_COLUMN, fillTableUids, markRowIdentityShared, mintRowUid, naturalRowUid, ROW_IDENTITY, registerRowUidFunction, rekeyedChildUid, rowIdentitySpec, UID_COLUMN, } from './row-identity.js';
+import { advanceTaskIdSequence, clearRowUidNative, deleteDisplayIdAliasNative, deleteQuarantineNative, insertDisplayIdAliasNative, insertIdentityRowNative, insertQuarantineNative, insertUidAliasNative, rekeyQuarantineNative, renameTaskDisplayIdNative, rewriteStoredRefUidNative, setNaturalUidNative, setRowUidNative, } from './sqlite-data-accessor.js';
+import { compareHlc as compareSyncHlc, encodeHlc, parseHlc } from './sync/hlc.js';
+import { tasks as tasksTable } from './tasks-schema.js';
+import { insertTaskSchema } from './validation-schemas.js';
+/** Physical name of the display-id alias table. */
+export const DISPLAY_ID_ALIAS_TABLE = 'tasks_display_id_aliases';
+/** Physical name of the uid re-key alias table. */
+export const UID_ALIAS_TABLE = 'tasks_uid_aliases';
+/** Physical name of the identity quarantine (local-only). */
+export const QUARANTINE_TABLE = 'tasks_identity_quarantine';
+// ---- HLC -------------------------------------------------------------------
+//
+// HLC values are the change journal's (T12342): the wire string `Hlc` in
+// `@cleocode/contracts` (`PPPPPPPPPPPPP-CCCCCC-<replica uuid>`), decoded and
+// ordered by `store/sync/hlc.ts`. String order is HLC order.
+/**
+ * Total order of two encoded HLC values (`Hlc` wire strings).
+ *
+ * @param a - One value.
+ * @param b - The other.
+ * @returns Negative, zero or positive.
+ * @throws HlcError when a value is not an encoded HLC.
+ */
+export function compareHlc(a, b) {
+    return compareSyncHlc(storedHlc(a), storedHlc(b));
+}
+/** Physical milliseconds of an encoded HLC. */
+function hlcMs(value) {
+    return storedHlc(value).phys;
+}
+/** The format 9.25 wrote with the uid flag on: `<ms 15>.<counter 6>.<node>`. */
+const LEGACY_HLC_RE = /^(\d{15})\.(\d{6})\.(.+)$/;
+/**
+ * Decode an HLC this module stored. The journal format is the only one
+ * written; a value in the 9.25 format (written only with
+ * `CLEO_ROW_UID_FILL=1`) is still read, ordered by the same
+ * `(physical, counter, node)` tuple, so an old alias never breaks a re-mint.
+ *
+ * @throws HlcError when the value is in neither format.
+ */
+function storedHlc(value) {
+    const legacy = LEGACY_HLC_RE.exec(value);
+    if (legacy) {
+        return { phys: Number(legacy[1]), ctr: Number(legacy[2]), replica: legacy[3] };
+    }
+    return parseHlc(value);
+}
+/**
+ * Whether an incoming alias row ranks before the stored one of the same uid
+ * (T12800): the least displacement HLC by HLC order (a missing one ranks
+ * last), then origin, then `created_at`. The same on every replica.
+ */
+function aliasPrecedes(incoming, stored) {
+    const a = incoming.displacedHlc;
+    const b = stored.displacedHlc;
+    if (a !== null && b === null)
+        return true;
+    if (a === null && b !== null)
+        return false;
+    if (a !== null && b !== null) {
+        const order = compareHlc(a, b);
+        if (order !== 0)
+            return order < 0;
+    }
+    const ao = incoming.origin ?? '';
+    const bo = stored.origin ?? '';
+    if (ao !== bo)
+        return ao < bo;
+    return incoming.createdAt < stored.createdAt;
+}
+/** The replica id a pre-HLC value carries: none issued it. */
+export const PRE_HLC_REPLICA = '00000000-0000-0000-0000-000000000000';
+/**
+ * The collision HLC of two rows that have no creation HLC (written before the
+ * change journal, T12342): the later of their two BIRTHS, at counter 0, from
+ * no replica ({@link PRE_HLC_REPLICA}). Every replica derives the same value
+ * from the rows' synced births; it only anchors the authority schedule
+ * ({@link remintAuthority}), never a clock (HLC never reads a uid's time).
+ *
+ * @param birthMsA - One row's birth, epoch ms.
+ * @param birthMsB - The other's.
+ * @returns An encoded HLC.
+ * @task T12802
+ */
+export function collisionHlcFromBirths(birthMsA, birthMsB) {
+    return encodeHlc({ phys: Math.max(birthMsA, birthMsB, 0), ctr: 0, replica: PRE_HLC_REPLICA });
+}
+// ---- Shared helpers ---------------------------------------------------------
+/** Quote an identifier for SQL. */
+function q(name) {
+    return `"${name.replaceAll('"', '""')}"`;
+}
+/** The declared project spec of `table`, or throw. */
+function specOf(table) {
+    const spec = rowIdentitySpec('project', table);
+    if (!spec)
+        throw new Error(`row identity: ${table} is not a declared project table`);
+    return spec;
+}
+/** The single-column key of a declared table. */
+function keyOf(table) {
+    const spec = specOf(table);
+    if (spec.key.length !== 1)
+        throw new Error(`row identity: ${table} has a composite key`);
+    return spec.key[0];
+}
+/** Run `fn` in a uniquely named savepoint. */
+function inSavepoint(db, name, fn) {
+    const sp = `_cleo_${name}_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
+    db.exec(`SAVEPOINT ${sp}`);
+    try {
+        const out = fn();
+        db.exec(`RELEASE SAVEPOINT ${sp}`);
+        return out;
+    }
+    catch (error) {
+        db.exec(`ROLLBACK TO SAVEPOINT ${sp}`);
+        db.exec(`RELEASE SAVEPOINT ${sp}`);
+        throw error;
+    }
+}
+/** The local row of a minted table with this uid AND birth fingerprint. */
+function localRow(db, table, uid, birthFp) {
+    return db
+        .prepare(`SELECT ${q(keyOf(table))} AS key, rowid AS rowid FROM main.${q(table)}
+        WHERE ${q(UID_COLUMN)} = ? AND ${q(BIRTH_FP_COLUMN)} = ?`)
+        .get(uid, birthFp);
+}
+// ---- Display-id collision: loser and authority -------------------------------
+/**
+ * Of two rows that carry the same display id, the one that must be re-minted:
+ * the greater uid. Every replica picks the same one for the same pair, and for
+ * UUIDv7 uids the older row keeps its id.
+ *
+ * @param a - Uid of one claimant.
+ * @param b - Uid of the other.
+ * @returns The uid to re-mint.
+ */
+export function collisionLoser(a, b) {
+    return a.toLowerCase() > b.toLowerCase() ? a : b;
+}
+/** Default length of one authority window (HLC physical time). */
+export const REMINT_TAKEOVER_MS = 72 * 60 * 60 * 1000;
+/**
+ * Which replica may re-mint the losing row of a display-id collision at HLC
+ * time `atHlc` (spec §9.2). A pure function of synced inputs: every replica
+ * evaluating the same time names the same authority.
+ *
+ * 1. The project syncs to cloud → the server.
+ * 2. Else the origin, while it is an active member, for the first window
+ *    after the collision.
+ * 3. Else the FALLBACK CHAIN: the active members other than the origin,
+ *    sorted, one window each, cycling. A fallback that stays silent loses its
+ *    turn when its window ends, so a collision never waits forever.
+ *
+ * @param input - The facts every replica can see.
+ * @returns The authority, the rule, and the window index (0 = origin).
+ */
+export function remintAuthority(input) {
+    if (input.cloudSynced)
+        return { authority: 'server', reason: 'server', slot: 0 };
+    const window = input.takeoverAfterMs ?? REMINT_TAKEOVER_MS;
+    const elapsed = Math.max(0, hlcMs(input.atHlc) - hlcMs(input.collisionHlc));
+    const active = input.replicas
+        .filter((r) => compareHlc(r.joinedHlc, input.atHlc) <= 0 &&
+        (r.retiredHlc == null || compareHlc(r.retiredHlc, input.atHlc) > 0))
+        .map((r) => r.id)
+        .sort();
+    if (active.length === 0)
+        throw new Error('remint authority: the project has no active replica');
+    const originLive = input.origin !== null && active.includes(input.origin);
+    if (originLive && elapsed < window) {
+        return { authority: input.origin, reason: 'origin', slot: 0 };
+    }
+    const others = active.filter((id) => id !== input.origin);
+    const chain = others.length > 0 ? others : active;
+    const turn = Math.floor(elapsed / window) - (originLive ? 1 : 0);
+    return {
+        authority: chain[turn % chain.length],
+        reason: 'fallback',
+        slot: turn + 1,
+    };
+}
+/**
+ * Record that `displayId` used to name the row (`entityUid`, `entityBirthFp`).
+ * Idempotent.
+ *
+ * @param db - Connection on the project `cleo.db`.
+ * @param entry - The displaced id, the row that carried it, and the displacement.
+ */
+export function recordDisplayIdAlias(db, entry) {
+    insertDisplayIdAliasNative(db, {
+        // The reason is part of the key (T12800 review): a `remint-assigned` and a
+        // `collision-remint` alias of one (id, row) are two facts, and neither may
+        // win an insert race and drop the other.
+        uid: naturalRowUid('project', DISPLAY_ID_ALIAS_TABLE, [
+            entry.table,
+            entry.displayId,
+            entry.entityUid,
+            entry.reason,
+        ]),
+        entityTable: entry.table,
+        displayId: entry.displayId,
+        entityUid: entry.entityUid,
+        entityBirthFp: entry.entityBirthFp,
+        reason: entry.reason,
+        origin: entry.origin ?? null,
+        displacedHlc: entry.displacedHlc ?? null,
+        // Derived from the displacement's HLC when there is one, so every replica
+        // that records this displacement writes the same row (T12800).
+        createdAt: entry.now ?? hlcTime(entry.displacedHlc) ?? new Date().toISOString(),
+    }, aliasPrecedes);
+}
+/** Wall-clock time of an encoded HLC, or `undefined` when there is none. */
+function hlcTime(hlc) {
+    if (!hlc)
+        return undefined;
+    try {
+        return new Date(storedHlc(hlc).phys).toISOString();
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Resolve a display id: a live row always wins (aliases come back as
+ * history); with no live row, one alias resolves and several are ambiguous.
+ *
+ * @param db - Connection on the project `cleo.db`.
+ * @param table - Display-id table (e.g. `tasks_tasks`).
+ * @param displayId - The id to resolve.
+ * @returns `resolved` (live, or the single alias), `ambiguous` with every
+ *   candidate (callers report it as an error and never pick), or `none`.
+ */
+export function resolveDisplayId(db, table, displayId) {
+    const spec = specOf(table);
+    if (!spec.displayId)
+        throw new Error(`display id: ${table} has no declared display id`);
+    const key = keyOf(table);
+    const live = db
+        .prepare(`SELECT ${q(UID_COLUMN)} AS uid FROM main.${q(table)} WHERE ${q(key)} = ?`)
+        .get(displayId);
+    const aliases = db
+        .prepare(`SELECT a.entity_uid AS uid, t.${q(key)} AS currentId, a.origin AS origin,
+                a.displaced_hlc AS displacedHlc
+           FROM ${DISPLAY_ID_ALIAS_TABLE} a
+           LEFT JOIN main.${q(table)} t
+             ON t.${q(UID_COLUMN)} = a.entity_uid
+            AND (a.entity_birth_fp IS NULL OR t.${q(BIRTH_FP_COLUMN)} = a.entity_birth_fp)
+          WHERE a.entity_table = ? AND a.display_id = ?
+          ORDER BY a.displaced_hlc, a.entity_uid`)
+        .all(table, displayId)
+        .filter((a) => a.uid !== live?.uid)
+        // One claimant per row: several reasons (collision-remint, remint-assigned)
+        // of one id and row are one history entry here.
+        .filter((a, i, all) => all.findIndex((b) => b.uid === a.uid) === i)
+        .map((a) => ({ ...a, via: 'alias' }));
+    if (live) {
+        return {
+            status: 'resolved',
+            claimant: { uid: live.uid, currentId: displayId, via: 'live' },
+            alsoKnownAs: aliases,
+        };
+    }
+    const [only] = aliases;
+    if (!only)
+        return { status: 'none' };
+    if (aliases.length > 1)
+        return { status: 'ambiguous', candidates: aliases };
+    return { status: 'resolved', claimant: only, alsoKnownAs: [] };
+}
+/**
+ * Allocate the next `T####` on the caller's handle, with the same lower bound
+ * `allocateNextTaskId` uses (the highest stored numeric id). Only the re-mint
+ * authority allocates for a collision.
+ *
+ * @param db - Connection on the project `cleo.db`.
+ * @returns The new display id.
+ */
+export function allocateTaskDisplayId(db) {
+    const inventory = db
+        .prepare(`SELECT COALESCE(MAX(CAST(substr(id, 2) AS INTEGER)), 0) AS maximum
+         FROM tasks_tasks WHERE id GLOB 'T[0-9]*' AND substr(id, 2) NOT GLOB '*[^0-9]*'`)
+        .get();
+    const counter = advanceTaskIdSequence(db, inventory.maximum);
+    if (counter === undefined) {
+        throw new CleoError(ExitCode.FILE_ERROR, 'Sequence counter not found during allocation', {
+            fix: 'Run `cleo sequence repair` to re-seed the task-id sequence, then retry.',
+        });
+    }
+    return `T${String(counter).padStart(3, '0')}`;
+}
+/** Every local column that holds a task's display id. */
+function taskReferenceColumns(db) {
+    const found = new Map();
+    const add = (table, column, jsonArray) => {
+        found.set(`${table}.${column}`, { table, column, jsonArray });
+    };
+    const fks = db
+        .prepare(`SELECT m.name AS tbl, f."from" AS col
+         FROM main.sqlite_master m, pragma_foreign_key_list(m.name) f
+        WHERE m.type = 'table' AND f."table" = 'tasks_tasks'
+          AND (f."to" IS NULL OR f."to" = 'id')`)
+        .all();
+    for (const fk of fks)
+        add(fk.tbl, fk.col, false);
+    for (const spec of ROW_IDENTITY.project) {
+        for (const ref of [...(spec.refs ?? []), ...(spec.keyRefs ?? []), ...(spec.owners ?? [])]) {
+            if (ref.table === 'tasks_tasks')
+                add(spec.table, ref.column, false);
+        }
+        for (const ref of spec.jsonArrayRefs ?? []) {
+            if (ref.table === 'tasks_tasks')
+                add(spec.table, ref.column, true);
+        }
+    }
+    const tables = new Set(db.prepare("SELECT name FROM main.sqlite_master WHERE type = 'table'").all().map((r) => r.name));
+    return [...found.values()].filter((ref) => tables.has(ref.table));
+}
+function readRemint(db, uid, birthFp) {
+    const rows = db
+        .prepare(`SELECT display_id AS newId, displaced_hlc AS hlc, origin FROM ${DISPLAY_ID_ALIAS_TABLE}
+        WHERE entity_table = 'tasks_tasks' AND entity_uid = ? AND entity_birth_fp = ?
+          AND reason = 'remint-assigned' AND displaced_hlc IS NOT NULL`)
+        .all(uid, birthFp);
+    let best;
+    for (const r of rows)
+        if (!best || compareHlc(r.hlc, best.hlc) > 0)
+            best = r;
+    return best;
+}
+/** Record the display id an op assigned (every op, winner or not: its number stays an alias). */
+function writeRemint(db, op) {
+    recordDisplayIdAlias(db, {
+        table: 'tasks_tasks',
+        displayId: op.newId,
+        entityUid: op.uid,
+        entityBirthFp: op.birthFp,
+        reason: 'remint-assigned',
+        origin: op.origin,
+        displacedHlc: op.hlc,
+    });
+}
+/**
+ * AUTHORITY ONLY ({@link remintAuthority}): give the losing task of a
+ * display-id collision a new display id. Allocates the next `T####`, renames
+ * through the chokepoint (version CAS, claim columns kept), records the
+ * contested id as an alias and the op as the row's re-mint record, places any
+ * held row the freed id unblocks, and returns the op to publish.
+ *
+ * @param db - Connection on the project `cleo.db`.
+ * @param taskId - Current local display id of the task to re-mint.
+ * @param options - The contested id (default: `taskId`), why, the authority,
+ *   the op's HLC, and an optional version / claim guard for a manual rename.
+ * @returns The op to publish, with what was rewritten here.
+ * @throws CleoError NOT_FOUND when the task does not exist or has no identity yet.
+ */
+export function remintTaskDisplayId(db, taskId, options) {
+    const row = db
+        .prepare('SELECT uid, birth_fp AS birthFp FROM tasks_tasks WHERE id = ?')
+        .get(taskId);
+    if (!row?.uid || !row.birthFp) {
+        throw new CleoError(ExitCode.NOT_FOUND, `No task ${taskId} with a uid and birth fingerprint`, {
+            fix: 'Check the id with `cleo show`; row identity is filled when CLEO_ROW_UID_FILL=1.',
+            details: { field: 'taskId', actual: taskId },
+        });
+    }
+    const { uid, birthFp } = row;
+    const oldId = options.contestedId ?? taskId;
+    registerRowUidFunction(db, 'project');
+    return inSavepoint(db, 'remint', () => {
+        const newId = allocateTaskDisplayId(db);
+        const { rewritten } = renameTaskDisplayIdNative(db, uid, newId, taskReferenceColumns(db), options.guard);
+        recordDisplayIdAlias(db, {
+            table: 'tasks_tasks',
+            displayId: oldId,
+            entityUid: uid,
+            entityBirthFp: birthFp,
+            reason: options.reason,
+            origin: options.origin,
+            displacedHlc: options.hlc,
+            now: options.now,
+        });
+        const op = { uid, birthFp, oldId, newId, origin: options.origin, hlc: options.hlc };
+        writeRemint(db, op);
+        const released = releaseHeldRows(db, [
+            { table: 'tasks_tasks', key: taskId },
+            { table: 'tasks_tasks', key: oldId },
+        ]);
+        return { ...op, rewritten, released };
+    });
+}
+/**
+ * NON-AUTHORITY: apply a re-mint an authority published. Of several ops for
+ * one row, the one with the greatest HLC wins on every replica, whatever the
+ * arrival order: a lesser op is recorded as an alias (`superseded`), a greater
+ * one renames the row again and turns the previous number into an alias.
+ * Never allocates.
+ *
+ * @param db - Connection on the project `cleo.db`.
+ * @param op - The published re-mint.
+ * @returns What happened.
+ */
+export function applyRemintOp(db, op) {
+    registerRowUidFunction(db, 'project');
+    markRowIdentityShared(db, 'receive');
+    const prior = readRemint(db, op.uid, op.birthFp);
+    const alias = (displayId, reason) => recordDisplayIdAlias(db, {
+        table: 'tasks_tasks',
+        displayId,
+        entityUid: op.uid,
+        entityBirthFp: op.birthFp,
+        reason,
+        origin: op.origin,
+        displacedHlc: op.hlc,
+    });
+    if (prior) {
+        const order = compareHlc(op.hlc, prior.hlc);
+        if (order === 0)
+            return { status: 'already-applied' };
+        if (order < 0) {
+            inSavepoint(db, 'remint_superseded', () => {
+                alias(op.oldId, 'collision-remint');
+                writeRemint(db, op);
+            });
+            return { status: 'superseded', winner: prior };
+        }
+    }
+    const live = localRow(db, 'tasks_tasks', op.uid, op.birthFp);
+    if (live) {
+        const holder = db.prepare('SELECT uid FROM tasks_tasks WHERE id = ?').get(op.newId);
+        if (holder && holder.uid !== op.uid)
+            return { status: 'conflict', holderUid: holder.uid };
+    }
+    return inSavepoint(db, 'remint_apply', () => {
+        alias(op.oldId, 'collision-remint');
+        writeRemint(db, op);
+        if (!live) {
+            const held = { entityTable: 'tasks_tasks', uid: op.uid, birthFp: op.birthFp };
+            return {
+                status: 'recorded',
+                released: releaseHeldRows(db, [{ table: 'tasks_tasks', held }]),
+            };
+        }
+        if (live.key === op.newId)
+            return { status: 'already-applied' };
+        const { rewritten } = renameTaskDisplayIdNative(db, op.uid, op.newId, taskReferenceColumns(db));
+        return {
+            status: 'applied',
+            receipt: {
+                ...op,
+                rewritten,
+                released: releaseHeldRows(db, [{ table: 'tasks_tasks', key: live.key }]),
+            },
+        };
+    });
+}
+/**
+ * Version of the wire row format. v2 (T12798) carries no local key of
+ * another row in `values`; a row without it (or older) came from a build
+ * whose values hold raw local keys, and is held (`unsupported-wire`) rather
+ * than applied or silently stripped.
+ */
+export const WIRE_VERSION = 2;
+/**
+ * AC-history rows whose criterion is gone everywhere are still history: they
+ * are placed with the criterion's uid carried and a key that names no live
+ * criterion (`gone:<uid>`), never held forever.
+ */
+const GONE_CRITERION_PREFIX = 'gone:';
+/** Follow `tasks_uid_aliases` from (uid, birth fp) to the row's current uid. */
+function followUidAlias(db, table, uid, birthFp) {
+    let current = uid;
+    for (let hop = 0; hop < 32; hop++) {
+        const alias = db
+            .prepare(`SELECT new_uid AS uid FROM ${UID_ALIAS_TABLE}
+          WHERE entity_table = ? AND old_uid = ? AND old_birth_fp = ?`)
+            .get(table, current, birthFp);
+        if (!alias)
+            break;
+        current = alias.uid;
+    }
+    return current;
+}
+/**
+ * Resolve a wire reference to a local row: the row with that uid AND that
+ * birth fingerprint, following `tasks_uid_aliases` when the target was
+ * re-keyed. A row that has the uid with ANOTHER fingerprint (the other side of
+ * a uid collision) never matches: the reference is `held` (its target waits
+ * in the quarantine) or `pending` (its target has not arrived, or its re-key
+ * has not), and the referencing row waits too.
+ *
+ * @param db - Connection on the project `cleo.db`.
+ * @param table - The referenced table.
+ * @param ref - The reference.
+ * @returns Where it points.
+ */
+export function resolveWireRef(db, table, ref) {
+    if (ref.uid === null)
+        return { status: 'pending' };
+    const minted = specOf(table).kind === 'minted';
+    // A minted row is identified by uid AND fingerprint: a reference without a
+    // fingerprint never matches one (the other side of a uid collision holds the
+    // same uid).
+    if (minted && ref.birthFp === null)
+        return { status: 'pending' };
+    const uid = minted && ref.birthFp !== null ? followUidAlias(db, table, ref.uid, ref.birthFp) : ref.uid;
+    const row = db
+        .prepare(`SELECT ${q(keyOf(table))} AS key, ${minted ? q(BIRTH_FP_COLUMN) : 'NULL'} AS fp
+         FROM main.${q(table)} WHERE ${q(UID_COLUMN)} = ?`)
+        .get(uid);
+    if (row && (!minted || row.fp === ref.birthFp)) {
+        return { status: 'row', key: row.key, uid };
+    }
+    const held = db
+        .prepare(`SELECT 1 AS x FROM ${QUARANTINE_TABLE} WHERE entity_table = ? AND uid = ? AND birth_fp = ?`)
+        .get(table, uid, ref.birthFp ?? '');
+    return held ? { status: 'held' } : { status: 'pending' };
+}
+/** Whether a column accepts NULL. */
+function nullableColumn(db, table, column) {
+    const info = db
+        .prepare('SELECT "notnull" AS notnull, pk FROM pragma_table_info(?) WHERE name = ?')
+        .get(table, column);
+    return info !== undefined && info.notnull === 0 && info.pk === 0;
+}
+/** Reference column → referenced table, for a declared table. */
+function refTargets(spec) {
+    const out = new Map();
+    for (const ref of [...(spec.refs ?? []), ...(spec.owners ?? []), ...(spec.keyRefs ?? [])]) {
+        out.set(ref.column, ref.table);
+    }
+    return out;
+}
+/** Stored reference uid column (`ac_uid`) → its table and key column (`ac_id`). */
+function storedUidRefs(spec) {
+    const out = new Map();
+    for (const ref of spec.storedRefUids ?? []) {
+        if ((ref.source ?? 'uid') === 'uid')
+            out.set(ref.column, { table: ref.table, from: ref.from });
+    }
+    return out;
+}
+/** JSON array of ids column → referenced table. */
+function jsonArrayTargets(spec) {
+    return new Map((spec.jsonArrayRefs ?? []).map((ref) => [ref.column, ref.table]));
+}
+/**
+ * Columns that hold another row's LOCAL key: never sent as values (T12798).
+ * `ac_text_hash` (a stored fact, not a key) is kept.
+ */
+function localKeyColumns(spec) {
+    const out = new Set([...refTargets(spec).keys(), ...jsonArrayTargets(spec).keys()]);
+    for (const [column, { from }] of storedUidRefs(spec)) {
+        out.add(column);
+        out.add(from);
+    }
+    return out;
+}
+/** Hold a row, keeping the time it was first held. */
+function hold(db, wire, reason, contestedId, previous) {
+    const key = { entityTable: wire.table, uid: wire.uid, birthFp: wire.birthFp ?? '' };
+    const was = previous ?? key;
+    const rowJson = JSON.stringify(wire);
+    const first = db
+        .prepare(`SELECT created_at AS createdAt, reason, contested_id AS contestedId, row_json AS rowJson
+         FROM ${QUARANTINE_TABLE} WHERE entity_table = ? AND uid = ? AND birth_fp = ?`)
+        .get(was.entityTable, was.uid, was.birthFp);
+    // A still-held row that is held for the same reason is never rewritten (T12801).
+    if (first &&
+        was.entityTable === key.entityTable &&
+        was.uid === key.uid &&
+        was.birthFp === key.birthFp &&
+        first.reason === reason &&
+        first.contestedId === contestedId &&
+        first.rowJson === rowJson) {
+        return;
+    }
+    if (previous)
+        deleteQuarantineNative(db, previous);
+    insertQuarantineNative(db, {
+        ...key,
+        reason,
+        contestedId,
+        rowJson,
+        receivedHlc: null,
+        createdAt: first?.createdAt ?? new Date().toISOString(),
+    });
+}
+/** Place one wire row, or hold it. Does not re-try other held rows. */
+function placeRow(db, incoming, heldAs) {
+    const spec = specOf(incoming.table);
+    const minted = spec.kind === 'minted';
+    // A v1 sender's values hold raw local keys of other rows: recognised and
+    // held, never applied and never silently stripped (T12798 review).
+    const version = incoming.version ?? 1;
+    if (version !== WIRE_VERSION) {
+        hold(db, incoming, 'unsupported-wire', `wire v${version}`, heldAs);
+        return { status: 'held', reason: 'unsupported-wire' };
+    }
+    if (minted && !incoming.birthFp) {
+        throw new Error(`receive: a ${incoming.table} row must carry its birth fingerprint`);
+    }
+    // A late copy of a row that was re-keyed: follow its uid alias.
+    const wire = minted
+        ? {
+            ...incoming,
+            uid: followUidAlias(db, incoming.table, incoming.uid, incoming.birthFp),
+        }
+        : incoming;
+    const done = () => {
+        if (heldAs)
+            deleteQuarantineNative(db, heldAs);
+    };
+    // A natural row is matched by its key AFTER its references resolve (below):
+    // its wire uid hashes endpoint uids, and an endpoint under a uid collision
+    // would make two different edges look like one.
+    const same = minted
+        ? db
+            .prepare(`SELECT ${q(BIRTH_FP_COLUMN)} AS fp FROM main.${q(wire.table)} WHERE ${q(UID_COLUMN)} = ?`)
+            .get(wire.uid)
+        : undefined;
+    if (same) {
+        if (same.fp === wire.birthFp) {
+            done();
+            return { status: 'duplicate', uid: wire.uid };
+        }
+        const local = same.fp ?? '';
+        const other = wire.birthFp;
+        const localIsLoser = local > other;
+        hold(db, wire, 'uid-collision', null, heldAs);
+        return {
+            status: 'held',
+            reason: 'uid-collision',
+            collision: {
+                kind: 'uid',
+                table: wire.table,
+                uid: wire.uid,
+                winnerBirthFp: localIsLoser ? other : local,
+                loserBirthFp: localIsLoser ? local : other,
+                localIsLoser,
+            },
+        };
+    }
+    const values = { ...wire.values };
+    // A local key of another row never comes from the sender's values (T12798);
+    // a JSON column that is not an id array travels as a value.
+    const arrayColumns = jsonArrayTargets(spec);
+    for (const column of localKeyColumns(spec)) {
+        if (!arrayColumns.has(column) || wire.jsonRefs?.[column])
+            delete values[column];
+    }
+    const targets = refTargets(spec);
+    const stored = storedUidRefs(spec);
+    const pending = () => {
+        hold(db, wire, 'ref-pending', null, heldAs);
+        return { status: 'held', reason: 'ref-pending' };
+    };
+    for (const [column, ref] of Object.entries(wire.refs ?? {})) {
+        const storedRef = stored.get(column);
+        const target = targets.get(column) ?? storedRef?.table;
+        if (!target)
+            throw new Error(`receive: ${wire.table}.${column} is not a declared reference`);
+        if (ref === null) {
+            values[column] = null;
+            if (storedRef)
+                values[storedRef.from] = null;
+            continue;
+        }
+        const resolved = resolveWireRef(db, target, ref);
+        if (resolved.status !== 'row' && ref.gone) {
+            // The sender no longer has the row this names, and neither do we.
+            if (storedRef && wire.table === 'tasks_task_acceptance_criteria_history') {
+                // History of a criterion gone everywhere: keep the history, carry the
+                // criterion's uid, point the key at no live criterion.
+                values[column] = ref.uid;
+                values[storedRef.from] = `${GONE_CRITERION_PREFIX}${ref.uid ?? wire.uid}`;
+                continue;
+            }
+            if (!storedRef && nullableColumn(db, wire.table, column)) {
+                values[column] = null; // a dangling optional reference is dropped
+                continue;
+            }
+        }
+        if (resolved.status !== 'row')
+            return pending();
+        if (storedRef) {
+            values[storedRef.from] = resolved.key;
+            values[column] = resolved.uid;
+        }
+        else {
+            values[column] = resolved.key;
+        }
+    }
+    for (const [column, refs] of Object.entries(wire.jsonRefs ?? {})) {
+        const target = arrayColumns.get(column);
+        if (!target)
+            throw new Error(`receive: ${wire.table}.${column} is not a declared id array`);
+        const keys = [];
+        for (const ref of refs) {
+            const resolved = resolveWireRef(db, target, ref);
+            if (resolved.status !== 'row')
+                return pending();
+            keys.push(resolved.key);
+        }
+        values[column] = JSON.stringify(keys);
+    }
+    if (spec.displayId && minted) {
+        const key = keyOf(wire.table);
+        const remint = readRemint(db, wire.uid, wire.birthFp);
+        if (remint)
+            values[key] = remint.newId;
+        const holder = db
+            .prepare(`SELECT ${q(UID_COLUMN)} AS uid FROM main.${q(wire.table)} WHERE ${q(key)} = ?`)
+            .get(values[key] ?? null);
+        if (holder) {
+            const contested = String(values[key]);
+            const loserUid = collisionLoser(holder.uid ?? '', wire.uid);
+            hold(db, wire, 'display-id-collision', contested, heldAs);
+            return {
+                status: 'held',
+                reason: 'display-id-collision',
+                collision: {
+                    kind: 'display-id',
+                    table: wire.table,
+                    displayId: contested,
+                    loserUid,
+                    localIsLoser: loserUid === holder.uid,
+                },
+            };
+        }
+    }
+    if (wire.table === DISPLAY_ID_ALIAS_TABLE || wire.table === UID_ALIAS_TABLE) {
+        // An alias row's uid IS its primary key, computed on write from its key
+        // values (none is a reference): derive it the same way here (T12800).
+        const uid = naturalRowUid('project', wire.table, spec.key.map((k) => (values[k] ?? null)));
+        const existed = db.prepare(`SELECT 1 AS x FROM main.${q(wire.table)} WHERE ${q(UID_COLUMN)} = ?`).get(uid) !==
+            undefined;
+        if (wire.table === DISPLAY_ID_ALIAS_TABLE) {
+            // The order-independent upsert: whichever copy arrives first, every
+            // replica keeps the same row.
+            insertDisplayIdAliasNative(db, {
+                uid,
+                entityTable: String(values['entity_table']),
+                displayId: String(values['display_id']),
+                entityUid: String(values['entity_uid']),
+                entityBirthFp: values['entity_birth_fp'] ?? null,
+                reason: String(values['reason']),
+                origin: values['origin'] ?? null,
+                displacedHlc: values['displaced_hlc'] ?? null,
+                createdAt: String(values['created_at']),
+            }, aliasPrecedes);
+        }
+        else if (!existed) {
+            insertIdentityRowNative(db, wire.table, { ...values, [UID_COLUMN]: uid });
+        }
+        done();
+        return existed ? { status: 'duplicate', uid } : { status: 'inserted', key: uid, uid };
+    }
+    if (!minted) {
+        const existing = db
+            .prepare(`SELECT ${q(UID_COLUMN)} AS uid FROM main.${q(wire.table)}
+          WHERE ${spec.key.map((k) => `${q(k)} = ?`).join(' AND ')}`)
+            .get(...spec.key.map((k) => values[k] ?? null));
+        if (existing) {
+            done();
+            return { status: 'duplicate', uid: existing.uid ?? wire.uid };
+        }
+    }
+    const rowidKey = rowidKeyOf(db, wire.table);
+    // An INTEGER PRIMARY KEY (AUTOINCREMENT) numbers from 1 on every device: the
+    // sender's value means nothing here. Drop it; SQLite assigns a local one (T12799).
+    if (rowidKey)
+        delete values[rowidKey];
+    if (!spec.displayId && spec.key.length === 1 && !rowidKey) {
+        // A local key another row holds (keys such as AC ids derive from local
+        // display ids): the merge engine re-derives it (T12344); held until then.
+        const key = spec.key[0];
+        const taken = db
+            .prepare(`SELECT 1 AS x FROM main.${q(wire.table)} WHERE ${q(key)} = ?`)
+            .get(values[key] ?? null);
+        if (taken) {
+            hold(db, wire, 'key-collision', String(values[key]), heldAs);
+            return { status: 'held', reason: 'key-collision' };
+        }
+    }
+    // Validate like a local writer would (T12801): a received row is data from
+    // another device, never trusted to satisfy this store's invariants.
+    const invalid = validateReceived(db, wire.table, values);
+    if (invalid) {
+        hold(db, wire, 'invalid', invalid, heldAs);
+        return { status: 'held', reason: 'invalid' };
+    }
+    try {
+        inSavepoint(db, 'receive_insert', () => {
+            if (minted) {
+                insertIdentityRowNative(db, wire.table, {
+                    ...values,
+                    [UID_COLUMN]: wire.uid,
+                    [BIRTH_FP_COLUMN]: wire.birthFp,
+                });
+            }
+            else {
+                // A natural uid is a pure function of its endpoints: derive it here.
+                insertIdentityRowNative(db, wire.table, { ...values, [UID_COLUMN]: null });
+                fillTableUids(db, 'project', wire.table);
+            }
+        });
+    }
+    catch (error) {
+        // The store's own guards refused it (hierarchy cycle and type-matrix
+        // triggers, CHECK and NOT NULL constraints): hold it, never throw the
+        // merge away, never insert it.
+        if (!isConstraintError(error))
+            throw error;
+        const message = error instanceof Error ? error.message : String(error);
+        hold(db, wire, 'invalid', message.slice(0, 200), heldAs);
+        return { status: 'held', reason: 'invalid' };
+    }
+    done();
+    const key = rowidKey
+        ? String(db
+            .prepare(`SELECT ${q(rowidKey)} AS k FROM main.${q(wire.table)} WHERE ${q(UID_COLUMN)} = ?`)
+            .get(wire.uid).k)
+        : spec.key.length === 1
+            ? String(values[spec.key[0]])
+            : wire.uid;
+    return { status: 'inserted', key, uid: wire.uid };
+}
+/** The table's INTEGER PRIMARY KEY column (a rowid alias, locally numbered), if it has one. */
+function rowidKeyOf(db, table) {
+    const pk = db.prepare('SELECT name, type, pk FROM pragma_table_info(?)').all(table).filter((c) => c.pk > 0);
+    const [only] = pk;
+    return pk.length === 1 && only && only.type.toUpperCase() === 'INTEGER' ? only.name : undefined;
+}
+/** Held rows a trigger may unblock (indexed lookups and a JSON text match, never a full retry). */
+function candidatesFor(db, t) {
+    const cols = `entity_table AS entityTable, uid, birth_fp AS birthFp, row_json AS rowJson`;
+    const out = [];
+    if (t.held) {
+        const row = db
+            .prepare(`SELECT ${cols} FROM ${QUARANTINE_TABLE} WHERE entity_table = ? AND uid = ? AND birth_fp = ?`)
+            .get(t.held.entityTable, t.held.uid, t.held.birthFp);
+        if (row)
+            out.push(row);
+    }
+    if (t.key !== undefined) {
+        out.push(...db
+            .prepare(`SELECT ${cols} FROM ${QUARANTINE_TABLE} WHERE entity_table = ? AND contested_id = ?
+            ORDER BY created_at, uid`)
+            .all(t.table, t.key));
+    }
+    if (t.uid !== undefined) {
+        // Rows waiting on a reference to this uid carry it in their wire form,
+        // either as this uid or as an old uid a re-key led here.
+        const uids = new Set([t.uid]);
+        for (let frontier = [t.uid]; frontier.length > 0;) {
+            const older = db
+                .prepare(`SELECT old_uid AS uid FROM ${UID_ALIAS_TABLE}
+            WHERE entity_table = ? AND new_uid IN (${frontier.map(() => '?').join(', ')})`)
+                .all(t.table, ...frontier);
+            frontier = older.map((r) => r.uid).filter((u) => !uids.has(u));
+            for (const u of frontier)
+                uids.add(u);
+        }
+        const find = db.prepare(`SELECT ${cols} FROM ${QUARANTINE_TABLE} WHERE instr(row_json, ?) > 0 AND uid <> ?
+        ORDER BY created_at, uid`);
+        for (const uid of uids) {
+            out.push(...find.all(`"${uid}"`, t.uid));
+        }
+    }
+    return out;
+}
+/**
+ * Re-try the held rows the triggers may unblock, then the rows each placement
+ * unblocks in turn (a placed owner unblocks its children). A held row is only
+ * re-tried when something it may wait on changed, and a row still held for
+ * the same reason is not rewritten (T12801: no full re-scan per receive).
+ * `'all'` re-tries every held row once (explicit {@link releaseHeld}).
+ */
+function releaseHeldRows(db, triggers) {
+    const released = [];
+    const work = [];
+    const attempt = (h) => {
+        const key = { entityTable: h.entityTable, uid: h.uid, birthFp: h.birthFp };
+        const result = placeRow(db, JSON.parse(h.rowJson), key);
+        if (result.status === 'held')
+            return;
+        released.push(key);
+        if (result.status === 'inserted') {
+            work.push({ table: h.entityTable, uid: result.uid, key: result.key });
+        }
+    };
+    if (triggers === 'all') {
+        const held = db
+            .prepare(`SELECT entity_table AS entityTable, uid, birth_fp AS birthFp, row_json AS rowJson
+           FROM ${QUARANTINE_TABLE} ORDER BY created_at, entity_table, uid`)
+            .all();
+        for (const h of held)
+            attempt(h);
+    }
+    else {
+        work.push(...triggers);
+    }
+    for (let next = work.shift(); next !== undefined; next = work.shift()) {
+        const seen = new Set();
+        for (const h of candidatesFor(db, next)) {
+            const id = `${h.entityTable}\u0000${h.uid}\u0000${h.birthFp}`;
+            if (seen.has(id))
+                continue;
+            seen.add(id);
+            attempt(h);
+        }
+    }
+    return released;
+}
+/** Release triggers of a re-key receipt: its moved rows and the uids they left and took. */
+function rekeyTriggers(receipt) {
+    const out = [
+        { table: receipt.table, uid: receipt.oldUid },
+        { table: receipt.table, uid: receipt.newUid },
+        {
+            table: receipt.table,
+            held: { entityTable: receipt.table, uid: receipt.newUid, birthFp: receipt.birthFp },
+        },
+    ];
+    for (const child of receipt.cascaded)
+        out.push(...rekeyTriggers(child));
+    return out;
+}
+/** The policy each connection receives under; set by {@link receiveRow}'s `policy`. */
+const receivePolicies = new WeakMap();
+/**
+ * Resolve the receive policy of a project from its configuration, exactly as
+ * a local task write does (`resolveHierarchyPolicy(loadConfig())`, so
+ * `hierarchy.maxDepth` and `CLEO_HIERARCHY_MAX_DEPTH` apply). The merge engine
+ * resolves it once per merge and passes it to {@link receiveRow}.
+ *
+ * @param cwd - Project root.
+ * @returns The policy.
+ */
+export async function loadReceivePolicy(cwd) {
+    // Loaded lazily: config.js is outside the store module graph.
+    const { loadConfig } = await import('../config.js');
+    return { maxDepth: resolveHierarchyPolicy(await loadConfig(cwd)).maxDepth };
+}
+/** The policy in force on `db`: the last one passed, else the default profile's. */
+function receivePolicyOf(db) {
+    return (receivePolicies.get(db) ?? {
+        maxDepth: resolveHierarchyPolicy({}).maxDepth,
+    });
+}
+/**
+ * Receive one row: place it, or hold it (module docs). The first receive
+ * marks the store's identity values as shared, so the open pass never
+ * clears them (T12746).
+ *
+ * @param db - Connection on the project `cleo.db`, inside the merge transaction.
+ * @param wire - The incoming row.
+ * @param policy - The project's resolved receive policy ({@link loadReceivePolicy}).
+ *   It stays in force on this connection, also for held rows released later;
+ *   without one, the default hierarchy profile applies.
+ * @returns What happened; a `held` result carries the collision for the caller
+ *   (the merge engine) to hand to its authority.
+ */
+export function receiveRow(db, wire, policy) {
+    if (policy)
+        receivePolicies.set(db, policy);
+    registerRowUidFunction(db, 'project');
+    return inSavepoint(db, 'receive', () => {
+        markRowIdentityShared(db, 'receive');
+        const result = placeRow(db, wire);
+        if (result.status === 'inserted') {
+            releaseHeldRows(db, [{ table: wire.table, uid: result.uid, key: result.key }]);
+        }
+        return result;
+    });
+}
+/** Depth of a local task (a root is 0), walking its parent chain. */
+function depthOf(db, taskId) {
+    const parentOf = db.prepare('SELECT parent_id AS p FROM tasks_tasks WHERE id = ?');
+    let depth = 0;
+    let current = taskId;
+    for (let hop = 0; hop < 64 && current !== null; hop++) {
+        const row = parentOf.get(current);
+        current = row?.p ?? null;
+        if (current !== null)
+            depth++;
+    }
+    return depth;
+}
+/**
+ * Whether an insert error is the store refusing the row: SQLite's
+ * SQLITE_CONSTRAINT family (CHECK, NOT NULL, UNIQUE, FOREIGN KEY, and the
+ * guard triggers' `RAISE(ABORT, ...)`, which report SQLITE_CONSTRAINT_TRIGGER).
+ * Anything else (a missing table, an I/O error) is not the row's fault and
+ * is thrown.
+ */
+function isConstraintError(error) {
+    const code = error?.errcode;
+    return typeof code === 'number' && (code & 0xff) === 19; // SQLITE_CONSTRAINT
+}
+/** The claim lease columns: local to the device that took the lease, never received. */
+const CLAIM_COLUMNS = ['claimed_by_session', 'claimed_by_agent', 'claimed_at', 'lease_expires_at'];
+/**
+ * Per-table validation of a received row, in place (T12801). A task is checked
+ * against `insertTaskSchema` (the schema every local task write satisfies) and
+ * arrives without a claim lease: a lease belongs to the device and session
+ * that took it. The store's triggers (containment cycle, type matrix, status
+ * pipeline) then run on the insert itself.
+ *
+ * @returns Why the row is invalid, or `null`.
+ */
+function validateReceived(db, table, values) {
+    if (table !== 'tasks_tasks')
+        return null;
+    // The containment depth cap every local task write enforces, from the
+    // project's resolved hierarchy policy (T12801 review).
+    const parent = values.parent_id;
+    if (typeof parent === 'string' && parent.length > 0) {
+        const { maxDepth } = receivePolicyOf(db);
+        const parentDepth = depthOf(db, parent);
+        if (exceedsMaxDepth(parentDepth, maxDepth)) {
+            return `E_DEPTH_EXCEEDED: depth ${parentDepth + 1} under ${parent} exceeds ${maxDepth}`;
+        }
+    }
+    for (const column of CLAIM_COLUMNS) {
+        if (column in values)
+            values[column] = null;
+    }
+    const byColumn = new Map(Object.entries(getTableColumns(tasksTable)).map(([prop, col]) => [col.name, prop]));
+    const candidate = {};
+    for (const [column, value] of Object.entries(values)) {
+        const prop = byColumn.get(column);
+        if (prop !== undefined && value !== null)
+            candidate[prop] = value;
+    }
+    const parsed = insertTaskSchema.safeParse(candidate);
+    if (parsed.success)
+        return null;
+    const issue = parsed.error.issues[0];
+    return `invalid ${issue?.path.join('.') ?? 'row'}: ${issue?.message ?? 'rejected'}`.slice(0, 200);
+}
+/**
+ * Re-try the held rows now (after an op this module did not apply).
+ *
+ * @param db - Connection on the project `cleo.db`.
+ * @returns The rows placed.
+ */
+export function releaseHeld(db) {
+    registerRowUidFunction(db, 'project');
+    return inSavepoint(db, 'release', () => releaseHeldRows(db, 'all'));
+}
+/**
+ * Every held row (read-only: held rows are never edited in place).
+ *
+ * @param db - Connection on the project `cleo.db`.
+ * @returns The held rows, oldest first.
+ */
+export function listHeldRows(db) {
+    return db
+        .prepare(`SELECT entity_table AS entityTable, uid, birth_fp AS birthFp, reason,
+                contested_id AS contestedId, created_at AS createdAt, row_json AS rowJson
+           FROM ${QUARANTINE_TABLE} ORDER BY created_at, entity_table, uid`)
+        .all().map(({ rowJson, ...rest }) => ({ ...rest, row: JSON.parse(rowJson) }));
+}
+/**
+ * The wire form of a local row (what a sender publishes): values without the
+ * identity columns, and every declared reference as the target's uid and
+ * birth fingerprint.
+ *
+ * @param db - Connection on the project `cleo.db`.
+ * @param table - Declared table.
+ * @param uid - The row's uid.
+ * @returns The wire row.
+ */
+export function wireRowOf(db, table, uid) {
+    const spec = specOf(table);
+    const row = db.prepare(`SELECT * FROM main.${q(table)} WHERE ${q(UID_COLUMN)} = ?`).get(uid);
+    if (!row)
+        throw new Error(`wire: no ${table} row with uid ${uid}`);
+    const keyColumns = localKeyColumns(spec);
+    const values = {};
+    for (const [column, value] of Object.entries(row)) {
+        if (column === UID_COLUMN || column === BIRTH_FP_COLUMN || keyColumns.has(column))
+            continue;
+        values[column] = value;
+    }
+    /** The identity of the target row, by its local key or by its uid. */
+    const identityOf = (target, by, value) => {
+        const minted = specOf(target).kind === 'minted';
+        const t = db
+            .prepare(`SELECT ${q(UID_COLUMN)} AS uid, ${minted ? q(BIRTH_FP_COLUMN) : 'NULL'} AS fp
+           FROM main.${q(target)} WHERE ${q(by === 'key' ? keyOf(target) : UID_COLUMN)} = ?`)
+            .get(value);
+        // A missing target travels as gone (the raw key never travels); one whose
+        // uid is not filled yet travels as uid null (the receiver waits).
+        if (!t)
+            return { uid: null, birthFp: null, gone: true };
+        return t.uid ? { uid: t.uid, birthFp: t.fp } : { uid: null, birthFp: null };
+    };
+    /** The fingerprint a deleted criterion had, from the AC uid graveyard. */
+    const graveyardFp = (acUid) => {
+        const has = db
+            .prepare("SELECT 1 AS x FROM sqlite_master WHERE type = 'table' AND name = ?")
+            .get(AC_UID_GRAVEYARD);
+        if (!has)
+            return null;
+        const r = db
+            .prepare(`SELECT birth_fp AS fp FROM ${AC_UID_GRAVEYARD} WHERE uid = ? ORDER BY seq DESC LIMIT 1`)
+            .get(acUid);
+        return r?.fp ?? null;
+    };
+    const refs = {};
+    for (const [column, target] of refTargets(spec)) {
+        const value = row[column];
+        refs[column] = value === null || value === undefined ? null : identityOf(target, 'key', value);
+    }
+    for (const [column, { table: target, from }] of storedUidRefs(spec)) {
+        const recorded = row[column];
+        const key = row[from];
+        if (recorded !== null && recorded !== undefined) {
+            refs[column] = identityOf(target, 'uid', recorded);
+            // A recorded uid whose row this store no longer has keeps its uid, with
+            // the fingerprint the graveyard kept when there is one; the receiver
+            // never matches it without a fingerprint.
+            if (refs[column]?.uid === null) {
+                refs[column] = {
+                    uid: String(recorded),
+                    birthFp: graveyardFp(String(recorded)),
+                    gone: true,
+                };
+            }
+        }
+        else {
+            refs[column] = key === null || key === undefined ? null : identityOf(target, 'key', key);
+        }
+    }
+    const jsonRefs = {};
+    for (const [column, target] of jsonArrayTargets(spec)) {
+        const raw = row[column];
+        let ids;
+        try {
+            ids = typeof raw === 'string' ? JSON.parse(raw) : null;
+        }
+        catch {
+            ids = null;
+        }
+        if (!Array.isArray(ids)) {
+            values[column] = raw ?? null; // not an id array: sent as is
+            continue;
+        }
+        // An id whose task this store no longer has is dropped from the array:
+        // there is nothing it could name on the receiver (T12798 review).
+        jsonRefs[column] = ids
+            .map((id) => identityOf(target, 'key', String(id)))
+            .filter((ref) => !ref.gone);
+    }
+    return {
+        version: WIRE_VERSION,
+        table,
+        uid,
+        birthFp: spec.kind === 'minted' ? (row[BIRTH_FP_COLUMN] ?? null) : null,
+        values,
+        refs,
+        ...(Object.keys(jsonRefs).length > 0 ? { jsonRefs } : {}),
+    };
+}
+/** Stored-uid copies, display aliases, the re-mint record and the uid alias of a moved row. */
+function followRow(db, table, key, oldUid, birthFp, newUid, options) {
+    const moved = [];
+    if (key !== null) {
+        for (const other of ROW_IDENTITY.project) {
+            for (const ref of other.storedRefUids ?? []) {
+                if (ref.table !== table || (ref.source ?? 'uid') !== 'uid')
+                    continue;
+                rewriteStoredRefUidNative(db, other.table, ref.column, ref.from, key, oldUid, newUid);
+            }
+        }
+    }
+    const aliases = db
+        .prepare(`SELECT uid, display_id AS displayId, reason, origin, displaced_hlc AS displacedHlc,
+              created_at AS createdAt
+         FROM ${DISPLAY_ID_ALIAS_TABLE}
+        WHERE entity_table = ? AND entity_uid = ? AND entity_birth_fp = ?`)
+        .all(table, oldUid, birthFp);
+    for (const a of aliases) {
+        deleteDisplayIdAliasNative(db, a.uid);
+        const uid = naturalRowUid('project', DISPLAY_ID_ALIAS_TABLE, [
+            table,
+            a.displayId,
+            newUid,
+            a.reason,
+        ]);
+        insertDisplayIdAliasNative(db, {
+            uid,
+            entityTable: table,
+            displayId: a.displayId,
+            entityUid: newUid,
+            entityBirthFp: birthFp,
+            reason: a.reason,
+            origin: a.origin,
+            displacedHlc: a.displacedHlc,
+            createdAt: a.createdAt,
+        }, aliasPrecedes);
+        moved.push({ table: DISPLAY_ID_ALIAS_TABLE, oldUid: a.uid, newUid: uid });
+    }
+    insertUidAliasNative(db, {
+        uid: naturalRowUid('project', UID_ALIAS_TABLE, [table, oldUid, birthFp]),
+        entityTable: table,
+        oldUid,
+        oldBirthFp: birthFp,
+        newUid,
+        origin: options.origin ?? null,
+        displacedHlc: options.displacedHlc ?? null,
+        createdAt: options.now ?? new Date().toISOString(),
+    });
+    return moved;
+}
+/** Natural rows keyed by (`table`, `key`): their table, rowid and uid. */
+function naturalRowsKeyedBy(db, table, key) {
+    const out = [];
+    for (const other of ROW_IDENTITY.project) {
+        if (other.kind !== 'natural')
+            continue;
+        const keyed = (other.keyRefs ?? []).filter((ref) => ref.table === table);
+        if (keyed.length === 0)
+            continue;
+        const rows = db
+            .prepare(`SELECT rowid AS rowid, ${q(UID_COLUMN)} AS uid FROM main.${q(other.table)}
+          WHERE ${keyed.map((ref) => `${q(ref.column)} = ?`).join(' OR ')}`)
+            .all(...keyed.map(() => key));
+        for (const r of rows)
+            out.push({ table: other.table, ...r });
+    }
+    return out;
+}
+/** Minted children of a placed row, found through their owner column. */
+function localChildren(db, table, key) {
+    const out = [];
+    for (const child of ROW_IDENTITY.project) {
+        if (child.kind !== 'minted')
+            continue;
+        for (const owner of child.owners ?? []) {
+            if (owner.table !== table)
+                continue;
+            const rows = db
+                .prepare(`SELECT ${q(UID_COLUMN)} AS uid, ${q(BIRTH_FP_COLUMN)} AS birthFp
+             FROM main.${q(child.table)}
+            WHERE ${q(owner.column)} = ? AND ${q(UID_COLUMN)} IS NOT NULL
+              AND ${q(BIRTH_FP_COLUMN)} IS NOT NULL
+            ORDER BY ${q(UID_COLUMN)}`)
+                .all(key);
+            for (const r of rows)
+                out.push({ table: child.table, ...r });
+        }
+    }
+    return out;
+}
+/** Held minted children of a held row, found through their wire owner ref. */
+function heldChildren(db, table, uid, birthFp) {
+    const out = [];
+    for (const h of listHeldRows(db)) {
+        const spec = rowIdentitySpec('project', h.entityTable);
+        if (spec?.kind !== 'minted')
+            continue;
+        for (const owner of spec.owners ?? []) {
+            if (owner.table !== table)
+                continue;
+            const ref = h.row.refs?.[owner.column];
+            if (ref && ref.uid === uid && ref.birthFp === birthFp) {
+                out.push({ table: h.entityTable, uid: h.uid, birthFp: h.birthFp });
+            }
+        }
+    }
+    return out;
+}
+/** Re-key a held row's wire form. */
+function rekeyHeldRow(db, key, newUid) {
+    const row = db
+        .prepare(`SELECT row_json AS rowJson FROM ${QUARANTINE_TABLE}
+        WHERE entity_table = ? AND uid = ? AND birth_fp = ?`)
+        .get(key.entityTable, key.uid, key.birthFp);
+    const wire = JSON.parse(row.rowJson);
+    rekeyQuarantineNative(db, key, newUid, JSON.stringify({ ...wire, uid: newUid }));
+}
+/** Where a (table, uid, birth fp) row is on this replica. */
+function locate(db, table, uid, birthFp) {
+    const local = localRow(db, table, uid, birthFp);
+    if (local)
+        return { where: 'local', key: local.key };
+    const held = db
+        .prepare(`SELECT 1 AS x FROM ${QUARANTINE_TABLE} WHERE entity_table = ? AND uid = ? AND birth_fp = ?`)
+        .get(table, uid, birthFp);
+    return held ? { where: 'held' } : { where: 'absent' };
+}
+/** AUTHORITY: re-key one row wherever it is, derive its cascade, and return the receipt. */
+function rekeyDerive(db, table, oldUid, birthFp, newUid, options) {
+    const at = locate(db, table, oldUid, birthFp);
+    const natural = [];
+    let children;
+    if (at.where === 'local') {
+        children = localChildren(db, table, at.key);
+        const keyed = naturalRowsKeyedBy(db, table, at.key);
+        setRowUidNative(db, table, oldUid, birthFp, newUid);
+        natural.push(...followRow(db, table, at.key, oldUid, birthFp, newUid, options));
+        for (const n of keyed)
+            clearRowUidNative(db, n.table, n.rowid);
+        for (const t of new Set(keyed.map((n) => n.table)))
+            fillTableUids(db, 'project', t);
+        for (const n of keyed) {
+            const now = db
+                .prepare(`SELECT ${q(UID_COLUMN)} AS uid FROM main.${q(n.table)} WHERE rowid = ?`)
+                .get(n.rowid);
+            if (n.uid && now.uid && n.uid !== now.uid) {
+                natural.push({ table: n.table, oldUid: n.uid, newUid: now.uid });
+            }
+        }
+    }
+    else if (at.where === 'held') {
+        children = heldChildren(db, table, oldUid, birthFp);
+        rekeyHeldRow(db, { entityTable: table, uid: oldUid, birthFp }, newUid);
+        followRow(db, table, null, oldUid, birthFp, newUid, options);
+    }
+    else {
+        throw new CleoError(ExitCode.NOT_FOUND, `No ${table} row ${oldUid} with birth ${birthFp}`, {
+            details: { field: 'uid', actual: oldUid },
+        });
+    }
+    const cascaded = children.map((c) => rekeyDerive(db, c.table, c.uid, c.birthFp, rekeyedChildUid('project', c.table, c.uid, newUid), options));
+    return {
+        table,
+        oldUid,
+        birthFp,
+        newUid,
+        natural,
+        cascaded,
+        origin: options.origin ?? null,
+        hlc: options.displacedHlc ?? null,
+    };
+}
+/**
+ * AUTHORITY ONLY: re-key the LOSER of a uid collision (same uid, different
+ * birth fingerprints; the loser is the greater fingerprint). The caller names
+ * the loser by its fingerprint and the call asserts it: the row re-keyed is
+ * the one with `loserBirthFp`, wherever it is here (placed, or held because
+ * the winner arrived first), and a fingerprint that is not the greater of the
+ * pair is refused. The row gets a random uid; the cascade follows from stored
+ * identity (module docs). Held rows the re-key unblocks are placed.
+ *
+ * @param db - Connection on the project `cleo.db`.
+ * @param table - Minted table of the row.
+ * @param uid - The colliding uid.
+ * @param collision - The loser's and the winner's birth fingerprints (the
+ *   winner must be the smaller; T12801).
+ * @param options - The authority and the HLC of the re-key.
+ * @returns The receipt to publish, with its cascade and natural uids.
+ * @throws CleoError when this replica has no row (uid, loserBirthFp), or the
+ *   fingerprint is not the loser's.
+ */
+export function rekeyRowUid(db, table, uid, collision, options = {}) {
+    if (specOf(table).kind !== 'minted') {
+        throw new Error(`rekey: ${table} is not a declared minted table`);
+    }
+    const { loserBirthFp, winnerBirthFp } = collision;
+    // The loser is the greater fingerprint of the pair; the caller names both,
+    // so a swapped or stale pair is refused rather than re-keying the winner.
+    if (!(winnerBirthFp < loserBirthFp)) {
+        throw new CleoError(ExitCode.VALIDATION_ERROR, `rekey: ${loserBirthFp} is not the loser of the ${table} uid collision on ${uid} (the loser is the greater fingerprint; winner ${winnerBirthFp})`, {
+            fix: 'Re-key the row with the greater birth fingerprint; the smaller one keeps the uid.',
+            details: { field: 'loserBirthFp', actual: loserBirthFp, expected: winnerBirthFp },
+        });
+    }
+    const rivals = [
+        ...db
+            .prepare(`SELECT ${q(BIRTH_FP_COLUMN)} AS fp FROM main.${q(table)} WHERE ${q(UID_COLUMN)} = ?`)
+            .all(uid).map((r) => r.fp),
+        ...db
+            .prepare(`SELECT birth_fp AS fp FROM ${QUARANTINE_TABLE} WHERE entity_table = ? AND uid = ?`)
+            .all(table, uid).map((r) => r.fp),
+    ].filter((fp) => fp !== null && fp !== loserBirthFp);
+    const greater = rivals.find((fp) => fp > loserBirthFp || fp !== winnerBirthFp);
+    if (greater !== undefined) {
+        throw new CleoError(ExitCode.VALIDATION_ERROR, `rekey: ${loserBirthFp} is not the loser of the ${table} uid collision on ${uid}`, {
+            fix: 'Re-key the row with the greater birth fingerprint; the smaller one keeps the uid.',
+            details: { field: 'loserBirthFp', actual: loserBirthFp, expected: greater },
+        });
+    }
+    if (locate(db, table, uid, loserBirthFp).where === 'absent') {
+        throw new CleoError(ExitCode.NOT_FOUND, `No ${table} row with uid ${uid} and birth fingerprint ${loserBirthFp} on this replica`, {
+            fix: 'Only a replica that holds the loser re-keys it; the others apply the receipt.',
+            details: { field: 'uid', actual: uid },
+        });
+    }
+    registerRowUidFunction(db, 'project');
+    return inSavepoint(db, 'rekey', () => {
+        const receipt = rekeyDerive(db, table, uid, loserBirthFp, mintRowUid(), options);
+        releaseHeldRows(db, rekeyTriggers(receipt));
+        return receipt;
+    });
+}
+/** Apply one receipt entry, then its cascade. */
+function applyEntry(db, e, out) {
+    const options = { origin: e.origin, displacedHlc: e.hlc };
+    const at = locate(db, e.table, e.oldUid, e.birthFp);
+    let status;
+    if (at.where === 'local') {
+        const keyed = naturalRowsKeyedBy(db, e.table, at.key);
+        setRowUidNative(db, e.table, e.oldUid, e.birthFp, e.newUid);
+        followRow(db, e.table, at.key, e.oldUid, e.birthFp, e.newUid, options);
+        for (const n of e.natural) {
+            if (n.table !== DISPLAY_ID_ALIAS_TABLE)
+                setNaturalUidNative(db, n.table, n.oldUid, n.newUid);
+        }
+        // A natural row the authority did not have (an edge only this replica
+        // holds) is re-derived here; for the published ones this is a no-op.
+        for (const n of keyed)
+            clearRowUidNative(db, n.table, n.rowid);
+        for (const t of new Set(keyed.map((n) => n.table)))
+            fillTableUids(db, 'project', t);
+        status = 'applied';
+    }
+    else if (at.where === 'held') {
+        rekeyHeldRow(db, { entityTable: e.table, uid: e.oldUid, birthFp: e.birthFp }, e.newUid);
+        followRow(db, e.table, null, e.oldUid, e.birthFp, e.newUid, options);
+        status = 'applied-held';
+    }
+    else {
+        status =
+            locate(db, e.table, e.newUid, e.birthFp).where === 'absent'
+                ? 'alias-only'
+                : 'already-applied';
+        followRow(db, e.table, null, e.oldUid, e.birthFp, e.newUid, options);
+    }
+    out.push({ table: e.table, oldUid: e.oldUid, status });
+    for (const child of e.cascaded)
+        applyEntry(db, child, out);
+}
+/**
+ * RECEIVER: apply a published {@link RekeyReceipt}. Every entry moves the row
+ * with (old uid, birth fingerprint) to the published new uid, wherever it is
+ * here: a placed row (with its stored copies, display aliases and the
+ * published natural uids), a held row (its wire form), or nowhere (the uid
+ * alias is recorded, so the row takes its new uid when it arrives). A row
+ * with the old uid and ANOTHER fingerprint (the winner) is never touched.
+ * Nothing is recomputed. Held rows the re-key unblocks are placed.
+ *
+ * @param db - Connection on the project `cleo.db`.
+ * @param receipt - The published receipt.
+ * @returns Per-row outcome, and the held rows placed.
+ */
+export function applyRekey(db, receipt) {
+    registerRowUidFunction(db, 'project');
+    return inSavepoint(db, 'rekey_apply', () => {
+        markRowIdentityShared(db, 'receive');
+        const rows = [];
+        applyEntry(db, receipt, rows);
+        return { rows, released: releaseHeldRows(db, rekeyTriggers(receipt)) };
+    });
+}
+//# sourceMappingURL=display-id-alias.js.map