@company-semantics/contracts 93.3.0 → 95.0.0

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>;