feat(document-api): comment reopen lifecycle inverse (SD-2789)

apps/docs/document-api/reference/_generated-manifest.json

@@ -1031,5 +1031,5 @@
     }
   ],
   "marker": "{/* GENERATED FILE: DO NOT EDIT. Regenerate via `pnpm run docapi:sync`. */}",
-  "sourceHash": "cdb0b02e84f6eb7f4db962c177d082e0f89ec48517abc775736a3d17e4da9ba8"
+  "sourceHash": "fa717df8cc013f9703b118596afe4cbbf655fe73f2e4e856588844110998ee2e"
 }

apps/docs/document-api/reference/comments/patch.mdx

@@ -28,7 +28,7 @@ Returns a Receipt confirming the comment was updated; reports NO_OP if no fields
 | --- | --- | --- | --- |
 | `commentId` | string | yes |  |
 | `isInternal` | boolean | no |  |
-| `status` | enum | no | `"resolved"` |
+| `status` | enum | no | `"resolved"`, `"active"` |
 | `target` | TextAddress | no | TextAddress |
 | `target.blockId` | string | no |  |
 | `target.kind` | `"text"` | no | Constant: `"text"` |
@@ -124,9 +124,10 @@ Returns a Receipt confirming the comment was updated; reports NO_OP if no fields
       "type": "boolean"
     },
     "status": {
-      "description": "Set comment status. Use 'resolved' to mark as resolved.",
+      "description": "Set comment status. Use 'resolved' to resolve a comment, or 'active' to reopen a previously resolved comment (lifecycle inverse).",
       "enum": [
-        "resolved"
+        "resolved",
+        "active"
       ]
     },
     "target": {

packages/document-api/src/comments/comments.test.ts

@@ -14,6 +14,7 @@ const stubAdapter = () =>
     reply: mock(() => ({ success: true })),
     move: mock(() => ({ success: true })),
     resolve: mock(() => ({ success: true })),
+    reopen: mock(() => ({ success: true })),
     remove: mock(() => ({ success: true })),
     setInternal: mock(() => ({ success: true })),
     setActive: mock(() => ({ success: true })),
@@ -60,7 +61,7 @@ describe('executeCommentsPatch validation', () => {
 
   it('rejects invalid status', () => {
     expect(() => executeCommentsPatch(stubAdapter(), { commentId: 'c1', status: 'open' } as any)).toThrow(
-      /must be "resolved"/,
+      /must be "resolved" or "active"/,
     );
   });
 
@@ -75,6 +76,20 @@ describe('executeCommentsPatch validation', () => {
     executeCommentsPatch(adapter, { commentId: 'c1', isInternal: true });
     expect(adapter.setInternal).toHaveBeenCalled();
   });
+
+  it('routes status:"resolved" to adapter.resolve', () => {
+    const adapter = stubAdapter();
+    executeCommentsPatch(adapter, { commentId: 'c1', status: 'resolved' });
+    expect(adapter.resolve).toHaveBeenCalledWith({ commentId: 'c1' }, undefined);
+    expect(adapter.reopen).not.toHaveBeenCalled();
+  });
+
+  it('routes status:"active" to adapter.reopen (lifecycle inverse of resolve)', () => {
+    const adapter = stubAdapter();
+    executeCommentsPatch(adapter, { commentId: 'c1', status: 'active' });
+    expect(adapter.reopen).toHaveBeenCalledWith({ commentId: 'c1' }, undefined);
+    expect(adapter.resolve).not.toHaveBeenCalled();
+  });
 });
 
 describe('executeCommentsDelete validation', () => {

packages/document-api/src/comments/comments.ts

@@ -44,6 +44,14 @@ export interface ResolveCommentInput {
   commentId: string;
 }
 
+/**
+ * Input for reopening a previously-resolved comment. Accepted as the
+ * `status: 'active'` branch of `comments.patch`.
+ */
+export interface ReopenCommentInput {
+  commentId: string;
+}
+
 export interface RemoveCommentInput {
   commentId: string;
 }
@@ -104,8 +112,12 @@ export interface CommentsPatchInput {
   text?: string;
   /** New anchor range (routes to move). */
   target?: TextAddress;
-  /** Set status to 'resolved' (routes to resolve). */
-  status?: 'resolved';
+  /**
+   * Lifecycle transition. `'resolved'` routes to resolve, `'active'`
+   * routes to reopen — symmetric inverse that removes the resolve
+   * anchors and restores the live comment mark.
+   */
+  status?: 'resolved' | 'active';
   /** Set the internal/private flag (routes to setInternal). */
   isInternal?: boolean;
 }
@@ -132,6 +144,14 @@ export interface CommentsAdapter {
   move(input: MoveCommentInput, options?: RevisionGuardOptions): Receipt;
   /** Resolve an open comment. */
   resolve(input: ResolveCommentInput, options?: RevisionGuardOptions): Receipt;
+  /**
+   * Reopen a previously-resolved comment. Symmetric inverse of
+   * {@link CommentsAdapter.resolve}: removes the
+   * `commentRangeStart` / `commentRangeEnd` anchor nodes inserted at
+   * resolve time and restores the live `comment` mark across the
+   * original range so subsequent operations see the comment as active.
+   */
+  reopen(input: ReopenCommentInput, options?: RevisionGuardOptions): Receipt;
   /** Remove a comment from the document. */
   remove(input: RemoveCommentInput, options?: RevisionGuardOptions): Receipt;
   /** Set the internal/private flag on a comment. */
@@ -268,11 +288,15 @@ function validatePatchCommentInput(input: unknown): asserts input is CommentsPat
     });
   }
 
-  if (status !== undefined && status !== 'resolved') {
-    throw new DocumentApiValidationError('INVALID_INPUT', `status must be "resolved", got "${String(status)}".`, {
-      field: 'status',
-      value: status,
-    });
+  if (status !== undefined && status !== 'resolved' && status !== 'active') {
+    throw new DocumentApiValidationError(
+      'INVALID_INPUT',
+      `status must be "resolved" or "active", got "${String(status)}".`,
+      {
+        field: 'status',
+        value: status,
+      },
+    );
   }
 
   if (isInternal !== undefined && typeof isInternal !== 'boolean') {
@@ -341,6 +365,9 @@ export function executeCommentsPatch(
   if (input.status === 'resolved') {
     return adapter.resolve({ commentId: input.commentId }, options);
   }
+  if (input.status === 'active') {
+    return adapter.reopen({ commentId: input.commentId }, options);
+  }
   if (input.isInternal !== undefined) {
     return adapter.setInternal({ commentId: input.commentId, isInternal: input.isInternal }, options);
   }

packages/document-api/src/contract/schemas.ts

@@ -611,7 +611,7 @@
 const trackedChangeAddressSchema = ref('TrackedChangeAddress');
 const entityAddressSchema = ref('EntityAddress');
 const selectionTargetSchema = ref('SelectionTarget');
 const targetLocatorSchema = ref('TargetLocator');
 const deleteBehaviorSchema = ref('DeleteBehavior');
 const resolvedHandleSchema = ref('ResolvedHandle');
 const pageInfoSchema = ref('PageInfo');
@@ -886,7 +886,7 @@
   text: { type: 'string' },
 });
 
 const nodeInfoSchema: JsonSchema = {
   type: 'object',
   required: ['nodeType', 'kind'],
   properties: {
@@ -902,7 +902,7 @@
   additionalProperties: false,
 };
 
 const matchContextSchema = objectSchema(
   {
     address: nodeAddressSchema,
     snippet: { type: 'string' },
@@ -913,7 +913,7 @@
   ['address', 'snippet', 'highlightRange'],
 );
 
 const unknownNodeDiagnosticSchema = objectSchema(
   {
     message: { type: 'string' },
     address: nodeAddressSchema,
@@ -4812,7 +4812,11 @@
         commentId: { type: 'string' },
         text: { type: 'string', description: 'Updated comment text.' },
         target: textAddressSchema,
-        status: { enum: ['resolved'], description: "Set comment status. Use 'resolved' to mark as resolved." },
+        status: {
+          enum: ['resolved', 'active'],
+          description:
+            "Set comment status. Use 'resolved' to resolve a comment, or 'active' to reopen a previously resolved comment (lifecycle inverse).",
+        },
         isInternal: {
           type: 'boolean',
           description: 'When true, marks the comment as internal (hidden from external collaborators).',

packages/document-api/src/index.ts

@@ -1416,6 +1416,7 @@ export type {
   ReplyToCommentInput,
   MoveCommentInput,
   ResolveCommentInput,
+  ReopenCommentInput,
   RemoveCommentInput,
   SetCommentInternalInput,
   GoToCommentInput,

packages/super-editor/src/editors/v1/document-api-adapters/capabilities-adapter.test.ts

@@ -15,6 +15,7 @@ function makeEditor(overrides: Partial<Editor> = {}): Editor {
     addCommentReply: vi.fn(() => true),
     moveComment: vi.fn(() => true),
     resolveComment: vi.fn(() => true),
+    reopenComment: vi.fn(() => true),
     removeComment: vi.fn(() => true),
     setCommentInternal: vi.fn(() => true),
     setActiveComment: vi.fn(() => true),

packages/super-editor/src/editors/v1/document-api-adapters/capabilities-adapter.ts

@@ -59,7 +59,7 @@ const REQUIRED_COMMANDS: Partial<Record<OperationId, readonly EditorCommandName[
   'lists.clearLevelOverrides': [],
   'blocks.delete': ['deleteBlockNodeById'],
   'comments.create': ['addComment', 'setTextSelection', 'addCommentReply'],
-  'comments.patch': ['editComment', 'moveComment', 'resolveComment', 'setCommentInternal'],
+  'comments.patch': ['editComment', 'moveComment', 'resolveComment', 'reopenComment', 'setCommentInternal'],
   'comments.delete': ['removeComment'],
   'trackChanges.decide': [
     'acceptTrackedChangeById',

packages/super-editor/src/editors/v1/document-api-adapters/plan-engine/comments-wrappers.ts

@@ -3,7 +3,7 @@
  * engine's revision management and execution path.
  *
  * Read operations (list, get, goTo) are pure queries or non-mutating navigation.
- * Mutating operations (add, edit, reply, move, resolve, remove, setInternal, setActive)
+ * Mutating operations (add, edit, reply, move, resolve, reopen, remove, setInternal, setActive)
  * delegate to editor commands with plan-engine revision tracking.
  */
 
@@ -20,6 +20,7 @@ import type {
   MoveCommentInput,
   Receipt,
   RemoveCommentInput,
+  ReopenCommentInput,
   ReplyToCommentInput,
   ResolveCommentInput,
   RevisionGuardOptions,
@@ -756,6 +757,68 @@ function resolveCommentHandler(editor: Editor, input: ResolveCommentInput, optio
   return { success: true, updated: [toCommentAddress(identity.commentId)] };
 }
 
+function reopenCommentHandler(editor: Editor, input: ReopenCommentInput, options?: RevisionGuardOptions): Receipt {
+  const reopenComment = requireEditorCommand(editor.commands?.reopenComment, 'comments.patch (reopenComment)');
+
+  const store = getCommentEntityStore(editor);
+  const identity = resolveCommentIdentity(editor, input.commentId);
+  const existing = findCommentEntity(store, identity.commentId);
+  // Idempotent on the no-op path: reopening an already-active comment
+  // (no anchor nodes in the doc, entity store doesn't show resolved)
+  // returns NO_OP rather than running a command that would fail
+  // silently.
+  const isAnchored = identity.anchors.length > 0;
+  const isResolvedInStore = existing ? isCommentResolved(existing) : false;
+  const isResolvedInDoc = isAnchored && identity.anchors.every((a) => a.status === 'resolved');
+  if (!isResolvedInStore && !isResolvedInDoc) {
+    return {
+      success: false,
+      failure: { code: 'NO_OP', message: 'Comment is already active.' },
+    };
+  }
+
+  // Recover the original `internal` flag from the entity store when
+  // present; the engine helper falls back to the value stamped on
+  // `commentRangeStart` when this is undefined, so a runtime-resolved
+  // comment with no entity record still round-trips correctly.
+  const storedInternal = (existing as { isInternal?: unknown } | undefined)?.isInternal;
+  const internalOverride = typeof storedInternal === 'boolean' ? storedInternal : undefined;
+
+  const receipt = executeDomainCommand(
+    editor,
+    () => {
+      const didReopen = reopenComment({
+        commentId: identity.commentId,
+        importedId: identity.importedId,
+        internal: internalOverride,
+      });
+      if (didReopen) {
+        // Clear the resolved markers in the entity store so subsequent
+        // `comments.list()` reflects the reopen. `resolvedTime` is
+        // dropped explicitly because `upsertCommentEntity` merges
+        // partials and would otherwise leave the prior timestamp in
+        // place.
+        upsertCommentEntity(store, identity.commentId, {
+          importedId: identity.importedId,
+          isDone: false,
+          resolvedTime: null,
+        });
+      }
+      return Boolean(didReopen);
+    },
+    { expectedRevision: options?.expectedRevision },
+  );
+
+  if (receipt.steps[0]?.effect !== 'changed') {
+    return {
+      success: false,
+      failure: { code: 'NO_OP', message: 'Comment reopen produced no change.' },
+    };
+  }
+
+  return { success: true, updated: [toCommentAddress(identity.commentId)] };
+}
+
 function removeCommentHandler(editor: Editor, input: RemoveCommentInput, options?: RevisionGuardOptions): Receipt {
   const removeComment = requireEditorCommand(editor.commands?.removeComment, 'comments.remove (removeComment)');
 
@@ -986,6 +1049,7 @@ export function createCommentsWrapper(editor: Editor): CommentsAdapter {
     move: (input: MoveCommentInput, options?: RevisionGuardOptions) => moveCommentHandler(editor, input, options),
     resolve: (input: ResolveCommentInput, options?: RevisionGuardOptions) =>
       resolveCommentHandler(editor, input, options),
+    reopen: (input: ReopenCommentInput, options?: RevisionGuardOptions) => reopenCommentHandler(editor, input, options),
     remove: (input: RemoveCommentInput, options?: RevisionGuardOptions) => removeCommentHandler(editor, input, options),
     setInternal: (input: SetCommentInternalInput, options?: RevisionGuardOptions) =>
       setCommentInternalHandler(editor, input, options),