@company-semantics/contracts 97.0.0 → 99.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@company-semantics/contracts",
-  "version": "97.0.0",
+  "version": "99.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 = 'f571d3d78c72' as const;
-export const SPEC_HASH_FULL = 'f571d3d78c720d7ad11592b2d490a723c48c539d162c41a6dd77f67bb6ad922f' as const;
+export const SPEC_HASH = '935ee995d53d' as const;
+export const SPEC_HASH_FULL = '935ee995d53d56538f0566bb3c1372041d5cb1def41f3b28db02716ad4d8c591' as const;

package/src/api/generated.ts

@@ -421,6 +421,23 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/api/chats/{id}/branch": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /** Make one version of a turn the active branch */
+        post: operations["selectChatBranch"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/api/chats/{id}/pin": {
         parameters: {
             query?: never;
@@ -1712,7 +1729,7 @@ export interface paths {
         };
         /**
          * Read one analysis workflow’s generic lifecycle envelope
-         * @description The domain-agnostic projection a client polls: identity, registered type, activity-free lifecycle state, start and completion times, the opaque domain progress and result payloads (null until the domain adapter supplies them), a closed failure class on a failed workflow, the frozen typed outcome of the current execution epoch once it settles (null until then), the execution affordances offered now (the contracts offer table over state, the type’s execution support and the frozen outcome, filtered by the viewer’s policy), the workflow it was relaunched from, the current execution epoch’s start and completion times, and the legacy capabilities (canStop, canContinue) kept until their consumers move. Org-scoped: a workflow in another workspace answers 404.
+         * @description The domain-agnostic projection a client polls: identity, registered type, activity-free lifecycle state, start and completion times, the opaque domain progress and result payloads (null until the domain adapter supplies them), a closed failure class on a failed workflow, the frozen typed outcome of the current execution epoch once it settles (null until then), the execution affordances offered now (the contracts offer table over state, the type’s execution support and the frozen outcome, filtered by the viewer’s policy), the workflow it was relaunched from, and the current execution epoch’s start and completion times. Org-scoped: a workflow in another workspace answers 404.
          */
         get: operations["getAnalysisWorkflow"];
         put?: never;
@@ -5652,7 +5669,16 @@ export interface components {
                 presentationGroupId: string | null;
                 /** @enum {string} */
                 turnKind: "conversation" | "workflow_launch" | "workflow_settlement" | "input_request_launch" | "proactive" | "refusal";
-                myFeedback: ("up" | "down") | null;
+                alternatives: {
+                    position: number;
+                    total: number;
+                    ids: string[];
+                } | null;
+                myFeedback: {
+                    /** @enum {string} */
+                    rating: "up" | "down";
+                    reason: ("incorrect" | "didnt_follow_instructions" | "not_helpful" | "missing_context" | "tool_or_workflow_issue" | "other") | null;
+                } | null;
             }[];
         };
         SuccessResponse: {
@@ -5710,6 +5736,10 @@ export interface components {
             title: string;
             isAutoGenerated: boolean;
         };
+        ChatBranchSelectRequest: {
+            /** Format: uuid */
+            messageId: string;
+        };
         ChatSseEvent: {
             /** @constant */
             v: 1;
@@ -5978,14 +6008,16 @@ export interface components {
         ChatMessageFeedbackResponse: {
             /** @enum {string} */
             rating: "up" | "down";
-            reason: string | null;
+            reason: ("incorrect" | "didnt_follow_instructions" | "not_helpful" | "missing_context" | "tool_or_workflow_issue" | "other") | null;
             /** Format: date-time */
             updatedAt: string;
         };
         PutChatMessageFeedbackRequest: {
             /** @enum {string} */
             rating: "up" | "down";
-            reason?: string;
+            /** @enum {string} */
+            reason?: "incorrect" | "didnt_follow_instructions" | "not_helpful" | "missing_context" | "tool_or_workflow_issue" | "other";
+            comment?: string;
         };
         WorkspaceAccessResponse: {
             hasAccess: boolean;
@@ -7756,10 +7788,6 @@ export interface components {
                 })[];
             }) | null;
             error?: string;
-            capabilities: {
-                canStop: boolean;
-                canContinue: boolean;
-            };
             executionAffordances: ({
                 /** @constant */
                 id: "workflow.stop";
@@ -12458,6 +12486,32 @@ export interface operations {
             };
         };
     };
+    selectChatBranch: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                id: string;
+            };
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["ChatBranchSelectRequest"];
+            };
+        };
+        responses: {
+            /** @description The chat with its new active branch */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["GetChatResponse"];
+                };
+            };
+        };
+    };
     pinChat: {
         parameters: {
             query?: never;

package/src/chat/README.md

@@ -59,16 +59,30 @@ A chat can belong to a SUBJECT — the durable case a hand-off to chat is about
 
 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
+- `ChatMessage.presentationGroupId`, `turnKind` and `myFeedback` are REQUIRED: null for no group, a kind for every row, null for no rating (otherwise `{ rating, reason }` — see "Versions and feedback"). 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
+- `messageActionsFor` is PURE and TOTAL. An unsettled turn offers nothing; input that does not parse offers nothing — unknown is never permissive. Regenerate is offered on ANY settled `conversation` answer and edit on ANY settled `conversation` prompt the reader authored — not only the latest: both add a sibling version (a branch) and never delete. `isLatestOnActiveBranch` stays on the context but gates nothing. Launch, settlement, input-request, proactive and refusal turns never offer regenerate
 - 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
 
+## Versions and feedback
+
+Regenerating an answer or editing a prompt ADDS A SIBLING VERSION of the turn — a branch in a message tree with an active leaf — and never deletes anything; a reader's rating of a turn carries a CLOSED reason (ADR slug `response-versions-and-feedback-reasons`).
+
+- `ChatMessage.alternatives` is REQUIRED and NULLABLE: null means the turn has no siblings. Otherwise `{ position, total, ids }` — `position` is 1-based, `ids` lists every sibling (this one included) ORDERED BY CREATION, and the schema refuses `ids.length !== total` or `position > total`, so a client never reconciles fields that disagree
+- The transcript carries the ACTIVE branch only. Other versions are reachable by id, never inlined
+- `ChatBranchSelectRequestSchema` (`{ messageId }`) is the body that makes one sibling the active branch. Naming an id is a lookup, not authority — the server re-checks it is a version of a turn in this chat
+- `FEEDBACK_RATINGS` is `up` / `down`. `FEEDBACK_REASONS` (`feedback.ts`) is CLOSED and append-only: a reason is a category the product can count, and free text belongs in `comment` (at most `FEEDBACK_COMMENT_MAX` = 2000 characters), never in a reason
+- `PutChatMessageFeedbackRequestSchema` is the body of `putChatMessageFeedback`, named after the generated operation's component so the backend can replace its route-local schema of the same name. A reason or a comment rides only a `down` rating; the schema refuses either on `up`. It is a deliberate exception to "request schemas live in backend": the closed reason list is shared vocabulary the app's picker and the backend's check must agree on
+- `ChatMessage.myFeedback` is `{ rating, reason } | null` — the READER's own rating; `reason` is null on an up rating and on a down rating given without one. The comment is write-only and never projected back onto the transcript
+- Feedback MEASURES a turn. It is NOT APPROVAL of anything the turn proposed, and never authorizes, confirms or executes
+- Load order: `feedback.ts` is a LEAF (zod only). `schemas.ts` imports it, it never imports `schemas.ts`, and `index.ts` re-exports it directly
+- `openapi/backend.yaml` deliberately lags (contracts-first): its `ChatMessage` has no `alternatives`, its `myFeedback` is a bare rating, and its feedback `reason` is free text. It catches up when the backend regenerates its spec
+
 <!-- BEGIN GENERATED: readme-public-api — derived from code by `pnpm readme-api`. Do not edit. -->
 
 ## Public API
@@ -83,6 +97,8 @@ One turn is one PRESENTATION GROUP whose action row appears once, when the turn
 - `CHAT_PAGE_VIEWS` — The app route parser's fifteen `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.
+- `ChatBranchSelectRequest` _(type)_ — Request body that makes one sibling version the active branch.
+- `ChatBranchSelectRequestSchema` — Request body that makes one version the active branch (response-versions-and-feedback-reasons).
 - `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.
@@ -111,8 +127,12 @@ One turn is one PRESENTATION GROUP whose action row appears once, when the turn
 - `ChatMentionableResponse` _(type)_ — Response for the chat composer's mentionable-candidate endpoint.
 - `ChatMentionableResponseSchema` — Who the chat composer may offer as a mention target.
 - `ChatMessage` _(type)_ — Individual message in a chat response (GET /api/chats/:id).
+- `ChatMessageAlternatives` _(type)_ — The sibling versions of one turn — 1-based `position`, `total`, and every sibling id ordered by creation…
+- `ChatMessageAlternativesSchema` — The VERSIONS of one turn (response-versions-and-feedback-reasons, ).
 - `ChatMessageMention` _(type)_ — One mention on a chat turn — a `PrincipalRef` target, a nullable UTF-16 code-unit range into `content`, and a…
 - `ChatMessageMentionSchema` — ONE mention on a chat turn — field-for-field `CommentMentionSchema` (`../comments/schemas`), and deliberately…
+- `ChatMessageMyFeedback` _(type)_
+- `ChatMessageMyFeedbackSchema` — The reader's own rating as `ChatMessage.myFeedback` carries it.
 - `ChatMessageSchema`
 - `ChatOrigin` _(type)_ — How a chat was born: `user` or `proactive` (the system spoke first).
 - `ChatOriginSchema` — How a chat was born: by the user, or by the system speaking first (a proactive occurrence projected onto the…
@@ -143,6 +163,13 @@ One turn is one PRESENTATION GROUP whose action row appears once, when the turn
 - `CreateChatResponse` _(type)_ — Response for POST /api/chats
 - `CreateChatResponseSchema` — Response for POST /api/chats
 - `DEFAULT_CHAT_RUNTIME_PROFILE` — Default profile when none is specified in the request.
+- `FEEDBACK_COMMENT_MAX` — Longest free-text comment a down rating may carry.
+- `FEEDBACK_RATINGS` — The two ratings a reader can give a turn.
+- `FEEDBACK_REASONS` — Why a reader rated a turn down.
+- `FeedbackRating` _(type)_
+- `FeedbackRatingSchema`
+- `FeedbackReason` _(type)_
+- `FeedbackReasonSchema`
 - `GetChatResponse` _(type)_ — Response for GET /api/chats/:id
 - `GetChatResponseSchema` — Response for GET /api/chats/:id
 - `InvalidateChatEvent` _(type)_ — Single-entity staleness signal.
@@ -164,6 +191,8 @@ One turn is one PRESENTATION GROUP whose action row appears once, when the turn
 - `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).
+- `PutChatMessageFeedbackRequest` _(type)_
+- `PutChatMessageFeedbackRequestSchema` — Body of PUT /api/chats/{id}/messages/{messageId}/feedback (operationId putChatMessageFeedback).
 - `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.

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

@@ -0,0 +1,121 @@
+/**
+ * The sibling versions of one turn (response-versions-and-feedback-reasons,
+ * ADR-CONTRACTS-228).
+ *
+ * INVARIANTS TESTED:
+ * - `ChatMessage.alternatives` is null (no siblings) or a version position
+ *   within the ordered sibling ids.
+ * - `ids` are uuids, `ids.length === total` and `1 <= position <= total`.
+ * - The branch-select request names one sibling by uuid `messageId`.
+ * - Both schemas and their types are reachable from the `./chat` barrel.
+ */
+import { describe, expect, it } from "vitest";
+import {
+  ChatBranchSelectRequestSchema,
+  ChatMessageAlternativesSchema,
+  ChatMessageSchema,
+} from "../schemas.js";
+import type {
+  ChatBranchSelectRequest,
+  ChatMessageAlternatives,
+} from "../index.js";
+import * as barrel from "../index.js";
+
+const A = "11111111-1111-4111-8111-111111111111";
+const B = "22222222-2222-4222-8222-222222222222";
+
+const makeMessage = (alternatives: 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: null,
+  turnKind: "conversation" as const,
+  alternatives,
+  myFeedback: null,
+});
+
+describe("ChatMessageAlternativesSchema", () => {
+  it("parses null alternatives on a message: the turn has no siblings", () => {
+    expect(ChatMessageSchema.parse(makeMessage(null)).alternatives).toBeNull();
+  });
+
+  it("accepts a version position within ordered sibling ids", () => {
+    const alternatives: ChatMessageAlternatives = {
+      position: 2,
+      total: 2,
+      ids: [A, B],
+    };
+    expect(
+      ChatMessageSchema.parse(makeMessage(alternatives)).alternatives,
+    ).toEqual(alternatives);
+  });
+
+  it("refuses ids whose length disagrees with total", () => {
+    expect(
+      ChatMessageAlternativesSchema.safeParse({
+        position: 1,
+        total: 3,
+        ids: [A, B],
+      }).success,
+    ).toBe(false);
+  });
+
+  it("refuses a position beyond total", () => {
+    expect(
+      ChatMessageAlternativesSchema.safeParse({
+        position: 3,
+        total: 2,
+        ids: [A, B],
+      }).success,
+    ).toBe(false);
+  });
+
+  it("refuses a position below 1", () => {
+    expect(
+      ChatMessageAlternativesSchema.safeParse({
+        position: 0,
+        total: 2,
+        ids: [A, B],
+      }).success,
+    ).toBe(false);
+  });
+
+  it("refuses a non-uuid sibling id", () => {
+    expect(
+      ChatMessageAlternativesSchema.safeParse({
+        position: 1,
+        total: 1,
+        ids: ["msg_1"],
+      }).success,
+    ).toBe(false);
+  });
+});
+
+describe("ChatBranchSelectRequestSchema", () => {
+  it("accepts a uuid messageId", () => {
+    const body: ChatBranchSelectRequest = { messageId: A };
+    expect(ChatBranchSelectRequestSchema.safeParse(body).success).toBe(true);
+  });
+
+  it("refuses a missing or non-uuid messageId", () => {
+    expect(ChatBranchSelectRequestSchema.safeParse({}).success).toBe(false);
+    expect(
+      ChatBranchSelectRequestSchema.safeParse({ messageId: "msg_1" }).success,
+    ).toBe(false);
+  });
+});
+
+describe("chat barrel exports the alternatives vocabulary", () => {
+  it("re-exports the same schemas the module defines", () => {
+    expect(barrel.ChatMessageAlternativesSchema).toBe(
+      ChatMessageAlternativesSchema,
+    );
+    expect(barrel.ChatBranchSelectRequestSchema).toBe(
+      ChatBranchSelectRequestSchema,
+    );
+  });
+});

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

@@ -11,19 +11,37 @@
  *   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
+ *   backend enforces: a settled conversation answer offers regenerate, latest
+ *   or not
+ * - The versions and feedback vocabulary (response-versions-and-feedback-reasons)
+ *   is exported from the chat barrel: ChatMessageAlternativesSchema,
+ *   ChatBranchSelectRequestSchema, FEEDBACK_RATINGS, FeedbackRatingSchema,
+ *   FEEDBACK_REASONS, FeedbackReasonSchema, FEEDBACK_COMMENT_MAX (2000),
+ *   PutChatMessageFeedbackRequestSchema and ChatMessageMyFeedbackSchema
  */
 import { describe, expect, it } from "vitest";
 import {
+  ChatBranchSelectRequestSchema,
+  ChatMessageAlternativesSchema,
+  ChatMessageMyFeedbackSchema,
   ChatStreamMessageMetadataSchema,
+  FEEDBACK_COMMENT_MAX,
+  FEEDBACK_RATINGS,
+  FEEDBACK_REASONS,
+  FeedbackRatingSchema,
+  FeedbackReasonSchema,
   isMessageActionAllowed,
   MESSAGE_ACTION_IDS,
   MessageActionContextSchema,
   messageActionsFor,
+  PutChatMessageFeedbackRequestSchema,
   TURN_KINDS,
   TurnKindSchema,
 } from "../index.js";
 
+const ID_A = "11111111-1111-4111-8111-111111111111";
+const ID_B = "22222222-2222-4222-8222-222222222222";
+
 describe("chat barrel exports the turn on the wire", () => {
   it("exports the closed vocabularies", () => {
     expect(TURN_KINDS).toContain("conversation");
@@ -58,4 +76,58 @@ describe("chat barrel exports the turn on the wire", () => {
     expect(isMessageActionAllowed(ctx, "regenerate")).toBe(true);
     expect(isMessageActionAllowed(ctx, "edit")).toBe(false);
   });
+
+  it("offers regenerate on an older answer through the barrel", () => {
+    const ctx = MessageActionContextSchema.parse({
+      role: "assistant",
+      turnKind: "conversation",
+      settled: true,
+      isLatestOnActiveBranch: false,
+      authoredByReader: false,
+    });
+    expect(isMessageActionAllowed(ctx, "regenerate")).toBe(true);
+  });
+});
+
+describe("chat barrel exports the versions and feedback vocabulary", () => {
+  it("exports the alternatives and branch-select schemas", () => {
+    expect(
+      ChatMessageAlternativesSchema.safeParse({
+        position: 2,
+        total: 2,
+        ids: [ID_A, ID_B],
+      }).success,
+    ).toBe(true);
+    expect(
+      ChatBranchSelectRequestSchema.safeParse({ messageId: ID_B }).success,
+    ).toBe(true);
+  });
+
+  it("exports the closed feedback vocabularies", () => {
+    expect(FEEDBACK_RATINGS).toEqual(["up", "down"]);
+    expect(FeedbackRatingSchema.options).toEqual([...FEEDBACK_RATINGS]);
+    expect(FEEDBACK_REASONS).toContain("other");
+    expect(FeedbackReasonSchema.options).toEqual([...FEEDBACK_REASONS]);
+    expect(FEEDBACK_COMMENT_MAX).toBe(2000);
+  });
+
+  it("exports the feedback request and myFeedback schemas", () => {
+    expect(
+      PutChatMessageFeedbackRequestSchema.safeParse({
+        rating: "down",
+        reason: "incorrect",
+        comment: "wrong date",
+      }).success,
+    ).toBe(true);
+    expect(
+      PutChatMessageFeedbackRequestSchema.safeParse({
+        rating: "up",
+        reason: "incorrect",
+      }).success,
+    ).toBe(false);
+    expect(
+      ChatMessageMyFeedbackSchema.safeParse({ rating: "up", reason: null })
+        .success,
+    ).toBe(true);
+  });
 });

package/src/chat/__tests__/feedback-reasons.test.ts

@@ -0,0 +1,99 @@
+/**
+ * Chat message feedback (response-versions-and-feedback-reasons).
+ *
+ * INVARIANTS TESTED:
+ * - A reason or a comment rides only a "down" rating; an up rating carrying
+ *   either is refused.
+ * - A comment is at most FEEDBACK_COMMENT_MAX (2000) characters.
+ * - FEEDBACK_REASONS is CLOSED: a reason outside it is refused.
+ * - ChatMessageMyFeedback is `{ rating, reason }` with a nullable reason.
+ */
+import { describe, expect, it } from "vitest";
+import {
+  ChatMessageMyFeedbackSchema,
+  FEEDBACK_COMMENT_MAX,
+  FEEDBACK_RATINGS,
+  FEEDBACK_REASONS,
+  PutChatMessageFeedbackRequestSchema,
+} from "../feedback.js";
+
+describe("PutChatMessageFeedbackRequestSchema", () => {
+  it("accepts a bare up or down rating", () => {
+    for (const rating of FEEDBACK_RATINGS) {
+      expect(
+        PutChatMessageFeedbackRequestSchema.safeParse({ rating }).success,
+      ).toBe(true);
+    }
+  });
+
+  it("accepts a down rating with a reason and a comment", () => {
+    expect(
+      PutChatMessageFeedbackRequestSchema.safeParse({
+        rating: "down",
+        reason: "incorrect",
+        comment: "wrong date",
+      }).success,
+    ).toBe(true);
+  });
+
+  it("refuses a reason with rating up", () => {
+    expect(
+      PutChatMessageFeedbackRequestSchema.safeParse({
+        rating: "up",
+        reason: "other",
+      }).success,
+    ).toBe(false);
+  });
+
+  it("refuses a comment with rating up", () => {
+    expect(
+      PutChatMessageFeedbackRequestSchema.safeParse({
+        rating: "up",
+        comment: "nice",
+      }).success,
+    ).toBe(false);
+  });
+
+  it("refuses a comment over 2000 characters", () => {
+    expect(FEEDBACK_COMMENT_MAX).toBe(2000);
+    expect(
+      PutChatMessageFeedbackRequestSchema.safeParse({
+        rating: "down",
+        comment: "x".repeat(FEEDBACK_COMMENT_MAX + 1),
+      }).success,
+    ).toBe(false);
+    expect(
+      PutChatMessageFeedbackRequestSchema.safeParse({
+        rating: "down",
+        comment: "x".repeat(FEEDBACK_COMMENT_MAX),
+      }).success,
+    ).toBe(true);
+  });
+
+  it("refuses a reason outside FEEDBACK_REASONS", () => {
+    expect(
+      PutChatMessageFeedbackRequestSchema.safeParse({
+        rating: "down",
+        reason: "rude",
+      }).success,
+    ).toBe(false);
+    expect(FEEDBACK_REASONS).toContain("other");
+  });
+});
+
+describe("ChatMessageMyFeedbackSchema", () => {
+  it("carries a rating and a nullable reason", () => {
+    expect(
+      ChatMessageMyFeedbackSchema.parse({ rating: "up", reason: null }),
+    ).toEqual({ rating: "up", reason: null });
+    expect(
+      ChatMessageMyFeedbackSchema.parse({ rating: "down", reason: "other" }),
+    ).toEqual({ rating: "down", reason: "other" });
+  });
+
+  it("requires the reason key", () => {
+    expect(
+      ChatMessageMyFeedbackSchema.safeParse({ rating: "up" }).success,
+    ).toBe(false);
+  });
+});

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

@@ -6,6 +6,8 @@
  * - 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.
+ * - Regenerate and edit are offered on older turns too — position gates
+ *   nothing, because both branch rather than delete.
  * - Total over TURN_KINDS; an unknown kind or role is never permissive.
  * - isMessageActionAllowed agrees with messageActionsFor.
  */
@@ -74,7 +76,7 @@ describe("messageActionsFor", () => {
     ).toEqual(["copy", "edit"]);
   });
 
-  it("a user turn that is not latest, or not the reader's own, offers copy only", () => {
+  it("an older user turn that is the reader's own still offers copy and edit (edit branches)", () => {
     expect(
       messageActionsFor(
         makeCtx({
@@ -83,10 +85,21 @@ describe("messageActionsFor", () => {
           isLatestOnActiveBranch: false,
         }),
       ),
-    ).toEqual(["copy"]);
-    expect(
-      messageActionsFor(makeCtx({ role: "user", authoredByReader: false })),
-    ).toEqual(["copy"]);
+    ).toEqual(["copy", "edit"]);
+  });
+
+  it("a user turn that is not the reader's own offers copy only, latest or not", () => {
+    for (const isLatestOnActiveBranch of [true, false]) {
+      expect(
+        messageActionsFor(
+          makeCtx({
+            role: "user",
+            authoredByReader: false,
+            isLatestOnActiveBranch,
+          }),
+        ),
+      ).toEqual(["copy"]);
+    }
   });
 
   it("the latest assistant conversation turn offers copy, feedback and regenerate", () => {
@@ -97,10 +110,25 @@ describe("messageActionsFor", () => {
     ]);
   });
 
-  it("an older assistant conversation turn offers copy and feedback", () => {
+  it("offers regenerate on a historical conversation answer", () => {
     expect(
       messageActionsFor(makeCtx({ isLatestOnActiveBranch: false })),
-    ).toEqual(["copy", "feedback"]);
+    ).toEqual(["copy", "feedback", "regenerate"]);
+  });
+
+  it("an older unsettled conversation turn still offers nothing", () => {
+    for (const role of ["user", "assistant"] as const) {
+      expect(
+        messageActionsFor(
+          makeCtx({
+            role,
+            settled: false,
+            isLatestOnActiveBranch: false,
+            authoredByReader: true,
+          }),
+        ),
+      ).toEqual([]);
+    }
   });
 
   it("never offers regenerate on a workflow_launch, workflow_settlement or input_request_launch turn", () => {
@@ -117,9 +145,13 @@ describe("messageActionsFor", () => {
     }
   });
 
-  it("a proactive or refusal turn offers copy only", () => {
+  it("a proactive or refusal turn offers copy only, latest or not", () => {
     for (const turnKind of ["proactive", "refusal"] as const) {
-      expect(messageActionsFor(makeCtx({ turnKind }))).toEqual(["copy"]);
+      for (const isLatestOnActiveBranch of [true, false]) {
+        expect(
+          messageActionsFor(makeCtx({ turnKind, isLatestOnActiveBranch })),
+        ).toEqual(["copy"]);
+      }
     }
   });
 

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

@@ -57,6 +57,7 @@ const makeMessage = (over: Record<string, unknown> = {}) => ({
   // REQUIRED turn identity — pinned in ./turn-wire.test.ts.
   presentationGroupId: null,
   turnKind: "conversation" as const,
+  alternatives: null,
   myFeedback: null,
   ...over,
 });

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

@@ -55,6 +55,7 @@ const makeMessage = (over: Record<string, unknown> = {}) => ({
   author: userPrincipal("user_1"),
   presentationGroupId: null,
   turnKind: "conversation" as const,
+  alternatives: null,
   myFeedback: null,
   ...over,
 });