@company-semantics/contracts 81.0.0 → 83.0.0

package/src/chat/continuity.ts

@@ -0,0 +1,207 @@
+/**
+ * Chat continuity wire vocabulary (chat-continuity-wire-vocabulary).
+ *
+ * A chat can belong to a SUBJECT — the durable case a hand-off to chat is
+ * about (a candidate review, a synthesis review, an org-structure review).
+ * A subject is worked in GENERATIONS: generation 1 is the first chat about
+ * it, and each "start fresh" mints the next generation linked back to its
+ * predecessor. Exactly one generation is active at a time, or none.
+ *
+ * Three identities, never conflated:
+ *   - the SUBJECT (`subjectId`) — the case, stable across every generation
+ *   - the GENERATION (`generation`) — which chat of the case this is
+ *   - the CHAT (`chatId`) — the ordinary chat row carrying that generation
+ *
+ * The contracts own only the wire shapes. Continuity POLICY — which launch
+ * kinds map onto which subject kind, what a subject is titled, when a new
+ * generation starts — is server-owned and deliberately absent here.
+ *
+ * LOAD ORDER: this module imports only zod and the shared primitives, and
+ * must NEVER import `./schemas` — `./schemas` imports this file, and the
+ * reverse edge would reach its declarations in the temporal dead zone.
+ * Types are declared here beside their schemas, as `./runtime-profile` does.
+ */
+
+import { z } from "zod";
+import { IsoDateTime } from "../api/primitives";
+
+/**
+ * The kinds of subject a chat can continue. CLOSED and append-only: a new
+ * kind is a new hand-off surface, and a consumer switching on this union
+ * must be told about it by the compiler.
+ *
+ * Deliberately NOT the input-request types or the launch kinds — the server
+ * maps those onto these, and that mapping is policy, not vocabulary.
+ */
+export const CONVERSATION_SUBJECT_KINDS = [
+  /** Reviewing the candidate files a source sync proposes to include. */
+  "source-sync-candidate-review",
+  /** Reviewing the synthesis a source sync produced. */
+  "source-sync-synthesis-review",
+  /** Reviewing the org structure. */
+  "org-structure-review",
+] as const;
+
+export const ConversationSubjectKindSchema = z.enum(CONVERSATION_SUBJECT_KINDS);
+export type ConversationSubjectKind = z.infer<
+  typeof ConversationSubjectKindSchema
+>;
+
+/**
+ * Why a generation continues its predecessor. CLOSED, and grown ONLY when a
+ * real trigger exists: today the only way a new generation starts is the
+ * reader choosing to start fresh. Speculative reasons are not wire values.
+ */
+export const CHAT_CONTINUATION_REASONS = [
+  /** The reader explicitly started a fresh chat on the same subject. */
+  "user-started-fresh",
+] as const;
+
+export const ChatContinuationReasonSchema = z.enum(CHAT_CONTINUATION_REASONS);
+export type ChatContinuationReason = z.infer<
+  typeof ChatContinuationReasonSchema
+>;
+
+/**
+ * Where a chat sits in its subject's lineage — carried on the chat detail.
+ *
+ * `continuationOf` and `continuationReason` are null TOGETHER or non-null
+ * TOGETHER; the refinement rejects a reason without a predecessor and a
+ * predecessor without a reason.
+ */
+export const ChatContinuitySchema = z
+  .object({
+    /** The subject (case) this chat belongs to — stable across generations. */
+    subjectId: z.string(),
+    subjectKind: ConversationSubjectKindSchema,
+    /** Server-authored display title of the subject. */
+    subjectTitle: z.string(),
+    /** Which generation of the subject this chat is; the first is 1. */
+    generation: z.number().int().positive(),
+    /** Whether THIS chat is the subject's active generation. */
+    isActiveGeneration: z.boolean(),
+    /**
+     * Where the case continues NOW. Equals this chat's own id when it is the
+     * active generation; another chat's id when a later generation took over;
+     * NULL when the subject currently has no active generation.
+     */
+    activeChatId: z.string().nullable(),
+    /**
+     * The generation this chat continues. NULL for generation 1, for a
+     * generation started after its predecessor was DELETED, and when the
+     * predecessor row no longer exists — a dangling link is never sent.
+     */
+    continuationOf: z
+      .object({
+        chatId: z.string(),
+        createdAt: IsoDateTime,
+      })
+      .nullable(),
+    /** Why this generation continues its predecessor; null exactly when `continuationOf` is. */
+    continuationReason: ChatContinuationReasonSchema.nullable(),
+  })
+  .refine(
+    (continuity) =>
+      (continuity.continuationOf === null) ===
+      (continuity.continuationReason === null),
+    {
+      message:
+        "continuationReason must be null exactly when continuationOf is null",
+      path: ["continuationReason"],
+    },
+  );
+export type ChatContinuity = z.infer<typeof ChatContinuitySchema>;
+
+/**
+ * What the read-only launch resolution found for a hand-off. CLOSED: the
+ * client branches on it to decide whether to open an existing chat, open it
+ * and post the launch, or create a chat and post the launch.
+ */
+export const LAUNCH_DISPOSITIONS = [
+  /** The subject's active generation already carries this launch — just open it. */
+  "resume-existing-anchor",
+  /** Open the subject's active generation and post the launch into it. */
+  "resume-and-launch",
+  /** No active generation to resume — the launch write creates the chat. */
+  "created-and-launch",
+] as const;
+
+export const LaunchDispositionSchema = z.enum(LAUNCH_DISPOSITIONS);
+export type LaunchDisposition = z.infer<typeof LaunchDispositionSchema>;
+
+/**
+ * Response of the read-only launch resolution.
+ *
+ * Resolution is READ-ONLY and never creates a chat, so `created-and-launch`
+ * carries a null `chatId` AND a null `generation`; its `subjectId` is still
+ * reported when the subject row already exists (a stable subject with no
+ * active generation), else null. Both `resume-*` dispositions name an
+ * existing chat, so `subjectId`, `chatId` and `generation` are all non-null.
+ * The refinement rejects every other combination.
+ */
+export const ResolveLaunchResponseSchema = z
+  .object({
+    subjectId: z.string().nullable(),
+    chatId: z.string().nullable(),
+    generation: z.number().int().positive().nullable(),
+    disposition: LaunchDispositionSchema,
+  })
+  .superRefine((response, ctx) => {
+    if (response.disposition === "created-and-launch") {
+      if (response.chatId !== null || response.generation !== null) {
+        ctx.addIssue({
+          code: "custom",
+          message:
+            "created-and-launch must carry a null chatId and a null generation — resolution never creates a chat",
+          path: ["disposition"],
+        });
+      }
+      return;
+    }
+    for (const field of ["subjectId", "chatId", "generation"] as const) {
+      if (response[field] === null) {
+        ctx.addIssue({
+          code: "custom",
+          message: `${response.disposition} must name the chat it resumes: ${field} is required`,
+          path: [field],
+        });
+      }
+    }
+  });
+export type ResolveLaunchResponse = z.infer<typeof ResolveLaunchResponseSchema>;
+
+/**
+ * Response of the start-fresh write: the NEW active generation of the
+ * subject, linked back to the chat it continues. Start-fresh always has a
+ * predecessor — the chat it was invoked on — so `continuationOf` is required.
+ */
+export const StartFreshChatResponseSchema = z.object({
+  chatId: z.string(),
+  interactionId: z.string(),
+  subjectId: z.string(),
+  generation: z.number().int().positive(),
+  continuationOf: z.object({
+    chatId: z.string(),
+  }),
+});
+export type StartFreshChatResponse = z.infer<
+  typeof StartFreshChatResponseSchema
+>;
+
+/** The 409 code for a launch posted into a chat that is not the subject's active generation. */
+export const LAUNCH_TARGET_SUPERSEDED_CODE =
+  "launch_target_superseded" as const;
+
+/**
+ * The 409 body the authoritative launch write returns when the posted chat
+ * is not — or can no longer become — the subject's active generation.
+ * `activeChatId` names where the case continues now; NULL means there is no
+ * active generation and the client should start a new chat.
+ */
+export const LaunchTargetSupersededSchema = z.object({
+  code: z.literal(LAUNCH_TARGET_SUPERSEDED_CODE),
+  activeChatId: z.string().nullable(),
+});
+export type LaunchTargetSuperseded = z.infer<
+  typeof LaunchTargetSupersededSchema
+>;

