@company-semantics/contracts 89.2.0 → 91.0.0

package/src/proactive/facts.ts

@@ -23,7 +23,9 @@
  *   receive different prose because they were handed different facts.
  */
 
+import type { WorkflowOutcomeData } from "../message-parts/workflow-outcome";
 import type { OrgSharedTransitionTrigger } from "../org/shared-transition";
+import type { ExplainedWorkflowOutcome } from "../workflows/deferred-route";
 
 // =============================================================================
 // Per-template facts
@@ -189,6 +191,39 @@ export interface SourceSyncReviewReadyFacts {
   readonly checkpoint: "candidates" | "synthesis";
 }
 
+// =============================================================================
+// Workflow settlement facts (control ADR-CTRL-540 phase 2)
+// =============================================================================
+
+/**
+ * The settlement data part a pushed chat may carry: an explained, fact-free
+ * outcome.
+ */
+export type ExplainedWorkflowOutcomeData = Omit<
+  WorkflowOutcomeData,
+  "outcome"
+> & {
+  readonly outcome: ExplainedWorkflowOutcome;
+};
+
+/**
+ * A workflow ended in a failure a person can act on, and nobody was watching.
+ *
+ * FACT-FREE (INV-PROACTIVE-CONTENT). `narration` is the BACKEND's deterministic
+ * settlement copy (src/chat/workflow-outcome-copy.ts), rendered from the
+ * fact-stripped outcome (`facts: null`) — the same sentence the launching chat
+ * would have received, so one module owns settlement wording and it already
+ * carries the call-to-action ban. `outcome` is the settlement data part with
+ * the frozen outcome's facts stripped: reason and affordance ids only, each
+ * affordance re-gated per viewer at render and executed by the server.
+ */
+export interface WorkflowNeedsAttentionFacts {
+  /** The backend settlement narration for this outcome, told with `facts: null`. */
+  readonly narration: string;
+  /** `{ workflowId, outcome }` — explained route only, `facts: null`. */
+  readonly outcome: ExplainedWorkflowOutcomeData;
+}
+
 // =============================================================================
 // ProactiveChatFacts
 // =============================================================================
@@ -207,4 +242,5 @@ export interface ProactiveChatFacts {
   readonly billingSuspended: BillingSuspendedFacts;
   readonly billingSubscriptionCanceled: BillingSubscriptionCanceledFacts;
   readonly sourceSyncReviewReady: SourceSyncReviewReadyFacts;
+  readonly workflowNeedsAttention: WorkflowNeedsAttentionFacts;
 }

package/src/proactive/index.ts

@@ -51,6 +51,8 @@ export type {
   BillingSuspendedFacts,
   BillingSubscriptionCanceledFacts,
   SourceSyncReviewReadyFacts,
+  ExplainedWorkflowOutcomeData,
+  WorkflowNeedsAttentionFacts,
   ProactiveChatFacts,
 } from "./facts";
 export { PROACTIVE_CHAT_MAX_REPLIES } from "./composer";

package/src/proactive/kinds.ts

@@ -302,6 +302,35 @@ export const PROACTIVE_EVENT_KIND_IDS = [
    * times its job is redelivered.
    */
   "orgStructure.review_ready",
+
+  // ===========================================================================
+  // Workflow settlements (control ADR-CTRL-540 phase 2; control ADR
+  // affordance-system)
+  // ===========================================================================
+  //
+  // A workflow that settles with no launching conversation (a scheduled
+  // rediscovery, an upkeep re-synthesis, a launch nobody docked into a chat)
+  // is ROUTED here by the backend, per reason, through the frozen
+  // `*_DEFERRED_ROUTE_OF_REASON` tables in ../workflows/deferred-route.
+  //
+  // TRIGGER: the committed `deferred → routed` transition of the settlement
+  // row (INV-PROACTIVE-TRIGGER). OCCURRENCE KEY:
+  // `workflow-settled:{workflowId}:{executionEpoch}` — one settlement announces
+  // once, however often the sweep runs.
+  /**
+   * A workflow ended in a failure a person can act on. `explained` — a pushed
+   * chat that says what happened, FACT-FREE (reason only), carrying the frozen
+   * outcome so its grounded affordances render as controls; plus a born-read
+   * inbox row. No banner: one background run is not the workspace broken.
+   */
+  "workflow.needs_attention",
+  /**
+   * A workflow finished (or failed with nothing to offer) while nobody was
+   * watching. A `notice` — an unread inbox row and nothing else: telling it
+   * needs counts, which are authority-sensitive and must re-render under the
+   * reader's current authority, never freeze into a chat.
+   */
+  "workflow.finished",
 ] as const;
 export type ProactiveEventKind = (typeof PROACTIVE_EVENT_KIND_IDS)[number];
 

