@company-semantics/contracts 82.0.0 → 83.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@company-semantics/contracts",
-  "version": "82.0.0",
+  "version": "83.0.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 = '2e37dedd5ad7' as const;
-export const SPEC_HASH_FULL = '2e37dedd5ad79e5b8ea6f6b470525a074c62c4a1bdf642b4792db0f893af887f' as const;
+export const SPEC_HASH = '9286d0cf0c7c' as const;
+export const SPEC_HASH_FULL = '9286d0cf0c7c1457a11e830402e9e860ee80e5b0b263b79d4ec15308d7ecb271' as const;

package/src/api/generated.ts

@@ -7629,9 +7629,13 @@ export interface components {
                     href: string | null;
                     createdAt: string;
                     readAt: string | null;
+                    activityAt: string;
+                    occurrenceCount: number;
+                    resolvedAt: string | null;
                 };
             })[];
             nextCursor: string | null;
+            viewCount: number;
             unreadCount: number;
             truncated: boolean;
         };

package/src/index.ts

@@ -327,7 +327,8 @@ export type {
   UserSseEvent,
 } from "./user-events/index";
 
-// Durable in-app inbox + the merged feed that renders it (ADR-CONT-108). The
+// Durable in-app inbox + the merged feed that renders it
+// (user-notification-inbox-and-merged-feed). 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
@@ -352,6 +353,55 @@ export type {
   UserNotificationKind,
 } from "./user-notifications/index";
 
+// Each inbox kind's declared lifecycle — condition, supersession, resolution,
+// retention (notification-lifecycle-is-declared-per-kind) — and the one
+// function that turns a kind + domain ref into its condition/supersession keys.
+export {
+  conditionKeyOf,
+  NOTIFICATION_ATTENTION_ON_SUPERSEDE,
+  NOTIFICATION_LIFECYCLE,
+  NOTIFICATION_RESOLUTION_AUDIENCES,
+  NOTIFICATION_RETENTION_CLASSES,
+  NotificationConditionKeyError,
+  notificationKeysOf,
+} from "./user-notifications/index";
+
+export type {
+  NotificationAttentionOnSupersede,
+  NotificationCondition,
+  NotificationKeys,
+  NotificationLifecycle,
+  NotificationResolution,
+  NotificationResolutionAudience,
+  NotificationRetention,
+} from "./user-notifications/index";
+
+// The feed's views, selectors (explicit ids, or a view as of `asOf`) and verb
+// wire — read / unread / delete / restore — for the caller's inbox rows.
+export {
+  FEED_SELECTOR_MAX_IDS,
+  FEED_VIEWS,
+  FeedDeleteRequestSchema,
+  FeedDeleteResponseSchema,
+  FeedMarkUnreadRequestSchema,
+  FeedMutationResponseSchema,
+  FeedRestoreRequestSchema,
+  FeedRestoreResponseSchema,
+  FeedSelectorSchema,
+  FeedViewSchema,
+} from "./user-notifications/index";
+
+export type {
+  FeedDeleteRequest,
+  FeedDeleteResponse,
+  FeedMarkUnreadRequest,
+  FeedMutationResponse,
+  FeedRestoreRequest,
+  FeedRestoreResponse,
+  FeedSelector,
+  FeedView,
+} from "./user-notifications/index";
+
 // Proactive delivery — how the system speaks first (ADR-CONTRACTS-142). A
 // COMPOSER above the three notification vocabularies, not a fourth peer: the
 // presentation class is a TOTAL FUNCTION from class to surfaces

package/src/user-notifications/README.md

@@ -21,8 +21,8 @@ that renders them alongside action items at the top of `/me/work`.
   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.
+  first, then informational rows unread-and-unresolved first, then `activityAt`
+  DESC, `id` DESC. "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
@@ -30,9 +30,9 @@ that renders them alongside action items at the top of `/me/work`.
 - **`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.
+- **The cursor is opaque and encodes `(unread, activityAt, id)`**, mirroring the
+  ordering. The id breaks ties so two rows with the same activity cannot
+  straddle a page boundary and be served twice or skipped.
 - **A row can be BORN READ.** Every proactive kind writes a durable row here
   as its paper trail, but only the class whose badge carrier is `inbox` writes
   it unread; `proactive.org_became_shared` is an `announcement`, so the banner
@@ -83,15 +83,102 @@ that renders them alongside action items at the top of `/me/work`.
   anywhere, and the proactive `unread` flag on a chat summary stays a one-time
   arrival badge that ordinary conversation never re-lights.
 
+## Lifecycle
+
+A row is the **current attention item for one condition**, not an event record
+(control ADR `notification-inbox-is-an-attention-surface`; contracts ADR
+`notification-lifecycle-is-declared-per-kind`). Every kind declares its
+lifecycle in `NOTIFICATION_LIFECYCLE`, typed
+`Readonly<Record<UserNotificationKind, NotificationLifecycle>>`, so a kind
+without one — or an entry for a kind that does not exist — fails to compile.
+Each entry declares four things:
+
+- **Condition — what the row is about.** `none` (an independent delivery with no
+  identity), `{ scope: 'kind' }` (one condition per kind), or
+  `{ scope: 'fields', fields }` (named fields of the producing domain's ref). The
+  condition is the identity RESOLUTION addresses.
+- **Supersession — a property of the condition, never a second identity.**
+  `supersedes: true` means a repeat occurrence updates the active row for that
+  condition instead of appending another; `supersedes: false` means each
+  occurrence is its own row (access requests: every request stands on its own).
+  A `none` condition cannot supersede.
+- **Renew vs preserve.** A superseding kind declares `attentionOnSupersede`.
+  `renew` restores the kind's normal initial attention state — unread, or read
+  when its proactive class is born read (`bornRead` decides, not this registry);
+  the repeat is news again. `preserve` keeps the row's current read state; the
+  repeat is a quiet update to a standing condition. Only a superseding kind may
+  declare it.
+- **Resolution, with an explicit audience.** `never`, or
+  `{ mode: 'source', audience }`: the producing DOMAIN resolves the condition,
+  for `all-recipients` or only the `recipient`. Source resolution needs a
+  condition to address, so `none` + `source` does not compile.
+- **Retention class.** `standard` or `persistent`. Every kind is `standard`
+  today; `persistent` must be declared, never accidental. The class is all
+  contracts carries — the retention DAY values live in the backend.
+
+The union makes the three illegal combinations unrepresentable (source
+resolution without a condition, `attentionOnSupersede` without
+`supersedes: true`, supersession of `none`); `__tests__/compile-fixtures.ts`
+pins each with `@ts-expect-error`.
+
+**One key builder.** `conditionKeyOf(kind, domainRef)` is the only way a
+condition key is spelled: the kind itself for `scope: 'kind'`; for
+`scope: 'fields'`, the kind then each named field sorted by name as
+`name=encodeURIComponent(value)`, joined by `|`; `null` for `none`. Values are
+never trimmed or lowercased, and a named field that is absent, not a string, or
+empty throws `NotificationConditionKeyError`. `notificationKeysOf` returns
+`{ conditionKey, supersessionKey }`, where the supersession key is the condition
+key of a superseding kind and `null` otherwise — not a second identity.
+
+**The row carries its lifecycle.** `activityAt` is the time of the latest
+occurrence (the ordering and retention clock), `occurrenceCount` how many
+occurrences the row has absorbed by supersession, and `resolvedAt` when the
+domain resolved the condition (`null` while it stands). All three are required.
+
+**The verbs take a selector** (`feed-lifecycle.ts`): explicit `ids` (at most
+`FEED_SELECTOR_MAX_IDS`), or a `view` (`all` | `unread`) AS OF `asOf`, so rows
+that arrive after the person acted are never swept in. `viewCount` on the feed
+response counts the notification rows in the requested view. A delete returns
+an opaque `restoreKey`; a restore reports `{ restored, superseded }`, where
+`superseded` counts rows left deleted because a newer active row already
+represents their condition.
+
+**There is no Archive.** No archived state, no archived view, no archive verb.
+A row is current, resolved, or deleted — and a deleted row is never served.
+
+The per-kind table and the retention and Undo values live in
+company-semantics-control docs/notification-inbox.md; the registry mirrors that
+table entry for entry.
+
 ## 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`                                       |
