@taskforcehq/taskforce 0.3.326 → 0.3.328

package/dist/core/planningReferencePolicy.d.ts

@@ -0,0 +1,14 @@
+import type { DatabaseAdapter } from '../storage/databaseAdapter.js';
+export type PlanningReferenceTable = 'initiatives' | 'workstreams';
+export type PlanningReferenceSequenceTable = 'workspace_initiative_reference_sequences' | 'workspace_workstream_reference_sequences';
+export declare function reservePlanningReferenceNumber(input: {
+    db: DatabaseAdapter;
+    tenantId: string;
+    workspaceId: string;
+    preferredReferenceNumber?: number | null;
+    tableName: PlanningReferenceTable;
+    sequenceTableName: PlanningReferenceSequenceTable;
+    normalizeWorkspaceId: (workspaceId: string) => string;
+    sanitizeReferenceNumber: (value: unknown) => number | null;
+    allocationFailed: () => never;
+}): number;

package/dist/core/planningReferencePolicy.js

@@ -0,0 +1,53 @@
+export function reservePlanningReferenceNumber(input) {
+    const workspaceId = input.normalizeWorkspaceId(input.workspaceId);
+    const preferred = input.sanitizeReferenceNumber(input.preferredReferenceNumber);
+    if (preferred) {
+        const existing = input.db.prepare(`
+            SELECT id
+            FROM ${input.tableName}
+            WHERE tenant_id = ? AND workspace_id = ? AND reference_number = ?
+            LIMIT 1
+        `).get(input.tenantId, workspaceId, preferred);
+        if (!existing?.id) {
+            input.db.prepare(`
+                INSERT INTO ${input.sequenceTableName} (tenant_id, workspace_id, next_reference_number)
+                VALUES (?, ?, ?)
+                ON CONFLICT (tenant_id, workspace_id) DO UPDATE SET
+                    next_reference_number = CASE
+                        WHEN ${input.sequenceTableName}.next_reference_number < EXCLUDED.next_reference_number
+                            THEN EXCLUDED.next_reference_number
+                        ELSE ${input.sequenceTableName}.next_reference_number
+                    END
+            `).run(input.tenantId, workspaceId, preferred);
+            return preferred;
+        }
+    }
+    const row = input.db.prepare(`
+        INSERT INTO ${input.sequenceTableName} (tenant_id, workspace_id, next_reference_number)
+        VALUES (
+            ?,
+            ?,
+            (
+                SELECT COALESCE(MAX(reference_number), 0) + 1
+                FROM ${input.tableName}
+                WHERE tenant_id = ? AND workspace_id = ?
+            )
+        )
+        ON CONFLICT (tenant_id, workspace_id) DO UPDATE SET
+            next_reference_number = CASE
+                WHEN ${input.sequenceTableName}.next_reference_number > (
+                    SELECT COALESCE(MAX(reference_number), 0)
+                    FROM ${input.tableName}
+                    WHERE tenant_id = ? AND workspace_id = ?
+                ) THEN ${input.sequenceTableName}.next_reference_number + 1
+                ELSE (
+                    SELECT COALESCE(MAX(reference_number), 0) + 1
+                    FROM ${input.tableName}
+                    WHERE tenant_id = ? AND workspace_id = ?
+                )
+            END
+        RETURNING next_reference_number
+    `).get(input.tenantId, workspaceId, input.tenantId, workspaceId, input.tenantId, workspaceId, input.tenantId, workspaceId);
+    const referenceNumber = input.sanitizeReferenceNumber(row?.next_reference_number);
+    return referenceNumber || input.allocationFailed();
+}

package/dist/core/taskReferencePolicy.js

