@company-semantics/contracts 89.1.0 → 90.0.0

package/src/source-sync/__tests__/barrel.test.ts

@@ -20,6 +20,9 @@
  *   the same binding.
  * - `DOCUMENT_TYPES` is reachable from the root as the same binding, and its
  *   two types are named by the barrel.
+ * - Every index-first discovery name (operating-knowledge families, the
+ *   enumeration vocabulary, attention evidence) is reachable from the root as
+ *   the same binding, and its types are named by the barrel.
  * - `ACTION_ITEM_KINDS` at the root carries `sourceSync.approval_pending`.
  * - The root re-exports the domain barrel explicitly.
  *
@@ -69,7 +72,9 @@ import type {
   SourceSyncStandingOrder,
   SourceSyncStandingOrdersResponse,
 } from "../../index";
+import * as attentionEvidence from "../attention-evidence";
 import * as candidateItem from "../candidate-item";
+import * as enumeration from "../enumeration";
 import * as reach from "../reach";
 import * as relevance from "../relevance";
 import * as rules from "../rules";
@@ -260,6 +265,40 @@ describe("source-sync Release C package surface", () => {
     expect([...barrelTypeExports]).toContain("KnownDocumentType");
   });
 
+  it("every index-first discovery name is reachable from the root as the same binding", () => {
+    const root = rootBarrel as Record<string, unknown>;
+    for (const [name, module] of [
+      ["OPERATING_KNOWLEDGE_FAMILIES", vocabulary],
+      ["ENUMERATION_COMPLETENESS", enumeration],
+      ["ENUMERATION_ROOT_KINDS", enumeration],
+      ["combineEnumerationCompleteness", enumeration],
+      ["EnumerationSkippedRangeSchema", enumeration],
+      ["RootCoverageSchema", enumeration],
+      ["DiscoveryStageCountersSchema", enumeration],
+      ["ATTENTION_SIGNAL_KINDS", attentionEvidence],
+      ["AttentionSignalSourceSchema", attentionEvidence],
+      ["AttentionSignalSchema", attentionEvidence],
+      ["AttentionEvidenceSchema", attentionEvidence],
+    ] as const) {
+      const declared = (module as Record<string, unknown>)[name];
+      expect(declared, `${name} is declared`).toBeDefined();
+      expect(root[name], `${name} at the root`).toBe(declared);
+    }
+    for (const type of [
+      "OperatingKnowledgeFamily",
+      "EnumerationCompleteness",
+      "EnumerationRootKind",
+      "RootCoverage",
+      "DiscoveryStageCounters",
+      "AttentionSignalKind",
+      "AttentionSignalSource",
+      "AttentionSignal",
+      "AttentionEvidence",
+    ]) {
+      expect([...barrelTypeExports]).toContain(type);
+    }
+  });
+
   it("exposes sourceSync.approval_pending in ACTION_ITEM_KINDS at the root", () => {
     expect(rootBarrel.ACTION_ITEM_KINDS).toContain(
       "sourceSync.approval_pending",

package/src/source-sync/__tests__/enumeration.test.ts

@@ -0,0 +1,160 @@
+/**
+ * Index-first enumeration vocabulary tests.
+ *
+ * INVARIANTS TESTED:
+ * - Root statuses combine so that only every root complete is `complete`, and
+ *   our ceiling plus the provider's incompleteness is `both`
+ * - A complete root skips nothing; a root id names exactly a shared drive
+ * - A skipped range never ends before it starts
+ * - Observed modified times are present exactly when a root enumerated a file
+ * - Stage counters are non-negative and narrow from enumerated to shown
+ */
+
+import { describe, it, expect } from "vitest";
+
+import {
+  combineEnumerationCompleteness,
+  DiscoveryStageCountersSchema,
+  EnumerationSkippedRangeSchema,
+  RootCoverageSchema,
+} from "../enumeration";
+
+function root(overrides: Record<string, unknown> = {}) {
+  return {
+    rootKind: "user",
+    rootId: null,
+    status: "complete",
+    enumeratedCount: 3,
+    observedOldestModifiedTime: "2025-01-01T00:00:00.000Z",
+    observedNewestModifiedTime: "2026-09-30T00:00:00.000Z",
+    skippedRanges: [],
+    ...overrides,
+  };
+}
+
+function counters(overrides: Record<string, unknown> = {}) {
+  return {
+    filesEnumerated: 1000,
+    filesMetadataEligible: 800,
+    filesT0Scored: 600,
+    filesT1Attended: 120,
+    filesPeeked: 40,
+    filesClassified: 200,
+    filesShown: 25,
+    filesRetained: 30,
+    ...overrides,
+  };
+}
+
+const RANGE = {
+  from: "2024-01-01T00:00:00.000Z",
+  to: "2024-06-30T00:00:00.000Z",
+};
+
+describe("enumeration", () => {
+  it("combines root statuses into one enumeration completeness", () => {
+    expect(combineEnumerationCompleteness(["complete", "complete"])).toBe(
+      "complete",
+    );
+    expect(
+      combineEnumerationCompleteness(["complete", "local_budget_truncated"]),
+    ).toBe("local_budget_truncated");
+    expect(
+      combineEnumerationCompleteness(["provider_incomplete", "complete"]),
+    ).toBe("provider_incomplete");
+    expect(
+      combineEnumerationCompleteness([
+        "local_budget_truncated",
+        "provider_incomplete",
+      ]),
+    ).toBe("both");
+    expect(combineEnumerationCompleteness(["both"])).toBe("both");
+  });
+
+  it("a complete root skips nothing", () => {
+    expect(RootCoverageSchema.safeParse(root()).success).toBe(true);
+    expect(
+      RootCoverageSchema.safeParse(root({ skippedRanges: [RANGE] })).success,
+    ).toBe(false);
+    expect(
+      RootCoverageSchema.safeParse(
+        root({ status: "local_budget_truncated", skippedRanges: [RANGE] }),
+      ).success,
+    ).toBe(true);
+  });
+
+  it("a root id names exactly a shared drive", () => {
+    expect(
+      RootCoverageSchema.safeParse(root({ rootId: "0AbCdEf" })).success,
+    ).toBe(false);
+    expect(
+      RootCoverageSchema.safeParse(root({ rootKind: "shared_drive" })).success,
+    ).toBe(false);
+    expect(
+      RootCoverageSchema.safeParse(
+        root({ rootKind: "shared_drive", rootId: "0AbCdEf" }),
+      ).success,
+    ).toBe(true);
+    expect(
+      RootCoverageSchema.safeParse(root({ rootKind: "domain" })).success,
+    ).toBe(true);
+  });
+
+  it("refuses a skipped range that ends before it starts", () => {
+    expect(EnumerationSkippedRangeSchema.safeParse(RANGE).success).toBe(true);
+    expect(
+      EnumerationSkippedRangeSchema.safeParse({
+        from: RANGE.to,
+        to: RANGE.from,
+      }).success,
+    ).toBe(false);
+  });
+
+  it("an empty root has no observed modified times", () => {
+    expect(
+      RootCoverageSchema.safeParse(root({ enumeratedCount: 0 })).success,
+    ).toBe(false);
+    expect(
+      RootCoverageSchema.safeParse(
+        root({
+          enumeratedCount: 0,
+          observedOldestModifiedTime: null,
+          observedNewestModifiedTime: null,
+        }),
+      ).success,
+    ).toBe(true);
+    expect(
+      RootCoverageSchema.safeParse(root({ observedNewestModifiedTime: null }))
+        .success,
+    ).toBe(false);
+    expect(
+      RootCoverageSchema.safeParse(
+        root({
+          observedOldestModifiedTime: "2026-09-30T00:00:00.000Z",
+          observedNewestModifiedTime: "2025-01-01T00:00:00.000Z",
+        }),
+      ).success,
+    ).toBe(false);
+  });
+
+  it("stage counters narrow from enumerated to shown", () => {
+    expect(DiscoveryStageCountersSchema.safeParse(counters()).success).toBe(
+      true,
+    );
+    expect(
+      DiscoveryStageCountersSchema.safeParse(counters({ filesPeeked: 121 }))
+        .success,
+    ).toBe(false);
+    expect(
+      DiscoveryStageCountersSchema.safeParse(counters({ filesShown: 31 }))
+        .success,
+    ).toBe(false);
+  });
+
+  it("refuses negative stage counters", () => {
+    expect(
+      DiscoveryStageCountersSchema.safeParse(counters({ filesEnumerated: -1 }))
+        .success,
+    ).toBe(false);
+  });
+});

package/src/source-sync/__tests__/schemas.test.ts

@@ -21,6 +21,13 @@
  * - 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.
+ * - Index-first discovery (control ADR index-first-operating-knowledge-discovery): an
+ *   item's operating-knowledge family, canonical path and attention evidence are
+ *   REQUIRED nullable keys; a family needs a known document type; evidence and a path
+ *   exist only on a line T1 attended and never on a withheld line.
+ * - The discovery block's enumeration fields are all present or all absent, and the
+ *   run's completeness is the combination of its roots' — a truncated run never
+ *   claims `complete`.
  */
 
 import { describe, expect, it } from "vitest";
@@ -59,6 +66,8 @@ function candidateItem(overrides: Record<string, unknown> = {}) {
     sourceClass: "board_deck",
     documentType: null,
     documentTypeConfidence: null,
+    operatingKnowledgeFamily: null,
+    canonicalPath: null,
     periodLabel: "Q3 2026",
     seriesRole: "current",
     relevance: 0.92,
@@ -74,6 +83,7 @@ function candidateItem(overrides: Record<string, unknown> = {}) {
     relevanceReasons: [],
     targetAudience: "org_wide",
     attention: { t1: null, t2: null },
+    attentionEvidence: null,
     included: true,
     treatmentUnresolved: false,
     matchReason: "A board deck for the current quarter.",
@@ -143,6 +153,9 @@ function candidateSet(overrides: Record<string, unknown> = {}) {
       filesDropped: 240,
       coveragePercent: 87,
       scanOutcome: "complete",
+      enumerationCompleteness: null,
+      rootCoverage: null,
+      stageCounters: null,
     },
     ...overrides,
   };
@@ -575,6 +588,111 @@ describe("candidate relevance", () => {
   });
 });
 
+describe("index-first discovery item fields", () => {
+  const evidence = [
+    {
+      kind: "path_terms",
+      values: ["playbook"],
+      source: { producer: "lexicon", version: "3" },
+    },
+  ];
+
+  it("an item carries its operating-knowledge family, canonical path and attention evidence", () => {
+    const parsed = SourceSyncCandidateItemSchema.safeParse(
+      candidateItem({
+        documentType: "process_playbook",
+        documentTypeConfidence: 0.88,
+        operatingKnowledgeFamily: "practices",
+        canonicalPath: "Product/How we work",
+        attention: { t1: "exploit", t2: null },
+        attentionEvidence: evidence,
+      }),
+    );
+    expect(parsed.success).toBe(true);
+    expect(parsed.data?.operatingKnowledgeFamily).toBe("practices");
+    expect(parsed.data?.canonicalPath).toBe("Product/How we work");
+    expect(parsed.data?.attentionEvidence).toEqual(evidence);
+  });
+
+  it("an item from before index-first discovery has no family, no path and no evidence", () => {
+    const parsed = SourceSyncCandidateItemSchema.safeParse(candidateItem());
+    expect(parsed.success).toBe(true);
+    expect(parsed.data?.operatingKnowledgeFamily).toBeNull();
+    expect(parsed.data?.canonicalPath).toBeNull();
+    expect(parsed.data?.attentionEvidence).toBeNull();
+    for (const key of [
+      "operatingKnowledgeFamily",
+      "canonicalPath",
+      "attentionEvidence",
+    ]) {
+      const item: Record<string, unknown> = candidateItem();
+      delete item[key];
+      expect(SourceSyncCandidateItemSchema.safeParse(item).success).toBe(false);
+    }
+  });
+
+  it("an operating-knowledge family needs a known document type", () => {
+    for (const [documentType, documentTypeConfidence] of [
+      [null, null],
+      ["unknown", null],
+    ] as const) {
+      const parsed = SourceSyncCandidateItemSchema.safeParse(
+        candidateItem({
+          documentType,
+          documentTypeConfidence,
+          operatingKnowledgeFamily: "practices",
+        }),
+      );
+      expect(parsed.success).toBe(false);
+      expect(parsed.error?.issues[0]?.message).toBe(
+        "an operating-knowledge family needs a known document type",
+      );
+    }
+  });
+
+  it("a withheld line carries no attention evidence and no path", () => {
+    for (const claim of [
+      { attentionEvidence: evidence },
+      { canonicalPath: "Finance/Board" },
+    ]) {
+      const parsed = SourceSyncCandidateItemSchema.safeParse(
+        candidateItem({
+          withheld: true,
+          attention: { t1: "exploit", t2: null },
+          ...claim,
+        }),
+      );
+      expect(parsed.success).toBe(false);
+      expect(parsed.error?.issues[0]?.message).toBe(
+        "a withheld line carries no attention evidence and no path",
+      );
+    }
+  });
+
+  it("attention evidence exists only on a line T1 attended", () => {
+    const parsed = SourceSyncCandidateItemSchema.safeParse(
+      candidateItem({
+        attention: { t1: null, t2: "explore" },
+        attentionEvidence: evidence,
+      }),
+    );
+    expect(parsed.success).toBe(false);
+    expect(parsed.error?.issues[0]?.message).toBe(
+      "attention evidence exists only on a line T1 attended",
+    );
+  });
+
+  it("a canonical path exists only on a line T1 attended", () => {
+    const parsed = SourceSyncCandidateItemSchema.safeParse(
+      candidateItem({ canonicalPath: "Product/How we work" }),
+    );
+    expect(parsed.success).toBe(false);
+    expect(parsed.error?.issues[0]?.message).toBe(
+      "a canonical path exists only on a line T1 attended",
+    );
+  });
+});
+
 describe("SourceSyncCandidateItemPatchSchema", () => {
   it("bring into review is a patch of visibility alone", () => {
     expect(
@@ -631,6 +749,111 @@ describe("SourceSyncCandidateSetResponseSchema discovery", () => {
       ).toBe(false);
     }
   });
+
+  const rootEntry = (status: string, rootId: string | null = null) => ({
+    rootKind: rootId === null ? "user" : "shared_drive",
+    rootId,
+    status,
+    enumeratedCount: 3,
+    observedOldestModifiedTime: "2024-01-01T00:00:00Z",
+    observedNewestModifiedTime: "2026-09-01T00:00:00Z",
+    skippedRanges: [],
+  });
+  const stageCounters = {
+    filesEnumerated: 100000,
+    filesMetadataEligible: 60000,
+    filesT0Scored: 60000,
+    filesT1Attended: 400,
+    filesPeeked: 120,
+    filesClassified: 300,
+    filesShown: 12,
+    filesRetained: 40,
+  };
+  const withEnumeration = (enumeration: Record<string, unknown>) =>
+    candidateSet({
+      discovery: { ...candidateSet().discovery, ...enumeration },
+    });
+
+  it("a discovery block from before index-first discovery has no enumeration fields", () => {
+    const parsed =
+      SourceSyncCandidateSetResponseSchema.safeParse(candidateSet());
+    expect(parsed.success).toBe(true);
+    expect(parsed.data?.discovery?.enumerationCompleteness).toBeNull();
+    expect(parsed.data?.discovery?.rootCoverage).toBeNull();
+    expect(parsed.data?.discovery?.stageCounters).toBeNull();
+    for (const key of [
+      "enumerationCompleteness",
+      "rootCoverage",
+      "stageCounters",
+    ]) {
+      const discovery: Record<string, unknown> = {
+        ...candidateSet().discovery,
+      };
+      delete discovery[key];
+      expect(
+        SourceSyncCandidateSetResponseSchema.safeParse(
+          candidateSet({ discovery }),
+        ).success,
+      ).toBe(false);
+    }
+  });
+
+  it("enumeration fields are all present or all absent", () => {
+    expect(
+      SourceSyncCandidateSetResponseSchema.safeParse(
+        withEnumeration({
+          enumerationCompleteness: "complete",
+          rootCoverage: [rootEntry("complete")],
+          stageCounters,
+        }),
+      ).success,
+    ).toBe(true);
+    for (const partial of [
+      { enumerationCompleteness: "complete" },
+      { enumerationCompleteness: "complete", stageCounters },
+      { rootCoverage: [rootEntry("complete")], stageCounters },
+    ]) {
+      const parsed = SourceSyncCandidateSetResponseSchema.safeParse(
+        withEnumeration(partial),
+      );
+      expect(parsed.success).toBe(false);
+      expect(parsed.error?.issues[0]?.message).toBe(
+        "enumeration fields are all present or all absent",
+      );
+    }
+  });
+
+  it("enumeration completeness is the combination of its roots", () => {
+    const rootCoverage = [
+      rootEntry("complete"),
+      rootEntry("local_budget_truncated", "0AbCdEfGhIjK"),
+    ];
+    const claimsComplete = SourceSyncCandidateSetResponseSchema.safeParse(
+      withEnumeration({
+        enumerationCompleteness: "complete",
+        rootCoverage,
+        stageCounters,
+      }),
+    );
+    expect(claimsComplete.success).toBe(false);
+    expect(claimsComplete.error?.issues[0]?.message).toBe(
+      "enumeration completeness is the combination of its roots",
+    );
+    const truncated = SourceSyncCandidateSetResponseSchema.safeParse(
+      withEnumeration({
+        enumerationCompleteness: "local_budget_truncated",
+        rootCoverage,
+        stageCounters,
+      }),
+    );
+    expect(truncated.success).toBe(true);
+    expect(truncated.data?.discovery?.stageCounters?.filesEnumerated).toBe(
+      100000,
+    );
+    expect(truncated.data?.discovery?.enumerationCompleteness).not.toBe(
+      "complete",
+    );
+  });
 });
 
 describe("SourceSyncDiscoveryRunResponseSchema", () => {

package/src/source-sync/__tests__/vocabulary.test.ts

@@ -6,18 +6,31 @@
  * order.
  *
  * INVARIANTS TESTED:
- * - Each of the twenty-three closed sets (ten Source Sync, thirteen discovery
- *   relevance) has exactly the members this release fixes
+ * - Each of the twenty-five closed sets (eleven Source Sync, thirteen discovery
+ *   relevance, one attention evidence) has exactly the members this release
+ *   fixes
  * - `decoy` is a source class; `unknown` is a sharing breadth
+ * - OPERATING_KNOWLEDGE_FAMILIES names exactly the five families
  * - 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
+ * - DOCUMENT_TYPES has exactly its forty members, the ten operating-knowledge
+ *   types immediately before `unknown`, `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)
+ * - ENUMERATION_COMPLETENESS and ENUMERATION_ROOT_KINDS sit OUTSIDE the
+ *   disjointness table: `complete` is also a scan outcome and `domain` a
+ *   sharing breadth (same word, separate axis), pinned exactly
  */
 
 import { describe, it, expect } from "vitest";
 
+import { ATTENTION_SIGNAL_KINDS } from "../attention-evidence";
+
+import {
+  ENUMERATION_COMPLETENESS,
+  ENUMERATION_ROOT_KINDS,
+} from "../enumeration";
+
 import {
   ATTENTION_LANES,
   CANDIDATE_MACHINE_STATES,
@@ -37,6 +50,7 @@ import {
 import {
   AUDIENCE_FITS,
   DOCUMENT_TYPES,
+  OPERATING_KNOWLEDGE_FAMILIES,
   SHARING_BREADTHS,
   SOURCE_CLASSES,
   SOURCE_SENSITIVITY_CLASSES,
@@ -126,6 +140,17 @@ const VOCABULARIES = [
     tuple: SOURCE_SYNC_SCOPE_APPROVER_KINDS,
     members: ["org_admin", "unit_head"],
   },
+  {
+    name: "OPERATING_KNOWLEDGE_FAMILIES",
+    tuple: OPERATING_KNOWLEDGE_FAMILIES,
+    members: [
+      "direction",
+      "operating_model",
+      "practices",
+      "identity_market",
+      "decisions_learning",
+    ],
+  },
   {
     name: "SOURCE_RELEVANCE_TIERS",
     tuple: SOURCE_RELEVANCE_TIERS,
@@ -240,6 +265,18 @@ const VOCABULARIES = [
     tuple: SCAN_OUTCOMES,
     members: ["complete", "budget_exhausted", "file_ceiling", "stopped"],
   },
+  {
+    name: "ATTENTION_SIGNAL_KINDS",
+    tuple: ATTENTION_SIGNAL_KINDS,
+    members: [
+      "tree_prior",
+      "path_terms",
+      "content_match",
+      "breadth",
+      "recency",
+      "mime_prior",
+    ],
+  },
 ] as const satisfies readonly {
   name: string;
   tuple: readonly string[];
@@ -274,6 +311,16 @@ describe("Source Sync closed sets", () => {
     expect(SHARING_BREADTHS).toContain("unknown");
   });
 
+  it("names the five operating-knowledge families", () => {
+    expect([...OPERATING_KNOWLEDGE_FAMILIES]).toEqual([
+      "direction",
+      "operating_model",
+      "practices",
+      "identity_market",
+      "decisions_learning",
+    ]);
+  });
+
   it("no member appears in two sets", () => {
     const all = VOCABULARIES.flatMap(({ tuple }) => [...tuple]);
     expect(new Set(all).size).toBe(all.length);
@@ -295,7 +342,7 @@ describe("Source Sync closed sets", () => {
 });
 
 describe("document types", () => {
-  it("has exactly the thirty document types, in order", () => {
+  it("has exactly the forty document types, in order", () => {
     expect([...DOCUMENT_TYPES]).toEqual([
       "board_deck",
       "board_minutes",
@@ -326,9 +373,34 @@ describe("document types", () => {
       "coursework",
       "empty_template",
       "image_or_screenshot",
+      "team_charter",
+      "process_playbook",
+      "policy_handbook",
+      "onboarding_guide",
+      "values_culture",
+      "positioning_messaging",
+      "decision_log",
+      "postmortem",
+      "metrics_definition",
+      "operating_cadence",
       "unknown",
     ]);
-    expect(new Set(DOCUMENT_TYPES).size).toBe(30);
+    expect(new Set(DOCUMENT_TYPES).size).toBe(40);
+  });
+
+  it("the ten operating-knowledge document types sit before unknown", () => {
+    expect(DOCUMENT_TYPES.slice(29, 39)).toEqual([
+      "team_charter",
+      "process_playbook",
+      "policy_handbook",
+      "onboarding_guide",
+      "values_culture",
+      "positioning_messaging",
+      "decision_log",
+      "postmortem",
+      "metrics_definition",
+      "operating_cadence",
+    ]);
   });
 
   it("unknown is the last document type", () => {
@@ -349,3 +421,30 @@ describe("document types", () => {
     ]);
   });
 });
+
+describe("enumeration vocabulary", () => {
+  it("enumeration vocabularies share a member with another set only where pinned", () => {
+    const others = new Set<string>(
+      VOCABULARIES.flatMap(({ tuple }) => [...tuple]),
+    );
+    // SCAN_OUTCOMES
+    expect(ENUMERATION_COMPLETENESS.filter((m) => others.has(m))).toEqual([
+      "complete",
+    ]);
+    // SHARING_BREADTHS
+    expect(ENUMERATION_ROOT_KINDS.filter((m) => others.has(m))).toEqual([
+      "domain",
+    ]);
+    expect([...ENUMERATION_COMPLETENESS]).toEqual([
+      "complete",
+      "local_budget_truncated",
+      "provider_incomplete",
+      "both",
+    ]);
+    expect([...ENUMERATION_ROOT_KINDS]).toEqual([
+      "user",
+      "shared_drive",
+      "domain",
+    ]);
+  });
+});