+| 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, viewCount, unreadCount, truncated |
+| `FeedMarkReadRequestSchema`           | `POST /api/me/feed/read` — `{ selector }`                                 |
+| `FEED_VIEWS` / `FeedViewSchema`       | `all` \| `unread`                                                         |
+| `FeedSelectorSchema`                  | `{ kind: 'ids', notificationIds }` \| `{ kind: 'view', view, asOf }`      |
+| `FEED_SELECTOR_MAX_IDS`               | The most ids one explicit selection may name (200)                        |
+| `FeedMarkUnreadRequestSchema`         | Mark unread — `{ selector }`                                              |
+| `FeedDeleteRequestSchema`             | Delete — `{ selector }`                                                   |
+| `FeedRestoreRequestSchema`            | Undo a delete — `{ restoreKey }`                                          |
+| `FeedMutationResponseSchema`          | `{ affected }`                                                            |
+| `FeedDeleteResponseSchema`            | `{ affected, restoreKey }` — the key is opaque                            |
+| `FeedRestoreResponseSchema`           | `{ restored, superseded }`                                                |
+| `NOTIFICATION_LIFECYCLE`              | Every kind's declared lifecycle                                           |
+| `NotificationLifecycle`               | The lifecycle union (condition, supersession, resolution, …)              |
+| `NotificationCondition`               | `{ scope: 'kind' }` \| `{ scope: 'fields', fields }`                      |
+| `NotificationResolution`              | `never` \| `{ mode: 'source', audience }`                                 |
+| `NOTIFICATION_ATTENTION_ON_SUPERSEDE` | `renew` \| `preserve`                                                     |
+| `NOTIFICATION_RESOLUTION_AUDIENCES`   | `all-recipients` \| `recipient`                                           |
+| `NOTIFICATION_RETENTION_CLASSES`      | `standard` \| `persistent`                                                |
+| `conditionKeyOf`                      | The one condition-key builder (kind + domain ref → key)                   |
+| `notificationKeysOf`                  | `{ conditionKey, supersessionKey }` for a kind + domain ref               |
+| `NotificationKeys`                    | The pair `notificationKeysOf` returns                                     |
+| `NotificationConditionKeyError`       | A named condition field is absent, not a string, or empty                 |
 
 ## Dependencies
 

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

@@ -23,6 +23,25 @@ Locks the claims `../README.md` and ADR-CONT-108 make that the compiler cannot.
      trap `action-items/__tests__` guards, and it would wedge the feed badge
      with no error anywhere.
 
