@company-semantics/contracts 88.1.0 → 88.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@company-semantics/contracts",
-  "version": "88.1.0",
+  "version": "88.2.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 = 'edc033bdac67' as const;
-export const SPEC_HASH_FULL = 'edc033bdac6767eaf9965214f6dfed6c536d48fb5f1f77a48e1af26533633fe1' as const;
+export const SPEC_HASH = 'fa844a445bc5' as const;
+export const SPEC_HASH_FULL = 'fa844a445bc5f62afa70d732ba33c9ce0b90b89f0634fabb2d6342743c0efeee' as const;

package/src/api/generated.ts

@@ -8897,6 +8897,20 @@ export interface components {
                     text: string;
                     detail?: string;
                 };
+                rows?: {
+                    rowId: string;
+                    label: string;
+                    note?: string;
+                    evidence: {
+                        label: string;
+                        value: string;
+                        withheld: boolean;
+                    }[];
+                    selectedChoiceId: string | null;
+                    recommendedChoiceId: string | null;
+                    allowedChoiceIds: string[];
+                    required: boolean;
+                }[];
             }[];
             withheldQuestionCount: number;
             totals: {
@@ -9023,6 +9037,20 @@ export interface components {
                     text: string;
                     detail?: string;
                 };
+                rows?: {
+                    rowId: string;
+                    label: string;
+                    note?: string;
+                    evidence: {
+                        label: string;
+                        value: string;
+                        withheld: boolean;
+                    }[];
+                    selectedChoiceId: string | null;
+                    recommendedChoiceId: string | null;
+                    allowedChoiceIds: string[];
+                    required: boolean;
+                }[];
             }[];
             withheldQuestionCount: number;
             changes: {

package/src/decisions/README.md

@@ -69,6 +69,11 @@ decision-effect-is-a-domain-parameter.
   effect and no apply-protocol address; `questionId` is its only id. Its `kind`
   is a bounded open string because each domain has its own kinds. Promoted
   because the backend renders it and the app consumes it.
+- **A matrix keeps its state on rows.** A presentation with `rows` is a matrix:
+  each row is one subject answered with one of `choices` (the columns). Columns
+  carry no `selected`/`recommended`; each row holds its own, within its
+  `allowedChoiceIds`. One answer per row, no free text. Enforced by
+  `matrixPresentationDefect` inside the schema (ADR-CONTRACTS-213).
 
 ## Measured evidence is optional
 

package/src/decisions/__tests__/presentation.test.ts

@@ -11,6 +11,7 @@ import { describe, expect, it } from "vitest";
 import {
   DecisionChoicePresentationSchema,
   DecisionQuestionPresentationSchema,
+  matrixPresentationDefect,
 } from "../index";
 
 function presentedQuestion(overrides: Record<string, unknown> = {}) {
@@ -110,3 +111,155 @@ describe("DecisionQuestionPresentationSchema", () => {
     );
   });
 });
