@company-semantics/contracts 63.0.0 → 63.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@company-semantics/contracts",
-  "version": "63.0.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",
@@ -181,5 +181,5 @@
     "*.md": "markdownlint-cli2",
     "package.json": "node -e \"JSON.parse(require('fs').readFileSync('package.json'))\""
   },
-  "securityRequirementsVersion": "2dcea336317c1136c8d94798b1cadc9c115febf574d041a173974a5f7959de0b"
+  "securityRequirementsVersion": "b5085eaa2fcf9fee09a3c8d2a9e15eab119800def73c98dc6ab6937d1c6e07b2"
 }

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 = 'e90aa233fbf5' as const;
-export const SPEC_HASH_FULL = 'e90aa233fbf5c821f7a67d53e8da52152166bf1eefb029e1999fde02e8e66a4f' as const;
+export const SPEC_HASH = '387045558d18' as const;
+export const SPEC_HASH_FULL = '387045558d1867722a744ddb05cf5ebb7260c54df0ff272b868bd4dd2ad2a973' as const;

package/src/api/generated.ts

@@ -4373,6 +4373,11 @@ export interface components {
             /** @enum {string} */
             origin?: "user" | "proactive";
             launch: {
+                /** @constant */
+                kind: "structure-review";
+                /** Format: uuid */
+                proposalId: string;
+            } | {
                 /** @constant */
                 kind: "workflow";
                 /** Format: uuid */
@@ -6961,12 +6966,19 @@ export interface components {
                 insertedText?: string;
             };
             body?: string;
-            mentions?: {
+            mentions?: ({
+                /** @constant */
+                kind: "user";
                 /** Format: uuid */
                 userId: string;
                 startOffset: number;
                 endOffset: number;
-            }[];
+            } | {
+                /** @constant */
+                kind: "agent";
+                startOffset: number;
+                endOffset: number;
+            })[];
         };
         /** @description The written reply, and whether it auto-reopened a resolved thread. */
         CommentReplyResponse: {
@@ -6975,12 +6987,19 @@ export interface components {
         };
         CommentReplyRequest: {
             body: string;
-            mentions?: {
+            mentions?: ({
+                /** @constant */
+                kind: "user";
                 /** Format: uuid */
                 userId: string;
                 startOffset: number;
                 endOffset: number;
-            }[];
+            } | {
+                /** @constant */
+                kind: "agent";
+                startOffset: number;
+                endOffset: number;
+            })[];
         };
         /** @description The comment after the mutation (redacted projection after delete). */
         CommentResponse: {
@@ -6988,12 +7007,19 @@ export interface components {
         };
         EditCommentRequest: {
             body: string;
-            mentions?: {
+            mentions?: ({
+                /** @constant */
+                kind: "user";
                 /** Format: uuid */
                 userId: string;
                 startOffset: number;
                 endOffset: number;
-            }[];
+            } | {
+                /** @constant */
+                kind: "agent";
+                startOffset: number;
+                endOffset: number;
+            })[];
         };
         /** @description The thread after a resolve/reopen transition. */
         CommentThreadSummaryResponse: {
@@ -7026,7 +7052,14 @@ export interface components {
         };
         /** @description A principal who can read the document and may therefore be mentioned. */
         CompanyMdMentionableCandidate: {
-            userId: string;
+            principal: {
+                /** @constant */
+                kind: "user";
+                userId: string;
+            } | {
+                /** @constant */
+                kind: "agent";
+            };
             displayName: string;
             avatarUrl: string | null;
         };
@@ -7107,6 +7140,29 @@ export interface components {
             /** @enum {string} */
             kind: "comment" | "suggestion";
             suggestion: components["schemas"]["Suggestion"] | null;
+            origin: {
+                /** @constant */
+                kind: "comment";
+            } | {
+                /** @constant */
+                kind: "doc_mention";
+                byUser: ({
+                    /** @constant */
+                    kind: "user";
+                    userId: string;
+                } | {
+                    /** @constant */
+                    kind: "agent";
+                }) | null;
+                introducedAt: string;
+            };
+            agentOutcomes: {
+                triggerId: string;
+                /** @enum {string} */
+                status: "pending" | "replied" | "unanswered";
+                reason: ("replies_off" | "mentioner_unavailable" | "delegate_unknown" | "subject_unreadable" | "rate_capped" | "turn_failed") | null;
+                replyCommentId: string | null;
+            }[];
             createdByUserId: string | null;
             resolvedByUserId: string | null;
             resolvedAt: string | null;
@@ -7155,16 +7211,30 @@ export interface components {
         Comment: {
             id: string;
             threadId: string;
-            authorUserId: string | null;
+            author: ({
+                /** @constant */
+                kind: "user";
+                userId: string;
+            } | {
+                /** @constant */
+                kind: "agent";
+            }) | null;
             body: string | null;
             editedAt: string | null;
             deletedAt: string | null;
             createdAt: string;
             mentions: components["schemas"]["CommentMention"][];
         };
-        /** @description One mention on a comment: the mentioned user id, its zero-based exclusive-end UTF-16 range (null until the offset columns exist), and the display name resolved at read time. */
+        /** @description One mention on a comment: the principal mentioned, its zero-based exclusive-end UTF-16 range (null until the offset columns exist), and the display name resolved at read time. */
         CommentMention: {
-            userId: string;
+            target: {
+                /** @constant */
+                kind: "user";
+                userId: string;
+            } | {
+                /** @constant */
+                kind: "agent";
+            };
             startOffset: number | null;
             endOffset: number | null;
             displayName: string;
@@ -7191,6 +7261,29 @@ export interface components {
             /** @enum {string} */
             kind: "comment" | "suggestion";
             suggestion: components["schemas"]["Suggestion"] | null;
+            origin: {
+                /** @constant */
+                kind: "comment";
+            } | {
+                /** @constant */
+                kind: "doc_mention";
+                byUser: ({
+                    /** @constant */
+                    kind: "user";
+                    userId: string;
+                } | {
+                    /** @constant */
+                    kind: "agent";
+                }) | null;
+                introducedAt: string;
+            };
+            agentOutcomes: {
+                triggerId: string;
+                /** @enum {string} */
+                status: "pending" | "replied" | "unanswered";
+                reason: ("replies_off" | "mentioner_unavailable" | "delegate_unknown" | "subject_unreadable" | "rate_capped" | "turn_failed") | null;
+                replyCommentId: string | null;
+            }[];
             createdByUserId: string | null;
             resolvedByUserId: string | null;
             resolvedAt: string | null;

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];
 
 /**