@company-semantics/contracts 63.1.0 → 63.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@company-semantics/contracts",
-  "version": "63.1.0",
+  "version": "63.3.0",
   "private": false,
   "repository": {
     "type": "git",
@@ -118,7 +118,7 @@
     "anchor-corpus:sync": "tsx scripts/anchor-corpus.ts --sync",
     "generate:spec-hash": "tsx scripts/generate-spec-hash.ts",
     "generate:spec-hash:check": "tsx scripts/generate-spec-hash.ts --check",
-    "generate:api": "pnpm generate:api-types && pnpm generate:spec-hash && pnpm generate:openapi-routes",
+    "generate:api": "pnpm generate:api-types && pnpm generate:spec-hash && pnpm generate:openapi-routes && pnpm file-sizes:pin",
     "generate:api:check": "pnpm generate:api-types:check && pnpm generate:spec-hash:check && pnpm generate:openapi-routes:check",
     "generate:api-types": "openapi-typescript openapi/backend.yaml -o src/api/generated.ts",
     "generate:openapi-routes": "tsx scripts/generate-openapi-routes.ts",

package/src/api/generated-spec-hash.ts

@@ -1,3 +1,3 @@
 // AUTO-GENERATED — do not edit. Run pnpm generate:spec-hash to regenerate.
-export const SPEC_HASH = '387045558d18' as const;
-export const SPEC_HASH_FULL = '387045558d1867722a744ddb05cf5ebb7260c54df0ff272b868bd4dd2ad2a973' as const;
+export const SPEC_HASH = '191634e28786' as const;
+export const SPEC_HASH_FULL = '191634e28786b02448431968a7b8f6f3fbbcd5f5cadc9f48e3067511a790c38b' as const;

package/src/api/generated.ts

@@ -3778,6 +3778,23 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/api/comments/threads/{threadId}": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        post?: never;
+        /** Soft-delete a thread of either kind (creator or subject owner) */
+        delete: operations["deleteCommentThread"];
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/api/comments/threads/{threadId}/accept-intent": {
         parameters: {
             query?: never;
@@ -3863,6 +3880,23 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/api/comments/threads/{threadId}/revert": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /** Revert a decided suggestion, restoring the passage an acceptance replaced */
+        post: operations["revertSuggestion"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
 }
 export type webhooks = Record<string, never>;
 export interface components {
@@ -7028,6 +7062,11 @@ export interface components {
         AnchorTraceRequest: {
             lastAnchoredOffset: number;
         };
+        /** @description Acknowledges a soft-deleted thread: its id and the deletion stamp. */
+        CommentThreadDeletedResponse: {
+            threadId: string;
+            deletedAt: string;
+        };
         /** @description The acceptance lease: the opaque claim token that alone can complete the accept, and how long the lease lives. */
         SuggestionClaimResponse: {
             claimToken: string;
@@ -7045,6 +7084,14 @@ export interface components {
             claimToken: string;
             expectedRevision: string;
         };
+        /** @description The reverted thread and the inverse document mutation that landed with it, or null when the suggestion had never been applied. */
+        SuggestionRevertedResponse: {
+            thread: components["schemas"]["CommentThreadSummary"];
+            reverted: components["schemas"]["SuggestionApplied"] | null;
+        };
+        SuggestionRevertRequest: {
+            expectedRevision?: string;
+        };
         /** @description Server-enforced collaboration size limits, published so clients can pre-check. */
         CollabSyncLimits: {
             maxUpdateBytes: number;
@@ -7205,7 +7252,7 @@ export interface components {
             op: "insert" | "delete" | "replace";
             insertedText?: string;
             /** @enum {string} */
-            status: "open" | "accepted" | "rejected";
+            status: "open" | "accepted" | "rejected" | "reverted";
         };
         /** @description One comment; body is null iff soft-deleted (redacted projection with empty mentions). */
         Comment: {
@@ -7246,6 +7293,8 @@ export interface components {
             canReopen: boolean;
             canDecideSuggestion: boolean;
             canWithdraw: boolean;
+            canRevertSuggestion: boolean;
+            canDeleteThread: boolean;
         };
         /** @description A comment thread without its comments. */
         CommentThreadSummary: {
@@ -13750,6 +13799,42 @@ export interface operations {
             };
         };
     };
+    deleteCommentThread: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                threadId: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Thread soft-deleted; the response acknowledges the id and the deletion stamp. Accepted suggestion text stays in the document */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["CommentThreadDeletedResponse"];
+                };
+            };
+            /** @description Thread not found, already deleted, or the caller is neither its creator nor a subject owner */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description A live acceptance lease is held on the suggestion */
+            409: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+        };
+    };
     acceptSuggestionIntent: {
         parameters: {
             query?: never;
@@ -13963,4 +14048,51 @@ export interface operations {
             };
         };
     };
+    revertSuggestion: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                threadId: string;
+            };
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["SuggestionRevertRequest"];
+            };
+        };
+        responses: {
+            /** @description Suggestion reverted (terminal; thread stays resolved). On an accepted suggestion the inverse edit landed in the document on the SAME transaction and is reported; on a rejected one `reverted` is null */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["SuggestionRevertedResponse"];
+                };
+            };
+            /** @description Malformed expectedRevision, or an accepted suggestion reverted without one */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description Thread not found, or the caller may not decide suggestions on it */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description Terminal, never retry: not a suggestion thread, still open, already reverted, a claim is on the row, the document moved past expectedRevision, or the inserted text cannot be found or no longer reads as inserted — re-read the document and decide again */
+            409: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+        };
+    };
 }

