@company-semantics/contracts 83.2.0 → 85.0.0

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. */