@company-semantics/contracts 43.0.0 → 44.1.0

package/package.json

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

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

package/src/api/generated.ts

@@ -2876,6 +2876,60 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/api/me/feed": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * What I owe and what happened, merged, newest first
+         * @description Actionable rows first, then informational rows newest-first — grouped, not chronologically interleaved. Only the informational half paginates.
+         */
+        get: operations["listMyFeed"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/api/me/feed/read": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /** Mark specific notifications read */
+        post: operations["markMyFeedRead"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/api/me/feed/read-all": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /** Mark every notification read */
+        post: operations["markMyFeedAllRead"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/api/me/meetings/recordings/start": {
         parameters: {
             query?: never;
@@ -5513,6 +5567,51 @@ export interface components {
                 createdAt: string;
             }[];
         };
+        FeedListResponse: {
+            items: ({
+                /** @constant */
+                row: "actionable";
+                item: {
+                    id: string;
+                    /** @enum {string} */
+                    kind: "companyMd.access_request_pending" | "execution.confirmation_pending";
+                    target: {
+                        /** @enum {string} */
+                        type: "company_md" | "org_unit" | "org" | "execution";
+                        id: string;
+                    };
+                    unitPath: string | null;
+                    title: string;
+                    detail: string | null;
+                    contextLabel: string;
+                    href: string;
+                    createdAt: string;
+                };
+            } | {
+                /** @constant */
+                row: "informational";
+                notification: {
+                    id: string;
+                    /** @enum {string} */
+                    kind: "companyMd.access_requested" | "companyMd.access_request_approved" | "companyMd.access_request_denied";
+                    target: {
+                        /** @enum {string} */
+                        type: "company_md" | "org_unit" | "org" | "execution";
+                        id: string;
+                    };
+                    unitPath: string | null;
+                    title: string;
+                    detail: string | null;
+                    contextLabel: string;
+                    href: string | null;
+                    createdAt: string;
+                    readAt: string | null;
+                };
+            })[];
+            nextCursor: string | null;
+            unreadCount: number;
+            truncated: boolean;
+        };
         /** @description Recording + work_item ids and the transcription session grant. */
         StartMeetingRecordingResponse: {
             /** @description ULID; unified trace key for the recording (INV-MTG-7). */
@@ -10766,6 +10865,62 @@ export interface operations {
             };
         };
     };
+    listMyFeed: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description One page of the merged feed for the current user */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["FeedListResponse"];
+                };
+            };
+        };
+    };
+    markMyFeedRead: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Read state applied to the actor’s own rows */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+        };
+    };
+    markMyFeedAllRead: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Read state applied to the actor’s own rows */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+        };
+    };
     startMeetingRecording: {
         parameters: {
             query?: never;

package/src/generated/openapi-routes.ts

@@ -75,6 +75,9 @@ export const openApiRoutes = {
   '/api/me': ['GET'],
   '/api/me/access-list': ['GET'],
   '/api/me/action-items': ['GET'],
+  '/api/me/feed': ['GET'],
+  '/api/me/feed/read': ['POST'],
+  '/api/me/feed/read-all': ['POST'],
   '/api/me/meetings/recordings/start': ['POST'],
   '/api/me/meetings/recordings/{id}': ['DELETE'],
   '/api/me/meetings/recordings/{id}/complete': ['POST'],

package/src/index.ts

@@ -289,6 +289,7 @@ export {
 } from "./user-events/index";
 
 export type {
+  NotificationCreatedEvent,
   ResourceInvalidatedEvent,
   UserEventConnected,
   UserEventResync,
@@ -296,6 +297,31 @@ export type {
   UserSseEvent,
 } from "./user-events/index";
 
+// Durable in-app inbox + the merged feed that renders it (ADR-CONT-108). The
+// THIRD vocabulary beside NotificationKind and ActionItemKind: a notification
+// leaves the building, an action item is standing state you can resolve, and
+// one of these is a stored fact you can only look at. Rows hold identifiers
+// only — every prose field is rendered at read time under the reader's CURRENT
+// authority, which is what keeps a stale row from leaking anything.
+// See src/user-notifications/README.md.
+export { USER_NOTIFICATION_KINDS } from "./user-notifications/index";
+
+export {
+  FeedItemSchema,
+  FeedListResponseSchema,
+  FeedMarkReadRequestSchema,
+  UserNotificationKindSchema,
+  UserNotificationSchema,
+} from "./user-notifications/index";
+
+export type {
+  FeedItem,
+  FeedListResponse,
+  FeedMarkReadRequest,
+  UserNotification,
+  UserNotificationKind,
+} from "./user-notifications/index";
+
 // Chat domain types
 // @see PRD-00142 for share chat design rationale
 export type {

package/src/resource-keys.ts

@@ -71,6 +71,15 @@ export type ResourceKey =
   // `timeline`, which are likewise viewer-filtered but org-partitioned — and it
   // inherits `resolveScope`'s impersonation handling for free.
   | { type: "actionItems"; orgId: string }
+  // The merged top-of-/me/work read: action items AND the durable inbox
+  // (ADR-CONT-108). Org-scoped for the same reason `actionItems` is — the
+  // content is per-viewer but the bucket differs per org, so a user-keyed entry
+  // would serve one org's feed after switching to another.
+  //
+  // Distinct from `actionItems` rather than replacing it: that key still backs
+  // every badge in the shell, and the two have different invalidation triggers
+  // (a notification being READ changes the feed and not the bucket).
+  | { type: "feed"; orgId: string }
   // User-scoped
   | { type: "dismissedBanners"; userId: string }
   | { type: "userOrgs"; userId: string }
@@ -115,6 +124,7 @@ const ORG_SCOPED_TYPES = [
   "peopleOrgChart",
   "orgUnitOwners",
   "actionItems",
+  "feed",
 ] as const;
 
 const USER_SCOPED_TYPES = [
@@ -201,6 +211,7 @@ export function toQueryKey(key: ResourceKey): readonly string[] {
     case "peopleOrgChart":
     case "orgUnitOwners":
     case "actionItems":
+    case "feed":
       return [key.type, key.orgId] as const;
 
     // System-scoped (ADR-CONTRACTS-052) — tenant-less super-admin resources

package/src/user-events/index.ts

@@ -7,6 +7,7 @@
 
 export {
   MAX_INVALIDATION_KEYS,
+  NotificationCreatedEventSchema,
   ResourceInvalidatedEventSchema,
   USER_EVENT_RESYNC_REASONS,
   UserEventBaseSchema,
@@ -17,6 +18,7 @@ export {
 } from "./schemas";
 
 export type {
+  NotificationCreatedEvent,
   ResourceInvalidatedEvent,
   UserEventConnected,
   UserEventResync,

package/src/user-events/schemas.ts

@@ -134,6 +134,46 @@ export const UserEventResyncSchema = UserEventBaseSchema.partial({
 });
 export type UserEventResync = z.infer<typeof UserEventResyncSchema>;
 
+// =============================================================================
+// notification.created — an ACCELERATOR, never the source of truth
+// =============================================================================
+
+/**
+ * A durable notification row was written for this user.
+ *
+ * AN ACCELERATOR ONLY. The row is already committed and the inbox
+ * (`GET /api/me/feed`) is the authority; this frame exists so a connected
+ * client sees it without waiting for a refetch. A client that misses it loses
+ * nothing — the row is still there on the next read, which is exactly why this
+ * stream is allowed to stay best-effort.
+ *
+ * That is also why it carries only the id and the unread count, not the
+ * rendered notification. Rendering happens at READ TIME under the reader's
+ * current authority (see `UserNotificationSchema`); a pre-rendered payload on
+ * the wire would be a snapshot of authority taken at write time, which is the
+ * one thing that must not be cached. It would also put entity content on a
+ * `pg_notify` payload, which the transport forbids for its own reasons.
+ *
+ * There is deliberately NO `notification.read` counterpart. Read state is a
+ * mutable column on a row whose id was allocated at creation, so a read event
+ * has no valid position in a stream ordered by anything — it would either move
+ * an id backwards or reuse one already observed. Read state is reconciled from
+ * the authoritative query instead.
+ */
+export const NotificationCreatedEventSchema = UserEventBaseSchema.partial({
+  v: true,
+  timestamp: true,
+}).extend({
+  type: z.literal("notification.created"),
+  /** The row id, so a client that already has it can dedupe. */
+  notificationId: z.string(),
+  /** Total unread after this write, so the badge updates without a fetch. */
+  unreadCount: z.number().int().nonnegative(),
+});
+export type NotificationCreatedEvent = z.infer<
+  typeof NotificationCreatedEventSchema
+>;
+
 // =============================================================================
 // connected — transport-level
 // =============================================================================
@@ -167,6 +207,7 @@ export type UserEventConnected = z.infer<typeof UserEventConnectedSchema>;
  */
 export const UserSseEventSchema = z.discriminatedUnion("type", [
   ResourceInvalidatedEventSchema,
+  NotificationCreatedEventSchema,
   UserEventResyncSchema,
   UserEventConnectedSchema,
 ]);

package/src/user-notifications/README.md

@@ -0,0 +1,72 @@
+# user-notifications/
+
+## Purpose
+
+The published shapes of the **durable in-app inbox** — informational facts
+addressed to one user, which they can only look at — and of the **merged feed**
+that renders them alongside action items at the top of `/me/work`.
+
+## Invariants
+
+- **A stored row holds IDENTIFIERS ONLY**: `kind` plus a `ref` of ids. No
+  titles, no paths, no names, no bodies. Everything in `UserNotificationSchema`
+  that reads like prose is produced at READ TIME by the producing domain's
+  renderer, under the reader's CURRENT authority.
+- **A stored row therefore never contains protected content**, so a stale row
+  cannot leak one. This is the invariant the whole design turns on: it is what
+  makes copy evolution a renderer change rather than a migration, and what makes
+  revocation a re-check rather than a backfill.
+- **`href` is nullable and a tombstone is a legitimate render.** A reader who
+  lost access, or whose client cannot decode the stored `ref_version`, still
+  sees that the thing happened — it simply does not link anywhere. "You were
+  granted access to something you can no longer see" is true and worth saying.
+- **Feed ordering is grouped, not chronologically interleaved.** Actionable rows
+  first, then informational rows newest-first. "Merged feed" names one visual
+  surface, not one timeline.
+- **Only notifications paginate.** Action items are already bounded and are
+  standing state, not a timeline. Page 1 = all action items + the first page of
+  notifications; every later page is notifications only. Paginating two
+  independent sources against one cursor is where merged feeds go wrong.
+- **`unreadCount` is total, never windowed.** A windowed count under-reports the
+  moment the inbox exceeds one page, and it drives a badge whose whole job is to
+  be trusted.
+- **The cursor encodes `(createdAt, id)`.** The id breaks ties so two rows
+  written in one transaction cannot straddle a page boundary and be served twice
+  or skipped.
+
+## Public API
+
+| Export                      | Description                                                    |
+| --------------------------- | -------------------------------------------------------------- |
+| `UserNotificationSchema`    | One informational row, as rendered                             |
+| `USER_NOTIFICATION_KINDS`   | The closed kind vocabulary                                     |
+| `FeedItemSchema`            | `actionable` \| `informational`, discriminated on `row`        |
+| `FeedListResponseSchema`    | `GET /api/me/feed` — items, nextCursor, unreadCount, truncated |
+| `FeedMarkReadRequestSchema` | `POST /api/me/feed/read`                                       |
+
+## Dependencies
+
+- `zod` — schemas are canonical, types are inferred.
+- `../action-items` — `ActionItemSchema`, `ActionItemTargetSchema`. The feed
+  UNIONS with action items; it does not redefine them, and it does not modify
+  them.
+
+## How this differs from the two vocabularies beside it
+
+Three things in this package look like "a notification". ADR-CONT-104 forbids
+collapsing the first two; this adds a third rather than bending either:
+
+- **`NotificationKind`** (`../notifications`) names a message that **leaves the
+  building** — composed into prose, delivered once to an address, lifecycle over
+  at send.
+- **`ActionItemKind`** (`../action-items`) names **standing state** — a decision
+  you owe, re-derived on every read, gone the moment anyone resolves it. Never
+  stored, no read state.
+- **`UserNotificationKind`** names a **stored fact about the past**, addressed to
+  one person, that they can only look at. `action-items/kinds.ts` named this gap
+  itself: _"a kind whose item cannot be acted on is not an action item — that is
+  the informational feed, which this layer does not model (yet)."_
+
+They are not in bijection. `companyMd.access_request_pending` is an action item
+and deliberately has **no** member here: the owner can resolve it, so modelling
+it in both places would give one fact two lifecycles that could disagree.

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

@@ -0,0 +1,43 @@
+# user-notifications/\_\_tests\_\_/
+
+## Purpose
+
+Locks the claims `../README.md` and ADR-CONT-108 make that the compiler cannot.
+
+- `vocabulary.test.ts` — four things a type signature does not say:
+  1. **The three vocabularies stay disjoint.** `UserNotificationKind`,
+     `ActionItemKind` and `NotificationKind` overlap in subject matter and look
+     mergeable; they are not, because a notification's lifecycle ends at send, an
+     action item's ends when anyone resolves it, and one of these ends never.
+     Specifically: `companyMd.access_request_pending` must NOT appear here — it
+     is resolvable, so modelling it in both places would give one fact two
+     lifecycles that could disagree.
+  2. **A tombstone parses.** `href: null` is a legitimate render, not a
+     degenerate one: a reader who lost access still learns the thing happened.
+     If this stops parsing, revocation silently becomes an error path.
+  3. **`FeedItem` discriminates on `row`, not on field-sniffing.** A client must
+     never have to infer "informational" from the presence of `readAt`.
+  4. **The response carries no field named `version`.** The app's
+     `invalidateResource` probes cached payloads for that name structurally and
+     SKIPS the invalidation when the cached value is at least as new — the same
+     trap `action-items/__tests__` guards, and it would wedge the feed badge
+     with no error anywhere.
+
+## Invariants
+
+- These assert VOCABULARY and SHAPE, never behaviour. Anything needing a
+  renderer, a database or an authority gate belongs in backend's
+  `src/user-notifications/__tests__/`.
+- The disjointness test reads the real kind arrays rather than restating them. A
+  hand-copied list drifts and starts passing vacuously.
+- Negative cases mutate ONE field of a well-formed fixture. A hand-built broken
+  object can pass for the wrong reason.
+
+## Public API
+
+None — test-only.
+
+## Dependencies
+
+`vitest`, the sibling modules under test, and `../../action-items` /
+`../../notifications` for the real kind lists.

package/src/user-notifications/__tests__/vocabulary.test.ts

@@ -0,0 +1,170 @@
+/**
+ * The inbox vocabulary's invariants, as tests rather than prose (ADR-CONT-108).
+ */
+import { describe, it, expect } from "vitest";
+import { USER_NOTIFICATION_KINDS } from "../kinds.js";
+import {
+  FeedItemSchema,
+  FeedListResponseSchema,
+  UserNotificationSchema,
+} from "../schemas.js";
+import { ACTION_ITEM_KINDS } from "../../action-items/index.js";
+import { NOTIFICATION_DEFINITIONS } from "../../notifications/index.js";
+
+const ORG_DOC = "22222222-2222-4222-8222-222222222222";
+
+function makeNotification(over: Record<string, unknown> = {}) {
+  return {
+    id: "n-1",
+    kind: "companyMd.access_request_approved",
+    target: { type: "company_md", id: ORG_DOC },
+    unitPath: "acme.sales",
+    title: "Dev Patel approved your request",
+    detail: null,
+    contextLabel: "Q3 OKRs",
+    href: "/@acme/md/doc-1",
+    createdAt: "2026-07-30T12:00:00.000Z",
+    readAt: null,
+    ...over,
+  };
+}
+
+describe("the three vocabularies stay disjoint", () => {
+  it("shares no member with ActionItemKind", () => {
+    // They overlap in SUBJECT MATTER and look mergeable. They are not: an
+    // action item is standing state that ends when anyone resolves it; one of
+    // these is a stored fact that ends never.
+    const actionItems = new Set<string>(ACTION_ITEM_KINDS);
+    for (const kind of USER_NOTIFICATION_KINDS) {
+      expect(actionItems.has(kind)).toBe(false);
+    }
+  });
+
+  it("does NOT model the pending request, which is resolvable", () => {
+    // The load-bearing case. `companyMd.access_request_pending` is an ACTION
+    // ITEM — the owner can settle it. A durable twin would give one fact two
+    // lifecycles that could disagree: resolve the action item and the stored
+    // row would still claim something is pending.
+    expect(USER_NOTIFICATION_KINDS).not.toContain(
+      "companyMd.access_request_pending",
+    );
+  });
+
+  it("names kinds in {domain}.{type} form, matching both siblings", () => {
+    for (const kind of USER_NOTIFICATION_KINDS) {
+      expect(kind).toMatch(/^[a-z][a-zA-Z0-9]*\.[a-z][a-z0-9_]*$/);
+    }
+  });
+
+  it("overlaps NotificationKind by NAME without inheriting its lifecycle", () => {
+    // Reading the real definitions rather than restating them, so this cannot
+    // pass vacuously. An overlap here is EXPECTED and fine — the email and the
+    // stored row are two different things about one event. What must not happen
+    // is one union being derived from the other.
+    const sent = new Set(Object.keys(NOTIFICATION_DEFINITIONS));
+    const shared = USER_NOTIFICATION_KINDS.filter((k) => sent.has(k));
+    expect(shared.length).toBeGreaterThan(0);
+    expect(USER_NOTIFICATION_KINDS.length).not.toBe(sent.size);
+  });
+});
+
+describe("UserNotificationSchema", () => {
+  it("parses a well-formed row", () => {
+    expect(UserNotificationSchema.safeParse(makeNotification()).success).toBe(
+      true,
+    );
+  });
+
+  it("parses a TOMBSTONE — href null is a legitimate render", () => {
+    // A reader who lost access, or whose client cannot decode the stored
+    // ref_version, still learns the thing happened. If this stops parsing,
+    // revocation silently becomes an error path instead of a render.
+    expect(
+      UserNotificationSchema.safeParse(makeNotification({ href: null }))
+        .success,
+    ).toBe(true);
+  });
+
+  it("carries read state, unlike an action item", () => {
+    const read = UserNotificationSchema.parse(
+      makeNotification({ readAt: "2026-07-30T13:00:00.000Z" }),
+    );
+    expect(read.readAt).not.toBeNull();
+  });
+
+  it("rejects an unknown kind", () => {
+    expect(
+      UserNotificationSchema.safeParse(makeNotification({ kind: "made.up" }))
+        .success,
+    ).toBe(false);
+  });
+});
+
+describe("FeedItem discriminates on `row`", () => {
+  it("accepts an informational row", () => {
+    const parsed = FeedItemSchema.safeParse({
+      row: "informational",
+      notification: makeNotification(),
+    });
+    expect(parsed.success).toBe(true);
+  });
+
+  it("accepts an actionable row", () => {
+    const parsed = FeedItemSchema.safeParse({
+      row: "actionable",
+      item: {
+        id: "companyMd.access_request_pending:req-1",
+        kind: "companyMd.access_request_pending",
+        target: { type: "company_md", id: ORG_DOC },
+        unitPath: null,
+        title: "Maya Chen wants access",
+        detail: null,
+        contextLabel: "Q3 OKRs",
+        href: "/@acme/md/doc-1?share=1&request=req-1",
+        createdAt: "2026-07-30T12:00:00.000Z",
+      },
+    });
+    expect(parsed.success).toBe(true);
+  });
+
+  it("cannot be satisfied by field-sniffing — the tag is required", () => {
+    // A client must never infer "informational" from the presence of `readAt`.
+    expect(
+      FeedItemSchema.safeParse({ notification: makeNotification() }).success,
+    ).toBe(false);
+  });
+});
+
+describe("FeedListResponse", () => {
+  const base = {
+    items: [],
+    nextCursor: null,
+    unreadCount: 0,
+    truncated: false,
+  };
+
+  it("parses an empty feed", () => {
+    expect(FeedListResponseSchema.safeParse(base).success).toBe(true);
+  });
+
+  it("carries a cursor for the next page of informational rows", () => {
+    expect(
+      FeedListResponseSchema.safeParse({ ...base, nextCursor: "opaque" })
+        .success,
+    ).toBe(true);
+  });
+
+  it("has NO field named `version`", () => {
+    // The app's invalidateResource probes cached payloads for that name
+    // structurally and SKIPS the invalidation when the cached value is at least
+    // as new. A field of that name here would wedge the feed badge with no
+    // error anywhere. Same trap `action-items/__tests__` guards.
+    expect(Object.keys(FeedListResponseSchema.shape)).not.toContain("version");
+  });
+
+  it("rejects a negative unread count", () => {
+    expect(
+      FeedListResponseSchema.safeParse({ ...base, unreadCount: -1 }).success,
+    ).toBe(false);
+  });
+});

package/src/user-notifications/index.ts

@@ -0,0 +1,25 @@
+/**
+ * user-notifications/ — the durable in-app inbox, and the merged feed that
+ * renders it alongside action items.
+ *
+ * See ./README.md for the domain, and ADR-CONT-108 for why this is a third
+ * vocabulary rather than a bend in either of the two beside it.
+ */
+
+export { USER_NOTIFICATION_KINDS } from "./kinds";
+export type { UserNotificationKind } from "./kinds";
+
+export {
+  FeedItemSchema,
+  FeedListResponseSchema,
+  FeedMarkReadRequestSchema,
+  UserNotificationKindSchema,
+  UserNotificationSchema,
+} from "./schemas";
+
+export type {
+  FeedItem,
+  FeedListResponse,
+  FeedMarkReadRequest,
+  UserNotification,
+} from "./schemas";

package/src/user-notifications/kinds.ts

@@ -0,0 +1,69 @@
+/**
+ * What kinds of durable in-app notification exist.
+ *
+ * A user notification is an INFORMATIONAL row addressed to one user: something
+ * that happened which they should know about and cannot act on. It is stored,
+ * it has read state, and it survives the user being offline.
+ *
+ * WHY THIS IS A THIRD VOCABULARY, alongside `NotificationKind` and
+ * `ActionItemKind` (ADR-CONT-104 forbids collapsing those two; this adds a
+ * third rather than bending either):
+ *
+ * - `NotificationKind` names a message that LEAVES THE BUILDING — an email or a
+ *   Slack post, composed by a render pipeline into prose carrying a brand and a
+ *   year, delivered once to an address. Its lifecycle ends at send.
+ * - `ActionItemKind` names STANDING STATE — a decision you owe, re-derived from
+ *   its domain's pending rows on every read, which stops existing the moment
+ *   anyone resolves it. It is never stored and has no read state, because
+ *   "resolved" is the only clearing mechanism it needs.
+ * - A user notification is neither. It is a FACT about the past, addressed to
+ *   one person, which they can only look at. `action-items/kinds.ts` already
+ *   named this gap: "a kind whose item cannot be acted on is not an action item
+ *   — that is the informational feed, which this layer does not model (yet)."
+ *   This is that layer.
+ *
+ * The three are not in bijection and never will be. `auth.otp` is a
+ * notification and can be neither of the others. `execution.confirmation_pending`
+ * is an action item with no notification. `companyMd.access_request_approved` is
+ * all three shapes' subject matter and gets a member in each, because the email,
+ * the (now absent) pending decision, and the durable "you were granted access"
+ * row are three different things with three different lifecycles.
+ *
+ * INVARIANTS:
+ * - `{domain}.{type}` dot notation, matching both sibling unions.
+ * - These strings go on the wire AND into a database column. Renaming one is a
+ *   migration, not a tidy-up.
+ * - A kind earns membership by being something a user should be able to come
+ *   back to. If it is only worth seeing while connected, it is a transient
+ *   frame on the user-event stream, not a row here.
+ * - A kind's row stores IDENTIFIERS ONLY (see `./schemas`). Copy lives in the
+ *   producing domain's renderer and is resolved at read time.
+ */
+
+// =============================================================================
+// UserNotificationKind Union
+// =============================================================================
+
+/**
+ * New kinds MUST be added to:
+ * 1. This union
+ * 2. A `NotificationRenderer` in the PRODUCING domain, which applies that
+ *    domain's own authority gate in bulk and returns a tombstone when the
+ *    reader may no longer see the referenced entity
+ *
+ * The three members below are the informational half of the company.md
+ * request-access lifecycle. Note what is NOT here:
+ * `companyMd.access_request_pending` is an ACTION ITEM — the owner can resolve
+ * it, so it is standing state, and modelling it here as well would give one
+ * fact two lifecycles that could disagree.
+ */
+export const USER_NOTIFICATION_KINDS = [
+  /** Someone asked for access to a doc you own. Informational twin of the action item. */
+  "companyMd.access_requested",
+  /** Your request was approved — you now have access. */
+  "companyMd.access_request_approved",
+  /** Your request was declined. */
+  "companyMd.access_request_denied",
+] as const;
+
+export type UserNotificationKind = (typeof USER_NOTIFICATION_KINDS)[number];

package/src/user-notifications/schemas.ts

@@ -0,0 +1,133 @@
+/**
+ * The published shapes of the durable notification inbox and the merged feed
+ * that renders it (`GET /api/me/feed`).
+ *
+ * Zod-canonical: schema is the source of truth, the type is inferred.
+ */
+import { z } from "zod";
+import { ActionItemSchema, ActionItemTargetSchema } from "../action-items";
+import { USER_NOTIFICATION_KINDS } from "./kinds";
+
+/** Zod mirror of the vocabulary. `./kinds` owns the list; this never restates it. */
+export const UserNotificationKindSchema = z.enum(USER_NOTIFICATION_KINDS);
+
+/**
+ * One informational row, AS RENDERED — never as stored.
+ *
+ * The stored row holds identifiers only (`kind` + a `ref` of ids). Everything
+ * below that reads like prose — `title`, `detail`, `contextLabel`, `href` — is
+ * produced at READ TIME by the producing domain's renderer, under the reader's
+ * CURRENT authority. Three problems dissolve at once:
+ *
+ * - **Copy evolution.** There is no frozen prose in the database to decode, so
+ *   changing wording is a renderer change, not a migration.
+ * - **Authorization drift.** A user who lost access to a document after being
+ *   notified about it must not keep reading its title out of an old row. The
+ *   renderer re-checks and returns a tombstone instead.
+ * - **Deletion.** A notification about a deleted doc renders as a tombstone
+ *   rather than dangling.
+ *
+ * The invariant that makes this safe is on the storage side and is worth
+ * stating here too, because this is where someone would be tempted to break it:
+ * **a stored notification row never contains protected content**, so a stale row
+ * cannot leak one.
+ *
+ * Deliberately shaped PARALLEL to `ActionItemSchema` — same field names, same
+ * meanings — so the merged feed is a union over two near-identical rows and the
+ * existing roll-up helpers keep working unchanged.
+ */
+export const UserNotificationSchema = z.object({
+  /** The stored row's id. Unlike an action item's, this IS a row id. */
+  id: z.string(),
+  kind: UserNotificationKindSchema,
+  target: ActionItemTargetSchema,
+  /** ltree anchor for subtree roll-up; `null` = org-wide. */
+  unitPath: z.string().nullable(),
+  /** One line naming what happened, e.g. "Dev Patel approved your request". */
+  title: z.string(),
+  /** Optional second line — the decider's note, a reason. */
+  detail: z.string().nullable(),
+  /** The thing it is about, as the user names it, e.g. "Sales.md". */
+  contextLabel: z.string(),
+  /**
+   * Where to go to SEE it — a RELATIVE app path.
+   *
+   * `null` when the reader can no longer reach the referent (access revoked,
+   * doc deleted, or a `ref` this client's version cannot decode). A tombstoned
+   * row still renders, because "you were granted access to something you can no
+   * longer see" is itself true and useful; it simply does not link anywhere.
+   */
+  href: z.string().nullable(),
+  createdAt: z.string(),
+  /** `null` while unread. The only mutable field on the row. */
+  readAt: z.string().nullable(),
+});
+export type UserNotification = z.infer<typeof UserNotificationSchema>;
+
+// =============================================================================
+// The merged feed
+// =============================================================================
+
+/**
+ * One row of `/me/work`'s top section, discriminated by what it DEMANDS.
+ *
+ * `actionable` rows are derived standing state you can resolve; `informational`
+ * rows are stored facts you can only read. They are merged for PRESENTATION —
+ * one list under one heading — and nowhere else: the two producing vocabularies
+ * stay separate (ADR-CONT-104), and the `action-items` domain still owns no
+ * tables.
+ *
+ * Discriminating on `row` rather than sniffing for `readAt` keeps the client
+ * from having to know which fields imply which lifecycle.
+ */
+export const FeedItemSchema = z.discriminatedUnion("row", [
+  z.object({ row: z.literal("actionable"), item: ActionItemSchema }),
+  z.object({
+    row: z.literal("informational"),
+    notification: UserNotificationSchema,
+  }),
+]);
+export type FeedItem = z.infer<typeof FeedItemSchema>;
+
+/**
+ * `GET /api/me/feed`.
+ *
+ * ORDERING IS INTENTIONALLY GROUPED, NOT CHRONOLOGICALLY INTERLEAVED: every
+ * `actionable` row first, then `informational` rows newest-first. "Merged feed"
+ * names one visual surface, not one timeline. Grouping is what keeps "what do I
+ * owe?" answerable at a glance instead of scattered between announcements — and
+ * it is what makes the pagination rule below coherent.
+ *
+ * ONLY NOTIFICATIONS PAGINATE. Action items are already bounded by
+ * `ACTION_ITEM_LIMIT` and are standing state rather than a timeline, so page 1
+ * carries all of them plus the first page of notifications, and every
+ * subsequent page is notifications only. Paginating two independent sources
+ * against one cursor is where merged feeds go wrong.
+ */
+export const FeedListResponseSchema = z.object({
+  items: z.array(FeedItemSchema),
+  /**
+   * Opaque cursor for the NEXT page of informational rows; `null` at the end.
+   *
+   * Encodes `(createdAt, id)` — `id` breaks ties so two rows written in the same
+   * transaction cannot straddle a page boundary and be served twice or skipped.
+   */
+  nextCursor: z.string().nullable(),
+  /**
+   * Total unread across ALL retained notifications — NOT within the returned
+   * window.
+   *
+   * A windowed count would silently under-report the moment the inbox grew past
+   * one page, and this number drives a badge whose entire job is to be trusted.
+   */
+  unreadCount: z.number().int().nonnegative(),
+  /** True when the ACTIONABLE half hit its cap; notifications say so via `nextCursor`. */
+  truncated: z.boolean(),
+});
+export type FeedListResponse = z.infer<typeof FeedListResponseSchema>;
+
+/** `POST /api/me/feed/read` — mark specific informational rows read. */
+export const FeedMarkReadRequestSchema = z.object({
+  notificationIds: z.array(z.string()).min(1).max(200),
+});
+export type FeedMarkReadRequest = z.infer<typeof FeedMarkReadRequestSchema>;