@cleocode/core 2026.10.27 → 2026.11.1-canary.10

package/dist/store/conduit-doc-history.js

@@ -31,10 +31,10 @@
  */
 import { createHash, randomUUID } from 'node:crypto';
 import { ExitCode } from '@cleocode/contracts/exit-codes.js';
-import { and, asc, desc, eq, sql } from 'drizzle-orm';
+import { and, asc, desc, eq, isNull, sql } from 'drizzle-orm';
 import { CleoError } from '../errors.js';
 import { birthFingerprint, mintedRowUid, naturalRowUid } from './row-identity.js';
-import { conduitAttachmentApprovals, conduitAttachments, conduitAttachmentVersions, conduitDocHeads, conduitDocSlugAliases, sectionCrdtStates, } from './schema/cleo-project/conduit.js';
+import { conduitAttachmentApprovals, conduitAttachmentContributors, conduitAttachments, conduitAttachmentVersions, conduitDocHeads, conduitDocSlugAliases, sectionCrdtStates, } from './schema/cleo-project/conduit.js';
 import { conduitDocMigrationLedger, docsAttachments } from './schema/cleo-project/docs.js';
 import { getDb, getNativeDb } from './sqlite.js';
 /**
@@ -128,6 +128,67 @@ export async function resolveConduitDocUid(projectRoot, slug) {
 }
 /** Transport owner and author of an adopted identity shell (`conversation_id`, `from_agent_id`). */
 const ADOPT_SENTINEL = 'cleodocs';
