@company-semantics/contracts 47.1.1 → 47.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@company-semantics/contracts",
-  "version": "47.1.1",
+  "version": "47.2.0",
   "private": false,
   "repository": {
     "type": "git",
@@ -148,10 +148,10 @@
     "markdownlint-cli2": "^0.23.2",
     "openapi-typescript": "^7.13.0",
     "prettier": "^3.9.6",
-    "tsx": "^4.23.1",
+    "tsx": "^4.23.11",
     "typescript": "^5.8.3",
     "typescript-eslint": "^8.66.0",
-    "vite": "^8.2.0",
+    "vite": "^8.2.1",
     "vitest": "^4.1.10",
     "yaml": "^2.9.0"
   },

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

@@ -234,6 +234,110 @@ describe("resource-keys: companyMdAccessRequests (per-doc identity)", () => {
   });
 });
 
+describe("resource-keys: companyMdDocVersions (per-doc version list)", () => {
+  const DOC_ID = "44444444-4444-4444-8444-444444444444";
+  const key: ResourceKey = {
+    type: "companyMdDocVersions",
+    orgId: ORG_ID,
+    docId: DOC_ID,
+  };
+
+  it("serialises to [type, orgId, docId]", () => {
+    expect(toQueryKey(key)).toEqual(["companyMdDocVersions", ORG_ID, DOC_ID]);
+  });
+
+  it("round-trips through fromQueryKey", () => {
+    expect(fromQueryKey(toQueryKey(key))).toEqual(key);
+  });
+
+  it("discriminates two keys differing only in docId", () => {
+    const other: ResourceKey = {
+      ...key,
+      docId: "55555555-5555-4555-8555-555555555555",
+    };
+    expect(matchesResourceKey(toQueryKey(key), key)).toBe(true);
+    expect(matchesResourceKey(toQueryKey(other), key)).toBe(false);
+  });
+
+  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
+    // never invalidate each other.
+    const requestsKey: ResourceKey = {
+      type: "companyMdAccessRequests",
+      orgId: ORG_ID,
+      docId: DOC_ID,
+    };
+    expect(matchesResourceKey(toQueryKey(requestsKey), key)).toBe(false);
+    expect(matchesResourceKey(toQueryKey(key), requestsKey)).toBe(false);
+  });
+});
+
+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.
+  const DOC_ID = "44444444-4444-4444-8444-444444444444";
+  const VERSION_ID = "66666666-6666-4666-8666-666666666666";
+  const key: ResourceKey = {
+    type: "companyMdDocVersion",
+    orgId: ORG_ID,
+    docId: DOC_ID,
+    versionId: VERSION_ID,
+  };
+
+  it("serialises to [type, orgId, docId, versionId]", () => {
+    const qk = toQueryKey(key);
+    expect(qk).toEqual(["companyMdDocVersion", ORG_ID, DOC_ID, VERSION_ID]);
+    expect(qk).toHaveLength(4);
+  });
+
+  it("round-trips through fromQueryKey", () => {
+    expect(fromQueryKey(toQueryKey(key))).toEqual(key);
+  });
+
+  it("is recognised by isResourceKeyShape", () => {
+    expect(isResourceKeyShape(key)).toBe(true);
+  });
+
+  it("discriminates two versions of the same document", () => {
+    const other: ResourceKey = {
+      ...key,
+      versionId: "77777777-7777-4777-8777-777777777777",
+    };
+    expect(matchesResourceKey(toQueryKey(key), key)).toBe(true);
+    expect(matchesResourceKey(toQueryKey(other), key)).toBe(false);
+  });
+
+  it("discriminates the same versionId under two different documents", () => {
+    const other: ResourceKey = {
+      ...key,
+      docId: "55555555-5555-4555-8555-555555555555",
+    };
+    expect(matchesResourceKey(toQueryKey(other), key)).toBe(false);
+    expect(matchesResourceKey(toQueryKey(key), other)).toBe(false);
+  });
+
+  it("is NOT invalidated by a sweep of the document's version LIST", () => {
+    // The whole reason the two members are distinct. A restore appends to the
+    // history and so invalidates `companyMdDocVersions`; the sealed bodies
+    // already fetched are immutable and must survive it.
+    const listKey: ResourceKey = {
+      type: "companyMdDocVersions",
+      orgId: ORG_ID,
+      docId: DOC_ID,
+    };
+    expect(matchesResourceKey(toQueryKey(key), listKey)).toBe(false);
+  });
+
+  it("refuses a query key that is missing the version segment", () => {
+    expect(() => fromQueryKey(["companyMdDocVersion", ORG_ID, DOC_ID])).toThrow(
+      /companyMdDocVersion/,
+    );
+  });
+});
+
 describe("resource-keys: commentThreads (composite subject identity)", () => {
   // The FIRST member of the union whose identity needs two segments. Every
   // other key is [type, scope] or [type, scope, oneId], and `fromQueryKey`'s

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 = '018976cde74a' as const;
-export const SPEC_HASH_FULL = '018976cde74aa4a20c06c5fb333963bf58199fba93d623cd89cf2a360d95eceb' as const;
+export const SPEC_HASH = '6aca68a12d82' as const;
+export const SPEC_HASH_FULL = '6aca68a12d828a1efb9e1d1865a3955e8540d9c83563d2d6be6b04ae3eac7da1' as const;

package/src/api/generated.ts

@@ -1548,6 +1548,57 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/api/company-md/docs/{id}/versions": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /** List a company.md document’s version history (metadata only) */
+        get: operations["listCompanyMdDocVersions"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/api/company-md/docs/{id}/versions/{versionId}": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /** Read one sealed company.md version, body included */
+        get: operations["getCompanyMdDocVersion"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/api/company-md/docs/{id}/versions/{versionId}/restore": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /** Restore a company.md document to a previous version */
+        post: operations["restoreCompanyMdDocVersion"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/api/company-md/extract": {
         parameters: {
             query?: never;
@@ -4915,6 +4966,51 @@ 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: {
+            currentRevision: string;
+            entries: components["schemas"]["CompanyMdDocVersionEntry"][];
+            nextCursor: string | null;
+        };
+        /** @description One sealed company.md version — its metadata and the body it sealed. */
+        CompanyMdDocVersionContent: {
+            id: string | null;
+            /** @enum {string} */
+            status: "sealed" | "open";
+            /** @enum {string} */
+            mutationSource: "human_edit" | "agent_edit" | "ingest" | "restore" | "system" | "baseline";
+            sourceOperationId: string | null;
+            actor: components["schemas"]["CompanyMdDocVersionActor"] | null;
+            contributors: string[];
+            initiatedBy: string | null;
+            sessionStartedAt: string;
+            sessionEndedAt: string;
+            contentBytes: number;
+            restoredFromVersionId: string | null;
+            isCurrent: boolean;
+            content: string;
+        };
+        /** @description One sealed version, or the in-progress session, as metadata only. */
+        CompanyMdDocVersionEntry: {
+            id: string | null;
+            /** @enum {string} */
+            status: "sealed" | "open";
+            /** @enum {string} */
+            mutationSource: "human_edit" | "agent_edit" | "ingest" | "restore" | "system" | "baseline";
+            sourceOperationId: string | null;
+            actor: components["schemas"]["CompanyMdDocVersionActor"] | null;
+            contributors: string[];
+            initiatedBy: string | null;
+            sessionStartedAt: string;
+            sessionEndedAt: string;
+            contentBytes: number;
+            restoredFromVersionId: string | null;
+            isCurrent: boolean;
+        };
+        /** @description The document revision the client believes it is restoring over. A mismatch is a 409. */
+        RestoreCompanyMdDocVersionRequest: {
+            expectedRevision: string;
+        };
         CompanyMdContextBankResponse: {
             items: {
                 id: string;
@@ -6351,6 +6447,12 @@ export interface components {
             displayName: string;
             avatarUrl: string | null;
         };
+        /** @description The singular actor a version is attributed to, in product vocabulary. */
+        CompanyMdDocVersionActor: {
+            /** @enum {string} */
+            type: "member" | "agent" | "system";
+            userId: string;
+        };
         /** @description An ACL-admitted context-doc discovery hit. */
         ContextDocDiscoveryHit: {
             id: string;
@@ -8868,6 +8970,123 @@ export interface operations {
             };
         };
     };
+    listCompanyMdDocVersions: {
+        parameters: {
+            query?: {
+                cursor?: string;
+                limit?: number;
+            };
+            header?: never;
+            path: {
+                id: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description A page of version metadata, plus the document’s live revision token */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["CompanyMdDocVersionsResponse"];
+                };
+            };
+            /** @description Invalid cursor or limit */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description Document not found, or the caller may not read its body */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+        };
+    };
+    getCompanyMdDocVersion: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                id: string;
+                versionId: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description The version’s metadata and the body it sealed */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["CompanyMdDocVersionContent"];
+                };
+            };
+            /** @description Document or version not found, or its body is withheld */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+        };
+    };
+    restoreCompanyMdDocVersion: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                id: string;
+                versionId: string;
+            };
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["RestoreCompanyMdDocVersionRequest"];
+            };
+        };
+        responses: {
+            /** @description The restore version that was appended to the document’s history */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["CompanyMdDocVersionEntry"];
+                };
+            };
+            /** @description Missing or malformed expectedRevision */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description Document or version not found, or the caller may not edit it */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description The document changed since the caller read its revision */
+            409: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+        };
+    };
     extractCompanyMd: {
         parameters: {
             query?: never;

package/src/generated/openapi-routes.ts

@@ -53,6 +53,9 @@ 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'],
   '/api/company-md/ownership/reassign': ['POST'],
   '/api/company-md/ownership/reassign/suggestion': ['GET'],

package/src/resource-key-types.ts

@@ -0,0 +1,157 @@
+/**
+ * ResourceKey — the shared resource VOCABULARY: one union member per resource
+ * the system can name, address, and invalidate.
+ *
+ * Split out of resource-keys.ts, which owns the OPERATIONS over these keys
+ * (scope resolution, the query-key round trip, matching). The union is a
+ * registry that grows one member at a time and carries a paragraph of rationale
+ * per non-obvious member; the operations are a fixed set of functions. They
+ * change for entirely different reasons, and only the union is appended to on
+ * essentially every resource addition.
+ *
+ * All keys MUST include scope (orgId or userId) to prevent cross-org cache leaks.
+ * Naming: camelCase nouns. Collections plural, identities singular.
+ */
+export type ResourceKey =
+  // Collections (plural) — lists of entities
+  | { type: "members"; orgId: string }
+  | { type: "departments"; orgId: string }
+  | { type: "chats"; orgId: string }
+  | { type: "teams"; orgId: string }
+  | { type: "integrations"; orgId: string }
+  | { type: "invites"; orgId: string }
+  | { type: "auditEvents"; orgId: string }
+  | { type: "timeline"; orgId: string }
+  // Identities (singular) — single entities
+  | { type: "member"; orgId: string; memberId: string }
+  | { type: "team"; orgId: string; teamId: string }
+  | { type: "department"; orgId: string; departmentId: string }
+  | { type: "chat"; orgId: string; chatId: string }
+  | { type: "companyMdDoc"; orgId: string; slug: string }
+  | { type: "companyMdContextBank"; orgId: string; slug: string }
+  // The access requests filed against ONE document — the owner's inbox, read by
+  // the Share dialog.
+  //
+  // Discriminated by `docId`, NOT `slug`, and the difference is load-bearing.
+  // `companyMdDoc` above carries the stable doc id under a field named `slug`
+  // for historical reasons; ADR-BE-315 made slugs only PARENT-SCOPED unique, so
+  // 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 }
+  // 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
+  // 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
+  // changed.
+  | {
+      type: "companyMdDocVersion";
+      orgId: string;
+      docId: string;
+      versionId: string;
+    }
+  // The comment threads hanging off ONE subject (ADR-CONTRACTS-116).
+  //
+  // Registered here rather than declared app-locally because THE KEY REGISTRY IS
+  // THE SSE COALESCER'S VOCABULARY: a `resource.invalidated` frame names a key,
+  // and a key the registry does not know cannot be routed through the coalescer
+  // at all. An app-local "commentThreads" would be a second vocabulary the
+  // server could never address.
+  //
+  // The only member with a TWO-SEGMENT identity, and it has to be: a thread
+  // list is addressed by (subjectType, subjectId), and the id alone is not
+  // enough — subject ids are per-class uuids, so two classes could collide and
+  // one subject's invalidation would flush another's cache. `subjectType` is
+  // typed `string` and not the closed `CommentSubjectType`: this is a cache
+  // vocabulary, `fromQueryKey` reconstructs keys from arbitrary wire strings,
+  // and narrowing it here would make that reconstruction a lie.
+  | {
+      type: "commentThreads";
+      orgId: string;
+      subjectType: string;
+      subjectId: string;
+    }
+  | { type: "workspace"; orgId: string }
+  | { type: "workspaceDomains"; orgId: string }
+  | { type: "authSettings"; orgId: string }
+  | { type: "billing"; orgId: string }
+  | { type: "aiUsage"; orgId: string }
+  | { type: "deletionEligibility"; orgId: string }
+  | { type: "transferOwnership"; orgId: string }
+  | { type: "companyMdDocs"; orgId: string }
+  // Directly-granted (non-inherited) ACL rows for the org, read by the admin
+  // grants surface (ADR-CONTRACTS-119).
+  | { type: "directGrants"; orgId: string }
+  // OrgUnit canonical model (ADR-BE-120) — Phase 2 Wave 4
+  | { type: "orgTree"; orgId: string }
+  | { type: "orgLevelConfig"; orgId: string }
+  | { type: "orgUnit"; orgId: string; unitId: string }
+  | { type: "orgUnitChildren"; orgId: string; unitId: string }
+  | { type: "orgUnitAncestors"; orgId: string; unitId: string }
+  | { type: "orgUnitMemberships"; orgId: string; unitId: string }
+  | { type: "orgUnitPermissions"; orgId: string; unitId: string }
+  // Open roles seated in a unit (ADR-BE-277) — a per-unit list, unitId-scoped
+  // like memberships/permissions. Read in the unit members view and the
+  // org-chart card; refreshed as a graph target of orgTree on structural
+  // mutations (create / advance lifecycle / fill). See ADR-CONTRACTS-065.
+  | { type: "orgUnitOpenRoles"; orgId: string; unitId: string }
+  // Org-unit owners list (ADR-CONTRACTS-052) — owners are an org-wide
+  // projection, not a per-unit collection, so unitId is intentionally excluded.
+  | { type: "orgUnitOwners"; orgId: string }
+  // THIS VIEWER'S authority over one unit (ADR-CONTRACTS-119) — what the viewer
+  // may do here, not what the unit's permission rows say. Deliberately distinct
+  // from `orgUnitPermissions`: same subject, different resource and different
+  // invalidation trigger (a membership change alters the viewer's authority
+  // without touching the unit's rows), the `actionItems`/`feed` split above.
+  | { type: "orgUnitMyAuthority"; orgId: string; unitId: string }
+  // People reporting (ADR-BE-166) — drives the settings Org chart drill-down
+  | { type: "peopleOrgChart"; orgId: string }
+  // System-scoped (ADR-CONTRACTS-052) — tenant-less super-admin resources.
+  // No orgId/userId: these live above any single org. scope is the literal 'system'.
+  | { type: "internalAdminAiProviders"; scope: "system" }
+  | { type: "internalAdminPrompts"; scope: "system" }
+  | { type: "internalAdminAiRuntimeDefaults"; scope: "system" }
+  // Software-factory surfaces (ADR-BE-239 / ADR-BE-243) — internal-admin
+  // dashboard reads over Global-infra factory tables; tenant-less, scope 'system'.
+  | { type: "factoryFloor"; scope: "system" }
+  | { type: "factorySnapshot"; scope: "system" }
+  // The KPI rollup over the same factory tables (ADR-CONTRACTS-119). Registered
+  // late: the app shipped it as a double-cast key literal, and because
+  // `useResource` disables a query whose `toQueryKey` throws, the panel it backs
+  // never fetched at all. An unregistered key is not a stale read, it is no read.
+  | { type: "factoryKpis"; scope: "system" }
+  // Everything awaiting the viewer's decision, across every domain
+  // (ADR-CONT-104). ORG-scoped, not user-scoped, even though the content is
+  // per-viewer: the bucket differs per org, so a user-keyed entry would serve
+  // one org's items after switching to another. Same shape as `chats` and
+  // `timeline`, which are likewise viewer-filtered but org-partitioned — and it
+  // inherits `resolveScope`'s impersonation handling for free.
+  | { type: "actionItems"; orgId: string }
+  // The merged top-of-/me/work read: action items AND the durable inbox
+  // (ADR-CONT-108). Org-scoped for the same reason `actionItems` is — the
+  // content is per-viewer but the bucket differs per org, so a user-keyed entry
+  // would serve one org's feed after switching to another.
+  //
+  // Distinct from `actionItems` rather than replacing it: that key still backs
+  // every badge in the shell, and the two have different invalidation triggers
+  // (a notification being READ changes the feed and not the bucket).
+  | { type: "feed"; orgId: string }
+  // User-scoped
+  | { type: "dismissedBanners"; userId: string }
+  | { type: "userOrgs"; userId: string }
+  | { type: "sessions"; userId: string }
+  // The viewer's personal doc (`/api/me/md`) — a per-user singleton, so it is
+  // keyed by userId alone with no doc identity segment. Its PAYLOAD is a work
+  // item, lazily materialized on first read (ADR-BE-487), but the resource is
+  // "this user's personal doc", not "work item <id>": a future generic
+  // `workItem` key would be a different resource with a different identity.
+  | { type: "userMd"; userId: string }
+  | { type: "viewer"; userId: string };

package/src/resource-keys.ts

@@ -1,131 +1,14 @@
 /**
- * ResourceKey — shared vocabulary for resources across the system.
- * All keys MUST include scope (orgId or userId) to prevent cross-org cache leaks.
- * Naming: camelCase nouns. Collections plural, identities singular.
+ * ResourceKey operations — scope resolution, the query-key round trip, and
+ * shape/identity matching.
+ *
+ * The union itself lives in `resource-key-types.ts` and is re-exported here, so
+ * `./resource-keys` remains the one import path for the whole vocabulary
+ * (the package barrel and every consumer reach for it through this module).
  */
-export type ResourceKey =
-  // Collections (plural) — lists of entities
-  | { type: "members"; orgId: string }
-  | { type: "departments"; orgId: string }
-  | { type: "chats"; orgId: string }
-  | { type: "teams"; orgId: string }
-  | { type: "integrations"; orgId: string }
-  | { type: "invites"; orgId: string }
-  | { type: "auditEvents"; orgId: string }
-  | { type: "timeline"; orgId: string }
-  // Identities (singular) — single entities
-  | { type: "member"; orgId: string; memberId: string }
-  | { type: "team"; orgId: string; teamId: string }
-  | { type: "department"; orgId: string; departmentId: string }
-  | { type: "chat"; orgId: string; chatId: string }
-  | { type: "companyMdDoc"; orgId: string; slug: string }
-  | { type: "companyMdContextBank"; orgId: string; slug: string }
-  // The access requests filed against ONE document — the owner's inbox, read by
-  // the Share dialog.
-  //
-  // Discriminated by `docId`, NOT `slug`, and the difference is load-bearing.
-  // `companyMdDoc` above carries the stable doc id under a field named `slug`
-  // for historical reasons; ADR-BE-315 made slugs only PARENT-SCOPED unique, so
-  // 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 comment threads hanging off ONE subject (ADR-CONTRACTS-116).
-  //
-  // Registered here rather than declared app-locally because THE KEY REGISTRY IS
-  // THE SSE COALESCER'S VOCABULARY: a `resource.invalidated` frame names a key,
-  // and a key the registry does not know cannot be routed through the coalescer
-  // at all. An app-local "commentThreads" would be a second vocabulary the
-  // server could never address.
-  //
-  // The only member with a TWO-SEGMENT identity, and it has to be: a thread
-  // list is addressed by (subjectType, subjectId), and the id alone is not
-  // enough — subject ids are per-class uuids, so two classes could collide and
-  // one subject's invalidation would flush another's cache. `subjectType` is
-  // typed `string` and not the closed `CommentSubjectType`: this is a cache
-  // vocabulary, `fromQueryKey` reconstructs keys from arbitrary wire strings,
-  // and narrowing it here would make that reconstruction a lie.
-  | {
-      type: "commentThreads";
-      orgId: string;
-      subjectType: string;
-      subjectId: string;
-    }
-  | { type: "workspace"; orgId: string }
-  | { type: "workspaceDomains"; orgId: string }
-  | { type: "authSettings"; orgId: string }
-  | { type: "billing"; orgId: string }
-  | { type: "aiUsage"; orgId: string }
-  | { type: "deletionEligibility"; orgId: string }
-  | { type: "transferOwnership"; orgId: string }
-  | { type: "companyMdDocs"; orgId: string }
-  // Directly-granted (non-inherited) ACL rows for the org, read by the admin
-  // grants surface (ADR-CONTRACTS-119).
-  | { type: "directGrants"; orgId: string }
-  // OrgUnit canonical model (ADR-BE-120) — Phase 2 Wave 4
-  | { type: "orgTree"; orgId: string }
-  | { type: "orgLevelConfig"; orgId: string }
-  | { type: "orgUnit"; orgId: string; unitId: string }
-  | { type: "orgUnitChildren"; orgId: string; unitId: string }
-  | { type: "orgUnitAncestors"; orgId: string; unitId: string }
-  | { type: "orgUnitMemberships"; orgId: string; unitId: string }
-  | { type: "orgUnitPermissions"; orgId: string; unitId: string }
-  // Open roles seated in a unit (ADR-BE-277) — a per-unit list, unitId-scoped
-  // like memberships/permissions. Read in the unit members view and the
-  // org-chart card; refreshed as a graph target of orgTree on structural
-  // mutations (create / advance lifecycle / fill). See ADR-CONTRACTS-065.
-  | { type: "orgUnitOpenRoles"; orgId: string; unitId: string }
-  // Org-unit owners list (ADR-CONTRACTS-052) — owners are an org-wide
-  // projection, not a per-unit collection, so unitId is intentionally excluded.
-  | { type: "orgUnitOwners"; orgId: string }
-  // THIS VIEWER'S authority over one unit (ADR-CONTRACTS-119) — what the viewer
-  // may do here, not what the unit's permission rows say. Deliberately distinct
-  // from `orgUnitPermissions`: same subject, different resource and different
-  // invalidation trigger (a membership change alters the viewer's authority
-  // without touching the unit's rows), the `actionItems`/`feed` split above.
-  | { type: "orgUnitMyAuthority"; orgId: string; unitId: string }
-  // People reporting (ADR-BE-166) — drives the settings Org chart drill-down
-  | { type: "peopleOrgChart"; orgId: string }
-  // System-scoped (ADR-CONTRACTS-052) — tenant-less super-admin resources.
-  // No orgId/userId: these live above any single org. scope is the literal 'system'.
-  | { type: "internalAdminAiProviders"; scope: "system" }
-  | { type: "internalAdminPrompts"; scope: "system" }
-  | { type: "internalAdminAiRuntimeDefaults"; scope: "system" }
-  // Software-factory surfaces (ADR-BE-239 / ADR-BE-243) — internal-admin
-  // dashboard reads over Global-infra factory tables; tenant-less, scope 'system'.
-  | { type: "factoryFloor"; scope: "system" }
-  | { type: "factorySnapshot"; scope: "system" }
-  // The KPI rollup over the same factory tables (ADR-CONTRACTS-119). Registered
-  // late: the app shipped it as a double-cast key literal, and because
-  // `useResource` disables a query whose `toQueryKey` throws, the panel it backs
-  // never fetched at all. An unregistered key is not a stale read, it is no read.
-  | { type: "factoryKpis"; scope: "system" }
-  // Everything awaiting the viewer's decision, across every domain
-  // (ADR-CONT-104). ORG-scoped, not user-scoped, even though the content is
-  // per-viewer: the bucket differs per org, so a user-keyed entry would serve
-  // one org's items after switching to another. Same shape as `chats` and
-  // `timeline`, which are likewise viewer-filtered but org-partitioned — and it
-  // inherits `resolveScope`'s impersonation handling for free.
-  | { type: "actionItems"; orgId: string }
-  // The merged top-of-/me/work read: action items AND the durable inbox
-  // (ADR-CONT-108). Org-scoped for the same reason `actionItems` is — the
-  // content is per-viewer but the bucket differs per org, so a user-keyed entry
-  // would serve one org's feed after switching to another.
-  //
-  // Distinct from `actionItems` rather than replacing it: that key still backs
-  // every badge in the shell, and the two have different invalidation triggers
-  // (a notification being READ changes the feed and not the bucket).
-  | { type: "feed"; orgId: string }
-  // User-scoped
-  | { type: "dismissedBanners"; userId: string }
-  | { type: "userOrgs"; userId: string }
-  | { type: "sessions"; userId: string }
-  // The viewer's personal doc (`/api/me/md`) — a per-user singleton, so it is
-  // keyed by userId alone with no doc identity segment. Its PAYLOAD is a work
-  // item, lazily materialized on first read (ADR-BE-487), but the resource is
-  // "this user's personal doc", not "work item <id>": a future generic
-  // `workItem` key would be a different resource with a different identity.
-  | { type: "userMd"; userId: string }
-  | { type: "viewer"; userId: string };
+
+export type { ResourceKey } from "./resource-key-types";
+import type { ResourceKey } from "./resource-key-types";
 
 /**
  * Action — structured mutation key used across execution system, audit, permissions.
@@ -213,6 +96,7 @@ const IDENTITY_FIELDS = {
   companyMdDoc: "slug",
   companyMdContextBank: "slug",
   companyMdAccessRequests: "docId",
+  companyMdDocVersions: "docId",
   orgUnit: "unitId",
   orgUnitChildren: "unitId",
   orgUnitAncestors: "unitId",
@@ -233,6 +117,7 @@ const IDENTITY_FIELDS = {
  */
 const COMPOSITE_IDENTITY_FIELDS = {
   commentThreads: ["subjectType", "subjectId"],
+  companyMdDocVersion: ["docId", "versionId"],
 } as const satisfies {
   [T in ResourceKey["type"]]?: readonly IdentityFieldsOf<T>[];
 };
@@ -341,6 +226,7 @@ export function toQueryKey(key: ResourceKey): readonly string[] {
     case "companyMdContextBank":
       return [key.type, key.orgId, key.slug] as const;
     case "companyMdAccessRequests":
+    case "companyMdDocVersions":
       return [key.type, key.orgId, key.docId] as const;
 
     // Composite identity — subject CLASS then subject id, in that order, so the
@@ -349,6 +235,12 @@ export function toQueryKey(key: ResourceKey): readonly string[] {
     case "commentThreads":
       return [key.type, key.orgId, key.subjectType, key.subjectId] as const;
 
+    // Composite identity — the document, then the version within it. Outer
+    // scope first, same ordering rule as `commentThreads`, so the segments read
+    // in the order the URL that produced them spells: /docs/{id}/versions/{v}.
+    case "companyMdDocVersion":
+      return [key.type, key.orgId, key.docId, key.versionId] as const;
+
     // OrgUnit identity keys (ADR-BE-120)
     case "orgUnit":
     case "orgUnitChildren":

package/src/resource-registry.ts

@@ -35,3 +35,72 @@ export const ResourceEntrySchema = z
 
 export type ResourceEntry = z.infer<typeof ResourceEntrySchema>;
 export type ResourceRegistry = ReadonlyMap<ResourceKey, ResourceEntry>;
+
+/**
+ * The shape a row is WRITTEN in, before the schema's branding transforms run.
+ *
+ * `ResourceEntry` is the PARSED form: `resource`, `staleTimeMs` and friends come
+ * out branded, and nothing hand-authored can ever be assignable to a brand. So
+ * `z.input` is the only type a literal row can be checked against — which is
+ * what makes the `satisfies` below a real check and not decoration.
+ */
+export type ResourceEntryInput = z.input<typeof ResourceEntrySchema>;
+
+/**
+ * Company.md version-history rows (PRD-00927) — the first rows this registry has
+ * carried since it was introduced as a schema with no entries.
+ *
+ * Exported as CHECKED LITERALS rather than a built `ResourceRegistry` Map on
+ * purpose. Building the Map means running `ResourceEntrySchema.parse` at module
+ * load to obtain the branded values, and this package is types-first: every
+ * consumer would pay that at import time to read a table that is fully known at
+ * compile time. `satisfies readonly ResourceEntryInput[]` gets the same
+ * field-level enforcement for free, and a consumer that wants the Map can parse
+ * these rows itself.
+ *
+ * TWO VOCABULARY CAVEATS, both deliberate and both for ADR-CONTRACTS-120:
+ *
+ *  1. `resource` here is the {@link ResourceKey} type TAG (`companyMdDocVersions`).
+ *     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 —
+ *     naming these rows after the keys they describe is the only choice that is
+ *     self-consistent here.
+ *  2. `hydrationDepends` names only rows in THIS array. Pointing at the app's
+ *     path-shaped names would be a dangling reference across that same gap.
+ */
+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",
+    priority: "P3",
+    hydrationPhase: "background",
+    hydrationDepends: [],
+    mutationBehavior: "collapse",
+    staleTimeMs: 30_000,
+    degradationSection: "core",
+    queryBudgetMs: 5_000,
+    resourceFairnessCap: 1,
+  },
+  {
+    // A sealed version is immutable, which is what makes the long staleTime
+    // safe rather than merely convenient: there is no edit that could make an
+    // already-fetched body wrong. Reached only through the list, hence the
+    // dependency.
+    //
+    // `serial`, not `collapse`: the mutation that targets this resource is
+    // restore, and it is guarded by `expectedRevision` — two in flight at once
+    // means one of them is guaranteed a 409 for no reason.
+    resource: "companyMdDocVersion",
+    priority: "P3",
+    hydrationPhase: "background",
+    hydrationDepends: ["companyMdDocVersions"],
+    mutationBehavior: "serial",
+    staleTimeMs: 300_000,
+    degradationSection: "core",
+    queryBudgetMs: 5_000,
+    resourceFairnessCap: 1,
+  },
+] satisfies readonly ResourceEntryInput[];