@company-semantics/contracts 88.2.0 → 89.0.0

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

package/src/source-sync/candidate-item.ts

@@ -0,0 +1,155 @@
+/**
+ * The Source Sync candidate item and its one-edit patch.
+ *
+ * A candidate item is ONE source proposed for ONE target document, because
+ * treatment and landing are source x target (INV-SOURCESYNC-LANDING-PER-TARGET).
+ * It carries facts ABOUT a source and a COUNT of people it is shared with, never
+ * its content and never their addresses. Absent values are `.nullable()`, never
+ * `.optional()`, so a response has one stable shape.
+ *
+ * The patch is a request body and is `.strict()`: an unknown key is an ERROR.
+ *
+ * Split out of `schemas.ts` (which keeps the set response that lists items) so
+ * that file stays within its size envelope.
+ */
+
+import { z } from "zod";
+import { IsoDateTime } from "../api/primitives";
+import {
+  AUDIENCE_FITS,
+  DOCUMENT_TYPES,
+  SHARING_BREADTHS,
+  SOURCE_CLASSES,
+  SOURCE_SENSITIVITY_CLASSES,
+  SOURCE_USES,
+} from "./vocabulary";
+import {
+  CANDIDATE_MACHINE_STATES,
+  CandidateAttentionSchema,
+  CLASSIFICATION_STATES,
+  PERSON_HOLD_REASONS,
+  refineCandidateRelevance,
+  RelevanceReasonSchema,
+  SELECTION_SOURCES,
+  SOURCE_RELEVANCE_TIERS,
+  TARGET_AUDIENCES,
+} from "./relevance";
+
+/** ONE source proposed for ONE target document. */
+export const SourceSyncCandidateItemSchema = z
+  .object({
+    itemId: z.string().uuid(),
+    sourceId: z.string().uuid(),
+    /**
+     * Display facts about the source. Never its content. When `withheld`, `name` is
+     * product copy naming only the source's class and period.
+     */
+    name: z.string().min(1).max(500),
+    mimeType: z.string().min(1).max(255),
+    /** Opens the source IN THE PROVIDER, which remains the ACL authority for it. */
+    webViewLink: z.string().url().nullable(),
+    ownerLabel: z.string().max(255).nullable(),
+    modifiedTime: IsoDateTime.nullable(),
+    /**
+     * True when the caller may not open this source: its identifying fields are
+     * withheld (`webViewLink`, `ownerLabel` and `sharedWithCount` are null, and
+     * `name` and `matchReason` are product copy). What the approver decides stays.
+     */
+    withheld: z.boolean(),
+    /** 'company' or 'unit:<uuid>'. */
+    scopeKey: z.string().min(1).max(64),
+    targetDocId: z.string().uuid(),
+    targetDocTitle: z.string().min(1).max(255),
+    /** The funnel's verdict for the wire: `dropped` never reaches it. Hidden = behind the drawer, undecided. */
+    visibility: z.enum(SOURCE_RELEVANCE_TIERS).exclude(["dropped"]),
+    /** Separate from visibility: a shown line may still await classification (machineState pending_classification). */
+    classificationState: z.enum(CLASSIFICATION_STATES),
+    /** NULL until a classifier has run for this line. */
+    sourceClass: z.enum(SOURCE_CLASSES).nullable(),
+    /**
+     * The RESOLVED document type: what the source IS, after the backend reconciles the model's T1 and
+     * T2 observations deterministically (control ADR source-discovery-observation-vs-policy). A NAME,
+     * never a verdict — the relevance policy it maps to is backend product policy and never on the wire.
+     * NULL on an unclassified line and on every line of a v1-pinned run.
+     */
+    documentType: z.enum(DOCUMENT_TYPES).nullable(),
+    /** Confidence of the resolved type, 0..1. NULL exactly when documentType is null or `unknown`. */
+    documentTypeConfidence: z.number().min(0).max(1).nullable(),
+    periodLabel: z.string().max(64).nullable(),
+    seriesRole: z.enum(["current", "history"]).nullable(),
+    /** The FUSED relevance score (control ADR source-discovery-relevance-funnel), 0..1. */
+    relevance: z.number().min(0).max(1),
+    sensitivityClass: z.enum(SOURCE_SENSITIVITY_CLASSES),
+    sharingBreadth: z.enum(SHARING_BREADTHS),
+    /** A COUNT of people the provider shares it with, when observed. Never addresses. */
+    sharedWithCount: z.number().int().min(0).nullable(),
+    /**
+     * Whether attaching under THIS target would show the source to more people than the provider does.
+     * A REQUIRED key with a NULLABLE value. NULL = not computed yet: discovery writes it null and the
+     * server computes it per source x target when it builds the draft set item. Every consumer reads
+     * null as UNRESOLVED (fail closed) — never as 'fits'.
+     */
+    audienceFit: z.enum(AUDIENCE_FITS).nullable(),
+    /** Machine state: the sensitivity default. NULL until classified — never `excluded` as a stand-in. */
+    recommendedUse: z.enum(SOURCE_USES).nullable(),
+    /** The COMMITTED treatment: null until a person (or an accepted approval default) commits one. */
+    use: z.enum(SOURCE_USES).nullable(),
+    /** Provenance of `use`; null exactly when `use` is null (INV-SOURCESYNC-RECOMMENDATION-IS-NOT-COMMITMENT). */
+    selectionSource: z.enum(SELECTION_SOURCES).nullable(),
+    /** Field-level write barriers a person placed on this line (INV-SOURCESYNC-HOLDS-ARE-FIELD-BARRIERS). */
+    personHoldReasons: z.array(z.enum(PERSON_HOLD_REASONS)).max(4),
+    /** The line's machine lifecycle (INV-SOURCESYNC-SET-IS-RECONCILED). */
+    machineState: z.enum(CANDIDATE_MACHINE_STATES),
+    /** Structured reasons for `relevance`; `matchReason` is rendered from these by the server. */
+    relevanceReasons: z.array(RelevanceReasonSchema).max(16),
+    /** The audience Attach would disclose to. NULL = unknown — reads as MAY WIDEN (INV-SOURCESYNC-ATTACH-SHOWS-ITS-AUDIENCE). */
+    targetAudience: z.enum(TARGET_AUDIENCES).nullable(),
+    /** Which lane earned each model tier's attention (INV-SOURCESYNC-EXPLORATION-RESERVED). */
+    attention: CandidateAttentionSchema,
+    /**
+     * Whether this line is in the set that approval would land — the SERVER's
+     * answer, never derived from `use`. A decoy, a series' history or a line a
+     * person left out is false while its `use` is still null.
+     */
+    included: z.boolean(),
+    /** True while a `widens` item — or one whose fit is not computed yet — has no person-chosen use: approval is refused until none remain. */
+    treatmentUnresolved: z.boolean(),
+    /**
+     * Product-owned copy saying why this file was proposed, rendered by the server from
+     * `relevanceReasons`. Never model-authored prose. Deprecated: removed next release.
+     */
+    matchReason: z.string().min(1).max(500),
+    /** Non-null when the source could not be read (a scanned PDF, an unsupported kind). */
+    unreadableReason: z
+      .enum(["unsupported_type", "needs_ocr", "unsupported_kind"])
+      .nullable(),
+  })
+  .superRefine(refineCandidateRelevance);
+
+/**
+ * One edit to one candidate item: a PATCH names EXACTLY ONE thing that changes, so bringing
+ * a line into review never also commits a treatment.
+ * The SERVER bumps the set's revision on every accepted edit; the client never sends one here.
+ */
+export const SourceSyncCandidateItemPatchSchema = z
+  .object({
+    /** Bring into review: hidden → shown. Changes VISIBILITY ONLY (INV-SOURCESYNC-RECOMMENDATION-IS-NOT-COMMITMENT). */
+    visibility: z.literal("shown").optional(),
+    /** Attach, direction only, or leave out. Choosing one on a `widens` item RESOLVES its treatment. */
+    use: z.enum(SOURCE_USES).optional(),
+    /** Correct the class the classifier chose. */
+    sourceClass: z.enum(SOURCE_CLASSES).optional(),
+    /** Re-route to another target document. The server re-computes audienceFit for the new target. */
+    targetDocId: z.string().uuid().optional(),
+  })
+  .strict()
+  .refine((patch) => Object.keys(patch).length === 1, {
+    message: "a patch changes exactly one thing",
+  });
+
+export type SourceSyncCandidateItem = z.infer<
+  typeof SourceSyncCandidateItemSchema
+>;
+export type SourceSyncCandidateItemPatch = z.infer<
+  typeof SourceSyncCandidateItemPatchSchema
+>;

