@cleocode/core 2026.9.25 → 2026.9.26

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

@@ -69,54 +69,98 @@
  * @task T12750
  * @epic T12323
  */
-import { ExitCode } from '@cleocode/contracts';
+import { ExitCode, } from '@cleocode/contracts';
+import { getTableColumns } from 'drizzle-orm';
 import { CleoError } from '../errors.js';
-import { BIRTH_FP_COLUMN, fillTableUids, markRowIdentityShared, mintRowUid, naturalRowUid, ROW_IDENTITY, ROW_IDENTITY_META_TABLE, registerRowUidFunction, rekeyedChildUid, rowIdentitySpec, UID_COLUMN, } from './row-identity.js';
-import { advanceTaskIdSequence, clearRowUidNative, deleteDisplayIdAliasNative, deleteQuarantineNative, deleteRowIdentityMetaNative, insertDisplayIdAliasNative, insertIdentityRowNative, insertQuarantineNative, insertUidAliasNative, rekeyQuarantineNative, renameTaskDisplayIdNative, rewriteStoredRefUidNative, setNaturalUidNative, setRowUidNative, writeRowIdentityMetaNative, } from './sqlite-data-accessor.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';
-const HLC_RE = /^(\d{15})\.(\d{6})\.(.+)$/;
+// ---- 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.
 /**
- * Encode an HLC value.
+ * Total order of two encoded HLC values (`Hlc` wire strings).
  *
- * @param hlc - The value.
- * @returns Its sortable string form.
+ * @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 encodeHlc(hlc) {
-    return `${String(hlc.physicalMs).padStart(15, '0')}.${String(hlc.counter).padStart(6, '0')}.${hlc.node}`;
+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})\.(.+)$/;
 /**
- * Parse an encoded HLC value.
+ * 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.
  *
- * @param value - Encoded HLC.
- * @returns The value.
- * @throws Error when the value is not an encoded HLC.
+ * @throws HlcError when the value is in neither format.
  */
-export function parseHlc(value) {
-    const m = HLC_RE.exec(value);
-    if (!m)
-        throw new Error(`not an HLC value: ${value}`);
-    return { physicalMs: Number(m[1]), counter: Number(m[2]), node: m[3] };
+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);
 }
 /**
- * Total order of two encoded HLC values.
+ * 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 a - One value.
- * @param b - The other.
- * @returns Negative, zero or positive.
+ * @param birthMsA - One row's birth, epoch ms.
+ * @param birthMsB - The other's.
+ * @returns An encoded HLC.
+ * @task T12802
  */
-export function compareHlc(a, b) {
-    const x = parseHlc(a);
-    const y = parseHlc(b);
-    if (x.physicalMs !== y.physicalMs)
-        return x.physicalMs < y.physicalMs ? -1 : 1;
-    if (x.counter !== y.counter)
-        return x.counter < y.counter ? -1 : 1;
-    return x.node < y.node ? -1 : x.node > y.node ? 1 : 0;
+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. */
@@ -152,13 +196,6 @@ function inSavepoint(db, name, fn) {
         throw error;
     }
 }
