@company-semantics/contracts 42.0.0 → 43.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@company-semantics/contracts",
-  "version": "42.0.0",
+  "version": "43.0.0",
   "private": false,
   "repository": {
     "type": "git",

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

@@ -97,3 +97,47 @@ describe("resource-keys: system-scoped internalAdmin* types", () => {
     ).toBe(false);
   });
 });
+
+describe("resource-keys: companyMdAccessRequests (per-doc identity)", () => {
+  const DOC_ID = "22222222-2222-4222-8222-222222222222";
+  const key: ResourceKey = {
+    type: "companyMdAccessRequests",
+    orgId: ORG_ID,
+    docId: DOC_ID,
+  };
+
+  it("serialises to [type, orgId, docId]", () => {
+    expect(toQueryKey(key)).toEqual([
+      "companyMdAccessRequests",
+      ORG_ID,
+      DOC_ID,
+    ]);
+  });
+
+  it("round-trips through fromQueryKey", () => {
+    expect(fromQueryKey(toQueryKey(key))).toEqual(key);
+  });
+
+  it("discriminates two keys differing only in docId", () => {
+    const other: ResourceKey = {
+      type: "companyMdAccessRequests",
+      orgId: ORG_ID,
+      docId: "33333333-3333-4333-8333-333333333333",
+    };
+    expect(matchesResourceKey(toQueryKey(key), key)).toBe(true);
+    expect(matchesResourceKey(toQueryKey(other), key)).toBe(false);
+  });
+
+  it("does NOT collide with companyMdDoc, whose id field is named `slug`", () => {
+    // companyMdDoc carries the stable doc id under a field named `slug`
+    // (ADR-BE-315 made slugs only parent-scoped unique). The two keys must stay
+    // distinguishable even when they carry the same document id.
+    const docKey: ResourceKey = {
+      type: "companyMdDoc",
+      orgId: ORG_ID,
+      slug: DOC_ID,
+    };
+    expect(matchesResourceKey(toQueryKey(docKey), key)).toBe(false);
+    expect(matchesResourceKey(toQueryKey(key), docKey)).toBe(false);
+  });
+});

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 = 'c0f32d11bf0f' as const;
-export const SPEC_HASH_FULL = 'c0f32d11bf0fdc59ee0a7bf84bee984f2f8109838d2659b6e66709e0198dcd4e' as const;
+export const SPEC_HASH = '017f7c7f6a72' as const;
+export const SPEC_HASH_FULL = '017f7c7f6a72c27413c0329be3eb9ff39547d425f575d570970d6e6920324638' as const;

package/src/api/generated.ts