+
+/**
+ * A MATRIX question: one subject per row, each answered with one of the
+ * question's choices. Rows carry the state; the columns carry none.
+ */
+function matrixQuestion(overrides: Record<string, unknown> = {}) {
+  return presentedQuestion({
+    questionId: "treatment_matrix:s1",
+    kind: "treatment_matrix",
+    header: "Strategy memo",
+    question:
+      "Plan was found relevant to 2 places. How should it be used in each?",
+    choices: [
+      {
+        choiceId: "attached",
+        label: "Attach",
+        recommended: false,
+        selected: false,
+      },
+      {
+        choiceId: "direction_only",
+        label: "Direction only",
+        recommended: false,
+        selected: false,
+      },
+      {
+        choiceId: "excluded",
+        label: "Leave out",
+        recommended: false,
+        selected: false,
+      },
+    ],
+    multiSelect: false,
+    freeFormAllowed: false,
+    recommendation: { strength: "confident" },
+    rows: [
+      {
+        rowId: "item-1",
+        label: "Support",
+        note: "Shared more narrowly than this doc",
+        evidence: [],
+        selectedChoiceId: null,
+        recommendedChoiceId: "direction_only",
+        allowedChoiceIds: ["attached", "direction_only", "excluded"],
+        required: true,
+      },
+      {
+        rowId: "item-2",
+        label: "Engineering",
+        evidence: [
+          { label: "Why it was found", value: "Title search", withheld: false },
+        ],
+        selectedChoiceId: "attached",
+        recommendedChoiceId: null,
+        allowedChoiceIds: ["attached", "direction_only", "excluded"],
+        required: false,
+      },
+    ],
+    ...overrides,
+  });
+}
+
+describe("DecisionQuestionPresentationSchema — matrix", () => {
+  it("accepts a matrix whose rows hold their own selection and recommendation", () => {
+    const parsed =
+      DecisionQuestionPresentationSchema.safeParse(matrixQuestion());
+    expect(parsed.success).toBe(true);
+    expect(parsed.data?.rows).toHaveLength(2);
+  });
+
+  it("leaves a question without rows untouched", () => {
+    expect(
+      matrixPresentationDefect(
+        DecisionQuestionPresentationSchema.parse(presentedQuestion()),
+      ),
+    ).toBeNull();
+  });
+
+  it.each([
+    ["matrix_multi_select", { multiSelect: true }],
+    ["matrix_free_form", { freeFormAllowed: true }],
+    ["matrix_recommendation_mismatch", { recommendation: null }],
+  ])("refuses %s", (defect, overrides) => {
+    const parsed = DecisionQuestionPresentationSchema.safeParse(
+      matrixQuestion(overrides),
+    );
+    expect(parsed.success).toBe(false);
+    expect(parsed.error?.issues[0]?.message).toBe(defect);
+    expect(parsed.error?.issues[0]?.path).toEqual(["rows"]);
+  });
+
+  it("refuses state on a column", () => {
+    const base = matrixQuestion();
+    const choices = base.choices.map((c, i) =>
+      i === 0 ? { ...c, selected: true } : c,
+    );
+    const parsed = DecisionQuestionPresentationSchema.safeParse({
+      ...base,
+      choices,
+    });
+    expect(parsed.error?.issues[0]?.message).toBe("matrix_column_state");
+  });
+
+  it("refuses two rows with one id", () => {
+    const base = matrixQuestion();
+    const rows = [base.rows[0], { ...base.rows[1], rowId: "item-1" }];
+    const parsed = DecisionQuestionPresentationSchema.safeParse({
+      ...base,
+      rows,
+    });
+    expect(parsed.error?.issues[0]?.message).toBe("matrix_duplicate_row");
+  });
+
+  it("refuses a row allowing a choice that is not a column", () => {
+    const base = matrixQuestion();
+    const rows = [
+      { ...base.rows[0], allowedChoiceIds: ["attached", "archived"] },
+      base.rows[1],
+    ];
+    const parsed = DecisionQuestionPresentationSchema.safeParse({
+      ...base,
+      rows,
+    });
+    expect(parsed.error?.issues[0]?.message).toBe("matrix_unknown_choice");
+  });
+
+  it("refuses a selection or recommendation the row does not allow", () => {
+    const base = matrixQuestion();
+    const narrowed = { ...base.rows[1], allowedChoiceIds: ["excluded"] };
+    const selected = DecisionQuestionPresentationSchema.safeParse({
+      ...base,
+      rows: [base.rows[0], narrowed],
+    });
+    expect(selected.error?.issues[0]?.message).toBe(
+      "matrix_selection_not_allowed",
+    );
+    const recommended = DecisionQuestionPresentationSchema.safeParse({
+      ...base,
+      rows: [{ ...base.rows[0], allowedChoiceIds: ["excluded"] }, base.rows[1]],
+    });
+    expect(recommended.error?.issues[0]?.message).toBe(
+      "matrix_recommendation_not_allowed",
+    );
+  });
+
+  it("refuses an empty row list", () => {
+    const parsed = DecisionQuestionPresentationSchema.safeParse(
+      matrixQuestion({ rows: [] }),
+    );
+    expect(parsed.success).toBe(false);
+  });
+});

package/src/decisions/index.ts

@@ -47,10 +47,15 @@ export {
   decisionAnswerSchemaOf,
 } from "./schemas";
 
-export type { DecisionQuestionPresentation } from "./presentation";
+export type {
+  DecisionMatrixRowPresentation,
+  DecisionQuestionPresentation,
+} from "./presentation";
 
 export {
   DecisionChoicePresentationSchema,
   DecisionEvidenceRowSchema,
+  DecisionMatrixRowPresentationSchema,
   DecisionQuestionPresentationSchema,
+  matrixPresentationDefect,
 } from "./presentation";