+/**
+ * Whether a doc identity answers to a slug (T14288 PR 3b): a live slug on
+ * `conduit_attachments` or an old slug in `conduit_doc_slug_aliases`. Slug
+ * allocators check it beside the registry, so a new doc never takes a slug a
+ * renamed doc's old links still reach.
+ *
+ * @param db - The project store's drizzle handle.
+ * @param slug - The candidate slug.
+ * @returns True when a doc identity answers to the slug.
+ * @task T14288
+ */
+export async function isConduitDocSlug(db, slug) {
+    const live = await db
+        .select({ uid: conduitAttachments.uid })
+        .from(conduitAttachments)
+        .where(eq(conduitAttachments.slug, slug))
+        .get();
+    if (live)
+        return true;
+    const alias = await db
+        .select({ uid: conduitDocSlugAliases.docUid })
+        .from(conduitDocSlugAliases)
+        .where(eq(conduitDocSlugAliases.slug, slug))
+        .get();
+    return alias !== undefined;
+}
+/**
+ * The ONE identity recipe of a doc born in the registry (T14332): its uid,
+ * birth fingerprint and birth facts, all functions of the doc's slug and its
+ * registry row's `created_at` (a synced value), never of the device. Adopt on
+ * first update ({@link ensureConduitDoc}), `docs add` (which adopts the row it
+ * just stored) and the legacy migration ({@link importMigratedConduitDoc}) all
+ * mint it, so two devices that bring the same doc into the conduit family by
+ * different paths derive one `(uid, birth_fp)` and the receiver places the
+ * peer's row as a duplicate (T13586).
+ *
+ * @param slug - The doc's slug.
+ * @param birth - The registry row's `created_at`.
+ * @param sha256 - The registry row's content hash.
+ * @returns The doc's whole `conduit_attachments` identity row.
+ * @task T14332
+ */
+export function legacyDocIdentity(slug, birth, sha256) {
+    return {
+        slug,
+        uid: mintedRowUid('project', 'conduit_attachments', [slug], birth),
+        birthFp: birthFingerprint('conduit_attachments', birth, [ADOPT_SENTINEL, ADOPT_SENTINEL]),
+        createdAt: birth,
+        conversationId: ADOPT_SENTINEL,
+        fromAgentId: ADOPT_SENTINEL,
+        // A thin shell: the version rows carry the content addressing. Every
+        // column is a synced fact, so both paths insert the identical row.
+        content: Buffer.alloc(0),
+        originalSize: 0,
+        compressedSize: 0,
+        contentHash: sha256,
+        format: 'text',
+        title: slug,
+        tokens: 0,
+    };
+}
 /**
  * Read one `conduit_attachments` row by its immutable uid.
  *
@@ -191,38 +252,34 @@ export async function ensureConduitDoc(projectRoot, input) {
     if (existing !== null)
         return { uid: existing, adopted: false };
     const db = await getDb(projectRoot);
-    const birth = input.legacyBirth ??
-        (await db
-            .select({ birth: docsAttachments.createdAt })
+    const legacy = input.legacyBirth !== undefined && input.legacySha256 !== undefined
+        ? { birth: input.legacyBirth, sha256: input.legacySha256 }
+        : ((await db
+            .select({ birth: docsAttachments.createdAt, sha256: docsAttachments.sha256 })
             .from(docsAttachments)
             .where(eq(docsAttachments.slug, input.slug))
-            .get())?.birth ??
-        null;
-    const identity = birth === null
-        ? { fromAgentId: input.authorAgentId }
-        : {
-            fromAgentId: ADOPT_SENTINEL,
-            createdAt: birth,
-            uid: mintedRowUid('project', 'conduit_attachments', [input.slug], birth),
-            birthFp: birthFingerprint('conduit_attachments', birth, [ADOPT_SENTINEL, ADOPT_SENTINEL]),
-        };
+            .get()) ?? null);
+    const birth = input.legacyBirth ?? legacy?.birth ?? null;
     await db
         .insert(conduitAttachments)
-        .values({
-        slug: input.slug,
-        conversationId: ADOPT_SENTINEL,
-        ...identity,
-        content: Buffer.alloc(0),
-        originalSize: input.content.length,
-        compressedSize: input.content.length,
-        contentHash: createHash('sha256').update(input.content).digest('hex'),
-        format: 'text',
-        title: input.slug,
-        tokens: input.content
-            .toString('utf-8')
-            .split(/\s+/)
-            .filter((w) => w.length > 0).length,
-    })
+        .values(birth !== null && legacy !== null
+        ? legacyDocIdentity(input.slug, birth, legacy.sha256)
+        : {
+            // A slug with no registry row is a new doc: a random mint.
+            slug: input.slug,
+            conversationId: ADOPT_SENTINEL,
+            fromAgentId: input.authorAgentId,
+            content: Buffer.alloc(0),
+            originalSize: input.content.length,
+            compressedSize: input.content.length,
+            contentHash: createHash('sha256').update(input.content).digest('hex'),
+            format: 'text',
+            title: input.slug,
+            tokens: input.content
+                .toString('utf-8')
+                .split(/\s+/)
+                .filter((w) => w.length > 0).length,
+        })
         .onConflictDoNothing()
         .run();
     const row = await db
@@ -234,8 +291,184 @@ export async function ensureConduitDoc(projectRoot, input) {
         // @sync-invariant docs.doc.adopt-once an adopt that cannot be read back means the store lost the write; fail loudly instead of returning a phantom
         throw new CleoError(ExitCode.GENERAL_ERROR, `conduit doc adopt for slug '${input.slug}' could not be read back`);
     }
+    // T14288: the new identity carries the doc's metadata from the start.
+    const docRow = await db
+        .select()
+        .from(docsAttachments)
+        .where(eq(docsAttachments.slug, input.slug))
+        .get();
+    if (docRow)
+        await setConduitDocMeta(projectRoot, row.uid, await conduitDocMetaOfRow(projectRoot, docRow));
     return { uid: row.uid, adopted: true };
 }
+/** The {@link ConduitDocMeta} keys, in column order. */
+const CONDUIT_DOC_META_KEYS = [
+    'docType',
+    'lifecycleStatus',
+    'supersedesUid',
+    'supersededByUid',
+    'summary',
+    'keywords',
+    'topics',
+    'relatedTasks',
+    'displayAlias',
+    'ownerVersion',
+];
+/**
+ * The doc metadata an identity row holds (T14288), in {@link ConduitDocMeta} form.
+ *
+ * @param row - A `conduit_attachments` row.
+ * @returns Its metadata columns.
+ * @task T14288
+ */
+export function conduitDocMetaOf(row) {
+    return {
+        docType: row.docType ?? null,
+        lifecycleStatus: row.lifecycleStatus ?? null,
+        supersedesUid: row.supersedesUid ?? null,
+        supersededByUid: row.supersededByUid ?? null,
+        summary: row.summary ?? null,
+        keywords: row.keywords ?? null,
+        topics: row.topics ?? null,
+        relatedTasks: row.relatedTasks ?? null,
+        displayAlias: row.displayAlias ?? null,
+        ownerVersion: row.ownerVersion ?? null,
+    };
+}
+/**
+ * Mirror every identity row that holds no metadata yet (T14288): rows adopted
+ * before the metadata columns existed. Deterministic (each row's values come
+ * from its synced registry row), so every device writes the same values;
+ * idempotent (a mirrored row always holds a lifecycle). Run by `cleo upgrade`.
+ *
+ * @param projectRoot - Absolute path to the CLEO project root.
+ * @returns How many identity rows were mirrored.
+ * @task T14288
+ */
+export async function mirrorUnmirroredConduitDocs(projectRoot) {
+    const db = await getDb(projectRoot);
+    const rows = await db
+        .select({ slug: conduitAttachments.slug })
+        .from(conduitAttachments)
+        .where(isNull(conduitAttachments.lifecycleStatus))
+        .all();
+    let mirrored = 0;
+    for (const { slug } of rows) {
+        if (await mirrorConduitDocMeta(projectRoot, { slug }))
+            mirrored += 1;
+    }
+    return mirrored;
+}
+/**
+ * A registry row's doc metadata in identity-row form (T14288): supersession
+ * pointers (registry row ids) become doc uids, NULL when the other doc has no
+ * identity yet.
+ *
+ * @param projectRoot - Absolute path to the CLEO project root.
+ * @param row - The `docs_attachments` row.
+ * @returns The metadata for {@link setConduitDocMeta}.
+ * @task T14288
+ */
+export async function conduitDocMetaOfRow(projectRoot, row) {
+    const db = await getDb(projectRoot);
+    const uidOfRow = async (id) => {
+        if (id === null)
+            return null;
+        const other = await db
+            .select({ slug: docsAttachments.slug })
+            .from(docsAttachments)
+            .where(eq(docsAttachments.id, id))
+            .get();
+        return other?.slug ? resolveConduitDocUid(projectRoot, other.slug) : null;
+    };
+    return {
+        docType: row.type ?? null,
+        lifecycleStatus: row.lifecycleStatus,
+        supersedesUid: await uidOfRow(row.supersedes ?? null),
+        supersededByUid: await uidOfRow(row.supersededBy ?? null),
+        summary: row.summary ?? null,
+        keywords: row.keywords ?? null,
+        topics: row.topics ?? null,
+        relatedTasks: row.relatedTasks ?? null,
+        displayAlias: row.displayAlias ?? null,
+        ownerVersion: row.ownerVersion ?? null,
+    };
+}
+/**
+ * Write a doc's metadata onto its identity row (T14288), changed columns only,
+ * so an unchanged mirror records nothing in the change journal. The lifecycle
+ * and its successor travel together (one merge group), and a superseded row
+ * stays superseded (the absorbing `docs.lifecycle.transitions` rule). This is
+ * the only UPDATE of these columns; the inserts are the adopt and migrate
+ * paths, which create the row.
+ *
+ * @param projectRoot - Absolute path to the CLEO project root.
+ * @param uid - The doc's `conduit_attachments.uid`.
+ * @param meta - The metadata to hold.
+ * @returns Whether a column changed.
+ * @task T14288
+ */
+export async function setConduitDocMeta(projectRoot, uid, meta) {
+    requireNonEmpty('uid', uid);
+    const db = await getDb(projectRoot);
+    const row = await db
+        .select()
+        .from(conduitAttachments)
+        .where(eq(conduitAttachments.uid, uid))
+        .get();
+    if (!row)
+        return false;
+    // superseded is absorbing (docs.lifecycle.transitions, no leave op): every
+    // receiver refuses a write that leaves it, so the identity row never does
+    // either, even when its registry row was restored (a modernize undo). The
+    // group stays as stored; the other columns still mirror.
+    // @sync-invariant docs.lifecycle.transitions a mirror never moves the identity row out of superseded; receivers would refuse it and diverge
+    const keepGroup = row.lifecycleStatus === 'superseded' && meta.lifecycleStatus !== 'superseded';
+    const differs = CONDUIT_DOC_META_KEYS.filter((key) => row[key] !== meta[key] &&
+        !(keepGroup && (key === 'lifecycleStatus' || key === 'supersededByUid')));
+    if (differs.length === 0)
+        return false;
+    const changed = {};
+    for (const key of differs)
+        Object.assign(changed, { [key]: meta[key] });
+    // One merge group: a U op carrying part of it is refused, so both travel.
+    if (differs.includes('lifecycleStatus') || differs.includes('supersededByUid')) {
+        Object.assign(changed, {
+            lifecycleStatus: meta.lifecycleStatus,
+            supersededByUid: meta.supersededByUid,
+        });
+    }
+    await db.update(conduitAttachments).set(changed).where(eq(conduitAttachments.uid, uid)).run();
+    return true;
+}
+/**
+ * Mirror a registry row's doc metadata onto the doc's identity row (T14288,
+ * PR 3a): the kind, lifecycle, supersession (registry row ids translated to
+ * doc uids), summary, keywords, topics, related tasks, display number and
+ * writing release. Every doc metadata writer calls it after its write, so the
+ * uid carries the doc's metadata before the readers move to it (PR 3b). A row
+ * without a slug, or a doc with no identity yet, has nothing to mirror (the
+ * identity row is created with the metadata when the doc is adopted).
+ *
+ * @param projectRoot - Absolute project root.
+ * @param ref - The `docs_attachments` row just written, by id or by its slug.
+ * @returns Whether the identity row changed.
+ * @task T14288
+ */
+export async function mirrorConduitDocMeta(projectRoot, ref) {
+    const db = await getDb(projectRoot);
+    const row = await db
+        .select()
+        .from(docsAttachments)
+        .where('rowId' in ref ? eq(docsAttachments.id, ref.rowId) : eq(docsAttachments.slug, ref.slug))
+        .get();
+    if (!row?.slug)
+        return false;
+    const uid = await resolveConduitDocUid(projectRoot, row.slug);
+    if (uid === null)
+        return false;
+    return setConduitDocMeta(projectRoot, uid, await conduitDocMetaOfRow(projectRoot, row));
+}
 /**
  * Record an old-slug → doc-uid alias (append-only).
  *
@@ -247,22 +480,28 @@ export async function ensureConduitDoc(projectRoot, input) {
  * @returns The alias row's uid.
  */
 export async function recordConduitDocAlias(projectRoot, alias) {
+    const row = conduitDocAliasRow(alias);
+    const db = await getDb(projectRoot);
+    await db.insert(conduitDocSlugAliases).values(row).onConflictDoNothing().run();
+    return row.uid;
+}
+/**
+ * The `conduit_doc_slug_aliases` row for an alias, with its natural uid, for
+ * writers that insert it inside their own transaction (a slug rename, T14118).
+ *
+ * @param alias - Slug, target doc uid and an optional reason.
+ * @returns The row to insert (`onConflictDoNothing`: a repeat is a no-op).
+ */
+export function conduitDocAliasRow(alias) {
     requireNonEmpty('slug', alias.slug);
     requireNonEmpty('docUid', alias.docUid);
-    const uid = naturalRowUid('project', 'conduit_doc_slug_aliases', [alias.slug, alias.docUid]);
-    const db = await getDb(projectRoot);
-    await db
-        .insert(conduitDocSlugAliases)
-        .values({
-        uid,
+    return {
+        uid: naturalRowUid('project', 'conduit_doc_slug_aliases', [alias.slug, alias.docUid]),
         slug: alias.slug,
         docUid: alias.docUid,
         reason: alias.reason ?? 'rename',
         createdAt: new Date().toISOString(),
-    })
-        .onConflictDoNothing()
-        .run();
-    return uid;
+    };
 }
 /**
  * Append a version row to a document's history DAG.
@@ -688,32 +927,265 @@ export async function rebaseSectionCrdtStates(projectRoot, attachmentUid, baseVe
 // @sync-invariant docs.docs-migration.idempotent-import the natural uid over the slug makes a re-run a verified no-op via ON CONFLICT DO NOTHING; nothing is updated or deleted
 export async function importMigratedConduitDoc(projectRoot, input) {
     requireNonEmpty('slug', input.slug);
-    requireNonEmpty('fromAgentId', input.fromAgentId);
-    requireNonEmpty('contentHash', input.contentHash);
-    const uid = naturalRowUid('project', 'conduit_attachments', [input.slug]);
+    requireNonEmpty('legacySha256', input.legacySha256);
+    requireNonEmpty('createdAt', input.createdAt);
+    // T14332: the same identity row adopt and `docs add` mint, so a doc migrated
+    // on one device and adopted on another converges to one row.
+    const identity = legacyDocIdentity(input.slug, input.createdAt, input.legacySha256);
+    const uid = identity.uid;
     const db = await getDb(projectRoot);
+    // T14288: the imported identity carries the doc's metadata from the start.
+    const docRow = await db
+        .select()
+        .from(docsAttachments)
+        .where(eq(docsAttachments.slug, input.slug))
+        .get();
+    const meta = docRow ? await conduitDocMetaOfRow(projectRoot, docRow) : {};
     const result = await db
         .insert(conduitAttachments)
-        .values({
-        slug: input.slug,
-        conversationId: 'docs:migration',
-        fromAgentId: input.fromAgentId,
-        content: input.content,
-        originalSize: input.content.length,
-        compressedSize: input.content.length,
-        contentHash: input.contentHash,
-        format: input.format,
-        ...(input.title !== undefined ? { title: input.title } : {}),
-        tokens: input.tokens,
-        versionCount: input.versionCount,
-        currentVersion: input.versionCount,
-        createdAt: input.createdAt,
-        uid,
-    })
+        .values({ ...identity, ...meta })
         .onConflictDoNothing()
         .run();
     return { uid, inserted: (result.changes ?? 0) > 0 };
 }
+/**
+ * The `conversation_id` the pre-T14332 docs migration wrote. Its rows carry
+ * the natural uid over the slug, so they never meet the identity an adopting
+ * device mints for the same doc ({@link legacyDocIdentity}).
+ */
+export const OLD_MIGRATE_CONVERSATION = 'docs:migration';
+/**
+ * Plan the move of every doc still on the pre-T14332 migrate recipe (T14336):
+ * a doc whose shared uid ({@link legacyDocIdentity}) another row already holds
+ * cannot move and is reported, never silently left behind, so a run with only
+ * stuck docs has nothing to do and writes no snapshot.
+ *
+ * @param projectRoot - Absolute path to the CLEO project root.
+ * @returns The movable slugs and the skipped docs.
+ */
+export async function planOldMigrateRekeys(projectRoot) {
+    const db = await getDb(projectRoot);
+    const rows = await db
+        .select({ slug: conduitAttachments.slug })
+        .from(conduitAttachments)
+        .where(eq(conduitAttachments.conversationId, OLD_MIGRATE_CONVERSATION))
+        .orderBy(asc(conduitAttachments.createdAt), asc(conduitAttachments.slug))
+        .all();
+    const movable = [];
+    const skipped = [];
+    for (const { slug } of rows) {
+        const target = await oldMigrateTarget(db, slug);
+        if (target === null)
+            continue;
+        if (target.holder !== null) {
+            skipped.push({ slug, reason: 'shared-uid-taken', holder: target.holder });
+        }
+        else {
+            movable.push(slug);
+        }
+    }
+    return { movable, skipped };
+}
+/**
+ * The old-recipe doc row for a slug, its shared identity, and the slug of any
+ * other row already holding that identity's uid; `null` when the slug is not
+ * on the old recipe.
+ */
+async function oldMigrateTarget(db, slug) {
+    const doc = await db
+        .select()
+        .from(conduitAttachments)
+        .where(and(eq(conduitAttachments.slug, slug), eq(conduitAttachments.conversationId, OLD_MIGRATE_CONVERSATION)))
+        .get();
+    if (!doc?.uid)
+        return null;
+    const ledger = await db
+        .select()
+        .from(conduitDocMigrationLedger)
+        .where(eq(conduitDocMigrationLedger.slug, slug))
+        .get();
+    const identity = legacyDocIdentity(slug, doc.createdAt, ledger?.legacySha256 ?? doc.contentHash);
+    const taken = await db
+        .select({ slug: conduitAttachments.slug })
+        .from(conduitAttachments)
+        .where(eq(conduitAttachments.uid, identity.uid))
+        .get();
+    return { doc: { ...doc, uid: doc.uid }, ledger, identity, holder: taken?.slug ?? null };
+}
+/**
+ * Move one pre-T14332 migrated doc onto the shared identity (T14336).
+ *
+ * The doc row is re-keyed to {@link legacyDocIdentity} (uid, birth
+ * fingerprint and the shared shell), which the capture triggers journal as a
+ * K carrying the new fingerprint, so a peer holding this doc behind its own
+ * adopted row places it as that row (T14335). Its children follow:
+ *
+ *   - versions are re-pointed, and an imported version whose uid is the
+ *     natural uid under the old doc uid moves to the natural uid under the
+ *     new one (a K: the uid a device migrating today derives);
+ *   - approvals, the migration ledger, the local section state, the
+ *     derived contributors rollup, and every doc's `supersedes_uid` /
+ *     `superseded_by_uid` naming the doc are re-pointed;
+ *   - heads and slug aliases, natural over the doc uid, are deleted and
+ *     inserted again under it (a K cannot carry a natural key change).
+ *
+ * The caller owns the transaction and the capture frame, and defers foreign
+ * keys: mid-call the children point at a uid that no row holds yet.
+ *
+ * @param projectRoot - Absolute path to the CLEO project root.
+ * @param slug - The doc's slug.
+ * @returns The receipt, or `null` when the doc is not on the old recipe or a
+ *   row already holds the shared uid (nothing is written).
+ * @task T14336
+ */
+export async function rekeyOldMigrateConduitDoc(projectRoot, slug) {
+    return rekeyOldMigrateConduitDocOn(await getDb(projectRoot), slug);
+}
+/**
+ * {@link rekeyOldMigrateConduitDoc} on an open store handle.
+ *
+ * @param db - Drizzle handle on the project store.
+ * @param slug - The doc's slug.
+ * @returns The receipt, or `null` when nothing was written.
+ * @task T14336
+ */
+// @sync-invariant docs.doc.adopt-once the re-key moves an old-recipe doc onto the identity adopt mints, so every replica converges on one (uid, birth_fp); a re-run finds no old-recipe row and writes nothing
+export async function rekeyOldMigrateConduitDocOn(db, slug) {
+    requireNonEmpty('slug', slug);
+    const target = await oldMigrateTarget(db, slug);
+    // Not on the old recipe, or the shared uid is held (planOldMigrateRekeys reports it).
+    if (target === null || target.holder !== null)
+        return null;
+    const { doc, ledger } = target;
+    const oldUid = doc.uid;
+    const { uid: newUid, birthFp, slug: _slug, ...shell } = target.identity;
+    const versionUid = (doc, v) => naturalRowUid('project', 'conduit_attachment_versions', [doc, v.contentHash, v.createdAt]);
+    const versions = await db
+        .select()
+        .from(conduitAttachmentVersions)
+        .where(eq(conduitAttachmentVersions.attachmentUid, oldUid))
+        .all();
+    const moved = new Map();
+    for (const v of versions) {
+        if (v.uid && v.uid === versionUid(oldUid, v))
+            moved.set(v.uid, versionUid(newUid, v));
+    }
+    const follow = (uid) => uid === null ? null : (moved.get(uid) ?? uid);
+    // Natural rows first out: their key is the old doc uid.
+    const heads = await db
+        .select()
+        .from(conduitDocHeads)
+        .where(eq(conduitDocHeads.attachmentUid, oldUid))
+        .all();
+    const aliases = await db
+        .select()
+        .from(conduitDocSlugAliases)
+        .where(eq(conduitDocSlugAliases.docUid, oldUid))
+        .all();
+    await db.delete(conduitDocHeads).where(eq(conduitDocHeads.attachmentUid, oldUid)).run();
+    await db.delete(conduitDocSlugAliases).where(eq(conduitDocSlugAliases.docUid, oldUid)).run();
+    // The doc: the K (uid and fingerprint) alone, then the shared shell.
+    await db
+        .update(conduitAttachments)
+        .set({ uid: newUid, birthFp })
+        .where(eq(conduitAttachments.uid, oldUid))
+        .run();
+    await db.update(conduitAttachments).set(shell).where(eq(conduitAttachments.uid, newUid)).run();
+    // Every doc that supersedes this one, or that it supersedes, names it by uid.
+    const supersedes = await db
+        .update(conduitAttachments)
+        .set({ supersedesUid: newUid })
+        .where(eq(conduitAttachments.supersedesUid, oldUid))
+        .run();
+    const supersededBy = await db
+        .update(conduitAttachments)
+        .set({ supersededByUid: newUid })
+        .where(eq(conduitAttachments.supersededByUid, oldUid))
+        .run();
+    for (const v of versions) {
+        if (!v.uid)
+            continue;
+        await db
+            .update(conduitAttachmentVersions)
+            .set({ attachmentUid: newUid, parentVersionUid: follow(v.parentVersionUid) })
+            .where(eq(conduitAttachmentVersions.uid, v.uid))
+            .run();
+        const to = moved.get(v.uid);
+        if (to !== undefined) {
+            await db
+                .update(conduitAttachmentVersions)
+                .set({ uid: to })
+                .where(eq(conduitAttachmentVersions.uid, v.uid))
+                .run();
+        }
+    }
+    const approvals = await db
+        .select()
+        .from(conduitAttachmentApprovals)
+        .where(eq(conduitAttachmentApprovals.attachmentUid, oldUid))
+        .all();
+    for (const a of approvals) {
+        await db
+            .update(conduitAttachmentApprovals)
+            .set({ attachmentUid: newUid, versionUid: follow(a.versionUid) })
+            .where(eq(conduitAttachmentApprovals.id, a.id))
+            .run();
+    }
+    for (const h of heads) {
+        await db
+            .insert(conduitDocHeads)
+            .values({
+            ...h,
+            attachmentUid: newUid,
+            headVersionUid: follow(h.headVersionUid) ?? h.headVersionUid,
+            uid: naturalRowUid('project', 'conduit_doc_heads', [newUid]),
+        })
+            .run();
+    }
+    for (const a of aliases) {
+        await db
+            .insert(conduitDocSlugAliases)
+            .values({
+            ...conduitDocAliasRow({ slug: a.slug, docUid: newUid, reason: a.reason }),
+            createdAt: a.createdAt,
+        })
+            .run();
+    }
+    if (ledger) {
+        await db
+            .update(conduitDocMigrationLedger)
+            .set({ docUid: newUid })
+            .where(eq(conduitDocMigrationLedger.slug, slug))
+            .run();
+    }
+    await db
+        .update(conduitAttachmentContributors)
+        .set({ attachmentUid: newUid })
+        .where(eq(conduitAttachmentContributors.attachmentUid, oldUid))
+        .run();
+    const states = await db
+        .select()
+        .from(sectionCrdtStates)
+        .where(eq(sectionCrdtStates.attachmentUid, oldUid))
+        .all();
+    for (const st of states) {
+        await db
+            .update(sectionCrdtStates)
+            .set({ attachmentUid: newUid, baseVersionUid: follow(st.baseVersionUid) })
+            .where(and(eq(sectionCrdtStates.attachmentUid, oldUid), eq(sectionCrdtStates.sectionId, st.sectionId)))
+            .run();
+    }
+    return {
+        slug,
+        oldUid,
+        newUid,
+        versionsRekeyed: moved.size,
+        versionsRepointed: versions.length,
+        approvalsRepointed: approvals.length,
+        naturalRowsRecreated: heads.length + aliases.length,
+        supersessionRepointed: Number(supersedes.changes ?? 0) + Number(supersededBy.changes ?? 0),
+    };
+}
 /**
  * Import one history row for a migrated doc.
  *