package/src/proactive/registry.ts

@@ -262,4 +262,26 @@ export const PROACTIVE_EVENT_KINDS = {
     class: "notice",
     inboxKind: "proactive.org_structure_review_ready",
   },
+
+  // ===========================================================================
+  // Workflow settlements (control ADR-CTRL-540 phase 2)
+  // ===========================================================================
+  //
+  // Routed per reason by the backend through ../workflows/deferred-route. NO
+  // PLAN SETS `emailKind` or `actionItemKind`: a background run's ending is
+  // announced, not standing work.
+  /**
+   * A failure a person can act on. EXPLAINED: the fact-free chat carries the
+   * badge and the frozen outcome; the inbox row is born read.
+   */
+  "workflow.needs_attention": {
+    class: "explained",
+    chatTemplate: "workflowNeedsAttention",
+    inboxKind: "proactive.workflow_needs_attention",
+  },
+  /** A finished run nobody watched. A NOTICE: the inbox row is the attention. */
+  "workflow.finished": {
+    class: "notice",
+    inboxKind: "proactive.workflow_finished",
+  },
 } as const satisfies Record<ProactiveEventKind, ProactiveEventDefinition>;

package/src/proactive/surfaces.ts

@@ -91,5 +91,7 @@ export const PROACTIVE_CHAT_TEMPLATES = [
   "billingSubscriptionCanceled",
   /** "A source review is ready — here is what it is and what happens if you leave it." */
   "sourceSyncReviewReady",
+  /** "A background run did not finish — here is what happened." Fact-free. */
+  "workflowNeedsAttention",
 ] as const;
 export type ProactiveChatTemplate = (typeof PROACTIVE_CHAT_TEMPLATES)[number];

package/src/proactive/templates/README.md

@@ -66,6 +66,13 @@ chat. That is the precedent notify/'s README states for outbound notifications
   nothing. It names no count, no document and no source: all three are
   scope-gated, and a frozen sentence cannot be taken back.
   `../__tests__/vocabulary.test.ts` enforces "no digit" for both checkpoints.
+- **`workflow-needs-attention.ts` FRAMES; IT DOES NOT NARRATE.** Its `text` is
+  the backend's settlement narration verbatim (one owner of settlement wording),
+  its title is per workflow type with no digit and no next step, it has no
+  chips, and it carries the fact-free outcome as `outcome` so the outcome's
+  grounded affordances render as real controls (control ADR
+  `affordance-system`). `../__tests__/workflow-attention.test.ts` pins all of
+  it.
 
 ## Public API
 
@@ -80,10 +87,11 @@ chat. That is the precedent notify/'s README states for outbound notifications
 | `billingSuspendedComposer`            | The grace period elapsed; leads with "nothing was deleted"      |
 | `billingSubscriptionCanceledComposer` | Seats ended; AI funds are not forfeit                           |
 | `sourceSyncReviewReadyComposer`       | A source review waits; nothing has happened yet; no count       |
+| `workflowNeedsAttentionComposer`      | A background run failed; frames the backend narration, no chips |
 
 ## Dependencies
 
 Type-only imports of `ProactiveChatComposer` (`../composer`),
 `ProactiveChatTemplate` (`../surfaces`) and the per-template facts