+- `lifecycle.test.ts` — the per-kind lifecycle registry: every kind in the
+  real `USER_NOTIFICATION_KINDS` declares one, a source-resolved kind always has
+  a condition, access requests never supersede, and no kind is `persistent`
+  yet.
+- `condition-keys.test.ts` — the one key builder's exact format: fields sorted
+  by name and URI-encoded (never trimmed or lowercased), a missing or empty
+  field throws, an independent kind has no key, a non-superseding kind has no
+  supersession key, and ref fields the lifecycle does not name never change it.
+- `feed-lifecycle.test.ts` — the feed wire: an `ids` selector names 1..200
+  ids, a `view` selector needs its `asOf` snapshot, there is no `archived`
+  view, mark-read takes a selector, a delete returns a restore key and a
+  restore counts superseded rows, and the row's `activityAt`,
+  `occurrenceCount` and `resolvedAt` (and the response's `viewCount`) are
+  required.
+- `compile-fixtures.ts` — not a test file, so `tsc -b` compiles it: the three
+  illegal lifecycles, each pinned with `@ts-expect-error`. A directive written
+  in a `*.test.ts` is never typechecked; one here fails `pnpm typecheck` with
+  TS2578 the moment the union loosens.
+
 ## Invariants
 
 - These assert VOCABULARY and SHAPE, never behavior. Anything needing a

package/src/user-notifications/__tests__/compile-fixtures.ts

@@ -0,0 +1,54 @@
+/**
+ * Negative typecheck fixtures — the illegal lifecycles the per-kind registry
+ * (notification-lifecycle-is-declared-per-kind) refuses, each pinned with
+ * `@ts-expect-error`.
+ *
+ * The directive is the proof. If the `NotificationLifecycle` union ever loosens
+ * so one of these becomes representable, the directive goes UNUSED and
+ * `pnpm typecheck` fails with TS2578.
+ *
+ * WHY A COMPILED MODULE. `src/tsconfig.json` excludes every `*.test.ts` file
+ * and vitest does not typecheck, so a directive inside `lifecycle.test.ts` is
+ * never checked. This file is not a `*.test.ts`, so `tsc -b` compiles it (the
+ * same placement as `../../proactive/__tests__/compile-fixtures.ts`), and
+ * `lifecycle.test.ts` imports it.
+ *
+ * Each directive sits IMMEDIATELY above the line the compiler reports on.
+ */
+
+import type { NotificationLifecycle } from "../lifecycle";
+
+/** CLAIM 1 — source resolution needs a condition identity to resolve. */
+const sourceWithoutCondition: NotificationLifecycle = {
+  condition: "none",
+  // @ts-expect-error a condition-less kind resolves `never`
+  resolution: { mode: "source", audience: "recipient" },
+  retention: "standard",
+};
+
+/** CLAIM 2 — attention on supersede means nothing without supersession. */
+const attentionWithoutSupersession: NotificationLifecycle = {
+  condition: { scope: "kind" },
+  supersedes: false,
+  // @ts-expect-error `attentionOnSupersede` exists only when `supersedes: true`
+  attentionOnSupersede: "renew",
+  resolution: "never",
+  retention: "standard",
+};
+
+/** CLAIM 3 — a condition-less kind has nothing to supersede by. */
+const supersedingWithoutCondition: NotificationLifecycle = {
+  condition: "none",
+  // @ts-expect-error a `none` condition carries no `supersedes`
+  supersedes: true,
+  attentionOnSupersede: "renew",
+  resolution: "never",
+  retention: "standard",
+};
+
+/** The fixtures, exported so the directives are not dead code. */
+export const ILLEGAL_LIFECYCLES = [
+  sourceWithoutCondition,
+  attentionWithoutSupersession,
+  supersedingWithoutCondition,
+] as const;

package/src/user-notifications/__tests__/condition-keys.test.ts

@@ -0,0 +1,126 @@
+/**
+ * The one condition-key builder (notification-lifecycle-is-declared-per-kind).
+ *
+ * INVARIANTS TESTED:
+ * - A `fields` key is the kind, then each named field sorted by name as
+ *   name=encodeURIComponent(value), joined by `|` — whatever order the ref
+ *   lists them in.
+ * - A named field that is absent, not a string, or empty throws
+ *   NotificationConditionKeyError naming the kind and the field.
+ * - An independent kind has neither key; a non-superseding kind has a
+ *   condition key but no supersession key; a `kind` key is the kind itself.
+ * - Values are never trimmed or lowercased, and fields the lifecycle does not
+ *   name never change the key.
+ * - Every export is reachable from both the domain barrel and the root barrel.
+ */
+import { describe, expect, it } from "vitest";
+import * as root from "../../index";
+import * as domain from "../index";
+import {
+  conditionKeyOf,
+  NotificationConditionKeyError,
+  notificationKeysOf,
+} from "../condition-keys";
+
+describe("conditionKeyOf / notificationKeysOf", () => {
+  it("condition key orders fields by name", () => {
+    const a = conditionKeyOf("comment.reply", {
+      subjectType: "company_md",
+      subjectId: "doc-1",
+    });
+    const b = conditionKeyOf("comment.reply", {
+      subjectId: "doc-1",
+      subjectType: "company_md",
+    });
+    expect(a).toBe("comment.reply|subjectId=doc-1|subjectType=company_md");
+    expect(b).toBe(a);
+  });
+
+  it("condition key refuses a missing field", () => {
+    const build = () =>
+      conditionKeyOf("companyMd.access_requested", { docId: "doc-1" });
+    expect(build).toThrow(NotificationConditionKeyError);
+    try {
+      build();
+    } catch (error) {
+      expect(error).toMatchObject({
+        name: "NotificationConditionKeyError",
+        kind: "companyMd.access_requested",
+        field: "requestId",
+      });
+    }
+  });
+
+  it("condition key refuses an empty or non-string field", () => {
+    for (const requestId of ["", 42, null]) {
+      expect(() =>
+        conditionKeyOf("companyMd.access_requested", { requestId }),
+      ).toThrow(NotificationConditionKeyError);
+    }
+  });
+
+  it("an independent kind has no condition key", () => {
+    expect(
+      notificationKeysOf("companyMd.access_request_approved", {
+        requestId: "req-1",
+      }),
+    ).toEqual({ conditionKey: null, supersessionKey: null });
+  });
+
+  it("a non-superseding kind has a condition key but no supersession key", () => {
+    expect(
+      notificationKeysOf("companyMd.access_requested", { requestId: "req-1" }),
+    ).toEqual({
+      conditionKey: "companyMd.access_requested|requestId=req-1",
+      supersessionKey: null,
+    });
+  });
+
+  it("a superseding kind's supersession key is its condition key", () => {
+    const keys = notificationKeysOf("chat.mention", { chatId: "chat-1" });
+    expect(keys.conditionKey).toBe("chat.mention|chatId=chat-1");
+    expect(keys.supersessionKey).toBe(keys.conditionKey);
+  });
+
+  it("a per-kind condition key is the kind itself", () => {
+    expect(
+      notificationKeysOf("proactive.brief_morning", {
+        orgLocalDate: "2026-09-25",
+      }),
+    ).toEqual({
+      conditionKey: "proactive.brief_morning",
+      supersessionKey: "proactive.brief_morning",
+    });
+  });
+
+  it("extra ref fields never change the key", () => {
+    const candidates = conditionKeyOf("proactive.source_sync_review_ready", {
+      checkpoint: "candidates",
+      runId: "run-1",
+    });
+    const again = conditionKeyOf("proactive.source_sync_review_ready", {
+      checkpoint: "candidates",
+      batchId: "batch-9",
+    });
+    expect(candidates).toBe(
+      "proactive.source_sync_review_ready|checkpoint=candidates",
+    );
+    expect(again).toBe(candidates);
+  });
+
+  it("values are URI-encoded, never trimmed or lowercased", () => {
+    expect(conditionKeyOf("chat.mention", { chatId: " Chat|A=B " })).toBe(
+      `chat.mention|chatId=${encodeURIComponent(" Chat|A=B ")}`,
+    );
+  });
+
+  it("every condition-key export is reachable from both barrels", () => {
+    for (const barrel of [root, domain]) {
+      expect(barrel.conditionKeyOf).toBe(conditionKeyOf);
+      expect(barrel.notificationKeysOf).toBe(notificationKeysOf);
+      expect(barrel.NotificationConditionKeyError).toBe(
+        NotificationConditionKeyError,
+      );
+    }
+  });
+});

package/src/user-notifications/__tests__/feed-lifecycle.test.ts

@@ -0,0 +1,260 @@
+/**
+ * The feed's views, selectors and verb wire, and the inbox row's lifecycle
+ * fields (notification-lifecycle-is-declared-per-kind).
+ *
+ * INVARIANTS TESTED:
+ * - An `ids` selector names 1..FEED_SELECTOR_MAX_IDS ids.
+ * - A `view` selector carries an `asOf` snapshot instant; without one it fails.
+ * - The views are exactly `all` and `unread` — there is no `archived` view.
+ * - A delete returns an opaque restore key; a restore reports the rows it
+ *   restored and the rows a newer active row had superseded.
+ * - `activityAt`, `occurrenceCount` and `resolvedAt` are REQUIRED on a row, and
+ *   `viewCount` on the feed response.
+ * - Mark-read takes a selector, never a bare id list.
+ * - Every export is reachable from both the domain barrel and the root barrel.
+ */
+import { describe, expect, it } from "vitest";
+import * as root from "../../index";
+import * as domain from "../index";
+import {
+  FEED_SELECTOR_MAX_IDS,
+  FEED_VIEWS,
+  FeedDeleteRequestSchema,
+  FeedDeleteResponseSchema,
+  FeedMarkUnreadRequestSchema,
+  FeedMutationResponseSchema,
+  FeedRestoreRequestSchema,
+  FeedRestoreResponseSchema,
+  FeedSelectorSchema,
+  FeedViewSchema,
+} from "../feed-lifecycle";
+import {
+  FeedListResponseSchema,
+  FeedMarkReadRequestSchema,
+  UserNotificationSchema,
+} from "../schemas";
+
+const AS_OF = "2026-07-30T12:00:00.000Z";
+
+function ids(count: number): string[] {
+  return Array.from({ length: count }, (_, i) => `n-${i}`);
+}
+
+function makeNotification(over: Record<string, unknown> = {}) {
+  return {
+    id: "n-1",
+    kind: "proactive.brief_morning",
+    target: { type: "org", id: "22222222-2222-4222-8222-222222222222" },
+    unitPath: null,
+    title: "Your morning brief is ready",
+    detail: null,
+    contextLabel: "Morning brief",
+    provider: null,
+    href: "/brief",
+    createdAt: "2026-07-28T08:00:00.000Z",
+    readAt: null,
+    activityAt: "2026-07-30T08:00:00.000Z",
+    occurrenceCount: 3,
+    resolvedAt: null,
+    ...over,
+  };
+}
+
+describe("FeedSelector", () => {
+  it("accepts exactly the maximum number of ids", () => {
+    expect(FEED_SELECTOR_MAX_IDS).toBe(200);
+    expect(
+      FeedSelectorSchema.safeParse({
+        kind: "ids",
+        notificationIds: ids(FEED_SELECTOR_MAX_IDS),
+      }).success,
+    ).toBe(true);
+  });
+
+  it("an ids selector refuses more than 200 ids", () => {
+    expect(
+      FeedSelectorSchema.safeParse({ kind: "ids", notificationIds: ids(201) })
+        .success,
+    ).toBe(false);
+  });
+
+  it("an ids selector refuses an empty selection", () => {
+    expect(
+      FeedSelectorSchema.safeParse({ kind: "ids", notificationIds: [] })
+        .success,
+    ).toBe(false);
+  });
+
+  it("a view selector requires asOf", () => {
+    // Without the snapshot, "everything in this view" would sweep in rows that
+    // arrived after the person acted.
+    expect(
+      FeedSelectorSchema.safeParse({ kind: "view", view: "unread" }).success,
+    ).toBe(false);
+    expect(
+      FeedSelectorSchema.safeParse({ kind: "view", view: "unread", asOf: "" })
+        .success,
+    ).toBe(false);
+    expect(
+      FeedSelectorSchema.safeParse({
+        kind: "view",
+        view: "unread",
+        asOf: AS_OF,
+      }).success,
+    ).toBe(true);
+  });
+
+  it("an unknown view is rejected", () => {
+    // There is no Archive — and so no archived view.
+    expect(FEED_VIEWS).toEqual(["all", "unread"]);
+    expect(FeedViewSchema.safeParse("archived").success).toBe(false);
+    expect(
+      FeedSelectorSchema.safeParse({
+        kind: "view",
+        view: "archived",
+        asOf: AS_OF,
+      }).success,
+    ).toBe(false);
+  });
+
+  it("refuses a selector without its discriminant", () => {
+    expect(
+      FeedSelectorSchema.safeParse({ notificationIds: ids(1) }).success,
+    ).toBe(false);
+  });
+});
+
+describe("the verbs take a selector", () => {
+  const selector = { kind: "ids", notificationIds: ids(2) };
+
+  it("mark read, mark unread and delete all accept { selector }", () => {
+    for (const schema of [
+      FeedMarkReadRequestSchema,
+      FeedMarkUnreadRequestSchema,
+      FeedDeleteRequestSchema,
+    ]) {
+      expect(schema.safeParse({ selector }).success).toBe(true);
+    }
+  });
+
+  it("mark read no longer accepts a bare id list", () => {
+    expect(
+      FeedMarkReadRequestSchema.safeParse({ notificationIds: ids(2) }).success,
+    ).toBe(false);
+  });
+
+  it("a restore request needs a non-empty restore key", () => {
+    expect(
+      FeedRestoreRequestSchema.safeParse({ restoreKey: "op-1" }).success,
+    ).toBe(true);
+    expect(FeedRestoreRequestSchema.safeParse({ restoreKey: "" }).success).toBe(
+      false,
+    );
+  });
+});
+
+describe("the verb responses", () => {
+  it("a mutation reports a non-negative affected count", () => {
+    expect(FeedMutationResponseSchema.safeParse({ affected: 0 }).success).toBe(
+      true,
+    );
+    expect(FeedMutationResponseSchema.safeParse({ affected: -1 }).success).toBe(
+      false,
+    );
+  });
+
+  it("a delete returns an opaque restore key", () => {
+    expect(
+      FeedDeleteResponseSchema.safeParse({ affected: 2, restoreKey: "op-1" })
+        .success,
+    ).toBe(true);
+    expect(FeedDeleteResponseSchema.safeParse({ affected: 2 }).success).toBe(
+      false,
+    );
+  });
+
+  it("a restore response counts superseded rows", () => {
+    const parsed = FeedRestoreResponseSchema.parse({
+      restored: 1,
+      superseded: 1,
+    });
+    expect(parsed.superseded).toBe(1);
+    expect(FeedRestoreResponseSchema.safeParse({ restored: 1 }).success).toBe(
+      false,
+    );
+  });
+});
+
+describe("the inbox row's lifecycle fields", () => {
+  it("parses a superseded, unresolved row", () => {
+    expect(UserNotificationSchema.safeParse(makeNotification()).success).toBe(
+      true,
+    );
+  });
+
+  it("parses a resolved row", () => {
+    expect(
+      UserNotificationSchema.safeParse(
+        makeNotification({ resolvedAt: "2026-07-30T09:00:00.000Z" }),
+      ).success,
+    ).toBe(true);
+  });
+
+  it("a notification without activityAt fails to parse", () => {
+    const { activityAt: _omitted, ...withoutActivity } = makeNotification();
+    expect(UserNotificationSchema.safeParse(withoutActivity).success).toBe(
+      false,
+    );
+  });
+
+  it("requires occurrenceCount, and refuses zero", () => {
+    const { occurrenceCount: _omitted, ...withoutCount } = makeNotification();
+    expect(UserNotificationSchema.safeParse(withoutCount).success).toBe(false);
+    expect(
+      UserNotificationSchema.safeParse(makeNotification({ occurrenceCount: 0 }))
+        .success,
+    ).toBe(false);
+  });
+
+  it("requires resolvedAt — null says 'standing', absence says nothing", () => {
+    const { resolvedAt: _omitted, ...withoutResolved } = makeNotification();
+    expect(UserNotificationSchema.safeParse(withoutResolved).success).toBe(
+      false,
+    );
+  });
+
+  it("the feed response requires viewCount", () => {
+    const base = {
+      items: [],
+      nextCursor: null,
+      unreadCount: 0,
+      truncated: false,
+    };
+    expect(FeedListResponseSchema.safeParse(base).success).toBe(false);
+    expect(
+      FeedListResponseSchema.safeParse({ ...base, viewCount: 0 }).success,
+    ).toBe(true);
+  });
+});
+
+describe("barrel reachability", () => {
+  const values = {
+    FEED_SELECTOR_MAX_IDS,
+    FEED_VIEWS,
+    FeedDeleteRequestSchema,
+    FeedDeleteResponseSchema,
+    FeedMarkUnreadRequestSchema,
+    FeedMutationResponseSchema,
+    FeedRestoreRequestSchema,
+    FeedRestoreResponseSchema,
+    FeedSelectorSchema,
+    FeedViewSchema,
+  };
+
+  it("every feed-lifecycle value is exported from both barrels", () => {
+    for (const [name, value] of Object.entries(values)) {
+      expect((domain as Record<string, unknown>)[name]).toBe(value);
+      expect((root as Record<string, unknown>)[name]).toBe(value);
+    }
+  });
+});

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

@@ -0,0 +1,114 @@
+/**
+ * Per-kind notification lifecycle (notification-lifecycle-is-declared-per-kind).
+ *
+ * INVARIANTS TESTED:
+ * - Every kind in USER_NOTIFICATION_KINDS declares exactly one lifecycle, and
+ *   the registry names no kind outside the union (the annotation proves both at
+ *   compile time; this proves it against the real runtime array).
+ * - A source-resolved kind always has a condition identity to resolve by.
+ * - Access requests are addressed per request and never supersede.
+ * - No kind is `persistent` yet — persistence is declared, never accidental.
+ * - The illegal lifecycles do not compile (./compile-fixtures.ts is the
+ *   checked proof; the directives below restate it where it is read).
+ * - Every export is reachable from both the domain barrel and the root barrel.
+ */
+import { describe, expect, it } from "vitest";
+import * as root from "../../index";
+import * as domain from "../index";
+import { USER_NOTIFICATION_KINDS } from "../kinds";
+import {
+  NOTIFICATION_ATTENTION_ON_SUPERSEDE,
+  NOTIFICATION_RESOLUTION_AUDIENCES,
+  NOTIFICATION_RETENTION_CLASSES,
+  type NotificationLifecycle,
+} from "../lifecycle";
+import { NOTIFICATION_LIFECYCLE } from "../lifecycle-registry";
+import { ILLEGAL_LIFECYCLES } from "./compile-fixtures";
+
+describe("NOTIFICATION_LIFECYCLE", () => {
+  it("every notification kind declares a lifecycle", () => {
+    for (const kind of USER_NOTIFICATION_KINDS) {
+      expect(NOTIFICATION_LIFECYCLE[kind], kind).toBeDefined();
+    }
+    expect(Object.keys(NOTIFICATION_LIFECYCLE).sort()).toEqual(
+      [...USER_NOTIFICATION_KINDS].sort(),
+    );
+  });
+
+  it("a source-resolved kind always has a condition identity", () => {
+    for (const [kind, lifecycle] of Object.entries(NOTIFICATION_LIFECYCLE)) {
+      if (lifecycle.resolution !== "never") {
+        expect(lifecycle.condition, kind).not.toBe("none");
+      }
+    }
+  });
+
+  it("access requests do not supersede one another", () => {
+    const lifecycle = NOTIFICATION_LIFECYCLE["companyMd.access_requested"];
+    expect(lifecycle.condition).toEqual({
+      scope: "fields",
+      fields: ["requestId"],
+    });
+    expect(lifecycle.condition !== "none" && lifecycle.supersedes).toBe(false);
+  });
+
+  it("no kind is persistent yet", () => {
+    for (const [kind, lifecycle] of Object.entries(NOTIFICATION_LIFECYCLE)) {
+      expect(lifecycle.retention, kind).toBe("standard");
+    }
+  });
+
+  it("the closed vocabularies are pinned member-for-member", () => {
+    expect(NOTIFICATION_ATTENTION_ON_SUPERSEDE).toEqual(["renew", "preserve"]);
+    expect(NOTIFICATION_RESOLUTION_AUDIENCES).toEqual([
+      "all-recipients",
+      "recipient",
+    ]);
+    expect(NOTIFICATION_RETENTION_CLASSES).toEqual(["standard", "persistent"]);
+  });
+
+  it("an illegal lifecycle does not compile", () => {
+    // Unchecked here (tsc excludes *.test.ts); ./compile-fixtures.ts holds the
+    // same three directives where `pnpm typecheck` enforces them.
+    const illegal: NotificationLifecycle[] = [
+      // @ts-expect-error — source resolution needs a condition
+      {
+        condition: "none",
+        resolution: { mode: "source", audience: "recipient" },
+        retention: "standard",
+      },
+      // @ts-expect-error — attention without supersession
+      {
+        condition: { scope: "kind" },
+        supersedes: false,
+        attentionOnSupersede: "renew",
+        resolution: "never",
+        retention: "standard",
+      },
+      // @ts-expect-error — a condition-less kind cannot supersede
+      {
+        condition: "none",
+        supersedes: true,
+        attentionOnSupersede: "renew",
+        resolution: "never",
+        retention: "standard",
+      },
+    ];
+    expect(illegal).toHaveLength(ILLEGAL_LIFECYCLES.length);
+  });
+
+  it("every lifecycle export is reachable from both barrels", () => {
+    for (const barrel of [root, domain]) {
+      expect(barrel.NOTIFICATION_LIFECYCLE).toBe(NOTIFICATION_LIFECYCLE);
+      expect(barrel.NOTIFICATION_ATTENTION_ON_SUPERSEDE).toBe(
+        NOTIFICATION_ATTENTION_ON_SUPERSEDE,
+      );
+      expect(barrel.NOTIFICATION_RESOLUTION_AUDIENCES).toBe(
+        NOTIFICATION_RESOLUTION_AUDIENCES,
+      );
+      expect(barrel.NOTIFICATION_RETENTION_CLASSES).toBe(
+        NOTIFICATION_RETENTION_CLASSES,
+      );
+    }
+  });
+});

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

@@ -1,5 +1,6 @@
 /**
- * The inbox vocabulary's invariants, as tests rather than prose (ADR-CONT-108).
+ * The inbox vocabulary's invariants, as tests rather than prose
+ * (user-notification-inbox-and-merged-feed).
  */
 import { describe, it, expect } from "vitest";
 import { USER_NOTIFICATION_KINDS } from "../kinds.js";
@@ -26,6 +27,9 @@ function makeNotification(over: Record<string, unknown> = {}) {
     href: "/@acme/md/doc-1",
     createdAt: "2026-07-30T12:00:00.000Z",
     readAt: null,
+    activityAt: "2026-07-30T12:00:00.000Z",
+    occurrenceCount: 1,
+    resolvedAt: null,
     ...over,
   };
 }
