@company-semantics/contracts 97.0.0 → 98.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@company-semantics/contracts",
-  "version": "97.0.0",
+  "version": "98.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 = '51e9ee445972' as const;
+export const SPEC_HASH_FULL = '51e9ee445972ebf381cd85489343494ecdd81453574bbec8696a038ef4fd327f' as const;

package/src/api/generated.ts

@@ -1712,7 +1712,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 +5652,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: {
@@ -7756,10 +7765,6 @@ export interface components {
                 })[];
             }) | null;
             error?: string;
-            capabilities: {
-                canStop: boolean;
-                canContinue: boolean;
-            };
             executionAffordances: ({
                 /** @constant */
                 id: "workflow.stop";

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,
 });

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

@@ -9,7 +9,11 @@
  * - 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.
+ * - `myFeedback` is `{ rating, reason }` or null: the rating is exactly `up`
+ *   or `down`, the reason one of the CLOSED FEEDBACK_REASONS or null, and the
+ *   old bare-string shape is refused.
+ * - `alternatives` is REQUIRED; null means the turn has no sibling versions
+ *   (the shape of a present value is pinned in alternatives.test.ts).
  */
 import { describe, expect, it } from "vitest";
 import { userPrincipal } from "../../identity/agent";
@@ -27,7 +31,8 @@ const makeMessage = (over: Record<string, unknown> = {}) => ({
   author: { kind: "agent" as const },
   presentationGroupId: "3f2b8c1e-6d4a-4f7b-9a2e-1c5d8e9f0a1b",
   turnKind: "workflow_settlement" as const,
-  myFeedback: "up" as const,
+  alternatives: null,
+  myFeedback: { rating: "up" as const, reason: null },
   ...over,
 });
 
@@ -86,8 +91,42 @@ describe("ChatMessageSchema turn identity", () => {
 
   it("refuses a rating other than up, down or null", () => {
     expect(
-      ChatMessageSchema.safeParse(makeMessage({ myFeedback: "neutral" }))
-        .success,
+      ChatMessageSchema.safeParse(
+        makeMessage({ myFeedback: { rating: "neutral", reason: null } }),
+      ).success,
+    ).toBe(false);
+  });
+
+  it("refuses the bare-string rating shape", () => {
+    expect(
+      ChatMessageSchema.safeParse(makeMessage({ myFeedback: "up" })).success,
     ).toBe(false);
   });
+
+  it("parses a down rating with a closed reason", () => {
+    const parsed = ChatMessageSchema.parse(
+      makeMessage({ myFeedback: { rating: "down", reason: "incorrect" } }),
+    );
+    expect(parsed.myFeedback).toEqual({ rating: "down", reason: "incorrect" });
+  });
+
+  it("refuses a reason outside FEEDBACK_REASONS", () => {
+    expect(
+      ChatMessageSchema.safeParse(
+        makeMessage({ myFeedback: { rating: "down", reason: "rude" } }),
+      ).success,
+    ).toBe(false);
+  });
+});
+
+describe("ChatMessageSchema alternatives", () => {
+  it("refuses a message without alternatives", () => {
+    expect(ChatMessageSchema.safeParse(without("alternatives")).success).toBe(
+      false,
+    );
+  });
+
+  it("parses null alternatives: the turn has no siblings", () => {
+    expect(ChatMessageSchema.parse(makeMessage()).alternatives).toBeNull();
+  });
 });

package/src/chat/feedback.ts

