@company-semantics/contracts 50.0.0 → 51.1.0

package/README.md

@@ -11,7 +11,10 @@ until they are proven stable.
 ## Usage
 
 ```typescript
-import type { IntentCategory, InsightConfidence } from '@company-semantics/contracts'
+import type {
+  IntentCategory,
+  InsightConfidence,
+} from "@company-semantics/contracts";
 ```
 
 ## What belongs here
@@ -33,6 +36,7 @@ It does not emit `.d.ts` files. Consumers are expected to compile TS.
 ## Versioning
 
 Follows semver:
+
 - Additive vocabulary → minor bump
 - Renaming or removal → major bump
 
@@ -41,6 +45,7 @@ Follows semver:
 Releases are published automatically via GitHub Actions.
 
 Steps:
+
 1. `npm version patch`
 2. `git push origin main --tags`
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@company-semantics/contracts",
-  "version": "50.0.0",
+  "version": "51.1.0",
   "private": false,
   "repository": {
     "type": "git",
@@ -88,8 +88,8 @@
     "typecheck:ci": "NODE_OPTIONS='--max-old-space-size=4096' tsc -p scripts/ci/tsconfig.json",
     "lint": "eslint src/ scripts/ tests/ __tests__/ vitest.config.ts",
     "lint:md": "markdownlint-cli2 '**/*.md' '#node_modules' '#.ralph/worktrees' '#.claude/worktrees'",
-    "format": "prettier --write src/",
-    "format:check": "prettier --check src/",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
     "lint:json": "node -e \"JSON.parse(require('fs').readFileSync('package.json'))\"",
     "prepare": "husky",
     "guard:export": "npx tsx scripts/ci/export-guard.ts",
@@ -101,9 +101,9 @@
     "guard:version-tag:json": "npx tsx scripts/ci/version-tag-guard.ts --json",
     "guard:decisions-deprecation": "npx tsx scripts/ci/decisions-deprecation-guard.ts",
     "guard:decisions-deprecation:json": "npx tsx scripts/ci/decisions-deprecation-guard.ts --json",
-    "guard:quick": "GUARD_DEPENDENCY_ROOT=../ tsx ../company-semantics-ci/run-guards.ts --config scripts/ci/guard-entries.ts --quick",
-    "ci:local": "pnpm typecheck && pnpm lint:md && pnpm guard:test && GUARD_DEPENDENCY_ROOT=../ pnpm guard",
-    "guard": "GUARD_DEPENDENCY_ROOT=../ tsx ../company-semantics-ci/run-guards.ts --config scripts/ci/guard-entries.ts",
+    "guard:quick": "sh scripts/ci/run-guard.sh --quick",
+    "ci:local": "pnpm typecheck && pnpm lint:md && pnpm guard:test && pnpm guard",
+    "guard": "sh scripts/ci/run-guard.sh",
     "guard:test": "NODE_OPTIONS='--max-old-space-size=4096' vitest run scripts/ci/__tests__",
     "release": "npx tsx scripts/release.ts",
     "prepublishOnly": "echo 'ERROR: Publishing is CI-only via tag push. Use pnpm release instead.' && exit 1",
@@ -120,13 +120,13 @@
     "generate:openapi-routes": "tsx scripts/generate-openapi-routes.ts",
     "generate:openapi-routes:check": "tsx scripts/generate-openapi-routes.ts --check",
     "generate:api-types:check": "openapi-typescript openapi/backend.yaml -o /tmp/cs-api-types-check.ts && diff -q src/api/generated.ts /tmp/cs-api-types-check.ts",
-    "generate:current": "tsx ../company-semantics-ci/scripts/generate-current.ts",
-    "adr:new": "tsx ../company-semantics-control/scripts/adr/adr-new-cli.ts",
-    "repo-map": "tsx ../company-semantics-ci/scripts/generate-repo-map.ts --roots src --name company-semantics-contracts --write",
-    "sync:workflow-pins": "tsx ../company-semantics-ci/scripts/sync-workflow-pins.ts --write",
-    "repo-map:check": "tsx ../company-semantics-ci/scripts/generate-repo-map.ts --roots src --name company-semantics-contracts --check",
-    "readme-api": "tsx ../company-semantics-ci/scripts/generate-readme-api.ts --roots src --write --jsdoc",
-    "readme-api:check": "tsx ../company-semantics-ci/scripts/generate-readme-api.ts --roots src --check --jsdoc",
+    "generate:current": "tsx \"$(git rev-parse --path-format=absolute --git-common-dir)/../../company-semantics-ci/scripts/generate-current.ts\"",
+    "adr:new": "tsx \"$(git rev-parse --path-format=absolute --git-common-dir)/../../company-semantics-control/scripts/adr/adr-new-cli.ts\"",
+    "repo-map": "tsx \"$(git rev-parse --path-format=absolute --git-common-dir)/../../company-semantics-ci/scripts/generate-repo-map.ts\" --roots src --name company-semantics-contracts --write",
+    "sync:workflow-pins": "tsx \"$(git rev-parse --path-format=absolute --git-common-dir)/../../company-semantics-ci/scripts/sync-workflow-pins.ts\" --write",
+    "repo-map:check": "tsx \"$(git rev-parse --path-format=absolute --git-common-dir)/../../company-semantics-ci/scripts/generate-repo-map.ts\" --roots src --name company-semantics-contracts --check",
+    "readme-api": "tsx \"$(git rev-parse --path-format=absolute --git-common-dir)/../../company-semantics-ci/scripts/generate-readme-api.ts\" --roots src --write --jsdoc",
+    "readme-api:check": "tsx \"$(git rev-parse --path-format=absolute --git-common-dir)/../../company-semantics-ci/scripts/generate-readme-api.ts\" --roots src --check --jsdoc",
     "validate:amp": "tsx scripts/validate-amp.ts"
   },
   "packageManager": "pnpm@10.25.0",
