@company-semantics/contracts 89.2.0 → 90.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@company-semantics/contracts",
-  "version": "89.2.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",
@@ -183,7 +184,7 @@
     }
   },
   "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'))\""
   },

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 = '7144c9a832d5' as const;
-export const SPEC_HASH_FULL = '7144c9a832d55cf9179e5825c6c8fa486bf7130c0d1022d1b721f175dcf99f6d' as const;
+export const SPEC_HASH = 'ba43b4881a93' as const;
+export const SPEC_HASH_FULL = 'ba43b4881a9318819726dfe0c0465ecae3802951f7f558fec6786a7171195a91' as const;

package/src/api/generated.ts

@@ -9328,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;
@@ -9375,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;
@@ -9465,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: {

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

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