@@ -85,9 +85,30 @@ export function persistLocalTaskReferenceSequence(deps, workspaceId, referenceNu
 }
 export function allocateNextTaskReferenceNumber(deps, workspaceId, excludeTaskId) {
     const normalizedWorkspaceId = deps.normalizeWorkspaceId(workspaceId);
-    const nextReferenceNumber = Math.max(getTaskReferenceSequenceValue(deps, normalizedWorkspaceId), getMaxTaskReferenceNumber(deps, normalizedWorkspaceId, excludeTaskId)) + 1;
-    persistTaskReferenceSequence(deps, normalizedWorkspaceId, nextReferenceNumber);
-    return nextReferenceNumber;
+    const normalizedExcludeTaskId = String(excludeTaskId || '').trim();
+    const maxReferenceSql = normalizedExcludeTaskId
+        ? `SELECT COALESCE(MAX(reference_number), 0) FROM tasks
+           WHERE tenant_id = ? AND workspace_id = ? AND id != ?`
+        : `SELECT COALESCE(MAX(reference_number), 0) FROM tasks
+           WHERE tenant_id = ? AND workspace_id = ?`;
+    const maxReferenceParams = normalizedExcludeTaskId
+        ? [deps.tenantId, normalizedWorkspaceId, normalizedExcludeTaskId]
+        : [deps.tenantId, normalizedWorkspaceId];
+    const row = deps.db.prepare(`
+        INSERT INTO workspace_task_reference_sequences (tenant_id, workspace_id, next_reference_number)
+        VALUES (?, ?, ((${maxReferenceSql}) + 1))
+        ON CONFLICT (tenant_id, workspace_id) DO UPDATE SET
+            next_reference_number = CASE
+                WHEN workspace_task_reference_sequences.next_reference_number >= (${maxReferenceSql})
+                    THEN workspace_task_reference_sequences.next_reference_number + 1
+                ELSE (${maxReferenceSql}) + 1
+            END
+        RETURNING next_reference_number
+    `).get(deps.tenantId, normalizedWorkspaceId, ...maxReferenceParams, ...maxReferenceParams, ...maxReferenceParams);
+    const referenceNumber = deps.sanitizeTaskReferenceNumber(row?.next_reference_number);
+    if (!referenceNumber)
+        throw new Error('Failed to allocate task reference number.');
+    return referenceNumber;
 }
 export function allocateNextLocalTaskReferenceNumber(deps, workspaceId, excludeTaskId) {
     const normalizedWorkspaceId = deps.normalizeWorkspaceId(workspaceId);

package/dist/core/types.d.ts

@@ -36,7 +36,6 @@ export interface TaskItem {
     priority: number;
     complexity: number;
     status: TaskStatus;
-    approach?: string;
     createdAt: string;
     updatedAt?: string;
     completedAt?: string | null;
@@ -56,6 +55,7 @@ export interface TaskItem {
         referenceLabel?: string;
         taskId?: string | null;
         timestamp?: string;
+        linkRole?: 'attachment' | 'image' | 'reference';
     }>;
     /** @deprecated */
     completed?: boolean;
@@ -64,7 +64,7 @@ export interface TaskItem {
     taxonomies?: Record<string, string | string[]>;
     createdBy?: string;
     assignee?: TaskAssignee;
-    canceledReason?: string;
+    canceledReason?: string | null;
     isArchived?: boolean;
     isDeleted?: boolean;
     deletedRecordId?: string | null;
@@ -72,6 +72,8 @@ export interface TaskItem {
     dueDate?: string | null;
     scheduledWeekKey?: string | null;
     orderInDay?: number | null;
+    workstreamOrder?: number | null;
+    workstreamId?: string | null;
 }
 export interface TaskWarning {
     code: string;
@@ -102,7 +104,7 @@ export interface ScheduleBoardResult {
         }>;
     };
 }
-export type RealtimeMutationEntityType = 'task' | 'taxonomy' | 'document-metadata';
+export type RealtimeMutationEntityType = 'task' | 'initiative' | 'workstream' | 'taxonomy' | 'document-metadata';
 export interface RealtimeMutationEvent {
     eventId: string;
     workspaceId: string;
@@ -112,6 +114,8 @@ export interface RealtimeMutationEvent {
     entityType: RealtimeMutationEntityType;
     changeType: string;
     entityIds: string[];
+    affectedCollections?: Array<'active' | 'archive' | 'deleted' | 'planning'>;
+    lifecycleTransition?: string;
     dataVersion: number;
     serverTs: string;
 }
@@ -137,6 +141,7 @@ export interface TaskforceConfig {
     storagePath?: string;
     tenantId?: string;
     runtimeMode?: RuntimeMode;
+    initializationMode?: 'standard' | 'cloud-read-worker';
     database?: {
         provider?: DatabaseProvider;
         connectionString?: string;
@@ -166,12 +171,6 @@ export interface TaskFile {
             color?: string;
             icon?: string;
         }>;
-        approaches?: Array<{
-            value: string;
-            label: string;
-            color?: string;
-            icon?: string;
-        }>;
         theme?: TaskforceTheme;
         shortcut?: string;
         jsonBackupEnabled?: boolean;
@@ -223,7 +222,6 @@ export interface InitiativeTemplateMilestone {
     title: string;
     description: string;
     priority?: number;
-    approach?: string;
     category?: string;
 }
 export interface InitiativeTemplate {
@@ -371,7 +369,7 @@ export interface InviteAcceptanceDetails {
     passwordRequired?: boolean;
 }
 export type McpAccessTokenStatus = 'active' | 'revoked' | 'expired';
-export type McpOAuthProvider = 'chatgpt' | 'claude';
+export type McpOAuthProvider = 'chatgpt' | 'claude' | 'grok' | 'gemini' | 'mistral' | 'perplexity';
 export type McpOAuthClientStatus = 'active' | 'revoked';
 export type McpOAuthGrantStatus = 'active' | 'revoked';
 export interface UserAccessRecord {
@@ -651,6 +649,7 @@ export interface McpOAuthClientRecord {
     id: string;
     provider: McpOAuthProvider;
     clientName: string;
+    productClientId?: string | null;
     redirectUris: string[];
     status: McpOAuthClientStatus;
     createdAt: string;
@@ -661,6 +660,7 @@ export interface McpOAuthConnectorGrantRecord {
     provider: McpOAuthProvider;
     clientId: string;
     clientName: string;
+    productClientId?: string | null;
     workspaceId: string;
     userId: string;
     scopes: McpAccessTokenScope[];
@@ -684,6 +684,7 @@ export interface McpOAuthAccessTokenAuthResult {
     userId: string;
     clientId: string;
     provider: McpOAuthProvider;
+    productClientId?: string | null;
     scopes: McpAccessTokenScope[];
     status: McpOAuthGrantStatus;
     aiProfileId?: string | null;

package/dist/documentReviews/DocumentReviewCommentStore.d.ts

@@ -1,5 +1,5 @@
 import type { DatabaseAdapter } from '../storage/databaseAdapter.js';
-import type { DocumentReviewAnchor, DocumentReviewCommentRecord, DocumentReviewCommentSyncRecord } from './types.js';
+import type { DocumentReviewAnchor, DocumentReviewCommentRecord, DocumentReviewCommentSyncRecord, DocumentReviewThreadStatus } from './types.js';
 export declare class DocumentReviewCommentStore {
     private readonly db;
     private readonly tenantId;
@@ -18,10 +18,28 @@ export declare class DocumentReviewCommentStore {
         anchor?: DocumentReviewAnchor | null;
         order: number;
         authorActorId?: string | null;
+        updatedByActorId?: string | null;
+        deletedByActorId?: string | null;
         createdAt?: string;
         updatedAt?: string;
         deletedAt?: string | null;
+        parentCommentId?: string | null;
+        threadStatus?: DocumentReviewThreadStatus | null;
+        threadStatusUpdatedAt?: string | null;
+        resolvedAt?: string | null;
+        resolvedByActorId?: string | null;
+        idempotencyKey?: string | null;
+        idempotencyFingerprint?: string | null;
+        idempotencyActorScope?: string | null;
     }): DocumentReviewCommentSyncRecord;
+    getByIdempotencyKey(input: {
+        workspaceId: string;
+        actorScope: string;
+        idempotencyKey: string;
+    }): {
+        comment: DocumentReviewCommentSyncRecord;
+        fingerprint: string;
+    } | null;
     get(commentIdRaw: string, workspaceIdRaw: string, options?: {
         includeDeleted?: boolean;
     }): DocumentReviewCommentSyncRecord | null;
@@ -32,8 +50,14 @@ export declare class DocumentReviewCommentStore {
         anchor?: DocumentReviewAnchor | null;
         order?: number;
         authorActorId?: string | null;
+        updatedByActorId?: string | null;
+        deletedByActorId?: string | null;
         updatedAt?: string;
         deletedAt?: string | null;
+        threadStatus?: DocumentReviewThreadStatus;
+        threadStatusUpdatedAt?: string;
+        resolvedAt?: string | null;
+        resolvedByActorId?: string | null;
     }): DocumentReviewCommentSyncRecord | null;
     upsertForSync(input: {
         id: string;
@@ -43,11 +67,18 @@ export declare class DocumentReviewCommentStore {
         anchor?: DocumentReviewAnchor | null;
         order: number;
         authorActorId?: string | null;
+        updatedByActorId?: string | null;
+        deletedByActorId?: string | null;
         createdAt?: string;
         updatedAt?: string;
         deletedAt?: string | null;
+        parentCommentId?: string | null;
+        threadStatus?: DocumentReviewThreadStatus | null;
+        threadStatusUpdatedAt?: string | null;
+        resolvedAt?: string | null;
+        resolvedByActorId?: string | null;
     }): DocumentReviewCommentSyncRecord;
-    softDelete(commentIdRaw: string, workspaceIdRaw: string, deletedAtRaw?: string): boolean;
+    softDelete(commentIdRaw: string, workspaceIdRaw: string, deletedAtRaw?: string, deletedByActorIdRaw?: string | null): boolean;
     replaceForSession(input: {
         sessionId: string;
         workspaceId: string;

package/dist/documentReviews/DocumentReviewCommentStore.js

@@ -27,9 +27,18 @@ function normalizeAnchor(raw) {
         const quote = String(record.quote || '').trim();
         if (!quote)
             return null;
+        const occurrenceIndex = record.occurrenceIndex === undefined || record.occurrenceIndex === null
+            ? null
+            : normalizePositiveInteger(record.occurrenceIndex);
         const prefix = normalizeNullable(record.prefix);
         const suffix = normalizeNullable(record.suffix);
-        return { kind: 'quote', quote, prefix, suffix };
+        return {
+            kind: 'quote',
+            quote,
+            ...(occurrenceIndex == null ? {} : { occurrenceIndex }),
+            prefix,
+            suffix,
+        };
     }
     if (kind === 'line-range') {
         const startLine = normalizePositiveInteger(record.startLine);
@@ -52,6 +61,13 @@ function mapRow(row) {
         tenantId: normalizeId(row.tenant_id) || 'default',
         workspaceId: normalizeWorkspaceId(row.workspace_id),
         sessionId: normalizeId(row.session_id),
+        parentCommentId: normalizeNullable(row.parent_comment_id),
+        threadStatus: normalizeNullable(row.parent_comment_id)
+            ? null
+            : (normalizeId(row.thread_status) === 'resolved' ? 'resolved' : 'open'),
+        threadStatusUpdatedAt: normalizeNullable(row.thread_status_updated_at),
+        resolvedAt: normalizeNullable(row.resolved_at),
+        resolvedByActorId: normalizeNullable(row.resolved_by_actor_id),
         order: normalizePositiveInteger(row.order_index) ?? 0,
         body: normalizeId(row.body),
         anchor: (() => {
@@ -66,6 +82,8 @@ function mapRow(row) {
             }
         })(),
         authorActorId: normalizeNullable(row.author_actor_id),
+        updatedByActorId: normalizeNullable(row.updated_by_actor_id),
+        deletedByActorId: normalizeNullable(row.deleted_by_actor_id),
         createdAt,
         updatedAt,
         deletedAt: normalizeNullable(row.deleted_at),
@@ -114,6 +132,7 @@ export class DocumentReviewCommentStore {
         const workspaceId = normalizeWorkspaceId(input.workspaceId);
         const createdAt = normalizeId(input.createdAt) || new Date().toISOString();
         const updatedAt = normalizeId(input.updatedAt) || createdAt;
+        const parentCommentId = normalizeNullable(input.parentCommentId);
         this.db.prepare(`
             INSERT INTO document_review_comments (
                 id,
@@ -123,14 +142,56 @@ export class DocumentReviewCommentStore {
                 body,
                 anchor_json,
                 author_actor_id,
+                updated_by_actor_id,
+                deleted_by_actor_id,
+                parent_comment_id,
+                thread_status,
+                thread_status_updated_at,
+                resolved_at,
+                resolved_by_actor_id,
+                idempotency_key,
+                idempotency_fingerprint,
+                idempotency_actor_scope,
                 order_index,
                 created_at,
                 updated_at,
                 deleted_at
-            ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
-        `).run(id, sessionId, this.tenantId, workspaceId, normalizeId(input.body), input.anchor ? JSON.stringify(input.anchor) : null, normalizeNullable(input.authorActorId), normalizePositiveInteger(input.order) ?? 0, createdAt, updatedAt, normalizeNullable(input.deletedAt));
+            ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+            ${normalizeNullable(input.idempotencyKey)
+            ? 'ON CONFLICT (tenant_id, workspace_id, idempotency_actor_scope, idempotency_key) DO NOTHING'
+            : ''}
+        `).run(id, sessionId, this.tenantId, workspaceId, normalizeId(input.body), input.anchor ? JSON.stringify(input.anchor) : null, normalizeNullable(input.authorActorId), normalizeNullable(input.updatedByActorId ?? input.authorActorId), normalizeNullable(input.deletedByActorId), parentCommentId, parentCommentId
+            ? null
+            : (input.threadStatus === 'resolved' ? 'resolved' : 'open'), parentCommentId ? null : (normalizeNullable(input.threadStatusUpdatedAt) || updatedAt), parentCommentId ? null : normalizeNullable(input.resolvedAt), parentCommentId ? null : normalizeNullable(input.resolvedByActorId), normalizeNullable(input.idempotencyKey), normalizeNullable(input.idempotencyFingerprint), normalizeId(input.idempotencyActorScope), normalizePositiveInteger(input.order) ?? 0, createdAt, updatedAt, normalizeNullable(input.deletedAt));
+        if (normalizeNullable(input.idempotencyKey)) {
+            const replay = this.getByIdempotencyKey({
+                workspaceId,
+                actorScope: normalizeId(input.idempotencyActorScope),
+                idempotencyKey: normalizeId(input.idempotencyKey),
+            });
+            if (replay)
+                return replay.comment;
+        }
         return this.get(id, workspaceId, { includeDeleted: true });
     }
+    getByIdempotencyKey(input) {
+        const workspaceId = normalizeWorkspaceId(input.workspaceId);
+        const row = this.db.prepare(`
+            SELECT *
+            FROM document_review_comments
+            WHERE tenant_id = ?
+              AND workspace_id = ?
+              AND idempotency_actor_scope = ?
+              AND idempotency_key = ?
+            LIMIT 1
+        `).get(this.tenantId, workspaceId, normalizeId(input.actorScope), normalizeId(input.idempotencyKey));
+        if (!row)
+            return null;
+        return {
+            comment: mapRow(row),
+            fingerprint: normalizeId(row.idempotency_fingerprint),
+        };
+    }
     get(commentIdRaw, workspaceIdRaw, options) {
         const commentId = normalizeId(commentIdRaw);
         const workspaceId = normalizeWorkspaceId(workspaceIdRaw);
@@ -158,12 +219,20 @@ export class DocumentReviewCommentStore {
                 anchor_json = ?,
                 order_index = ?,
                 author_actor_id = ?,
+                updated_by_actor_id = ?,
+                deleted_by_actor_id = ?,
+                thread_status = ?,
+                thread_status_updated_at = ?,
+                resolved_at = ?,
+                resolved_by_actor_id = ?,
                 updated_at = ?,
                 deleted_at = ?
             WHERE tenant_id = ?
               AND workspace_id = ?
               AND id = ?
-        `).run(input.body === undefined ? existing.body : normalizeId(input.body), input.anchor === undefined ? (existing.anchor ? JSON.stringify(existing.anchor) : null) : (input.anchor ? JSON.stringify(input.anchor) : null), input.order === undefined ? existing.order : (normalizePositiveInteger(input.order) ?? existing.order), input.authorActorId === undefined ? existing.authorActorId : normalizeNullable(input.authorActorId), normalizeId(input.updatedAt) || new Date().toISOString(), input.deletedAt === undefined ? existing.deletedAt : normalizeNullable(input.deletedAt), this.tenantId, normalizeWorkspaceId(input.workspaceId), normalizeId(input.id));
+        `).run(input.body === undefined ? existing.body : normalizeId(input.body), input.anchor === undefined ? (existing.anchor ? JSON.stringify(existing.anchor) : null) : (input.anchor ? JSON.stringify(input.anchor) : null), input.order === undefined ? existing.order : (normalizePositiveInteger(input.order) ?? existing.order), input.authorActorId === undefined ? existing.authorActorId : normalizeNullable(input.authorActorId), input.updatedByActorId === undefined ? existing.updatedByActorId : normalizeNullable(input.updatedByActorId), input.deletedByActorId === undefined ? existing.deletedByActorId : normalizeNullable(input.deletedByActorId), existing.parentCommentId
+            ? null
+            : (input.threadStatus === undefined ? existing.threadStatus : input.threadStatus), input.threadStatusUpdatedAt === undefined ? existing.threadStatusUpdatedAt : normalizeNullable(input.threadStatusUpdatedAt), input.resolvedAt === undefined ? existing.resolvedAt : normalizeNullable(input.resolvedAt), input.resolvedByActorId === undefined ? existing.resolvedByActorId : normalizeNullable(input.resolvedByActorId), normalizeId(input.updatedAt) || new Date().toISOString(), input.deletedAt === undefined ? existing.deletedAt : normalizeNullable(input.deletedAt), this.tenantId, normalizeWorkspaceId(input.workspaceId), normalizeId(input.id));
         return this.get(input.id, input.workspaceId, { includeDeleted: true });
     }
     upsertForSync(input) {
@@ -171,12 +240,40 @@ export class DocumentReviewCommentStore {
         if (!existing) {
             return this.create(input);
         }
+        const incomingSessionId = normalizeId(input.sessionId);
+        if (incomingSessionId && incomingSessionId !== existing.sessionId) {
+            throw new Error(`Document review comment ${existing.id} cannot move between review sessions.`);
+        }
+        const incomingParentCommentId = input.parentCommentId === undefined
+            ? undefined
+            : normalizeNullable(input.parentCommentId);
+        if (incomingParentCommentId !== undefined && incomingParentCommentId !== existing.parentCommentId) {
+            throw new Error(`Document review comment ${existing.id} cannot move between threads.`);
+        }
+        const incomingThreadStatusUpdatedAt = input.threadStatusUpdatedAt === undefined
+            ? undefined
+            : normalizeNullable(input.threadStatusUpdatedAt);
+        const shouldApplyThreadLifecycle = input.threadStatus !== undefined
+            && incomingThreadStatusUpdatedAt !== undefined
+            && (!existing.threadStatusUpdatedAt
+                || (incomingThreadStatusUpdatedAt !== null
+                    && incomingThreadStatusUpdatedAt >= existing.threadStatusUpdatedAt));
+        const nextParentCommentId = incomingParentCommentId === undefined
+            ? existing.parentCommentId
+            : incomingParentCommentId;
         this.db.prepare(`
             UPDATE document_review_comments
             SET session_id = ?,
                 body = ?,
                 anchor_json = ?,
                 author_actor_id = ?,
+                updated_by_actor_id = ?,
+                deleted_by_actor_id = ?,
+                parent_comment_id = ?,
+                thread_status = ?,
+                thread_status_updated_at = ?,
+                resolved_at = ?,
+                resolved_by_actor_id = ?,
                 order_index = ?,
                 created_at = ?,
                 updated_at = ?,
@@ -184,23 +281,36 @@ export class DocumentReviewCommentStore {
             WHERE tenant_id = ?
               AND workspace_id = ?
               AND id = ?
-        `).run(normalizeId(input.sessionId) || existing.sessionId, normalizeId(input.body), input.anchor ? JSON.stringify(input.anchor) : null, normalizeNullable(input.authorActorId), normalizePositiveInteger(input.order) ?? existing.order, normalizeId(input.createdAt) || existing.createdAt, normalizeId(input.updatedAt) || existing.updatedAt, normalizeNullable(input.deletedAt), this.tenantId, normalizeWorkspaceId(input.workspaceId), normalizeId(input.id));
+        `).run(normalizeId(input.sessionId) || existing.sessionId, normalizeId(input.body), input.anchor ? JSON.stringify(input.anchor) : null, normalizeNullable(input.authorActorId), normalizeNullable(input.updatedByActorId), input.deletedByActorId === undefined ? existing.deletedByActorId : normalizeNullable(input.deletedByActorId), nextParentCommentId, nextParentCommentId
+            ? null
+            : (shouldApplyThreadLifecycle ? input.threadStatus : existing.threadStatus), shouldApplyThreadLifecycle
+            ? incomingThreadStatusUpdatedAt
+            : existing.threadStatusUpdatedAt, shouldApplyThreadLifecycle
+            ? normalizeNullable(input.resolvedAt)
+            : existing.resolvedAt, shouldApplyThreadLifecycle
+            ? normalizeNullable(input.resolvedByActorId)
+            : existing.resolvedByActorId, normalizePositiveInteger(input.order) ?? existing.order, normalizeId(input.createdAt) || existing.createdAt, normalizeId(input.updatedAt) || existing.updatedAt, existing.deletedAt || (input.deletedAt === undefined
+            ? null
+            : normalizeNullable(input.deletedAt)), this.tenantId, normalizeWorkspaceId(input.workspaceId), normalizeId(input.id));
         return this.get(input.id, input.workspaceId, { includeDeleted: true });
     }
-    softDelete(commentIdRaw, workspaceIdRaw, deletedAtRaw) {
+    softDelete(commentIdRaw, workspaceIdRaw, deletedAtRaw, deletedByActorIdRaw) {
         const commentId = normalizeId(commentIdRaw);
         const workspaceId = normalizeWorkspaceId(workspaceIdRaw);
         if (!commentId)
             return false;
         const deletedAt = normalizeId(deletedAtRaw) || new Date().toISOString();
+        const deletedByActorId = normalizeNullable(deletedByActorIdRaw);
         const result = this.db.prepare(`
             UPDATE document_review_comments
-            SET deleted_at = ?, updated_at = ?
+            SET deleted_at = ?,
+                deleted_by_actor_id = COALESCE(?, deleted_by_actor_id),
+                updated_at = ?
             WHERE tenant_id = ?
               AND workspace_id = ?
               AND id = ?
               AND deleted_at IS NULL
-        `).run(deletedAt, deletedAt, this.tenantId, workspaceId, commentId);
+        `).run(deletedAt, deletedByActorId, deletedAt, this.tenantId, workspaceId, commentId);
         return Number(result?.changes || 0) > 0;
     }
     replaceForSession(input) {
@@ -221,6 +331,13 @@ export class DocumentReviewCommentStore {
                 anchor: comment.anchor,
                 order: comment.order,
                 authorActorId: comment.authorActorId,
+                updatedByActorId: comment.updatedByActorId,
+                deletedByActorId: comment.deletedByActorId,
+                parentCommentId: comment.parentCommentId,
+                threadStatus: comment.threadStatus,
+                threadStatusUpdatedAt: comment.threadStatusUpdatedAt,
+                resolvedAt: comment.resolvedAt,
+                resolvedByActorId: comment.resolvedByActorId,
                 createdAt: comment.createdAt,
                 updatedAt: comment.updatedAt,
                 deletedAt: comment.deletedAt,

package/dist/documentReviews/commandService.d.ts

@@ -0,0 +1,51 @@
+import type { DocumentReviewAnchor, DocumentReviewSession } from './types.js';
+export interface ReviewDocumentCommandComment {
+    body: string;
+    anchor?: DocumentReviewAnchor | null;
+}
+export interface ReviewDocumentCommandInput {
+    workspaceId: string;
+    assetId: string;
+    documentLabel?: string | null;
+    sessionId?: string | null;
+    title?: string | null;
+    comments: readonly ReviewDocumentCommandComment[];
+    actorId?: string | null;
+}
+export interface DocumentReviewCommandServiceDependencies {
+    getSession(input: {
+        workspaceId: string;
+        sessionId: string;
+    }): DocumentReviewSession | null;
+    listSessions(input: {
+        workspaceId: string;
+        assetId: string;
+    }): DocumentReviewSession[];
+    createSession(input: {
+        workspaceId: string;
+        assetId: string;
+        title: string | null;
+        status: 'open';
+        actorId?: string | null;
+    }): DocumentReviewSession;
+    addComment(input: {
+        workspaceId: string;
+        sessionId: string;
+        body: string;
+        anchor: DocumentReviewAnchor | null;
+        actorId?: string | null;
+    }): DocumentReviewSession;
+}
+export declare class DocumentReviewCommandError extends Error {
+    readonly code: string;
+    readonly statusCode: number;
+    constructor(message: string, code: string, statusCode: number);
+}
+export interface ReviewDocumentCommandResult {
+    session: DocumentReviewSession;
+    sessionAction: 'reused' | 'created';
+    postedCommentIds: string[];
+}
+export declare function createDocumentReviewCommandService(deps: DocumentReviewCommandServiceDependencies): {
+    review(input: ReviewDocumentCommandInput): ReviewDocumentCommandResult;
+};

package/dist/documentReviews/commandService.js

@@ -0,0 +1,63 @@
+export class DocumentReviewCommandError extends Error {
+    code;
+    statusCode;
+    constructor(message, code, statusCode) {
+        super(message);
+        this.name = 'DocumentReviewCommandError';
+        this.code = code;
+        this.statusCode = statusCode;
+    }
+}
+export function createDocumentReviewCommandService(deps) {
+    return {
+        review(input) {
+            const requestedSessionId = typeof input.sessionId === 'string' && input.sessionId
+                ? input.sessionId
+                : null;
+            let session = requestedSessionId
+                ? deps.getSession({ workspaceId: input.workspaceId, sessionId: requestedSessionId.trim() })
+                : null;
+            let sessionAction = 'reused';
+            if (!session && requestedSessionId) {
+                throw new DocumentReviewCommandError(`Document review session ${requestedSessionId} not found.`, 'MCP_NOT_FOUND', 404);
+            }
+            if (session && session.assetId !== input.assetId) {
+                throw new DocumentReviewCommandError(`Document review session ${session.id} is not linked to document ${input.documentLabel || input.assetId}.`, 'MCP_ATTACHMENT_CONFLICT', 409);
+            }
+            if (!session) {
+                const openSessions = deps.listSessions({
+                    workspaceId: input.workspaceId,
+                    assetId: input.assetId,
+                }).filter((candidate) => candidate.status === 'open');
+                if (openSessions.length === 1) {
+                    session = openSessions[0];
+                }
+                else {
+                    session = deps.createSession({
+                        workspaceId: input.workspaceId,
+                        assetId: input.assetId,
+                        title: typeof input.title === 'string' ? input.title : null,
+                        status: 'open',
+                        actorId: input.actorId,
+                    });
+                    sessionAction = 'created';
+                }
+            }
+            const postedCommentIds = [];
+            let currentSession = session;
+            for (const comment of input.comments) {
+                currentSession = deps.addComment({
+                    workspaceId: input.workspaceId,
+                    sessionId: currentSession.id,
+                    body: comment.body,
+                    anchor: comment.anchor ?? null,
+                    actorId: input.actorId,
+                });
+                const createdComment = currentSession.comments.at(-1);
+                if (createdComment)
+                    postedCommentIds.push(createdComment.id);
+            }
+            return { session: currentSession, sessionAction, postedCommentIds };
+        },
+    };
+}