@company-semantics/contracts 88.2.0 → 89.1.0

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

package/src/source-sync/schemas.ts

@@ -1,8 +1,9 @@
 /**
  * The Source Sync discovery and candidate-set wire schemas.
  *
- * A candidate item is ONE source proposed for ONE target document, because
- * treatment and landing are source x target (INV-SOURCESYNC-LANDING-PER-TARGET).
+ * A candidate item (./candidate-item) is ONE source proposed for ONE target
+ * document, because treatment and landing are source x target
+ * (INV-SOURCESYNC-LANDING-PER-TARGET).
  * The wire carries facts ABOUT a source and a COUNT of people it is shared with,
  * never its content and never their addresses: the external provider remains the
  * ACL authority for the source itself.
@@ -20,28 +21,14 @@ import { z } from "zod";
 import { DecisionQuestionPresentationSchema } from "../decisions/presentation";
 import { IsoDateTime } from "../api/primitives";
 import {
-  AUDIENCE_FITS,
-  SHARING_BREADTHS,
   SOURCE_CLASSES,
-  SOURCE_SENSITIVITY_CLASSES,
   SOURCE_SYNC_DOC_DISPOSITIONS,
   SOURCE_SYNC_DOC_RISKS,
   SOURCE_SYNC_SCOPE_APPROVAL_STATES,
   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";
+import { CandidateDiscoverySummarySchema } from "./relevance";
+import { SourceSyncCandidateItemSchema } from "./candidate-item";
 
 /** Integer micro-USD as a string — the billing domain's money convention on the wire. */
 const MicroUsd = z.string().regex(/^[0-9]+$/);
@@ -88,88 +75,6 @@ export const SourceSyncDiscoveryRunResponseSchema = z.object({
   workflowType: z.literal("source-sync/discover"),
 });
 
-/** 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(),
-    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({
   /** Files in the review: at least one line, included or left out. */
@@ -216,27 +121,6 @@ export const SourceSyncCandidateSetResponseSchema = z.object({
   discovery: z.nullable(CandidateDiscoverySummarySchema),
 });
 
-/**
- * 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",
-  });
-
 /** "Add one I missed": a file the person picked in the provider's own search. */
 export const SourceSyncAddCandidateRequestSchema = z
   .object({
@@ -440,18 +324,12 @@ export const SourceSyncCurrentSynthesisResponseSchema = z.object({
 export type SourceSyncDiscoveryRunResponse = z.infer<
   typeof SourceSyncDiscoveryRunResponseSchema
 >;
-export type SourceSyncCandidateItem = z.infer<
-  typeof SourceSyncCandidateItemSchema
->;
 export type SourceSyncCandidateSetResponse = z.infer<
   typeof SourceSyncCandidateSetResponseSchema
 >;
 export type SourceSyncCandidateTotals = z.infer<
   typeof SourceSyncCandidateTotalsSchema
 >;
-export type SourceSyncCandidateItemPatch = z.infer<
-  typeof SourceSyncCandidateItemPatchSchema
->;
 export type SourceSyncAddCandidateRequest = z.infer<
   typeof SourceSyncAddCandidateRequestSchema
 >;

package/src/source-sync/vocabulary.ts

@@ -110,3 +110,48 @@ export const SOURCE_SYNC_SCOPE_APPROVER_KINDS = [
 ] as const;
 export type SourceSyncScopeApproverKind =
   (typeof SOURCE_SYNC_SCOPE_APPROVER_KINDS)[number];
+
+/**
+ * What a source IS — a STRUCTURAL name the model observes, never a relevance verdict
+ * (control ADR source-discovery-observation-vs-policy). Product policy in the backend maps a
+ * resolved type to a family, a source class, a sensitivity and a relevance policy; none of
+ * that travels on the wire. A medium is not a meaning: `image_or_screenshot` is graded on
+ * content. `unknown` is a real answer (the model could not tell, or two reads disagreed).
+ * Five strings are shared with other sets on purpose: board_deck, board_minutes,
+ * investor_update, roadmap (SOURCE_CLASSES) and unknown (SHARING_BREADTHS) — same word,
+ * separate axis.
+ */
+export const DOCUMENT_TYPES = [
+  "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",
+] as const;
+export type DocumentType = (typeof DOCUMENT_TYPES)[number];
+export type KnownDocumentType = Exclude<DocumentType, "unknown">;

package/src/workflows/README.md

@@ -32,7 +32,23 @@ so every producer, validator and renderer agrees on it.
 - **Source Sync registers two flows.** `source-sync/discover` (Stage 1)
   retains nothing; `source-sync/synthesize` (Stage 4) runs only after a person
   approved the exact set it reads.
+- **Every type has a typed outcome** (`outcome.ts`, control ADR-CTRL-540). A
+  terminal transition is classified once, by the backend, into a per-type
+  member of `WorkflowOutcome`: a closed `reason`, typed count-only `facts`, a
+  `kind` that is a function of the reason (`*_OUTCOME_KIND_OF_REASON`), and an
+  explicit `disposition` (`review` or `narrate`). Adding a workflow type means
+  adding its outcome member; the union must cover every registered type.
+- **`unknown` is a safety valve, not a status.** It names an unrecognized
+  terminal transition, never a workflow whose state could not be read.
+
+## Public API
+
+- `ANALYSIS_WORKFLOW_TYPES`, `WorkflowType`, `isWorkflowType` (`types.ts`).
+- `WorkflowOutcomeSchema` / `WorkflowOutcome` and the per-type member schemas,
+  reason tables, fact schemas and `WorkflowOutcomeDispositionSchema`
+  (`outcome.ts`).
 
 ## Dependencies
 
-None. Pure vocabulary data and one pure guard; no `zod`, no runtime imports.
+`zod` (outcome schemas) and `../input-requests/types` (the review
+disposition's request type). Otherwise pure vocabulary data and one guard.

package/src/workflows/__tests__/README.md

@@ -13,6 +13,12 @@ wire value against it.
   rejections: a bare `hris-connect` without its namespace, the namespace on
   its own, a trailing separator, an unknown flow, and non-string inputs.
 
+- `outcome.test.ts` — the outcome union covers every registered workflow type
+  (compile-time), each reason table's kinds are valid, the schema accepts a
+  well-formed member and refuses a kind that does not match its reason, a
+  review disposition on a non-produced outcome, a reason from another type,
+  and extra keys (the facts stay closed).
+
 ## Invariants
 
 - These assert VOCABULARY and SHAPE, never behavior. What a workflow of a