@company-semantics/contracts 51.0.0 → 51.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@company-semantics/contracts",
-  "version": "51.0.0",
+  "version": "51.1.0",
   "private": false,
   "repository": {
     "type": "git",
@@ -148,9 +148,9 @@
     "markdownlint-cli2": "^0.23.2",
     "openapi-typescript": "^7.13.0",
     "prettier": "^3.9.6",
-    "tsx": "^4.23.11",
+    "tsx": "^4.23.12",
     "typescript": "^5.8.3",
-    "typescript-eslint": "^8.66.0",
+    "typescript-eslint": "^8.67.0",
     "vite": "^8.2.1",
     "vitest": "^4.1.10",
     "yaml": "^2.9.0"

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 = '6dcd82441a54' as const;
-export const SPEC_HASH_FULL = '6dcd82441a54409faaa94d94f36a43cd72894c7e655fb49f5eb758a0963c9a43' as const;
+export const SPEC_HASH = '544058ec2d0f' as const;
+export const SPEC_HASH_FULL = '544058ec2d0ffc4b77cd02a9121088dadc5618d5bc04ed33707298a8a1ce6114' as const;

package/src/api/generated.ts

@@ -3565,6 +3565,23 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/api/comments/threads/{threadId}/anchor-trace": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /** Report where a thread's anchored passage used to be */
+        post: operations["stampCommentAnchorTrace"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/api/comments/threads/{threadId}/accept-intent": {
         parameters: {
             query?: never;
@@ -6514,6 +6531,9 @@ export interface components {
         CommentThreadSummaryResponse: {
             thread: components["schemas"]["CommentThreadSummary"];
         };
+        AnchorTraceRequest: {
+            lastAnchoredOffset: number;
+        };
         /** @description The acceptance lease: the opaque claim token that alone can complete the accept, and how long the lease lives. */
         SuggestionClaimResponse: {
             claimToken: string;
@@ -6550,12 +6570,13 @@ export interface components {
             /** @enum {string} */
             category: "version" | "source" | "lifecycle" | "access" | "sync";
             /** @enum {string} */
-            eventType: "doc_created" | "source_added" | "source_removed" | "content_generated" | "external_sync_completed" | "access_granted" | "access_revoked" | "access_updated" | "sharing_policy_changed" | "visibility_changed" | "owner_transferred" | "discoverability_changed";
+            eventType: "doc_created" | "doc_renamed" | "doc_moved" | "source_added" | "source_attached" | "source_detached" | "source_removed" | "source_extraction_started" | "source_extraction_succeeded" | "source_extraction_failed" | "content_generated" | "external_sync_completed" | "access_granted" | "access_revoked" | "access_updated" | "sharing_policy_changed" | "visibility_changed" | "owner_transferred" | "discoverability_changed";
             actor: components["schemas"]["CompanyMdDocVersionActor"] | null;
             subject: string | null;
             target: components["schemas"]["CompanyMdDocHistoryTarget"] | null;
             previousValue: string | null;
             newValue: string | null;
+            correlationId: string | null;
         };
         /** @description The singular actor a version is attributed to, in product vocabulary. */
         CompanyMdDocVersionActor: {
@@ -6612,6 +6633,7 @@ export interface components {
             createdByUserId: string | null;
             resolvedByUserId: string | null;
             resolvedAt: string | null;
+            lastAnchoredOffset: number | null;
             createdAt: string;
             updatedAt: string;
             comments: components["schemas"]["Comment"][];
@@ -6686,6 +6708,7 @@ export interface components {
             createdByUserId: string | null;
             resolvedByUserId: string | null;
             resolvedAt: string | null;
+            lastAnchoredOffset: number | null;
             createdAt: string;
             updatedAt: string;
         };
@@ -12833,6 +12856,46 @@ export interface operations {
             };
         };
     };
+    stampCommentAnchorTrace: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                threadId: string;
+            };
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["AnchorTraceRequest"];
+            };
+        };
+        responses: {
+            /** @description Offset recorded, or the already-recorded thread returned unchanged (first write wins) */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["CommentThreadSummaryResponse"];
+                };
+            };
+            /** @description Invalid body */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description Thread not found, or the caller may not comment on its subject */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+        };
+    };
     acceptSuggestionIntent: {
         parameters: {
             query?: never;

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

@@ -17,6 +17,7 @@ import {
   CommentThreadListResponseSchema,
   CommentThreadSchema,
   CommentThreadStatusSchema,
+  CommentThreadSummarySchema,
   MentionableResponseSchema,
 } from "../schemas.js";
 
@@ -68,6 +69,7 @@ function makeThread(over: Record<string, unknown> = {}) {
     createdByUserId: USER_ID,
     resolvedByUserId: null,
     resolvedAt: null,
+    lastAnchoredOffset: null,
     createdAt: "2026-08-01T12:00:00.000Z",
     updatedAt: "2026-08-01T12:00:00.000Z",
     comments: [makeComment()],
@@ -224,7 +226,13 @@ describe("CommentThreadSchema", () => {
     ).toBe(false);
   });
 
-  it("keeps tombstones in the comment list rather than filtering them", () => {
+  it("parses a redacted comment inside a thread — the schema still admits one", () => {
+    // This test once asserted that a reader SEES tombstones in a conversation.
+    // ADR-BE-545 ended that: the list read omits deleted comments outright. What
+    // survives is the SHAPE — the redacted projection is still a legal
+    // `CommentProjection`, because it is what the DELETE acknowledgement returns
+    // to the caller who performed the delete. So this pins the parse, not a read
+    // behaviour the server no longer has.
     const thread = CommentThreadSchema.parse(
       makeThread({
         comments: [
@@ -243,6 +251,26 @@ describe("CommentThreadSchema", () => {
 });
 
 describe("CommentThreadSummarySchema kind and suggestion", () => {
+  it("carries a lastAnchoredOffset, and null is the ordinary answer", () => {
+    // An ORDERING HINT and nothing else (ADR-BE-548): where an orphaned thread's
+    // passage used to be, so a client can keep the card in the reader's list
+    // rather than piling every orphan at the top. It must never yield a range.
+    expect(
+      CommentThreadSummarySchema.parse(makeThread()).lastAnchoredOffset,
+      "a thread nobody has watched lose its passage carries null",
+    ).toBeNull();
+    expect(
+      CommentThreadSummarySchema.parse(makeThread({ lastAnchoredOffset: 412 }))
+        .lastAnchoredOffset,
+    ).toBe(412);
+    expect(
+      CommentThreadSummarySchema.safeParse(
+        makeThread({ lastAnchoredOffset: 3.5 }),
+      ).success,
+      "a fractional offset is not a source position",
+    ).toBe(false);
+  });
+
   it("a zero-comment suggestion thread parses through both response shapes", () => {
     // The full suggestion projection: kind `suggestion`, a v1 payload, a
     // zero-width text-insertion anchor, and NO comments. The backend creates a

package/src/comments/schemas.ts

@@ -110,11 +110,14 @@ export type CommentMention = z.infer<typeof CommentMentionSchema>;
  * One comment as the app renders it.
  *
  * THE REDACTION INVARIANT: `body` is null EXACTLY WHEN `deletedAt` is set, and a
- * soft-deleted comment also arrives with `mentions` empty. A deleted comment is
- * a REDACTED PROJECTION, not a removed row — the tombstone keeps its position in
- * the (createdAt ASC, id ASC) sequence, so replies above and below it still read
- * in order, and a thread whose comments were all deleted stays distinguishable
- * from a thread that never had any.
+ * soft-deleted comment also arrives with `mentions` empty.
+ *
+ * WHERE A REDACTED COMMENT ACTUALLY APPEARS is narrower than it once was, and
+ * this docblock used to overstate it. The redacted projection is the DELETE
+ * acknowledgement — the response to the caller who performed the delete, telling
+ * them what they destroyed. It is NOT a row in a thread listing: ADR-BE-545 has
+ * the read omit deleted comments outright, and drop a comment-kind thread once
+ * nothing live is left on it. A reader never sees a tombstone in a conversation.
  *
  * The invariant is DOCUMENTED here and enforced by the writer, not by a Zod
  * refinement. A refinement would make this package refuse a response the server
@@ -166,6 +169,18 @@ export type CommentProjection = z.infer<typeof CommentSchema>;
  * would make this package refuse a response the server is willing to emit and
  * would be a third wire description no parity guard can check.
  *
+ * `lastAnchoredOffset` IS NOT AN ANCHOR. It is a source offset recording where
+ * this thread's passage USED TO BE, reported by the client that watched the
+ * passage disappear (ADR-BE-548). It exists so a client can keep an ORPHANED
+ * thread in the reader's list where the conversation happened, instead of piling
+ * every one of them at the top — and it may be used for NOTHING ELSE. It must
+ * never yield a range, and nothing may place a highlight, a decoration or a
+ * leader line from it: a comment shown against the wrong sentence is strictly
+ * worse than one shown as unanchored (ADR-APP-120), and that ordering is what
+ * bounds this field. `null` is ordinary — it means no client has watched this
+ * thread's passage go — and the value is WRITE-ONCE on the server, so it records
+ * the first sighting and never a correction.
+ *
  * THE TWO-LEVEL STATUS MODEL: `status` stays exactly `open | resolved`
  * (`COMMENT_THREAD_STATUSES` is NOT widened — widening a closed published enum
  * is a parse outage for every deployed client). A decided suggestion arrives as
@@ -185,6 +200,7 @@ export const CommentThreadSummarySchema = z.object({
   createdByUserId: z.string().nullable(),
   resolvedByUserId: z.string().nullable(),
   resolvedAt: z.string().nullable(),
+  lastAnchoredOffset: z.number().int().nullable(),
   createdAt: z.string(),
   updatedAt: z.string(),
 });
@@ -193,9 +209,12 @@ export type CommentThreadSummary = z.infer<typeof CommentThreadSummarySchema>;
 /**
  * A thread with ALL its comments, oldest-first by (createdAt ASC, id ASC).
  *
- * Soft-deleted comments appear REDACTED, never filtered out — filtering them
- * would renumber the conversation under the reader and make "…replying to the
- * comment above" false.
+ * DELETED COMMENTS ARE OMITTED, NOT REDACTED. This once said the opposite, and
+ * the prose outlived the rule: ADR-BE-545 made the read drop deleted comments
+ * entirely, and drop a comment-kind thread once nothing live is left on it —
+ * deleting the comment that IS a thread deletes the thread with it, so the reply
+ * order a redacted row used to hold open no longer has anything to hold. The
+ * wire SHAPE is unchanged either way; what changed is which rows arrive.
  */
 export const CommentThreadSchema = CommentThreadSummarySchema.extend({
   comments: z.array(CommentSchema),

package/src/generated/openapi-routes.ts

@@ -26,6 +26,7 @@ export const openApiRoutes = {
   '/api/comments/threads/{threadId}/accept-complete': ['POST'],
   '/api/comments/threads/{threadId}/accept-intent': ['POST'],
   '/api/comments/threads/{threadId}/accept-release': ['POST'],
+  '/api/comments/threads/{threadId}/anchor-trace': ['POST'],
   '/api/comments/threads/{threadId}/comments': ['POST'],
   '/api/comments/threads/{threadId}/reject': ['POST'],
   '/api/comments/threads/{threadId}/reopen': ['POST'],