@company-semantics/contracts 89.2.0 → 91.0.0

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

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