@company-semantics/contracts 39.2.0 → 39.4.0

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

@@ -240,6 +240,32 @@ export {
   isValidNotificationKind,
 } from "./notifications/index";
 
+// Action-item domain types — things awaiting a user's DECISION, derived from
+// each domain's own pending rows rather than stored. Deliberately a separate
+// vocabulary from NotificationKind above: that one names events that get SENT,
+// this one names standing state. See src/action-items/README.md.
+// @see ADR-CONT-104
+export {
+  ACTION_ITEM_KINDS,
+  ACTION_ITEM_TARGET_TYPES,
+} from "./action-items/index";
+
+export {
+  ActionItemKindSchema,
+  ActionItemListResponseSchema,
+  ActionItemSchema,
+  ActionItemTargetSchema,
+  ActionItemTargetTypeSchema,
+} from "./action-items/index";
+
+export type {
+  ActionItem,
+  ActionItemKind,
+  ActionItemListResponse,
+  ActionItemTarget,
+  ActionItemTargetType,
+} from "./action-items/index";
+
 // Chat domain types
 // @see PRD-00142 for share chat design rationale
 export type {
@@ -418,6 +444,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…