@company-semantics/contracts 88.2.0 → 89.1.0

package/src/generated/openapi-routes.ts

@@ -93,11 +93,29 @@ export const openApiRoutes = {
   '/api/executions/{executionId}/undo': ['POST'],
   '/api/factory/floor': ['GET'],
   '/api/factory/kpis': ['GET'],
+  '/api/factory/quality/changes': ['POST'],
+  '/api/factory/quality/corpus': ['GET'],
+  '/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'],
   '/api/internal-admin/impersonate/session': ['GET'],
   '/api/internal-admin/impersonate/start': ['POST'],
+  '/api/internal-admin/quality/blocked': ['GET'],
+  '/api/internal-admin/quality/candidates': ['GET'],
+  '/api/internal-admin/quality/candidates/{id}': ['GET'],
+  '/api/internal-admin/quality/candidates/{id}/accept': ['POST'],
+  '/api/internal-admin/quality/candidates/{id}/reject': ['POST'],
+  '/api/internal-admin/quality/changes/manual': ['POST'],
+  '/api/internal-admin/quality/escalations': ['GET'],
+  '/api/internal-admin/quality/escalations/{id}/resolve': ['POST'],
+  '/api/internal-admin/quality/plans/{planId}/status': ['GET'],
+  '/api/internal-admin/quality/references/floor': ['PUT'],
+  '/api/internal-admin/quality/spend': ['GET'],
+  '/api/internal-admin/quality/subjects': ['GET'],
+  '/api/internal-admin/quality/subjects/{subjectKind}/{subjectKey}/timeline': ['GET'],
   '/api/me': ['GET'],
   '/api/me/access-list': ['GET'],
   '/api/me/action-items': ['GET'],
