@company-semantics/contracts 89.1.0 → 90.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@company-semantics/contracts",
-  "version": "89.1.0",
+  "version": "90.0.0",
   "private": false,
   "repository": {
     "type": "git",
@@ -109,6 +109,7 @@
     "guard:decisions-deprecation:json": "npx tsx scripts/ci/decisions-deprecation-guard.ts --json",
     "guard:quick": "sh scripts/ci/run-guard.sh --quick",
     "ci:local": "pnpm typecheck && pnpm lint:md && pnpm guard:test && pnpm guard",
+    "verify": "sh scripts/ci/run-verify.sh",
     "guard": "sh scripts/ci/run-guard.sh",
     "guard:test": "NODE_OPTIONS='--max-old-space-size=4096' vitest run scripts/ci/__tests__",
     "release": "npx tsx scripts/release.ts",
@@ -177,14 +178,15 @@
       "picomatch@<4.0.4": ">=4.0.4",
       "esbuild@<0.28.1": ">=0.28.1",
       "linkify-it@<5.0.2": ">=5.0.2",
-      "postcss@<8.5.18": ">=8.5.18",
-      "markdown-it@<14.2.0": ">=14.2.0"
+      "postcss@<8.5.23": ">=8.5.23",
+      "markdown-it@<14.2.0": ">=14.2.0",
+      "@humanfs/node@<0.16.8": ">=0.16.8 <0.17.0"
     }
   },
   "lint-staged": {
-    "*.ts": "bash -c 'tsc -b --noEmit'",
+    "*.ts": "sh scripts/ci/unless-verified.sh tsc 'tsc -b --noEmit'",
     "*.md": "markdownlint-cli2",
     "package.json": "node -e \"JSON.parse(require('fs').readFileSync('package.json'))\""
   },
-  "securityRequirementsVersion": "bfd57aaebc7d47d195f06ba507ed3fb56da0faa9c40aca3c00f2e63dbd3b617b"
+  "securityRequirementsVersion": "8700b9fe36f8c948f12970ec54128e4f1955986dd9b634114f7501fdb1884267"
 }

package/src/api/generated-spec-hash.ts

@@ -1,3 +1,3 @@
 // AUTO-GENERATED — do not edit. Run pnpm generate:spec-hash to regenerate.
-export const SPEC_HASH = '50b15a02e5ef' as const;
-export const SPEC_HASH_FULL = '50b15a02e5efb3a03bd903551f31a4c74693891d2577816c34a030d09909e389' as const;
+export const SPEC_HASH = 'ba43b4881a93' as const;
+export const SPEC_HASH_FULL = 'ba43b4881a9318819726dfe0c0465ecae3802951f7f558fec6786a7171195a91' as const;

package/src/api/generated.ts

@@ -1675,7 +1675,7 @@ export interface paths {
         };
         /**
          * Read one analysis workflow’s generic lifecycle envelope
-         * @description The domain-agnostic projection a client polls: identity, registered type, activity-free lifecycle state, start and completion times, the opaque domain progress and result payloads (null until the domain adapter supplies them), a closed failure class on a failed workflow, and the capabilities the surface may offer — canStop from the generic layer, canContinue as the domain declares it. Org-scoped: a workflow in another workspace answers 404.
+         * @description The domain-agnostic projection a client polls: identity, registered type, activity-free lifecycle state, start and completion times, the opaque domain progress and result payloads (null until the domain adapter supplies them), a closed failure class on a failed workflow, the frozen typed outcome of the current execution epoch once it settles (null until then), and the capabilities the surface may offer — canStop from the generic layer, canContinue as the domain declares it. Org-scoped: a workflow in another workspace answers 404.
          */
         get: operations["getAnalysisWorkflow"];
         put?: never;
