@company-semantics/contracts 39.2.0 → 39.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@company-semantics/contracts",
-  "version": "39.2.0",
+  "version": "39.3.0",
   "private": false,
   "repository": {
     "type": "git",
@@ -108,6 +108,7 @@
     "generate:spec-hash": "tsx scripts/generate-spec-hash.ts",
     "generate:spec-hash:check": "tsx scripts/generate-spec-hash.ts --check",
     "generate:api": "pnpm generate:api-types && pnpm generate:spec-hash && pnpm generate:openapi-routes",
+    "generate:api:check": "pnpm generate:api-types:check && pnpm generate:spec-hash:check && pnpm generate:openapi-routes:check",
     "generate:api-types": "openapi-typescript openapi/backend.yaml -o src/api/generated.ts",
     "generate:openapi-routes": "tsx scripts/generate-openapi-routes.ts",
     "generate:openapi-routes:check": "tsx scripts/generate-openapi-routes.ts --check",
@@ -138,13 +139,22 @@
     "prettier": "^3.9.6",
     "tsx": "^4.23.1",
     "typescript": "^5.8.3",
+    "vite": "^7.3.6",
     "vitest": "^4.1.10",
     "yaml": "^2.9.0"
   },
   "pnpm": {
     "overrides": {
-      "picomatch": ">=4.0.4",
-      "brace-expansion@<5.0.8": ">=5.0.8"
+      "brace-expansion@<5.0.8": ">=5.0.8",
+      "minimatch@<10.2.3": ">=10.2.3",
+      "rollup@<4.59.0": ">=4.59.0",
+      "picomatch@<4.0.4": ">=4.0.4",
+      "esbuild@<0.28.1": ">=0.28.1",
+      "linkify-it@<5.0.2": ">=5.0.2",
+      "postcss@<8.5.18": ">=8.5.18",
+      "markdown-it@<14.2.0": ">=14.2.0",
+      "js-yaml@>=4.0.0 <4.3.0": ">=4.3.0 <5.0.0",
+      "js-yaml@>=5.0.0 <5.2.2": ">=5.2.2"
     }
   },
   "lint-staged": {
@@ -152,5 +162,5 @@
     "*.md": "markdownlint-cli2",
     "package.json": "node -e \"JSON.parse(require('fs').readFileSync('package.json'))\""
   },
-  "securityRequirementsVersion": "8320e7a5612c6877c2959c127ffa78e693b9d1e95805340a5e4af11a01c4a669"
+  "securityRequirementsVersion": "e88ddf247895bafc36dc5d878bb1045dc522a2375683fe08e1b59a10f99e8766"
 }

package/src/api/README.md

@@ -12,7 +12,7 @@ Provides reusable functions that encode API response shapes shared between the c
 - Response shapes must match the types defined in `src/mcp/` (e.g., `ToolDiscoveryResponse`)
 - Capability graph inclusion is opt-in via query parameter convention (`?include=graph`)
 - `generated.ts` contains only type exports — zero runtime imports, zero const/let/var/function declarations
-- `generated.ts` must stay in sync with `openapi/backend.yaml` — run `pnpm generate:api-types:check` to verify
+- `generated.ts` must stay in sync with `openapi/backend.yaml` — run `pnpm generate:api:check` to verify (it checks all three spec-derived artifacts, not just this one)
 
 ## Generated Types (`generated.ts`)
 
@@ -22,7 +22,7 @@ Auto-generated by `openapi-typescript` from `openapi/backend.yaml`. Exports thre
 - `components` — All schema types (MeResponse, WorkspaceOverview, etc.)
 - `operations` — Operation-level types keyed by operationId
 
-Regenerate with `pnpm generate:api-types`. Check for staleness with `pnpm generate:api-types:check`.
+Regenerate with `pnpm generate:api` — never `pnpm generate:api-types` alone. Three artifacts derive from `openapi/backend.yaml` (this file, `generated-spec-hash.ts`, and `src/generated/openapi-routes.ts`); regenerating one leaves the others stale. Check for staleness with `pnpm generate:api:check`.
 
 The file is committed to the repo (not .gitignored) so consumers can import types without running the generator, and type changes are visible in code review diffs.
 

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 = '4669379f3c9c' as const;
-export const SPEC_HASH_FULL = '4669379f3c9c9733dea3f5bf53f2c1c0d1f0e496fddbf874e8d1f1951e805d7c' as const;
+export const SPEC_HASH = '578211b8b148' as const;
+export const SPEC_HASH_FULL = '578211b8b1489b1d26938629c14b09a94ee3bf636085a5f058f1b573747f8fce' as const;

package/src/api/generated.ts