@@ -0,0 +1,80 @@
+/**
+ * Chat message feedback (response-versions-and-feedback-reasons,
+ * ADR-CONTRACTS-228).
+ *
+ * Feedback MEASURES a message. It is never approval of anything the message
+ * proposed (chat-action-system rule 8): a thumbs-up does not authorize,
+ * confirm or execute.
+ *
+ * INVARIANTS:
+ * - FEEDBACK_REASONS is CLOSED and append-only.
+ * - A reason or a comment rides only a "down" rating.
+ * - LOAD ORDER: this module is a LEAF. It imports only zod and must NEVER
+ *   import `./schemas` (or any module that does) — `./schemas` imports this
+ *   file, and the reverse edge would reach its declarations in the temporal
+ *   dead zone.
+ */
+
+import { z } from "zod";
+
+/** The two ratings a reader can give a turn. */
+export const FEEDBACK_RATINGS = ["up", "down"] as const;
+export const FeedbackRatingSchema = z.enum(FEEDBACK_RATINGS);
+export type FeedbackRating = z.infer<typeof FeedbackRatingSchema>;
+
+/**
+ * Why a reader rated a turn down. CLOSED and append-only: a reason is a
+ * category the product can count, so free text belongs in `comment`, never
+ * here.
+ */
+export const FEEDBACK_REASONS = [
+  /** The answer states something false. */
+  "incorrect",
+  /** The answer ignored what the prompt asked for. */
+  "didnt_follow_instructions",
+  /** Accurate, but it did not help. */
+  "not_helpful",
+  /** The answer lacked context it should have had. */
+  "missing_context",
+  /** A tool call or launched workflow misbehaved. */
+  "tool_or_workflow_issue",
+  /** None of the above; the comment says why. */
+  "other",
+] as const;
+export const FeedbackReasonSchema = z.enum(FEEDBACK_REASONS);
+export type FeedbackReason = z.infer<typeof FeedbackReasonSchema>;
+
+/** Longest free-text comment a down rating may carry. */
+export const FEEDBACK_COMMENT_MAX = 2000;
+
+/**
+ * Body of PUT /api/chats/{id}/messages/{messageId}/feedback (operationId
+ * putChatMessageFeedback). Named after the generated operation's component so
+ * the backend can replace its route-local schema of the same name.
+ */
+export const PutChatMessageFeedbackRequestSchema = z
+  .object({
+    rating: FeedbackRatingSchema,
+    reason: FeedbackReasonSchema.optional(),
+    comment: z.string().max(FEEDBACK_COMMENT_MAX).optional(),
+  })
+  .refine(
+    (b) =>
+      b.rating === "down" ||
+      (b.reason === undefined && b.comment === undefined),
+    { message: "reason and comment ride only a down rating" },
+  );
+export type PutChatMessageFeedbackRequest = z.infer<
+  typeof PutChatMessageFeedbackRequestSchema
+>;
+
+/**
+ * The reader's own rating as `ChatMessage.myFeedback` carries it. `reason` is
+ * null on an up rating and on a down rating given without one. The comment is
+ * write-only — it is never projected back onto the transcript.
+ */
+export const ChatMessageMyFeedbackSchema = z.object({
+  rating: FeedbackRatingSchema,
+  reason: FeedbackReasonSchema.nullable(),
+});
+export type ChatMessageMyFeedback = z.infer<typeof ChatMessageMyFeedbackSchema>;

package/src/chat/index.ts

