@company-semantics/contracts 88.1.0 → 89.0.0

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

package/src/generated/openapi-routes.ts

@@ -93,6 +93,10 @@ export const openApiRoutes = {
   '/api/executions/{executionId}/undo': ['POST'],
   '/api/factory/floor': ['GET'],
   '/api/factory/kpis': ['GET'],
+  '/api/factory/quality/changes': ['POST'],
+  '/api/factory/quality/deployments': ['POST'],
+  '/api/factory/quality/plans/{planId}': ['GET'],
+  '/api/factory/quality/plans/{planId}/decision': ['GET'],
   '/api/factory/snapshot': ['GET'],
   '/api/ingestion/operations/{id}': ['GET'],
   '/api/internal-admin/impersonate/end': ['POST'],

package/src/source-sync/README.md

@@ -134,7 +134,7 @@ Doctrine: control ADR `source-discovery-relevance-funnel`. Vocabulary: ADR
   `unclassified` (so `sourceClass` and `recommendedUse` are both null) or
   `classified` (both non-null). A shown line can still be
   `pending_classification` in its `machineState`.
-- **Reasons are a discriminated union.** `relevanceReasons` (≤ 8) is
+- **Reasons are a discriminated union.** `relevanceReasons` (≤ 16) is
   `RelevanceReason`: `lexicon` (a product-owned `term` and a `count`),
   `signal` (a `value` or null), `evaluation` (a code only) or `model` (a
   `score` or null). Each kind has its own disjoint code set, and the app
@@ -155,6 +155,42 @@ Doctrine: control ADR `source-discovery-relevance-funnel`. Vocabulary: ADR
   `filesNotRediscovered` and `filesPendingClassification`, counted by
   `candidateTotalsOf` over distinct files.
 
+## Document type
+
+Doctrine: control ADR `source-discovery-observation-vs-policy`. Vocabulary: ADR
+`source-discovery-document-type-vocabulary`. The model NAMES what a source is;
+product policy in the backend decides what that means.
+
+- **Structural, never a verdict.** `DOCUMENT_TYPES` (in `vocabulary.ts`) says
+  what a file IS — `corporate_formation_record`, never `irrelevant_doc` —
+  never how relevant it is. A medium is not a meaning: `image_or_screenshot`
+  is graded on its content. `unknown` is a real answer (the model could not
+  tell, or two reads disagreed) and is always last.
+- **The resolved type travels, nothing else.** The candidate item's
+  `documentType` and `documentTypeConfidence` (0..1) carry the RESOLVED type,
+  after the backend reconciles the T1 and T2 observations. Both are null on an
+  unclassified line and on every line of a run pinned before the typed path
+  (v1), where `sourceClass` alone is set. A known type always carries a
+  confidence; `unknown` and null never do. Per-tier types and per-layer scores
+  are backend evidence and stay off the wire.
+- **Policy lives in the backend.** Families, relevance policy modes, ceilings,
+  confidence floors, strategy signals and peek verdicts are backend product
+  policy, never contracts vocabulary
+  (INV-SOURCESYNC-OBSERVATION-IS-SEPARATE-FROM-POLICY). Changing what a type
+  means is a backend change, not a release.
+- **Same word, separate axis.** Five members are also words in other sets:
+  `board_deck`, `board_minutes`, `investor_update`, `roadmap`
+  (`SOURCE_CLASSES`) and `unknown` (`SHARING_BREADTHS`). `DOCUMENT_TYPES`
+  therefore sits outside the cross-set disjointness check, and its overlap is
+  pinned to exactly those five.
+- **Typed-relevance reasons.** Model codes `type_policy` (the policy-applied
+  score of the resolved type) and `peek_strategy_evidence_present` /
+  `peek_strategy_evidence_absent`. Evaluation codes
+  `peek_insufficient_evidence`, `type_disagreement`, `type_below_confidence`
+  and `execution_failed_t1` / `execution_failed_t2`: a tier that did not run
+  is uncertainty, never irrelevance. `peek_confirms` / `peek_contradicts`
+  stay for v1-pinned rows.
+
 ## Public API
 
 - `SOURCE_CLASSES` / `SourceClass` — what kind of document a source is.
@@ -172,10 +208,14 @@ Doctrine: control ADR `source-discovery-relevance-funnel`. Vocabulary: ADR
   `pending`, `approved` or `rejected` (no verb writes `rejected` yet).
 - `SOURCE_SYNC_SCOPE_APPROVER_KINDS` / `SourceSyncScopeApproverKind` —
   `org_admin` or `unit_head`.
+- `DOCUMENT_TYPES` / `DocumentType` / `KnownDocumentType` — what a source is,
+  structurally; `KnownDocumentType` excludes `unknown` (see Document type).
 - `SourceSyncDiscoveryRunResponseSchema` / `SourceSyncDiscoveryRunResponse` —
   the discovery run started, and the workflow narrating it.
 - `SourceSyncCandidateItemSchema` / `SourceSyncCandidateItem` — one source
-  proposed for one target document, with the server's `included`.
+  proposed for one target document, with the server's `included` and the
+  resolved `documentType` / `documentTypeConfidence` (null when unclassified
+  or v1-pinned).
 - `SourceSyncCandidateSetResponseSchema` / `SourceSyncCandidateSetResponse` —
   the draft set under review: its revision, items, presented questions,
   distinct-file `totals` and cost estimate.
@@ -267,5 +307,7 @@ Doctrine: control ADR `source-discovery-relevance-funnel`. Vocabulary: ADR
 
 `rules.ts` imports only `zod`, `../api/primitives` and `./vocabulary`.
 `upkeep.ts` and `reach.ts` import only `zod` and `../api/primitives`.
+`candidate-item.ts` imports only `zod`, `../api/primitives`, `./vocabulary`
+and `./relevance`.
 `relevance.ts` imports only `zod`.
 `vocabulary.ts` itself has no imports.

package/src/source-sync/__tests__/barrel.test.ts

@@ -18,6 +18,8 @@
  *   standing orders and the Drive-reach shapes.
  * - Every runtime name `relevance.ts` declares is reachable from the root as
  *   the same binding.
+ * - `DOCUMENT_TYPES` is reachable from the root as the same binding, and its
+ *   two types are named by the barrel.
  * - `ACTION_ITEM_KINDS` at the root carries `sourceSync.approval_pending`.
  * - The root re-exports the domain barrel explicitly.
  *
@@ -67,18 +69,20 @@ import type {
   SourceSyncStandingOrder,
   SourceSyncStandingOrdersResponse,
 } from "../../index";
+import * as candidateItem from "../candidate-item";
 import * as reach from "../reach";
 import * as relevance from "../relevance";
 import * as rules from "../rules";
 import * as schemas from "../schemas";
 import * as upkeep from "../upkeep";
+import * as vocabulary from "../vocabulary";
 
 /** Runtime names Release C adds, keyed to the module that declares them. */
 const RELEASE_C_RUNTIME_NAMES: ReadonlyArray<
   readonly [name: string, module: Record<string, unknown>]
 > = [
   ["SOURCE_SYNC_RISK_REASONS", schemas],
-  ["SourceSyncCandidateItemPatchSchema", schemas],
+  ["SourceSyncCandidateItemPatchSchema", candidateItem],
   ["SourceSyncAddCandidateRequestSchema", schemas],
   ["SourceSyncApproveRequestSchema", schemas],
   ["SourceSyncScopeApprovalSchema", schemas],
@@ -250,6 +254,12 @@ describe("source-sync Release C package surface", () => {
     }
   });
 
+  it("every document-type name is reachable from the root as the same binding", () => {
+    expect(rootBarrel.DOCUMENT_TYPES).toBe(vocabulary.DOCUMENT_TYPES);
+    expect([...barrelTypeExports]).toContain("DocumentType");
+    expect([...barrelTypeExports]).toContain("KnownDocumentType");
+  });
+
   it("exposes sourceSync.approval_pending in ACTION_ITEM_KINDS at the root", () => {
     expect(rootBarrel.ACTION_ITEM_KINDS).toContain(
       "sourceSync.approval_pending",

package/src/source-sync/__tests__/schemas.test.ts

@@ -14,6 +14,9 @@
  * - Relevance and treatment are two axes (control ADR source-discovery-relevance-funnel):
  *   a hidden line is never included; an unclassified line has no recommendation and
  *   no class; `selectionSource` is present exactly when `use` is.
+ * - The resolved document type (control ADR source-discovery-observation-vs-policy)
+ *   is a REQUIRED nullable key: an unclassified line has none, and a confidence
+ *   travels exactly with a known type. A line carries at most sixteen reasons.
  * - A relevance reason's code belongs to its kind's closed set.
  * - A candidate patch changes exactly one thing: bringing a line into review never
  *   also commits a treatment, and a patch can never hide a line.
@@ -28,6 +31,8 @@ import {
   SourceSyncCandidateSetResponseSchema,
   SourceSyncDiscoveryRunResponseSchema,
 } from "../index";
+import * as root from "../../index";
+import * as candidateItemModule from "../candidate-item";
 
 const RUN_ID = "3f1a2b4c-5d6e-4f70-8192-a3b4c5d6e7f8";
 const WORKFLOW_ID = "4a2b3c5d-6e7f-4a81-9b2c-b4c5d6e7f8a9";
@@ -52,6 +57,8 @@ function candidateItem(overrides: Record<string, unknown> = {}) {
     visibility: "shown",
     classificationState: "classified",
     sourceClass: "board_deck",
+    documentType: null,
+    documentTypeConfidence: null,
     periodLabel: "Q3 2026",
     seriesRole: "current",
     relevance: 0.92,
@@ -142,6 +149,18 @@ function candidateSet(overrides: Record<string, unknown> = {}) {
 }
 
 describe("SourceSyncCandidateItemSchema", () => {
+  it("the candidate item schema moved without changing what it accepts", () => {
+    const parsed = SourceSyncCandidateItemSchema.safeParse(candidateItem());
+    expect(parsed.success).toBe(true);
+    expect(parsed.data).toEqual(candidateItem());
+    expect(root.SourceSyncCandidateItemSchema).toBe(
+      candidateItemModule.SourceSyncCandidateItemSchema,
+    );
+    expect(root.SourceSyncCandidateItemPatchSchema).toBe(
+      candidateItemModule.SourceSyncCandidateItemPatchSchema,
+    );
+  });
+
   it("refuses a candidate item with no audience fit key at all", () => {
     const { audienceFit: _omitted, ...item } = candidateItem();
     const parsed = SourceSyncCandidateItemSchema.safeParse(item);
@@ -362,15 +381,104 @@ describe("candidate relevance", () => {
     ]);
   });
 
-  it("refuses more than eight reasons", () => {
+  it("accepts sixteen reasons", () => {
     const reason = { kind: "evaluation", code: "explored_t1" };
     expect(
       SourceSyncCandidateItemSchema.safeParse(
-        candidateItem({ relevanceReasons: Array(9).fill(reason) }),
+        candidateItem({ relevanceReasons: Array(16).fill(reason) }),
+      ).success,
+    ).toBe(true);
+  });
+
+  it("refuses more than sixteen reasons", () => {
+    const reason = { kind: "evaluation", code: "explored_t1" };
+    expect(
+      SourceSyncCandidateItemSchema.safeParse(
+        candidateItem({ relevanceReasons: Array(17).fill(reason) }),
+      ).success,
+    ).toBe(false);
+  });
+
+  it("a typed item carries its resolved document type and confidence", () => {
+    const parsed = SourceSyncCandidateItemSchema.safeParse(
+      candidateItem({
+        documentType: "corporate_formation_record",
+        documentTypeConfidence: 0.92,
+        sourceClass: "other",
+      }),
+    );
+    expect(parsed.success).toBe(true);
+    expect(parsed.data?.documentType).toBe("corporate_formation_record");
+    expect(parsed.data?.documentTypeConfidence).toBe(0.92);
+  });
+
+  it("a v1-pinned classified item has no document type", () => {
+    const parsed = SourceSyncCandidateItemSchema.safeParse(
+      candidateItem({ sourceClass: "board_minutes" }),
+    );
+    expect(parsed.success).toBe(true);
+    expect(parsed.data?.documentType).toBeNull();
+    expect(parsed.data?.documentTypeConfidence).toBeNull();
+  });
+
+  it("an unclassified line has no document type", () => {
+    const parsed = SourceSyncCandidateItemSchema.safeParse(
+      candidateItem({
+        visibility: "hidden",
+        classificationState: "unclassified",
+        recommendedUse: null,
+        sourceClass: null,
+        included: false,
+        documentType: "strategy_memo",
+        documentTypeConfidence: 0.9,
+      }),
+    );
+    expect(parsed.success).toBe(false);
+    expect(parsed.error?.issues[0]?.message).toBe(
+      "an unclassified line has no document type",
+    );
+  });
+
+  it("a known document type carries a confidence; unknown and absent carry none", () => {
+    for (const [documentType, documentTypeConfidence, ok] of [
+      ["strategy_memo", 0.9, true],
+      ["strategy_memo", null, false],
+      ["unknown", null, true],
+      ["unknown", 0.4, false],
+      [null, null, true],
+      [null, 0.4, false],
+    ] as const) {
+      const parsed = SourceSyncCandidateItemSchema.safeParse(
+        candidateItem({ documentType, documentTypeConfidence }),
+      );
+      expect(parsed.success).toBe(ok);
+      if (!ok) {
+        expect(parsed.error?.issues[0]?.message).toBe(
+          "a known document type carries a confidence; unknown and absent carry none",
+        );
+      }
+    }
+  });
+
+  it("refuses a document type outside the closed set", () => {
+    expect(
+      SourceSyncCandidateItemSchema.safeParse(
+        candidateItem({
+          documentType: "irrelevant_doc",
+          documentTypeConfidence: 0.9,
+        }),
       ).success,
     ).toBe(false);
   });
 
+  it("the document type keys are required", () => {
+    for (const key of ["documentType", "documentTypeConfidence"]) {
+      const item: Record<string, unknown> = candidateItem();
+      delete item[key];
+      expect(SourceSyncCandidateItemSchema.safeParse(item).success).toBe(false);
+    }
+  });
+
   it("a reason whose code belongs to another kind is refused", () => {
     for (const reason of [
       { kind: "lexicon", code: "version_churn", term: "board", count: 1 },
@@ -382,6 +490,37 @@ describe("candidate relevance", () => {
     }
   });
 
+  it("accepts the typed-relevance reason codes", () => {
+    const relevanceReasons = [
+      { kind: "model", code: "type_policy", score: 0.05 },
+      { kind: "model", code: "peek_strategy_evidence_present", score: 0.8 },
+      { kind: "model", code: "peek_strategy_evidence_absent", score: 0.1 },
+      { kind: "evaluation", code: "peek_insufficient_evidence" },
+      { kind: "evaluation", code: "type_disagreement" },
+      { kind: "evaluation", code: "type_below_confidence" },
+      { kind: "evaluation", code: "execution_failed_t1" },
+      { kind: "evaluation", code: "execution_failed_t2" },
+    ];
+    expect(
+      SourceSyncCandidateItemSchema.safeParse(
+        candidateItem({ relevanceReasons }),
+      ).success,
+    ).toBe(true);
+  });
+
+  it("a typed-relevance code under the wrong kind is refused", () => {
+    for (const reason of [
+      { kind: "evaluation", code: "type_policy" },
+      { kind: "model", code: "type_disagreement", score: 0.5 },
+    ]) {
+      expect(
+        SourceSyncCandidateItemSchema.safeParse(
+          candidateItem({ relevanceReasons: [reason] }),
+        ).success,
+      ).toBe(false);
+    }
+  });
+
   it("refuses a lexicon reason without a term or a count, and a model score outside 0..1", () => {
     for (const reason of [
       { kind: "lexicon", code: "title_term", count: 1 },

package/src/source-sync/__tests__/scope-projection.test.ts

@@ -16,12 +16,12 @@ import { DecisionEvidenceRowSchema } from "../../decisions/presentation";
 import {
   SourceSyncApplyResponseSchema,
   SourceSyncApproveResponseSchema,
-  SourceSyncCandidateItemSchema,
   SourceSyncCandidateSetResponseSchema,
   SourceSyncDocChangeSchema,
   SourceSyncScopeApprovalProjectionSchema,
   SourceSyncSynthesisResponseSchema,
 } from "../schemas";
+import { SourceSyncCandidateItemSchema } from "../candidate-item";
 
 const UNIT_SCOPE = "unit:3f1c2d4e-5a6b-4c7d-8e9f-a0b1c2d3e4f5";
 

package/src/source-sync/__tests__/vocabulary.test.ts

@@ -11,6 +11,9 @@
  * - `decoy` is a source class; `unknown` is a sharing breadth
  * - No member string appears in two sets
  * - The four relevance reason code sets are pairwise disjoint
+ * - DOCUMENT_TYPES has exactly its thirty members, `unknown` last; it sits
+ *   OUTSIDE the disjointness table and shares a word with another set only
+ *   where pinned (a structural name on a separate axis)
  */
 
 import { describe, it, expect } from "vitest";
@@ -33,6 +36,7 @@ import {
 
 import {
   AUDIENCE_FITS,
+  DOCUMENT_TYPES,
   SHARING_BREADTHS,
   SOURCE_CLASSES,
   SOURCE_SENSITIVITY_CLASSES,
@@ -175,12 +179,24 @@ const VOCABULARIES = [
       "folder_truncated",
       "explored_t1",
       "explored_t2",
+      "peek_insufficient_evidence",
+      "type_disagreement",
+      "type_below_confidence",
+      "execution_failed_t1",
+      "execution_failed_t2",
     ],
   },
   {
     name: "MODEL_REASON_CODES",
     tuple: MODEL_REASON_CODES,
-    members: ["title_path_score", "peek_confirms", "peek_contradicts"],
+    members: [
+      "title_path_score",
+      "peek_confirms",
+      "peek_contradicts",
+      "type_policy",
+      "peek_strategy_evidence_present",
+      "peek_strategy_evidence_absent",
+    ],
   },
   {
     name: "TARGET_AUDIENCES",
@@ -277,3 +293,59 @@ describe("Source Sync closed sets", () => {
     });
   });
 });
+
+describe("document types", () => {
+  it("has exactly the thirty document types, in order", () => {
+    expect([...DOCUMENT_TYPES]).toEqual([
+      "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",
+    ]);
+    expect(new Set(DOCUMENT_TYPES).size).toBe(30);
+  });
+
+  it("unknown is the last document type", () => {
+    expect(DOCUMENT_TYPES[DOCUMENT_TYPES.length - 1]).toBe("unknown");
+  });
+
+  it("document types share a member with another set only where pinned", () => {
+    const others = new Set<string>(
+      VOCABULARIES.flatMap(({ tuple }) => [...tuple]),
+    );
+    const shared = DOCUMENT_TYPES.filter((t) => others.has(t)).sort();
+    expect(shared).toEqual([
+      "board_deck",
+      "board_minutes",
+      "investor_update",
+      "roadmap",
+      "unknown",
+    ]);
+  });
+});