@company-semantics/contracts 83.2.0 → 85.0.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,