@@ -3529,10 +3529,10 @@ export interface components {
             share: {
                 id: string;
                 chatId: string;
-                token: string;
+                token?: string;
                 /** @enum {string} */
                 visibility: "private" | "public";
-                shareUrl: string;
+                shareUrl?: string;
                 messageCountAtShare: number;
                 titleAtShare: string;
                 /** Format: date-time */
@@ -3552,10 +3552,10 @@ export interface components {
             shares: {
                 id: string;
                 chatId: string;
-                token: string;
+                token?: string;
                 /** @enum {string} */
                 visibility: "private" | "public";
-                shareUrl: string;
+                shareUrl?: string;
                 messageCountAtShare: number;
                 titleAtShare: string;
                 /** Format: date-time */
@@ -3568,10 +3568,10 @@ export interface components {
             share: {
                 id: string;
                 chatId: string;
-                token: string;
+                token?: string;
                 /** @enum {string} */
                 visibility: "private" | "public";
-                shareUrl: string;
+                shareUrl?: string;
                 messageCountAtShare: number;
                 titleAtShare: string;
                 /** Format: date-time */

package/src/index.ts

@@ -266,6 +266,36 @@ export type {
   ActionItemTargetType,
 } from "./action-items/index";
 
+// User-scoped push envelope — the frames any domain may put on ONE
+// authenticated user's connection without owning a route or an SSE union of its
+// own. A THIRD vocabulary alongside the two above, and deliberately unlike
+// both: a notification LEAVES the building, an action item is STANDING state,
+// and a user event is a single unreplayable instant meaning "your cache is
+// stale". This stream is a wake-up channel, NOT an ordered event log — no frame
+// carries an SSE `id:` and nothing durable may be hung off it.
+// See src/user-events/README.md.
+export {
+  MAX_INVALIDATION_KEYS,
+  USER_EVENT_RESYNC_REASONS,
+} from "./user-events/index";
+
+export {
+  ResourceInvalidatedEventSchema,
+  UserEventBaseSchema,
+  UserEventConnectedSchema,
+  UserEventResyncReasonSchema,
+  UserEventResyncSchema,
+  UserSseEventSchema,
+} from "./user-events/index";
+
+export type {
+  ResourceInvalidatedEvent,
+  UserEventConnected,
+  UserEventResync,
+  UserEventResyncReason,
+  UserSseEvent,
+} from "./user-events/index";
+
 // Chat domain types
 // @see PRD-00142 for share chat design rationale
 export type {
@@ -859,6 +889,7 @@ export {
   toQueryKey,
   fromQueryKey,
   matchesResourceKey,
+  isResourceKeyShape,
 } from "./resource-keys";
 
 // Resource response wrapper (typed versioning for cache invalidation)

package/src/resource-keys.ts

@@ -20,6 +20,15 @@ export type ResourceKey =
   | { type: "chat"; orgId: string; chatId: string }
   | { type: "companyMdDoc"; orgId: string; slug: string }
   | { type: "companyMdContextBank"; orgId: string; slug: string }
+  // The access requests filed against ONE document — the owner's inbox, read by
+  // the Share dialog.
+  //
+  // Discriminated by `docId`, NOT `slug`, and the difference is load-bearing.
+  // `companyMdDoc` above carries the stable doc id under a field named `slug`
+  // for historical reasons; ADR-BE-315 made slugs only PARENT-SCOPED unique, so
+  // a bare slug does not identify a document. That field name is a wart to be
+  // contained, not propagated — a new key gets the honest name.
+  | { type: "companyMdAccessRequests"; orgId: string; docId: string }
   | { type: "workspace"; orgId: string }
   | { type: "workspaceDomains"; orgId: string }
   | { type: "authSettings"; orgId: string }
@@ -151,6 +160,8 @@ export function toQueryKey(key: ResourceKey): readonly string[] {
     case "companyMdDoc":
     case "companyMdContextBank":
       return [key.type, key.orgId, key.slug] as const;
+    case "companyMdAccessRequests":
+      return [key.type, key.orgId, key.docId] as const;
 
     // OrgUnit identity keys (ADR-BE-120)
     case "orgUnit":
@@ -228,6 +239,7 @@ export function fromQueryKey(queryKey: readonly string[]): ResourceKey {
     chat: "chatId",
     companyMdDoc: "slug",
     companyMdContextBank: "slug",
+    companyMdAccessRequests: "docId",
     orgUnit: "unitId",
     orgUnitChildren: "unitId",
     orgUnitAncestors: "unitId",
@@ -327,6 +339,12 @@ export function matchesResourceKey(
     return false;
   if ("slug" in parsed && "slug" in targetKey && parsed.slug !== targetKey.slug)
     return false;
+  if (
+    "docId" in parsed &&
+    "docId" in targetKey &&
+    parsed.docId !== targetKey.docId
+  )
+    return false;
   if (
     "unitId" in parsed &&
     "unitId" in targetKey &&
@@ -343,6 +361,37 @@ export function matchesResourceKey(
   return true;
 }
 
+/**
+ * Is this the SHAPE of a ResourceKey?
+ *
+ * A wire-boundary predicate, deliberately NOT a vocabulary check: it asserts a
+ * non-empty `type` and exactly one scope discriminator, and says nothing about
+ * whether `type` is a member of the union.
+ *
+ * The asymmetry is the point. `ResourceKey` is a large union whose authority is
+ * `toQueryKey`'s exhaustive switch; a Zod mirror of it would be a second source
+ * of truth that drifts. Worse, a vocabulary-strict gate would REJECT AN ENTIRE
+ * FRAME when a newer backend names a key this client's contracts version has
+ * not learned yet — today an unknown key simply matches no query and the rest
+ * of the frame still lands, which is the behaviour worth keeping.
+ * `matchesResourceKey` is already lenient about unknown types at runtime, so a
+ * stricter gate here would be the only place in the pipeline that hard-fails on
+ * a key it merely does not recognise.
+ *
+ * Used by the user-event wire schema (`../user-events`) to validate
+ * `resource.invalidated` payloads without importing the union's vocabulary.
+ */
+export function isResourceKeyShape(value: unknown): value is ResourceKey {
+  if (typeof value !== "object" || value === null) return false;
+  const candidate = value as Record<string, unknown>;
+  if (typeof candidate.type !== "string" || candidate.type.length === 0)
+    return false;
+  const scopeCount = ["orgId", "userId", "scope"].filter(
+    (field) => typeof candidate[field] === "string",
+  ).length;
+  return scopeCount === 1;
+}
+
 function isReadonlyArray(value: unknown): value is readonly unknown[] {
   return Array.isArray(value);
 }

package/src/security/token-policy.ts

@@ -61,28 +61,14 @@ export const AUTH_TOKEN_POLICY_REQUIREMENTS = {
     hashAlgorithm: "SHA-256",
     storageFormat: "hashed",
     contextPatterns: ["session"],
-    conformance: {
-      status: "unmet",
-      gap:
-        "Issuance now conforms: minted by issueCapabilityToken at 256 bits and " +
-        "stored as a sha256:v1: digest (ADR-BE-460 deploy B). Still UNMET because " +
-        "the dual-read window is open — sessions.token retains the raw value so a " +
-        "rollback keeps working, and every lookup carries a plaintext fallback arm. " +
-        "Conformance is reached when migration C retires the column and deploy D " +
-        "removes the fallbacks.",
-    },
+    conformance: { status: "enforced" },
   },
   ChatShareToken: {
     minEntropyBits: 256,
     hashAlgorithm: "SHA-256",
     storageFormat: "hashed",
     contextPatterns: ["share"],
-    conformance: {
-      status: "unmet",
-      gap:
-        "Minted with randomBytes(32) and persisted verbatim: chat_shares.token holds " +
-        "the share-URL value itself, and lookup is raw equality against it.",
-    },
+    conformance: { status: "enforced" },
   },
   InviteToken: {
     minEntropyBits: 256,

package/src/user-events/README.md

@@ -0,0 +1,66 @@
+# user-events/
+
+## Purpose
+
+The published wire contract for the **user-scoped push stream** — the frames any
+domain may send to one authenticated user without owning a route or an SSE union
+of its own.
+
+## Invariants
+
+- **This stream is a wake-up channel plus ephemeral cache hints. It is NOT an
+  ordered event log.** Publishing a user event grants no replay guarantee, and
+  no durable effect may be hung off it.
+- **No frame carries an SSE `id:` line.** An id implies a resumable position;
+  there is no log behind this stream, so an id would be a lie. Contrast
+  `ExecutionSseEvent`, whose `eventSequence` legitimately doubles as
+  `Last-Event-ID` because it projects a durable row (ADR-CONT-066).
+- **Delivery is edge-triggered only.** A missed frame may leave caches stale
+  until the next authoritative refresh. Acceptable because no correctness
+  depends on invalidations — every frame means "re-read this", and the read is
+  the authority.
+- **`resource.invalidated.keys` validates shape, not vocabulary.** A
+  vocabulary-strict gate would reject an entire frame when a newer server names
+  a key this client has not learned. Today an unknown key matches no query and
+  the rest of the frame still lands.
+- **`version` is an entity timestamp, never request time.** A request-time value
+  silently re-opens the race the client's version gate exists to close.
+- **`v`/`timestamp` are optional on `resource.invalidated`, `resync` and
+  `connected`, and required nowhere else.** The invalidation frame was already
+  on the wire without them; requiring them would make promotion a breaking
+  change dressed as a tidy-up.
+
+## Public API
+
+| Export                                | Description                                       |
+| ------------------------------------- | ------------------------------------------------- |
+| `UserSseEventSchema` / `UserSseEvent` | The union. OpenAPI component `UserSseEvent`.      |
+| `ResourceInvalidatedEventSchema`      | Cache-staleness signal carrying `ResourceKey[]`   |
+| `UserEventResyncSchema`               | "Could not name what changed; re-read everything" |
+| `UserEventConnectedSchema`            | Transport-level open frame                        |
+| `MAX_INVALIDATION_KEYS`               | Per-frame key cap (`16`)                          |
+| `USER_EVENT_RESYNC_REASONS`           | `listen-recovered` \| `payload-over-cap`          |
+
+## Dependencies
+
+- `zod` — schemas are canonical, types are inferred.
+- `../resource-keys` — `ResourceKey`, `isResourceKeyShape`.
+
+Nothing else. In particular: no `notifications/`, no `action-items/`.
+
+## How this differs from the two adjacent vocabularies
+
+Three things in this package can look like "a notification". They are distinct,
+and ADR-CONT-104 forbids collapsing them:
+
+- **`NotificationKind`** (`../notifications`) names a message that **leaves the
+  building** to a durable address, composed by a render pipeline into prose
+  carrying a brand and a year.
+- **`ActionItemKind`** (`../action-items`) names **standing state** — a decision
+  you owe — re-derived from source rows on every read, which stops existing when
+  someone resolves it.
+- **A user event** is neither. It is a single instant on a socket, unreplayable
+  and unaddressable, whose entire meaning is "your cached view is stale".
+
+A domain that needs durability emits the durable thing **and** a user event —
+never a user event alone.

package/src/user-events/__tests__/README.md

@@ -0,0 +1,43 @@
+# user-events/\_\_tests\_\_/
+
+## Purpose
+
+Locks the claims `../README.md` and ADR-CONT-107 make that the compiler cannot.
+
+- `user-events.test.ts` — four things a type signature does not say:
+  1. **Promotion did not change the wire.** The load-bearing test of the whole
+     module. `resource.invalidated` was already deployed, emitted by the backend
+     and re-declared structurally in the app, carrying neither `v` nor
+     `timestamp`. The schema is pinned against that exact object. If it fails,
+     publishing the shape broke every client already running.
+  2. **An unknown key type is ACCEPTED.** The reason `keys` validates shape and
+     not vocabulary. A newer server naming a key this contracts version has not
+     learned must cost that one key, never the whole frame. A strict gate here
+     would be the only place in the pipeline that hard-fails on version skew.
+  3. **An unmodeled frame `type` is REJECTED.** So the client logs it instead of
+     silently dropping it. The two rules pull in opposite directions on purpose:
+     lenient about payload vocabulary, strict about frame identity.
+  4. **`resource.invalidated` rejects an `ActionItem`-shaped payload.** What
+     stops the future "just reuse ActionItem on the stream" change. An action
+     item is re-derived on every read and resolves when someone acts; it cannot
+     be delivered once and forgotten.
+
+## Invariants
+
+- These tests assert the WIRE, never behaviour — there is no behaviour here.
+  Anything needing a socket, a dispatcher or a database belongs in backend's
+  `src/user-events/__tests__/`, not here.
+- The disjointness test reads `ACTION_ITEM_KINDS` rather than restating the
+  kinds. A hand-copied list would drift and start passing vacuously.
+- Negative cases assert `.success === false` on a frame that is otherwise
+  well-formed, mutating one field. A negative test that hand-builds a broken
+  object can pass for the wrong reason.
+
+## Public API
+
+None — test-only.
+
+## Dependencies
+
+`vitest`, the sibling module under test, `../../action-items` (for the real kind
+list), and `../../resource-keys` (for `isResourceKeyShape`).

package/src/user-events/__tests__/user-events.test.ts

@@ -0,0 +1,196 @@
+/**
+ * The user-event wire contract's invariants, as tests rather than prose.
+ *
+ * These lock the claims the README makes that a compiler cannot: that promoting
+ * `resource.invalidated` did not change the wire, that key validation is
+ * forward-compatible across version skew, and that this vocabulary is separate
+ * from the two adjacent ones (ADR-CONT-104).
+ */
+import { describe, it, expect } from "vitest";
+import {
+  MAX_INVALIDATION_KEYS,
+  ResourceInvalidatedEventSchema,
+  USER_EVENT_RESYNC_REASONS,
+  UserEventConnectedSchema,
+  UserEventResyncSchema,
+  UserSseEventSchema,
+} from "../schemas.js";
+import { ACTION_ITEM_KINDS } from "../../action-items/index.js";
+import { isResourceKeyShape } from "../../resource-keys.js";
+
+const ORG_ID = "11111111-1111-4111-8111-111111111111";
+const DOC_ID = "22222222-2222-4222-8222-222222222222";
+
+describe("resource.invalidated — promotion must not change the wire", () => {
+  it("parses the EXACT object the backend emits today", () => {
+    // Verbatim shape of `ResourceInvalidationEvent` in backend
+    // src/chat/execution/resource-invalidation.ts: no `v`, no `timestamp`.
+    // If this fails, promoting the interface into contracts broke the wire and
+    // every already-deployed client stops receiving invalidations.
+    const onTheWireToday = {
+      type: "resource.invalidated",
+      keys: [{ type: "actionItems", orgId: ORG_ID }],
+      traceId: "trace-1",
+      version: 1785312000000,
+    };
+
+    expect(
+      ResourceInvalidatedEventSchema.safeParse(onTheWireToday).success,
+    ).toBe(true);
+  });
+
+  it("accepts a frame with neither traceId nor the base fields", () => {
+    expect(
+      ResourceInvalidatedEventSchema.safeParse({
+        type: "resource.invalidated",
+        keys: [
+          { type: "companyMdAccessRequests", orgId: ORG_ID, docId: DOC_ID },
+        ],
+        version: 0,
+      }).success,
+    ).toBe(true);
+  });
+
+  it("rejects a request-time version that is not an epoch integer", () => {
+    const result = ResourceInvalidatedEventSchema.safeParse({
+      type: "resource.invalidated",
+      keys: [{ type: "actionItems", orgId: ORG_ID }],
+      version: 1.5,
+    });
+    expect(result.success).toBe(false);
+  });
+
+  it("rejects an empty key list — a frame naming nothing is a bug, not a no-op", () => {
+    expect(
+      ResourceInvalidatedEventSchema.safeParse({
+        type: "resource.invalidated",
+        keys: [],
+        version: 1,
+      }).success,
+    ).toBe(false);
+  });
+
+  it("caps keys so the envelope cannot approach the NOTIFY payload limit", () => {
+    const overCap = Array.from({ length: MAX_INVALIDATION_KEYS + 1 }, () => ({
+      type: "actionItems",
+      orgId: ORG_ID,
+    }));
+    expect(
+      ResourceInvalidatedEventSchema.safeParse({
+        type: "resource.invalidated",
+        keys: overCap,
+        version: 1,
+      }).success,
+    ).toBe(false);
+  });
+});
+
+describe("key validation is forward-compatible across version skew", () => {
+  it("ACCEPTS a key type this contracts version has never heard of", () => {
+    // The whole reason `keys` validates shape and not vocabulary. A newer
+    // server naming a key we do not know must not cost us the ENTIRE frame —
+    // the unknown key matches no query, the known ones still land.
+    const result = ResourceInvalidatedEventSchema.safeParse({
+      type: "resource.invalidated",
+      keys: [
+        { type: "somethingShippedAfterThisClient", orgId: ORG_ID },
+        { type: "actionItems", orgId: ORG_ID },
+      ],
+      version: 1,
+    });
+    expect(result.success).toBe(true);
+  });
+
+  it("rejects a key with no scope discriminator", () => {
+    expect(isResourceKeyShape({ type: "actionItems" })).toBe(false);
+  });
+
+  it("rejects a key with two scope discriminators", () => {
+    expect(
+      isResourceKeyShape({ type: "actionItems", orgId: ORG_ID, userId: "u1" }),
+    ).toBe(false);
+  });
+
+  it("rejects non-objects and an empty type", () => {
+    expect(isResourceKeyShape(null)).toBe(false);
+    expect(isResourceKeyShape("actionItems")).toBe(false);
+    expect(isResourceKeyShape({ type: "", orgId: ORG_ID })).toBe(false);
+  });
+});
+
+describe("resync", () => {
+  it("accepts every declared reason", () => {
+    for (const reason of USER_EVENT_RESYNC_REASONS) {
+      expect(
+        UserEventResyncSchema.safeParse({ type: "resync", reason }).success,
+      ).toBe(true);
+    }
+  });
+
+  it("rejects an undeclared reason", () => {
+    expect(
+      UserEventResyncSchema.safeParse({ type: "resync", reason: "because" })
+        .success,
+    ).toBe(false);
+  });
+});
+
+describe("the union", () => {
+  it("discriminates every member on `type`", () => {
+    const frames = [
+      {
+        type: "resource.invalidated",
+        keys: [{ type: "actionItems", orgId: ORG_ID }],
+        version: 1,
+      },
+      { type: "resync", reason: "listen-recovered" },
+      { type: "connected" },
+    ];
+    for (const frame of frames) {
+      expect(UserSseEventSchema.safeParse(frame).success).toBe(true);
+    }
+  });
+
+  it("rejects an unmodeled type so the client LOGS it rather than silently dropping", () => {
+    expect(
+      UserSseEventSchema.safeParse({ type: "notification.created", id: "n1" })
+        .success,
+    ).toBe(false);
+  });
+
+  it("models `connected` at all — an unmodeled open frame would log a parse error on every connect", () => {
+    expect(
+      UserEventConnectedSchema.safeParse({ type: "connected" }).success,
+    ).toBe(true);
+  });
+});
+
+describe("boundary with the two adjacent vocabularies (ADR-CONT-104)", () => {
+  it("shares no member name with ActionItemKind", () => {
+    // Not symmetry policing — a shared string would make one of the two
+    // meanings lie, since an action item is standing state and a user event is
+    // a single unreplayable instant.
+    const frameTypes = new Set(["resource.invalidated", "resync", "connected"]);
+    for (const kind of ACTION_ITEM_KINDS) {
+      expect(frameTypes.has(kind)).toBe(false);
+    }
+  });
+
+  it("REJECTS an ActionItem-shaped payload", () => {
+    // The test that stops the future "just reuse ActionItem on the stream" PR.
+    // An action item is re-derived on every read and resolves when someone
+    // acts; it cannot be delivered once and forgotten.
+    const actionItemShaped = {
+      type: "resource.invalidated",
+      id: "companyMd.access_request_pending:req-1",
+      kind: "companyMd.access_request_pending",
+      target: { type: "company_md", id: DOC_ID },
+      unitPath: "acme.sales",
+      title: "Maya Chen wants access",
+      href: "/@acme/md/doc-1?share=1",
+    };
+    expect(
+      ResourceInvalidatedEventSchema.safeParse(actionItemShaped).success,
+    ).toBe(false);
+  });
+});

package/src/user-events/index.ts

@@ -0,0 +1,25 @@
+/**
+ * user-events/ — the frames any domain may put on ONE user's connection.
+ *
+ * See ./README.md for the domain and for why this is neither
+ * `NotificationKind` nor `ActionItemKind`.
+ */
+
+export {
+  MAX_INVALIDATION_KEYS,
+  ResourceInvalidatedEventSchema,
+  USER_EVENT_RESYNC_REASONS,
+  UserEventBaseSchema,
+  UserEventConnectedSchema,
+  UserEventResyncReasonSchema,
+  UserEventResyncSchema,
+  UserSseEventSchema,
+} from "./schemas";
+
+export type {
+  ResourceInvalidatedEvent,
+  UserEventConnected,
+  UserEventResync,
+  UserEventResyncReason,
+  UserSseEvent,
+} from "./schemas";

package/src/user-events/schemas.ts

@@ -0,0 +1,173 @@
+/**
+ * The user-scoped push envelope — every frame the server sends to ONE
+ * authenticated user on a long-lived connection, regardless of domain.
+ *
+ * WHY THIS IS NOT A FIFTH `<Domain>SseEvent`. `ChatSseEvent`,
+ * `ExecutionSseEvent`, `CompanyMdCollabSseEvent` and `ImpersonationSseEvent`
+ * each describe ONE domain's traffic on ONE route. This union describes the
+ * frames any domain may put on the user's connection WITHOUT owning a route or
+ * a union of its own — which is exactly what `resource.invalidated` has been
+ * doing unpublished (backend `src/chat/execution/resource-invalidation.ts`,
+ * redeclared structurally in app `src/hooks/useChatEvents.ts`) since before
+ * there was a place to put it.
+ *
+ * WHAT THIS STREAM IS, STATED SO NOBODY ASSUMES MORE:
+ *
+ *   It is a wake-up channel plus ephemeral cache hints. It is NOT a general
+ *   ordered event log. Publishing a user event grants NO replay guarantee.
+ *
+ * Two rules encode that, and both are load-bearing:
+ *
+ * - **No frame carries an SSE `id:` line.** An id implies a resumable position;
+ *   there is no log behind this stream, so an id would be a lie. (Contrast
+ *   `ExecutionSseEvent`, whose `eventSequence` doubles as `Last-Event-ID`
+ *   because it projects a durable `execution_events` row — ADR-CONT-066.)
+ * - **Delivery is edge-triggered only.** Missing a frame may leave caches stale
+ *   until the next authoritative refresh. That is acceptable because NO
+ *   CORRECTNESS DEPENDS ON INVALIDATIONS — every frame means "re-read this",
+ *   and the read is the authority. Nothing durable may ever be hung off this
+ *   stream without first giving it a real commit-ordered log.
+ */
+import { z } from "zod";
+import type { ResourceKey } from "../resource-keys";
+import { isResourceKeyShape } from "../resource-keys";
+
+/**
+ * Local, not chat's. `chat/schemas.ts` owns a structurally identical helper;
+ * importing it would make a chat frame change a user-events breaking change.
+ */
+const IsoDateString = z.string().datetime();
+
+/**
+ * Fields every frame carries.
+ *
+ * Structurally identical to chat's `BaseEventSchema` on purpose, so folding
+ * chat onto this envelope later is a no-op — but deliberately NOT the same
+ * object, for the reason above.
+ */
+export const UserEventBaseSchema = z.object({
+  v: z.literal(1),
+  timestamp: IsoDateString,
+});
+
+// =============================================================================
+// resource.invalidated — promoted verbatim from the ad-hoc backend interface
+// =============================================================================
+
+/** Upper bound on keys per frame. Keeps the envelope far under NOTIFY's limit. */
+export const MAX_INVALIDATION_KEYS = 16;
+
+/**
+ * A cache-staleness signal. The client refreshes the named keys and shows the
+ * user nothing.
+ *
+ * `keys` validates SHAPE, not VOCABULARY — see `isResourceKeyShape` for why a
+ * vocabulary-strict gate here would reject whole frames on version skew.
+ *
+ * `v` and `timestamp` are OPTIONAL HERE AND NOWHERE ELSE. The frame already on
+ * the wire carries neither; requiring them would make promotion a breaking
+ * change dressed up as a tidy-up. Same carve-out, same reason, as
+ * `CompanyMdCollabConnectedEventSchema`.
+ */
+export const ResourceInvalidatedEventSchema = UserEventBaseSchema.partial({
+  v: true,
+  timestamp: true,
+}).extend({
+  type: z.literal("resource.invalidated"),
+  keys: z
+    .array(z.custom<ResourceKey>(isResourceKeyShape))
+    .min(1)
+    .max(MAX_INVALIDATION_KEYS),
+  /** Correlates the frame with the mutation that caused it. */
+  traceId: z.string().optional(),
+  /**
+   * Entity version — MUST be the entity's own `updatedAt`/`resolvedAt` as epoch
+   * ms, NEVER request time. The client's version gate compares it against the
+   * cached payload's `version`; a request-time value silently re-opens the race
+   * the gate exists to close. (The invariant the backend module already states,
+   * published here so it binds the wire rather than one emitter.)
+   */
+  version: z.number().int().nonnegative(),
+});
+export type ResourceInvalidatedEvent = z.infer<
+  typeof ResourceInvalidatedEventSchema
+>;
+
+// =============================================================================
+// resync — freshness when precision is unavailable
+// =============================================================================
+
+/**
+ * Why the server could not name what changed.
+ *
+ * - `listen-recovered` — the LISTEN connection was down and frames were missed.
+ * - `payload-over-cap`  — a single frame exceeded the NOTIFY payload limit.
+ */
+export const USER_EVENT_RESYNC_REASONS = [
+  "listen-recovered",
+  "payload-over-cap",
+] as const;
+export const UserEventResyncReasonSchema = z.enum(USER_EVENT_RESYNC_REASONS);
+export type UserEventResyncReason = z.infer<typeof UserEventResyncReasonSchema>;
+
+/**
+ * "I could not tell you precisely what changed; re-read everything."
+ *
+ * The client invalidates every resource it subscribes to. One frame type covers
+ * both reasons because they mean the same thing to a client, and because the
+ * alternative in each case is worse:
+ *
+ * - Truncating an over-cap frame yields a SHORTENED `keys` array — a stale
+ *   cache that looks fresh, which is undetectable downstream.
+ * - Dropping it instead leaves that user stale until their next reconnect,
+ *   which may be hours away.
+ *
+ * **Precision is expendable; freshness is not.** A resync costs one refetch
+ * wave and is always correct.
+ */
+export const UserEventResyncSchema = UserEventBaseSchema.partial({
+  v: true,
+  timestamp: true,
+}).extend({
+  type: z.literal("resync"),
+  reason: UserEventResyncReasonSchema,
+});
+export type UserEventResync = z.infer<typeof UserEventResyncSchema>;
+
+// =============================================================================
+// connected — transport-level
+// =============================================================================
+
+/**
+ * The stream is open.
+ *
+ * Modeled for the same reason `CompanyMdCollabConnectedEventSchema` is: without
+ * it, a client that validates EVERY frame logs a parse error on a perfectly
+ * normal connect.
+ */
+export const UserEventConnectedSchema = UserEventBaseSchema.partial({
+  v: true,
+  timestamp: true,
+}).extend({ type: z.literal("connected") });
+export type UserEventConnected = z.infer<typeof UserEventConnectedSchema>;
+
+// =============================================================================
+// The union
+// =============================================================================
+
+/**
+ * Every frame the user-scoped stream emits.
+ *
+ * Registered as the OpenAPI component `UserSseEvent`, per the `ChatSseEvent` /
+ * `ExecutionSseEvent` / `CompanyMdCollabSseEvent` precedent.
+ *
+ * `server_drain` is deliberately NOT modeled: the stream already emits it under
+ * its own SSE `event:` name and the client binds a dedicated out-of-band
+ * listener for it. Adding it here would create two handling paths for one frame.
+ */
+export const UserSseEventSchema = z.discriminatedUnion("type", [
+  ResourceInvalidatedEventSchema,
+  UserEventResyncSchema,
+  UserEventConnectedSchema,
+]);
+export type UserSseEvent = z.infer<typeof UserSseEventSchema>;