@company-semantics/contracts 83.2.0 → 84.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@company-semantics/contracts",
-  "version": "83.2.0",
+  "version": "84.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 = 'ed793823fd73' as const;
-export const SPEC_HASH_FULL = 'ed793823fd7383fa2708a90aca342dd575fcc636aa8286958832e4096f032745' as const;
+export const SPEC_HASH = '53f462b4c90b' as const;
+export const SPEC_HASH_FULL = '53f462b4c90ba419e71d55d82e19bb6a9836d95aeaaae6299b8124ac340320d8' as const;

package/src/api/generated.ts

@@ -8876,7 +8876,10 @@ export interface components {
                 targetDocId: string;
                 targetDocTitle: string;
                 /** @enum {string} */
-                sourceClass: "board_deck" | "board_minutes" | "investor_update" | "financial_brief" | "budget_forecast" | "okr_plan" | "annual_plan" | "all_hands" | "unit_strategy" | "roadmap" | "qbr" | "other" | "decoy";
+                visibility: "hidden" | "shown";
+                /** @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;
                 periodLabel: string | null;
                 seriesRole: ("current" | "history") | null;
                 relevance: number;
@@ -8886,9 +8889,42 @@ export interface components {
                 sharingBreadth: "restricted_few" | "group" | "domain" | "anyone" | "unknown";
                 sharedWithCount: number | null;
                 audienceFit: ("fits" | "widens") | null;
-                /** @enum {string} */
-                recommendedUse: "attached" | "direction_only" | "excluded";
+                recommendedUse: ("attached" | "direction_only" | "excluded") | null;
                 use: ("attached" | "direction_only" | "excluded") | null;
+                selectionSource: ("person" | "approval_default") | null;
+                personHoldReasons: ("relevance_override" | "treatment_selection" | "target_override" | "manual_add")[];
+                /** @enum {string} */
+                machineState: "fresh" | "refreshed" | "filtered_out" | "not_rediscovered" | "pending_classification" | "retired";
+                relevanceReasons: ({
+                    /** @constant */
+                    kind: "lexicon";
+                    /** @enum {string} */
+                    code: "title_term" | "folder_term" | "negative_title_term" | "negative_folder_term";
+                    term: string;
+                    count: number;
+                } | {
+                    /** @constant */
+                    kind: "signal";
+                    /** @enum {string} */
+                    code: "folder_probe_hit" | "title_probe_hit" | "version_churn" | "mime_class" | "size_band" | "dated_series" | "recent_edit" | "owner_unit_head" | "owner_executive" | "sharing_breadth" | "duplicate_title" | "personal_mime";
+                    value: number | null;
+                } | {
+                    /** @constant */
+                    kind: "evaluation";
+                    /** @enum {string} */
+                    code: "not_evaluated_t1" | "not_evaluated_t2" | "folder_unresolved" | "folder_truncated" | "explored_t1" | "explored_t2";
+                } | {
+                    /** @constant */
+                    kind: "model";
+                    /** @enum {string} */
+                    code: "title_path_score" | "peek_confirms" | "peek_contradicts";
+                    score: number | null;
+                })[];
+                targetAudience: ("restricted" | "unit" | "org_wide") | null;
+                attention: {
+                    t1: ("exploit" | "explore") | null;
+                    t2: ("exploit" | "explore") | null;
+                };
                 included: boolean;
                 treatmentUnresolved: boolean;
                 matchReason: string;
@@ -8931,6 +8967,9 @@ export interface components {
                 files: number;
                 filesIncluded: number;
                 filesNeedingChoice: number;
+                filesHidden: number;
+                filesNotRediscovered: number;
+                filesPendingClassification: number;
             };
             scopes: {
                 scopeKey: string;
@@ -8953,6 +8992,16 @@ export interface components {
                 highMicroUsd: string;
                 capMicroUsd: string;
             } | null;
+            discovery: {
+                foundThisRun: number;
+                retainedDecisions: number;
+                notRediscovered: number;
+                pendingClassification: number;
+                filesDropped: number;
+                coveragePercent: number;
+                /** @enum {string} */
+                scanOutcome: "complete" | "budget_exhausted" | "file_ceiling" | "stopped";
+            } | null;
         };
         SourceSyncApproveResponse: {
             /** Format: uuid */
@@ -17884,6 +17933,8 @@ export interface operations {
         requestBody: {
             content: {
                 "application/json": {
+                    /** @constant */
+                    visibility?: "shown";
                     /** @enum {string} */
                     use?: "attached" | "direction_only" | "excluded";
                     /** @enum {string} */

package/src/source-sync/README.md

@@ -107,6 +107,54 @@ way. This directory holds that shared spelling.
   domain is the largest trust change in the wave, and an empty body is
   indistinguishable from a mistaken or replayed body-less POST.
 
+## Relevance
+
+Doctrine: control ADR `source-discovery-relevance-funnel`. Vocabulary: ADR
+`source-discovery-relevance-vocabulary`. The sets live in `relevance.ts`.
+
+- **Two axes on the wire.**
+  - **Relevance** is the funnel's verdict: `visibility` is `shown` or
+    `hidden`.
+  - **Treatment** is a person's decision: `recommendedUse` (machine state,
+    null until classified), `use` (the committed treatment, null until
+    chosen) and `selectionSource` (`person` or `approval_default`, present
+    exactly when `use` is).
+
+  Neither axis changes the other. The disclosure question is asked only of
+  lines that cleared relevance.
+
+- **Hidden is not dropped.** `SOURCE_RELEVANCE_TIERS` includes `dropped` so the
+  backend can mirror it in persistence, but the item schema excludes it: a
+  dropped sighting never reaches the wire. A hidden line sits behind the
+  drawer, is never `included`, and a person can bring it into review with the
+  patch `{ visibility: "shown" }`. The patch changes exactly one field, so
+  promoting a line never also commits a treatment, and no client can hide a
+  line.
+- **Classification is separate from visibility.** `classificationState` is
+  `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
+  `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
+  switches over `kind`, then `code`, exhaustively. `relevance` is the fused
+  score, and `matchReason` is server copy rendered from the reasons
+  (deprecated).
+- **Holds and lifecycle travel on the item.** `personHoldReasons` are the
+  field-level barriers a person's actions placed on the line. `machineState`
+  is its lifecycle (`fresh`, `refreshed`, `filtered_out`, `not_rediscovered`,
+  `pending_classification`, `retired`). `attention` says which lane
+  (`exploit` or `explore`) earned each model tier's look.
+- **Attach shows its audience.** `targetAudience` is the audience Attach would
+  disclose to. Null means unknown and reads as "may widen".
+- **No single ambiguous total.** `discovery` on the set response carries the
+  last completed run's counts (found, retained decisions, not rediscovered,
+  pending classification, dropped, coverage and how the scan ended). It is
+  null before any run completes. `totals` adds `filesHidden`,
+  `filesNotRediscovered` and `filesPendingClassification`, counted by
+  `candidateTotalsOf` over distinct files.
+
 ## Public API
 
 - `SOURCE_CLASSES` / `SourceClass` — what kind of document a source is.
@@ -135,7 +183,16 @@ way. This directory holds that shared spelling.
   `candidateTotalsOf(items)` — THE file count: distinct `sourceId`, never lines
   (ADR-CONTRACTS-195).
 - `SourceSyncCandidateItemPatchSchema` / `SourceSyncCandidateItemPatch` — one
-  edit to one candidate item (use, class or target); never empty.
+  edit to one candidate item: exactly one of visibility (`shown` only), use,
+  class or target.
+- `SOURCE_RELEVANCE_TIERS`, `CLASSIFICATION_STATES`, `RELEVANCE_REASON_KINDS`,
+  `LEXICON_REASON_CODES`, `SIGNAL_REASON_CODES`, `EVALUATION_REASON_CODES`,
+  `MODEL_REASON_CODES`, `TARGET_AUDIENCES`, `ATTENTION_LANES`,
+  `CANDIDATE_MACHINE_STATES`, `SELECTION_SOURCES`, `PERSON_HOLD_REASONS`,
+  `SCAN_OUTCOMES` and their derived unions — the relevance vocabulary (see
+  Relevance).
+- `RelevanceReasonSchema` / `RelevanceReason` — why a candidate scored as it
+  did: a discriminated union on `kind`.
 - `SourceSyncAddCandidateRequestSchema` / `SourceSyncAddCandidateRequest` —
   "add one I missed": a provider file id picked in the provider's own search.
 - `SourceSyncApproveRequestSchema` / `SourceSyncApproveRequest` — approve the
@@ -210,4 +267,5 @@ way. This directory holds that shared spelling.
 
 `rules.ts` imports only `zod`, `../api/primitives` and `./vocabulary`.
 `upkeep.ts` and `reach.ts` import only `zod` and `../api/primitives`.
+`relevance.ts` imports only `zod`.
 `vocabulary.ts` itself has no imports.

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

@@ -5,8 +5,8 @@
  * backend answers with.
  *
  * INVARIANTS TESTED:
- * - A candidate patch changes something: an empty patch is refused, and an
- *   unknown key is an error, not surplus.
+ * - A candidate patch changes exactly one thing: an empty patch is refused, and
+ *   an unknown key is an error, not surplus.
  * - An approval echoes the revision the person reviewed and carries the spend
  *   cap as integer micro-USD; either one missing is refused.
  * - An approval answers PER SCOPE: one row per scope approved, each bound to its

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

@@ -16,6 +16,8 @@
  *   below, which fails typecheck if one is missing at the root).
  * - The same two checks hold for the Release D names: staleness findings,
  *   standing orders and the Drive-reach shapes.
+ * - Every runtime name `relevance.ts` declares is reachable from the root as
+ *   the same binding.
  * - `ACTION_ITEM_KINDS` at the root carries `sourceSync.approval_pending`.
  * - The root re-exports the domain barrel explicitly.
  *
@@ -66,6 +68,7 @@ import type {
   SourceSyncStandingOrdersResponse,
 } from "../../index";
 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";
@@ -236,6 +239,17 @@ describe("source-sync Release C package surface", () => {
     }
   });
 
+  it("every discovery relevance set is exported from the package root", () => {
+    const root = rootBarrel as Record<string, unknown>;
+    const names = Object.keys(relevance);
+    expect(names.length).toBeGreaterThan(0);
+    for (const name of names) {
+      expect(root[name], `${name} at the root`).toBe(
+        (relevance as Record<string, unknown>)[name],
+      );
+    }
+  });
+
   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__/candidate-totals.test.ts

@@ -0,0 +1,119 @@
+/**
+ * The one file count for a candidate review.
+ *
+ * INVARIANTS TESTED:
+ * - Every total counts DISTINCT files (`sourceId`), never lines: a file routed to
+ *   two documents is two lines and one file in every total.
+ * - A file is hidden only when EVERY line of it is hidden; one shown line shows it.
+ * - A file is not rediscovered / pending classification when ANY line of it is.
+ */
+
+import { describe, expect, it } from "vitest";
+import { candidateTotalsOf, type CandidateTotalsInput } from "../index";
+
+function line(
+  sourceId: string,
+  overrides: Partial<CandidateTotalsInput> = {},
+): CandidateTotalsInput {
+  return {
+    sourceId,
+    included: true,
+    treatmentUnresolved: false,
+    visibility: "shown",
+    machineState: "fresh",
+    ...overrides,
+  };
+}
+
+describe("candidateTotalsOf", () => {
+  it("counts distinct files, never lines", () => {
+    expect(
+      candidateTotalsOf([
+        line("a", { treatmentUnresolved: true }),
+        line("a"),
+        line("b", { included: false, treatmentUnresolved: true }),
+        line("c"),
+      ]),
+    ).toEqual({
+      files: 3,
+      filesIncluded: 2,
+      filesNeedingChoice: 1,
+      filesHidden: 0,
+      filesNotRediscovered: 0,
+      filesPendingClassification: 0,
+    });
+  });
+
+  it("a file is hidden only when every line of it is hidden", () => {
+    const hidden = { visibility: "hidden", included: false } as const;
+    const totals = candidateTotalsOf([
+      line("partly", hidden),
+      line("partly"),
+      line("wholly", hidden),
+      line("wholly", hidden),
+      line("shown"),
+    ]);
+    expect(totals.files).toBe(3);
+    expect(totals.filesHidden).toBe(1);
+    expect(totals.filesIncluded).toBe(2);
+  });
+
+  it("a file is not rediscovered or pending classification when any line of it is", () => {
+    const totals = candidateTotalsOf([
+      line("a", { machineState: "not_rediscovered" }),
+      line("a", { machineState: "refreshed" }),
+      line("b", { machineState: "pending_classification" }),
+      line("b"),
+      line("c", { machineState: "retired" }),
+    ]);
+    expect(totals.filesNotRediscovered).toBe(1);
+    expect(totals.filesPendingClassification).toBe(1);
+  });
+
+  it("a file routed to two documents counts once in every total", () => {
+    const facts = {
+      treatmentUnresolved: true,
+      visibility: "hidden",
+      machineState: "not_rediscovered",
+      included: false,
+    } as const;
+    const hiddenTwice = candidateTotalsOf([line("a", facts), line("a", facts)]);
+    expect(hiddenTwice).toEqual({
+      files: 1,
+      filesIncluded: 0,
+      filesNeedingChoice: 0,
+      filesHidden: 1,
+      filesNotRediscovered: 1,
+      filesPendingClassification: 0,
+    });
+    const shownTwice = candidateTotalsOf([
+      line("a", {
+        treatmentUnresolved: true,
+        machineState: "pending_classification",
+      }),
+      line("a", {
+        treatmentUnresolved: true,
+        machineState: "pending_classification",
+      }),
+    ]);
+    expect(shownTwice).toEqual({
+      files: 1,
+      filesIncluded: 1,
+      filesNeedingChoice: 1,
+      filesHidden: 0,
+      filesNotRediscovered: 0,
+      filesPendingClassification: 1,
+    });
+  });
+
+  it("counts nothing for an empty review", () => {
+    expect(candidateTotalsOf([])).toEqual({
+      files: 0,
+      filesIncluded: 0,
+      filesNeedingChoice: 0,
+      filesHidden: 0,
+      filesNotRediscovered: 0,
+      filesPendingClassification: 0,
+    });
+  });
+});

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

@@ -11,11 +11,19 @@
  * - The wire carries a COUNT of people a source is shared with, never addresses.
  * - Money is integer micro-USD strings; a decimal or a JSON number is refused.
  * - A candidate set carries presented questions, never decision effects.
+ * - 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.
+ * - 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.
+ * - The set response's discovery block is required and null before any completed run.
  */
 
 import { describe, expect, it } from "vitest";
 import {
-  candidateTotalsOf,
+  RelevanceReasonSchema,
+  SourceSyncCandidateItemPatchSchema,
   SourceSyncCandidateItemSchema,
   SourceSyncCandidateSetResponseSchema,
   SourceSyncDiscoveryRunResponseSchema,
@@ -41,6 +49,8 @@ function candidateItem(overrides: Record<string, unknown> = {}) {
     scopeKey: "company",
     targetDocId: TARGET_DOC_ID,
     targetDocTitle: "Company overview",
+    visibility: "shown",
+    classificationState: "classified",
     sourceClass: "board_deck",
     periodLabel: "Q3 2026",
     seriesRole: "current",
@@ -51,6 +61,12 @@ function candidateItem(overrides: Record<string, unknown> = {}) {
     audienceFit: "fits",
     recommendedUse: "direction_only",
     use: null,
+    selectionSource: null,
+    personHoldReasons: [],
+    machineState: "fresh",
+    relevanceReasons: [],
+    targetAudience: "org_wide",
+    attention: { t1: null, t2: null },
     included: true,
     treatmentUnresolved: false,
     matchReason: "A board deck for the current quarter.",
@@ -98,13 +114,29 @@ function candidateSet(overrides: Record<string, unknown> = {}) {
     items: [candidateItem()],
     questions: [presentedQuestion()],
     withheldQuestionCount: 0,
-    totals: { files: 1, filesIncluded: 1, filesNeedingChoice: 0 },
+    totals: {
+      files: 1,
+      filesIncluded: 1,
+      filesNeedingChoice: 0,
+      filesHidden: 0,
+      filesNotRediscovered: 0,
+      filesPendingClassification: 0,
+    },
     scopes: [],
     estimate: {
       lowMicroUsd: "250000",
       highMicroUsd: "1250000",
       capMicroUsd: "2000000",
     },
+    discovery: {
+      foundThisRun: 12,
+      retainedDecisions: 3,
+      notRediscovered: 1,
+      pendingClassification: 2,
+      filesDropped: 240,
+      coveragePercent: 87,
+      scanOutcome: "complete",
+    },
     ...overrides,
   };
 }
@@ -260,6 +292,208 @@ describe("SourceSyncCandidateSetResponseSchema", () => {
   });
 });
 
+describe("candidate relevance", () => {
+  it("a hidden unclassified item has no recommendation, no class and is not included", () => {
+    const parsed = SourceSyncCandidateItemSchema.safeParse(
+      candidateItem({
+        visibility: "hidden",
+        classificationState: "unclassified",
+        recommendedUse: null,
+        sourceClass: null,
+        included: false,
+        targetAudience: null,
+        machineState: "pending_classification",
+      }),
+    );
+    expect(parsed.success).toBe(true);
+    expect(parsed.data?.recommendedUse).toBeNull();
+    expect(parsed.data?.sourceClass).toBeNull();
+    for (const claim of [
+      { recommendedUse: "attached" },
+      { sourceClass: "board_deck" },
+    ]) {
+      expect(
+        SourceSyncCandidateItemSchema.safeParse(
+          candidateItem({
+            visibility: "hidden",
+            classificationState: "unclassified",
+            recommendedUse: null,
+            sourceClass: null,
+            included: false,
+            ...claim,
+          }),
+        ).success,
+      ).toBe(false);
+    }
+  });
+
+  it("a classified item has a recommendation and a class", () => {
+    for (const missing of [{ recommendedUse: null }, { sourceClass: null }]) {
+      expect(
+        SourceSyncCandidateItemSchema.safeParse(candidateItem(missing)).success,
+      ).toBe(false);
+    }
+  });
+
+  it("a shown item carries a reason of every kind", () => {
+    const relevanceReasons = [
+      { kind: "lexicon", code: "title_term", term: "board", count: 2 },
+      { kind: "signal", code: "version_churn", value: 41 },
+      { kind: "signal", code: "owner_executive", value: null },
+      { kind: "evaluation", code: "not_evaluated_t2" },
+      { kind: "model", code: "title_path_score", score: 0.81 },
+      { kind: "model", code: "peek_confirms", score: null },
+    ];
+    const parsed = SourceSyncCandidateItemSchema.safeParse(
+      candidateItem({
+        relevanceReasons,
+        attention: { t1: "exploit", t2: "explore" },
+        personHoldReasons: ["relevance_override"],
+      }),
+    );
+    expect(parsed.success).toBe(true);
+    expect(parsed.data?.relevanceReasons.map((reason) => reason.kind)).toEqual([
+      "lexicon",
+      "signal",
+      "signal",
+      "evaluation",
+      "model",
+      "model",
+    ]);
+  });
+
+  it("refuses more than eight reasons", () => {
+    const reason = { kind: "evaluation", code: "explored_t1" };
+    expect(
+      SourceSyncCandidateItemSchema.safeParse(
+        candidateItem({ relevanceReasons: Array(9).fill(reason) }),
+      ).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 },
+      { kind: "signal", code: "title_term", value: 1 },
+      { kind: "evaluation", code: "peek_confirms" },
+      { kind: "model", code: "folder_unresolved", score: 0.5 },
+    ]) {
+      expect(RelevanceReasonSchema.safeParse(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 },
+      { kind: "lexicon", code: "title_term", term: "", count: 1 },
+      { kind: "lexicon", code: "title_term", term: "board", count: 0 },
+      { kind: "model", code: "title_path_score", score: 1.2 },
+    ]) {
+      expect(RelevanceReasonSchema.safeParse(reason).success).toBe(false);
+    }
+  });
+
+  it("a hidden item that claims inclusion is refused", () => {
+    const parsed = SourceSyncCandidateItemSchema.safeParse(
+      candidateItem({ visibility: "hidden", included: true }),
+    );
+    expect(parsed.success).toBe(false);
+    expect(parsed.error?.issues[0]?.message).toBe(
+      "a hidden line is never included",
+    );
+  });
+
+  it("refuses the dropped tier on the wire item", () => {
+    expect(
+      SourceSyncCandidateItemSchema.safeParse(
+        candidateItem({ visibility: "dropped", included: false }),
+      ).success,
+    ).toBe(false);
+  });
+
+  it("carries a selection source exactly when a treatment is committed", () => {
+    const committed = { use: "attached", treatmentUnresolved: false };
+    expect(
+      SourceSyncCandidateItemSchema.safeParse(
+        candidateItem({ ...committed, selectionSource: "person" }),
+      ).success,
+    ).toBe(true);
+    expect(
+      SourceSyncCandidateItemSchema.safeParse(
+        candidateItem({ ...committed, selectionSource: "approval_default" }),
+      ).success,
+    ).toBe(true);
+    expect(
+      SourceSyncCandidateItemSchema.safeParse(
+        candidateItem({ ...committed, selectionSource: null }),
+      ).success,
+    ).toBe(false);
+    expect(
+      SourceSyncCandidateItemSchema.safeParse(
+        candidateItem({ use: null, selectionSource: "person" }),
+      ).success,
+    ).toBe(false);
+  });
+});
+
+describe("SourceSyncCandidateItemPatchSchema", () => {
+  it("bring into review is a patch of visibility alone", () => {
+    expect(
+      SourceSyncCandidateItemPatchSchema.safeParse({ visibility: "shown" })
+        .success,
+    ).toBe(true);
+    expect(
+      SourceSyncCandidateItemPatchSchema.safeParse({ visibility: "hidden" })
+        .success,
+    ).toBe(false);
+  });
+
+  it("a patch may not both promote and choose a treatment", () => {
+    for (const patch of [
+      { visibility: "shown", use: "attached" },
+      { visibility: "shown", targetDocId: TARGET_DOC_ID },
+      { use: "attached", sourceClass: "board_deck" },
+      {},
+    ]) {
+      expect(SourceSyncCandidateItemPatchSchema.safeParse(patch).success).toBe(
+        false,
+      );
+    }
+  });
+});
+
+describe("SourceSyncCandidateSetResponseSchema discovery", () => {
+  it("a set response before any completed run has a null discovery block", () => {
+    expect(
+      SourceSyncCandidateSetResponseSchema.safeParse(
+        candidateSet({ discovery: null }),
+      ).success,
+    ).toBe(true);
+    const { discovery: _omitted, ...withoutKey } = candidateSet();
+    expect(
+      SourceSyncCandidateSetResponseSchema.safeParse(withoutKey).success,
+    ).toBe(false);
+  });
+
+  it("accepts a discovery block and refuses a coverage above 100 or an unknown outcome", () => {
+    const set = candidateSet();
+    expect(SourceSyncCandidateSetResponseSchema.safeParse(set).success).toBe(
+      true,
+    );
+    for (const change of [
+      { coveragePercent: 101 },
+      { scanOutcome: "timed_out" },
+      { filesDropped: -1 },
+    ]) {
+      expect(
+        SourceSyncCandidateSetResponseSchema.safeParse(
+          candidateSet({ discovery: { ...set.discovery, ...change } }),
+        ).success,
+      ).toBe(false);
+    }
+  });
+});
+
 describe("SourceSyncDiscoveryRunResponseSchema", () => {
   it("refuses a workflow type other than source-sync/discover", () => {
     expect(
@@ -281,16 +515,3 @@ describe("SourceSyncDiscoveryRunResponseSchema", () => {
     ).toBe(true);
   });
 });
-
-describe("candidateTotalsOf", () => {
-  it("counts distinct files, never lines", () => {
-    expect(
-      candidateTotalsOf([
-        { sourceId: "a", included: true, treatmentUnresolved: true },
-        { sourceId: "a", included: true, treatmentUnresolved: false },
-        { sourceId: "b", included: false, treatmentUnresolved: true },
-        { sourceId: "c", included: true, treatmentUnresolved: false },
-      ]),
-    ).toEqual({ files: 3, filesIncluded: 2, filesNeedingChoice: 1 });
-  });
-});

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

@@ -6,13 +6,31 @@
  * order.
  *
  * INVARIANTS TESTED:
- * - Each of the ten closed sets has exactly the members this release fixes
+ * - Each of the twenty-three closed sets (ten Source Sync, thirteen discovery
+ *   relevance) has exactly the members this release fixes
  * - `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
  */
 
 import { describe, it, expect } from "vitest";
 
+import {
+  ATTENTION_LANES,
+  CANDIDATE_MACHINE_STATES,
+  CLASSIFICATION_STATES,
+  EVALUATION_REASON_CODES,
+  LEXICON_REASON_CODES,
+  MODEL_REASON_CODES,
+  PERSON_HOLD_REASONS,
+  RELEVANCE_REASON_KINDS,
+  SCAN_OUTCOMES,
+  SELECTION_SOURCES,
+  SIGNAL_REASON_CODES,
+  SOURCE_RELEVANCE_TIERS,
+  TARGET_AUDIENCES,
+} from "../relevance";
+
 import {
   AUDIENCE_FITS,
   SHARING_BREADTHS,
@@ -104,6 +122,108 @@ const VOCABULARIES = [
     tuple: SOURCE_SYNC_SCOPE_APPROVER_KINDS,
     members: ["org_admin", "unit_head"],
   },
+  {
+    name: "SOURCE_RELEVANCE_TIERS",
+    tuple: SOURCE_RELEVANCE_TIERS,
+    members: ["dropped", "hidden", "shown"],
+  },
+  {
+    name: "CLASSIFICATION_STATES",
+    tuple: CLASSIFICATION_STATES,
+    members: ["unclassified", "classified"],
+  },
+  {
+    name: "RELEVANCE_REASON_KINDS",
+    tuple: RELEVANCE_REASON_KINDS,
+    members: ["lexicon", "signal", "evaluation", "model"],
+  },
+  {
+    name: "LEXICON_REASON_CODES",
+    tuple: LEXICON_REASON_CODES,
+    members: [
+      "title_term",
+      "folder_term",
+      "negative_title_term",
+      "negative_folder_term",
+    ],
+  },
+  {
+    name: "SIGNAL_REASON_CODES",
+    tuple: SIGNAL_REASON_CODES,
+    members: [
+      "folder_probe_hit",
+      "title_probe_hit",
+      "version_churn",
+      "mime_class",
+      "size_band",
+      "dated_series",
+      "recent_edit",
+      "owner_unit_head",
+      "owner_executive",
+      "sharing_breadth",
+      "duplicate_title",
+      "personal_mime",
+    ],
+  },
+  {
+    name: "EVALUATION_REASON_CODES",
+    tuple: EVALUATION_REASON_CODES,
+    members: [
+      "not_evaluated_t1",
+      "not_evaluated_t2",
+      "folder_unresolved",
+      "folder_truncated",
+      "explored_t1",
+      "explored_t2",
+    ],
+  },
+  {
+    name: "MODEL_REASON_CODES",
+    tuple: MODEL_REASON_CODES,
+    members: ["title_path_score", "peek_confirms", "peek_contradicts"],
+  },
+  {
+    name: "TARGET_AUDIENCES",
+    tuple: TARGET_AUDIENCES,
+    members: ["restricted", "unit", "org_wide"],
+  },
+  {
+    name: "ATTENTION_LANES",
+    tuple: ATTENTION_LANES,
+    members: ["exploit", "explore"],
+  },
+  {
+    name: "CANDIDATE_MACHINE_STATES",
+    tuple: CANDIDATE_MACHINE_STATES,
+    members: [
+      "fresh",
+      "refreshed",
+      "filtered_out",
+      "not_rediscovered",
+      "pending_classification",
+      "retired",
+    ],
+  },
+  {
+    name: "SELECTION_SOURCES",
+    tuple: SELECTION_SOURCES,
+    members: ["person", "approval_default"],
+  },
+  {
+    name: "PERSON_HOLD_REASONS",
+    tuple: PERSON_HOLD_REASONS,
+    members: [
+      "relevance_override",
+      "treatment_selection",
+      "target_override",
+      "manual_add",
+    ],
+  },
+  {
+    name: "SCAN_OUTCOMES",
+    tuple: SCAN_OUTCOMES,
+    members: ["complete", "budget_exhausted", "file_ceiling", "stopped"],
+  },
 ] as const satisfies readonly {
   name: string;
   tuple: readonly string[];
@@ -142,4 +262,18 @@ describe("Source Sync closed sets", () => {
     const all = VOCABULARIES.flatMap(({ tuple }) => [...tuple]);
     expect(new Set(all).size).toBe(all.length);
   });
+
+  it("the four reason code sets are pairwise disjoint", () => {
+    const codeSets: readonly (readonly string[])[] = [
+      LEXICON_REASON_CODES,
+      SIGNAL_REASON_CODES,
+      EVALUATION_REASON_CODES,
+      MODEL_REASON_CODES,
+    ];
+    codeSets.forEach((a, i) => {
+      codeSets.slice(i + 1).forEach((b) => {
+        expect(a.filter((code) => b.includes(code))).toEqual([]);
+      });
+    });
+  });
 });

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

@@ -12,15 +12,19 @@ import type {
   SourceSyncCandidateTotals,
 } from "./schemas";
 
+/** The relevance facts the count reads (control ADR source-discovery-relevance-funnel). */
+type RelevanceFacts = "visibility" | "machineState";
+
 /** The item facts the count reads. */
 export type CandidateTotalsInput = Pick<
   SourceSyncCandidateItem,
-  "sourceId" | "included" | "treatmentUnresolved"
+  "sourceId" | "included" | "treatmentUnresolved" | RelevanceFacts
 >;
 
 /**
  * Included when any of the file's lines is; in need of a choice when any
- * included line's treatment is unresolved.
+ * included line's treatment is unresolved. Hidden only when EVERY line of the
+ * file is hidden; not rediscovered / pending classification when ANY line is.
  */
 export function candidateTotalsOf(
   items: readonly CandidateTotalsInput[],
@@ -28,15 +32,29 @@ export function candidateTotalsOf(
   const files = new Set<string>();
   const included = new Set<string>();
   const needingChoice = new Set<string>();
+  const anyShown = new Set<string>();
+  const notRediscovered = new Set<string>();
+  const pendingClassification = new Set<string>();
   for (const item of items) {
     files.add(item.sourceId);
+    if (item.visibility === "shown") anyShown.add(item.sourceId);
+    if (item.machineState === "not_rediscovered") {
+      notRediscovered.add(item.sourceId);
+    }
+    if (item.machineState === "pending_classification") {
+      pendingClassification.add(item.sourceId);
+    }
     if (!item.included) continue;
     included.add(item.sourceId);
     if (item.treatmentUnresolved) needingChoice.add(item.sourceId);
   }
+  const hidden = [...files].filter((id) => !anyShown.has(id)).length;
   return {
     files: files.size,
     filesIncluded: included.size,
     filesNeedingChoice: needingChoice.size,
+    filesHidden: hidden,
+    filesNotRediscovered: notRediscovered.size,
+    filesPendingClassification: pendingClassification.size,
   };
 }

package/src/source-sync/index.ts

@@ -3,7 +3,7 @@
  *
  * Re-exports the closed Source Sync vocabularies (the sets the backend persists
  * and mirrors as database CHECK constraints, and the app handles exhaustively)
- * the discovery and candidate-set response schemas, the candidate-edit and
+ * including the discovery relevance vocabulary, the discovery and candidate-set response schemas, the candidate-edit and
  * per-scope approval request and response schemas, the per-document change
  * plan and apply schemas, the source-resolution rule schemas, the staleness
  * finding and standing-order schemas, and the Drive-reach status and upgrade
@@ -44,6 +44,45 @@ export {
   SOURCE_SYNC_SCOPE_APPROVER_KINDS,
 } from "./vocabulary";
 
+export type {
+  SourceRelevanceTier,
+  ClassificationState,
+  RelevanceReasonKind,
+  LexiconReasonCode,
+  SignalReasonCode,
+  EvaluationReasonCode,
+  ModelReasonCode,
+  TargetAudience,
+  AttentionLane,
+  CandidateMachineState,
+  SelectionSource,
+  PersonHoldReason,
+  ScanOutcome,
+  RelevanceReason,
+  CandidateAttention,
+  CandidateDiscoverySummary,
+} from "./relevance";
+
+export {
+  SOURCE_RELEVANCE_TIERS,
+  CLASSIFICATION_STATES,
+  RELEVANCE_REASON_KINDS,
+  LEXICON_REASON_CODES,
+  SIGNAL_REASON_CODES,
+  EVALUATION_REASON_CODES,
+  MODEL_REASON_CODES,
+  TARGET_AUDIENCES,
+  ATTENTION_LANES,
+  CANDIDATE_MACHINE_STATES,
+  SELECTION_SOURCES,
+  PERSON_HOLD_REASONS,
+  SCAN_OUTCOMES,
+  RelevanceReasonSchema,
+  CandidateAttentionSchema,
+  CandidateDiscoverySummarySchema,
+  refineCandidateRelevance,
+} from "./relevance";
+
 export type {
   SourceSyncDiscoveryRunResponse,
   SourceSyncCandidateItem,

package/src/source-sync/relevance.ts

@@ -0,0 +1,216 @@
+/**
+ * Source discovery RELEVANCE vocabulary (control ADR source-discovery-relevance-funnel).
+ * Closed sets that go on the wire AND into backend CHECK constraints. Renaming a member is a migration.
+ *
+ * Two axes: relevance (dropped | hidden | shown — the funnel's verdict) and the disclosure
+ * treatment (SOURCE_USES — a person's). Neither changes the other.
+ */
+
+import { z } from "zod";
+
+/** The funnel's verdict. `dropped` is persisted (drop ledger / re-scored observation) and never reaches the wire item. */
+export const SOURCE_RELEVANCE_TIERS = ["dropped", "hidden", "shown"] as const;
+export type SourceRelevanceTier = (typeof SOURCE_RELEVANCE_TIERS)[number];
+
+/** Whether a classifier has produced class/scope/period/sensitivity for the line. Separate from relevance. */
+export const CLASSIFICATION_STATES = ["unclassified", "classified"] as const;
+export type ClassificationState = (typeof CLASSIFICATION_STATES)[number];
+
+/** RelevanceReason is a discriminated union on `kind`; each kind has its own disjoint code set. */
+export const RELEVANCE_REASON_KINDS = [
+  "lexicon",
+  "signal",
+  "evaluation",
+  "model",
+] as const;
+export type RelevanceReasonKind = (typeof RELEVANCE_REASON_KINDS)[number];
+
+/** A product-owned lexicon TERM matched (the term travels; a filename slice never does). */
+export const LEXICON_REASON_CODES = [
+  "title_term",
+  "folder_term",
+  "negative_title_term",
+  "negative_folder_term",
+] as const;
+export type LexiconReasonCode = (typeof LEXICON_REASON_CODES)[number];
+
+/** A metadata signal with a numeric value (or null). `version_churn` is Drive's server-side version, never an edit count. */
+export const SIGNAL_REASON_CODES = [
+  "folder_probe_hit",
+  "title_probe_hit",
+  "version_churn",
+  "mime_class",
+  "size_band",
+  "dated_series",
+  "recent_edit",
+  "owner_unit_head",
+  "owner_executive",
+  "sharing_breadth",
+  "duplicate_title",
+  "personal_mime",
+] 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). */
+export const EVALUATION_REASON_CODES = [
+  "not_evaluated_t1",
+  "not_evaluated_t2",
+  "folder_unresolved",
+  "folder_truncated",
+  "explored_t1",
+  "explored_t2",
+] as const;
+export type EvaluationReasonCode = (typeof EVALUATION_REASON_CODES)[number];
+
+/** A model tier's contribution. */
+export const MODEL_REASON_CODES = [
+  "title_path_score",
+  "peek_confirms",
+  "peek_contradicts",
+] as const;
+export type ModelReasonCode = (typeof MODEL_REASON_CODES)[number];
+
+/** The audience Attach would disclose the source to. Mirrors the backend's TARGET_BREADTHS. `restricted` ≠ `restricted_few`. */
+export const TARGET_AUDIENCES = ["restricted", "unit", "org_wide"] as const;
+export type TargetAudience = (typeof TARGET_AUDIENCES)[number];
+
+/** Why a tier got the model's attention (INV-SOURCESYNC-EXPLORATION-RESERVED). */
+export const ATTENTION_LANES = ["exploit", "explore"] as const;
+export type AttentionLane = (typeof ATTENTION_LANES)[number];
+
+/** A candidate line's machine lifecycle (INV-SOURCESYNC-SET-IS-RECONCILED, INV-SOURCESYNC-DROP-IS-TWO-LIFECYCLES). `retired` = positive absence only. */
+export const CANDIDATE_MACHINE_STATES = [
+  "fresh",
+  "refreshed",
+  "filtered_out",
+  "not_rediscovered",
+  "pending_classification",
+  "retired",
+] as const;
+export type CandidateMachineState = (typeof CANDIDATE_MACHINE_STATES)[number];
+
+/** Provenance of a committed treatment (INV-SOURCESYNC-RECOMMENDATION-IS-NOT-COMMITMENT). */
+export const SELECTION_SOURCES = ["person", "approval_default"] as const;
+export type SelectionSource = (typeof SELECTION_SOURCES)[number];
+
+/** Field-level write barriers a person's action places on a line (INV-SOURCESYNC-HOLDS-ARE-FIELD-BARRIERS). */
+export const PERSON_HOLD_REASONS = [
+  "relevance_override",
+  "treatment_selection",
+  "target_override",
+  "manual_add",
+] as const;
+export type PersonHoldReason = (typeof PERSON_HOLD_REASONS)[number];
+
+/** How a discovery scan ended. */
+export const SCAN_OUTCOMES = [
+  "complete",
+  "budget_exhausted",
+  "file_ceiling",
+  "stopped",
+] as const;
+export type ScanOutcome = (typeof SCAN_OUTCOMES)[number];
+
+/**
+ * Why a candidate scored as it did. A discriminated union: the drop ledger keeps only {kind, code}
+ * and counts; product copy switches exhaustively on `kind` then `code`. A lexicon `term` is ALWAYS a
+ * product-owned lexicon entry, never a slice of the file name (INV-SOURCESYNC-POLICY-IS-RECORDED).
+ */
+export const RelevanceReasonSchema = z.discriminatedUnion("kind", [
+  z.object({
+    kind: z.literal("lexicon"),
+    code: z.enum(LEXICON_REASON_CODES),
+    term: z.string().min(1).max(64),
+    count: z.number().int().min(1),
+  }),
+  z.object({
+    kind: z.literal("signal"),
+    code: z.enum(SIGNAL_REASON_CODES),
+    value: z.number().nullable(),
+  }),
+  z.object({
+    kind: z.literal("evaluation"),
+    code: z.enum(EVALUATION_REASON_CODES),
+  }),
+  z.object({
+    kind: z.literal("model"),
+    code: z.enum(MODEL_REASON_CODES),
+    score: z.number().min(0).max(1).nullable(),
+  }),
+]);
+export type RelevanceReason = z.infer<typeof RelevanceReasonSchema>;
+
+/** Which lane earned each model tier's attention for a line; null = that tier did not look at it. */
+export const CandidateAttentionSchema = z.object({
+  t1: z.enum(ATTENTION_LANES).nullable(),
+  t2: z.enum(ATTENTION_LANES).nullable(),
+});
+export type CandidateAttention = z.infer<typeof CandidateAttentionSchema>;
+
+/**
+ * The last completed discovery run's counts, so no surface shows one ambiguous total.
+ * The set response carries it NULL before any run has completed.
+ */
+export const CandidateDiscoverySummarySchema = z.object({
+  foundThisRun: z.number().int().min(0),
+  retainedDecisions: z.number().int().min(0),
+  notRediscovered: z.number().int().min(0),
+  pendingClassification: z.number().int().min(0),
+  filesDropped: z.number().int().min(0),
+  coveragePercent: z.number().int().min(0).max(100),
+  scanOutcome: z.enum(SCAN_OUTCOMES),
+});
+export type CandidateDiscoverySummary = z.infer<
+  typeof CandidateDiscoverySummarySchema
+>;
+
+/** The item fields the relevance consistency rules read. */
+type CandidateRelevanceFacts = {
+  visibility: SourceRelevanceTier;
+  included: boolean;
+  classificationState: ClassificationState;
+  recommendedUse: string | null;
+  sourceClass: string | null;
+  use: string | null;
+  selectionSource: SelectionSource | 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.
+ */
+export function refineCandidateRelevance(
+  item: CandidateRelevanceFacts,
+  ctx: z.RefinementCtx,
+): void {
+  const unclassified = item.classificationState === "unclassified";
+  const hasRecommendation =
+    item.recommendedUse !== null || item.sourceClass !== null;
+  const missingRecommendation =
+    item.recommendedUse === null || item.sourceClass === null;
+  if (item.visibility === "hidden" && item.included) {
+    ctx.addIssue({
+      code: "custom",
+      message: "a hidden line is never included",
+    });
+  }
+  if (unclassified && hasRecommendation) {
+    ctx.addIssue({
+      code: "custom",
+      message: "an unclassified line has no recommendation and no class",
+    });
+  }
+  if (!unclassified && missingRecommendation) {
+    ctx.addIssue({
+      code: "custom",
+      message: "a classified line has a recommendation and a class",
+    });
+  }
+  if ((item.use === null) !== (item.selectionSource === null)) {
+    ctx.addIssue({
+      code: "custom",
+      message: "selectionSource is present exactly when use is",
+    });
+  }
+}

package/src/source-sync/schemas.ts

@@ -30,6 +30,18 @@ import {
   SOURCE_SYNC_SCOPE_APPROVER_KINDS,
   SOURCE_USES,
 } from "./vocabulary";
+import {
+  CANDIDATE_MACHINE_STATES,
+  CandidateAttentionSchema,
+  CandidateDiscoverySummarySchema,
+  CLASSIFICATION_STATES,
+  PERSON_HOLD_REASONS,
+  refineCandidateRelevance,
+  RelevanceReasonSchema,
+  SELECTION_SOURCES,
+  SOURCE_RELEVANCE_TIERS,
+  TARGET_AUDIENCES,
+} from "./relevance";
 
 /** Integer micro-USD as a string — the billing domain's money convention on the wire. */
 const MicroUsd = z.string().regex(/^[0-9]+$/);
@@ -77,62 +89,86 @@ export const SourceSyncDiscoveryRunResponseSchema = z.object({
 });
 
 /** 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),
-  sourceClass: z.enum(SOURCE_CLASSES),
-  periodLabel: z.string().max(64).nullable(),
-  seriesRole: z.enum(["current", "history"]).nullable(),
-  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(),
-  recommendedUse: z.enum(SOURCE_USES),
-  /** What the person has chosen; null until they (or an accepted default) decide. */
-  use: z.enum(SOURCE_USES).nullable(),
-  /**
-   * 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. Never model-authored prose. */
-  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(),
-});
+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(),
+    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(8),
+    /** 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);
 
 /** Distinct-file totals over every line of a candidate set the caller may see. */
 export const SourceSyncCandidateTotalsSchema = z.object({
@@ -142,6 +178,12 @@ export const SourceSyncCandidateTotalsSchema = z.object({
   filesIncluded: z.number().int().min(0),
   /** Files with at least one included line whose treatment is unresolved. */
   filesNeedingChoice: z.number().int().min(0),
+  /** Files every line of which is hidden (behind the drawer; control ADR source-discovery-relevance-funnel). */
+  filesHidden: z.number().int().min(0),
+  /** Files with at least one line the latest run did not see again. */
+  filesNotRediscovered: z.number().int().min(0),
+  /** Files with at least one line awaiting classification. */
+  filesPendingClassification: z.number().int().min(0),
 });
 
 /** The draft set under review. `revision` moves on every edit and is echoed on approve. */
@@ -170,14 +212,19 @@ export const SourceSyncCandidateSetResponseSchema = z.object({
       capMicroUsd: MicroUsd,
     })
     .nullable(),
+  /** The last completed discovery run's counts; null before any run completed. */
+  discovery: z.nullable(CandidateDiscoverySummarySchema),
 });
 
 /**
- * One edit to one candidate item. Every field optional: a PATCH names what changes.
+ * 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. */
@@ -186,8 +233,8 @@ export const SourceSyncCandidateItemPatchSchema = z
     targetDocId: z.string().uuid().optional(),
   })
   .strict()
-  .refine((patch) => Object.keys(patch).length > 0, {
-    message: "a patch changes something",
+  .refine((patch) => Object.keys(patch).length === 1, {
+    message: "a patch changes exactly one thing",
   });
 
 /** "Add one I missed": a file the person picked in the provider's own search. */