@company-semantics/contracts 82.0.0 → 83.1.0

package/package.json

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

package/src/api/generated.ts

@@ -281,6 +281,23 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/api/chats/resolve-launch": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /** Resolve a launch to its subject’s active chat (read-only) */
+        post: operations["resolveChatLaunch"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/api/chats/{id}": {
         parameters: {
             query?: never;
@@ -369,6 +386,23 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/api/chats/{id}/start-fresh": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /** Start a fresh chat on the same subject, handing over a summary */
+        post: operations["startFreshChat"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/api/chats/{id}/generate-title": {
         parameters: {
             query?: never;
@@ -4865,6 +4899,34 @@ export interface components {
                 avatarUrl: string | null;
             }[];
         };
+        ResolveLaunchResponse: {
+            subjectId: string | null;
+            chatId: string | null;
+            generation: number | null;
+            /** @enum {string} */
+            disposition: "resume-existing-anchor" | "resume-and-launch" | "created-and-launch";
+        };
+        /** @description The launch to resolve against its subject’s active generation. */
+        ResolveLaunchRequest: {
+            launch: {
+                /** @constant */
+                kind: "structure-review";
+                /** Format: uuid */
+                proposalId: string;
+            } | {
+                /** @constant */
+                kind: "workflow";
+                /** Format: uuid */
+                workflowId: string;
+            } | {
+                /** @constant */
+                kind: "input-request";
+                /** @enum {string} */
+                requestType: "org-structure/review" | "source-sync/candidates" | "source-sync/synthesis";
+                /** Format: uuid */
+                requestId: string;
+            };
+        };
         GetChatResponse: {
             chat: {
                 id: string;
@@ -4973,6 +5035,20 @@ export interface components {
             /** Format: uuid */
             userId: string;
         };
+        StartFreshChatResponse: {
+            chatId: string;
+            interactionId: string;
+            subjectId: string;
+            generation: number;
+            continuationOf: {
+                chatId: string;
+            };
+        };
+        LaunchTargetSuperseded: {
+            /** @constant */
+            code: "launch_target_superseded";
+            activeChatId: string | null;
+        };
         GenerateTitleResponse: {
             title: string;
             isAutoGenerated: boolean;
@@ -7629,9 +7705,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;
         };
@@ -10050,6 +10130,8 @@ export interface operations {
                 limit?: number;
                 cursor?: string;
                 includePinned?: "true" | "false";
+                surface?: "recents";
+                subjectId?: string;
             };
             header?: never;
             path?: never;
@@ -10136,6 +10218,30 @@ export interface operations {
             };
         };
     };
+    resolveChatLaunch: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["ResolveLaunchRequest"];
+            };
+        };
+        responses: {
+            /** @description Where the launch would land; nothing is written */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ResolveLaunchResponse"];
+                };
+            };
+        };
+    };
     getChat: {
         parameters: {
             query?: never;
@@ -10326,6 +10432,37 @@ export interface operations {
             };
         };
     };
+    startFreshChat: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                id: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description The new active chat of the subject */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["StartFreshChatResponse"];
+                };
+            };
+            /** @description The chat is not its subject’s active chat */
+            409: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["LaunchTargetSuperseded"];
+                };
+            };
+        };
+    };
     generateChatTitle: {
         parameters: {
             query?: never;

package/src/generated/openapi-routes.ts

@@ -20,6 +20,7 @@ export const openApiRoutes = {
   '/api/chats/events': ['GET'],
   '/api/chats/mentionable': ['GET'],
   '/api/chats/proactive/{eventId}': ['GET'],
+  '/api/chats/resolve-launch': ['POST'],
   '/api/chats/{chatId}/shares': ['GET', 'POST'],
   '/api/chats/{id}': ['DELETE', 'GET', 'PATCH'],
   '/api/chats/{id}/generate-title': ['POST'],
@@ -28,6 +29,7 @@ export const openApiRoutes = {
   '/api/chats/{id}/participants': ['GET', 'POST'],
   '/api/chats/{id}/participants/{userId}': ['DELETE'],
   '/api/chats/{id}/pin': ['DELETE', 'POST'],
+  '/api/chats/{id}/start-fresh': ['POST'],
   '/api/comments': ['GET'],
   '/api/comments/threads': ['POST'],
   '/api/comments/threads/{threadId}': ['DELETE'],

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,
+      );
+    }
+  });
+});