@company-semantics/contracts 89.1.0 → 90.0.0

package/src/source-sync/attention-evidence.ts

@@ -0,0 +1,93 @@
+/**
+ * WHY a file received T1 attention — the evidence vector, each signal with its
+ * PROVENANCE (control ADR index-first-operating-knowledge-discovery;
+ * INV-SOURCESYNC-ATTENTION-EVIDENCE-HAS-PROVENANCE).
+ *
+ * It exists only for a file that crossed T1 attention: pre-attention signals are
+ * ephemeral (INV-SOURCESYNC-PRE-ATTENTION-SIGNALS-ARE-EPHEMERAL), so a file that never
+ * reached attention carries NULL evidence. Every signal names the producer and version
+ * that judged it, so "why did c_S find this?" stays answerable after prompts and
+ * lexicons change. `producer` is a documented key string (not a closed set, so a new
+ * producer needs no contracts major); the producers in use are `lexicon`,
+ * `source-discovery-tree-triage`, `source-discovery-plan` and `metadata-scorer`.
+ *
+ * TERMS are product- or plan-proposed vocabulary that MATCHED — never a slice of the
+ * file's name and never text read from the file. A folder is named by its provider
+ * id (`folderId`), never its name (INV-SOURCESYNC-TOPOLOGY-IS-NOT-SOURCE-EVIDENCE).
+ */
+import { z } from "zod";
+import { SHARING_BREADTHS } from "./vocabulary";
+
+export const ATTENTION_SIGNAL_KINDS = [
+  "tree_prior",
+  "path_terms",
+  "content_match",
+  "breadth",
+  "recency",
+  "mime_prior",
+] as const;
+export type AttentionSignalKind = (typeof ATTENTION_SIGNAL_KINDS)[number];
+
+/** Who judged a signal: a producer key (a prompt key, `lexicon`, a scorer) and its version. */
+export const AttentionSignalSourceSchema = z.object({
+  producer: z.string().regex(/^[a-z0-9][a-z0-9.-]{0,63}$/),
+  version: z.string().min(1).max(32),
+});
+export type AttentionSignalSource = z.infer<typeof AttentionSignalSourceSchema>;
+
+const Score = z.number().min(0).max(1);
+const Terms = z.array(z.string().min(1).max(64)).min(1).max(16);
+
+export const AttentionSignalSchema = z.discriminatedUnion("kind", [
+  z.object({
+    kind: z.literal("tree_prior"),
+    score: Score,
+    /** The provider id of the folder the tree triage ranked — never its name. */
+    folderId: z.string().min(1).max(128),
+    source: AttentionSignalSourceSchema,
+  }),
+  z.object({
+    kind: z.literal("path_terms"),
+    values: Terms,
+    source: AttentionSignalSourceSchema,
+  }),
+  z.object({
+    kind: z.literal("content_match"),
+    values: Terms,
+    strength: Score,
+    /** The structured content probe that matched. */
+    probeId: z.string().min(1).max(64),
+    source: AttentionSignalSourceSchema,
+  }),
+  z.object({
+    kind: z.literal("breadth"),
+    value: z.enum(SHARING_BREADTHS),
+    source: AttentionSignalSourceSchema,
+  }),
+  z.object({
+    kind: z.literal("recency"),
+    score: Score,
+    source: AttentionSignalSourceSchema,
+  }),
+  z.object({
+    kind: z.literal("mime_prior"),
+    score: Score,
+    source: AttentionSignalSourceSchema,
+  }),
+]);
+export type AttentionSignal = z.infer<typeof AttentionSignalSchema>;
+
+/** At most one signal of each kind. */
+export const AttentionEvidenceSchema = z
+  .array(AttentionSignalSchema)
+  .max(ATTENTION_SIGNAL_KINDS.length)
+  .superRefine((signals, ctx) => {
+    const kinds = signals.map((s) => s.kind);
+    if (new Set(kinds).size !== kinds.length) {
+      ctx.addIssue({
+        code: "custom",
+        message: "an attention signal kind appears at most once",
+      });
+    }
+  });
+export type AttentionEvidence = z.infer<typeof AttentionEvidenceSchema>;

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

