@company-semantics/contracts 93.3.0 → 94.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@company-semantics/contracts",
-  "version": "93.3.0",
+  "version": "94.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 = '694bbd340597' as const;
-export const SPEC_HASH_FULL = '694bbd3405976ed940683994c167242174ad628748e5694fc6f138ccd4802cee' as const;
+export const SPEC_HASH = '826e3d4d23ef' as const;
+export const SPEC_HASH_FULL = '826e3d4d23ef986d25b22b32497686755ce2b9bebc0ad90efd7768b4e1e076de' as const;

package/src/api/generated.ts

@@ -5569,6 +5569,10 @@ export interface components {
                     requestId: string;
                     questionId: string;
                 };
+                presentationGroupId: string | null;
+                /** @enum {string} */
+                turnKind: "conversation" | "workflow_launch" | "workflow_settlement" | "input_request_launch" | "proactive" | "refusal";
+                myFeedback: ("up" | "down") | null;
             }[];
         };
         SuccessResponse: {

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,

package/src/chat/message-actions.ts

@@ -0,0 +1,143 @@
+/**
+ * Chat message action eligibility (chat-action-system).
+ *
+ * Which MESSAGE actions (copy, feedback) and CONVERSATION actions (regenerate,
+ * edit) a chat turn offers is decided by ONE pure function over wire facts:
+ * the turn's role, its TurnKind and its position. The app renders the action
+ * row from `messageActionsFor`; the backend enforces the SAME function on every
+ * regenerate, edit and feedback request. Hiding a button is never the security
+ * boundary.
+ *
+ * Execution actions (Cancel, Continue, Retry operation, Run again) are NOT
+ * here: they act on durable work, not on a message, and reach a person as
+ * affordances from the closed catalog (affordance-system).
+ *
+ * INVARIANTS:
+ * - PURE and TOTAL: no I/O, no clock, no defaults. Every input yields a list.
+ * - An unsettled turn offers NOTHING — the row appears once, when it settles.
+ * - Regenerate is never offered on a workflow_launch, workflow_settlement,
+ *   input_request_launch, proactive or refusal turn: it would ask the model for
+ *   new prose without re-running the work.
+ * - Regenerate and edit are offered only on the latest turn of the active
+ *   branch; edit only to the reader who authored it.
+ * - An input the schema does not recognize (an unknown kind or role) offers
+ *   NOTHING. Unknown is never permissive.
+ *
+ * LOAD ORDER: imports only zod and `./turn-kind` (a leaf); never `./schemas`.
+ */
+
+import { z } from "zod";
+import { TurnKindSchema, type TurnKind } from "./turn-kind";
+
+/**
+ * The message and conversation actions a turn's action row can carry. CLOSED
+ * and append-only. The order is the order the row draws them in, and the
+ * order `messageActionsFor` returns them in.
+ */
+export const MESSAGE_ACTION_IDS = [
+  /** Copy the turn's readable prose. Side-effect-free. */
+  "copy",
+  /** Rate the turn up or down. Measures a message; never approves anything. */
+  "feedback",
+  /** A new answer to the same request; supersedes the old one. Never re-runs work. */
+  "regenerate",
+  /** Rewrite the reader's own prompt; supersedes the branch after it. */
+  "edit",
+] as const;
+
+export const MessageActionIdSchema = z.enum(MESSAGE_ACTION_IDS);
+export type MessageActionId = z.infer<typeof MessageActionIdSchema>;
+
+/**
+ * The wire facts eligibility is decided from — all of them known to the app
+ * when it draws a turn and to the backend when it receives a request.
+ */
+export const MessageActionContextSchema = z.object({
+  role: z.enum(["user", "assistant"]),
+  turnKind: TurnKindSchema,
+  /**
+   * The turn is done: not streaming, and no launched workflow behind it is in
+   * flight or awaiting settlement delivery.
+   */
+  settled: z.boolean(),
+  /** The turn is the latest of its role on the active branch. */
+  isLatestOnActiveBranch: z.boolean(),
+  /** The reader is the turn's author (a user turn they wrote). */
+  authoredByReader: z.boolean(),
+});
+export type MessageActionContext = z.infer<typeof MessageActionContextSchema>;
+
+/** `always` is offered on every settled turn; `latest` only on the latest. */
+type ActionRule = {
+  always: readonly MessageActionId[];
+  latest: readonly MessageActionId[];
+};
+
+/**
+ * The eligibility table. `satisfies Record<TurnKind, …>` makes a new TurnKind a
+ * compile error here until its eligibility is decided. Only a conversation
+ * turn is a request/answer pair, so only it offers regenerate or edit; a user
+ * row of any other kind (none exists today) is copy-only.
+ */
+const TURN_ACTIONS = {
+  conversation: {
+    user: { always: ["copy"], latest: ["edit"] },
+    assistant: { always: ["copy", "feedback"], latest: ["regenerate"] },
+  },
+  workflow_launch: {
+    user: { always: ["copy"], latest: [] },
+    assistant: { always: ["copy", "feedback"], latest: [] },
+  },
+  workflow_settlement: {
+    user: { always: ["copy"], latest: [] },
+    assistant: { always: ["copy", "feedback"], latest: [] },
+  },
+  input_request_launch: {
+    user: { always: ["copy"], latest: [] },
+    assistant: { always: ["copy", "feedback"], latest: [] },
+  },
+  proactive: {
+    user: { always: ["copy"], latest: [] },
+    assistant: { always: ["copy"], latest: [] },
+  },
+  refusal: {
+    user: { always: ["copy"], latest: [] },
+    assistant: { always: ["copy"], latest: [] },
+  },
+} as const satisfies Record<
+  TurnKind,
+  Record<MessageActionContext["role"], ActionRule>
+>;
+
+/**
+ * The actions a turn offers, in MESSAGE_ACTION_IDS order.
+ *
+ * - Input that does not parse (unknown kind, unknown role) → [].
+ * - Not settled → [].
+ * - User turn → its `always`, plus `latest` iff latest on the active branch
+ *   AND authored by the reader.
+ * - Assistant turn → its `always`, plus `latest` iff latest on the active
+ *   branch.
+ */
+export function messageActionsFor(
+  ctx: MessageActionContext,
+): readonly MessageActionId[] {
+  const parsed = MessageActionContextSchema.safeParse(ctx);
+  if (!parsed.success || !parsed.data.settled) return [];
+  const { role, turnKind, isLatestOnActiveBranch, authoredByReader } =
+    parsed.data;
+  const rule: ActionRule = TURN_ACTIONS[turnKind][role];
+  const latest =
+    role === "user"
+      ? isLatestOnActiveBranch && authoredByReader
+      : isLatestOnActiveBranch;
+  return latest ? [...rule.always, ...rule.latest] : [...rule.always];
+}
+
+/** Whether `action` is among `messageActionsFor(ctx)` — the backend's check. */
+export function isMessageActionAllowed(
+  ctx: MessageActionContext,
+  action: MessageActionId,
+): boolean {
+  return messageActionsFor(ctx).includes(action);
+}

package/src/chat/schemas.ts

@@ -25,6 +25,7 @@ import {
   proactiveChatFields,
   TitleSourceSchema,
 } from "./enums";
+import { TurnKindSchema } from "./turn-kind";
 
 // The chat vocabulary and the SSE event contract, re-exported so this module
 // stays the single import site for every chat schema.
@@ -285,6 +286,35 @@ export const ChatMessageSchema = z.object({
    *
    */
   discussionScope: ChatDiscussionScopeSchema.optional(),
+
+  /**
+   * The PRESENTATION GROUP this turn belongs to: every row of one launched
+   * piece of work draws as ONE response, with one action row
+   * (chat-action-system). REQUIRED, and null means the turn stands alone —
+   * every row has an answer, so there is no absence to make optional.
+   *
+   * A group is a SEPARATE CONCEPT FROM THE WORKFLOW it may name
+   * (INV-LAUNCHTURN-2): it is a presentation fact, never a workflow or run id,
+   * and a client must not join on it as one. The settlement row and the review
+   * hand-off INHERIT the anchor's group, so a launch, its settlement and its
+   * hand-off render together. Superseded rows are never on this wire — the
+   * transcript carries the active branch only.
+   */
+  presentationGroupId: z.string().uuid().nullable(),
+
+  /**
+   * What KIND of turn this row is — derived by the server from what persisted
+   * it, never inferred by a client from content. REQUIRED: every row is exactly
+   * one kind. Not a principal kind; `author` is unchanged by it.
+   */
+  turnKind: TurnKindSchema,
+
+  /**
+   * The READER's current rating of this turn — the person this response was
+   * projected for, never an aggregate of other participants. REQUIRED so a
+   * reload restores the rating; null on user turns and on unrated turns.
+   */
+  myFeedback: z.enum(["up", "down"]).nullable(),
 });
 
 // =============================================================================

package/src/chat/stream-metadata.ts

@@ -0,0 +1,40 @@
+/**
+ * Live-stream message metadata (chat-action-system).
+ *
+ * The `messageMetadata` the backend attaches to the AI SDK `start` chunk of a
+ * streamed assistant turn. It exists so a LIVE message is already the
+ * persisted message: the app adopts `messageId` as the live message's id, so
+ * the live message's id IS the persisted row id (doctrine rule 10), and it
+ * carries its presentation group and turn kind before any reload. Without
+ * it, a client could only draw a live turn as a loose message and regroup it
+ * after the next fetch — the flicker the presentation group exists to end.
+ *
+ * Every field mirrors the same-named field on `ChatMessage`, with the same
+ * meaning: a client that reads the live metadata and later reloads the
+ * transcript sees the same id, group, kind and timestamp.
+ *
+ * LOAD ORDER: imports only zod, `../api/primitives` and the `./turn-kind`
+ * leaf. It must NEVER import `./schemas`.
+ */
+
+import { z } from "zod";
+import { IsoDateTime } from "../api/primitives";
+import { TurnKindSchema } from "./turn-kind";
+
+export const ChatStreamMessageMetadataSchema = z.object({
+  /** The persisted row id of this message — the live message adopts it. */
+  messageId: z.string().uuid(),
+  /**
+   * The presentation group this turn joins; null when it stands alone.
+   * REQUIRED, exactly as on `ChatMessage` — every turn has an answer.
+   */
+  presentationGroupId: z.string().uuid().nullable(),
+  /** What kind of turn this is, derived by the server. REQUIRED. */
+  turnKind: TurnKindSchema,
+  /** The persisted row's creation time, so the live turn orders as it will on reload. */
+  createdAt: IsoDateTime,
+});
+
+export type ChatStreamMessageMetadata = z.infer<
+  typeof ChatStreamMessageMetadataSchema
+>;

package/src/chat/turn-kind.ts

@@ -0,0 +1,43 @@
+/**
+ * Chat turn kind (chat-action-system).
+ *
+ * Every chat message row is exactly one KIND of turn. The kind is a wire
+ * fact the server derives from what persisted the row — never something a
+ * client infers from content — so a client can decide how to draw a turn
+ * and which message actions it offers from the wire alone.
+ *
+ * A turn kind is NOT a principal kind: it never changes who authored the
+ * row (`author` stays a PrincipalRef), and it is not the presentation group
+ * — a group is a separate concept from the workflow it may name.
+ *
+ * LOAD ORDER: this module is a LEAF. It imports only zod and must NEVER
+ * import `./schemas` (or any module that does) — `./schemas`,
+ * `./stream-metadata` and `./message-actions` all import this file, and the
+ * reverse edge would reach its declarations in the temporal dead zone.
+ */
+
+import { z } from "zod";
+
+/**
+ * The kinds of chat turn. CLOSED and append-only: a new kind is a new
+ * eligibility decision, and every `Record<TurnKind, …>` table must fail to
+ * compile until that decision is made. Each kind is defined by the
+ * persisted fact that produces it.
+ */
+export const TURN_KINDS = [
+  /** A user turn, or a model-authored answer to one — no launch behind it. */
+  "conversation",
+  /** A launch-only anchor whose launch kind names a workflow. */
+  "workflow_launch",
+  /** A settlement row: its launch identity carries the `workflow-settled:` prefix. */
+  "workflow_settlement",
+  /** A launch-only anchor whose launch kind names an input request. */
+  "input_request_launch",
+  /** An opener written by the ProactiveChatWriter, not in reply to a turn. */
+  "proactive",
+  /** The row recording a launch the server refused. */
+  "refusal",
+] as const;
+
+export const TurnKindSchema = z.enum(TURN_KINDS);
+export type TurnKind = z.infer<typeof TurnKindSchema>;