@sascha384/tic 5.16.0 → 5.17.0

package/dist/storage/index.js

@@ -12,7 +12,6 @@ const DEFAULT_STATUSES = ['backlog', 'todo', 'in-progress', 'review', 'done'];
 const DEFAULT_TYPES = ['epic', 'issue', 'task'];
 const DEFAULT_ITERATIONS = ['default'];
 const DEFAULT_CURRENT_ITERATION = 'default';
-const DEFAULT_NEXT_ID = 1;
 const DEFAULT_BRANCH_MODE = 'worktree';
 const DEFAULT_AUTO_UPDATE = true;
 const DEFAULT_BRANCH_COMMAND = `claude "Brainstorm the implementation of issue #$TIC_ITEM_ID: $TIC_ITEM_TITLE. $TIC_ITEM_DESCRIPTION"`;
@@ -20,19 +19,24 @@ const DEFAULT_COPY_TO_CLIPBOARD = true;
 export class Storage extends BaseBackend {
     db;
     root;
-    tempIds;
-    constructor(db, root, options) {
+    _hasRemoteBackend = false;
+    constructor(db, root) {
         super(0); // No TTL — DB is always fresh
         this.db = db;
         this.root = root;
-        this.tempIds = options?.tempIds ?? false;
+    }
+    get hasRemoteBackend() {
+        return this._hasRemoteBackend;
+    }
+    setHasRemoteBackend(value) {
+        this._hasRemoteBackend = value;
     }
     /**
      * Create a Storage instance, initializing the database and seeding defaults.
      */
-    static create(root, options) {
+    static create(root) {
         const db = createDatabase(root);
-        const backend = new Storage(db, root, options);
+        const backend = new Storage(db, root);
         backend.seedDefaults();
         backend.migrateFromYaml();
         return backend;
@@ -40,8 +44,8 @@ export class Storage extends BaseBackend {
     /**
      * Create a Storage instance from an existing database instance (for testing).
      */
-    static createFromDb(db, options) {
-        const backend = new Storage(db, ':memory:', options);
+    static createFromDb(db) {
+        const backend = new Storage(db, ':memory:');
         backend.seedDefaults();
         return backend;
     }
@@ -62,7 +66,6 @@ export class Storage extends BaseBackend {
             id: 1,
             backend: 'drizzle',
             currentIteration: DEFAULT_CURRENT_ITERATION,
-            nextId: DEFAULT_NEXT_ID,
             branchMode: DEFAULT_BRANCH_MODE,
             branchCommand: DEFAULT_BRANCH_COMMAND,
             copyToClipboard: DEFAULT_COPY_TO_CLIPBOARD,
@@ -116,15 +119,6 @@ export class Storage extends BaseBackend {
         try {
             const raw = fs.readFileSync(yamlPath, 'utf-8');
             const config = yaml.parse(raw);
-            // Recalculate nextId from actual max item ID to prevent collisions
-            // (the YAML next_id may be stale if items were synced from a remote)
-            const maxRow = this.db.raw
-                .prepare('SELECT MAX(CAST(id AS INTEGER)) AS maxId FROM work_items')
-                .get();
-            const maxId = maxRow?.maxId ?? 0;
-            if (maxId >= config.next_id) {
-                config.next_id = maxId + 1;
-            }
             this.db.transaction((tx) => {
                 insertConfigTx(tx, config);
             });
@@ -229,7 +223,7 @@ export class Storage extends BaseBackend {
         const rows = this.db
             .selectDistinct({ label: schema.workItemLabels.label })
             .from(schema.workItemLabels)
-            .innerJoin(schema.workItems, eq(schema.workItemLabels.workItemId, schema.workItems.id))
+            .innerJoin(schema.workItems, eq(schema.workItemLabels.workItemRowId, schema.workItems.rowId))
             .where(isNull(schema.workItems.deletedAt))
             .all();
         return rows.map((r) => r.label).sort();
@@ -285,30 +279,63 @@ export class Storage extends BaseBackend {
         if (!row) {
             throw new Error(`Work item #${id} not found`);
         }
+        return this.assembleWorkItemByRowId(row);
+    }
+    // eslint-disable-next-line @typescript-eslint/require-await
+    async getWorkItemByRowId(rowId) {
+        const row = this.db
+            .select()
+            .from(schema.workItems)
+            .where(and(eq(schema.workItems.rowId, rowId), isNull(schema.workItems.deletedAt)))
+            .get();
+        if (!row) {
+            throw new Error(`Work item with rowId ${rowId} not found`);
+        }
+        return this.assembleWorkItemByRowId(row);
+    }
+    /**
+     * Get the display ID for a rowId, including soft-deleted items.
+     * Used by SyncManager to resolve display IDs for delete pushes.
+     */
+    getDisplayIdByRowId(rowId) {
+        const row = this.db
+            .select({ id: schema.workItems.id })
+            .from(schema.workItems)
+            .where(eq(schema.workItems.rowId, rowId))
+            .get();
+        if (!row)
+            return null;
+        return row.id;
+    }
+    /**
+     * Assemble a single work item from its row, loading labels/deps/comments by rowId.
+     */
+    assembleWorkItemByRowId(row) {
         const labels = this.db
             .select()
             .from(schema.workItemLabels)
-            .where(eq(schema.workItemLabels.workItemId, id))
+            .where(eq(schema.workItemLabels.workItemRowId, row.rowId))
             .all();
         const deps = this.db
             .select()
             .from(schema.workItemDeps)
-            .where(eq(schema.workItemDeps.workItemId, id))
+            .where(eq(schema.workItemDeps.workItemRowId, row.rowId))
             .all();
         const itemComments = this.db
             .select()
             .from(schema.comments)
-            .where(eq(schema.comments.workItemId, id))
+            .where(eq(schema.comments.workItemRowId, row.rowId))
             .all();
         return rowToWorkItem(row, labels, deps, itemComments);
     }
     // ─── Read: relationships (SQL-optimized overrides) ─────────────────
     // eslint-disable-next-line @typescript-eslint/require-await
     async getChildren(id) {
+        const parentRowId = this.resolveRowId(id);
         const childRows = this.db
             .select()
             .from(schema.workItems)
-            .where(and(eq(schema.workItems.parent, id), isNull(schema.workItems.deletedAt)))
+            .where(and(eq(schema.workItems.parent, parentRowId), isNull(schema.workItems.deletedAt)))
             .all();
         if (childRows.length === 0)
             return [];
@@ -316,19 +343,20 @@ export class Storage extends BaseBackend {
     }
     // eslint-disable-next-line @typescript-eslint/require-await
     async getDependents(id) {
-        // Find items that depend on `id`
+        const targetRowId = this.resolveRowId(id);
+        // Find items that depend on `targetRowId`
         const depRows = this.db
-            .select({ workItemId: schema.workItemDeps.workItemId })
+            .select({ workItemRowId: schema.workItemDeps.workItemRowId })
             .from(schema.workItemDeps)
-            .where(eq(schema.workItemDeps.dependsOnId, id))
+            .where(eq(schema.workItemDeps.dependsOnRowId, targetRowId))
             .all();
         if (depRows.length === 0)
             return [];
-        const dependentIds = depRows.map((r) => r.workItemId);
+        const dependentRowIds = depRows.map((r) => r.workItemRowId);
         const itemRows = this.db
             .select()
             .from(schema.workItems)
-            .where(and(inArray(schema.workItems.id, dependentIds), isNull(schema.workItems.deletedAt)))
+            .where(and(inArray(schema.workItems.rowId, dependentRowIds), isNull(schema.workItems.deletedAt)))
             .all();
         if (itemRows.length === 0)
             return [];
@@ -338,75 +366,89 @@ export class Storage extends BaseBackend {
      * Helper: given a set of work item rows, fetch their labels/deps/comments and assemble.
      */
     assembleWorkItems(itemRows, options) {
-        const itemIds = itemRows.map((r) => r.id);
+        const rowIds = itemRows.map((r) => r.rowId);
         const labelRows = this.db
             .select()
             .from(schema.workItemLabels)
-            .where(inArray(schema.workItemLabels.workItemId, itemIds))
+            .where(inArray(schema.workItemLabels.workItemRowId, rowIds))
             .all();
         const depRows = this.db
             .select()
             .from(schema.workItemDeps)
-            .where(inArray(schema.workItemDeps.workItemId, itemIds))
+            .where(inArray(schema.workItemDeps.workItemRowId, rowIds))
             .all();
         const commentRows = options?.includeComments
             ? this.db
                 .select()
                 .from(schema.comments)
-                .where(inArray(schema.comments.workItemId, itemIds))
+                .where(inArray(schema.comments.workItemRowId, rowIds))
                 .all()
             : [];
         const labelsByItem = new Map();
         for (const l of labelRows) {
-            const arr = labelsByItem.get(l.workItemId);
+            const arr = labelsByItem.get(l.workItemRowId);
             if (arr)
                 arr.push(l);
             else
-                labelsByItem.set(l.workItemId, [l]);
+                labelsByItem.set(l.workItemRowId, [l]);
         }
         const depsByItem = new Map();
         for (const d of depRows) {
-            const arr = depsByItem.get(d.workItemId);
+            const arr = depsByItem.get(d.workItemRowId);
             if (arr)
                 arr.push(d);
             else
-                depsByItem.set(d.workItemId, [d]);
+                depsByItem.set(d.workItemRowId, [d]);
         }
         const commentsByItem = new Map();
         for (const c of commentRows) {
-            const arr = commentsByItem.get(c.workItemId);
+            const arr = commentsByItem.get(c.workItemRowId);
             if (arr)
                 arr.push(c);
             else
-                commentsByItem.set(c.workItemId, [c]);
+                commentsByItem.set(c.workItemRowId, [c]);
         }
-        return itemRows.map((row) => rowToWorkItem(row, labelsByItem.get(row.id) ?? [], depsByItem.get(row.id) ?? [], commentsByItem.get(row.id) ?? []));
+        return itemRows.map((row) => rowToWorkItem(row, labelsByItem.get(row.rowId) ?? [], depsByItem.get(row.rowId) ?? [], commentsByItem.get(row.rowId) ?? []));
     }
     // ─── Read: item URL ────────────────────────────────────────────────
     getItemUrl(id) {
         return `${this.root}/.tic/items/${id}.md`;
     }
+    // ─── Row ID resolution ─────────────────────────────────────────
+    /**
+     * Resolve a display ID to a rowId. Throws if not found.
+     */
+    resolveRowId(displayId) {
+        const row = this.db
+            .select({ rowId: schema.workItems.rowId })
+            .from(schema.workItems)
+            .where(and(eq(schema.workItems.id, displayId), isNull(schema.workItems.deletedAt)))
+            .get();
+        if (!row)
+            throw new Error(`Work item "${displayId}" not found`);
+        return row.rowId;
+    }
     // ─── Relationship validation ─────────────────────────────────────
-    validateRelationships(id, parent, dependsOn) {
+    validateRelationships(itemRowId, parent, dependsOn) {
         // Validate parent
         if (parent !== null && parent !== undefined) {
-            if (parent === id) {
-                throw new Error(`Work item #${id} cannot be its own parent`);
+            if (parent === itemRowId) {
+                throw new Error(`Work item #${this.displayIdForRowId(itemRowId)} cannot be its own parent`);
             }
             const parentRow = this.db
-                .select({ id: schema.workItems.id })
+                .select({ rowId: schema.workItems.rowId })
                 .from(schema.workItems)
-                .where(and(eq(schema.workItems.id, parent), isNull(schema.workItems.deletedAt)))
+                .where(and(eq(schema.workItems.rowId, parent), isNull(schema.workItems.deletedAt)))
                 .get();
             if (!parentRow) {
-                throw new Error(`Parent #${parent} does not exist`);
+                throw new Error(`Parent #${this.displayIdForRowId(parent)} does not exist`);
             }
             // Walk up the parent chain to detect circular references
             let current = parent;
             const visited = new Set();
             while (current !== null) {
-                if (current === id) {
-                    throw new Error(`Circular parent chain detected for #${id}`);
+                if (current === itemRowId) {
+                    throw new Error(`Circular parent chain detected for #${this.displayIdForRowId(itemRowId)}`);
                 }
                 if (visited.has(current))
                     break;
@@ -414,83 +456,86 @@ export class Storage extends BaseBackend {
                 const row = this.db
                     .select({ parent: schema.workItems.parent })
                     .from(schema.workItems)
-                    .where(and(eq(schema.workItems.id, current), isNull(schema.workItems.deletedAt)))
+                    .where(and(eq(schema.workItems.rowId, current), isNull(schema.workItems.deletedAt)))
                     .get();
                 current = row?.parent ?? null;
             }
         }
         // Validate dependencies
         if (dependsOn !== undefined && dependsOn.length > 0) {
-            for (const depId of dependsOn) {
-                if (depId === id) {
-                    throw new Error(`Work item #${id} cannot depend on itself`);
+            for (const depRowId of dependsOn) {
+                if (depRowId === itemRowId) {
+                    throw new Error(`Work item #${this.displayIdForRowId(itemRowId)} cannot depend on itself`);
                 }
             }
             // Check all deps exist in one query
             const existingRows = this.db
-                .select({ id: schema.workItems.id })
+                .select({ rowId: schema.workItems.rowId })
                 .from(schema.workItems)
-                .where(and(inArray(schema.workItems.id, dependsOn), isNull(schema.workItems.deletedAt)))
+                .where(and(inArray(schema.workItems.rowId, dependsOn), isNull(schema.workItems.deletedAt)))
                 .all();
-            const existingIds = new Set(existingRows.map((r) => r.id));
-            for (const depId of dependsOn) {
-                if (!existingIds.has(depId)) {
-                    throw new Error(`Dependency #${depId} does not exist`);
+            const existingRowIds = new Set(existingRows.map((r) => r.rowId));
+            for (const depRowId of dependsOn) {
+                if (!existingRowIds.has(depRowId)) {
+                    throw new Error(`Dependency #${this.displayIdForRowId(depRowId)} does not exist`);
                 }
             }
             // Check for circular dependency chains
-            const hasCycle = (startId, targetId) => {
+            const hasCycle = (startRowId, targetRowId) => {
                 const visited = new Set();
-                const stack = [startId];
+                const stack = [startRowId];
                 while (stack.length > 0) {
                     const current = stack.pop();
-                    if (current === targetId)
+                    if (current === targetRowId)
                         return true;
                     if (visited.has(current))
                         continue;
                     visited.add(current);
                     const deps = this.db
-                        .select({ dependsOnId: schema.workItemDeps.dependsOnId })
+                        .select({
+                        dependsOnRowId: schema.workItemDeps.dependsOnRowId,
+                    })
                         .from(schema.workItemDeps)
-                        .where(eq(schema.workItemDeps.workItemId, current))
+                        .where(eq(schema.workItemDeps.workItemRowId, current))
                         .all();
                     for (const dep of deps) {
-                        stack.push(dep.dependsOnId);
+                        stack.push(dep.dependsOnRowId);
                     }
                 }
                 return false;
             };
-            for (const depId of dependsOn) {
-                if (hasCycle(depId, id)) {
-                    throw new Error(`Circular dependency chain detected for #${id}`);
+            for (const depRowId of dependsOn) {
+                if (hasCycle(depRowId, itemRowId)) {
+                    throw new Error(`Circular dependency chain detected for #${this.displayIdForRowId(itemRowId)}`);
                 }
             }
         }
     }
+    /**
+     * Get the display id for a rowId, for error messages.
+     * Returns the display id if set, otherwise the rowId as string.
+     */
+    displayIdForRowId(rowId) {
+        if (rowId === null)
+            return 'null';
+        const row = this.db
+            .select({ id: schema.workItems.id })
+            .from(schema.workItems)
+            .where(eq(schema.workItems.rowId, rowId))
+            .get();
+        return row?.id ?? String(rowId);
+    }
     // ─── Write: createWorkItem ────────────────────────────────────────
     // eslint-disable-next-line @typescript-eslint/require-await
     async createWorkItem(data) {
         this.validateFields(data);
         const now = new Date().toISOString();
-        // Single IMMEDIATE transaction: allocate ID + validate + insert atomically.
-        // IMMEDIATE acquires a write lock upfront, preventing the race condition where
-        // two processes (e.g., parallel MCP calls) read the same nextId before either
-        // commits (#37).
-        const id = this.db.transaction((tx) => {
-            // Allocate ID
-            const config = tx
-                .select()
-                .from(schema.projectConfig)
-                .where(eq(schema.projectConfig.id, 1))
-                .get();
-            const nid = config?.nextId ?? 1;
-            const itemId = this.tempIds ? `local-${nid}` : String(nid);
-            tx.update(schema.projectConfig)
-                .set({ nextId: nid + 1 })
-                .where(eq(schema.projectConfig.id, 1))
-                .run();
-            // Validate relationships
-            this.validateRelationships(itemId, data.parent, data.dependsOn);
+        // Single IMMEDIATE transaction: validate + insert atomically.
+        // IMMEDIATE acquires a write lock upfront, preventing race conditions
+        // with parallel MCP calls (#37).
+        const result = this.db.transaction((tx) => {
+            // Validate relationships (these are rowIds now)
+            this.validateRelationships(null, data.parent, data.dependsOn);
             // Ensure iteration exists
             if (data.iteration) {
                 tx.insert(schema.iterations)
@@ -498,10 +543,10 @@ export class Storage extends BaseBackend {
                     .onConflictDoNothing()
                     .run();
             }
-            // Insert work item
-            tx.insert(schema.workItems)
+            // Insert work item — let SQLite assign rowId via AUTOINCREMENT
+            const insertResult = tx
+                .insert(schema.workItems)
                 .values({
-                id: itemId,
                 title: data.title,
                 type: data.type,
                 status: data.status,
@@ -514,26 +559,36 @@ export class Storage extends BaseBackend {
                 updated: now,
             })
                 .run();
+            const rowId = Number(insertResult.lastInsertRowid);
+            // Assign display ID: if no remote backend, use rowId as display ID
+            const displayId = this._hasRemoteBackend ? null : String(rowId);
+            if (displayId !== null) {
+                tx.update(schema.workItems)
+                    .set({ id: displayId })
+                    .where(eq(schema.workItems.rowId, rowId))
+                    .run();
+            }
             // Insert labels
             if (data.labels.length > 0) {
                 tx.insert(schema.workItemLabels)
-                    .values(data.labels.map((label) => ({ workItemId: itemId, label })))
+                    .values(data.labels.map((label) => ({ workItemRowId: rowId, label })))
                     .run();
             }
             // Insert deps
             if (data.dependsOn.length > 0) {
                 tx.insert(schema.workItemDeps)
-                    .values(data.dependsOn.map((dependsOnId) => ({
-                    workItemId: itemId,
-                    dependsOnId,
+                    .values(data.dependsOn.map((dependsOnRowId) => ({
+                    workItemRowId: rowId,
+                    dependsOnRowId,
                 })))
                     .run();
             }
-            return itemId;
+            return { rowId, displayId };
         }, { behavior: 'immediate' });
         this.invalidateCache();
         return {
-            id,
+            rowId: result.rowId,
+            id: result.displayId,
             title: data.title,
             type: data.type,
             status: data.status,
@@ -552,23 +607,7 @@ export class Storage extends BaseBackend {
     // ─── Write: importWorkItem (for sync) ───────────────────────────────
     // eslint-disable-next-line @typescript-eslint/require-await
     async importWorkItem(item) {
-        this.db.transaction((tx) => {
-            // Bump nextId past imported numeric IDs to prevent collisions
-            const numericId = Number(item.id);
-            if (!Number.isNaN(numericId) && numericId > 0) {
-                const config = tx
-                    .select({ nextId: schema.projectConfig.nextId })
-                    .from(schema.projectConfig)
-                    .where(eq(schema.projectConfig.id, 1))
-                    .get();
-                const currentNext = config?.nextId ?? 1;
-                if (numericId >= currentNext) {
-                    tx.update(schema.projectConfig)
-                        .set({ nextId: numericId + 1 })
-                        .where(eq(schema.projectConfig.id, 1))
-                        .run();
-                }
-            }
+        const resultRowId = this.db.transaction((tx) => {
             // Ensure iteration exists
             if (item.iteration) {
                 tx.insert(schema.iterations)
@@ -576,24 +615,43 @@ export class Storage extends BaseBackend {
                     .onConflictDoNothing()
                     .run();
             }
-            // Upsert work item
-            tx.insert(schema.workItems)
-                .values({
-                id: item.id,
-                title: item.title,
-                type: item.type,
-                status: item.status,
-                iteration: item.iteration,
-                priority: item.priority,
-                assignee: item.assignee,
-                description: item.description,
-                parent: item.parent,
-                created: item.created,
-                updated: item.updated,
-            })
-                .onConflictDoUpdate({
-                target: schema.workItems.id,
-                set: {
+            // Resolve parent: incoming item.parent is a remote numeric ID (as number).
+            // Look up the local rowId by display ID.
+            let parentRowId = null;
+            if (item.parent !== null) {
+                const parentRow = tx
+                    .select({ rowId: schema.workItems.rowId })
+                    .from(schema.workItems)
+                    .where(eq(schema.workItems.id, String(item.parent)))
+                    .get();
+                parentRowId = parentRow?.rowId ?? null;
+            }
+            // Resolve dependsOn: same logic
+            const depRowIds = [];
+            for (const depId of item.dependsOn) {
+                const depRow = tx
+                    .select({ rowId: schema.workItems.rowId })
+                    .from(schema.workItems)
+                    .where(eq(schema.workItems.id, String(depId)))
+                    .get();
+                if (depRow) {
+                    depRowIds.push(depRow.rowId);
+                }
+            }
+            // Look up existing row by display id
+            const existing = item.id
+                ? tx
+                    .select({ rowId: schema.workItems.rowId })
+                    .from(schema.workItems)
+                    .where(eq(schema.workItems.id, item.id))
+                    .get()
+                : null;
+            let rowId;
+            if (existing) {
+                // Update existing row
+                rowId = existing.rowId;
+                tx.update(schema.workItems)
+                    .set({
                     title: item.title,
                     type: item.type,
                     status: item.status,
@@ -601,42 +659,63 @@ export class Storage extends BaseBackend {
                     priority: item.priority,
                     assignee: item.assignee,
                     description: item.description,
-                    parent: item.parent,
+                    parent: parentRowId,
                     created: item.created,
                     updated: item.updated,
-                },
-            })
-                .run();
+                })
+                    .where(eq(schema.workItems.rowId, rowId))
+                    .run();
+            }
+            else {
+                // Insert new row
+                const insertResult = tx
+                    .insert(schema.workItems)
+                    .values({
+                    id: item.id,
+                    title: item.title,
+                    type: item.type,
+                    status: item.status,
+                    iteration: item.iteration,
+                    priority: item.priority,
+                    assignee: item.assignee,
+                    description: item.description,
+                    parent: parentRowId,
+                    created: item.created,
+                    updated: item.updated,
+                })
+                    .run();
+                rowId = Number(insertResult.lastInsertRowid);
+            }
             // Replace labels
             tx.delete(schema.workItemLabels)
-                .where(eq(schema.workItemLabels.workItemId, item.id))
+                .where(eq(schema.workItemLabels.workItemRowId, rowId))
                 .run();
             if (item.labels.length > 0) {
                 tx.insert(schema.workItemLabels)
-                    .values(item.labels.map((label) => ({ workItemId: item.id, label })))
+                    .values(item.labels.map((label) => ({ workItemRowId: rowId, label })))
                     .run();
             }
             // Replace deps
             tx.delete(schema.workItemDeps)
-                .where(eq(schema.workItemDeps.workItemId, item.id))
+                .where(eq(schema.workItemDeps.workItemRowId, rowId))
                 .run();
-            if (item.dependsOn.length > 0) {
+            if (depRowIds.length > 0) {
                 tx.insert(schema.workItemDeps)
-                    .values(item.dependsOn.map((dependsOnId) => ({
-                    workItemId: item.id,
-                    dependsOnId,
+                    .values(depRowIds.map((dependsOnRowId) => ({
+                    workItemRowId: rowId,
+                    dependsOnRowId,
                 })))
                     .run();
             }
             // Replace comments
             tx.delete(schema.comments)
-                .where(eq(schema.comments.workItemId, item.id))
+                .where(eq(schema.comments.workItemRowId, rowId))
                 .run();
             if (item.comments.length > 0) {
                 for (const c of item.comments) {
                     tx.insert(schema.comments)
                         .values({
-                        workItemId: item.id,
+                        workItemRowId: rowId,
                         author: c.author,
                         body: c.body,
                         created: c.date,
@@ -644,9 +723,19 @@ export class Storage extends BaseBackend {
                         .run();
                 }
             }
+            return rowId;
         });
         this.invalidateCache();
-        return item;
+        return { ...item, rowId: resultRowId };
+    }
+    // ─── Write: setDisplayId ───────────────────────────────────────────
+    setDisplayId(rowId, displayId) {
+        this.db
+            .update(schema.workItems)
+            .set({ id: displayId })
+            .where(eq(schema.workItems.rowId, rowId))
+            .run();
+        this.invalidateCache();
     }
     // ─── Write: updateWorkItem ────────────────────────────────────────
     async updateWorkItem(id, data) {
@@ -660,11 +749,12 @@ export class Storage extends BaseBackend {
         if (!existingRow) {
             throw new Error(`Work item #${id} not found`);
         }
+        const rowId = existingRow.rowId;
         // 2. Validate relationships if parent/dependsOn changed
         const newParent = 'parent' in data ? data.parent : undefined;
         const newDepsOn = 'dependsOn' in data ? data.dependsOn : undefined;
         if (newParent !== undefined || newDepsOn !== undefined) {
-            this.validateRelationships(id, newParent !== undefined ? (newParent ?? null) : undefined, newDepsOn);
+            this.validateRelationships(rowId, newParent !== undefined ? (newParent ?? null) : undefined, newDepsOn);
         }
         const now = new Date().toISOString();
         // 3. In a transaction: update workItems row, delete+re-insert labels/deps
@@ -689,29 +779,29 @@ export class Storage extends BaseBackend {
                 updateSet['parent'] = data.parent ?? null;
             tx.update(schema.workItems)
                 .set(updateSet)
-                .where(eq(schema.workItems.id, id))
+                .where(eq(schema.workItems.rowId, rowId))
                 .run();
             // Replace labels if changed
             if ('labels' in data && data.labels !== undefined) {
                 tx.delete(schema.workItemLabels)
-                    .where(eq(schema.workItemLabels.workItemId, id))
+                    .where(eq(schema.workItemLabels.workItemRowId, rowId))
                     .run();
                 if (data.labels.length > 0) {
                     tx.insert(schema.workItemLabels)
-                        .values(data.labels.map((label) => ({ workItemId: id, label })))
+                        .values(data.labels.map((label) => ({ workItemRowId: rowId, label })))
                         .run();
                 }
             }
             // Replace deps if changed
             if ('dependsOn' in data && data.dependsOn !== undefined) {
                 tx.delete(schema.workItemDeps)
-                    .where(eq(schema.workItemDeps.workItemId, id))
+                    .where(eq(schema.workItemDeps.workItemRowId, rowId))
                     .run();
                 if (data.dependsOn.length > 0) {
                     tx.insert(schema.workItemDeps)
-                        .values(data.dependsOn.map((dependsOnId) => ({
-                        workItemId: id,
-                        dependsOnId,
+                        .values(data.dependsOn.map((dependsOnRowId) => ({
+                        workItemRowId: rowId,
+                        dependsOnRowId,
                     })))
                         .run();
                 }
@@ -734,23 +824,23 @@ export class Storage extends BaseBackend {
                     .all()
                     .slice(-1)
                     .map((r) => r.name));
-                const cascadeIteration = (parentId) => {
+                const cascadeIteration = (parentRowId) => {
                     const children = tx
                         .select()
                         .from(schema.workItems)
-                        .where(and(eq(schema.workItems.parent, parentId), isNull(schema.workItems.deletedAt)))
+                        .where(and(eq(schema.workItems.parent, parentRowId), isNull(schema.workItems.deletedAt)))
                         .all();
                     for (const child of children) {
                         if (closedStatuses.has(child.status))
                             continue;
                         tx.update(schema.workItems)
                             .set({ iteration: data.iteration, updated: now })
-                            .where(eq(schema.workItems.id, child.id))
+                            .where(eq(schema.workItems.rowId, child.rowId))
                             .run();
-                        cascadeIteration(child.id);
+                        cascadeIteration(child.rowId);
                     }
                 };
-                cascadeIteration(id);
+                cascadeIteration(rowId);
             }
         });
         this.invalidateCache();
@@ -760,18 +850,21 @@ export class Storage extends BaseBackend {
     // ─── Write: deleteWorkItem ────────────────────────────────────────
     // eslint-disable-next-line @typescript-eslint/require-await
     async deleteWorkItem(id) {
+        const rowId = this.resolveRowId(id);
         this.db.transaction((tx) => {
             // 1. Null out parent on children
             tx.update(schema.workItems)
                 .set({ parent: null })
-                .where(eq(schema.workItems.parent, id))
+                .where(eq(schema.workItems.parent, rowId))
                 .run();
             // 2. Remove deps referencing this item (other items depending on this one)
             tx.delete(schema.workItemDeps)
-                .where(eq(schema.workItemDeps.dependsOnId, id))
+                .where(eq(schema.workItemDeps.dependsOnRowId, rowId))
                 .run();
             // 3. Delete the item (cascade handles labels, deps, comments of this item)
-            tx.delete(schema.workItems).where(eq(schema.workItems.id, id)).run();
+            tx.delete(schema.workItems)
+                .where(eq(schema.workItems.rowId, rowId))
+                .run();
         });
         this.invalidateCache();
     }
@@ -779,31 +872,32 @@ export class Storage extends BaseBackend {
     // eslint-disable-next-line @typescript-eslint/require-await
     async softDeleteWorkItem(id) {
         const now = new Date().toISOString();
+        // Resolve without the deletedAt filter since this method may be called on any item
+        const row = this.db
+            .select({ rowId: schema.workItems.rowId })
+            .from(schema.workItems)
+            .where(eq(schema.workItems.id, id))
+            .get();
+        if (!row)
+            return;
         this.db
             .update(schema.workItems)
             .set({ deletedAt: now })
-            .where(eq(schema.workItems.id, id))
+            .where(eq(schema.workItems.rowId, row.rowId))
             .run();
         this.invalidateCache();
     }
     // ─── Write: addComment ────────────────────────────────────────────
     // eslint-disable-next-line @typescript-eslint/require-await
     async addComment(workItemId, comment) {
-        // 1. Verify item exists
-        const row = this.db
-            .select({ id: schema.workItems.id })
-            .from(schema.workItems)
-            .where(and(eq(schema.workItems.id, workItemId), isNull(schema.workItems.deletedAt)))
-            .get();
-        if (!row) {
-            throw new Error(`Work item #${workItemId} not found`);
-        }
+        // 1. Verify item exists and resolve rowId
+        const rowId = this.resolveRowId(workItemId);
         // 2. Insert comment (do NOT update work item's updated timestamp)
         const now = new Date().toISOString();
         this.db
             .insert(schema.comments)
             .values({
-            workItemId,
+            workItemRowId: rowId,
             author: comment.author,
             body: comment.body,
             created: now,
@@ -819,17 +913,35 @@ export class Storage extends BaseBackend {
     // ─── Write: restore (undo soft delete) ──────────────────────────
     // eslint-disable-next-line @typescript-eslint/require-await
     async restoreWorkItem(id) {
+        // Look up by display id without deletedAt filter (item is soft-deleted)
+        const row = this.db
+            .select({ rowId: schema.workItems.rowId })
+            .from(schema.workItems)
+            .where(eq(schema.workItems.id, id))
+            .get();
+        if (!row)
+            return;
         this.db
             .update(schema.workItems)
             .set({ deletedAt: null })
-            .where(eq(schema.workItems.id, id))
+            .where(eq(schema.workItems.rowId, row.rowId))
             .run();
         this.invalidateCache();
     }
     // ─── Write: permanent delete ───────────────────────────────────
     // eslint-disable-next-line @typescript-eslint/require-await
     async permanentlyDeleteWorkItem(id) {
-        this.db.delete(schema.workItems).where(eq(schema.workItems.id, id)).run();
+        const row = this.db
+            .select({ rowId: schema.workItems.rowId })
+            .from(schema.workItems)
+            .where(eq(schema.workItems.id, id))
+            .get();
+        if (!row)
+            return;
+        this.db
+            .delete(schema.workItems)
+            .where(eq(schema.workItems.rowId, row.rowId))
+            .run();
         this.invalidateCache();
     }
     // ─── Write: cleanup all soft-deleted items ─────────────────────
@@ -1084,9 +1196,9 @@ export class Storage extends BaseBackend {
         for (const link of linkRows) {
             const arr = linksByPr.get(link.prId);
             if (arr)
-                arr.push(link.itemId);
+                arr.push(link.itemRowId);
             else
-                linksByPr.set(link.prId, [link.itemId]);
+                linksByPr.set(link.prId, [link.itemRowId]);
         }
         return prRows.map((row) => rowToPullRequest(row, linksByPr.get(row.id) ?? []));
     }
@@ -1104,7 +1216,7 @@ export class Storage extends BaseBackend {
             .from(schema.prItemLinks)
             .where(eq(schema.prItemLinks.prId, id))
             .all();
-        return rowToPullRequest(row, linkRows.map((l) => l.itemId));
+        return rowToPullRequest(row, linkRows.map((l) => l.itemRowId));
     }
     // eslint-disable-next-line @typescript-eslint/require-await
     async importPullRequest(pr) {
@@ -1146,17 +1258,18 @@ export class Storage extends BaseBackend {
                 .run();
             if (pr.linkedItems.length > 0) {
                 tx.insert(schema.prItemLinks)
-                    .values(pr.linkedItems.map((itemId) => ({ prId: pr.id, itemId })))
+                    .values(pr.linkedItems.map((itemRowId) => ({ prId: pr.id, itemRowId })))
                     .run();
             }
         });
     }
     // eslint-disable-next-line @typescript-eslint/require-await
     async getLinkedPullRequests(itemId) {
+        const itemRowId = this.resolveRowId(itemId);
         const linkRows = this.db
             .select({ prId: schema.prItemLinks.prId })
             .from(schema.prItemLinks)
-            .where(eq(schema.prItemLinks.itemId, itemId))
+            .where(eq(schema.prItemLinks.itemRowId, itemRowId))
             .all();
         if (linkRows.length === 0)
             return [];
@@ -1178,34 +1291,42 @@ export class Storage extends BaseBackend {
         for (const link of allLinks) {
             const arr = linksByPr.get(link.prId);
             if (arr)
-                arr.push(link.itemId);
+                arr.push(link.itemRowId);
             else
-                linksByPr.set(link.prId, [link.itemId]);
+                linksByPr.set(link.prId, [link.itemRowId]);
         }
         return prRows.map((row) => rowToPullRequest(row, linksByPr.get(row.id) ?? []));
     }
     // eslint-disable-next-line @typescript-eslint/require-await
     async getLinkedItems(prId) {
         const rows = this.db
-            .select({ itemId: schema.prItemLinks.itemId })
+            .select({
+            itemRowId: schema.prItemLinks.itemRowId,
+            itemId: schema.workItems.id,
+        })
             .from(schema.prItemLinks)
+            .innerJoin(schema.workItems, eq(schema.prItemLinks.itemRowId, schema.workItems.rowId))
             .where(eq(schema.prItemLinks.prId, prId))
             .all();
-        return rows.map((r) => r.itemId);
+        return rows
+            .map((r) => r.itemId ?? String(r.itemRowId))
+            .filter((id) => id.length > 0);
     }
     // eslint-disable-next-line @typescript-eslint/require-await
     async linkItem(prId, itemId) {
+        const itemRowId = this.resolveRowId(itemId);
         this.db
             .insert(schema.prItemLinks)
-            .values({ prId, itemId })
+            .values({ prId, itemRowId })
             .onConflictDoNothing()
             .run();
     }
     // eslint-disable-next-line @typescript-eslint/require-await
     async unlinkItem(prId, itemId) {
+        const itemRowId = this.resolveRowId(itemId);
         this.db
             .delete(schema.prItemLinks)
-            .where(and(eq(schema.prItemLinks.prId, prId), eq(schema.prItemLinks.itemId, itemId)))
+            .where(and(eq(schema.prItemLinks.prId, prId), eq(schema.prItemLinks.itemRowId, itemRowId)))
             .run();
     }
     // eslint-disable-next-line @typescript-eslint/no-unused-vars, @typescript-eslint/require-await