package/src/source-sync/candidate-totals.ts

@@ -7,10 +7,8 @@
  * with the same function, so no surface counts "files" its own way.
  */
 
-import type {
-  SourceSyncCandidateItem,
-  SourceSyncCandidateTotals,
-} from "./schemas";
+import type { SourceSyncCandidateItem } from "./candidate-item";
+import type { SourceSyncCandidateTotals } from "./schemas";
 
 /** The relevance facts the count reads (control ADR source-discovery-relevance-funnel). */
 type RelevanceFacts = "visibility" | "machineState";

package/src/source-sync/index.ts

@@ -29,6 +29,8 @@ export type {
   SourceSyncDocDisposition,
   SourceSyncScopeApprovalState,
   SourceSyncScopeApproverKind,
+  DocumentType,
+  KnownDocumentType,
 } from "./vocabulary";
 
 export {
@@ -42,6 +44,7 @@ export {
   SOURCE_SYNC_DOC_DISPOSITIONS,
   SOURCE_SYNC_SCOPE_APPROVAL_STATES,
   SOURCE_SYNC_SCOPE_APPROVER_KINDS,
+  DOCUMENT_TYPES,
 } from "./vocabulary";
 
 export type {
@@ -84,11 +87,19 @@ export {
 } from "./relevance";
 
 export type {
-  SourceSyncDiscoveryRunResponse,
   SourceSyncCandidateItem,
+  SourceSyncCandidateItemPatch,
+} from "./candidate-item";
+
+export {
+  SourceSyncCandidateItemSchema,
+  SourceSyncCandidateItemPatchSchema,
+} from "./candidate-item";
+
+export type {
+  SourceSyncDiscoveryRunResponse,
   SourceSyncCandidateSetResponse,
   SourceSyncCandidateTotals,
-  SourceSyncCandidateItemPatch,
   SourceSyncAddCandidateRequest,
   SourceSyncApproveRequest,
   SourceSyncScopeApproval,
@@ -107,10 +118,8 @@ export type {
 export {
   SOURCE_SYNC_RISK_REASONS,
   SourceSyncDiscoveryRunResponseSchema,
-  SourceSyncCandidateItemSchema,
   SourceSyncCandidateSetResponseSchema,
   SourceSyncCandidateTotalsSchema,
-  SourceSyncCandidateItemPatchSchema,
   SourceSyncAddCandidateRequestSchema,
   SourceSyncApproveRequestSchema,
   SourceSyncScopeApprovalSchema,

package/src/source-sync/relevance.ts

@@ -51,7 +51,11 @@ export const SIGNAL_REASON_CODES = [
 ] as const;
 export type SignalReasonCode = (typeof SIGNAL_REASON_CODES)[number];
 
-/** What was NOT evaluated, or was explored. Never negative evidence (INV-SOURCESYNC-MISSING-EVIDENCE-IS-NOT-EVIDENCE). */
+/**
+ * What was NOT evaluated, or was explored, or could not be decided. Never negative evidence
+ * (INV-SOURCESYNC-MISSING-EVIDENCE-IS-NOT-EVIDENCE; INV-SOURCESYNC-NONEXECUTION-IS-NOT-NEGATIVE-EVIDENCE):
+ * an `execution_failed_*` tier (timeout, budget, provider, parse) reads as uncertainty, never as irrelevance.
+ */
 export const EVALUATION_REASON_CODES = [
   "not_evaluated_t1",
   "not_evaluated_t2",
@@ -59,14 +63,26 @@ export const EVALUATION_REASON_CODES = [
   "folder_truncated",
   "explored_t1",
   "explored_t2",
+  "peek_insufficient_evidence",
+  "type_disagreement",
+  "type_below_confidence",
+  "execution_failed_t1",
+  "execution_failed_t2",
 ] as const;
 export type EvaluationReasonCode = (typeof EVALUATION_REASON_CODES)[number];
 
-/** A model tier's contribution. */
+/**
+ * A model tier's contribution. `type_policy` carries the POLICY-APPLIED score of the resolved document
+ * type (control ADR source-discovery-observation-vs-policy). The peek verdict is domain-named:
+ * strategy evidence present / absent. `peek_confirms` / `peek_contradicts` stay for v1-pinned rows.
+ */
 export const MODEL_REASON_CODES = [
   "title_path_score",
   "peek_confirms",
   "peek_contradicts",
+  "type_policy",
+  "peek_strategy_evidence_present",
+  "peek_strategy_evidence_absent",
 ] as const;
 export type ModelReasonCode = (typeof MODEL_REASON_CODES)[number];
 
@@ -173,12 +189,16 @@ type CandidateRelevanceFacts = {
   sourceClass: string | null;
   use: string | null;
   selectionSource: SelectionSource | null;
+  documentType: string | null;
+  documentTypeConfidence: number | null;
 };
 
 /**
  * The candidate item's cross-field rules (control ADR source-discovery-relevance-funnel):
  * a hidden line is never included; classification decides whether a recommendation and a
- * class exist; `selectionSource` is present exactly when a treatment is committed.
+ * class exist; `selectionSource` is present exactly when a treatment is committed. A
+ * document type exists only on a classified line, and carries a confidence exactly when
+ * it is a known type (control ADR source-discovery-observation-vs-policy).
  */
 export function refineCandidateRelevance(
   item: CandidateRelevanceFacts,
@@ -213,4 +233,19 @@ export function refineCandidateRelevance(
       message: "selectionSource is present exactly when use is",
     });
   }
+  if (item.documentType !== null && unclassified) {
+    ctx.addIssue({
+      code: "custom",
+      message: "an unclassified line has no document type",
+    });
+  }
+  const knownType =
+    item.documentType !== null && item.documentType !== "unknown";
+  if (knownType !== (item.documentTypeConfidence !== null)) {
+    ctx.addIssue({
+      code: "custom",
+      message:
+        "a known document type carries a confidence; unknown and absent carry none",
+    });
+  }
 }