-/** A row-identity meta value. */
-function readMeta(db, key) {
-    const row = db
-        .prepare(`SELECT value FROM main.${q(ROW_IDENTITY_META_TABLE)} WHERE key = ?`)
-        .get(key);
-    return row?.value;
-}
 /** The local row of a minted table with this uid AND birth fingerprint. */
 function localRow(db, table, uid, birthFp) {
     return db
@@ -200,7 +237,7 @@ 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, parseHlc(input.atHlc).physicalMs - parseHlc(input.collisionHlc).physicalMs);
+    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))
@@ -230,10 +267,14 @@ export function remintAuthority(input) {
  */
 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,
@@ -242,8 +283,21 @@ export function recordDisplayIdAlias(db, entry) {
         reason: entry.reason,
         origin: entry.origin ?? null,
         displacedHlc: entry.displacedHlc ?? null,
-        createdAt: entry.now ?? new Date().toISOString(),
-    });
+        // 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
@@ -274,6 +328,9 @@ export function resolveDisplayId(db, table, displayId) {
           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 {
@@ -337,15 +394,29 @@ function taskReferenceColumns(db) {
     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 remintKey(uid, birthFp) {
-    return `remint:tasks_tasks:${uid}:${birthFp}`;
-}
 function readRemint(db, uid, birthFp) {
-    const raw = readMeta(db, remintKey(uid, birthFp));
-    return raw === undefined ? undefined : JSON.parse(raw);
+    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) {
-    writeRowIdentityMetaNative(db, remintKey(op.uid, op.birthFp), JSON.stringify({ newId: op.newId, hlc: op.hlc, origin: op.origin }));
+    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
@@ -389,7 +460,11 @@ export function remintTaskDisplayId(db, taskId, options) {
         });
         const op = { uid, birthFp, oldId, newId, origin: options.origin, hlc: options.hlc };
         writeRemint(db, op);
-        return { ...op, rewritten, released: releaseHeldRows(db) };
+        const released = releaseHeldRows(db, [
+            { table: 'tasks_tasks', key: taskId },
+            { table: 'tasks_tasks', key: oldId },
+        ]);
+        return { ...op, rewritten, released };
     });
 }
 /**
@@ -423,8 +498,7 @@ export function applyRemintOp(db, op) {
         if (order < 0) {
             inSavepoint(db, 'remint_superseded', () => {
                 alias(op.oldId, 'collision-remint');
-                if (op.newId !== prior.newId)
-                    alias(op.newId, 'superseded-remint');
+                writeRemint(db, op);
             });
             return { status: 'superseded', winner: prior };
         }
@@ -437,20 +511,40 @@ export function applyRemintOp(db, op) {
     }
     return inSavepoint(db, 'remint_apply', () => {
         alias(op.oldId, 'collision-remint');
-        if (prior && prior.newId !== op.newId)
-            alias(prior.newId, 'superseded-remint');
         writeRemint(db, op);
-        if (!live)
-            return { status: 'recorded', released: releaseHeldRows(db) };
+        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) },
+            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;
@@ -479,13 +573,20 @@ function followUidAlias(db, table, uid, birthFp) {
  * @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 || ref.birthFp === null || row.fp === ref.birthFp)) {
+    if (row && (!minted || row.fp === ref.birthFp)) {
         return { status: 'row', key: row.key, uid };
     }
     const held = db
@@ -493,6 +594,13 @@ export function resolveWireRef(db, table, ref) {
         .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();
@@ -501,21 +609,57 @@ function refTargets(spec) {
     }
     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 FROM ${QUARANTINE_TABLE}
-        WHERE entity_table = ? AND uid = ? AND birth_fp = ?`)
+        .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: JSON.stringify(wire),
+        rowJson,
         receivedHlc: null,
         createdAt: first?.createdAt ?? new Date().toISOString(),
     });
@@ -524,6 +668,13 @@ function hold(db, wire, reason, contestedId, previous) {
 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`);
     }
@@ -569,21 +720,67 @@ function placeRow(db, incoming, heldAs) {
         };
     }
     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 target = targets.get(column);
+        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') {
-            hold(db, wire, 'ref-pending', null, heldAs);
-            return { status: 'held', reason: 'ref-pending' };
+        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] = resolved.key;
+        values[column] = JSON.stringify(keys);
     }
     if (spec.displayId && minted) {
         const key = keyOf(wire.table);
@@ -610,6 +807,33 @@ function placeRow(db, incoming, heldAs) {
             };
         }
     }
+    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)}
@@ -637,17 +861,38 @@ function placeRow(db, incoming, heldAs) {
             return { status: 'held', reason: 'key-collision' };
         }
     }
-    if (minted) {
-        insertIdentityRowNative(db, wire.table, {
-            ...values,
-            [UID_COLUMN]: wire.uid,
-            [BIRTH_FP_COLUMN]: wire.birthFp,
+    // 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);
+            }
         });
     }
-    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
@@ -665,31 +910,123 @@ function rowidKeyOf(db, table) {
     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 every held row until none moves: a placement can unblock others
- * (a released owner unblocks its children).
+ * 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) {
+function releaseHeldRows(db, triggers) {
     const released = [];
-    for (let round = 0; round < 64; round++) {
+    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();
-        let moved = false;
-        for (const h of held) {
-            const key = { entityTable: h.entityTable, uid: h.uid, birthFp: h.birthFp };
-            const result = placeRow(db, JSON.parse(h.rowJson), key);
-            if (result.status !== 'held') {
-                released.push(key);
-                moved = true;
-            }
+        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);
         }
-        if (!moved)
-            break;
     }
     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
@@ -697,19 +1034,90 @@ function releaseHeldRows(db) {
  *
  * @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) {
+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);
+        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).
  *
@@ -718,7 +1126,7 @@ export function receiveRow(db, wire) {
  */
 export function releaseHeld(db) {
     registerRowUidFunction(db, 'project');
-    return inSavepoint(db, 'release', () => releaseHeldRows(db));
+    return inSavepoint(db, 'release', () => releaseHeldRows(db, 'all'));
 }
 /**
  * Every held row (read-only: held rows are never edited in place).
@@ -748,32 +1156,91 @@ export function wireRowOf(db, table, uid) {
     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)
-            values[column] = value;
+        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];
-        if (value === null || value === undefined) {
-            refs[column] = null;
+        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;
         }
-        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(keyOf(target))} = ?`)
-            .get(value);
-        if (t)
-            refs[column] = { uid: t.uid, birthFp: t.fp };
+        // 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. */
@@ -796,7 +1263,12 @@ function followRow(db, table, key, oldUid, birthFp, newUid, options) {
         .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]);