@@ -1706,6 +1706,26 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/api/analysis-workflows/{id}/settlement": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Deliver a settled analysis workflow’s outcome into its launching conversation now
+         * @description An ACCELERATOR, never required for correctness (control ADR-CTRL-540): every terminal transition records a settlement that the server delivers on its own — immediately after settling, and on the reconciler sweep. The app calls this when its poll sees the current execution epoch settle, so the settlement turn appears without waiting. Idempotent: a second call for the same epoch answers skipped or delivered and writes nothing new. Answers not_settled while the epoch is still moving. Org-scoped: a workflow in another workspace answers 404.
+         */
+        post: operations["deliverAnalysisWorkflowSettlement"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/api/company-md/tree": {
         parameters: {
             query?: never;
@@ -4200,6 +4220,57 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/api/internal-admin/quality/graders": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /** Every grader version with its calibration and the severities it may gate */
+        get: operations["listQualityGraders"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/api/internal-admin/quality/graders/{id}/label-queue": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /** A judge's unlabeled samples with their case content; the judge's verdict is hidden */
+        get: operations["getQualityGraderLabelQueue"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/api/internal-admin/quality/graders/{id}/labels": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /** Label a judged sample, then recalibrate the judge; reveals the judge's verdict */
+        post: operations["submitQualityGraderLabel"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/api/comments": {
         parameters: {
             query?: never;
@@ -6915,6 +6986,7 @@ export interface components {
             completedAt: string | null;
             progress: unknown | null;
             result: unknown | null;
+            outcome: unknown | null;
             error?: string;
             capabilities: {
                 canStop: boolean;
@@ -6934,6 +7006,10 @@ export interface components {
             /** @constant */
             reason: "not_running";
         };
+        DeliverWorkflowSettlementResponse: {
+            /** @enum {string} */
+            result: "delivered" | "deferred" | "busy" | "skipped" | "not_settled";
+        };
         CompanyMdListResponse: {
             items: {
                 id: string;
@@ -9252,8 +9328,10 @@ export interface components {
                 /** @enum {string} */
                 classificationState: "unclassified" | "classified";
                 sourceClass: ("board_deck" | "board_minutes" | "investor_update" | "financial_brief" | "budget_forecast" | "okr_plan" | "annual_plan" | "all_hands" | "unit_strategy" | "roadmap" | "qbr" | "other" | "decoy") | null;
-                documentType: ("board_deck" | "board_minutes" | "strategy_memo" | "planning_doc" | "okr_doc" | "roadmap" | "operating_review" | "all_hands_deck" | "offsite_notes" | "investor_update" | "pitch_deck" | "product_spec" | "research_analysis" | "general_meeting_notes" | "financial_plan" | "financial_actuals" | "equity_admin_record" | "corporate_formation_record" | "corporate_governance_record" | "government_filing" | "equity_agreement" | "commercial_agreement" | "employment_agreement" | "transaction_record" | "personal_document" | "social_event_material" | "coursework" | "empty_template" | "image_or_screenshot" | "unknown") | null;
+                documentType: ("board_deck" | "board_minutes" | "strategy_memo" | "planning_doc" | "okr_doc" | "roadmap" | "operating_review" | "all_hands_deck" | "offsite_notes" | "investor_update" | "pitch_deck" | "product_spec" | "research_analysis" | "general_meeting_notes" | "financial_plan" | "financial_actuals" | "equity_admin_record" | "corporate_formation_record" | "corporate_governance_record" | "government_filing" | "equity_agreement" | "commercial_agreement" | "employment_agreement" | "transaction_record" | "personal_document" | "social_event_material" | "coursework" | "empty_template" | "image_or_screenshot" | "team_charter" | "process_playbook" | "policy_handbook" | "onboarding_guide" | "values_culture" | "positioning_messaging" | "decision_log" | "postmortem" | "metrics_definition" | "operating_cadence" | "unknown") | null;
                 documentTypeConfidence: number | null;
+                operatingKnowledgeFamily: ("direction" | "operating_model" | "practices" | "identity_market" | "decisions_learning") | null;
+                canonicalPath: string | null;
                 periodLabel: string | null;
                 seriesRole: ("current" | "history") | null;
                 relevance: number;
@@ -9299,6 +9377,59 @@ export interface components {
                     t1: ("exploit" | "explore") | null;
                     t2: ("exploit" | "explore") | null;
                 };
+                attentionEvidence: ({
+                    /** @constant */
+                    kind: "tree_prior";
+                    score: number;
+                    folderId: string;
+                    source: {
+                        producer: string;
+                        version: string;
+                    };
+                } | {
+                    /** @constant */
+                    kind: "path_terms";
+                    values: string[];
+                    source: {
+                        producer: string;
+                        version: string;
+                    };
+                } | {
+                    /** @constant */
+                    kind: "content_match";
+                    values: string[];
+                    strength: number;
+                    probeId: string;
+                    source: {
+                        producer: string;
+                        version: string;
+                    };
+                } | {
+                    /** @constant */
+                    kind: "breadth";
+                    /** @enum {string} */
+                    value: "restricted_few" | "group" | "domain" | "anyone" | "unknown";
+                    source: {
+                        producer: string;
+                        version: string;
+                    };
+                } | {
+                    /** @constant */
+                    kind: "recency";
+                    score: number;
+                    source: {
+                        producer: string;
+                        version: string;
+                    };
+                } | {
+                    /** @constant */
+                    kind: "mime_prior";
+                    score: number;
+                    source: {
+                        producer: string;
+                        version: string;
+                    };
+                })[] | null;
                 included: boolean;
                 treatmentUnresolved: boolean;
                 matchReason: string;
@@ -9389,6 +9520,33 @@ export interface components {
                 coveragePercent: number;
                 /** @enum {string} */
                 scanOutcome: "complete" | "budget_exhausted" | "file_ceiling" | "stopped";
+                enumerationCompleteness: ("complete" | "local_budget_truncated" | "provider_incomplete" | "both") | null;
+                rootCoverage: {
+                    /** @enum {string} */
+                    rootKind: "user" | "shared_drive" | "domain";
+                    rootId: string | null;
+                    /** @enum {string} */
+                    status: "complete" | "local_budget_truncated" | "provider_incomplete" | "both";
+                    enumeratedCount: number;
+                    observedOldestModifiedTime: string | null;
+                    observedNewestModifiedTime: string | null;
+                    skippedRanges: {
+                        /** Format: date-time */
+                        from: string;
+                        /** Format: date-time */
+                        to: string;
+                    }[];
+                }[] | null;
+                stageCounters: {
+                    filesEnumerated: number;
+                    filesMetadataEligible: number;
+                    filesT0Scored: number;
+                    filesT1Attended: number;
+                    filesPeeked: number;
+                    filesClassified: number;
+                    filesShown: number;
+                    filesRetained: number;
+                } | null;
             } | null;
         };
         SourceSyncApproveResponse: {
@@ -13002,6 +13160,42 @@ export interface operations {
             };
         };
     };
+    deliverAnalysisWorkflowSettlement: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                id: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description What the delivery attempt did */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["DeliverWorkflowSettlementResponse"];
+                };
+            };
+            /** @description The workflow id is not a uuid */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description No such workflow in this workspace */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+        };
+    };
     getCompanyMdTree: {
         parameters: {
             query?: {
@@ -17743,6 +17937,133 @@ export interface operations {
             };
         };
     };
+    listQualityGraders: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Grader versions with confusion matrices by severity and failure kind */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description Not an internal admin, or missing internal.manage_quality */
+            403: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+        };
+    };
+    getQualityGraderLabelQueue: {
+        parameters: {
+            query?: {
+                limit?: number;
+            };
+            header?: never;
+            path: {
+                id: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Samples waiting for a label, newest run first, without verdicts */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description Validation error */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description Not an internal admin, or missing internal.manage_quality */
+            403: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description No such judge */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+        };
+    };
+    submitQualityGraderLabel: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                id: string;
+            };
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": {
+                    /** Format: uuid */
+                    runId: string;
+                    caseId: string;
+                    sample: number;
+                    humanPassed: boolean;
+                    humanFailureKind?: string | null;
+                };
+            };
+        };
+        responses: {
+            /** @description The label, the judge's verdict and the recomputed calibration */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description Validation error */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description Not an internal admin, missing internal.manage_quality, or no CSRF token */
+            403: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description No such judge, or the judge graded no such sample */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description The sample is already labeled, or the judge gave no valid verdict */
+            409: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+        };
+    };
     listCommentThreads: {
         parameters: {
             query: {

package/src/generated/openapi-routes.ts

@@ -10,6 +10,7 @@ export const openApiRoutes = {
   '/api/account/sessions': ['GET'],
   '/api/account/sessions/{sessionId}': ['DELETE'],
   '/api/analysis-workflows/{id}': ['GET'],
+  '/api/analysis-workflows/{id}/settlement': ['POST'],
   '/api/analysis-workflows/{id}/stop': ['POST'],
   '/api/auth/consent/grant': ['POST'],
   '/api/billing/price-list': ['GET'],
@@ -111,6 +112,9 @@ export const openApiRoutes = {
   '/api/internal-admin/quality/changes/manual': ['POST'],
   '/api/internal-admin/quality/escalations': ['GET'],
   '/api/internal-admin/quality/escalations/{id}/resolve': ['POST'],
+  '/api/internal-admin/quality/graders': ['GET'],
+  '/api/internal-admin/quality/graders/{id}/label-queue': ['GET'],
+  '/api/internal-admin/quality/graders/{id}/labels': ['POST'],
   '/api/internal-admin/quality/plans/{planId}/status': ['GET'],
   '/api/internal-admin/quality/references/floor': ['PUT'],
   '/api/internal-admin/quality/spend': ['GET'],

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