@@ -1457,6 +1457,77 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/api/company-md/docs/{id}/collab/sync": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /** Get merged collaboration state for a company.md document body */
+        get: operations["getCompanyMdDocCollabSync"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/api/company-md/docs/{id}/collab/updates": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /** Append one Yjs update to a company.md document’s collaboration log */
+        post: operations["appendCompanyMdDocCollabUpdate"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/api/company-md/docs/{id}/collab/presence": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /** Signal presence (cursor position, status, departure) on a company.md document */
+        post: operations["postCompanyMdDocCollabPresence"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/api/company-md/docs/{id}/collab/stream": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * Stream company.md collaboration updates via SSE
+         * @description Server-Sent Events stream of collaboration updates for a company.md document body. x-streaming: true. Durable frames are `event: collab-update` with `id: <seq>` (decimal string); resume via `?after=<seq>&epoch=<n>` from /collab/sync, or the Last-Event-ID header on reconnect. An unusable cursor gets `event: collab-reset` and the client refetches /collab/sync. See ADR-BE-439.
+         */
+        get: operations["streamCompanyMdDocCollab"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/api/company-md/extract": {
         parameters: {
             query?: never;
@@ -4578,6 +4649,48 @@ export interface components {
         UpdateCompanyMdTitleRequest: {
             title: string;
         };
+        /** @description Merged collaboration state plus the cursor the stream resumes from. */
+        CollabSyncResponse: {
+            epoch: number;
+            seq: string;
+            update: string;
+            reset: boolean;
+            editable: boolean;
+            limits: components["schemas"]["CollabSyncLimits"];
+        };
+        /** @description The position the update was assigned, and whether it was a replayed retry. */
+        CollabAppendUpdateResponse: {
+            seq: string;
+            duplicate: boolean;
+        };
+        /** @description One Yjs update plus the generation and idempotency pair it belongs to. */
+        CollabAppendUpdateRequest: {
+            epoch: number;
+            /** Format: uuid */
+            clientKey: string;
+            /** Format: uuid */
+            clientUpdateId: string;
+            update: string;
+        };
+        /** @description One presence signal: position blobs and a status for the caller’s own editor instance. Identity is stamped server-side. */
+        CollabPresenceRequest: {
+            /** Format: uuid */
+            clientKey: string;
+            /** @enum {string} */
+            status: "editing" | "viewing";
+            anchor?: string;
+            head?: string;
+            /** @constant */
+            gone?: true;
+        };
+        /** @description One durable collaboration update, as streamed over SSE. */
+        CollabStreamUpdateFrame: {
+            /** @constant */
+            v: 1;
+            epoch: number;
+            seq: string;
+            update: string;
+        };
         CompanyMdContextBankResponse: {
             items: {
                 id: string;
@@ -5882,6 +5995,11 @@ export interface components {
                 userAgent: string;
             } | null;
         };
+        /** @description Server-enforced collaboration size limits, published so clients can pre-check. */
+        CollabSyncLimits: {
+            maxUpdateBytes: number;
+            maxDocTextBytes: number;
+        };
         /** @description An ACL-admitted context-doc discovery hit. */
         ContextDocDiscoveryHit: {
             id: string;
@@ -8117,6 +8235,183 @@ export interface operations {
             };
         };
     };
+    getCompanyMdDocCollabSync: {
+        parameters: {
+            query?: {
+                since?: string;
+                epoch?: number;
+            };
+            header?: never;
+            path: {
+                id: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Merged collaboration state plus the cursor the stream resumes from */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["CollabSyncResponse"];
+                };
+            };
+            /** @description Document not found, or the caller may not read its body */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description The supplied cursor is ahead of this document’s log; resync */
+            409: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+        };
+    };
+    appendCompanyMdDocCollabUpdate: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                id: string;
+            };
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["CollabAppendUpdateRequest"];
+            };
+        };
+        responses: {
+            /** @description The position the update was assigned, and whether it was a replayed retry */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["CollabAppendUpdateResponse"];
+                };
+            };
+            /** @description Malformed body, or a payload that does not decode as a Yjs update */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description Document not found, or the caller may not edit it */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description Epoch mismatch, or the document was never activated for collaboration */
+            409: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description Applying the update would exceed the document text cap; not logged */
+            413: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description Too many uncompacted updates pending; retry after backoff */
+            429: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+        };
+    };
+    postCompanyMdDocCollabPresence: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                id: string;
+            };
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["CollabPresenceRequest"];
+            };
+        };
+        responses: {
+            /** @description Presence signal accepted (ephemeral; nothing durable written) */
+            204: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description Malformed body (bad clientKey, status, or oversized position blob) */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description The clientKey is bound to a different user on this document */
+            403: {
+                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;
+            };
+        };
+    };
+    streamCompanyMdDocCollab: {
+        parameters: {
+            query?: {
+                after?: string;
+                epoch?: number;
+            };
+            header?: never;
+            path: {
+                id: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description SSE event stream (text/event-stream). Durable frame payload: CollabStreamUpdateFrame. */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "text/event-stream": components["schemas"]["CollabStreamUpdateFrame"];
+                };
+            };
+            /** @description Document not found, or the caller may not read its body */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+        };
+    };
     extractCompanyMd: {
         parameters: {
             query?: never;

package/src/generated/openapi-routes.ts

@@ -30,6 +30,10 @@ export const openApiRoutes = {
   '/api/company-md/docs/:id/context-bank/suggestions': ['GET'],
   '/api/company-md/docs/{id}': ['GET'],
   '/api/company-md/docs/{id}/access-requests': ['GET', 'POST'],
+  '/api/company-md/docs/{id}/collab/presence': ['POST'],
+  '/api/company-md/docs/{id}/collab/stream': ['GET'],
+  '/api/company-md/docs/{id}/collab/sync': ['GET'],
+  '/api/company-md/docs/{id}/collab/updates': ['POST'],
   '/api/company-md/docs/{id}/content': ['PUT'],
   '/api/company-md/docs/{id}/context-bank': ['GET'],
   '/api/company-md/docs/{id}/context-bank/associate': ['POST'],

package/src/index.ts

@@ -418,6 +418,38 @@ export type {
 export { SourceAuthoritySchema } from "./org/index";
 export type { SourceAuthority } from "./org/index";
 
+// Company.md real-time collaboration wire contract: sync/update-accepted
+// responses, the SSE frame union, the Y.Doc shape constant, and the published
+// size limits. Sequences are ALWAYS decimal strings. (ADR-CONT-102)
+export {
+  COMPANY_MD_COLLAB_TEXT_KEY,
+  COMPANY_MD_COLLAB_MAX_UPDATE_B64_CHARS,
+  COMPANY_MD_COLLAB_MAX_DOC_TEXT_BYTES,
+  COMPANY_MD_COLLAB_MAX_PRESENCE_POSITION_CHARS,
+  CompanyMdCollabSyncLimitsSchema,
+  CompanyMdCollabSyncResponseSchema,
+  CompanyMdCollabUpdateAcceptedSchema,
+  CompanyMdCollabUpdateEventSchema,
+  CompanyMdCollabPresenceEventSchema,
+  CompanyMdCollabResetEventSchema,
+  CompanyMdCollabAccessRevokedEventSchema,
+  CompanyMdCollabConnectedEventSchema,
+  CompanyMdCollabServerDrainEventSchema,
+  CompanyMdCollabSseEventSchema,
+} from "./org/index";
+export type {
+  CompanyMdCollabSyncLimits,
+  CompanyMdCollabSyncResponse,
+  CompanyMdCollabUpdateAccepted,
+  CompanyMdCollabUpdateEvent,
+  CompanyMdCollabPresenceEvent,
+  CompanyMdCollabResetEvent,
+  CompanyMdCollabAccessRevokedEvent,
+  CompanyMdCollabConnectedEvent,
+  CompanyMdCollabServerDrainEvent,
+  CompanyMdCollabSseEvent,
+} from "./org/index";
+
 // Sync run summary: the outcome record of one adapter sync run (counts +
 // cursor watermark). A flat report shape, not a structure fact. (ADR-CONT-085)
 export { SyncRunSummarySchema } from "./org/index";

package/src/org/README.md

@@ -37,6 +37,10 @@ Shared type vocabulary for organization ownership, type classification, and tran
 - `AuthoritySource` _(type)_
 - `AuthoritySourceSchema` — Engine-internal authority source.
 - `AuthorizableView` _(type)_ — Type for views that can be checked against VIEWSCOPEMAP.
+- `COMPANY_MD_COLLAB_MAX_DOC_TEXT_BYTES` — Cap on the MATERIALIZED document text, in UTF-8 bytes of the expanded result.
+- `COMPANY_MD_COLLAB_MAX_PRESENCE_POSITION_CHARS` — Cap on ONE presence position blob (`anchor` or `head`), in base64 chars.
+- `COMPANY_MD_COLLAB_MAX_UPDATE_B64_CHARS` — Cap on ONE encoded update, measured on the base64 payload as it is sent.
+- `COMPANY_MD_COLLAB_TEXT_KEY` — The Y.Doc root key holding the document body — a CONTRACT, not a detail.
 - `CanonicalFacts` _(type)_
 - `CanonicalFactsSchema` — The full normalized batch an external-source adapter emits in one pass: every person, org unit, position…
 - `CanonicalOccupancy` _(type)_
@@ -55,6 +59,26 @@ Shared type vocabulary for organization ownership, type classification, and tran
 - `ChangeMemberRoleResponse` _(type)_
 - `ChangeMemberRoleResponseSchema`
 - `CompanyMdClassification` _(type)_ — Information classification for a Company.md node — what the document is, for governance, NOT permissions.
+- `CompanyMdCollabAccessRevokedEvent` _(type)_
+- `CompanyMdCollabAccessRevokedEventSchema` — `event: access-revoked` — the actor's read grant went away mid-stream.
+- `CompanyMdCollabConnectedEvent` _(type)_
+- `CompanyMdCollabConnectedEventSchema` — `event: connected` — the stream is open.
+- `CompanyMdCollabPresenceEvent` _(type)_
+- `CompanyMdCollabPresenceEventSchema` — `event: collab-presence` — one participant's presence signal, either live or replayed from the roster right…
+- `CompanyMdCollabResetEvent` _(type)_
+- `CompanyMdCollabResetEventSchema` — `event: collab-reset` — the client's cursor was unusable (a superseded generation, older than what compaction…
+- `CompanyMdCollabServerDrainEvent` _(type)_
+- `CompanyMdCollabServerDrainEventSchema` — `event: server_drain` — the server is shutting the stream down deliberately (a rolling restart, not a…
+- `CompanyMdCollabSseEvent` _(type)_
+- `CompanyMdCollabSseEventSchema` — Every frame the collaboration stream emits, discriminated on the `type` the client stamps from the SSE…
+- `CompanyMdCollabSyncLimits` _(type)_
+- `CompanyMdCollabSyncLimitsSchema` — Protocol limits the client needs BEFORE it sends anything.
+- `CompanyMdCollabSyncResponse` _(type)_
+- `CompanyMdCollabSyncResponseSchema` — `GET /collab/sync` response body — merged collaboration state plus the cursor the stream resumes from.
+- `CompanyMdCollabUpdateAccepted` _(type)_
+- `CompanyMdCollabUpdateAcceptedSchema` — `POST /collab/updates` response body.
+- `CompanyMdCollabUpdateEvent` _(type)_
+- `CompanyMdCollabUpdateEventSchema` — `event: collab-update` — one durable collaboration update.
 - `CompanyMdContextBankItem` _(type)_ — A context bank item — a company.md doc associated with one or more parent nodes.
 - `CompanyMdDependency` _(type)_
 - `CompanyMdDiscoverabilityPolicy` _(type)_ — Discoverability policy for a Company.md node — who knows it exists, orthogonal to who may read it (authority…

package/src/org/__tests__/company-md-collab.test.ts

@@ -0,0 +1,290 @@
+import { describe, it, expect } from "vitest";
+
+import {
+  COMPANY_MD_COLLAB_TEXT_KEY,
+  COMPANY_MD_COLLAB_MAX_UPDATE_B64_CHARS,
+  COMPANY_MD_COLLAB_MAX_DOC_TEXT_BYTES,
+  COMPANY_MD_COLLAB_MAX_PRESENCE_POSITION_CHARS,
+  CompanyMdCollabSyncResponseSchema,
+  CompanyMdCollabUpdateAcceptedSchema,
+  CompanyMdCollabSseEventSchema,
+} from "../company-md-collab.js";
+
+const DOC_ID = "9f1c7b62-2b3e-4d21-9a11-6a0c0b5e7c31";
+const USER_ID = "3d0a2f18-5c44-4a90-8b7a-1d2e3f4a5b6c";
+const CLIENT_KEY = "7c9e6679-7425-40de-944b-e07fc1f90ae7";
+
+/**
+ * A sequence past 2^53. This is the whole reason seq is a string: as a JSON
+ * number it would round, and a rounded cursor resumes at the wrong position
+ * without failing.
+ */
+const BIG_SEQ = "9007199254740993";
+
+describe("CompanyMdCollabSyncResponseSchema", () => {
+  const base = {
+    epoch: 3,
+    seq: "42",
+    update: "AQIDBA==",
+    editable: true,
+    reset: false,
+    limits: { maxUpdateBytes: 262144, maxDocTextBytes: 1000000 },
+  };
+
+  it("accepts the sync response the backend emits", () => {
+    expect(CompanyMdCollabSyncResponseSchema.parse(base)).toEqual(base);
+  });
+
+  it("accepts a seq beyond the JS safe-integer range", () => {
+    const parsed = CompanyMdCollabSyncResponseSchema.parse({
+      ...base,
+      seq: BIG_SEQ,
+    });
+    expect(parsed.seq).toBe(BIG_SEQ);
+  });
+
+  it("accepts a response without reset (the field is additive-optional)", () => {
+    const { reset: _reset, ...withoutReset } = base;
+    expect(() =>
+      CompanyMdCollabSyncResponseSchema.parse(withoutReset),
+    ).not.toThrow();
+  });
+
+  it("rejects a numeric seq", () => {
+    expect(() =>
+      CompanyMdCollabSyncResponseSchema.parse({ ...base, seq: 42 }),
+    ).toThrow();
+  });
+
+  it("rejects a non-digit seq", () => {
+    expect(() =>
+      CompanyMdCollabSyncResponseSchema.parse({ ...base, seq: "42n" }),
+    ).toThrow();
+  });
+
+  it("rejects a zero epoch", () => {
+    expect(() =>
+      CompanyMdCollabSyncResponseSchema.parse({ ...base, epoch: 0 }),
+    ).toThrow();
+  });
+
+  it("rejects a response missing limits", () => {
+    const { limits: _limits, ...withoutLimits } = base;
+    expect(() =>
+      CompanyMdCollabSyncResponseSchema.parse(withoutLimits),
+    ).toThrow();
+  });
+});
+
+describe("CompanyMdCollabUpdateAcceptedSchema", () => {
+  it("accepts the append response the backend emits", () => {
+    const frame = { seq: "1024", duplicate: false };
+    expect(CompanyMdCollabUpdateAcceptedSchema.parse(frame)).toEqual(frame);
+  });
+
+  it("rejects a numeric seq", () => {
+    expect(() =>
+      CompanyMdCollabUpdateAcceptedSchema.parse({
+        seq: 1024,
+        duplicate: false,
+      }),
+    ).toThrow();
+  });
+
+  it("rejects a missing duplicate flag", () => {
+    expect(() =>
+      CompanyMdCollabUpdateAcceptedSchema.parse({ seq: "1024" }),
+    ).toThrow();
+  });
+});
+
+/**
+ * The frames below are the exact `data:` bodies the backend writes, with `type`
+ * stamped from the SSE `event:` name — which is how a client feeds the union.
+ * If one of these stops parsing, the published contract has drifted from the
+ * stream.
+ */
+describe("CompanyMdCollabSseEventSchema — raw backend frames", () => {
+  it("parses a collab-update frame", () => {
+    const parsed = CompanyMdCollabSseEventSchema.parse({
+      type: "collab-update",
+      v: 1,
+      epoch: 3,
+      seq: BIG_SEQ,
+      update: "AQIDBA==",
+    });
+    expect(parsed.type).toBe("collab-update");
+  });
+
+  it("parses a collab-presence frame with selection blobs", () => {
+    const parsed = CompanyMdCollabSseEventSchema.parse({
+      type: "collab-presence",
+      v: 1,
+      userId: USER_ID,
+      clientKey: CLIENT_KEY,
+      status: "editing",
+      anchor: "AQAB",
+      head: "AQAC",
+    });
+    expect(parsed.type).toBe("collab-presence");
+  });
+
+  it("parses a collab-presence departure frame", () => {
+    expect(() =>
+      CompanyMdCollabSseEventSchema.parse({
+        type: "collab-presence",
+        v: 1,
+        userId: USER_ID,
+        clientKey: CLIENT_KEY,
+        status: "viewing",
+        gone: true,
+      }),
+    ).not.toThrow();
+  });
+
+  it("parses a collab-reset frame for each reason the backend sends", () => {
+    for (const reason of ["epoch-mismatch", "compacted", "cursor-ahead"]) {
+      expect(() =>
+        CompanyMdCollabSseEventSchema.parse({
+          type: "collab-reset",
+          v: 1,
+          reason,
+          epoch: 4,
+          resumeSeq: "77",
+        }),
+      ).not.toThrow();
+    }
+  });
+
+  it("parses an access-revoked frame with its empty body", () => {
+    const parsed = CompanyMdCollabSseEventSchema.parse({
+      type: "access-revoked",
+    });
+    expect(parsed.type).toBe("access-revoked");
+  });
+
+  it("parses a connected frame with its empty body", () => {
+    expect(() =>
+      CompanyMdCollabSseEventSchema.parse({ type: "connected" }),
+    ).not.toThrow();
+  });
+
+  it("parses a server_drain frame", () => {
+    expect(() =>
+      CompanyMdCollabSseEventSchema.parse({
+        type: "server_drain",
+        reason: "shutting_down",
+      }),
+    ).not.toThrow();
+  });
+});
+
+describe("CompanyMdCollabSseEventSchema — optional attribution fields", () => {
+  it("accepts a collab-update carrying docId, author and origin", () => {
+    expect(() =>
+      CompanyMdCollabSseEventSchema.parse({
+        type: "collab-update",
+        v: 1,
+        epoch: 3,
+        seq: "9",
+        update: "AQIDBA==",
+        docId: DOC_ID,
+        authorUserId: USER_ID,
+        origin: "client",
+      }),
+    ).not.toThrow();
+  });
+
+  it("accepts a server-originated collab-update with a null author", () => {
+    expect(() =>
+      CompanyMdCollabSseEventSchema.parse({
+        type: "collab-update",
+        v: 1,
+        epoch: 3,
+        seq: "9",
+        update: "AQIDBA==",
+        authorUserId: null,
+        origin: "bridge",
+      }),
+    ).not.toThrow();
+  });
+});
+
+describe("CompanyMdCollabSseEventSchema — rejections", () => {
+  it("rejects an unknown event type", () => {
+    expect(() =>
+      CompanyMdCollabSseEventSchema.parse({ type: "collab-yolo", v: 1 }),
+    ).toThrow();
+  });
+
+  it("rejects a frame with no type stamped on it", () => {
+    expect(() =>
+      CompanyMdCollabSseEventSchema.parse({
+        v: 1,
+        epoch: 3,
+        seq: "9",
+        update: "AQIDBA==",
+      }),
+    ).toThrow();
+  });
+
+  it("rejects a numeric seq on collab-update", () => {
+    expect(() =>
+      CompanyMdCollabSseEventSchema.parse({
+        type: "collab-update",
+        v: 1,
+        epoch: 3,
+        seq: 9,
+        update: "AQIDBA==",
+      }),
+    ).toThrow();
+  });
+
+  it("rejects a numeric resumeSeq on collab-reset", () => {
+    expect(() =>
+      CompanyMdCollabSseEventSchema.parse({
+        type: "collab-reset",
+        v: 1,
+        reason: "compacted",
+        epoch: 4,
+        resumeSeq: 77,
+      }),
+    ).toThrow();
+  });
+
+  it("rejects an unknown presence status", () => {
+    expect(() =>
+      CompanyMdCollabSseEventSchema.parse({
+        type: "collab-presence",
+        v: 1,
+        userId: USER_ID,
+        clientKey: CLIENT_KEY,
+        status: "idle",
+      }),
+    ).toThrow();
+  });
+
+  it("rejects a future frame version", () => {
+    expect(() =>
+      CompanyMdCollabSseEventSchema.parse({
+        type: "collab-update",
+        v: 2,
+        epoch: 3,
+        seq: "9",
+        update: "AQIDBA==",
+      }),
+    ).toThrow();
+  });
+});
+
+describe("collaboration protocol constants", () => {
+  it("names the Y.Doc root key the backend materializes text from", () => {
+    expect(COMPANY_MD_COLLAB_TEXT_KEY).toBe("content");
+  });
+
+  it("publishes the size limits the server enforces", () => {
+    expect(COMPANY_MD_COLLAB_MAX_UPDATE_B64_CHARS).toBe(256 * 1024);
+    expect(COMPANY_MD_COLLAB_MAX_DOC_TEXT_BYTES).toBe(1_000_000);
+    expect(COMPANY_MD_COLLAB_MAX_PRESENCE_POSITION_CHARS).toBe(512);
+  });
+});

package/src/org/company-md-collab.ts

@@ -0,0 +1,337 @@
+/**
+ * company.md real-time collaboration — the published wire contract.
+ *
+ * The response and event vocabulary of the four `/api/company-md/docs/{id}/collab/*`
+ * routes. Promoted here because both the app (the editor and its transport) and
+ * the backend (the routes and the Y.Doc bridge) must agree on these shapes, and
+ * a client that guesses one of them fails silently rather than loudly. Request
+ * bodies deliberately stay backend-side per ADR-CONT-029 — only responses and
+ * broadcast events are the published promise.
+ *
+ * THE ONE RULE — every sequence value is a DECIMAL STRING, never a JSON number.
+ * Sequences are Postgres bigints; past 2^53 `JSON.parse` rounds them, and a
+ * rounded cursor does not fail, it silently resumes at the wrong position. So
+ * `seq` and `resumeSeq` are `z.string().regex(/^[0-9]+$/)` and a numeric value
+ * is rejected at the boundary.
+ *
+ * ON THE SSE UNION'S DISCRIMINATOR — the stream's frames do NOT carry a `type`
+ * field. The discriminator is the SSE `event:` NAME, and the `data:` body is the
+ * bare payload. A client therefore stamps `type` from the frame's event name
+ * before parsing:
+ *
+ *     CompanyMdCollabSseEventSchema.parse({ type: ev.type, ...JSON.parse(ev.data) })
+ *
+ * The union is modeled on `type` anyway (the ChatSseEvent precedent) because
+ * that is the shape a consumer actually switches on. Fields the server does not
+ * put on the wire today are optional, so a stamped raw frame parses as-is.
+ *
+ * @see ADR-CONT-102 for what is promoted here and what deliberately is not.
+ * @see the backend protocol ADR (slug `company-md-collab-protocol`) for the
+ *   authoritative protocol semantics these shapes describe.
+ */
+
+import { z } from "zod";
+
+// ---------------------------------------------------------------------------
+// Protocol constants
+// ---------------------------------------------------------------------------
+
+/**
+ * The Y.Doc root key holding the document body — a CONTRACT, not a detail.
+ *
+ * The server materializes text by reading this key and the bridge mutates the
+ * same type. A client that writes its body under a different root key gets its
+ * updates durably logged and permanently ignored: the log is correct, the
+ * stored `content` stays empty, and nothing errors anywhere. Title is
+ * deliberately NOT in the CRDT document.
+ */
+export const COMPANY_MD_COLLAB_TEXT_KEY = "content" as const;
+
+/**
+ * Cap on ONE encoded update, measured on the base64 payload as it is sent.
+ * Published so an editor can refuse an oversized paste locally instead of
+ * discovering the cap on a rejected POST. Prefer the `limits` block on a live
+ * {@link CompanyMdCollabSyncResponseSchema} when one is in hand — this constant
+ * is the compile-time default for a client that has not synced yet.
+ */
+export const COMPANY_MD_COLLAB_MAX_UPDATE_B64_CHARS = 262144 as const;
+
+/**
+ * Cap on the MATERIALIZED document text, in UTF-8 bytes of the expanded result.
+ *
+ * Not redundant with {@link COMPANY_MD_COLLAB_MAX_UPDATE_B64_CHARS}: a CRDT
+ * update is a DELTA, so a small delta can expand the document arbitrarily and a
+ * stream of individually-tiny updates can grow state without any single request
+ * looking suspicious. Only a measurement on the expanded text catches that.
+ */
+export const COMPANY_MD_COLLAB_MAX_DOC_TEXT_BYTES = 1_000_000 as const;
+
+/**
+ * Cap on ONE presence position blob (`anchor` or `head`), in base64 chars.
+ * These are encoded Y.RelativePosition values — opaque POSITION data, a few
+ * dozen bytes in practice; the cap keeps a full presence envelope well under
+ * the transport's payload ceiling so an envelope is never truncated.
+ */
+export const COMPANY_MD_COLLAB_MAX_PRESENCE_POSITION_CHARS = 512 as const;
+
+// ---------------------------------------------------------------------------
+// Sequences
+// ---------------------------------------------------------------------------
+
+/**
+ * A sequence number on the wire: decimal digits only, arbitrary precision.
+ * Module-private on purpose — consumers reach it through the field that uses
+ * it, so there is one place the rule can change.
+ */
+const CollabSeqString = z
+  .string()
+  .regex(
+    /^[0-9]+$/,
+    "seq must be a decimal string (bigint values are never JSON numbers)",
+  );
+
+// ---------------------------------------------------------------------------
+// Response shapes
+// ---------------------------------------------------------------------------
+
+/**
+ * Protocol limits the client needs BEFORE it sends anything. Published from the
+ * same constants the server enforces — a published limit that disagrees with
+ * the enforced one is worse than none, because the editor lets the user type
+ * and the server then rejects the result.
+ */
+export const CompanyMdCollabSyncLimitsSchema = z.object({
+  /** Max size of ONE base64-encoded update the server will accept, in bytes. */
+  maxUpdateBytes: z.number().int(),
+  /** Max size of the MATERIALIZED document text, in UTF-8 bytes. */
+  maxDocTextBytes: z.number().int(),
+});
+export type CompanyMdCollabSyncLimits = z.infer<
+  typeof CompanyMdCollabSyncLimitsSchema
+>;
+
+/**
+ * `GET /collab/sync` response body — merged collaboration state plus the cursor
+ * the stream resumes from.
+ *
+ * `seq` is handed straight back to the stream as `?after=`, which is what closes
+ * the race between "fetched state" and "receiving live updates": the server
+ * serves everything strictly after that seq, so an update committed inside the
+ * window is re-sent rather than lost.
+ */
+export const CompanyMdCollabSyncResponseSchema = z.object({
+  /** The document's current collaboration generation. */
+  epoch: z.number().int().positive(),
+  /** Cursor this payload advances the client to — pass verbatim as `after=`. */
+  seq: CollabSeqString,
+  /** base64 Yjs bytes: a full snapshot when `reset`, otherwise a delta. */
+  update: z.string(),
+  /**
+   * Whether this actor may edit the body — surfaced so a client can mount a
+   * read-only editor instead of walking into a doomed first write. Signal only;
+   * it never affects admittance to the stream.
+   */
+  editable: z.boolean(),
+  /**
+   * True when `update` is a full snapshot because the client's cursor was
+   * unusable (absent, from another generation, or older than what compaction
+   * still holds). Applying it is identical either way — Yjs merges losslessly —
+   * but anything the client queued against the old cursor is void.
+   *
+   * Optional on the published contract though the server always sends it: a
+   * reader that treats an absent value as `false` behaves correctly against
+   * every server that omits it, and this keeps the field addable to sibling
+   * responses later without a major.
+   */
+  reset: z.boolean().optional(),
+  limits: CompanyMdCollabSyncLimitsSchema,
+});
+export type CompanyMdCollabSyncResponse = z.infer<
+  typeof CompanyMdCollabSyncResponseSchema
+>;
+
+/**
+ * `POST /collab/updates` response body.
+ *
+ * `duplicate` is not decoration: on a retry the server returns the ORIGINAL seq
+ * and writes nothing, so a client that treats the response as proof of a fresh
+ * append would double-count its own edit.
+ */
+export const CompanyMdCollabUpdateAcceptedSchema = z.object({
+  /** The position this update occupies in the doc's log. */
+  seq: CollabSeqString,
+  /** True when this exact `(clientKey, clientUpdateId)` was already appended. */
+  duplicate: z.boolean(),
+});
+export type CompanyMdCollabUpdateAccepted = z.infer<
+  typeof CompanyMdCollabUpdateAcceptedSchema
+>;
+
+// ---------------------------------------------------------------------------
+// SSE frames
+//
+// Each member's `type` is the SSE `event:` name, stamped by the client onto the
+// parsed `data:` body (see the module note). Fields the server does not
+// currently emit are optional so a stamped raw frame parses unchanged.
+// ---------------------------------------------------------------------------
+
+/**
+ * `event: collab-update` — one durable collaboration update.
+ *
+ * The only frame that carries an SSE `id:` line (equal to `seq`), which is what
+ * makes a browser's `Last-Event-ID` resume land on a durable cursor. Every other
+ * frame is deliberately id-less so it can never advance that cursor.
+ */
+export const CompanyMdCollabUpdateEventSchema = z.object({
+  type: z.literal("collab-update"),
+  /** Frame format version. */
+  v: z.literal(1),
+  /** The generation this update belongs to. */
+  epoch: z.number().int(),
+  /** The update's position in the doc's log — mirrors the frame's `id:`. */
+  seq: CollabSeqString,
+  /** base64 Yjs update bytes. Opaque; the server never interprets them. */
+  update: z.string(),
+  /** The document. Absent on a single-doc stream, where the URL already names it. */
+  docId: z.string().uuid().optional(),
+  /** Who produced the update; `null` for server-originated writes. Absent when not attributed. */
+  authorUserId: z.string().uuid().nullable().optional(),
+  /** Where the update came from. Absent when the server does not attribute origin. */
+  origin: z.enum(["client", "bridge", "bootstrap"]).optional(),
+});
+export type CompanyMdCollabUpdateEvent = z.infer<
+  typeof CompanyMdCollabUpdateEventSchema
+>;
+
+/**
+ * `event: collab-presence` — one participant's presence signal, either live or
+ * replayed from the roster right after connect (so a joining client's avatar
+ * stack fills instantly).
+ *
+ * `userId` is trustworthy: the server stamps it from the posting session and
+ * never takes it from a client body. That is why no client-supplied identity
+ * type is published — receiving clients resolve name/avatar/colour from
+ * `userId` themselves.
+ */
+export const CompanyMdCollabPresenceEventSchema = z.object({
+  type: z.literal("collab-presence"),
+  /** Frame format version. */
+  v: z.literal(1),
+  /** The participant — session-stamped server-side; resolve identity from this. */
+  userId: z.string().uuid(),
+  /** The participant's editor instance (one user may hold several). */
+  clientKey: z.string().uuid(),
+  /** What that editor instance is doing. */
+  status: z.enum(["editing", "viewing"]),
+  /** Selection anchor — an encoded Y.RelativePosition blob. */
+  anchor: z.string().optional(),
+  /** Selection head — an encoded Y.RelativePosition blob. */
+  head: z.string().optional(),
+  /** Present (`true`) when this clientKey left — explicitly or by TTL expiry. */
+  gone: z.literal(true).optional(),
+  /** The document. Absent on a single-doc stream, where the URL already names it. */
+  docId: z.string().uuid().optional(),
+  /** The generation. Absent because presence is not a log position. */
+  epoch: z.number().int().optional(),
+});
+export type CompanyMdCollabPresenceEvent = z.infer<
+  typeof CompanyMdCollabPresenceEventSchema
+>;
+
+/**
+ * `event: collab-reset` — the client's cursor was unusable (a superseded
+ * generation, older than what compaction still holds, or ahead of anything this
+ * generation ever issued). The stream keeps serving from the current tail; the
+ * client refetches `/sync` and its local Y.Doc merges the snapshot losslessly,
+ * so nothing typed meanwhile is lost.
+ */
+export const CompanyMdCollabResetEventSchema = z.object({
+  type: z.literal("collab-reset"),
+  /** Frame format version. */
+  v: z.literal(1),
+  /**
+   * Why the cursor could not be honored. Currently one of `epoch-mismatch`,
+   * `compacted`, `cursor-ahead` — published as an open string, not an enum, so
+   * a server that grows a fourth reason does not turn every existing client's
+   * reset into a parse failure. The client's response is the same regardless:
+   * refetch `/sync`.
+   */
+  reason: z.string(),
+  /** The document's CURRENT generation — what `/sync` will answer from. */
+  epoch: z.number().int(),
+  /** The tail the stream is serving from while the client re-syncs. */
+  resumeSeq: CollabSeqString,
+});
+export type CompanyMdCollabResetEvent = z.infer<
+  typeof CompanyMdCollabResetEventSchema
+>;
+
+/**
+ * `event: access-revoked` — the actor's read grant went away mid-stream. The
+ * server closes immediately after; the client must tear down its editor rather
+ * than reconnect.
+ *
+ * Carries an EMPTY body on the wire, so `v` is optional here even though every
+ * other frame requires it. Requiring `v` would reject the real frame.
+ */
+export const CompanyMdCollabAccessRevokedEventSchema = z.object({
+  type: z.literal("access-revoked"),
+  /** Frame format version; absent on the wire today. */
+  v: z.literal(1).optional(),
+});
+export type CompanyMdCollabAccessRevokedEvent = z.infer<
+  typeof CompanyMdCollabAccessRevokedEventSchema
+>;
+
+/**
+ * `event: connected` — the stream is open. Transport-level, with an empty body;
+ * modeled so a client that routes EVERY frame through this union does not treat
+ * a normal connect as an unknown event.
+ */
+export const CompanyMdCollabConnectedEventSchema = z.object({
+  type: z.literal("connected"),
+  /** Frame format version; absent on the wire today. */
+  v: z.literal(1).optional(),
+});
+export type CompanyMdCollabConnectedEvent = z.infer<
+  typeof CompanyMdCollabConnectedEventSchema
+>;
+
+/**
+ * `event: server_drain` — the server is shutting the stream down deliberately
+ * (a rolling restart, not a permission change). The client should reconnect;
+ * unlike `access-revoked` this is not terminal.
+ *
+ * Modeled for the same reason as `connected`: without it, every rolling restart
+ * looks like an unknown event to a client that validates all frames. Note the
+ * snake_case name — it predates the kebab-case collab frames.
+ */
+export const CompanyMdCollabServerDrainEventSchema = z.object({
+  type: z.literal("server_drain"),
+  /** Why the server is draining; `shutting_down` today. Open string for forward compatibility. */
+  reason: z.string(),
+  /** Frame format version; absent on the wire today. */
+  v: z.literal(1).optional(),
+});
+export type CompanyMdCollabServerDrainEvent = z.infer<
+  typeof CompanyMdCollabServerDrainEventSchema
+>;
+
+/**
+ * Every frame the collaboration stream emits, discriminated on the `type` the
+ * client stamps from the SSE `event:` name.
+ *
+ * Registered as the OpenAPI component `CompanyMdCollabSseEvent`, per the
+ * `ChatSseEvent` / `ExecutionSseEvent` precedent.
+ */
+export const CompanyMdCollabSseEventSchema = z.discriminatedUnion("type", [
+  CompanyMdCollabUpdateEventSchema,
+  CompanyMdCollabPresenceEventSchema,
+  CompanyMdCollabResetEventSchema,
+  CompanyMdCollabAccessRevokedEventSchema,
+  CompanyMdCollabConnectedEventSchema,
+  CompanyMdCollabServerDrainEventSchema,
+]);
+export type CompanyMdCollabSseEvent = z.infer<
+  typeof CompanyMdCollabSseEventSchema
+>;

package/src/org/company-md.ts

@@ -218,6 +218,18 @@ export interface CompanyMdDocCore extends CompanyMdNodeIdentity {
    * recipient to an `owners` node may still be allowed to request).
    */
   readonly canRequestAccess?: boolean;
+  /**
+   * Whether this doc is served by the real-time collaboration protocol
+   * (ADR-CONT-102). When `true` the client may open `/collab/sync` + the collab
+   * stream; otherwise it uses the legacy save path.
+   *
+   * Optional so the app deploy and the contract bump stay order-independent in
+   * BOTH directions: an old client reading a new API ignores the field, and a
+   * new client reading an old API sees it absent — and an absent value means
+   * "not collaborative", so both degrade to the legacy editing path rather than
+   * to a broken one.
+   */
+  readonly collabEnabled?: boolean;
 }
 
 export interface CompanyMdDocCollaborators {

package/src/org/index.ts

@@ -227,6 +227,38 @@ export type {
   CompanyMdContextBankItem,
 } from "./company-md";
 
+// Company.md real-time collaboration wire contract: sync/update-accepted
+// responses, the SSE frame union, the Y.Doc shape constant, and the published
+// size limits. Sequences are ALWAYS decimal strings. (ADR-CONT-102)
+export {
+  COMPANY_MD_COLLAB_TEXT_KEY,
+  COMPANY_MD_COLLAB_MAX_UPDATE_B64_CHARS,
+  COMPANY_MD_COLLAB_MAX_DOC_TEXT_BYTES,
+  COMPANY_MD_COLLAB_MAX_PRESENCE_POSITION_CHARS,
+  CompanyMdCollabSyncLimitsSchema,
+  CompanyMdCollabSyncResponseSchema,
+  CompanyMdCollabUpdateAcceptedSchema,
+  CompanyMdCollabUpdateEventSchema,
+  CompanyMdCollabPresenceEventSchema,
+  CompanyMdCollabResetEventSchema,
+  CompanyMdCollabAccessRevokedEventSchema,
+  CompanyMdCollabConnectedEventSchema,
+  CompanyMdCollabServerDrainEventSchema,
+  CompanyMdCollabSseEventSchema,
+} from "./company-md-collab";
+export type {
+  CompanyMdCollabSyncLimits,
+  CompanyMdCollabSyncResponse,
+  CompanyMdCollabUpdateAccepted,
+  CompanyMdCollabUpdateEvent,
+  CompanyMdCollabPresenceEvent,
+  CompanyMdCollabResetEvent,
+  CompanyMdCollabAccessRevokedEvent,
+  CompanyMdCollabConnectedEvent,
+  CompanyMdCollabServerDrainEvent,
+  CompanyMdCollabSseEvent,
+} from "./company-md-collab";
+
 // Sharing and ACL types (PRD-00306). The legacy AccessSource / AccessReason /
 // EffectiveAccess / EvaluationStep / AccessExplanation were removed with
 // CompanyMdAccessEvaluator (ADR-BE-392); ShareState.effectiveAccess now carries