package/src/chat/index.ts

@@ -124,6 +124,32 @@ export {
 export type { RecognizedProactiveKind } from "./proactive-kind";
 export { recognizeProactiveKind } from "./proactive-kind";
 
+// Chat continuity (chat-continuity-wire-vocabulary): subjects, generations
+// and the lineage a chat detail carries; the launch-resolution disposition,
+// the start-fresh response and the launch-target 409
+export type {
+  ConversationSubjectKind,
+  ChatContinuationReason,
+  ChatContinuity,
+  LaunchDisposition,
+  ResolveLaunchResponse,
+  StartFreshChatResponse,
+  LaunchTargetSuperseded,
+} from "./continuity";
+export {
+  CONVERSATION_SUBJECT_KINDS,
+  ConversationSubjectKindSchema,
+  CHAT_CONTINUATION_REASONS,
+  ChatContinuationReasonSchema,
+  ChatContinuitySchema,
+  LAUNCH_DISPOSITIONS,
+  LaunchDispositionSchema,
+  ResolveLaunchResponseSchema,
+  StartFreshChatResponseSchema,
+  LAUNCH_TARGET_SUPERSEDED_CODE,
+  LaunchTargetSupersededSchema,
+} from "./continuity";
+
 // Runtime profile types and constants
 export type {
   ChatRuntimeProfile,

package/src/chat/schemas.ts

@@ -18,6 +18,7 @@ import { z } from "zod";
 import { IsoDateTime } from "../api/primitives";
 import { MentionableCandidateSchema } from "../comments/schemas";
 import { PrincipalRefSchema } from "../identity/agent";
+import { ChatContinuitySchema } from "./continuity";
 import {
   ChatParticipantRoleSchema,
   ChatVisibilitySchema,
@@ -468,6 +469,12 @@ export const ChatDetailSchema = z.object({
    * an empty array is not a state the server produces.
    */
   participants: z.array(ChatParticipantSchema).optional(),
+  /**
+   * The chat's place in its subject's lineage (chat-continuity-wire-vocabulary).
+   * NULL for a chat that belongs to no subject. REQUIRED, not optional: a
+   * missing one is a backend that has not adopted this release.
+   */
+  continuity: ChatContinuitySchema.nullable(),
 });
 
 /** Response for GET /api/chats/:id */

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
@@ -589,6 +639,17 @@ export type {
   ChatParticipantRole,
   ChatParticipant,
   ChatParticipantsResponse,
+  // Chat continuity (chat-continuity-wire-vocabulary): the subject a chat
+  // belongs to, its generation, and the lineage back to its predecessor.
+  ConversationSubjectKind,
+  ChatContinuationReason,
+  ChatContinuity,
+  // Launch resolution: the disposition the read-only resolve reports, the
+  // start-fresh response, and the launch-target-superseded 409 body.
+  LaunchDisposition,
+  ResolveLaunchResponse,
+  StartFreshChatResponse,
+  LaunchTargetSuperseded,
 } from "./chat/index";
 
 export {
@@ -616,6 +677,21 @@ export {
   ChatParticipantRoleSchema,
   ChatParticipantSchema,
   ChatParticipantsResponseSchema,
+  // Chat continuity: the closed subject-kind and continuation-reason
+  // vocabularies, and the lineage object on the chat detail.
+  CONVERSATION_SUBJECT_KINDS,
+  ConversationSubjectKindSchema,
+  CHAT_CONTINUATION_REASONS,
+  ChatContinuationReasonSchema,
+  ChatContinuitySchema,
+  // Launch resolution: the closed disposition vocabulary, the resolve and
+  // start-fresh responses, and the 409 code + body for a superseded target.
+  LAUNCH_DISPOSITIONS,
+  LaunchDispositionSchema,
+  ResolveLaunchResponseSchema,
+  StartFreshChatResponseSchema,
+  LAUNCH_TARGET_SUPERSEDED_CODE,
+  LaunchTargetSupersededSchema,
 } from "./chat/index";
 
 // Organization domain types

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;