@company-semantics/contracts 63.1.0 → 63.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@company-semantics/contracts",
-  "version": "63.1.0",
+  "version": "63.2.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/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];
 
 /**