@@ -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"
@@ -159,7 +159,7 @@
     "overrides": {
       "brace-expansion@<5.0.9": ">=5.0.9",
       "minimatch@<10.2.3": ">=10.2.3",
-      "nanoid@<3.3.17": ">=3.3.17",
+      "nanoid@<3.3.18": ">=3.3.18",
       "js-yaml@>=4.0.0 <4.3.1": ">=4.3.1 <5.0.0",
       "js-yaml@>=5.0.0 <5.2.2": ">=5.2.2 <6.0.0",
       "ajv@<6.14.0": ">=6.14.0",
@@ -176,5 +176,5 @@
     "*.md": "markdownlint-cli2",
     "package.json": "node -e \"JSON.parse(require('fs').readFileSync('package.json'))\""
   },
-  "securityRequirementsVersion": "dfe68368cb5b7fdc67290fba5cd5a920c9a2ca9c20a9e297232a467b2022e5b5"
+  "securityRequirementsVersion": "2dcea336317c1136c8d94798b1cadc9c115febf574d041a173974a5f7959de0b"
 }

package/src/__tests__/resource-keys.test.ts

@@ -234,16 +234,16 @@ describe("resource-keys: companyMdAccessRequests (per-doc identity)", () => {
   });
 });
 
-describe("resource-keys: companyMdDocVersions (per-doc version list)", () => {
+describe("resource-keys: companyMdDocHistory (per-doc history list)", () => {
   const DOC_ID = "44444444-4444-4444-8444-444444444444";
   const key: ResourceKey = {
-    type: "companyMdDocVersions",
+    type: "companyMdDocHistory",
     orgId: ORG_ID,
     docId: DOC_ID,
   };
 
   it("serialises to [type, orgId, docId]", () => {
-    expect(toQueryKey(key)).toEqual(["companyMdDocVersions", ORG_ID, DOC_ID]);
+    expect(toQueryKey(key)).toEqual(["companyMdDocHistory", ORG_ID, DOC_ID]);
   });
 
   it("round-trips through fromQueryKey", () => {
@@ -261,7 +261,7 @@ describe("resource-keys: companyMdDocVersions (per-doc version list)", () => {
 
   it("does NOT collide with companyMdAccessRequests, which shares its shape", () => {
     // Same segments, same field name, same document — only the type tag tells
-    // the two apart. An owner's access-request inbox and a version list must
+    // the two apart. An owner's access-request inbox and a history list must
     // never invalidate each other.
     const requestsKey: ResourceKey = {
       type: "companyMdAccessRequests",
@@ -277,7 +277,7 @@ describe("resource-keys: companyMdDocVersion (composite version identity)", () =
   // The second composite member. Its identity is (docId, versionId), so it
   // exercises the same four-segment path `commentThreads` opened — and, unlike
   // that key, it has a SIBLING of the same doc scope one segment shorter
-  // (companyMdDocVersions), which is the collision the split exists to avoid.
+  // (companyMdDocHistory), which is the collision the split exists to avoid.
   const DOC_ID = "44444444-4444-4444-8444-444444444444";
   const VERSION_ID = "66666666-6666-4666-8666-666666666666";
   const key: ResourceKey = {
@@ -319,12 +319,12 @@ describe("resource-keys: companyMdDocVersion (composite version identity)", () =
     expect(matchesResourceKey(toQueryKey(key), other)).toBe(false);
   });
 
-  it("is NOT invalidated by a sweep of the document's version LIST", () => {
+  it("is NOT invalidated by a sweep of the document's history LIST", () => {
     // The whole reason the two members are distinct. A restore appends to the
-    // history and so invalidates `companyMdDocVersions`; the sealed bodies
+    // history and so invalidates `companyMdDocHistory`; the sealed bodies
     // already fetched are immutable and must survive it.
     const listKey: ResourceKey = {
-      type: "companyMdDocVersions",
+      type: "companyMdDocHistory",
       orgId: ORG_ID,
       docId: DOC_ID,
     };

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

package/src/api/generated.ts

@@ -1548,15 +1548,15 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
-    "/api/company-md/docs/{id}/versions": {
+    "/api/company-md/docs/{id}/history": {
         parameters: {
             query?: never;
             header?: never;
             path?: never;
             cookie?: never;
         };
-        /** List a company.md document’s version history (metadata only) */
-        get: operations["listCompanyMdDocVersions"];
+        /** List a company.md document’s merged history (versions and lifecycle events) */
+        get: operations["listCompanyMdDocHistory"];
         put?: never;
         post?: never;
         delete?: never;
@@ -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;
@@ -5034,10 +5051,11 @@ export interface components {
         CompanyMdMentionableResponse: {
             items: components["schemas"]["CompanyMdMentionableCandidate"][];
         };
-        /** @description A page of a company.md document’s version history, plus the opaque token a restore is gated on. */
-        CompanyMdDocVersionsResponse: {
+        /** @description A page of a company.md document’s merged History — versions and lifecycle events under one cursor — plus the opaque token a restore is gated on. */
+        CompanyMdDocHistoryResponse: {
             currentRevision: string;
-            entries: components["schemas"]["CompanyMdDocVersionEntry"][];
+            items: components["schemas"]["CompanyMdDocHistoryItem"][];
+            withheldCategories: ("version" | "source" | "lifecycle" | "access" | "sync")[];
             nextCursor: string | null;
         };
         /** @description One sealed company.md version — its metadata and the body it sealed. */
@@ -6513,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;
@@ -6532,12 +6553,56 @@ export interface components {
             displayName: string;
             avatarUrl: string | null;
         };
+        /** @description One item in a document’s merged History: a sealed version (or the in-progress session) nested as `version`, or a lifecycle event. */
+        CompanyMdDocHistoryItem: {
+            /** @constant */
+            kind: "version";
+            mergeId: string | null;
+            occurredAt: string;
+            /** @constant */
+            category: "version";
+            version: components["schemas"]["CompanyMdDocVersionEntry"];
+        } | {
+            /** @constant */
+            kind: "event";
+            mergeId: string;
+            occurredAt: string;
+            /** @enum {string} */
+            category: "version" | "source" | "lifecycle" | "access" | "sync";
+            /** @enum {string} */
+            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: {
             /** @enum {string} */
             type: "member" | "agent" | "system";
             userId: string;
         };
+        /** @description What a history event acted on: an ACL principal (member, unit, or the whole org) or the extracted source artifact. */
+        CompanyMdDocHistoryTarget: {
+            /** @constant */
+            type: "member";
+            userId: string;
+        } | {
+            /** @constant */
+            type: "unit";
+            unitId: string;
+        } | {
+            /** @constant */
+            type: "org";
+        } | {
+            /** @constant */
+            type: "source";
+            filename: string | null;
+            mime: string;
+            byteSize: number;
+        };
         /** @description An ACL-admitted context-doc discovery hit. */
         ContextDocDiscoveryHit: {
             id: string;
@@ -6568,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"][];
@@ -6642,6 +6708,7 @@ export interface components {
             createdByUserId: string | null;
             resolvedByUserId: string | null;
             resolvedAt: string | null;
+            lastAnchoredOffset: number | null;
             createdAt: string;
             updatedAt: string;
         };
@@ -9079,7 +9146,7 @@ export interface operations {
             };
         };
     };
-    listCompanyMdDocVersions: {
+    listCompanyMdDocHistory: {
         parameters: {
             query?: {
                 cursor?: string;
@@ -9093,13 +9160,13 @@ export interface operations {
         };
         requestBody?: never;
         responses: {
-            /** @description A page of version metadata, plus the document’s live revision token */
+            /** @description A page of merged history items, plus the document’s live revision token and the categories withheld for this reader */
             200: {
                 headers: {
                     [name: string]: unknown;
                 };
                 content: {
-                    "application/json": components["schemas"]["CompanyMdDocVersionsResponse"];
+                    "application/json": components["schemas"]["CompanyMdDocHistoryResponse"];
                 };
             };
             /** @description Invalid cursor or limit */
@@ -12789,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'],
@@ -50,6 +51,7 @@ export const openApiRoutes = {
   '/api/company-md/docs/{id}/context-bank/upload': ['POST'],
   '/api/company-md/docs/{id}/context-bank/{contextDocId}': ['DELETE'],
   '/api/company-md/docs/{id}/context-bank/{contextDocId}/order': ['PATCH'],
+  '/api/company-md/docs/{id}/history': ['GET'],
   '/api/company-md/docs/{id}/mentionable': ['GET'],
   '/api/company-md/docs/{id}/sharing': ['GET'],
   '/api/company-md/docs/{id}/sharing/acl': ['POST'],
@@ -57,7 +59,6 @@ export const openApiRoutes = {
   '/api/company-md/docs/{id}/sharing/policy': ['PUT'],
   '/api/company-md/docs/{id}/title': ['PUT'],
   '/api/company-md/docs/{id}/transfer-owner': ['POST'],
-  '/api/company-md/docs/{id}/versions': ['GET'],
   '/api/company-md/docs/{id}/versions/{versionId}': ['GET'],
   '/api/company-md/docs/{id}/versions/{versionId}/restore': ['POST'],
   '/api/company-md/extract': ['POST'],

package/src/resource-key-types.ts

@@ -38,16 +38,19 @@ export type ResourceKey =
   // a bare slug does not identify a document. That field name is a wart to be
   // contained, not propagated — a new key gets the honest name.
   | { type: "companyMdAccessRequests"; orgId: string; docId: string }
-  // The sealed version history of ONE document (PRD-00927) — the metadata-only
-  // list the history panel pages through. Keyed by `docId` for the same reason
-  // `companyMdAccessRequests` is: the honest name for the stable document id,
-  // rather than propagating `companyMdDoc`'s legacy `slug` field name.
-  | { type: "companyMdDocVersions"; orgId: string; docId: string }
+  // The merged history feed of ONE document (PRD-00938) — sealed versions plus
+  // lifecycle events, the metadata-only list the history panel pages through.
+  // Named `companyMdDocHistory`, not `companyMdDocVersions`: the history is the
+  // list, a version is a thing in it (see `companyMdDocVersion` below). Keyed by
+  // `docId` for the same reason `companyMdAccessRequests` is: the honest name
+  // for the stable document id, rather than propagating `companyMdDoc`'s legacy
+  // `slug` field name.
+  | { type: "companyMdDocHistory"; orgId: string; docId: string }
   // ONE sealed version, body included.
   //
   // A member of its own rather than a `versionId` segment folded into the list
   // key above, and the split is load-bearing. A restore APPENDS to the history,
-  // so it must invalidate `companyMdDocVersions` — and because a sealed version
+  // so it must invalidate `companyMdDocHistory` — and because a sealed version
   // is immutable, every already-fetched body must SURVIVE that invalidation.
   // Fold the two together and each restore evicts the whole set of historical
   // bodies the reader just paged through, to re-fetch content that cannot have

package/src/resource-keys.ts

@@ -96,7 +96,7 @@ const IDENTITY_FIELDS = {
   companyMdDoc: "slug",
   companyMdContextBank: "slug",
   companyMdAccessRequests: "docId",
-  companyMdDocVersions: "docId",
+  companyMdDocHistory: "docId",
   orgUnit: "unitId",
   orgUnitChildren: "unitId",
   orgUnitAncestors: "unitId",
@@ -226,7 +226,7 @@ export function toQueryKey(key: ResourceKey): readonly string[] {
     case "companyMdContextBank":
       return [key.type, key.orgId, key.slug] as const;
     case "companyMdAccessRequests":
-    case "companyMdDocVersions":
+    case "companyMdDocHistory":
       return [key.type, key.orgId, key.docId] as const;
 
     // Composite identity — subject CLASS then subject id, in that order, so the

package/src/resource-registry.ts

@@ -60,7 +60,7 @@ export type ResourceEntryInput = z.input<typeof ResourceEntrySchema>;
  *
  * TWO VOCABULARY CAVEATS, both deliberate and both for ADR-CONTRACTS-120:
  *
- *  1. `resource` here is the {@link ResourceKey} type TAG (`companyMdDocVersions`).
+ *  1. `resource` here is the {@link ResourceKey} type TAG (`companyMdDocHistory`).
  *     The registry that currently holds live rows is the app's copy, and its
  *     `resource` values are PATH-shaped (`company-md/docs`, `orgs/:orgId/billing`).
  *     The two do not line up, and reconciling them is not this PRD's work —
@@ -73,8 +73,9 @@ export const COMPANY_MD_VERSION_RESOURCE_ENTRIES = [
   {
     // The history panel is opened, never hydrated with the page — hence
     // background/P3. A restore appends to this list, so it is the row that
-    // takes the invalidation.
-    resource: "companyMdDocVersions",
+    // takes the invalidation. The history is the list, a version is a thing
+    // in it — hence `companyMdDocHistory` here and `companyMdDocVersion` below.
+    resource: "companyMdDocHistory",
     priority: "P3",
     hydrationPhase: "background",
     hydrationDepends: [],
@@ -96,7 +97,7 @@ export const COMPANY_MD_VERSION_RESOURCE_ENTRIES = [
     resource: "companyMdDocVersion",
     priority: "P3",
     hydrationPhase: "background",
-    hydrationDepends: ["companyMdDocVersions"],
+    hydrationDepends: ["companyMdDocHistory"],
     mutationBehavior: "serial",
     staleTimeMs: 300_000,
     degradationSection: "core",