@company-semantics/contracts 50.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": "50.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 = '7ed2b7218b4b' as const;
-export const SPEC_HASH_FULL = '7ed2b7218b4b4a160ba6e9d8854f2e9277d540c33658448d9a0452e96f1cd581' 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;
@@ -5034,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. */
@@ -6532,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;
@@ -9079,7 +9123,7 @@ export interface operations {
             };
         };
     };
-    listCompanyMdDocVersions: {
+    listCompanyMdDocHistory: {
         parameters: {
             query?: {
                 cursor?: string;
@@ -9093,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 */

package/src/generated/openapi-routes.ts

@@ -50,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'],
@@ -57,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",