@company-semantics/contracts 39.2.0 → 39.4.0

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