feat(daemon): persist team-collab comment anchor state

Storage layer for the read-only comment drift ladder (C lane, spec D2),
building on the contract from #5222.

- preview_comments gains anchor_state / anchored_version / author_member_id /
  last_good_position_json. The migration runs after the slide-key table rebuild
  so a legacy rebuild cannot drop the new columns.
- upsert persists creation metadata (anchoredVersion, authorMemberId); resolved
  state stays null for the drift ladder to fill in.
- updatePreviewCommentAnchor is the engine write-back: COALESCE keeps the
  last-good position/version on a lost resolve, and it never bumps updated_at.
- contract: anchoredVersion on PreviewCommentTarget, authorMemberId on the upsert
  request (server-set), and PreviewCommentAnchorUpdateRequest.

Tests cover fresh-db columns, creation round-trip, engine write-back with
lost-keeps-last-good, and legacy-migration backfill.

Author: lefarcen

apps/daemon/src/db.ts

@@ -156,6 +156,10 @@ function migrate(db: SqliteDb): void {
       status TEXT NOT NULL,
       created_at INTEGER NOT NULL,
       updated_at INTEGER NOT NULL,
+      anchor_state TEXT,
+      anchored_version INTEGER,
+      author_member_id TEXT,
+      last_good_position_json TEXT,
       UNIQUE(project_id, conversation_id, file_path, element_id, slide_key),
       FOREIGN KEY(project_id) REFERENCES projects(id) ON DELETE CASCADE,
       FOREIGN KEY(conversation_id) REFERENCES conversations(id) ON DELETE CASCADE
@@ -329,6 +333,21 @@ function migrate(db: SqliteDb): void {
     db.exec(`ALTER TABLE preview_comments ADD COLUMN slide_index INTEGER`);
   }
   migratePreviewCommentsSlideKey(db);
+  // Team-collab anchor columns — added after the slide-key rebuild so a legacy
+  // table rebuild cannot drop them.
+  const previewCommentAnchorCols = db.prepare(`PRAGMA table_info(preview_comments)`).all() as DbRow[];
+  if (!previewCommentAnchorCols.some((c: DbRow) => c.name === 'anchor_state')) {
+    db.exec(`ALTER TABLE preview_comments ADD COLUMN anchor_state TEXT`);
+  }
+  if (!previewCommentAnchorCols.some((c: DbRow) => c.name === 'anchored_version')) {
+    db.exec(`ALTER TABLE preview_comments ADD COLUMN anchored_version INTEGER`);
+  }
+  if (!previewCommentAnchorCols.some((c: DbRow) => c.name === 'author_member_id')) {
+    db.exec(`ALTER TABLE preview_comments ADD COLUMN author_member_id TEXT`);
+  }
+  if (!previewCommentAnchorCols.some((c: DbRow) => c.name === 'last_good_position_json')) {
+    db.exec(`ALTER TABLE preview_comments ADD COLUMN last_good_position_json TEXT`);
+  }
   const deploymentCols = db.prepare(`PRAGMA table_info(deployments)`).all() as DbRow[];
   if (!deploymentCols.some((c: DbRow) => c.name === 'status')) {
     db.exec(`ALTER TABLE deployments ADD COLUMN status TEXT NOT NULL DEFAULT 'ready'`);
@@ -1610,6 +1629,8 @@ export function listPreviewComments(db: SqliteDb, projectId: string, conversatio
               pod_members_json AS podMembersJson, style_json AS styleJson,
               attachments_json AS attachmentsJson,
               slide_index AS slideIndex,
+              anchor_state AS anchorState, anchored_version AS anchoredVersion,
+              author_member_id AS authorMemberId, last_good_position_json AS lastGoodPositionJson,
               note, status, created_at AS createdAt, updated_at AS updatedAt
          FROM preview_comments
         WHERE project_id = ? AND conversation_id = ?
@@ -1643,6 +1664,15 @@ export function upsertPreviewComment(db: SqliteDb, projectId: string, conversati
     : 0;
   const slideIndex = Number.isFinite(target.slideIndex) ? Math.max(0, Math.round(target.slideIndex)) : null;
   const slideKey = slideIndex ?? -1;
+  // Team-collab creation metadata. anchor_state / last_good_position stay null at
+  // creation — the drift ladder resolves and writes them back (updatePreviewCommentAnchor).
+  const anchoredVersion = Number.isFinite(target.anchoredVersion)
+    ? Math.max(0, Math.round(target.anchoredVersion))
+    : null;
+  const authorMemberId =
+    typeof input?.authorMemberId === 'string' && input.authorMemberId.trim()
+      ? input.authorMemberId.trim()
+      : null;
   const now = Date.now();
   const existing = db
     .prepare(
@@ -1661,8 +1691,9 @@ export function upsertPreviewComment(db: SqliteDb, projectId: string, conversati
     `INSERT INTO preview_comments
        (id, project_id, conversation_id, file_path, element_id, selector, label,
         text, position_json, html_hint, selection_kind, member_count, pod_members_json,
-        style_json, attachments_json, slide_index, slide_key, note, status, created_at, updated_at)
-     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+        style_json, attachments_json, slide_index, slide_key, note, status, created_at, updated_at,
+        anchored_version, author_member_id)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
      ON CONFLICT(project_id, conversation_id, file_path, element_id, slide_key) DO UPDATE SET
        selector = excluded.selector,
        label = excluded.label,
@@ -1677,6 +1708,8 @@ export function upsertPreviewComment(db: SqliteDb, projectId: string, conversati
        slide_index = excluded.slide_index,
        note = excluded.note,
        status = 'open',
+       anchored_version = excluded.anchored_version,
+       author_member_id = excluded.author_member_id,
        updated_at = excluded.updated_at`,
   ).run(
     id,
@@ -1700,6 +1733,8 @@ export function upsertPreviewComment(db: SqliteDb, projectId: string, conversati
     'open',
     createdAt,
     now,
+    anchoredVersion,
+    authorMemberId,
   );
   return getPreviewComment(db, projectId, conversationId, id);
 }
@@ -1715,6 +1750,41 @@ export function updatePreviewCommentStatus(db: SqliteDb, projectId: string, conv
   return getPreviewComment(db, projectId, conversationId, id);
 }
 
+/**
+ * Team-collab drift-ladder write-back: persist how a comment resolved this render.
+ * `lastGoodPosition`/`anchoredVersion` are COALESCEd so a `lost` resolve (which omits
+ * them) keeps the last known-good values instead of wiping them. Does not bump
+ * `updated_at` — anchor resolution is a derived read, not a content edit.
+ */
+export function updatePreviewCommentAnchor(
+  db: SqliteDb,
+  projectId: string,
+  conversationId: string,
+  id: string,
+  input: DbRow,
+) {
+  const anchorState = typeof input?.anchorState === 'string' ? input.anchorState : null;
+  const lastGoodPosition = input?.lastGoodPosition ? normalizePosition(input.lastGoodPosition) : null;
+  const anchoredVersion = Number.isFinite(input?.anchoredVersion)
+    ? Math.max(0, Math.round(input.anchoredVersion))
+    : null;
+  db.prepare(
+    `UPDATE preview_comments
+        SET anchor_state = ?,
+            last_good_position_json = COALESCE(?, last_good_position_json),
+            anchored_version = COALESCE(?, anchored_version)
+      WHERE id = ? AND project_id = ? AND conversation_id = ?`,
+  ).run(
+    anchorState,
+    lastGoodPosition ? JSON.stringify(lastGoodPosition) : null,
+    anchoredVersion,
+    id,
+    projectId,
+    conversationId,
+  );
+  return getPreviewComment(db, projectId, conversationId, id);
+}
+
 export function deletePreviewComment(db: SqliteDb, projectId: string, conversationId: string, id: string) {
   const result = db
     .prepare(
@@ -1735,6 +1805,8 @@ function getPreviewComment(db: SqliteDb, projectId: string, conversationId: stri
               pod_members_json AS podMembersJson, style_json AS styleJson,
               attachments_json AS attachmentsJson,
               slide_index AS slideIndex,
+              anchor_state AS anchorState, anchored_version AS anchoredVersion,
+              author_member_id AS authorMemberId, last_good_position_json AS lastGoodPositionJson,
               note, status, created_at AS createdAt, updated_at AS updatedAt
          FROM preview_comments
         WHERE id = ? AND project_id = ? AND conversation_id = ?`,
@@ -1772,6 +1844,10 @@ function normalizePreviewComment(row: DbRow) {
     status: row.status,
     createdAt: row.createdAt,
     updatedAt: row.updatedAt,
+    anchorState: typeof row.anchorState === 'string' ? row.anchorState : undefined,
+    anchoredVersion: Number.isFinite(row.anchoredVersion) ? row.anchoredVersion : undefined,
+    authorMemberId: typeof row.authorMemberId === 'string' ? row.authorMemberId : undefined,
+    lastGoodPosition: parseJsonOrUndef(row.lastGoodPositionJson),
   };
 }
 

apps/daemon/tests/comment-attachments.test.ts

@@ -13,6 +13,7 @@ import {
   listMessages,
   listPreviewComments,
   openDatabase,
+  updatePreviewCommentAnchor,
   updatePreviewCommentStatus,
   upsertMessage,
   upsertPreviewComment,
@@ -57,6 +58,67 @@ describe('preview comment persistence', () => {
     expect(critiqueTable?.name).toBe('critique_runs');
   });
 
+  it('adds the team-collab anchor columns on a fresh database', () => {
+    tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'od-comments-'));
+    const db = openDatabase(tempDir);
+    expect(tableColumnNames(db.prepare(`PRAGMA table_info(preview_comments)`).all())).toEqual(
+      expect.arrayContaining([
+        'anchor_state',
+        'anchored_version',
+        'author_member_id',
+        'last_good_position_json',
+      ]),
+    );
+  });
+
+  it('round-trips team-collab anchor creation metadata and defers resolved state', () => {
+    const db = seededDb();
+    const saved = upsertPreviewComment(db, 'project-1', 'conversation-1', {
+      target: target({ elementId: 'hero-title', anchoredVersion: 7 }),
+      note: 'Anchor me',
+      authorMemberId: 'member-42',
+    });
+    if (!saved) throw new Error('comment upsert failed');
+    // Creation metadata persists...
+    expect(saved.anchoredVersion).toBe(7);
+    expect(saved.authorMemberId).toBe('member-42');
+    // ...while the resolved state is left for the drift ladder to fill in.
+    expect(saved.anchorState).toBeUndefined();
+    expect(saved.lastGoodPosition).toBeUndefined();
+    // Survives the re-fetch (the list read path).
+    const [listed] = listPreviewComments(db, 'project-1', 'conversation-1');
+    expect(listed?.anchoredVersion).toBe(7);
+    expect(listed?.authorMemberId).toBe('member-42');
+  });
+
+  it('writes back resolved anchor state and keeps last-good position on a lost resolve', () => {
+    const db = seededDb();
+    const saved = upsertPreviewComment(db, 'project-1', 'conversation-1', {
+      target: target({ elementId: 'hero-title' }),
+      note: 'Anchor me',
+    });
+    if (!saved) throw new Error('comment upsert failed');
+
+    // Engine resolves it (anchored) and writes back a known-good position.
+    const good = { x: 5, y: 15, width: 120, height: 40 };
+    const anchored = updatePreviewCommentAnchor(db, 'project-1', 'conversation-1', saved.id, {
+      anchorState: 'anchored',
+      lastGoodPosition: good,
+      anchoredVersion: 3,
+    });
+    expect(anchored?.anchorState).toBe('anchored');
+    expect(anchored?.lastGoodPosition).toEqual(good);
+    expect(anchored?.anchoredVersion).toBe(3);
+
+    // Later the element vanishes → 'lost' with no new position. Last-good must survive.
+    const lost = updatePreviewCommentAnchor(db, 'project-1', 'conversation-1', saved.id, {
+      anchorState: 'lost',
+    });
+    expect(lost?.anchorState).toBe('lost');
+    expect(lost?.lastGoodPosition).toEqual(good); // COALESCE preserved it
+    expect(lost?.anchoredVersion).toBe(3); // COALESCE preserved it
+  });
+
   it('upserts the latest comment by conversation, file, and element', () => {
     const db = seededDb();
     const first = upsertPreviewComment(db, 'project-1', 'conversation-1', {
@@ -275,6 +337,16 @@ describe('preview comment persistence', () => {
     expect(table?.sql).toMatch(/slide_key INTEGER NOT NULL DEFAULT -1/);
     expect(table?.sql).toMatch(/UNIQUE\(project_id, conversation_id, file_path, element_id, slide_key\)/);
     expect(listPreviewComments(db, 'project-1', 'conversation-1')[0]?.slideIndex).toBe(0);
+    // Anchor columns are backfilled even though the table was rebuilt for the
+    // slide-key migration (the ALTERs run after the rebuild).
+    expect(tableColumnNames(db.prepare(`PRAGMA table_info(preview_comments)`).all())).toEqual(
+      expect.arrayContaining([
+        'anchor_state',
+        'anchored_version',
+        'author_member_id',
+        'last_good_position_json',
+      ]),
+    );
 
     const secondSlide = upsertPreviewComment(db, 'project-1', 'conversation-1', {
       target: target({ elementId: 'hero-title', slideIndex: 1, text: 'Slide two title' }),

packages/contracts/src/api/comments.ts

@@ -84,6 +84,12 @@ export interface PreviewCommentTarget {
   podMembers?: PreviewCommentMember[];
   /** Zero-based deck slide index when the comment was placed. */
   slideIndex?: number;
+  /**
+   * Team-collab: content version this anchor was captured against. Persisted as
+   * {@link PreviewComment.anchoredVersion}; drives the drift ladder's
+   * "based on older vN" badge.
+   */
+  anchoredVersion?: number;
 }
 
 export interface PreviewComment {
@@ -130,6 +136,24 @@ export interface PreviewCommentUpsertRequest {
   target: PreviewCommentTarget;
   note: string;
   attachments?: PreviewCommentAttachment[];
+  /**
+   * Team-collab: comment author's workspaceMemberId. Server-set from the request
+   * identity (B token → member context); clients do not supply it.
+   */
+  authorMemberId?: string;
+}
+
+/**
+ * Team-collab: drift-ladder write-back. The anchoring engine reports where a
+ * comment resolved this render so the resolved state persists across sessions
+ * (see {@link PreviewCommentAnchorState}).
+ */
+export interface PreviewCommentAnchorUpdateRequest {
+  anchorState: PreviewCommentAnchorState;
+  /** Written back on a successful (anchored/reanchored) resolve; the `lost` ghost pin renders here. */
+  lastGoodPosition?: PreviewCommentPosition;
+  /** Optional: refresh the anchored content version. */
+  anchoredVersion?: number;
 }
 
 export interface PreviewCommentStatusRequest {