package/src/decisions/presentation.ts

@@ -39,7 +39,29 @@ export const DecisionEvidenceRowSchema = z.object({
   withheld: z.boolean(),
 });
 
-export const DecisionQuestionPresentationSchema = z.object({
+/**
+ * One row of a MATRIX question: a single subject answered with one of the
+ * question's choices (the matrix's columns). Each row is its own answer, so the
+ * row — not the column — carries selection and recommendation state.
+ */
+export const DecisionMatrixRowPresentationSchema = z.object({
+  /** The row's submit address, never rendered. */
+  rowId: z.string().min(1).max(64),
+  label: z.string().min(1).max(200),
+  /** A short line under the label: why this row is asked, or why it is not. */
+  note: z.string().min(1).max(300).optional(),
+  evidence: z.array(DecisionEvidenceRowSchema).max(6),
+  /** The choice this row holds now. Selection is STATE the server owns. */
+  selectedChoiceId: z.string().min(1).max(64).nullable(),
+  /** The choice the derivation believes is right for this row, independent of selection. */
+  recommendedChoiceId: z.string().min(1).max(64).nullable(),
+  /** The choices this row may take, in the question's column order. */
+  allowedChoiceIds: z.array(z.string().min(1).max(64)).min(1).max(8),
+  /** True when the question is unanswered until this row holds a choice. */
+  required: z.boolean(),
+});
+
+const DecisionQuestionPresentationBaseSchema = z.object({
   questionId: z.string().min(1).max(200),
   /** A public semantic discriminator. Never an id, never reasoning. */
   kind: z.string().min(1).max(64),
@@ -69,8 +91,67 @@ export const DecisionQuestionPresentationSchema = z.object({
       detail: z.string().max(2000).optional(),
     })
     .optional(),
+  /**
+   * Present exactly when the question is a MATRIX: one subject per row, each
+   * answered with one of `choices` (the columns). A matrix takes no free text
+   * and one choice per row, and its columns carry no state — `selected` and
+   * `recommended` are false on every choice; each row holds its own.
+   */
+  rows: z.array(DecisionMatrixRowPresentationSchema).min(1).max(20).optional(),
 });
 
+type DecisionQuestionPresentationBase = z.infer<
+  typeof DecisionQuestionPresentationBaseSchema
+>;
+
+/** Why a matrix question is malformed, or null. Pure. */
+export function matrixPresentationDefect(
+  question: DecisionQuestionPresentationBase,
+): string | null {
+  const rows = question.rows;
+  if (rows === undefined) return null;
+  if (question.multiSelect) return "matrix_multi_select";
+  if (question.freeFormAllowed) return "matrix_free_form";
+  if (question.choices.some((c) => c.selected || c.recommended)) {
+    return "matrix_column_state";
+  }
+  const columns = new Set(question.choices.map((c) => c.choiceId));
+  if (new Set(rows.map((r) => r.rowId)).size !== rows.length) {
+    return "matrix_duplicate_row";
+  }
+  for (const row of rows) {
+    if (row.allowedChoiceIds.some((id) => !columns.has(id))) {
+      return "matrix_unknown_choice";
+    }
+    const allowed = new Set(row.allowedChoiceIds);
+    if (row.selectedChoiceId !== null && !allowed.has(row.selectedChoiceId)) {
+      return "matrix_selection_not_allowed";
+    }
+    if (
+      row.recommendedChoiceId !== null &&
+      !allowed.has(row.recommendedChoiceId)
+    ) {
+      return "matrix_recommendation_not_allowed";
+    }
+  }
+  const anyRecommended = rows.some((r) => r.recommendedChoiceId !== null);
+  if (anyRecommended !== (question.recommendation !== null)) {
+    return "matrix_recommendation_mismatch";
+  }
+  return null;
+}
+
+export const DecisionQuestionPresentationSchema =
+  DecisionQuestionPresentationBaseSchema.superRefine((question, ctx) => {
+    const defect = matrixPresentationDefect(question);
+    if (defect !== null) {
+      ctx.addIssue({ code: "custom", path: ["rows"], message: defect });
+    }
+  });
+
 export type DecisionQuestionPresentation = z.infer<
   typeof DecisionQuestionPresentationSchema
 >;
+export type DecisionMatrixRowPresentation = z.infer<
+  typeof DecisionMatrixRowPresentationSchema
+>;