@company-semantics/contracts 49.0.0 → 51.0.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": "49.0.0",
+  "version": "51.0.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",
@@ -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 = '6aca68a12d82' as const;
-export const SPEC_HASH_FULL = '6aca68a12d828a1efb9e1d1865a3955e8540d9c83563d2d6be6b04ae3eac7da1' as const;
+export const SPEC_HASH = '6dcd82441a54' as const;
+export const SPEC_HASH_FULL = '6dcd82441a54409faaa94d94f36a43cd72894c7e655fb49f5eb758a0963c9a43' 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,74 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/api/comments/threads/{threadId}/accept-intent": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /** Claim the acceptance lease on an open suggestion */
+        post: operations["acceptSuggestionIntent"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/api/comments/threads/{threadId}/accept-complete": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /** Record the accept decision by claim token */
+        post: operations["acceptSuggestionComplete"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/api/comments/threads/{threadId}/accept-release": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /** Release a held acceptance lease without deciding */
+        post: operations["releaseSuggestionClaim"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/api/comments/threads/{threadId}/reject": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /** Reject an open suggestion (or withdraw as its author) */
+        post: operations["rejectSuggestion"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
 }
 export type webhooks = Record<string, never>;
 export interface components {
@@ -4966,10 +5034,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. */
@@ -6397,7 +6466,16 @@ export interface components {
             /** Format: uuid */
             subjectId: string;
             anchor: components["schemas"]["CommentAnchor"];
-            body: string;
+            /** @enum {string} */
+            kind?: "comment" | "suggestion";
+            suggestion?: {
+                /** @constant */
+                v: 1;
+                /** @enum {string} */
+                op: "insert" | "delete" | "replace";
+                insertedText?: string;
+            };
+            body?: string;
             mentions?: {
                 /** Format: uuid */
                 userId: string;
@@ -6436,6 +6514,14 @@ export interface components {
         CommentThreadSummaryResponse: {
             thread: components["schemas"]["CommentThreadSummary"];
         };
+        /** @description The acceptance lease: the opaque claim token that alone can complete the accept, and how long the lease lives. */
+        SuggestionClaimResponse: {
+            claimToken: string;
+            leaseDurationMs: number;
+        };
+        SuggestionClaimRequest: {
+            claimToken: string;
+        };
         /** @description Server-enforced collaboration size limits, published so clients can pre-check. */
         CollabSyncLimits: {
             maxUpdateBytes: number;
@@ -6447,12 +6533,55 @@ 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" | "source_added" | "source_removed" | "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;
+        };
         /** @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;
@@ -6473,10 +6602,13 @@ export interface components {
             subjectType: "company_md" | "strategy_doc" | "work_item" | "meeting_recording";
             subjectId: string;
             /** @enum {string} */
-            anchorType: "document" | "text";
+            anchorType: "document" | "text" | "text-insertion";
             anchor: components["schemas"]["CommentAnchor"];
             /** @enum {string} */
             status: "open" | "resolved";
+            /** @enum {string} */
+            kind: "comment" | "suggestion";
+            suggestion: components["schemas"]["Suggestion"] | null;
             createdByUserId: string | null;
             resolvedByUserId: string | null;
             resolvedAt: string | null;
@@ -6484,7 +6616,7 @@ export interface components {
             updatedAt: string;
             comments: components["schemas"]["Comment"][];
         };
-        /** @description Opaque, versioned comment anchor: document-level, or a text anchor with a required quote and optional relative positions. */
+        /** @description Opaque, versioned comment anchor: document-level, a text anchor with a required quote and optional relative positions, or a zero-width text-insertion point for insert suggestions. */
         CommentAnchor: {
             /** @constant */
             type: "document";
@@ -6500,6 +6632,24 @@ export interface components {
             quote: string;
             prefix: string;
             suffix: string;
+        } | {
+            /** @constant */
+            type: "text-insertion";
+            /** @constant */
+            v: 1;
+            relPos?: string;
+            leftContext: string;
+            rightContext: string;
+        };
+        /** @description A suggested edit as proposed: the operation, its insertedText (insert/replace only), and the decision status composed from the thread row. */
+        Suggestion: {
+            /** @constant */
+            v: 1;
+            /** @enum {string} */
+            op: "insert" | "delete" | "replace";
+            insertedText?: string;
+            /** @enum {string} */
+            status: "open" | "accepted" | "rejected";
         };
         /** @description One comment; body is null iff soft-deleted (redacted projection with empty mentions). */
         Comment: {
@@ -6526,10 +6676,13 @@ export interface components {
             subjectType: "company_md" | "strategy_doc" | "work_item" | "meeting_recording";
             subjectId: string;
             /** @enum {string} */
-            anchorType: "document" | "text";
+            anchorType: "document" | "text" | "text-insertion";
             anchor: components["schemas"]["CommentAnchor"];
             /** @enum {string} */
             status: "open" | "resolved";
+            /** @enum {string} */
+            kind: "comment" | "suggestion";
+            suggestion: components["schemas"]["Suggestion"] | null;
             createdByUserId: string | null;
             resolvedByUserId: string | null;
             resolvedAt: string | null;
@@ -8970,7 +9123,7 @@ export interface operations {
             };
         };
     };
-    listCompanyMdDocVersions: {
+    listCompanyMdDocHistory: {
         parameters: {
             query?: {
                 cursor?: string;
@@ -8984,13 +9137,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 */
@@ -12635,6 +12788,13 @@ export interface operations {
                 };
                 content?: never;
             };
+            /** @description Not a comment thread: a suggestion is decided via accept or reject, never resolved */
+            409: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
         };
     };
     reopenCommentThread: {
@@ -12664,6 +12824,179 @@ export interface operations {
                 };
                 content?: never;
             };
+            /** @description Not a comment thread: a decided suggestion is terminal and never reopens */
+            409: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+        };
+    };
+    acceptSuggestionIntent: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                threadId: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Lease claimed: the opaque claim token (the only artifact that can complete the accept) and its duration */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["SuggestionClaimResponse"];
+                };
+            };
+            /** @description Thread not found, or the caller may not decide suggestions on it */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description Not a suggestion thread, already claimed by a live lease, or already decided */
+            409: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+        };
+    };
+    acceptSuggestionComplete: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                threadId: string;
+            };
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["SuggestionClaimRequest"];
+            };
+        };
+        responses: {
+            /** @description Suggestion accepted (thread resolved); valid after lease expiry and retry-safe for the same actor */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["CommentThreadSummaryResponse"];
+                };
+            };
+            /** @description Malformed claim token */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description Thread not found, or the caller may not read its subject */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description Not a suggestion thread, or the token does not match a live claim on an open suggestion */
+            409: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+        };
+    };
+    releaseSuggestionClaim: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                threadId: string;
+            };
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["SuggestionClaimRequest"];
+            };
+        };
+        responses: {
+            /** @description Lease released; the suggestion stays open and claimable */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["CommentThreadSummaryResponse"];
+                };
+            };
+            /** @description Malformed claim token */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description Thread not found, or the caller may not read its subject */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description Not a suggestion thread, or the token does not match a live claim on an open suggestion */
+            409: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+        };
+    };
+    rejectSuggestion: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                threadId: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Suggestion rejected (thread resolved) */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["CommentThreadSummaryResponse"];
+                };
+            };
+            /** @description Thread not found, or the caller may not decide suggestions on it */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description Not a suggestion thread, a live acceptance lease is held, or already decided */
+            409: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
         };
     };
 }

package/src/generated/openapi-routes.ts

@@ -23,7 +23,11 @@ export const openApiRoutes = {
   '/api/chats/{id}/pin': ['DELETE', 'POST'],
   '/api/comments': ['GET'],
   '/api/comments/threads': ['POST'],
+  '/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}/comments': ['POST'],
+  '/api/comments/threads/{threadId}/reject': ['POST'],
   '/api/comments/threads/{threadId}/reopen': ['POST'],
   '/api/comments/threads/{threadId}/resolve': ['POST'],
   '/api/comments/{commentId}': ['DELETE', 'PATCH'],
@@ -46,6 +50,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'],
@@ -53,7 +58,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",