@company-semantics/contracts 93.3.0 → 95.0.0

package/src/billing/types.ts

@@ -37,8 +37,13 @@ import type {
   ModelAllowlistSchema,
   OrgBillingOverviewSchema,
   PortalSessionResponseSchema,
+  PriceBookVersionListSchema,
+  PriceBookVersionSummarySchema,
   PriceListModelSchema,
+  PriceListQuerySchema,
+  PriceListRatesSchema,
   PriceListSchema,
+  PriceListTierSchema,
   ProviderKeyListSchema,
   ProviderKeyStatusSchema,
   SpendingControlsSchema,
@@ -151,11 +156,28 @@ export type ProviderKeyStatus = z.infer<typeof ProviderKeyStatusSchema>;
 /** Every provider the org could configure a key for. */
 export type ProviderKeyList = z.infer<typeof ProviderKeyListSchema>;
 
-/** One priced model. Every rate is micro-USD per million tokens. */
+/** One rate set, micro-USD per million tokens; null = no separate rate. */
+export type PriceListRates = z.infer<typeof PriceListRatesSchema>;
+
+/** One tier of one processing mode: reference and hosted rates. */
+export type PriceListTier = z.infer<typeof PriceListTierSchema>;
+
+/** One priced model's card: provenance, aliases and tiers per mode. */
 export type PriceListModel = z.infer<typeof PriceListModelSchema>;
 
 /** The published price book, versioned. */
 export type PriceList = z.infer<typeof PriceListSchema>;
 
+/** The price-list query: an optional version label, else the active one. */
+export type PriceListQuery = z.infer<typeof PriceListQuerySchema>;
+
+/** One published price-book version. */
+export type PriceBookVersionSummary = z.infer<
+  typeof PriceBookVersionSummarySchema
+>;
+
+/** The price book's version history, newest first. */
+export type PriceBookVersionList = z.infer<typeof PriceBookVersionListSchema>;
+
 /** A house-funded org's grant. */
 export type HouseFunding = z.infer<typeof HouseFundingSchema>;

package/src/billing/vocabulary.ts

@@ -332,6 +332,43 @@ export const BILLING_PROVIDERS = [
 export type BillingProvider = (typeof BILLING_PROVIDERS)[number];
 export const BillingProviderSchema = z.enum(BILLING_PROVIDERS);
 
+/**
+ * How a provider processes a request, which selects the rate set it is billed
+ * at. Each mode is an EXPLICIT rate set published by the provider, never a
+ * multiplier we derive: OpenAI's gpt-4o "Fast" is 1.7x Standard, gpt-6-luna's is
+ * 2x, and Anthropic's Batch is 0.5x. "fast" is what OpenAI called "priority"
+ * until 2026-07-30 and what Anthropic calls fast mode.
+ */
+export const PROCESSING_MODES = [
+  /** The provider's default processing. Every priced model has it. */
+  "standard",
+  /** Asynchronous batch processing. */
+  "batch",
+  /** OpenAI Flex: lower price, slower and best-effort capacity. */
+  "flex",
+  /** Premium latency (OpenAI Fast, formerly Priority; Anthropic fast mode). */
+  "fast",
+  /** OpenAI Ultrafast. */
+  "ultrafast",
+] as const;
+export type ProcessingMode = (typeof PROCESSING_MODES)[number];
+export const ProcessingModeSchema = z.enum(PROCESSING_MODES);
+
+/**
+ * What a provider counts to decide which prompt-length tier a request pays.
+ * Anthropic (Claude Haiku 5.5, >100K): every input token, INCLUDING cache reads
+ * and cache writes. A model with more than one tier must name its measure; an
+ * ambiguous provider rule is never guessed (the long tier stays unpublished).
+ */
+export const PROMPT_TIER_MEASURES = [
+  /** input + cache read + cache write. */
+  "input_incl_cache",
+  /** Fresh (uncached) input only. */
+  "input_excl_cache",
+] as const;
+export type PromptTierMeasure = (typeof PROMPT_TIER_MEASURES)[number];
+export const PromptTierMeasureSchema = z.enum(PROMPT_TIER_MEASURES);
+
 /* -------------------------------------------------------------------------- */
 /* Derived tables                                                             */
 /* -------------------------------------------------------------------------- */

package/src/chat/README.md

@@ -55,6 +55,20 @@ A chat can belong to a SUBJECT — the durable case a hand-off to chat is about
 - 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
 
+## Turn on the wire
+
+One turn is one PRESENTATION GROUP whose action row appears once, when the turn settles (control doctrine `chat-action-system`; ADR slug `chat-turn-identity-and-message-actions`).
+
+- `ChatMessage.presentationGroupId`, `turnKind` and `myFeedback` are REQUIRED: null for no group, a kind for every row, null for no rating. They shipped in a MAJOR so no consumer holds a second opinion about a missing key
+- `TURN_KINDS` (`turn-kind.ts`) is CLOSED and append-only. The server derives the kind from what persisted the row; a client never infers it from content. A turn kind is not a principal kind and never changes `author`
+- `myFeedback` is the READER's own rating, per-reader like `myRole`
+- `ChatStreamMessageMetadataSchema` (`stream-metadata.ts`) rides the AI SDK `start` chunk. The live message adopts `messageId`, so a streaming turn already IS the persisted row, already grouped; every field means what the same-named `ChatMessage` field means
+- `messageActionsFor` (`message-actions.ts`) is the ONE eligibility function: the app renders the action row from it and the backend enforces the same function (`isMessageActionAllowed`) on every regenerate, edit and feedback request. Hiding a button is never the boundary
+- `messageActionsFor` is PURE and TOTAL. An unsettled turn offers nothing; input that does not parse offers nothing — unknown is never permissive. Regenerate is offered only on the latest settled `conversation` answer, edit only on the reader's own latest `conversation` prompt
+- Its per-kind table is `satisfies Record<TurnKind, …>`, so a new kind fails to compile until its eligibility is decided
+- Execution actions (cancel, continue, retry, run again) are NOT message actions and are not here — they reach a person as affordances
+- Load order: `turn-kind.ts` is a LEAF (zod only). `schemas.ts`, `stream-metadata.ts` and `message-actions.ts` import it; the latter two never import `schemas.ts`, and `index.ts` re-exports all three directly
+
 <!-- BEGIN GENERATED: readme-public-api — derived from code by `pnpm readme-api`. Do not edit. -->
 
 ## Public API
@@ -114,6 +128,8 @@ A chat can belong to a SUBJECT — the durable case a hand-off to chat is about
 - `ChatRuntimeProfileInfo` _(type)_ — Runtime profile metadata for UI rendering.
 - `ChatSseEvent` _(type)_ — SSE event types for chat updates.
 - `ChatSseEventSchema`
+- `ChatStreamMessageMetadata` _(type)_
+- `ChatStreamMessageMetadataSchema`
 - `ChatSuccessResponse` _(type)_ — Generic mutation success confirmation.
 - `ChatSuccessResponseSchema` — Generic success confirmation for mutations that return no entity data.
 - `ChatSummary` _(type)_ — Lightweight chat summary for list views.
@@ -141,6 +157,11 @@ A chat can belong to a SUBJECT — the durable case a hand-off to chat is about
 - `LaunchDispositionSchema`
 - `LaunchTargetSuperseded` _(type)_
 - `LaunchTargetSupersededSchema` — The 409 body the authoritative launch write returns when the posted chat is not — or can no longer become —…
+- `MESSAGE_ACTION_IDS` — The message and conversation actions a turn's action row can carry.
+- `MessageActionContext` _(type)_
+- `MessageActionContextSchema` — The wire facts eligibility is decided from — all of them known to the app when it draws a turn and to the…
+- `MessageActionId` _(type)_
+- `MessageActionIdSchema`
 - `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 —…
@@ -148,12 +169,17 @@ A chat can belong to a SUBJECT — the durable case a hand-off to chat is about
 - `ResolveLaunchResponseSchema` — Response of the read-only launch resolution.
 - `StartFreshChatResponse` _(type)_
 - `StartFreshChatResponseSchema` — Response of the start-fresh write: the NEW active generation of the subject, linked back to the chat it…
+- `TURN_KINDS` — The kinds of chat turn.
 - `TitleGenerationRequest` _(type)_ — Request to generate a title for a chat.
 - `TitleGenerationResponse` _(type)_ — Response from title generation.
 - `TitleGenerationResponseSchema`
 - `TitleSource` _(type)_ — Title source - tracks how the title was set. - auto: Generated automatically by LLM - manual: Set by user…
 - `TitleSourceSchema`
+- `TurnKind` _(type)_
+- `TurnKindSchema`
 - `UpdateChatParticipantRequest` _(type)_ — Request for PATCH /api/chats/:chatId/participants/:userId — the owner moving someone between Read only and…
+- `isMessageActionAllowed` — Whether `action` is among `messageActionsFor(ctx)` — the backend's check.
+- `messageActionsFor` — The actions a turn offers, in MESSAGEACTIONIDS order. - Input that does not parse (unknown kind, unknown…
 - `recognizeProactiveKind` — Recognize a wire `proactiveKind`.
 
 <!-- END GENERATED: readme-public-api -->

package/src/chat/__tests__/chat-exports.test.ts

@@ -0,0 +1,61 @@
+/**
+ * The turn-on-the-wire vocabulary is reachable from the `./chat` entry
+ * (chat-turn-identity-and-message-actions).
+ *
+ * The backend and the app import these from `@company-semantics/contracts/chat`,
+ * which maps to `src/chat/index.ts`. A symbol that exists in its module but is
+ * missing from the barrel is invisible to every consumer.
+ *
+ * INVARIANTS TESTED:
+ * - TURN_KINDS, ChatStreamMessageMetadataSchema, MESSAGE_ACTION_IDS,
+ *   MessageActionContextSchema, messageActionsFor and isMessageActionAllowed
+ *   are exported from the chat barrel
+ * - messageActionsFor called through the barrel is the same function the
+ *   backend enforces: a settled, latest conversation answer offers regenerate
+ */
+import { describe, expect, it } from "vitest";
+import {
+  ChatStreamMessageMetadataSchema,
+  isMessageActionAllowed,
+  MESSAGE_ACTION_IDS,
+  MessageActionContextSchema,
+  messageActionsFor,
+  TURN_KINDS,
+  TurnKindSchema,
+} from "../index.js";
+
+describe("chat barrel exports the turn on the wire", () => {
+  it("exports the closed vocabularies", () => {
+    expect(TURN_KINDS).toContain("conversation");
+    expect(TurnKindSchema.options).toEqual([...TURN_KINDS]);
+    expect(MESSAGE_ACTION_IDS).toEqual([
+      "copy",
+      "feedback",
+      "regenerate",
+      "edit",
+    ]);
+  });
+
+  it("exports the live-stream metadata schema", () => {
+    const parsed = ChatStreamMessageMetadataSchema.safeParse({
+      messageId: "11111111-1111-4111-8111-111111111111",
+      presentationGroupId: null,
+      turnKind: "conversation",
+      createdAt: "2026-10-09T12:00:00.000Z",
+    });
+    expect(parsed.success).toBe(true);
+  });
+
+  it("calls messageActionsFor through the barrel", () => {
+    const ctx = MessageActionContextSchema.parse({
+      role: "assistant",
+      turnKind: "conversation",
+      settled: true,
+      isLatestOnActiveBranch: true,
+      authoredByReader: false,
+    });
+    expect(messageActionsFor(ctx)).toEqual(["copy", "feedback", "regenerate"]);
+    expect(isMessageActionAllowed(ctx, "regenerate")).toBe(true);
+    expect(isMessageActionAllowed(ctx, "edit")).toBe(false);
+  });
+});

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

@@ -0,0 +1,208 @@
+/**
+ * messageActionsFor — the ONE eligibility decision the app renders from and
+ * the backend enforces (chat-action-system).
+ *
+ * INVARIANTS TESTED:
+ * - One test per row of the doctrine matrix.
+ * - An unsettled turn offers nothing.
+ * - Regenerate is never offered on a launch, settlement or input-request turn.
+ * - Total over TURN_KINDS; an unknown kind or role is never permissive.
+ * - isMessageActionAllowed agrees with messageActionsFor.
+ */
+import { describe, expect, it } from "vitest";
+import {
+  MESSAGE_ACTION_IDS,
+  MessageActionContextSchema,
+  isMessageActionAllowed,
+  messageActionsFor,
+  type MessageActionContext,
+} from "../message-actions.js";
+import { TURN_KINDS } from "../turn-kind.js";
+
+function makeCtx(
+  over: Partial<MessageActionContext> = {},
+): MessageActionContext {
+  return {
+    role: "assistant",
+    turnKind: "conversation",
+    settled: true,
+    isLatestOnActiveBranch: true,
+    authoredByReader: false,
+    ...over,
+  };
+}
+
+describe("MESSAGE_ACTION_IDS", () => {
+  it("names the four message and conversation actions, in order", () => {
+    expect(MESSAGE_ACTION_IDS).toEqual([
+      "copy",
+      "feedback",
+      "regenerate",
+      "edit",
+    ]);
+  });
+});
+
+describe("MessageActionContextSchema", () => {
+  it("accepts a valid context and refuses an unknown turn kind", () => {
+    expect(MessageActionContextSchema.safeParse(makeCtx()).success).toBe(true);
+    expect(
+      MessageActionContextSchema.safeParse({
+        ...makeCtx(),
+        turnKind: "tool_call",
+      }).success,
+    ).toBe(false);
+  });
+});
+
+describe("messageActionsFor", () => {
+  it("an unsettled turn offers nothing", () => {
+    for (const turnKind of TURN_KINDS) {
+      for (const role of ["user", "assistant"] as const) {
+        expect(
+          messageActionsFor(
+            makeCtx({ role, turnKind, settled: false, authoredByReader: true }),
+          ),
+        ).toEqual([]);
+      }
+    }
+  });
+
+  it("a user turn that is latest and the reader's own offers copy and edit", () => {
+    expect(
+      messageActionsFor(makeCtx({ role: "user", authoredByReader: true })),
+    ).toEqual(["copy", "edit"]);
+  });
+
+  it("a user turn that is not latest, or not the reader's own, offers copy only", () => {
+    expect(
+      messageActionsFor(
+        makeCtx({
+          role: "user",
+          authoredByReader: true,
+          isLatestOnActiveBranch: false,
+        }),
+      ),
+    ).toEqual(["copy"]);
+    expect(
+      messageActionsFor(makeCtx({ role: "user", authoredByReader: false })),
+    ).toEqual(["copy"]);
+  });
+
+  it("the latest assistant conversation turn offers copy, feedback and regenerate", () => {
+    expect(messageActionsFor(makeCtx())).toEqual([
+      "copy",
+      "feedback",
+      "regenerate",
+    ]);
+  });
+
+  it("an older assistant conversation turn offers copy and feedback", () => {
+    expect(
+      messageActionsFor(makeCtx({ isLatestOnActiveBranch: false })),
+    ).toEqual(["copy", "feedback"]);
+  });
+
+  it("never offers regenerate on a workflow_launch, workflow_settlement or input_request_launch turn", () => {
+    for (const turnKind of [
+      "workflow_launch",
+      "workflow_settlement",
+      "input_request_launch",
+    ] as const) {
+      for (const isLatestOnActiveBranch of [true, false]) {
+        expect(
+          messageActionsFor(makeCtx({ turnKind, isLatestOnActiveBranch })),
+        ).toEqual(["copy", "feedback"]);
+      }
+    }
+  });
+
+  it("a proactive or refusal turn offers copy only", () => {
+    for (const turnKind of ["proactive", "refusal"] as const) {
+      expect(messageActionsFor(makeCtx({ turnKind }))).toEqual(["copy"]);
+    }
+  });
+
+  it("never offers edit on an assistant turn, nor regenerate on a user turn", () => {
+    for (const turnKind of TURN_KINDS) {
+      expect(
+        messageActionsFor(makeCtx({ turnKind, authoredByReader: true })),
+      ).not.toContain("edit");
+      expect(
+        messageActionsFor(
+          makeCtx({ role: "user", turnKind, authoredByReader: true }),
+        ),
+      ).not.toContain("regenerate");
+    }
+  });
+
+  it("is total: every turn kind and role yields a list of known actions", () => {
+    // `satisfies Record<TurnKind, …>` proves totality at compile time; this
+    // loops the vocabulary at runtime.
+    for (const turnKind of TURN_KINDS) {
+      for (const role of ["user", "assistant"] as const) {
+        const actions = messageActionsFor(makeCtx({ role, turnKind }));
+        expect(actions).toContain("copy");
+        for (const action of actions)
+          expect(MESSAGE_ACTION_IDS).toContain(action);
+      }
+    }
+  });
+
+  it("an unknown turn kind or role offers nothing", () => {
+    const unknownKind = {
+      ...makeCtx(),
+      turnKind: "tool_call",
+    } as unknown as MessageActionContext;
+    const unknownRole = {
+      ...makeCtx(),
+      role: "system",
+    } as unknown as MessageActionContext;
+    const inherited = {
+      ...makeCtx(),
+      turnKind: "toString",
+    } as unknown as MessageActionContext;
+    expect(messageActionsFor(unknownKind)).toEqual([]);
+    expect(messageActionsFor(unknownRole)).toEqual([]);
+    expect(messageActionsFor(inherited)).toEqual([]);
+  });
+
+  it("is pure: the same input yields the same result and the result is a fresh list", () => {
+    const first = messageActionsFor(makeCtx());
+    const second = messageActionsFor(makeCtx());
+    expect(first).toEqual(second);
+    expect(first).not.toBe(second);
+  });
+});
+
+describe("isMessageActionAllowed", () => {
+  it("agrees with messageActionsFor for every kind, role, position and action", () => {
+    for (const turnKind of TURN_KINDS) {
+      for (const role of ["user", "assistant"] as const) {
+        for (const isLatestOnActiveBranch of [true, false]) {
+          const ctx = makeCtx({
+            role,
+            turnKind,
+            isLatestOnActiveBranch,
+            authoredByReader: true,
+          });
+          const offered = messageActionsFor(ctx);
+          for (const action of MESSAGE_ACTION_IDS) {
+            expect(isMessageActionAllowed(ctx, action)).toBe(
+              offered.includes(action),
+            );
+          }
+        }
+      }
+    }
+  });
+
+  it("refuses regenerate on a settled workflow turn the server is asked to regenerate", () => {
+    expect(
+      isMessageActionAllowed(
+        makeCtx({ turnKind: "workflow_settlement" }),
+        "regenerate",
+      ),
+    ).toBe(false);
+  });
+});

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

@@ -54,6 +54,10 @@ const makeMessage = (over: Record<string, unknown> = {}) => ({
   // required-ness itself is pinned in ./multi-party.test.ts; here it is just
   // part of a well-formed message.
   author: userPrincipal("user_1"),
+  // REQUIRED turn identity — pinned in ./turn-wire.test.ts.
+  presentationGroupId: null,
+  turnKind: "conversation" as const,
+  myFeedback: null,
   ...over,
 });
 

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

@@ -53,6 +53,9 @@ const makeMessage = (over: Record<string, unknown> = {}) => ({
   createdAt: ISO,
   mentions: [],
   author: userPrincipal("user_1"),
+  presentationGroupId: null,
+  turnKind: "conversation" as const,
+  myFeedback: null,
   ...over,
 });
 

package/src/chat/__tests__/stream-metadata.test.ts

@@ -0,0 +1,73 @@
+/**
+ * ChatStreamMessageMetadataSchema — the AI SDK `start` chunk metadata
+ * (chat-action-system).
+ *
+ * INVARIANTS TESTED:
+ *   - a valid metadata value round-trips unchanged
+ *   - a null presentation group parses (the turn stands alone)
+ *   - a non-uuid messageId is refused
+ *   - each field is required; an unknown turnKind is refused
+ */
+import { describe, expect, it } from "vitest";
+import {
+  ChatStreamMessageMetadataSchema,
+  type ChatStreamMessageMetadata,
+} from "../stream-metadata.js";
+
+function makeMetadata(
+  over: Partial<Record<keyof ChatStreamMessageMetadata, unknown>> = {},
+): Record<string, unknown> {
+  return {
+    messageId: "6f1c2a3b-4d5e-4f60-8a7b-9c0d1e2f3a4b",
+    presentationGroupId: "0e9d8c7b-6a5f-4e3d-9c2b-1a0f9e8d7c6b",
+    turnKind: "workflow_launch",
+    createdAt: "2026-10-08T12:00:00.000Z",
+    ...over,
+  };
+}
+
+describe("ChatStreamMessageMetadataSchema", () => {
+  it("round-trips a valid metadata value", () => {
+    const value = makeMetadata();
+    expect(ChatStreamMessageMetadataSchema.parse(value)).toEqual(value);
+  });
+
+  it("accepts a null presentationGroupId", () => {
+    const value = makeMetadata({
+      presentationGroupId: null,
+      turnKind: "conversation",
+    });
+    expect(ChatStreamMessageMetadataSchema.parse(value)).toEqual(value);
+  });
+
+  it("refuses a non-uuid messageId", () => {
+    expect(
+      ChatStreamMessageMetadataSchema.safeParse(
+        makeMetadata({ messageId: "msg-1" }),
+      ).success,
+    ).toBe(false);
+  });
+
+  it("refuses a value missing any field", () => {
+    for (const key of [
+      "messageId",
+      "presentationGroupId",
+      "turnKind",
+      "createdAt",
+    ] as const) {
+      const value = makeMetadata();
+      delete value[key];
+      expect(ChatStreamMessageMetadataSchema.safeParse(value).success).toBe(
+        false,
+      );
+    }
+  });
+
+  it("refuses an unknown turnKind", () => {
+    expect(
+      ChatStreamMessageMetadataSchema.safeParse(
+        makeMetadata({ turnKind: "execution" }),
+      ).success,
+    ).toBe(false);
+  });
+});

package/src/chat/__tests__/turn-kind.test.ts

@@ -0,0 +1,34 @@
+/**
+ * TURN_KINDS — the closed vocabulary of chat turn kinds (chat-action-system).
+ *
+ * INVARIANTS TESTED:
+ *   - the union is exactly the six kinds, in declaration order
+ *   - TurnKindSchema accepts every member and refuses anything else
+ */
+import { describe, expect, it } from "vitest";
+import { TURN_KINDS, TurnKindSchema } from "../turn-kind.js";
+
+describe("TURN_KINDS", () => {
+  it("names the six turn kinds, in order", () => {
+    expect(TURN_KINDS).toEqual([
+      "conversation",
+      "workflow_launch",
+      "workflow_settlement",
+      "input_request_launch",
+      "proactive",
+      "refusal",
+    ]);
+  });
+
+  it("TurnKindSchema accepts every member", () => {
+    for (const kind of TURN_KINDS) {
+      expect(TurnKindSchema.parse(kind)).toBe(kind);
+    }
+  });
+
+  it("TurnKindSchema refuses an unknown kind", () => {
+    expect(TurnKindSchema.safeParse("execution").success).toBe(false);
+    expect(TurnKindSchema.safeParse("Conversation").success).toBe(false);
+    expect(TurnKindSchema.safeParse(null).success).toBe(false);
+  });
+});

package/src/chat/__tests__/turn-wire.test.ts

@@ -0,0 +1,93 @@
+/**
+ * The chat turn on the wire (chat-action-system).
+ *
+ * INVARIANTS TESTED:
+ * - `presentationGroupId`, `turnKind` and `myFeedback` are REQUIRED on every
+ *   chat message. Every row has an answer — null for no group, a kind for every
+ *   row, null for no rating — so a missing field is a backend that has not
+ *   adopted this release, and refusing it is the intended failure.
+ * - A null group and a null rating parse: the turn stands alone / is unrated.
+ * - The group is a uuid; anything else is refused.
+ * - `turnKind` is CLOSED: an unknown kind is refused, never passed through.
+ * - `myFeedback` is exactly `up`, `down` or null.
+ */
+import { describe, expect, it } from "vitest";
+import { userPrincipal } from "../../identity/agent";
+import { ChatMessageSchema } from "../schemas.js";
+import { TURN_KINDS } from "../turn-kind.js";
+
+// One well-formed message; every negative case changes exactly ONE field.
+const makeMessage = (over: Record<string, unknown> = {}) => ({
+  id: "msg_1",
+  role: "assistant" as const,
+  content: "Done.",
+  sequenceNumber: 1,
+  createdAt: "2026-10-08T00:00:00.000Z",
+  mentions: [],
+  author: { kind: "agent" as const },
+  presentationGroupId: "3f2b8c1e-6d4a-4f7b-9a2e-1c5d8e9f0a1b",
+  turnKind: "workflow_settlement" as const,
+  myFeedback: "up" as const,
+  ...over,
+});
+
+const without = (key: string) => {
+  const message: Record<string, unknown> = makeMessage();
+  delete message[key];
+  return message;
+};
+
+describe("ChatMessageSchema turn identity", () => {
+  it("accepts a well-formed grouped, rated turn", () => {
+    expect(ChatMessageSchema.safeParse(makeMessage()).success).toBe(true);
+  });
+
+  it("refuses a message without presentationGroupId, turnKind or myFeedback", () => {
+    for (const key of ["presentationGroupId", "turnKind", "myFeedback"]) {
+      expect(ChatMessageSchema.safeParse(without(key)).success).toBe(false);
+    }
+  });
+
+  it("parses a null group and a null rating", () => {
+    const parsed = ChatMessageSchema.parse(
+      makeMessage({
+        role: "user",
+        author: userPrincipal("user_1"),
+        presentationGroupId: null,
+        turnKind: "conversation",
+        myFeedback: null,
+      }),
+    );
+    expect(parsed.presentationGroupId).toBeNull();
+    expect(parsed.myFeedback).toBeNull();
+  });
+
+  it("accepts every turn kind", () => {
+    for (const turnKind of TURN_KINDS) {
+      expect(
+        ChatMessageSchema.safeParse(makeMessage({ turnKind })).success,
+      ).toBe(true);
+    }
+  });
+
+  it("refuses an unknown turnKind", () => {
+    expect(
+      ChatMessageSchema.safeParse(makeMessage({ turnKind: "workflow" }))
+        .success,
+    ).toBe(false);
+  });
+
+  it("refuses a non-uuid presentationGroupId", () => {
+    expect(
+      ChatMessageSchema.safeParse(makeMessage({ presentationGroupId: "run_1" }))
+        .success,
+    ).toBe(false);
+  });
+
+  it("refuses a rating other than up, down or null", () => {
+    expect(
+      ChatMessageSchema.safeParse(makeMessage({ myFeedback: "neutral" }))
+        .success,
+    ).toBe(false);
+  });
+});

package/src/chat/index.ts

@@ -138,6 +138,23 @@ export {
   LaunchTargetSupersededSchema,
 } from "./continuity";
 
+// The turn on the wire (chat-turn-identity-and-message-actions): the closed
+// turn-kind vocabulary, the live-stream message metadata for the AI SDK start
+// chunk, and the one pure eligibility function the app renders from and the
+// backend enforces (doctrine: chat-action-system)
+export type { TurnKind } from "./turn-kind";
+export { TURN_KINDS, TurnKindSchema } from "./turn-kind";
+export type { ChatStreamMessageMetadata } from "./stream-metadata";
+export { ChatStreamMessageMetadataSchema } from "./stream-metadata";
+export type { MessageActionId, MessageActionContext } from "./message-actions";
+export {
+  MESSAGE_ACTION_IDS,
+  MessageActionIdSchema,
+  MessageActionContextSchema,
+  messageActionsFor,
+  isMessageActionAllowed,
+} from "./message-actions";
+
 // Runtime profile types and constants
 export type {
   ChatRuntimeProfile,