@company-semantics/contracts 81.0.0 → 82.0.0

package/package.json

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

package/src/api/generated.ts

@@ -4889,6 +4889,21 @@ export interface components {
                     /** Format: date-time */
                     addedAt: string;
                 }[];
+                continuity: {
+                    subjectId: string;
+                    /** @enum {string} */
+                    subjectKind: "source-sync-candidate-review" | "source-sync-synthesis-review" | "org-structure-review";
+                    subjectTitle: string;
+                    generation: number;
+                    isActiveGeneration: boolean;
+                    activeChatId: string | null;
+                    continuationOf: {
+                        chatId: string;
+                        /** Format: date-time */
+                        createdAt: string;
+                    } | null;
+                    continuationReason: "user-started-fresh" | null;
+                } | null;
             };
             messages: {
                 id: string;

package/src/chat/README.md

@@ -38,24 +38,44 @@ Shared types for chat persistence, sharing, real-time events, and runtime profil
 - The summary carries a participant COUNT, never the roster. A 50-row sidebar page must not carry 50 rosters, and a chat's membership is not disclosed by the chat merely appearing in a list. `ChatDetail.participants` is where the names are, and it is optional — a missing roster is simply not drawn, whereas a guessed role is drawn wrong
 - A `ChatParticipant` is a USER, never a `PrincipalRef` — the deliberate asymmetry with a mention TARGET, which is a ref precisely so the agent can be named. The agent takes part in every chat by construction and has no participant row: it is mentionable, not a member, and cannot be added, removed or left
 - `ChatParticipantRole` has EXACTLY two members. A third would be an access band, and this is participation rather than an ACL: a participant sees the whole conversation, `owner` names the one person who additionally deletes, renames, pins and shares it, and a chat you can read half of is not a thing this surface models
-- The chat schemas are THREE files with a one-way load order: `enums.ts` (the closed vocabularies plus the `proactiveChatFields` / `multiPartyChatFields` groups) imports nothing from the domain, `event-schemas.ts` imports only from it, and `schemas.ts` imports from both and RE-EXPORTS them so `index.ts`, `types.ts` and the tests keep one import site. An import from either of the first two back into `schemas.ts` is a load cycle: the re-export edge is evaluated before `schemas.ts`'s body, so the shared declarations are reached in the temporal dead zone and every consumer throws a `ReferenceError` at import time
+- The chat schemas are THREE files with a one-way load order: `enums.ts` (the closed vocabularies plus the `proactiveChatFields` / `multiPartyChatFields` groups) imports nothing from the domain, `event-schemas.ts` imports only from it, and `schemas.ts` imports from both and RE-EXPORTS them so `index.ts`, `types.ts` and the tests keep one import site. An import from either of the first two back into `schemas.ts` is a load cycle: the re-export edge is evaluated before `schemas.ts`'s body, so the shared declarations are reached in the temporal dead zone and every consumer throws a `ReferenceError` at import time. `continuity.ts` sits outside that set on the same terms: `schemas.ts` imports it, it never imports `schemas.ts`, and `index.ts` re-exports it directly (its types are declared beside its schemas, as `runtime-profile.ts` does)
 - `CHAT_PAGE_VIEWS` and `CHAT_PAGE_SCOPES` are a projection of the app's `Route` union (`company-semantics-app/src/platform/route-parser.ts`), not a parallel vocabulary. A view the parser can emit but the schema rejects fails the send outright rather than degrading
 
+## Continuity
+
+A chat can belong to a SUBJECT — the durable case a hand-off to chat is about — and a subject is worked in numbered GENERATIONS, each a chat linked back to its predecessor (`src/chat/continuity.ts`, ADR slug `chat-continuity-wire-vocabulary`).
+
+- `ChatDetail.continuity` is REQUIRED and NULLABLE: null means the chat belongs to no subject; a missing key is a backend that has not adopted the release
+- Three identities, never conflated: `subjectId` (the case), `generation` (1-based position in the lineage), and the chat id carrying it. `activeChatId` is where the case continues now — this chat's own id when it is active, null when the subject has no active generation
+- `continuationOf` and `continuationReason` are null together: generation 1, a generation started after its predecessor was deleted, and a predecessor row that no longer exists all send null, never a dangling link
+- Compaction NEVER changes subject or generation identity. Compacting a chat (`compactedThroughSequence`) summarizes the older turns of the SAME chat — it keeps the same `subjectId`, the same `generation` and the same chat id, and it is not a continuation. A new generation starts only through a `continuationReason`, and compaction is deliberately not one
+- `CONVERSATION_SUBJECT_KINDS` and `CHAT_CONTINUATION_REASONS` are CLOSED. A reason is added only when a real trigger exists; the launch-kind → subject-kind mapping and subject titles are server policy and do not live here
+- Launch resolution is READ-ONLY and never creates a chat. `LAUNCH_DISPOSITIONS` is CLOSED; `created-and-launch` carries a null `chatId` AND a null `generation` (its `subjectId` is still reported when the subject row exists), and both `resume-*` dispositions carry `subjectId`, `chatId` and `generation`. `ResolveLaunchResponseSchema` refuses every other combination
+- `StartFreshChatResponse` is the NEW active generation and always links its predecessor (`continuationOf.chatId`)
+- A launch posted into a chat that is not — or can no longer become — the subject's active generation is a 409 whose body is `LaunchTargetSuperseded` (`code: "launch_target_superseded"`); its `activeChatId` names where to go, and null means start a new chat
+- Request bodies for resolve-launch and start-fresh are deliberately NOT here: the resolve body embeds the backend-local launch schema, and start-fresh has no body
+
 <!-- BEGIN GENERATED: readme-public-api — derived from code by `pnpm readme-api`. Do not edit. -->
 
 ## Public API
 
 - `BaseEvent` _(type)_ — Base envelope for all SSE events.
 - `BaseEventSchema`
+- `CHAT_CONTINUATION_REASONS` — Why a generation continues its predecessor.
 - `CHAT_DISCUSSION_REQUEST_TYPES` — The kinds of durable input request a turn can be scoped to.
 - `CHAT_PAGE_ENTITY_TYPES` — What kind of thing the reader has open, when they have one open.
 - `CHAT_PAGE_SCOPES` — The route parser's four URL scopes: unscoped, `/me/*`, `/team/*`, `/@:org/*`.
 - `CHAT_PAGE_VIEWS` — The app route parser's seventeen `type` values, projected onto the wire.
 - `CHAT_RUNTIME_PROFILES` — Ordered list of available profiles for UI rendering.
+- `CONVERSATION_SUBJECT_KINDS` — The kinds of subject a chat can continue.
 - `ChatByInteractionResponse` _(type)_ — Response for GET /api/chats/by-interaction/:interactionId
 - `ChatByInteractionResponseSchema` — Response for GET /api/chats/by-interaction/:interactionId
 - `ChatChangedField` _(type)_ — Fields that can change on a chat, used in changed array.
 - `ChatChangedFieldSchema`
+- `ChatContinuationReason` _(type)_
+- `ChatContinuationReasonSchema`
+- `ChatContinuity` _(type)_
+- `ChatContinuitySchema` — Where a chat sits in its subject's lineage — carried on the chat detail.
 - `ChatCreatedEvent` _(type)_ — Emitted exactly once after a chat is successfully persisted.
 - `ChatCreatedEventSchema` — Emitted exactly once after a chat is persisted; a pushed proactive chat is announced over this event too.
 - `ChatDeletedEvent` _(type)_ — Emitted when a chat is deleted.
@@ -103,6 +123,8 @@ Shared types for chat persistence, sharing, real-time events, and runtime profil
 - `ChatUpdatedEventSchema`
 - `ChatVisibility` _(type)_ — Chat share visibility. - private: Token exists but access requires authentication as chat owner - public…
 - `ChatVisibilitySchema`
+- `ConversationSubjectKind` _(type)_
+- `ConversationSubjectKindSchema`
 - `CreateChatResponse` _(type)_ — Response for POST /api/chats
 - `CreateChatResponseSchema` — Response for POST /api/chats
 - `CreateShareRequest` _(type)_ — Request to create a new share for a chat.
@@ -117,15 +139,25 @@ Shared types for chat persistence, sharing, real-time events, and runtime profil
 - `InvalidateChatListEventSchema`
 - `InvalidationReason` _(type)_ — Reason for cache invalidation.
 - `InvalidationReasonSchema`
+- `LAUNCH_DISPOSITIONS` — What the read-only launch resolution found for a hand-off.
+- `LAUNCH_TARGET_SUPERSEDED_CODE` — The 409 code for a launch posted into a chat that is not the subject's active generation.
+- `LaunchDisposition` _(type)_
+- `LaunchDispositionSchema`
+- `LaunchTargetSuperseded` _(type)_
+- `LaunchTargetSupersededSchema` — The 409 body the authoritative launch write returns when the posted chat is not — or can no longer become —…
 - `ListSharesResponse` _(type)_ — Response for GET /api/chats/:chatId/shares
 - `ListSharesResponseSchema` — Response for GET /api/chats/:chatId/shares
 - `ProactiveChatResolution` _(type)_ — Resolving an occurrence id to the CURRENT reader's chat — one of the four bounded states `ready` (with…
 - `ProactiveChatResolutionSchema` — Resolving an occurrence id to THIS reader's chat (INV-PROACTIVE-LINK).
 - `RecognizedProactiveKind` _(type)_ — A wire `proactiveKind` after recognition: a kind this contracts version knows, or the raw string it did not —…
+- `ResolveLaunchResponse` _(type)_
+- `ResolveLaunchResponseSchema` — Response of the read-only launch resolution.
 - `SharedChatMessage` _(type)_ — Individual message in a shared chat view.
 - `SharedChatMessageSchema`
 - `SharedChatView` _(type)_ — Shared chat view returned to viewers.
 - `SharedChatViewSchema`
+- `StartFreshChatResponse` _(type)_
+- `StartFreshChatResponseSchema` — Response of the start-fresh write: the NEW active generation of the subject, linked back to the chat it…
 - `TitleGenerationRequest` _(type)_ — Request to generate a title for a chat.
 - `TitleGenerationResponse` _(type)_ — Response from title generation.
 - `TitleGenerationResponseSchema`

package/src/chat/__tests__/compaction-boundary.test.ts

@@ -34,6 +34,7 @@ const BASE_DETAIL = {
   interactionId: "int_1",
   createdAt: "2026-08-31T00:00:00.000Z",
   updatedAt: "2026-08-31T01:00:00.000Z",
+  continuity: null,
 };
 
 describe("ChatDetail compaction boundary", () => {

package/src/chat/__tests__/continuity.test.ts

@@ -0,0 +1,402 @@
+/**
+ * Chat continuity wire vocabulary (chat-continuity-wire-vocabulary).
+ *
+ * INVARIANTS TESTED:
+ * - The subject-kind and continuation-reason vocabularies are CLOSED and
+ *   pinned member-for-member; the only continuation reason is
+ *   `user-started-fresh`.
+ * - `generation` is a positive integer — generation 1 is the first.
+ * - `continuationOf` and `continuationReason` are null TOGETHER: a reason
+ *   without a predecessor, or a predecessor without a reason, is refused.
+ * - `activeChatId` is nullable (the subject has no active generation).
+ * - `ChatDetail.continuity` is REQUIRED and NULLABLE: null parses (a chat
+ *   with no subject), a missing key does not.
+ * - The launch dispositions are CLOSED. `created-and-launch` carries a null
+ *   chatId AND generation (resolve never creates a chat); both `resume-*`
+ *   dispositions carry subjectId, chatId and generation — the refinement
+ *   rejects either direction of violation.
+ * - The start-fresh response always links its predecessor; the 409 body's
+ *   code is the literal `launch_target_superseded`, activeChatId nullable.
+ * - Every export is reachable from both the chat barrel and the root barrel.
+ */
+import { describe, expect, it } from "vitest";
+import * as root from "../../index";
+import {
+  CHAT_CONTINUATION_REASONS,
+  ChatContinuationReasonSchema,
+  ChatContinuitySchema,
+  CONVERSATION_SUBJECT_KINDS,
+  ConversationSubjectKindSchema,
+  LAUNCH_DISPOSITIONS,
+  LAUNCH_TARGET_SUPERSEDED_CODE,
+  LaunchDispositionSchema,
+  LaunchTargetSupersededSchema,
+  ResolveLaunchResponseSchema,
+  StartFreshChatResponseSchema,
+} from "../continuity";
+import * as chat from "../index";
+import { ChatDetailSchema, GetChatResponseSchema } from "../schemas";
+
+// ---------------------------------------------------------------------------
+// Fixtures
+// ---------------------------------------------------------------------------
+
+/** Generation 1 of a subject, and the active one. */
+const FIRST_GENERATION = {
+  subjectId: "subj_1",
+  subjectKind: "source-sync-candidate-review",
+  subjectTitle: "Review candidate files",
+  generation: 1,
+  isActiveGeneration: true,
+  activeChatId: "chat_1",
+  continuationOf: null,
+  continuationReason: null,
+} as const;
+
+/** Generation 2, continuing chat_1 because the reader started fresh. */
+const SECOND_GENERATION = {
+  ...FIRST_GENERATION,
+  generation: 2,
+  activeChatId: "chat_2",
+  continuationOf: { chatId: "chat_1", createdAt: "2026-09-01T00:00:00.000Z" },
+  continuationReason: "user-started-fresh",
+} as const;
+
+/** A chat detail with every REQUIRED field except `continuity`. */
+const BASE_DETAIL = {
+  id: "chat_1",
+  title: "Candidate review",
+  interactionId: "int_1",
+  createdAt: "2026-09-01T00:00:00.000Z",
+  updatedAt: "2026-09-01T01:00:00.000Z",
+};
+
+describe("continuity vocabularies", () => {
+  it("pins the closed subject kinds", () => {
+    expect([...CONVERSATION_SUBJECT_KINDS]).toEqual([
+      "source-sync-candidate-review",
+      "source-sync-synthesis-review",
+      "org-structure-review",
+    ]);
+    expect(new Set(CONVERSATION_SUBJECT_KINDS).size).toBe(
+      CONVERSATION_SUBJECT_KINDS.length,
+    );
+    expect(ConversationSubjectKindSchema.safeParse("chat").success).toBe(false);
+  });
+
+  it("has exactly one continuation reason: user-started-fresh", () => {
+    expect([...CHAT_CONTINUATION_REASONS]).toEqual(["user-started-fresh"]);
+    expect(ChatContinuationReasonSchema.safeParse("inactivity").success).toBe(
+      false,
+    );
+    expect(
+      ChatContinuationReasonSchema.safeParse("semantic-divergence").success,
+    ).toBe(false);
+  });
+});
+
+describe("ChatContinuitySchema", () => {
+  it("a first generation has no continuation", () => {
+    const parsed = ChatContinuitySchema.parse(FIRST_GENERATION);
+    expect(parsed).toEqual(FIRST_GENERATION);
+    expect(parsed.generation).toBe(1);
+    expect(parsed.continuationOf).toBeNull();
+    expect(parsed.continuationReason).toBeNull();
+  });
+
+  it("parses a continuing generation with its predecessor and reason", () => {
+    expect(ChatContinuitySchema.parse(SECOND_GENERATION)).toEqual(
+      SECOND_GENERATION,
+    );
+  });
+
+  it("parses a superseded generation pointing at the active chat", () => {
+    const parsed = ChatContinuitySchema.parse({
+      ...FIRST_GENERATION,
+      isActiveGeneration: false,
+      activeChatId: "chat_2",
+    });
+    expect(parsed.activeChatId).toBe("chat_2");
+  });
+
+  it("accepts a null activeChatId when the subject has no active generation", () => {
+    const parsed = ChatContinuitySchema.parse({
+      ...FIRST_GENERATION,
+      isActiveGeneration: false,
+      activeChatId: null,
+    });
+    expect(parsed.activeChatId).toBeNull();
+  });
+
+  it("refuses a reason without a predecessor", () => {
+    expect(
+      ChatContinuitySchema.safeParse({
+        ...FIRST_GENERATION,
+        continuationReason: "user-started-fresh",
+      }).success,
+    ).toBe(false);
+  });
+
+  it("refuses a predecessor without a reason", () => {
+    expect(
+      ChatContinuitySchema.safeParse({
+        ...SECOND_GENERATION,
+        continuationReason: null,
+      }).success,
+    ).toBe(false);
+  });
+
+  it("requires a positive integer generation", () => {
+    for (const generation of [0, -1, 1.5]) {
+      expect(
+        ChatContinuitySchema.safeParse({ ...FIRST_GENERATION, generation })
+          .success,
+      ).toBe(false);
+    }
+  });
+
+  it("requires an ISO timestamp on the predecessor", () => {
+    expect(
+      ChatContinuitySchema.safeParse({
+        ...SECOND_GENERATION,
+        continuationOf: { chatId: "chat_1", createdAt: "yesterday" },
+      }).success,
+    ).toBe(false);
+  });
+
+  it("an unknown subject kind is rejected", () => {
+    expect(
+      ChatContinuitySchema.safeParse({
+        ...FIRST_GENERATION,
+        subjectKind: "org-structure/review",
+      }).success,
+    ).toBe(false);
+  });
+});
+
+describe("ChatDetail.continuity", () => {
+  it("is null for a chat that belongs to no subject", () => {
+    const parsed = ChatDetailSchema.parse({ ...BASE_DETAIL, continuity: null });
+    expect(parsed.continuity).toBeNull();
+  });
+
+  it("carries the lineage for a chat that belongs to a subject", () => {
+    const parsed = ChatDetailSchema.parse({
+      ...BASE_DETAIL,
+      continuity: SECOND_GENERATION,
+    });
+    expect(parsed.continuity?.generation).toBe(2);
+  });
+
+  it("a chat detail without continuity fails to parse", () => {
+    expect(ChatDetailSchema.safeParse(BASE_DETAIL).success).toBe(false);
+  });
+
+  it("rides the chat detail in GET /api/chats/:id", () => {
+    const parsed = GetChatResponseSchema.parse({
+      chat: { ...BASE_DETAIL, continuity: FIRST_GENERATION },
+      messages: [],
+    });
+    expect(parsed.chat.continuity?.subjectId).toBe("subj_1");
+  });
+});
+
+describe("barrel exports", () => {
+  it("every continuity value is reachable from both barrels", () => {
+    for (const barrel of [chat, root]) {
+      expect(barrel.CONVERSATION_SUBJECT_KINDS).toBe(
+        CONVERSATION_SUBJECT_KINDS,
+      );
+      expect(barrel.ConversationSubjectKindSchema).toBe(
+        ConversationSubjectKindSchema,
+      );
+      expect(barrel.CHAT_CONTINUATION_REASONS).toBe(CHAT_CONTINUATION_REASONS);
+      expect(barrel.ChatContinuationReasonSchema).toBe(
+        ChatContinuationReasonSchema,
+      );
+      expect(barrel.ChatContinuitySchema).toBe(ChatContinuitySchema);
+      expect(barrel.LAUNCH_DISPOSITIONS).toBe(LAUNCH_DISPOSITIONS);
+      expect(barrel.LaunchDispositionSchema).toBe(LaunchDispositionSchema);
+      expect(barrel.ResolveLaunchResponseSchema).toBe(
+        ResolveLaunchResponseSchema,
+      );
+      expect(barrel.StartFreshChatResponseSchema).toBe(
+        StartFreshChatResponseSchema,
+      );
+      expect(barrel.LAUNCH_TARGET_SUPERSEDED_CODE).toBe(
+        LAUNCH_TARGET_SUPERSEDED_CODE,
+      );
+      expect(barrel.LaunchTargetSupersededSchema).toBe(
+        LaunchTargetSupersededSchema,
+      );
+    }
+  });
+});
+
+describe("launch dispositions", () => {
+  it("pins the closed disposition vocabulary", () => {
+    expect([...LAUNCH_DISPOSITIONS]).toEqual([
+      "resume-existing-anchor",
+      "resume-and-launch",
+      "created-and-launch",
+    ]);
+    expect(new Set(LAUNCH_DISPOSITIONS).size).toBe(LAUNCH_DISPOSITIONS.length);
+    expect(LaunchDispositionSchema.safeParse("created").success).toBe(false);
+  });
+});
+
+describe("ResolveLaunchResponseSchema", () => {
+  const RESUME = {
+    subjectId: "subj_1",
+    chatId: "chat_1",
+    generation: 1,
+  } as const;
+
+  it("parses both resume dispositions with subject, chat and generation", () => {
+    for (const disposition of [
+      "resume-existing-anchor",
+      "resume-and-launch",
+    ] as const) {
+      expect(
+        ResolveLaunchResponseSchema.parse({ ...RESUME, disposition }),
+      ).toEqual({ ...RESUME, disposition });
+    }
+  });
+
+  it("parses created-and-launch with no chat and no generation", () => {
+    const parsed = ResolveLaunchResponseSchema.parse({
+      subjectId: null,
+      chatId: null,
+      generation: null,
+      disposition: "created-and-launch",
+    });
+    expect(parsed.chatId).toBeNull();
+  });
+
+  it("created-and-launch still reports an existing subject with no active generation", () => {
+    const parsed = ResolveLaunchResponseSchema.parse({
+      subjectId: "subj_1",
+      chatId: null,
+      generation: null,
+      disposition: "created-and-launch",
+    });
+    expect(parsed.subjectId).toBe("subj_1");
+  });
+
+  // Resolve never creates a chat, so a created-and-launch cannot name one.
+  it("created-and-launch with a chat id is rejected", () => {
+    expect(
+      ResolveLaunchResponseSchema.safeParse({
+        subjectId: "subj_1",
+        chatId: "chat_1",
+        generation: null,
+        disposition: "created-and-launch",
+      }).success,
+    ).toBe(false);
+  });
+
+  it("rejects created-and-launch carrying a generation", () => {
+    expect(
+      ResolveLaunchResponseSchema.safeParse({
+        subjectId: "subj_1",
+        chatId: null,
+        generation: 1,
+        disposition: "created-and-launch",
+      }).success,
+    ).toBe(false);
+  });
+
+  it("resume-and-launch without a chat id is rejected", () => {
+    const result = ResolveLaunchResponseSchema.safeParse({
+      ...RESUME,
+      chatId: null,
+      disposition: "resume-and-launch",
+    });
+    expect(result.success).toBe(false);
+    expect(result.error?.issues[0]?.path).toEqual(["chatId"]);
+  });
+
+  it("rejects a resume disposition missing chatId, subjectId or generation", () => {
+    for (const disposition of [
+      "resume-existing-anchor",
+      "resume-and-launch",
+    ] as const) {
+      for (const field of ["chatId", "subjectId", "generation"] as const) {
+        const result = ResolveLaunchResponseSchema.safeParse({
+          ...RESUME,
+          disposition,
+          [field]: null,
+        });
+        expect(result.success).toBe(false);
+        expect(result.error?.issues[0]?.path).toEqual([field]);
+      }
+    }
+  });
+
+  it("requires a positive integer generation", () => {
+    expect(
+      ResolveLaunchResponseSchema.safeParse({
+        ...RESUME,
+        generation: 0,
+        disposition: "resume-and-launch",
+      }).success,
+    ).toBe(false);
+  });
+});
+
+describe("StartFreshChatResponseSchema", () => {
+  const FRESH = {
+    chatId: "chat_2",
+    interactionId: "int_2",
+    subjectId: "subj_1",
+    generation: 2,
+    continuationOf: { chatId: "chat_1" },
+  };
+
+  it("parses the new active generation linked to its predecessor", () => {
+    expect(StartFreshChatResponseSchema.parse(FRESH)).toEqual(FRESH);
+  });
+
+  it("requires the predecessor link", () => {
+    expect(
+      StartFreshChatResponseSchema.safeParse({ ...FRESH, continuationOf: null })
+        .success,
+    ).toBe(false);
+  });
+
+  it("requires a positive integer generation", () => {
+    expect(
+      StartFreshChatResponseSchema.safeParse({ ...FRESH, generation: 0 })
+        .success,
+    ).toBe(false);
+  });
+});
+
+describe("LaunchTargetSupersededSchema", () => {
+  it("pins the 409 code", () => {
+    expect(LAUNCH_TARGET_SUPERSEDED_CODE).toBe("launch_target_superseded");
+  });
+
+  it("a superseded target names the active chat", () => {
+    const body = { code: "launch_target_superseded", activeChatId: "chat_2" };
+    expect(LaunchTargetSupersededSchema.parse(body)).toEqual(body);
+  });
+
+  it("a null activeChatId means start a new chat", () => {
+    expect(
+      LaunchTargetSupersededSchema.parse({
+        code: LAUNCH_TARGET_SUPERSEDED_CODE,
+        activeChatId: null,
+      }).activeChatId,
+    ).toBeNull();
+  });
+
+  it("rejects any other code", () => {
+    expect(
+      LaunchTargetSupersededSchema.safeParse({
+        code: "conflict",
+        activeChatId: null,
+      }).success,
+    ).toBe(false);
+  });
+});

package/src/chat/__tests__/message-mentions.test.ts

@@ -95,6 +95,7 @@ describe("ChatMessageSchema mentions", () => {
         interactionId: "int_1",
         createdAt: "2026-09-02T00:00:00.000Z",
         updatedAt: "2026-09-02T01:00:00.000Z",
+        continuity: null,
       },
       messages: [makeMessage({ mentions: [makeMention()] })],
     });

package/src/chat/__tests__/multi-party.test.ts

@@ -124,6 +124,7 @@ const BASE_DETAIL = {
   interactionId: "int_1",
   createdAt: ISO,
   updatedAt: ISO,
+  continuity: null,
 };
 
 describe("ChatMessageSchema author", () => {

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

@@ -589,6 +589,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 +627,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