+        const uid = naturalRowUid('project', DISPLAY_ID_ALIAS_TABLE, [
+            table,
+            a.displayId,
+            newUid,
+            a.reason,
+        ]);
         insertDisplayIdAliasNative(db, {
             uid,
             entityTable: table,
@@ -807,16 +1279,9 @@ function followRow(db, table, key, oldUid, birthFp, newUid, options) {
             origin: a.origin,
             displacedHlc: a.displacedHlc,
             createdAt: a.createdAt,
-        });
+        }, aliasPrecedes);
         moved.push({ table: DISPLAY_ID_ALIAS_TABLE, oldUid: a.uid, newUid: uid });
     }
-    if (table === 'tasks_tasks') {
-        const remint = readMeta(db, remintKey(oldUid, birthFp));
-        if (remint !== undefined) {
-            writeRowIdentityMetaNative(db, remintKey(newUid, birthFp), remint);
-            deleteRowIdentityMetaNative(db, remintKey(oldUid, birthFp));
-        }
-    }
     insertUidAliasNative(db, {
         uid: naturalRowUid('project', UID_ALIAS_TABLE, [table, oldUid, birthFp]),
         entityTable: table,
@@ -963,16 +1428,26 @@ function rekeyDerive(db, table, oldUid, birthFp, newUid, options) {
  * @param db - Connection on the project `cleo.db`.
  * @param table - Minted table of the row.
  * @param uid - The colliding uid.
- * @param loserBirthFp - The loser's birth fingerprint.
+ * @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, loserBirthFp, options = {}) {
+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)} = ?`)
@@ -981,7 +1456,7 @@ export function rekeyRowUid(db, table, uid, loserBirthFp, options = {}) {
             .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);
+    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.',
@@ -997,7 +1472,7 @@ export function rekeyRowUid(db, table, uid, loserBirthFp, options = {}) {
     registerRowUidFunction(db, 'project');
     return inSavepoint(db, 'rekey', () => {
         const receipt = rekeyDerive(db, table, uid, loserBirthFp, mintRowUid(), options);
-        releaseHeldRows(db);
+        releaseHeldRows(db, rekeyTriggers(receipt));
         return receipt;
     });
 }
@@ -1057,7 +1532,7 @@ export function applyRekey(db, receipt) {
         markRowIdentityShared(db, 'receive');
         const rows = [];
         applyEntry(db, receipt, rows);
-        return { rows, released: releaseHeldRows(db) };
+        return { rows, released: releaseHeldRows(db, rekeyTriggers(receipt)) };
     });
 }
 //# sourceMappingURL=display-id-alias.js.map