@@ -18,6 +18,7 @@ import { IsoDateTime } from "../api/primitives";
 import {
   AUDIENCE_FITS,
   DOCUMENT_TYPES,
+  OPERATING_KNOWLEDGE_FAMILIES,
   SHARING_BREADTHS,
   SOURCE_CLASSES,
   SOURCE_SENSITIVITY_CLASSES,
@@ -34,6 +35,7 @@ import {
   SOURCE_RELEVANCE_TIERS,
   TARGET_AUDIENCES,
 } from "./relevance";
+import { AttentionEvidenceSchema } from "./attention-evidence";
 
 /** ONE source proposed for ONE target document. */
 export const SourceSyncCandidateItemSchema = z
@@ -75,6 +77,22 @@ export const SourceSyncCandidateItemSchema = z
     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(),
+    /**
+     * WHAT KIND of operating knowledge the line is — a NAME the backend RESOLVES from the
+     * resolved document type through its versioned policy table (control ADR
+     * index-first-operating-knowledge-discovery), exactly as it resolves sourceClass. The
+     * backend's internal relevance-policy families never travel. NULL when the type is
+     * null or unknown, or names no operating knowledge (a legal agreement, a transaction,
+     * personal material), and on every line of a run that predates index-first discovery.
+     */
+    operatingKnowledgeFamily: z.enum(OPERATING_KNOWLEDGE_FAMILIES).nullable(),
+    /**
+     * WHERE the source lives in the provider ("Product/Planning/2026") — the Tier-1
+     * canonical path the backend resolves from its location graph once the file reached
+     * T1 attention (Tier-0 never retains a name or a path). NULL for a file that never
+     * reached attention, on a withheld line, and on a run that predates index-first discovery.
+     */
+    canonicalPath: z.string().min(1).max(1024).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. */
@@ -106,6 +124,13 @@ export const SourceSyncCandidateItemSchema = z
     targetAudience: z.enum(TARGET_AUDIENCES).nullable(),
     /** Which lane earned each model tier's attention (INV-SOURCESYNC-EXPLORATION-RESERVED). */
     attention: CandidateAttentionSchema,
+    /**
+     * WHY the line received T1 attention: each signal with its producer and version
+     * (INV-SOURCESYNC-ATTENTION-EVIDENCE-HAS-PROVENANCE). NULL for a file that never
+     * reached attention, on a withheld line (terms and folder ids identify a source), and
+     * on every line of a run that predates index-first discovery.
+     */
+    attentionEvidence: AttentionEvidenceSchema.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

package/src/source-sync/enumeration.ts

@@ -0,0 +1,152 @@
+/**
+ * Index-first discovery's ENUMERATION vocabulary (control ADR
+ * index-first-operating-knowledge-discovery; INV-SOURCESYNC-PARTIAL-ENUMERATION-IS-UNKNOWN).
+ *
+ * A discovery run first enumerates every source reachable through the connection,
+ * root by root (the person's own corpus, each shared drive, the domain corpus).
+ * How completely it did so is a closed answer that separates OUR ceiling from the
+ * PROVIDER's incompleteness, so a partial enumeration can never read as an index of
+ * the corpus: only `complete` lets a surface say "full index". Anything else means
+ * absence is UNKNOWN, never negative evidence.
+ *
+ * Stage counters name what each count did: enumerated / metadata-eligible / T0-scored
+ * are metadata only; attended / peeked / classified involve a model; shown / retained
+ * are outcomes. `filesEnumerated = 100000` with `local_budget_truncated` never reads as
+ * "indexed every file".
+ */
+import { z } from "zod";
+import { IsoDateTime } from "../api/primitives";
+
+/** How completely a run (or one root) was enumerated. */
+export const ENUMERATION_COMPLETENESS = [
+  "complete",
+  "local_budget_truncated",
+  "provider_incomplete",
+  "both",
+] as const;
+export type EnumerationCompleteness = (typeof ENUMERATION_COMPLETENESS)[number];
+
+/** Which corpus a root is: the connected person's, one shared drive, or the domain. */
+export const ENUMERATION_ROOT_KINDS = [
+  "user",
+  "shared_drive",
+  "domain",
+] as const;
+export type EnumerationRootKind = (typeof ENUMERATION_ROOT_KINDS)[number];
+
+/**
+ * PURE: one completeness for many roots. Our ceiling anywhere and the provider's
+ * incompleteness anywhere combine to `both`; only every root complete is `complete`.
+ */
+export function combineEnumerationCompleteness(
+  statuses: readonly EnumerationCompleteness[],
+): EnumerationCompleteness {
+  const local = statuses.some(
+    (s) => s === "local_budget_truncated" || s === "both",
+  );
+  const provider = statuses.some(
+    (s) => s === "provider_incomplete" || s === "both",
+  );
+  if (local && provider) return "both";
+  if (local) return "local_budget_truncated";
+  if (provider) return "provider_incomplete";
+  return "complete";
+}
+
+const MS = (iso: string): number => Date.parse(iso);
+
+/** A modified-time range the sampler did not enumerate. */
+export const EnumerationSkippedRangeSchema = z
+  .object({ from: IsoDateTime, to: IsoDateTime })
+  .refine((r) => MS(r.from) <= MS(r.to), {
+    message: "a skipped range ends no earlier than it starts",
+  });
+
+/** How far one root's enumeration got. Counts, times and provider ids only — never a name. */
+export const RootCoverageSchema = z
+  .object({
+    rootKind: z.enum(ENUMERATION_ROOT_KINDS),
+    /** The shared drive's provider id; null for the user and domain corpora. */
+    rootId: z.string().min(1).max(128).nullable(),
+    status: z.enum(ENUMERATION_COMPLETENESS),
+    enumeratedCount: z.number().int().min(0),
+    /** Null exactly when nothing was enumerated under the root. */
+    observedOldestModifiedTime: IsoDateTime.nullable(),
+    observedNewestModifiedTime: IsoDateTime.nullable(),
+    skippedRanges: z.array(EnumerationSkippedRangeSchema).max(16),
+  })
+  .superRefine((root, ctx) => {
+    if ((root.rootId !== null) !== (root.rootKind === "shared_drive")) {
+      ctx.addIssue({
+        code: "custom",
+        message: "a root id names exactly a shared drive",
+      });
+    }
+    if (root.status === "complete" && root.skippedRanges.length > 0) {
+      ctx.addIssue({
+        code: "custom",
+        message: "a complete root skips nothing",
+      });
+    }
+    const empty = root.enumeratedCount === 0;
+    const timesAbsent =
+      root.observedOldestModifiedTime === null &&
+      root.observedNewestModifiedTime === null;
+    const timesPresent =
+      root.observedOldestModifiedTime !== null &&
+      root.observedNewestModifiedTime !== null;
+    if (empty ? !timesAbsent : !timesPresent) {
+      ctx.addIssue({
+        code: "custom",
+        message:
+          "observed modified times are present exactly when the root enumerated a file",
+      });
+    }
+    if (
+      timesPresent &&
+      MS(root.observedOldestModifiedTime as string) >
+        MS(root.observedNewestModifiedTime as string)
+    ) {
+      ctx.addIssue({
+        code: "custom",
+        message: "the oldest observed time is not after the newest",
+      });
+    }
+  });
+export type RootCoverage = z.infer<typeof RootCoverageSchema>;
+
+/**
+ * A run's stage counters. Each narrows the one before it:
+ * enumerated >= metadata-eligible >= T0-scored >= T1-attended >= peeked;
+ * T0-scored >= classified; T0-scored >= retained >= shown.
+ */
+export const DiscoveryStageCountersSchema = z
+  .object({
+    filesEnumerated: z.number().int().min(0),
+    filesMetadataEligible: z.number().int().min(0),
+    filesT0Scored: z.number().int().min(0),
+    filesT1Attended: z.number().int().min(0),
+    filesPeeked: z.number().int().min(0),
+    filesClassified: z.number().int().min(0),
+    filesShown: z.number().int().min(0),
+    filesRetained: z.number().int().min(0),
+  })
+  .superRefine((c, ctx) => {
+    const narrows =
+      c.filesMetadataEligible <= c.filesEnumerated &&
+      c.filesT0Scored <= c.filesMetadataEligible &&
+      c.filesT1Attended <= c.filesT0Scored &&
+      c.filesPeeked <= c.filesT1Attended &&
+      c.filesClassified <= c.filesT0Scored &&
+      c.filesRetained <= c.filesT0Scored &&
+      c.filesShown <= c.filesRetained;
+    if (!narrows) {
+      ctx.addIssue({
+        code: "custom",
+        message: "stage counters narrow from enumerated to shown",
+      });
+    }
+  });
+export type DiscoveryStageCounters = z.infer<
+  typeof DiscoveryStageCountersSchema
+>;

package/src/source-sync/index.ts

@@ -3,7 +3,9 @@
  *
  * Re-exports the closed Source Sync vocabularies (the sets the backend persists
  * and mirrors as database CHECK constraints, and the app handles exhaustively)
- * including the discovery relevance vocabulary, the discovery and candidate-set response schemas, the candidate-edit and
+ * including the discovery relevance vocabulary, the index-first enumeration
+ * vocabulary (completeness, root coverage, stage counters), the attention
+ * evidence schemas, 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
@@ -31,6 +33,7 @@ export type {
   SourceSyncScopeApproverKind,
   DocumentType,
   KnownDocumentType,
+  OperatingKnowledgeFamily,
 } from "./vocabulary";
 
 export {
@@ -45,6 +48,7 @@ export {
   SOURCE_SYNC_SCOPE_APPROVAL_STATES,
   SOURCE_SYNC_SCOPE_APPROVER_KINDS,
   DOCUMENT_TYPES,
+  OPERATING_KNOWLEDGE_FAMILIES,
 } from "./vocabulary";
 
 export type {
@@ -86,6 +90,36 @@ export {
   refineCandidateRelevance,
 } from "./relevance";
 
+export type {
+  EnumerationCompleteness,
+  EnumerationRootKind,
+  RootCoverage,
+  DiscoveryStageCounters,
+} from "./enumeration";
+
+export {
+  ENUMERATION_COMPLETENESS,
+  ENUMERATION_ROOT_KINDS,
+  combineEnumerationCompleteness,
+  EnumerationSkippedRangeSchema,
+  RootCoverageSchema,
+  DiscoveryStageCountersSchema,
+} from "./enumeration";
+
+export type {
+  AttentionSignalKind,
+  AttentionSignalSource,
+  AttentionSignal,
+  AttentionEvidence,
+} from "./attention-evidence";
+
+export {
+  ATTENTION_SIGNAL_KINDS,
+  AttentionSignalSourceSchema,
+  AttentionSignalSchema,
+  AttentionEvidenceSchema,
+} from "./attention-evidence";
+
 export type {
   SourceSyncCandidateItem,
   SourceSyncCandidateItemPatch,

package/src/source-sync/relevance.ts

@@ -7,6 +7,12 @@
  */
 
 import { z } from "zod";
+import {
+  combineEnumerationCompleteness,
+  DiscoveryStageCountersSchema,
+  ENUMERATION_COMPLETENESS,
+  RootCoverageSchema,
+} from "./enumeration";
 
 /** 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;
@@ -165,17 +171,50 @@ 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.
+ * The set response carries it NULL before any run has completed. The three enumeration
+ * fields are all present or all absent: NULL on all three = the run predates index-first
+ * discovery (control ADR index-first-operating-knowledge-discovery).
  */
-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 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),
+    /** How completely the run enumerated; only `complete` may be called a full index. */
+    enumerationCompleteness: z.enum(ENUMERATION_COMPLETENESS).nullable(),
+    /** One entry per enumerated root. */
+    rootCoverage: z.array(RootCoverageSchema).min(1).max(64).nullable(),
+    /** What each stage did, by count (filesEnumerated is metadata only — never "indexed"). */
+    stageCounters: DiscoveryStageCountersSchema.nullable(),
+  })
+  .superRefine((s, ctx) => {
+    const present = [
+      s.enumerationCompleteness,
+      s.rootCoverage,
+      s.stageCounters,
+    ].filter((v) => v !== null).length;
+    if (present !== 0 && present !== 3) {
+      ctx.addIssue({
+        code: "custom",
+        message: "enumeration fields are all present or all absent",
+      });
+    }
+    if (
+      s.rootCoverage !== null &&
+      s.enumerationCompleteness !== null &&
+      combineEnumerationCompleteness(s.rootCoverage.map((r) => r.status)) !==
+        s.enumerationCompleteness
+    ) {
+      ctx.addIssue({
+        code: "custom",
+        message: "enumeration completeness is the combination of its roots",
+      });
+    }
+  });
 export type CandidateDiscoverySummary = z.infer<
   typeof CandidateDiscoverySummarySchema
 >;
@@ -191,6 +230,11 @@ type CandidateRelevanceFacts = {
   selectionSource: SelectionSource | null;
   documentType: string | null;
   documentTypeConfidence: number | null;
+  withheld: boolean;
+  attention: { t1: AttentionLane | null; t2: AttentionLane | null };
+  operatingKnowledgeFamily: string | null;
+  canonicalPath: string | null;
+  attentionEvidence: readonly unknown[] | null;
 };
 
 /**
@@ -198,7 +242,10 @@ type CandidateRelevanceFacts = {
  * a hidden line is never included; classification decides whether a recommendation and a
  * 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).
+ * it is a known type (control ADR source-discovery-observation-vs-policy). An
+ * operating-knowledge family needs a known type; attention evidence and a canonical path
+ * exist only on a line T1 attended and never on a withheld one (control ADR
+ * index-first-operating-knowledge-discovery).
  */
 export function refineCandidateRelevance(
   item: CandidateRelevanceFacts,
@@ -248,4 +295,31 @@ export function refineCandidateRelevance(
         "a known document type carries a confidence; unknown and absent carry none",
     });
   }