package/src/comments/__tests__/schemas.test.ts

@@ -86,6 +86,8 @@ function makeThread(over: Record<string, unknown> = {}) {
       canReopen: false,
       canDecideSuggestion: false,
       canWithdraw: false,
+      canRevertSuggestion: false,
+      canDeleteThread: false,
     },
     ...over,
   };

package/src/comments/__tests__/suggestion.test.ts

@@ -34,10 +34,36 @@ describe("the vocabulary tuples", () => {
     expect([...SUGGESTION_OPS]).toEqual(["insert", "delete", "replace"]);
   });
 
-  it("SUGGESTION_STATUSES is exactly open, accepted and rejected", () => {
+  it("SUGGESTION_STATUSES is exactly open, accepted, rejected and reverted", () => {
     // The SECOND status level. The thread-level enum stays open|resolved —
     // `./schemas.test.ts` pins that separately — and the decision lives here.
-    expect([...SUGGESTION_STATUSES]).toEqual(["open", "accepted", "rejected"]);
+    //
+    // PINNED AS A LIST, NOT A LENGTH, because widening it is the one change on
+    // this surface that cannot be walked back: a published `z.enum` refuses a
+    // member it has not shipped, and this one is nested inside the thread
+    // summary, so an unfamiliar status costs a client the whole document's
+    // comments. Failing here is the reminder that adding a member is a
+    // coordinated release — readers first, emitter second.
+    expect([...SUGGESTION_STATUSES]).toEqual([
+      "open",
+      "accepted",
+      "rejected",
+      "reverted",
+    ]);
+  });
+
+  it("accepts a reverted payload", () => {
+    // The state a taken-back decision lands in. Parsed here so the widening is
+    // proven at the schema, not just in the tuple above.
+    expect(
+      SuggestionSchema.safeParse(
+        makeSuggestion({
+          op: "replace",
+          insertedText: "x",
+          status: "reverted",
+        }),
+      ).success,
+    ).toBe(true);
   });
 });
 

package/src/comments/schemas.ts

@@ -355,6 +355,32 @@ export const ThreadCapabilitiesSchema = z.object({
    * their own suggestion.
    */
   canWithdraw: z.boolean(),
+  /**
+   * Take back a decision on a DECIDED suggestion — the complement of
+   * `canDecideSuggestion`, exactly as `canReopen` is the complement of
+   * `canResolve` one kind over.
+   *
+   * The edit band, like deciding: undoing an acceptance puts the replaced
+   * passage back into the document, which is the same authority as putting the
+   * proposal in. A reverted suggestion offers it no longer — `reverted` is
+   * terminal, so this is false there as well as on an open one.
+   */
+  canRevertSuggestion: z.boolean(),
+  /**
+   * Delete the whole thread — the conversation, not one comment in it.
+   *
+   * TRUE FOR BOTH KINDS, and it is the only capability here that does not
+   * mention one. A comment thread could previously only be dismantled by
+   * deleting its first comment, which cascaded; a suggestion thread could not be
+   * deleted at all, because its proposal is not a comment and there was nothing
+   * to aim the cascade at. One flag answers both.
+   *
+   * IT SAYS NOTHING ABOUT THE DOCUMENT. Deleting a thread whose suggestion was
+   * accepted leaves the accepted words where they are: they are the document's
+   * now, and taking them back is `canRevertSuggestion`'s act, deliberately kept
+   * separate so neither one silently performs the other.
+   */
+  canDeleteThread: z.boolean(),
 });
 export type ThreadCapabilities = z.infer<typeof ThreadCapabilitiesSchema>;
 

