@company-semantics/contracts 88.1.0 → 89.0.0

package/package.json

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

package/src/api/generated.ts

@@ -3834,6 +3834,80 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/api/factory/quality/changes": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Report a pull request head and get the evaluation plan to run for it
+         * @description Resolves the changed files to an impact set, records the change and plans its evaluation. Idempotent: the same head reported again answers the same plan. A change no impact rule matches answers { noImpact: true } and records nothing.
+         */
+        post: operations["createQualityChange"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/api/factory/quality/plans/{planId}": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /** Read an evaluation plan: suites, pinned manifests, samples, model profile, budget */
+        get: operations["getQualityPlan"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/api/factory/quality/plans/{planId}/decision": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /** Read where a plan's evaluation stands and, once recorded, its decision */
+        get: operations["getQualityPlanDecision"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/api/factory/quality/deployments": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Report one phase of a deploy run so an applied backend deployment is verified
+         * @description An applied phase that names a backend commit pins the release references, records the deployment as a change to verify, plans the verification and asks for its runs. Idempotent: the same deployment reported again answers the same change and plan. Any other report answers 202 { ignored: true } and records nothing. The deployment is never held for its verification.
+         */
+        post: operations["recordQualityDeployment"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/api/internal-admin/impersonate/start": {
         parameters: {
             query?: never;
@@ -8255,6 +8329,87 @@ export interface components {
                 [key: string]: unknown;
             } | null;
         };
+        CreateQualityChangeResponse: {
+            /** Format: uuid */
+            planId: string;
+            suites: string[];
+            samples: number;
+            budgetUsd: number;
+            modelProfile: {
+                [key: string]: unknown;
+            };
+        } | {
+            /** @constant */
+            noImpact: true;
+        };
+        CreateQualityChangeRequest: {
+            /** @constant */
+            sourceKind: "pull_request";
+            sourceRef: string;
+            gitSha: string;
+            changedFiles: string[];
+        };
+        QualityPlanResponse: {
+            /** Format: uuid */
+            planId: string;
+            suites: string[];
+            samples: number;
+            budgetUsd: number;
+            modelProfile: {
+                [key: string]: unknown;
+            };
+            /** Format: uuid */
+            changeId: string;
+            /** @enum {string} */
+            state: "active" | "superseded";
+            supersededBy: string | null;
+            manifests: {
+                suite: string;
+                manifestId: string;
+                entries: {
+                    caseId: string;
+                    caseRevision: string;
+                }[] | null;
+            }[];
+        };
+        QualityPlanDecisionResponse: {
+            /** @enum {string} */
+            state: "queued" | "running" | "blocked" | "complete";
+            /** @enum {string} */
+            blockReason?: "budget_exhausted" | "grader_calibration_pending" | "required_run_pending" | "provider_unavailable" | "manifest_unavailable";
+            decision?: {
+                /** @enum {string} */
+                outcome: "promote" | "reject" | "escalate";
+                reasons: {
+                    /** @enum {string} */
+                    code: "critical_regression" | "invariant_regression" | "protected_case_failed" | "below_floor" | "bucket_budget_exceeded" | "insufficient_improvement" | "cost_regression" | "latency_regression" | "grader_ineligible" | "insufficient_samples" | "flaky_case" | "policy_ambiguous" | "all_gates_passed" | "human_override";
+                    detail?: string;
+                }[];
+            };
+            /** Format: uuid */
+            supersededBy?: string;
+        };
+        RecordQualityDeploymentResponse: {
+            /** Format: uuid */
+            changeId: string;
+            /** Format: uuid */
+            planId: string;
+            releaseReferences: number;
+        };
+        QualityDeploymentIgnored: {
+            /** @constant */
+            ignored: true;
+        };
+        RecordQualityDeploymentRequest: {
+            manifestId: string | null;
+            phase: string;
+            shas: {
+                backend?: string;
+                app?: string;
+                edge?: string;
+            } | null;
+            surfaces: string[];
+        };
         ImpersonationSessionResponse: {
             session: {
                 impersonationSessionId: string;
@@ -8816,6 +8971,8 @@ export interface components {
                 /** @enum {string} */
                 classificationState: "unclassified" | "classified";
                 sourceClass: ("board_deck" | "board_minutes" | "investor_update" | "financial_brief" | "budget_forecast" | "okr_plan" | "annual_plan" | "all_hands" | "unit_strategy" | "roadmap" | "qbr" | "other" | "decoy") | null;
+                documentType: ("board_deck" | "board_minutes" | "strategy_memo" | "planning_doc" | "okr_doc" | "roadmap" | "operating_review" | "all_hands_deck" | "offsite_notes" | "investor_update" | "pitch_deck" | "product_spec" | "research_analysis" | "general_meeting_notes" | "financial_plan" | "financial_actuals" | "equity_admin_record" | "corporate_formation_record" | "corporate_governance_record" | "government_filing" | "equity_agreement" | "commercial_agreement" | "employment_agreement" | "transaction_record" | "personal_document" | "social_event_material" | "coursework" | "empty_template" | "image_or_screenshot" | "unknown") | null;
+                documentTypeConfidence: number | null;
                 periodLabel: string | null;
                 seriesRole: ("current" | "history") | null;
                 relevance: number;
@@ -8848,12 +9005,12 @@ export interface components {
                     /** @constant */
                     kind: "evaluation";
                     /** @enum {string} */
-                    code: "not_evaluated_t1" | "not_evaluated_t2" | "folder_unresolved" | "folder_truncated" | "explored_t1" | "explored_t2";
+                    code: "not_evaluated_t1" | "not_evaluated_t2" | "folder_unresolved" | "folder_truncated" | "explored_t1" | "explored_t2" | "peek_insufficient_evidence" | "type_disagreement" | "type_below_confidence" | "execution_failed_t1" | "execution_failed_t2";
                 } | {
                     /** @constant */
                     kind: "model";
                     /** @enum {string} */
-                    code: "title_path_score" | "peek_confirms" | "peek_contradicts";
+                    code: "title_path_score" | "peek_confirms" | "peek_contradicts" | "type_policy" | "peek_strategy_evidence_present" | "peek_strategy_evidence_absent";
                     score: number | null;
                 })[];
                 targetAudience: ("restricted" | "unit" | "org_wide") | null;
@@ -8897,6 +9054,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 +9194,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: {
@@ -16423,6 +16608,184 @@ export interface operations {
             };
         };
     };
+    createQualityChange: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["CreateQualityChangeRequest"];
+            };
+        };
+        responses: {
+            /** @description The plan to run (planId, suites, samples, budgetUsd, modelProfile), or noImpact */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["CreateQualityChangeResponse"];
+                };
+            };
+            /** @description Payload invalid */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description Missing or invalid Floor bearer token */
+            401: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description The change was replaced; its replacement is what is planned */
+            409: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+        };
+    };
+    getQualityPlan: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                planId: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description The plan as a runner needs it */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["QualityPlanResponse"];
+                };
+            };
+            /** @description Payload invalid */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description Missing or invalid Floor bearer token */
+            401: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description No such plan */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+        };
+    };
+    getQualityPlanDecision: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                planId: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Evaluation state, block reason while blocked, and the decision once decided */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["QualityPlanDecisionResponse"];
+                };
+            };
+            /** @description Payload invalid */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description Missing or invalid Floor bearer token */
+            401: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description No such plan */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+        };
+    };
+    recordQualityDeployment: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["RecordQualityDeploymentRequest"];
+            };
+        };
+        responses: {
+            /** @description The change that verifies the deployment, its plan, and the release references pinned */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["RecordQualityDeploymentResponse"];
+                };
+            };
+            /** @description Not an applied backend deployment: nothing was recorded */
+            202: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["QualityDeploymentIgnored"];
+                };
+            };
+            /** @description Payload invalid */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description Missing or invalid Floor bearer token */
+            401: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+        };
+    };
     startImpersonation: {
         parameters: {
             query?: never;

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