+  if (item.operatingKnowledgeFamily !== null && !knownType) {
+    ctx.addIssue({
+      code: "custom",
+      message: "an operating-knowledge family needs a known document type",
+    });
+  }
+  if (
+    item.withheld &&
+    (item.attentionEvidence !== null || item.canonicalPath !== null)
+  ) {
+    ctx.addIssue({
+      code: "custom",
+      message: "a withheld line carries no attention evidence and no path",
+    });
+  }
+  if (item.attentionEvidence !== null && item.attention.t1 === null) {
+    ctx.addIssue({
+      code: "custom",
+      message: "attention evidence exists only on a line T1 attended",
+    });
+  }
+  if (item.canonicalPath !== null && item.attention.t1 === null) {
+    ctx.addIssue({
+      code: "custom",
+      message: "a canonical path exists only on a line T1 attended",
+    });
+  }
 }

package/src/source-sync/vocabulary.ts

@@ -113,7 +113,9 @@ export type SourceSyncScopeApproverKind =
 
 /**
  * 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
+ * (control ADR source-discovery-observation-vs-policy). The set names operating
+ * knowledge — charters, playbooks, policies, decision logs, postmortems and the like —
+ * beside strategy (control ADR index-first-operating-knowledge-discovery). 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).
@@ -151,7 +153,41 @@ export const DOCUMENT_TYPES = [
   "coursework",
   "empty_template",
   "image_or_screenshot",
+  // Operating knowledge (control ADR index-first-operating-knowledge-discovery):
+  "team_charter",
+  "process_playbook",
+  "policy_handbook",
+  "onboarding_guide",
+  "values_culture",
+  "positioning_messaging",
+  "decision_log",
+  "postmortem",
+  "metrics_definition",
+  "operating_cadence",
   "unknown",
 ] as const;
 export type DocumentType = (typeof DOCUMENT_TYPES)[number];
 export type KnownDocumentType = Exclude<DocumentType, "unknown">;
+
+/**
+ * WHAT KIND of operating knowledge a source is: what the company is trying to do
+ * (direction), how it is organized to do it (operating_model), how it runs
+ * (practices), who it is and for whom (identity_market), and what it decided and
+ * learned (decisions_learning). Control ADR index-first-operating-knowledge-discovery.
+ *
+ * A NAME the product derives from the resolved document type — the backend's
+ * versioned policy table owns the type -> family mapping, exactly as it owns
+ * sourceClass. It is NOT the backend's relevance-policy family (strategy,
+ * reference, corporate_record, …), which never travels on the wire. Board and
+ * financial material are ordinary members of `direction`; no family is required
+ * to exist for a discovery to be valid.
+ */
+export const OPERATING_KNOWLEDGE_FAMILIES = [
+  "direction",
+  "operating_model",
+  "practices",
+  "identity_market",
+  "decisions_learning",
+] as const;
+export type OperatingKnowledgeFamily =
+  (typeof OPERATING_KNOWLEDGE_FAMILIES)[number];