-(`../facts`). No `zod`, no runtime imports beyond the sibling template
+(`../facts`), and of `WorkflowType` (`../../workflows`). No `zod`, no runtime imports beyond the sibling template
 modules.

package/src/proactive/templates/index.ts

@@ -31,6 +31,7 @@ import { billingSuspendedComposer } from "./billing-suspended";
 import { morningBriefComposer } from "./morning-brief";
 import { orgBecameSharedComposer } from "./org-became-shared";
 import { sourceSyncReviewReadyComposer } from "./source-sync-review-ready";
+import { workflowNeedsAttentionComposer } from "./workflow-needs-attention";
 
 export const PROACTIVE_CHAT_COMPOSERS = {
   orgBecameShared: orgBecameSharedComposer,
@@ -41,4 +42,5 @@ export const PROACTIVE_CHAT_COMPOSERS = {
   billingSuspended: billingSuspendedComposer,
   billingSubscriptionCanceled: billingSubscriptionCanceledComposer,
   sourceSyncReviewReady: sourceSyncReviewReadyComposer,
+  workflowNeedsAttention: workflowNeedsAttentionComposer,
 } as const satisfies Record<ProactiveChatTemplate, ProactiveChatComposer>;

package/src/proactive/templates/workflow-needs-attention.ts

@@ -0,0 +1,35 @@
+/**
+ * The workflow-needs-attention pushed chat — a background run ended in a
+ * failure a person can act on, while nobody was watching.
+ *
+ * THIS COMPOSER FRAMES; IT DOES NOT NARRATE. The sentence is the backend's
+ * deterministic settlement narration (one owner of settlement wording, already
+ * under the call-to-action ban), passed in as `narration`. The composer adds a
+ * title per workflow type and carries the fact-free outcome so its grounded
+ * affordances render as real controls (control ADR affordance-system). It
+ * offers no next step in words and no chips: a chip only sends a chat prompt,
+ * which is not grounded in a control.
+ *
+ * NO COUNTS (INV-PROACTIVE-CONTENT): the outcome's facts are stripped and the
+ * narration is told from the stripped outcome.
+ */
+import type { WorkflowType } from "../../workflows/types";
+import type { ProactiveChatComposer } from "../composer";
+
+const TITLE_OF_WORKFLOW_TYPE = {
+  "source-sync/discover": "The drive search did not finish",
+  "source-sync/synthesize": "The document update did not finish",
+  "org-structure/hris-connect": "The org structure analysis did not finish",
+  "org-structure/reanalyze": "The org structure analysis did not finish",
+} as const satisfies Record<WorkflowType, string>;
+
+export const workflowNeedsAttentionComposer: ProactiveChatComposer<"workflowNeedsAttention"> =
+  {
+    template: "workflowNeedsAttention",
+    compose: (facts) => ({
+      title: TITLE_OF_WORKFLOW_TYPE[facts.outcome.outcome.workflowType],
+      text: facts.narration,
+      replies: [],
+      outcome: facts.outcome,
+    }),
+  };

package/src/root-exports/README.md

@@ -48,6 +48,7 @@ documented in its owning domain (`src/org/`, `src/chat/`, `src/comments/`, …).
 **Internal domains:**
 
 - `action-items`
+- `affordances`
 - `api`
 - `autotune`
 - `chat`

package/src/root-exports/delivery.ts

@@ -201,6 +201,8 @@ export type {
   ProactiveEventDefinition,
   OrgBecameSharedFacts,
   MorningBriefFacts,
+  ExplainedWorkflowOutcomeData,
+  WorkflowNeedsAttentionFacts,
   ProactiveChatFacts,
   ProactiveChatComposer,
   ProactiveChatMessage,
@@ -219,31 +221,60 @@ export type { WorkflowType } from "../workflows/index";
 
 // The typed outcome of a workflow's terminal transition (control ADR-CTRL-540):
 // per-type closed reasons, typed facts and an explicit disposition, classified
-// once by the backend and frozen. See src/workflows/outcome.ts.
+// once by the backend and frozen. Each ending also freezes the next steps its
+// reason offers (control ADR affordance-system); `affordancesOfOutcome` is the
+// one projection consumers render from. An ending with no launching
+// conversation takes its reason's deferred route (explained | notice | covered
+// | silent). See src/workflows/outcome.ts and src/workflows/deferred-route.ts.
 export {
+  DEFERRED_ROUTES,
+  DISCOVER_AFFORDANCES_OF_REASON,
+  DISCOVER_DEFERRED_ROUTE_OF_REASON,
   DISCOVER_OUTCOME_KIND_OF_REASON,
+  DeferredRouteSchema,
   DiscoverOutcomeFactsSchema,
   DiscoverWorkflowOutcomeSchema,
   HrisConnectWorkflowOutcomeSchema,
+  ORG_STRUCTURE_AFFORDANCES_OF_REASON,
+  ORG_STRUCTURE_DEFERRED_ROUTE_OF_REASON,
   ORG_STRUCTURE_OUTCOME_KIND_OF_REASON,
   OrgStructureOutcomeFactsSchema,
   ReanalyzeWorkflowOutcomeSchema,
+  SETTLEMENT_AUDIENCE_POLICIES,
+  SETTLEMENT_COVERING_KINDS,
+  SETTLEMENT_SILENT_REASONS,
+  SYNTHESIZE_AFFORDANCES_OF_REASON,
+  SYNTHESIZE_DEFERRED_ROUTE_OF_REASON,
   SYNTHESIZE_OUTCOME_KIND_OF_REASON,
   SynthesizeOutcomeFactsSchema,
   SynthesizeWorkflowOutcomeSchema,
+  WORKFLOW_AFFORDANCES_OF_REASON,
+  WORKFLOW_DEFERRED_ROUTE_OF_REASON,
   WORKFLOW_OUTCOME_KINDS,
   WorkflowOutcomeDispositionSchema,
   WorkflowOutcomeSchema,
+  affordancesOfOutcome,
+  affordancesOfReason,
+  deferredRouteOf,
+  toExplainedOutcome,
 } from "../workflows/index";
 
 export type {
+  DeferredRoute,
+  DeferredRouteKind,
   DiscoverOutcomeFacts,
   DiscoverOutcomeReason,
   DiscoverWorkflowOutcome,
+  ExplainedDiscoverReason,
+  ExplainedOrgStructureReason,
+  ExplainedSynthesizeReason,
+  ExplainedWorkflowOutcome,
   HrisConnectWorkflowOutcome,
   OrgStructureOutcomeFacts,
   OrgStructureOutcomeReason,
   ReanalyzeWorkflowOutcome,
+  SettlementAudiencePolicy,
+  SettlementCoveringKind,
   SynthesizeOutcomeFacts,
   SynthesizeOutcomeReason,
   SynthesizeWorkflowOutcome,
@@ -252,3 +283,40 @@ export type {
   WorkflowOutcomeKind,
   WorkflowOutcomeOf,
 } from "../workflows/index";
+
+// Affordances (control ADR affordance-system): the closed vocabulary of next
+// steps the product may offer, as INSTANCES ({ id, args? }), with each one's
+// binding kind and live availability condition. An affordance is offered only
+// by a domain-owned deterministic rule; existing here never offers it. See
+// src/affordances/README.md.
+export {
+  AFFORDANCE_AVAILABILITY_IDS,
+  AFFORDANCE_AVAILABILITY_OF,
+  AFFORDANCE_ARGS,
+  AFFORDANCE_BINDING_KINDS,
+  AFFORDANCE_BINDING_KIND_OF,
+  AFFORDANCE_IDS,
+  AFFORDANCE_UNAVAILABLE_REASONS,
+  AffordanceAvailabilityIdSchema,
+  AffordanceAvailabilitySchema,
+  AffordanceIdSchema,
+  AffordanceSchema,
+  MAX_OFFERED_AFFORDANCES,
+  NO_ARG_AFFORDANCE_IDS,
+  OfferedAffordanceSchema,
+  PROJECTED_AFFORDANCE_IDS,
+  ReviewOpenArgsSchema,
+  sameAffordances,
+} from "../affordances/index";
+
+export type {
+  Affordance,
+  AffordanceArgs,
+  AffordanceAvailability,
+  AffordanceAvailabilityId,
+  AffordanceBindingKind,
+  AffordanceId,
+  AffordanceUnavailableReason,
+  OfferedAffordance,
+  ProjectedAffordanceId,
+} from "../affordances/index";

package/src/source-sync/README.md

@@ -165,7 +165,15 @@ product policy in the backend decides what that means.
   what a file IS — `corporate_formation_record`, never `irrelevant_doc` —
   never how relevant it is. A medium is not a meaning: `image_or_screenshot`
   is graded on its content. `unknown` is a real answer (the model could not
-  tell, or two reads disagreed) and is always last.
+  tell, or two reads disagreed) and is always last. There are forty: the ten
+  operating-knowledge types (`team_charter` … `operating_cadence`, control ADR
+  `index-first-operating-knowledge-discovery`) sit just before `unknown`.
+- **Operating-knowledge family is a derived name.**
+  `OPERATING_KNOWLEDGE_FAMILIES` (`direction`, `operating_model`, `practices`,
+  `identity_market`, `decisions_learning`) is resolved by backend policy from
+  the resolved type, like `sourceClass`, and travels as the item's
+  `operatingKnowledgeFamily`, which needs a known type. It is not the backend's
+  relevance-policy family, which never travels.
 - **The resolved type travels, nothing else.** The candidate item's
   `documentType` and `documentTypeConfidence` (0..1) carry the RESOLVED type,
   after the backend reconciles the T1 and T2 observations. Both are null on an
@@ -191,6 +199,63 @@ product policy in the backend decides what that means.
   is uncertainty, never irrelevance. `peek_confirms` / `peek_contradicts`
   stay for v1-pinned rows.
 
+## Enumeration
+
+Doctrine: control ADR `index-first-operating-knowledge-discovery`. Vocabulary:
+ADR `operating-knowledge-discovery-vocabulary`. The sets live in
+`enumeration.ts`.
+
+- **A partial enumeration is never presented as an index of the corpus.**
+  `ENUMERATION_COMPLETENESS` has four values, never a boolean: `complete`,
+  `local_budget_truncated` (our ceiling), `provider_incomplete` (the
+  provider's incomplete search) and `both`. Only `complete` may be called a
+  full index. Any other value means absence is unknown, not negative evidence
+  (INV-SOURCESYNC-PARTIAL-ENUMERATION-IS-UNKNOWN).
+- **Per root, never by name.** `RootCoverage` covers one root
+  (`ENUMERATION_ROOT_KINDS`: `user`, `shared_drive`, `domain`). It holds the
+  shared drive's provider id (null for the other kinds), the root's status and
+  count, the observed modified-time bounds (present exactly when it enumerated
+  a file) and the skipped ranges (none when it is complete). It never holds a
+  drive, folder or file name.
+- **The run's completeness is the combination of its roots.**
+  `combineEnumerationCompleteness` is pure: our ceiling anywhere and the
+  provider's incompleteness anywhere make `both`, and the run is `complete`
+  only when every root is.
+- **Counters name what they did.** `DiscoveryStageCounters` holds
+  `filesEnumerated`, `filesMetadataEligible`, `filesT0Scored`,
+  `filesT1Attended`, `filesPeeked`, `filesClassified`, `filesShown` and
+  `filesRetained`, and the counts narrow from enumerated to shown. A metadata
+  count never reads as a content read: there is no `filesIndexed`.
+- **On the discovery summary, all or none.** `enumerationCompleteness`,
+  `rootCoverage` (1..64) and `stageCounters` are required and nullable. Either
+  all three are present, or all three are null, which means the run predates
+  index-first discovery.
+
+## Attention evidence
+
+Vocabulary: ADR `operating-knowledge-discovery-vocabulary`. The schemas live
+in `attention-evidence.ts`.
+
+- **Why a file got T1 attention.** `AttentionEvidence` is an array of at most
+  six signals with at most one per `ATTENTION_SIGNAL_KINDS` kind: `tree_prior`
+  (a score and the folder's provider `folderId`), `path_terms` (matched
+  product terms), `content_match` (matched plan terms, a strength and the
+  `probeId`), `breadth` (a `SHARING_BREADTHS` member, so there is no new
+  breadth vocabulary), `recency` and `mime_prior` (a score each).
+- **Every signal has provenance.** Each signal carries
+  `source: { producer, version }`
+  (INV-SOURCESYNC-ATTENTION-EVIDENCE-HAS-PROVENANCE). `producer` is a
+  documented lowercase key, not a closed set. The documented keys are
+  `lexicon`, `source-discovery-tree-triage`, `source-discovery-plan` and
+  `metadata-scorer`.
+- **Terms are vocabulary, never content.** A term is product or plan
+  vocabulary that matched. It is never text read from the file and never a
+  slice of its name. A folder is named only by its provider id.
+- **Only after T1 attention, never when withheld.** The item's
+  `attentionEvidence` and `canonicalPath` (the Tier-1 path) are null when the
+  line never received T1 attention, when it is withheld, and for runs before
+  index-first discovery.
+
 ## Public API
 
 - `SOURCE_CLASSES` / `SourceClass` — what kind of document a source is.
@@ -210,12 +275,34 @@ product policy in the backend decides what that means.
   `org_admin` or `unit_head`.
 - `DOCUMENT_TYPES` / `DocumentType` / `KnownDocumentType` — what a source is,
   structurally; `KnownDocumentType` excludes `unknown` (see Document type).
+- `OPERATING_KNOWLEDGE_FAMILIES` / `OperatingKnowledgeFamily` — what kind of
+  operating knowledge a line is, resolved by the backend (see Document type).
+- `ENUMERATION_COMPLETENESS` / `EnumerationCompleteness` — how completely a
+  run or root was enumerated; only `complete` is a full index (see
+  Enumeration).
+- `ENUMERATION_ROOT_KINDS` / `EnumerationRootKind` — `user`, `shared_drive` or
+  `domain`.
+- `combineEnumerationCompleteness(statuses)` — the pure fold of per-root
+  statuses into one.
+- `EnumerationSkippedRangeSchema` — a modified-time range left unenumerated.
+- `RootCoverageSchema` / `RootCoverage` — how far one root's enumeration got.
+- `DiscoveryStageCountersSchema` / `DiscoveryStageCounters` — what each stage
+  did, by count, narrowing from enumerated to shown.
+- `ATTENTION_SIGNAL_KINDS` / `AttentionSignalKind` — the kinds of attention
+  signal (see Attention evidence).
+- `AttentionSignalSourceSchema` / `AttentionSignalSource` — a signal's
+  producer and version.
+- `AttentionSignalSchema` / `AttentionSignal` — one signal: a discriminated
+  union on `kind`.
+- `AttentionEvidenceSchema` / `AttentionEvidence` — why a line got T1
+  attention: at most one signal per kind.
 - `SourceSyncDiscoveryRunResponseSchema` / `SourceSyncDiscoveryRunResponse` —
   the discovery run started, and the workflow narrating it.
 - `SourceSyncCandidateItemSchema` / `SourceSyncCandidateItem` — one source
   proposed for one target document, with the server's `included` and the
   resolved `documentType` / `documentTypeConfidence` (null when unclassified
-  or v1-pinned).
+  or v1-pinned), `operatingKnowledgeFamily`, `canonicalPath` and
+  `attentionEvidence` (null before index-first discovery).
 - `SourceSyncCandidateSetResponseSchema` / `SourceSyncCandidateSetResponse` —
   the draft set under review: its revision, items, presented questions,
   distinct-file `totals` and cost estimate.
@@ -307,7 +394,10 @@ product policy in the backend decides what that means.
 
 `rules.ts` imports only `zod`, `../api/primitives` and `./vocabulary`.
 `upkeep.ts` and `reach.ts` import only `zod` and `../api/primitives`.
-`candidate-item.ts` imports only `zod`, `../api/primitives`, `./vocabulary`
-and `./relevance`.
-`relevance.ts` imports only `zod`.
+`candidate-item.ts` imports only `zod`, `../api/primitives`, `./vocabulary`,
+`./relevance` and `./attention-evidence`.
+`relevance.ts` imports only `zod` and `./enumeration`.
+`enumeration.ts` imports only `zod` and `../api/primitives` (never
+`./relevance`, so there is no cycle).
+`attention-evidence.ts` imports only `zod` and `./vocabulary`.
 `vocabulary.ts` itself has no imports.

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

@@ -0,0 +1,96 @@
+/**
+ * Attention evidence tests.
+ *
+ * INVARIANTS TESTED:
+ * - Every attention signal kind is accepted with its provenance; empty evidence
+ *   is accepted
+ * - An attention signal kind appears at most once
+ * - A tree prior names its folder by provider id; a content match names its probe
+ * - Every signal carries a lowercase producer key and a version
+ * - Breadth reuses the sharing breadth vocabulary
+ */
+
+import { describe, it, expect } from "vitest";
+
+import { AttentionEvidenceSchema } from "../attention-evidence";
+
+const source = { producer: "lexicon", version: "3" };
+const everyKind = [
+  {
+    kind: "tree_prior",
+    score: 0.72,
+    folderId: "0AbcFolder",
+    source: { producer: "source-discovery-tree-triage", version: "1" },
+  },
+  { kind: "path_terms", values: ["planning", "qbr"], source },
+  {
+    kind: "content_match",
+    values: ["operating review"],
+    strength: 0.8,
+    probeId: "practices_1",
+    source: { producer: "source-discovery-plan", version: "2" },
+  },
+  {
+    kind: "breadth",
+    value: "domain",
+    source: { producer: "metadata-scorer", version: "4" },
+  },
+  {
+    kind: "recency",
+    score: 0.31,
+    source: { producer: "metadata-scorer", version: "4" },
+  },
+  {
+    kind: "mime_prior",
+    score: 0.6,
+    source: { producer: "metadata-scorer", version: "4" },
+  },
+] as const;
+
+describe("AttentionEvidenceSchema", () => {
+  it("accepts one entry of every attention signal kind with its provenance", () => {
+    expect(AttentionEvidenceSchema.safeParse(everyKind).success).toBe(true);
+    expect(AttentionEvidenceSchema.safeParse([]).success).toBe(true);
+  });
+
+  it("an attention signal kind appears at most once", () => {
+    expect(
+      AttentionEvidenceSchema.safeParse([everyKind[1], everyKind[1]]).success,
+    ).toBe(false);
+  });
+
+  it("a tree prior names the folder and a content match names the probe", () => {
+    const { folderId: _f, ...noFolder } = everyKind[0];
+    const { probeId: _p, ...noProbe } = everyKind[2];
+    expect(AttentionEvidenceSchema.safeParse([noFolder]).success).toBe(false);
+    expect(AttentionEvidenceSchema.safeParse([noProbe]).success).toBe(false);
+  });
+
+  it("refuses an attention signal without a producer version", () => {
+    expect(
+      AttentionEvidenceSchema.safeParse([
+        {
+          kind: "recency",
+          score: 0.3,
+          source: { producer: "metadata-scorer" },
+        },
+      ]).success,
+    ).toBe(false);
+    expect(
+      AttentionEvidenceSchema.safeParse([
+        {
+          kind: "recency",
+          score: 0.3,
+          source: { producer: "Has Spaces", version: "1" },
+        },
+      ]).success,
+    ).toBe(false);
+  });
+
+  it("breadth reuses the sharing breadth vocabulary", () => {
+    expect(
+      AttentionEvidenceSchema.safeParse([{ ...everyKind[3], value: "public" }])
+        .success,
+    ).toBe(false);
+  });
+});

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