@@ -152,6 +170,7 @@ export const openApiRoutes = {
   '/api/org/cancel-deletion': ['POST'],
   '/api/org/delete': ['POST'],
   '/api/org/deletion-eligibility': ['GET'],
+  '/api/org/improve-with-usage': ['GET', 'PUT'],
   '/api/org/reconciliation': ['GET'],
   '/api/org/reconciliation/divergences/{divergenceId}/resolution': ['POST'],
   '/api/org/structure-findings': ['GET'],

package/src/message-parts/README.md

@@ -91,6 +91,9 @@ Canonical vocabulary for structured assistant message output. Defines the type s
 - `UndoResultData` _(type)_ — Undo result data payload.
 - `UndoResultDataPart` _(type)_ — Undo result data part (wire format).
 - `WireSurfaceBuilder` — Factory for creating wire-format surface parts.
+- `WorkflowOutcomeData` _(type)_ — Workflow outcome data payload: which workflow, and how its epoch ended.
+- `WorkflowOutcomeDataPart` _(type)_ — Workflow outcome data part (wire format, as persisted in `chat_messages.parts`).
+- `WorkflowOutcomePart` _(type)_ — Workflow outcome message part (semantic type, as rendered).
 - `WorkflowProgressData` _(type)_ — Workflow progress surface data payload — the anchor's handle and its discriminator.
 - `WorkflowProgressDataPart` _(type)_ — Workflow progress data part (wire format, as persisted in `chat_messages.parts`).
 - `WorkflowProgressPart` _(type)_ — Workflow progress message part (semantic type, as rendered).

package/src/message-parts/__tests__/workflow-outcome.test.ts

@@ -0,0 +1,41 @@
+import { describe, expect, it } from "vitest";
+
+import { WireSurfaceBuilder } from "../wire";
+import type { WorkflowOutcomeData } from "../workflow-outcome";
+
+describe("WireSurfaceBuilder.workflowOutcome", () => {
+  const data: WorkflowOutcomeData = {
+    workflowId: "3f1c2d4e-0000-0000-0000-000000000000",
+    outcome: {
+      workflowType: "source-sync/discover",
+      executionEpoch: 0,
+      kind: "empty",
+      reason: "nothing_found",
+      facts: {
+        probesTotal: 12,
+        probesDone: 12,
+        filesSeen: 0,
+        filesShown: 0,
+        filesHidden: 0,
+        filesDropped: 0,
+        coveragePercent: 100,
+      },
+      disposition: { kind: "narrate" },
+    },
+  };
+
+  it("returns a data-workflow-outcome part carrying the data verbatim", () => {
+    const part = WireSurfaceBuilder.workflowOutcome(data);
+    expect(part.type).toBe("data-workflow-outcome");
+    expect(part.data).toEqual(data);
+  });
+
+  // Non-governed: nothing on the payload makes it count against the
+  // at-most-one-governed-surface-per-turn budget.
+  it("carries no governed-surface fields", () => {
+    const part = WireSurfaceBuilder.workflowOutcome(data);
+    expect(Object.keys(part.data).sort()).toEqual(["outcome", "workflowId"]);
+    expect(part.data).not.toHaveProperty("executionId");
+    expect(part.data).not.toHaveProperty("submitEndpoint");
+  });
+});

package/src/message-parts/index.ts

@@ -90,6 +90,13 @@ export type {
   WorkflowProgressDataPart,
 } from "./workflow-progress";
 
+// Workflow outcome types (non-governed, the frozen outcome on a settlement message)
+export type {
+  WorkflowOutcomeData,
+  WorkflowOutcomePart,
+  WorkflowOutcomeDataPart,
+} from "./workflow-outcome";
+
 // Execution result types
 export type {
   ExecutionArtifactStatus,

package/src/message-parts/types.ts

@@ -21,6 +21,7 @@ import type { StructureReviewPart } from "./structure-review";
 import type { InputRequestPart } from "./input-request";
 import type { SuggestedRepliesPart } from "./suggested-replies";
 import type { WorkflowProgressPart } from "./workflow-progress";
+import type { WorkflowOutcomePart } from "./workflow-outcome";
 
 // =============================================================================
 // Narrative Parts (Streamable)
@@ -125,6 +126,10 @@ export interface TablePart {
  * background workflow to the occurrence and presents no decision, so it must
  * not consume the governed-surface budget either.
  *
+ * WorkflowOutcomePart is the third non-governed member: the frozen outcome of a
+ * workflow's execution epoch, carried on its settlement message. It presents no
+ * decision; a review disposition is delivered as its own InputRequestPart.
+ *
  * InputRequestPart is GOVERNED, like StructureReviewPart: it anchors a reviewed
  * request that asks the person to decide, so it counts against the
  * at-most-one-governed-surface-per-turn budget. It is the generic anchor;
@@ -142,7 +147,8 @@ export type SurfacePart =
   | StructureReviewPart
   | InputRequestPart
   | SuggestedRepliesPart
-  | WorkflowProgressPart;
+  | WorkflowProgressPart
+  | WorkflowOutcomePart;
 
 /**
  * All assistant message part types.

package/src/message-parts/wire.ts

@@ -35,6 +35,10 @@ import type {
   WorkflowProgressData,
   WorkflowProgressDataPart,
 } from "./workflow-progress";
+import type {
+  WorkflowOutcomeData,
+  WorkflowOutcomeDataPart,
+} from "./workflow-outcome";
 import type {
   ExecutionResultData,
   ExecutionResultDataPart,
@@ -246,6 +250,28 @@ export const WireSurfaceBuilder = {
     };
   },
 
+  /**
+   * Build a workflow-outcome data part for a settlement message.
+   * The frozen outcome of one execution epoch, written once at settlement
+   * (control ADR-CTRL-540).
+   *
+   * INVARIANTS:
+   * - Not a governed surface: presents no decision
+   * - The outcome is the classified, immutable value; nothing re-derives it
+   * - Counts and closed codes only, so it is safe on share-visible parts
+   * - Emission is orchestration-driven (settlement delivery), never a model
+   *   choice
+   *
+   * @param data - Workflow outcome data (workflowId + frozen outcome)
+   * @returns Wire-format workflow outcome part
+   */
+  workflowOutcome(data: WorkflowOutcomeData): WorkflowOutcomeDataPart {
+    return {
+      type: "data-workflow-outcome",
+      data,
+    };
+  },
+
   /**
    * Build an execution result data part for streaming.
    * Reports the outcome of an executed action.

package/src/message-parts/workflow-outcome.ts

@@ -0,0 +1,54 @@
+/**
+ * Workflow Outcome Part Types
+ *
+ * The settled outcome of one execution epoch of a durable background workflow,
+ * carried on the settlement message the server writes into the conversation
+ * that launched the workflow (control ADR-CTRL-540). It is the durable,
+ * conversation-level EVIDENCE of how the run ended: the deterministic narration
+ * beside it is built from exactly this value, and a later turn ("what
+ * happened?") is grounded in it.
+ *
+ * WORKFLOW OUTCOME INVARIANTS:
+ * - WRITTEN ONCE, AT SETTLEMENT. Unlike `data-workflow-progress`, which is
+ *   minted at t=0 and so must carry no result, this part is minted only after
+ *   the outcome is frozen, on a message of its own. It can never be stale.
+ * - THE FROZEN OUTCOME, VERBATIM. `outcome` is the value the backend classified
+ *   atomically with the terminal transition. Nothing re-derives it.
+ * - SHARE-SAFE. Chat parts reach token-only share readers verbatim, so the
+ *   outcome holds counts and closed codes only (see `../workflows/outcome.ts`).
+ * - NON-GOVERNED. It presents no decision: no `executionId`, no
+ *   `submitEndpoint`. A `review` disposition is delivered as its own input
+ *   request anchor, not through this part.
+ * - Emission is orchestration-driven (settlement delivery), never a model
+ *   choice.
+ *
+ * Purely additive: an app that predates this part normalizes unknown part types
+ * to null, drops it, and still renders the narration text.
+ *
+ * @see ../workflows/outcome.ts for the outcome vocabulary
+ */
+
+import type { WorkflowOutcome } from "../workflows/outcome";
+
+/** Workflow outcome data payload: which workflow, and how its epoch ended. */
+export interface WorkflowOutcomeData {
+  /** The durable workflow the outcome settles. */
+  workflowId: string;
+  /** The frozen, typed outcome (carries its workflow type and epoch). */
+  outcome: WorkflowOutcome;
+}
+
+/** Workflow outcome message part (semantic type, as rendered). */
+export interface WorkflowOutcomePart {
+  type: "workflow-outcome";
+  data: WorkflowOutcomeData;
+}
+
+/**
+ * Workflow outcome data part (wire format, as persisted in
+ * `chat_messages.parts`). Uses AI SDK's data-{name} convention.
+ */
+export interface WorkflowOutcomeDataPart {
+  type: "data-workflow-outcome";
+  data: WorkflowOutcomeData;
+}

package/src/root-exports/agent-runtime.ts

@@ -93,6 +93,10 @@ export type {
   WorkflowProgressData,
   WorkflowProgressPart,
   WorkflowProgressDataPart,
+  // Workflow outcome types (non-governed, frozen outcome on a settlement message, ADR-CTRL-540)
+  WorkflowOutcomeData,
+  WorkflowOutcomePart,
+  WorkflowOutcomeDataPart,
   // Execution result types (Phase 5)
   ExecutionArtifactStatus,
   ExecutionResultSummary,

package/src/root-exports/delivery.ts

@@ -216,3 +216,39 @@ export type {
 export { ANALYSIS_WORKFLOW_TYPES, isWorkflowType } from "../workflows/index";
 
 export type { WorkflowType } from "../workflows/index";
+
+// The typed outcome of a workflow's terminal transition (control ADR-CTRL-540):
+// per-type closed reasons, typed facts and an explicit disposition, classified
+// once by the backend and frozen. See src/workflows/outcome.ts.
+export {
+  DISCOVER_OUTCOME_KIND_OF_REASON,
+  DiscoverOutcomeFactsSchema,
+  DiscoverWorkflowOutcomeSchema,
+  HrisConnectWorkflowOutcomeSchema,
+  ORG_STRUCTURE_OUTCOME_KIND_OF_REASON,
+  OrgStructureOutcomeFactsSchema,
+  ReanalyzeWorkflowOutcomeSchema,
+  SYNTHESIZE_OUTCOME_KIND_OF_REASON,
+  SynthesizeOutcomeFactsSchema,
+  SynthesizeWorkflowOutcomeSchema,
+  WORKFLOW_OUTCOME_KINDS,
+  WorkflowOutcomeDispositionSchema,
+  WorkflowOutcomeSchema,
+} from "../workflows/index";
+
+export type {
+  DiscoverOutcomeFacts,
+  DiscoverOutcomeReason,
+  DiscoverWorkflowOutcome,
+  HrisConnectWorkflowOutcome,
+  OrgStructureOutcomeFacts,
+  OrgStructureOutcomeReason,
+  ReanalyzeWorkflowOutcome,
+  SynthesizeOutcomeFacts,
+  SynthesizeOutcomeReason,
+  SynthesizeWorkflowOutcome,
+  WorkflowOutcome,
+  WorkflowOutcomeDisposition,
+  WorkflowOutcomeKind,
+  WorkflowOutcomeOf,
+} from "../workflows/index";

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