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

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

Implements the missing inverse of `comments.patch({ status:
'resolved' })` so resolve <-> reopen round-trips both at the engine
level and across DOCX. Surfaced on the public Document API as
`comments.patch({ commentId, status: 'active' })`.

Resolve removes the live `comment` mark and inserts
`commentRangeStart` / `commentRangeEnd` anchor nodes around the
same range. Reopen mirrors that: matches anchor nodes by `w:id`,
pairs them in document order, re-inserts the comment mark with
`(commentId, importedId, internal)` attrs, and deletes the anchor
nodes. The `internal` flag falls back to the value stamped on
`commentRangeStart` when no override is provided so import-resolved
comments (with `w15:done="1"`) reopen without losing the flag; the
plan-engine handler reads the entity store value when present and
forwards it as the override path.

Engine

  - `reopenCommentById` in `comments-helpers.js` — symmetric inverse
    of `resolveCommentById`. Maps positions through `tr.mapping` so
    mark inserts and node deletes stay in sync; processes deletes
    in descending order to avoid position drift.
  - `reopenComment` editor command in `comments-plugin.js`.

Document API

  - `ReopenCommentInput` type alongside `ResolveCommentInput`.
  - `CommentsPatchInput.status` widened to `'resolved' | 'active'`.
  - `validatePatchCommentInput` accepts both values.
  - `executeCommentsPatch` routes `status: 'active'` to
    `adapter.reopen`.
  - `CommentsAdapter.reopen` interface method added.
  - Public re-export from the `@superdoc/document-api` barrel.

Adapter

  - `reopenCommentHandler` in `comments-wrappers.ts` mirrors
    `resolveCommentHandler`: short-circuits to NO_OP when neither
    the entity store nor the doc anchors indicate a resolved state,
    flips `isDone: false` and clears `resolvedTime` on success.
  - Wired into `createCommentsWrapper`.
  - `'reopenComment'` added to the `'comments.patch'` capability
    list so feature detection still produces a single value for the
    operation.

Tests

  - Engine-level: reopen restores mark + removes anchors; honors
    `internal` from anchor; honors explicit `internal` override;
    no-op when not resolved.
  - Doc-API: validator accepts `'active'`, rejects others; routes
    to `adapter.reopen` not `adapter.resolve`.
  - Capability registry test stub gets `reopenComment`.

Generated artifacts

  - SDK contract regenerated via `pnpm run generate:all`. Only
    formatter normalization landed in `intent-dispatch.ts` —
    operation count unchanged.

Out of scope

  - Audit history of resolve/reopen events.
  - Reopening a deleted comment (delete is irreversible).
  - Threaded reply resolution semantics (root only).
  - Lab cleanup in `examples/headless/dropin-assessment` —
    will land in a follow-up PR alongside the SD-2790 ui.comments
    consumer migration.

* fix(document-api): widen comments.patch.status JSON schema to active (PR #2987 review)

The TypeScript type for `CommentsPatchInput.status` was widened to
`'resolved' | 'active'` in the prior commit, but the contract JSON
schema in `contract/schemas.ts` still enumerated only `['resolved']`.
After `generate:all`, the SDK / CLI / MCP / tool-catalog clients
that hydrate from the contract schema would have rejected
`status: 'active'`, leaving reopen reachable only from direct
TypeScript callers — not the documented contract surface.

Widens the input schema's enum to `['resolved', 'active']` and
extends the description to call out the lifecycle-inverse semantics
so contract-driven generators (Mintlify reference, OpenAI tool
schema, Python SDK) all see the same shape as the typed surface.

Output schemas (`commentInfoSchema`, `commentDomainItemSchema`, the
listing fragment) keep `['open', 'resolved']` — those describe
*states a comment can be in*, not *transitions a caller can
request*. Two intentionally different vocabularies: input is
imperative (`'active'` = "reopen this"), output is the resulting
state (`'open'`).

Regenerated artifacts via `pnpm run generate:all`:

   - `apps/docs/document-api/reference/comments/patch.mdx` —
     reference doc now lists both enum values + describes reopen.
   - `_generated-manifest.json` — manifest hash refresh.

* fix(super-editor): add reopenComment to CommentCommands typings (PR #2987 review)

Author: caio-pizzol

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

@@ -4812,7 +4812,11 @@ const operationSchemas: Record<OperationId, OperationSchemaSet> = {
         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),