@@ -203,6 +207,7 @@ describe("FeedListResponse", () => {
   const base = {
     items: [],
     nextCursor: null,
+    viewCount: 0,
     unreadCount: 0,
     truncated: false,
   };

package/src/user-notifications/condition-keys.ts

@@ -0,0 +1,64 @@
+/**
+ * THE key builder. The backend stores exactly what this returns and never
+ * builds a key any other way — two spellings of one condition would be two
+ * conditions, and resolution would silently miss.
+ *
+ *   kind scope   → "proactive.brief_morning"
+ *   fields scope → "comment.reply|subjectId=doc-1|subjectType=company_md"
+ *                  (fields sorted by name; values encodeURIComponent'd, never
+ *                  trimmed or lowercased)
+ *   none         → null
+ *
+ * The supersession key is not a second identity: it is the condition key of a
+ * kind that supersedes, and null otherwise.
+ */
+import type { UserNotificationKind } from "./kinds";
+import { NOTIFICATION_LIFECYCLE } from "./lifecycle-registry";
+
+/** A condition field the kind's lifecycle names is absent, not a string, or empty. */
+// @vocabulary-exempt: Error subclass so callers can `instanceof` a malformed domain ref
+export class NotificationConditionKeyError extends Error {
+  constructor(
+    readonly kind: UserNotificationKind,
+    readonly field: string,
+  ) {
+    super(
+      `notification kind ${kind} needs a non-empty string "${field}" in its domain ref`,
+    );
+    this.name = "NotificationConditionKeyError";
+  }
+}
+
+export function conditionKeyOf(
+  kind: UserNotificationKind,
+  domainRef: Readonly<Record<string, unknown>>,
+): string | null {
+  const { condition } = NOTIFICATION_LIFECYCLE[kind];
+  if (condition === "none") return null;
+  if (condition.scope === "kind") return kind;
+  const parts = [...condition.fields].sort().map((field) => {
+    const value = domainRef[field];
+    if (typeof value !== "string" || value.length === 0) {
+      throw new NotificationConditionKeyError(kind, field);
+    }
+    return `${field}=${encodeURIComponent(value)}`;
+  });
+  return [kind, ...parts].join("|");
+}
+
+export type NotificationKeys = {
+  /** Resolution identity. Null only for an independent (`condition: "none"`) kind. */
+  readonly conditionKey: string | null;
+  /** Active-row uniqueness identity: the condition key of a superseding kind, else null. */
+  readonly supersessionKey: string | null;
+};
+
+export function notificationKeysOf(
+  kind: UserNotificationKind,
+  domainRef: Readonly<Record<string, unknown>>,
+): NotificationKeys {
+  const lifecycle = NOTIFICATION_LIFECYCLE[kind];
+  const conditionKey = conditionKeyOf(kind, domainRef);
+  const supersedes = lifecycle.condition !== "none" && lifecycle.supersedes;
+  return { conditionKey, supersessionKey: supersedes ? conditionKey : null };
+}

package/src/user-notifications/feed-lifecycle.ts

@@ -0,0 +1,76 @@
+/**
+ * The feed's views, selectors and verbs.
+ *
+ * A SELECTOR says which rows a verb touches. `ids` is what the person ticked;
+ * `view` is "everything in this view AS OF `asOf`" — rows that arrive after the
+ * person acted are never swept in (the snapshot rule). Verbs touch the caller's
+ * own notification rows only, never action items.
+ *
+ * There is no Archive: no archived view and no archive verb. A delete is undone
+ * by restoring with the opaque key it returned.
+ *
+ * Imports only `zod` — `./schemas` imports this module, never the reverse.
+ */
+import { z } from "zod";
+
+export const FEED_VIEWS = ["all", "unread"] as const;
+export const FeedViewSchema = z.enum(FEED_VIEWS);
+export type FeedView = z.infer<typeof FeedViewSchema>;
+
+/** The most ids one explicit selection may name. */
+export const FEED_SELECTOR_MAX_IDS = 200;
+
+export const FeedSelectorSchema = z.discriminatedUnion("kind", [
+  z.object({
+    kind: z.literal("ids"),
+    notificationIds: z.array(z.string()).min(1).max(FEED_SELECTOR_MAX_IDS),
+  }),
+  z.object({
+    kind: z.literal("view"),
+    view: FeedViewSchema,
+    /** The snapshot instant: only rows whose activity is at or before it are touched. */
+    asOf: z.string().datetime(),
+  }),
+]);
+export type FeedSelector = z.infer<typeof FeedSelectorSchema>;
+
+/** Mark the selected informational rows unread. */
+export const FeedMarkUnreadRequestSchema = z.object({
+  selector: FeedSelectorSchema,
+});
+export type FeedMarkUnreadRequest = z.infer<typeof FeedMarkUnreadRequestSchema>;
+
+/** Delete the selected informational rows; undone by a restore. */
+export const FeedDeleteRequestSchema = z.object({
+  selector: FeedSelectorSchema,
+});
+export type FeedDeleteRequest = z.infer<typeof FeedDeleteRequestSchema>;
+
+/** Undo. `restoreKey` is the opaque operation id a delete returned. */
+export const FeedRestoreRequestSchema = z.object({
+  restoreKey: z.string().min(1),
+});
+export type FeedRestoreRequest = z.infer<typeof FeedRestoreRequestSchema>;
+
+/** A read / unread mutation: how many rows it changed. */
+export const FeedMutationResponseSchema = z.object({
+  affected: z.number().int().nonnegative(),
+});
+export type FeedMutationResponse = z.infer<typeof FeedMutationResponseSchema>;
+
+/** A delete (or clear-resolved). `restoreKey` is opaque — never parse it. */
+export const FeedDeleteResponseSchema = z.object({
+  affected: z.number().int().nonnegative(),
+  restoreKey: z.string().min(1),
+});
+export type FeedDeleteResponse = z.infer<typeof FeedDeleteResponseSchema>;
+
+/**
+ * `superseded` counts rows left deleted because a newer active row already
+ * represents their condition — a restore never duplicates a condition.
+ */
+export const FeedRestoreResponseSchema = z.object({
+  restored: z.number().int().nonnegative(),
+  superseded: z.number().int().nonnegative(),
+});
+export type FeedRestoreResponse = z.infer<typeof FeedRestoreResponseSchema>;

package/src/user-notifications/index.ts

@@ -2,13 +2,37 @@
  * 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.
+ * See ./README.md for the domain, and user-notification-inbox-and-merged-feed
+ * 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 {
+  NOTIFICATION_ATTENTION_ON_SUPERSEDE,
+  NOTIFICATION_RESOLUTION_AUDIENCES,
+  NOTIFICATION_RETENTION_CLASSES,
+} from "./lifecycle";
+export type {
+  NotificationAttentionOnSupersede,
+  NotificationCondition,
+  NotificationLifecycle,
+  NotificationResolution,
+  NotificationResolutionAudience,
+  NotificationRetention,
+} from "./lifecycle";
+
+export { NOTIFICATION_LIFECYCLE } from "./lifecycle-registry";
+
+export {
+  conditionKeyOf,
+  NotificationConditionKeyError,
+  notificationKeysOf,
+} from "./condition-keys";
+export type { NotificationKeys } from "./condition-keys";
+
 export {
   FeedItemSchema,
   FeedListResponseSchema,
@@ -23,3 +47,26 @@ export type {
   FeedMarkReadRequest,
   UserNotification,
 } from "./schemas";
+
+export {
+  FEED_SELECTOR_MAX_IDS,
+  FEED_VIEWS,
+  FeedDeleteRequestSchema,
+  FeedDeleteResponseSchema,
+  FeedMarkUnreadRequestSchema,
+  FeedMutationResponseSchema,
+  FeedRestoreRequestSchema,
+  FeedRestoreResponseSchema,
+  FeedSelectorSchema,
+  FeedViewSchema,
+} from "./feed-lifecycle";
+export type {
+  FeedDeleteRequest,
+  FeedDeleteResponse,
+  FeedMarkUnreadRequest,
+  FeedMutationResponse,
+  FeedRestoreRequest,
+  FeedRestoreResponse,
+  FeedSelector,
+  FeedView,
+} from "./feed-lifecycle";

package/src/user-notifications/lifecycle-registry.ts

@@ -0,0 +1,123 @@
+/**
+ * NOTIFICATION_LIFECYCLE — every inbox kind's declared lifecycle
+ * (notification-lifecycle-is-declared-per-kind). See ./lifecycle for what each
+ * axis means.
+ */
+import type { UserNotificationKind } from "./kinds";
+import type { NotificationLifecycle } from "./lifecycle";
+
+const INDEPENDENT = {
+  condition: "none",
+  resolution: "never",
+  retention: "standard",
+} as const;
+const PER_KIND = { scope: "kind" } as const;
+const RESOLVED_FOR_ALL = {
+  mode: "source",
+  audience: "all-recipients",
+} as const;
+/** One active row per kind; each repeat is news again. */
+const RENEWING = {
+  condition: PER_KIND,
+  supersedes: true,
+  attentionOnSupersede: "renew",
+  resolution: "never",
+  retention: "standard",
+} as const;
+/** A standing condition: repeats update it quietly; the domain resolves it. */
+const STANDING = {
+  condition: PER_KIND,
+  supersedes: true,
+  attentionOnSupersede: "preserve",
+  resolution: RESOLVED_FOR_ALL,
+  retention: "standard",
+} as const;
+
+/**
+ * Every kind's lifecycle. Annotated (not `satisfies`) so a missing kind and an
+ * excess key are both compile errors. Values mirror
+ * company-semantics-control docs/notification-inbox.md § Per-kind lifecycle.
+ * (prettier-ignore keeps the annotation on one line, where it is greppable.)
+ */
+// prettier-ignore
+export const NOTIFICATION_LIFECYCLE: Readonly<Record<UserNotificationKind, NotificationLifecycle>> = {
+  "companyMd.access_requested": {
+    condition: { scope: "fields", fields: ["requestId"] },
+    supersedes: false,
+    resolution: RESOLVED_FOR_ALL,
+    retention: "standard",
+  },
+  "companyMd.access_request_approved": INDEPENDENT,
+  "companyMd.access_request_denied": INDEPENDENT,
+  "comment.mention": {
+    condition: { scope: "fields", fields: ["subjectId", "subjectType"] },
+    supersedes: true,
+    attentionOnSupersede: "renew",
+    resolution: "never",
+    retention: "standard",
+  },
+  "comment.reply": {
+    condition: { scope: "fields", fields: ["subjectId", "subjectType"] },
+    supersedes: true,
+    attentionOnSupersede: "renew",
+    resolution: "never",
+    retention: "standard",
+  },
+  "chat.mention": {
+    condition: { scope: "fields", fields: ["chatId"] },
+    supersedes: true,
+    attentionOnSupersede: "renew",
+    resolution: "never",
+    retention: "standard",
+  },
+  "proactive.org_became_shared": INDEPENDENT,
+  "proactive.brief_morning": RENEWING,
+  "proactive.billing_balance_below_half": STANDING,
+  "proactive.billing_balance_below_threshold": STANDING,
+  "proactive.billing_balance_exhausted": STANDING,
+  "proactive.billing_auto_recharge_failed": STANDING,
+  "proactive.billing_payment_past_due": STANDING,
+  "proactive.billing_suspended": STANDING,
+  "proactive.billing_byo_key_invalid": {
+    condition: { scope: "fields", fields: ["configId"] },
+    supersedes: true,
+    attentionOnSupersede: "preserve",
+    resolution: RESOLVED_FOR_ALL,
+    retention: "standard",
+  },
+  "proactive.billing_user_monthly_limit_reached": {
+    condition: { scope: "fields", fields: ["userId"] },
+    supersedes: true,
+    attentionOnSupersede: "renew",
+    resolution: "never",
+    retention: "standard",
+  },
+  "proactive.billing_auto_recharge_succeeded": RENEWING,
+  "proactive.billing_top_up_credited": RENEWING,
+  "proactive.billing_monthly_budget_80": RENEWING,
+  "proactive.billing_monthly_budget_100": RENEWING,
+  "proactive.billing_provider_price_changed": RENEWING,
+  "proactive.billing_payment_recovered": RENEWING,
+  "proactive.billing_subscription_canceled": RENEWING,
+  "proactive.source_sync_docs_updated": {
+    condition: PER_KIND,
+    supersedes: true,
+    attentionOnSupersede: "preserve",
+    resolution: "never",
+    retention: "standard",
+  },
+  "proactive.source_sync_review_ready": {
+    condition: { scope: "fields", fields: ["checkpoint"] },
+    supersedes: true,
+    attentionOnSupersede: "preserve",
+    resolution: RESOLVED_FOR_ALL,
+    retention: "standard",
+  },
+  "proactive.org_structure_review_ready": {
+    condition: PER_KIND,
+    supersedes: true,
+    attentionOnSupersede: "renew",
+    resolution: RESOLVED_FOR_ALL,
+    retention: "standard",
+  },
+};

package/src/user-notifications/lifecycle.ts

@@ -0,0 +1,75 @@
+/**
+ * The lifecycle of an inbox row, declared per kind.
+ *
+ * A notification row is the CURRENT ATTENTION ITEM for one condition, not an
+ * event record (control ADR `notification-inbox-is-an-attention-surface`).
+ *
+ *   condition   — what the row is about; addresses RESOLUTION. `none` = an
+ *                 independent delivery with no identity.
+ *   supersedes  — a property of the condition: a repeat occurrence updates the
+ *                 active row instead of appending one.
+ *   attentionOnSupersede — `renew` restores the kind's normal initial attention
+ *                 state (unread, or read when its class is born read);
+ *                 `preserve` keeps the row's current read state.
+ *   resolution  — `never`, or resolved by its producing DOMAIN (`source`) for
+ *                 `all-recipients` or only the `recipient`.
+ *   retention   — `standard`, or `persistent` (longer bounds; declared, never
+ *                 accidental).
+ *
+ * There is no Archive. See company-semantics-control docs/notification-inbox.md.
+ */
+
+export const NOTIFICATION_ATTENTION_ON_SUPERSEDE = [
+  "renew",
+  "preserve",
+] as const;
+export type NotificationAttentionOnSupersede =
+  (typeof NOTIFICATION_ATTENTION_ON_SUPERSEDE)[number];
+
+export const NOTIFICATION_RESOLUTION_AUDIENCES = [
+  "all-recipients",
+  "recipient",
+] as const;
+export type NotificationResolutionAudience =
+  (typeof NOTIFICATION_RESOLUTION_AUDIENCES)[number];
+
+export const NOTIFICATION_RETENTION_CLASSES = [
+  "standard",
+  "persistent",
+] as const;
+export type NotificationRetention =
+  (typeof NOTIFICATION_RETENTION_CLASSES)[number];
+
+export type NotificationCondition =
+  | { readonly scope: "kind" }
+  | {
+      readonly scope: "fields";
+      readonly fields: readonly [string, ...string[]];
+    };
+
+export type NotificationResolution =
+  | "never"
+  | {
+      readonly mode: "source";
+      readonly audience: NotificationResolutionAudience;
+    };
+
+type Supersession =
+  | { readonly supersedes: false }
+  | {
+      readonly supersedes: true;
+      readonly attentionOnSupersede: NotificationAttentionOnSupersede;
+    };
+
+export type NotificationLifecycle =
+  | {
+      /** An independent delivery: no identity, cannot resolve, cannot supersede. */
+      readonly condition: "none";
+      readonly resolution: "never";
+      readonly retention: NotificationRetention;
+    }
+  | ({
+      readonly condition: NotificationCondition;
+      readonly resolution: NotificationResolution;
+      readonly retention: NotificationRetention;
+    } & Supersession);

package/src/user-notifications/schemas.ts

@@ -6,6 +6,7 @@
  */
 import { z } from "zod";
 import { ActionItemSchema, ActionItemTargetSchema } from "../action-items";
+import { FeedSelectorSchema } from "./feed-lifecycle";
 import { USER_NOTIFICATION_KINDS } from "./kinds";
 
 /** Zod mirror of the vocabulary. `./kinds` owns the list; this never restates it. */
@@ -68,9 +69,22 @@ export const UserNotificationSchema = z.object({
    * longer see" is itself true and useful; it simply does not link anywhere.
    */
   href: z.string().nullable(),
+  /** When the row was first written — its FIRST occurrence. */
   createdAt: z.string(),
-  /** `null` while unread. The only mutable field on the row. */
+  /** `null` while unread. Changed by the read/unread verbs and by supersession. */
   readAt: z.string().nullable(),
+  /**
+   * The time of the LATEST occurrence this row represents — the ordering and
+   * retention clock. Equals `createdAt` until a repeat supersedes into the row.
+   */
+  activityAt: z.string(),
+  /** How many occurrences this row has absorbed by supersession. 1 for a fresh row. */
+  occurrenceCount: z.number().int().positive(),
+  /**
+   * Set when the producing domain resolved the row's condition; `null` while
+   * it stands. A resolved row still renders (muted) until retention removes it.
+   */
+  resolvedAt: z.string().nullable(),
 });
 export type UserNotification = z.infer<typeof UserNotificationSchema>;
 
@@ -103,7 +117,8 @@ 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"
+ * `actionable` row first, then `informational` rows — unread-and-unresolved
+ * first, then `activityAt` DESC, `id` DESC. "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.
@@ -119,10 +134,16 @@ export const FeedListResponseSchema = z.object({
   /**
    * 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.
+   * Encodes `(unread, activityAt, id)`, mirroring the ordering above — `id`
+   * breaks ties so two rows with the same activity cannot straddle a page
+   * boundary and be served twice or skipped. Never parse it.
    */
   nextCursor: z.string().nullable(),
+  /**
+   * The number of notification rows matching the requested view — never action
+   * items, never a window. What "Select all in this view" would touch.
+   */
+  viewCount: z.number().int().nonnegative(),
   /**
    * Total unread across ALL retained notifications — NOT within the returned
    * window.
@@ -136,8 +157,8 @@ export const FeedListResponseSchema = z.object({
 });
 export type FeedListResponse = z.infer<typeof FeedListResponseSchema>;
 
-/** `POST /api/me/feed/read` — mark specific informational rows read. */
+/** `POST /api/me/feed/read` — mark the selected informational rows read. */
 export const FeedMarkReadRequestSchema = z.object({
-  notificationIds: z.array(z.string()).min(1).max(200),
+  selector: FeedSelectorSchema,
 });
 export type FeedMarkReadRequest = z.infer<typeof FeedMarkReadRequestSchema>;