package/src/comments/suggestion.ts

@@ -37,14 +37,43 @@ export const SUGGESTION_OPS = ["insert", "delete", "replace"] as const;
 export type SuggestionOp = (typeof SUGGESTION_OPS)[number];
 
 /**
- * open -> accepted | rejected. Terminal states are terminal: there is no
- * reopen for a decided suggestion (unlike comment resolve/reopen). This is
- * the SECOND status level — the thread-level `status` enum stays exactly
- * `open | resolved`, and a decided suggestion arrives as thread status
- * `resolved` with this field carrying which way it went. Widening the closed
- * thread enum instead would be a parse outage for every deployed client.
+ * `open -> accepted | rejected -> reverted`. This is the SECOND status level —
+ * the thread-level `status` enum stays exactly `open | resolved`, and a decided
+ * suggestion arrives as thread status `resolved` with this field carrying which
+ * way it went. Widening the closed thread enum instead would be a parse outage
+ * for every deployed client.
+ *
+ * A DECISION IS NO LONGER THE LAST WORD, BUT IT IS STILL ONE-WAY. This tuple
+ * read `open | accepted | rejected` with "terminal states are terminal: there is
+ * no reopen for a decided suggestion" written beside it, and that is now false:
+ * people are allowed to change their minds, and undoing an acceptance restores
+ * the passage the edit replaced. What has NOT changed is that the arrow never
+ * points back to `open`. `reverted` is its own terminal state rather than a
+ * return to the start, for two reasons — a reverted proposal is a decision
+ * somebody took and then took back, which is a different fact from one nobody
+ * has answered yet; and an `open` suggestion whose document still carries an
+ * application receipt is exactly the shape the server's reconciler treats as
+ * proof of an unacknowledged accept, so returning one to `open` would have it
+ * silently re-accepted by background maintenance.
+ *
+ * WIDENING THIS TUPLE IS ORDERED, NOT FREE. `SuggestionSchema` below is a
+ * `z.strictObject` nested inside `CommentThreadSummarySchema`, so for anyone who
+ * PARSES a thread list, one row carrying a status they do not know fails the
+ * whole list — every comment on that document, not just the odd suggestion — and
+ * it fails the first time somebody reverts rather than at deploy. No consumer in
+ * this workspace parses these at runtime today (the app is typed off the
+ * generated spec; the backend validates against its own local copies), which was
+ * checked rather than assumed, so this package leads the release and the emitter
+ * follows. The next person to add a member owes that check again for their own
+ * consumers — which is why `__tests__/suggestion.test.ts` pins this list
+ * exactly. See the ADR with slug `suggestion-revert-vocabulary`.
  */
-export const SUGGESTION_STATUSES = ["open", "accepted", "rejected"] as const;
+export const SUGGESTION_STATUSES = [
+  "open",
+  "accepted",
+  "rejected",
+  "reverted",
+] as const;
 export type SuggestionStatus = (typeof SUGGESTION_STATUSES)[number];
 
 /**

package/src/generated/openapi-routes.ts

@@ -24,6 +24,7 @@ export const openApiRoutes = {
   '/api/chats/{id}/pin': ['DELETE', 'POST'],
   '/api/comments': ['GET'],
   '/api/comments/threads': ['POST'],
+  '/api/comments/threads/{threadId}': ['DELETE'],
   '/api/comments/threads/{threadId}/accept-apply': ['POST'],
   '/api/comments/threads/{threadId}/accept-complete': ['POST'],
   '/api/comments/threads/{threadId}/accept-intent': ['POST'],
@@ -33,6 +34,7 @@ export const openApiRoutes = {
   '/api/comments/threads/{threadId}/reject': ['POST'],
   '/api/comments/threads/{threadId}/reopen': ['POST'],
   '/api/comments/threads/{threadId}/resolve': ['POST'],
+  '/api/comments/threads/{threadId}/revert': ['POST'],
   '/api/comments/{commentId}': ['DELETE', 'PATCH'],
   '/api/company-md/access-requests/{id}/approve': ['POST'],
   '/api/company-md/access-requests/{id}/deny': ['POST'],