@company-semantics/contracts 82.0.0 → 83.1.0

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";