@company-semantics/contracts 88.2.0 → 89.0.0

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">;