@@ -41,6 +41,10 @@ export type {
   ChatListResponse,
   CreateChatResponse,
   ChatMessage,
+  // Sibling versions of a turn and the branch-select request body
+  // (response-versions-and-feedback-reasons, ADR-CONTRACTS-228)
+  ChatMessageAlternatives,
+  ChatBranchSelectRequest,
   // Mentions on a chat turn (ADR-CONTRACTS-160): a PrincipalRef target, so the
   // agent is a legal mention target on the chat surface too.
   ChatMessageMention,
@@ -88,6 +92,8 @@ export {
   ChatListResponseSchema,
   CreateChatResponseSchema,
   ChatMessageSchema,
+  ChatMessageAlternativesSchema,
+  ChatBranchSelectRequestSchema,
   ChatMessageMentionSchema,
   ChatMentionableResponseSchema,
   // Participants: the role vocabulary, one participant row, and the list
@@ -155,6 +161,26 @@ export {
   isMessageActionAllowed,
 } from "./message-actions";
 
+// Feedback (response-versions-and-feedback-reasons): the rating vocabulary,
+// the CLOSED reasons a down rating may carry, the PUT feedback request body and
+// the reader's own rating as ChatMessage.myFeedback carries it. Feedback
+// measures a turn; it is never approval.
+export type {
+  FeedbackRating,
+  FeedbackReason,
+  PutChatMessageFeedbackRequest,
+  ChatMessageMyFeedback,
+} from "./feedback";
+export {
+  FEEDBACK_RATINGS,
+  FeedbackRatingSchema,
+  FEEDBACK_REASONS,
+  FeedbackReasonSchema,
+  FEEDBACK_COMMENT_MAX,
+  PutChatMessageFeedbackRequestSchema,
+  ChatMessageMyFeedbackSchema,
+} from "./feedback";
+
 // Runtime profile types and constants
 export type {
   ChatRuntimeProfile,

package/src/chat/message-actions.ts

@@ -18,8 +18,11 @@
  * - 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.
+ * - Regenerate and edit are offered on ANY settled conversation turn, not only
+ *   the latest: both BRANCH (add a sibling version) and never delete, so an
+ *   older turn is as safe to act on as the latest. Edit only to the reader who
+ *   authored the prompt (response-versions-and-feedback-reasons).
+ * - Position (`isLatestOnActiveBranch`) is on the context but gates NOTHING.
  * - An input the schema does not recognize (an unknown kind or role) offers
  *   NOTHING. Unknown is never permissive.
  *
@@ -39,9 +42,9 @@ export const MESSAGE_ACTION_IDS = [
   "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. */
+  /** A new answer to the same request; adds a sibling version. Never re-runs work. */
   "regenerate",
-  /** Rewrite the reader's own prompt; supersedes the branch after it. */
+  /** Rewrite the reader's own prompt; adds a sibling version of it. */
   "edit",
 ] as const;
 
@@ -60,17 +63,24 @@ export const MessageActionContextSchema = z.object({
    * flight or awaiting settlement delivery.
    */
   settled: z.boolean(),
-  /** The turn is the latest of its role on the active branch. */
+  /**
+   * The turn is the latest of its role on the active branch. Carried for the
+   * reader's orientation; it no longer gates any action — regenerate and edit
+   * branch, so they are offered on older turns too.
+   */
   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. */
+/**
+ * `always` is offered on every settled turn; `authored` only on a settled user
+ * turn the reader wrote.
+ */
 type ActionRule = {
   always: readonly MessageActionId[];
-  latest: readonly MessageActionId[];
+  authored: readonly MessageActionId[];
 };
 
 /**
@@ -81,28 +91,28 @@ type ActionRule = {
  */
 const TURN_ACTIONS = {
   conversation: {
-    user: { always: ["copy"], latest: ["edit"] },
-    assistant: { always: ["copy", "feedback"], latest: ["regenerate"] },
+    user: { always: ["copy"], authored: ["edit"] },
+    assistant: { always: ["copy", "feedback", "regenerate"], authored: [] },
   },
   workflow_launch: {
-    user: { always: ["copy"], latest: [] },
-    assistant: { always: ["copy", "feedback"], latest: [] },
+    user: { always: ["copy"], authored: [] },
+    assistant: { always: ["copy", "feedback"], authored: [] },
   },
   workflow_settlement: {
-    user: { always: ["copy"], latest: [] },
-    assistant: { always: ["copy", "feedback"], latest: [] },
+    user: { always: ["copy"], authored: [] },
+    assistant: { always: ["copy", "feedback"], authored: [] },
   },
   input_request_launch: {
-    user: { always: ["copy"], latest: [] },
-    assistant: { always: ["copy", "feedback"], latest: [] },
+    user: { always: ["copy"], authored: [] },
+    assistant: { always: ["copy", "feedback"], authored: [] },
   },
   proactive: {
-    user: { always: ["copy"], latest: [] },
-    assistant: { always: ["copy"], latest: [] },
+    user: { always: ["copy"], authored: [] },
+    assistant: { always: ["copy"], authored: [] },
   },
   refusal: {
-    user: { always: ["copy"], latest: [] },
-    assistant: { always: ["copy"], latest: [] },
+    user: { always: ["copy"], authored: [] },
+    assistant: { always: ["copy"], authored: [] },
   },
 } as const satisfies Record<
   TurnKind,
@@ -114,24 +124,20 @@ const TURN_ACTIONS = {
  *
  * - 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.
+ * - User turn → its `always`, plus `authored` iff authored by the reader.
+ * - Assistant turn → its `always`.
+ * - Position on the branch gates nothing.
  */
 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 { role, turnKind, 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];
+  return role === "user" && authoredByReader
+    ? [...rule.always, ...rule.authored]
+    : [...rule.always];
 }
 
 /** Whether `action` is among `messageActionsFor(ctx)` — the backend's check. */

package/src/chat/schemas.ts

@@ -25,6 +25,7 @@ import {
   proactiveChatFields,
   TitleSourceSchema,
 } from "./enums";
+import { ChatMessageMyFeedbackSchema } from "./feedback";
 import { TurnKindSchema } from "./turn-kind";
 
 // The chat vocabulary and the SSE event contract, re-exported so this module
@@ -238,6 +239,41 @@ export const ChatDiscussionScopeSchema = z
   })
   .strict(); // an unknown key is an ERROR, not surplus
 
+/**
+ * The VERSIONS of one turn (response-versions-and-feedback-reasons,
+ * ADR-CONTRACTS-228). Regenerating an answer or editing a prompt never deletes
+ * the turn it replaces — it ADDS A SIBLING VERSION, and the reader picks which
+ * one the active branch runs through.
+ *
+ * `ids` lists every sibling, this one included, ORDERED BY CREATION — so the
+ * selector reads "2 / 3" from `position` / `total` and steps through `ids`
+ * without a second fetch. `position` is 1-based. The refinements make the three
+ * fields agree by construction: a client never has to reconcile a `total` that
+ * disagrees with the list it was sent.
+ */
+export const ChatMessageAlternativesSchema = z
+  .object({
+    position: z.number().int().min(1),
+    total: z.number().int().min(1),
+    ids: z.array(z.string().uuid()),
+  })
+  .refine((a) => a.ids.length === a.total, {
+    message: "ids.length must equal total",
+  })
+  .refine((a) => a.position <= a.total, {
+    message: "position must not exceed total",
+  });
+
+/**
+ * Request body that makes one version the active branch
+ * (response-versions-and-feedback-reasons). `messageId` names the SIBLING to
+ * select; the server re-checks it is a version of a turn in this chat — naming
+ * an id is a lookup, not authority.
+ */
+export const ChatBranchSelectRequestSchema = z.object({
+  messageId: z.string().uuid(),
+});
+
 export const ChatMessageSchema = z.object({
   id: z.string(),
   role: z.enum(["user", "assistant"]),
@@ -309,12 +345,26 @@ export const ChatMessageSchema = z.object({
    */
   turnKind: TurnKindSchema,
 
+  /**
+   * The sibling VERSIONS of this turn, when it has been regenerated (answer)
+   * or edited (prompt) — see {@link ChatMessageAlternativesSchema}. REQUIRED,
+   * and null means this turn has no siblings: every row has an answer, so there
+   * is no absence to make optional. The transcript carries the ACTIVE branch
+   * only; the other versions are reachable by id, never inlined.
+   */
+  alternatives: ChatMessageAlternativesSchema.nullable(),
+
   /**
    * 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.
+   *
+   * `{ rating, reason }` (response-versions-and-feedback-reasons): `reason` is
+   * one of the CLOSED FEEDBACK_REASONS, and only ever set on a down rating.
+   * Feedback MEASURES the turn — it is NOT APPROVAL of anything the turn
+   * proposed, and never authorizes, confirms or executes.
    */
-  myFeedback: z.enum(["up", "down"]).nullable(),
+  myFeedback: ChatMessageMyFeedbackSchema.nullable(),
 });
 
 // =============================================================================

package/src/chat/types.ts

@@ -30,6 +30,8 @@ import {
   ChatListResponseSchema,
   CreateChatResponseSchema,
   ChatMessageSchema,
+  ChatMessageAlternativesSchema,
+  ChatBranchSelectRequestSchema,
   ChatMessageMentionSchema,
   ChatMentionableResponseSchema,
   ChatParticipantRoleSchema,
@@ -227,6 +229,19 @@ export type CreateChatResponse = z.infer<typeof CreateChatResponseSchema>;
 /** Individual message in a chat response (GET /api/chats/:id). */
 export type ChatMessage = z.infer<typeof ChatMessageSchema>;
 
+/**
+ * The sibling versions of one turn — 1-based `position`, `total`, and every
+ * sibling id ordered by creation (response-versions-and-feedback-reasons).
+ */
+export type ChatMessageAlternatives = z.infer<
+  typeof ChatMessageAlternativesSchema
+>;
+
+/** Request body that makes one sibling version the active branch. */
+export type ChatBranchSelectRequest = z.infer<
+  typeof ChatBranchSelectRequestSchema
+>;
+
 /**
  * One mention on a chat turn — a `PrincipalRef` target, a nullable UTF-16
  * code-unit range into `content`, and a read-time display name.