uidex 0.9.0 → 0.10.0

package/dist/scan/index.d.ts

@@ -15,8 +15,8 @@ interface EntityRef {
 /**
  * The four kinds every captured route is expected to render — the state-matrix
  * axis. A capture that only shoots the happy path leaves most of the value on
- * the table, so a missing core kind must be captured, waived (the page CANNOT
- * render it), or acknowledged in the MISSING_KINDS baseline.
+ * the table, so a missing core kind must be captured or ACKNOWLEDGED (see
+ * `Metadata.acknowledge`).
  */
 declare const CORE_STATE_KINDS: readonly ["loading", "empty", "populated", "error"];
 type CoreStateKind = (typeof CORE_STATE_KINDS)[number];
@@ -50,18 +50,24 @@ interface Metadata {
     /** Declared render states (see StateDecl); the capture-completeness gate. */
     states?: StateDecl[];
     /**
-     * `false` opts this page/feature/widget out of visual-states capture forever
-     * (a redirect, a static notice, an internal target). The page-coverage gate
-     * treats an opted-out route as accounted-for. Reason belongs in `description`.
+     * The ONE way to say "don't complain about this gap": scope → typed reason.
+     *
+     *   - scope `"*"` covers the whole entity (a redirect page that can never be
+     *     captured, a component whose states are not gated here);
+     *   - a core-kind scope covers that one cell of this page's route matrix.
+     *
+     * `type: "impossible"` is a permanent design statement and needs a `reason`;
+     * `type: "backlog"` is debt and does not. Keeping both as values of one field
+     * is what makes mislabeling debt as impossible a visible, reviewable edit.
+     * `captured-elsewhere` is computed by the workspace and never authored here.
      */
-    capture?: boolean;
-    /**
-     * Per-core-kind waivers: a core kind this page's route legitimately CANNOT
-     * render (a create form has no `empty`), mapped to a substantive reason. The
-     * state-matrix gate treats a waived kind as accounted-for. A waiver is a
-     * permanent design statement — unlike MISSING_KINDS backlog, which is debt.
-     */
-    waivers?: Partial<Record<CoreStateKind, string>>;
+    acknowledge?: Partial<Record<AcknowledgeScope, MetaAcknowledgment>>;
+}
+/** Scope of an acknowledgment: one core kind, or the whole entity. */
+type AcknowledgeScope = CoreStateKind | "*";
+interface MetaAcknowledgment {
+    type: "impossible" | "backlog";
+    reason?: string;
 }
 interface EntityWithMetaBase {
     id: string;
@@ -178,6 +184,15 @@ interface AuditConfig {
     pageCoverage?: boolean;
     /** State-matrix (core-kind) gate (default on when a manifest is present). */
     stateMatrix?: boolean;
+    /**
+     * Per-diagnostic-code severity overrides, e.g.
+     * `{ "missing-state-capture": "error" }`. A code's built-in severity is a
+     * default, not a policy — this is how a repo escalates an advisory gate into
+     * a build-failing ratchet, or silences one it has consciously accepted.
+     * `"off"` drops the diagnostic entirely. Unknown codes are rejected by
+     * config validation, so a typo can't silently disable a gate.
+     */
+    severity?: Record<string, DiagnosticSeverity | "off">;
 }
 interface UidexConfig {
     $schema?: string;
@@ -194,11 +209,21 @@ interface UidexConfig {
      */
     statesManifest?: string;
     /**
-     * Path (relative to the config dir) of the page-coverage baseline — the
-     * tool-managed, shrink-only backlog written by `uidex scan --update-baseline`.
-     * Defaults to `uidex-coverage-baseline.json`.
+     * Path (relative to the config dir) of the coverage baseline — the
+     * tool-managed, shrink-only `acknowledge` backlog written by
+     * `uidex scan --update-baseline`. Defaults to `uidex-coverage-baseline.json`.
      */
     coverageBaseline?: string;
+    /**
+     * The workspace this app belongs to — the level that answers "did a SIBLING
+     * app capture this shared declaration?" exactly, instead of guessing.
+     *
+     *   - omitted (default): auto-detect by walking up for a workspace marker
+     *     (`pnpm-workspace.yaml`, `turbo.json`, `.git`, …). Costs a few JSON reads.
+     *   - a path (relative to the config dir): use exactly this root.
+     *   - `false`: closed world — never look at siblings.
+     */
+    workspace?: string | false;
 }
 interface DiscoveredConfig {
     configPath: string;
@@ -253,16 +278,32 @@ interface MetadataExport {
      * one adjacent comma) keyed by field name. Used by `--fix` codemods.
      */
     fieldSpans?: Record<string, Span>;
+    /**
+     * Spans of top-level fields WITHOUT the comma extension (key start → value
+     * end), keyed by field name. `fieldSpans` deletes a property; this one
+     * replaces it in place, which is what the `acknowledge` codemod needs.
+     */
+    fieldPropSpans?: Record<string, Span>;
     /** Spans of the string-literal items in `features`, parallel to `features`. */
     featureSpans?: Span[];
     /** Spans of the string-literal items in `widgets`, parallel to `widgets`. */
     widgetSpans?: Span[];
     /** Declared render states (page/feature/widget); see ParsedState. */
     states?: ParsedState[];
-    /** `capture: false` opts the entity out of the page-coverage gate. */
-    capture?: boolean;
-    /** Per-core-kind waivers: kind → reason the route cannot render it. */
-    waivers?: Record<string, string>;
+    /** Scope (`"*"` | core kind) → typed acknowledgment. See `acknowledge.ts`. */
+    acknowledge?: Record<string, ParsedAcknowledgment>;
+    /**
+     * REMOVED fields, parsed only so the `acknowledge` codemod can rewrite them.
+     * No gate reads these — an unmigrated declaration is an error with a fix
+     * attached, never a silently different meaning.
+     */
+    legacyCapture?: boolean;
+    legacyWaivers?: Record<string, string>;
+}
+/** A parsed `acknowledge` entry from `export const uidex`. */
+interface ParsedAcknowledgment {
+    type: "impossible" | "backlog";
+    reason?: string;
 }
 /**
  * A parsed `states` entry from `export const uidex`. The authored form is a
@@ -405,6 +446,13 @@ declare const CONFIG_FILENAME = ".uidex.json";
 interface DiscoverOptions {
     cwd?: string;
     maxDepth?: number;
+    /**
+     * Keep descending past a config found at `cwd` itself, so the result is EVERY
+     * config in the tree rather than the innermost one. The workspace level needs
+     * the whole set; a plain `uidex scan` wants the nearest, which is why that
+     * stays the default.
+     */
+    all?: boolean;
 }
 declare function discover(options?: DiscoverOptions): DiscoveredConfig[];
 
@@ -474,6 +522,151 @@ interface ResolveOutput {
  */
 declare function resolve(ctx: ResolveContext): ResolveOutput;
 
+/**
+ * ACKNOWLEDGMENT — the single primitive for "don't complain about this".
+ *
+ * There used to be four mechanisms plus an implicit fifth (`waivers`, the
+ * baseline's `missingKinds` / `uncapturedPages`, `capture: false`, and a
+ * borrowed-entity inference). They overlapped, lived in unrelated files with
+ * unrelated shapes, and the rule keeping them straight — "don't fold capturable
+ * debt into a waiver" — was enforced socially, in prose, because nothing
+ * structural stopped you reaching for the wrong one.
+ *
+ * They are now one map from a SCOPE to a typed REASON:
+ *
+ *     acknowledge: {
+ *       empty: { type: "impossible", reason: "a create form has no empty state" },
+ *       "*":   { type: "backlog" },
+ *     }
+ *
+ * SCOPE is a core kind (that kind of this route) or `"*"` (the whole entity —
+ * every axis of it). TYPE is why:
+ *
+ *   - `impossible` — human-authored. The surface CANNOT render this; a
+ *     substantive `reason` is REQUIRED. Contradicted by an actual capture →
+ *     `stale-acknowledgment`.
+ *   - `backlog` — debt. It CAN render this and nobody has captured it yet.
+ *     `reason` is optional. Tool-managed in the coverage baseline
+ *     (`--update-baseline`, shrink-only), and authorable in source when you want
+ *     the debt to sit next to the declaration.
+ *   - `captured-elsewhere` — COMPUTED by the workspace level, never authored: a
+ *     sibling app that registers this same declaration captured it. Replaces the
+ *     borrowed-entity guess with an exact answer.
+ *
+ * The anti-laundering property is now structural rather than social:
+ * `impossible` and `backlog` are sibling values of ONE field, so choosing wrongly
+ * is a one-token, greppable, reviewable edit — not a choice between two
+ * unrelated files. And the reason rule points the lazy path at the honest
+ * answer: `impossible` costs you a sentence, `backlog` is free.
+ */
+/** The scope key meaning "the whole entity", not one core kind. */
+declare const ACK_ALL = "*";
+/** Every valid scope key: the four core kinds plus `"*"`. */
+declare const ACK_SCOPES: readonly string[];
+type AcknowledgeType = "impossible" | "backlog" | "captured-elsewhere";
+interface Acknowledgment {
+    type: AcknowledgeType;
+    /** Why. Required for `impossible`, optional for `backlog`. */
+    reason?: string;
+    /** `captured-elsewhere` only: the workspace app whose capture covers this. */
+    by?: string;
+}
+/** scope (`"*"` | core kind) → why it is acknowledged. */
+type AcknowledgeMap = Record<string, Acknowledgment>;
+/** Where an acknowledgment came from, so diagnostics can point at the right file. */
+type AcknowledgeOrigin = "source" | "baseline" | "workspace";
+interface ResolvedAcknowledgment extends Acknowledgment {
+    scope: string;
+    origin: AcknowledgeOrigin;
+}
+/**
+ * The committed, tool-managed coverage backlog. Same `Acknowledgment` shape as
+ * the source-authored field, keyed by route pattern — so the two really are the
+ * same primitive in two homes, not two lookalikes.
+ */
+interface CoverageBaseline {
+    version: 2;
+    /** route pattern → scope → acknowledgment (always `type: "backlog"`). */
+    acknowledge: Record<string, AcknowledgeMap>;
+}
+/** The pre-`acknowledge` baseline shape, recognized only to migrate it. */
+interface LegacyCoverageBaseline {
+    uncapturedPages?: string[];
+    missingKinds?: Record<string, string[]>;
+}
+/**
+ * The acknowledgments in force for one ROUTE: the baseline's entry for the route
+ * layered UNDER the page's own `acknowledge`. Source wins — a human statement
+ * outranks tool-recorded debt, and `--update-baseline` drops the shadowed entry
+ * on its next run.
+ */
+declare function routeAcknowledge(registry: Registry, baseline: CoverageBaseline | undefined, route: string, page: string | undefined): Map<string, ResolvedAcknowledgment>;
+/**
+ * The acknowledgments in force for one ENTITY (page/feature/widget). Only `"*"`
+ * is meaningful here — the core-kind axis is route-scoped. `capturedElsewhere`
+ * is the workspace's computed verdict; source still wins, so an explicit
+ * `impossible` is never silently reinterpreted.
+ */
+declare function entityAcknowledge(meta: Metadata | undefined, capturedElsewhereBy?: string): ResolvedAcknowledgment | undefined;
+/**
+ * Parse a v2 baseline. Malformed entries are dropped rather than thrown on: a
+ * hand-mangled baseline must not crash the scan, and every dropped entry simply
+ * re-appears as an unacknowledged gap the gate reports.
+ */
+declare function parseCoverageBaseline(raw: unknown): CoverageBaseline | null;
+/** Whether a parsed baseline JSON is the pre-`acknowledge` shape. */
+declare function isLegacyBaseline(raw: unknown): raw is LegacyCoverageBaseline;
+/** Convert the pre-`acknowledge` baseline shape to v2. Pure; no I/O. */
+declare function migrateBaseline(legacy: LegacyCoverageBaseline): CoverageBaseline;
+/** Serialize a baseline with stable key order, so its diff is reviewable. */
+declare function serializeCoverageBaseline(baseline: CoverageBaseline): string;
+
+interface WorkspaceApp {
+    /** Display name — the config dir's basename (e.g. "platform-web"). */
+    name: string;
+    configDir: string;
+    configPath: string;
+    /** Whether this app's configured sources would register `absFile`. */
+    registers: (absFile: string) => boolean;
+    /** `captureKey` values this app's manifest captured. */
+    captured: ReadonlySet<string>;
+}
+interface Workspace {
+    root: string;
+    /** Every OTHER app in the workspace; the scanning app is excluded. */
+    siblings: WorkspaceApp[];
+}
+interface ResolveWorkspaceOptions {
+    configDir: string;
+    config: UidexConfig;
+    /** Overrides discovery; used by tests to avoid touching the real filesystem. */
+    configs?: DiscoveredConfig[];
+}
+/**
+ * Walk up from the app looking for a workspace marker. Returns `undefined` when
+ * there is none — a standalone app then keeps today's closed-world behavior
+ * rather than silently treating its parent directory as a workspace.
+ */
+declare function findWorkspaceRoot(configDir: string): string | undefined;
+/**
+ * Resolve the workspace an app participates in.
+ *
+ * `config.workspace` selects the root: a path (relative to the config dir),
+ * `false` for an explicit closed world, or omitted for auto-detect via
+ * `findWorkspaceRoot`. Returns `undefined` when there is no workspace or no
+ * sibling in it — callers then behave exactly as a single-app scan does.
+ */
+declare function resolveWorkspace(opts: ResolveWorkspaceOptions): Workspace | undefined;
+/**
+ * The sibling app that already captured this declaration, if any — the exact
+ * answer that replaces the borrowed-entity guess. `absFile` is the declaring
+ * file's real path (a display path cannot be resolved back across a `prefix`).
+ *
+ * A capture recording no `kind` matches on id alone, mirroring how the
+ * state-coverage gate treats an unlabeled capture.
+ */
+declare function capturedElsewhere(workspace: Workspace | undefined, absFile: string | undefined, kind: string, id: string): string | undefined;
+
 /**
  * State-capture completeness — the deterministic replacement for a bespoke
  * `check-states.mjs`. Cross-checks the states DECLARED on registry entities
@@ -487,8 +680,17 @@ declare function resolve(ctx: ResolveContext): ResolveOutput;
  *   - `orphan-state-capture` — a run captured a state the entity never declared,
  *     so the contact sheet shows a state the registry doesn't know about.
  *
- * Pure: same (registry, manifest) → same diagnostics. Only runs when a manifest
- * is present, so a plain `uidex scan` (no capture run) never fails on it.
+ * Two things take an entity out of the gate, and both are acknowledgments:
+ * a SOURCE `acknowledge: { "*": … }`, or the WORKSPACE observing that a sibling
+ * app which registers this same declaration captured it (`captured-elsewhere`).
+ *
+ * The workspace answer replaces a heuristic this module used to carry: a
+ * "borrowed" entity (one declared under a shared source `prefix`) that this app
+ * captured nothing for was ASSUMED to be a sibling's responsibility. That guess
+ * could not tell a genuinely shared component from an id that merely collided
+ * with a sibling's, and it silenced real gaps whenever an app captured nothing.
+ * The workspace checks the sibling's actual source set and actual manifest, so
+ * the answer is exact and the guess is gone.
  */
 /** One `entity/state` a capture run recorded. */
 interface CapturedState {
@@ -507,49 +709,21 @@ interface CapturedState {
 }
 interface CapturedStatesManifest {
     captured: CapturedState[];
+    /** ISO timestamp the reporter stamped; drives the staleness check. */
+    generatedAt?: string;
 }
-declare function checkStateCoverage(registry: Registry, manifest: CapturedStatesManifest): Diagnostic[];
-
-/**
- * Page-capture coverage — the coarse gate above the per-state gate. Every
- * derived route must be accounted for: captured (a run drove it), opted out
- * (`export const uidex = { page, capture: false }`), or acknowledged backlog (a
- * tool-managed, shrink-only baseline). A route in none of those is a *new*
- * uncaptured page and fails hard — the ratchet that keeps debt from growing.
- *
- * uidex derives the route set (route groups stripped, dynamic segments kept), so
- * unlike a hand-rolled `src/app/**` walk there is no page list to enumerate or
- * keep from rotting: a route exists in the registry or it doesn't. And captures
- * observe the URL they ran against, so which route a capture covers is matched,
- * never hand-declared.
- */
-/** The committed, tool-managed backlog. Shrinks as pages/kinds get captured. */
-interface PageCoverageBaseline {
-    /** Route patterns acknowledged as uncaptured (e.g. "/[scope]/collections"). */
-    uncapturedPages: string[];
-    /** route → core kinds acknowledged as not-yet-captured (the matrix backlog). */
-    missingKinds?: Record<string, string[]>;
+interface StateCoverageOptions {
+    /** The workspace, when one is resolved; enables `captured-elsewhere`. */
+    workspace?: Workspace;
+    /**
+     * Maps an entity's `loc.file` (a DISPLAY path, which a `prefix` makes
+     * unresolvable on its own) back to its real path on disk. Supplied by
+     * `audit()` from the scanned-file list, so the workspace can test the file
+     * against a sibling's source roots.
+     */
+    resolveSourcePath?: (displayPath: string) => string | undefined;
 }
-/**
- * Turn a Next-style route pattern into an anchored matcher.
- *   `/[scope]/products/[productId]/edit` → matches `/acme/products/p1/edit`
- *   `/[...slug]` (catch-all) → matches one or more segments
- * Returns the literal-segment count as a specificity score, so the most literal
- * matching pattern wins when several match (e.g. `/x/new` beats `/x/[id]`).
- */
-declare function compileRoute(pattern: string): {
-    test: (url: string) => boolean;
-    specificity: number;
-};
-/** The route pattern (from the given set) that most-specifically matches a URL. */
-declare function matchUrlToRoute(url: string, routePaths: string[]): string | null;
-declare function checkPageCoverage(registry: Registry, manifest: CapturedStatesManifest, baseline?: PageCoverageBaseline): Diagnostic[];
-/**
- * Compute the shrink-only baseline for `--update-baseline`: every route with no
- * capture and no opt-out. Seeds on first run and prunes on later runs; growth
- * only ever happens through this explicit command, visible in the file's diff.
- */
-declare function computePageBaseline(registry: Registry, manifest: CapturedStatesManifest): PageCoverageBaseline;
+declare function checkStateCoverage(registry: Registry, manifest: CapturedStatesManifest, opts?: StateCoverageOptions): Diagnostic[];
 
 interface AuditOptions {
     registry: Registry;
@@ -581,8 +755,12 @@ interface AuditOptions {
     locsOutputPath?: string;
     /** Captured-states manifest for the completeness gate; absent → gate skipped. */
     capturedStates?: CapturedStatesManifest;
-    /** Page-coverage baseline (the shrink-only backlog); absent → empty baseline. */
-    pageBaseline?: PageCoverageBaseline;
+    /** Coverage baseline (the shrink-only `acknowledge` backlog). */
+    coverageBaseline?: CoverageBaseline;
+    /** Migration diagnostic when the baseline on disk is the removed shape. */
+    baselineDiagnostic?: Diagnostic;
+    /** The resolved workspace; enables `captured-elsewhere`. */
+    workspace?: Workspace;
 }
 declare function audit(opts: AuditOptions): AuditSummary;
 
@@ -688,11 +866,22 @@ interface RunScanOptions {
     configs?: DiscoveredConfig[];
     /** Captured-states manifest for the completeness gate; overrides on-disk load. */
     capturedStates?: CapturedStatesManifest;
-    /** Page-coverage baseline; overrides on-disk load. */
-    pageBaseline?: PageCoverageBaseline;
+    /** Coverage baseline (the shrink-only backlog); overrides on-disk load. */
+    coverageBaseline?: CoverageBaseline;
+    /** Workspace override; skips auto-detection (used by tests). */
+    workspace?: Workspace;
 }
-/** Load the page-coverage baseline from disk, if present + well-formed. */
-declare function loadPageBaseline(configDir: string, config: UidexConfig): PageCoverageBaseline | undefined;
+interface LoadedBaseline {
+    baseline?: CoverageBaseline;
+    /** Present when the file on disk is the pre-`acknowledge` shape. */
+    legacy?: Diagnostic;
+}
+/**
+ * Load the coverage baseline from disk. A file in the REMOVED shape does not
+ * silently read as "no baseline" — that would turn every acknowledged-backlog
+ * route into a hard error — it comes back as a migration diagnostic with a fix.
+ */
+declare function loadCoverageBaseline(configDir: string, config: UidexConfig): LoadedBaseline;
 /** One generated artifact: its bytes plus where it lands (abs + repo-relative). */
 interface ScanArtifact {
     generated: string;
@@ -724,33 +913,113 @@ declare function runScan(opts?: RunScanOptions): ScanResult[];
  * actually moved. Returns `true` if any file was written.
  */
 declare function writeScanResult(result: ScanResult): boolean;
-/** Absolute path of the page-coverage baseline for a scan result. */
-declare function pageBaselinePath(result: ScanResult): string;
+/** Absolute path of the coverage baseline for a scan result. */
+declare function coverageBaselinePath(result: ScanResult): string;
 
 /**
- * State-matrix coverage — the second completeness axis. A capture that only ever
- * shoots the happy path leaves most of the harness's value on the table, so
- * every *captured* route must render each of the four core kinds
- * (loading / empty / populated / error), or account for the gap:
+ * Page-capture coverage — the coarse gate above the per-state gate. Every
+ * derived route must be accounted for: captured (a run drove it), or
+ * ACKNOWLEDGED at `"*"` scope — either `impossible` (a redirect, a static
+ * notice, an internal target — the old `capture: false`, which now has to say
+ * WHY) or `backlog` (tool-managed, shrink-only). A route in none of those is a
+ * *new* uncaptured page and fails hard — the ratchet that keeps debt growing.
  *
- *   - a **waiver** (`export const uidex = { page, waivers: { empty: "…" } }`) —
- *     the route CANNOT render that kind (a create form has no empty state);
- *   - the **MISSING_KINDS baseline** — the route CAN render it and nobody has
- *     captured it yet (a per-(route, kind) shrink-only backlog).
+ * uidex derives the route set (route groups stripped, dynamic segments kept), so
+ * unlike a hand-rolled `src/app/**` walk there is no page list to enumerate or
+ * keep from rotting: a route exists in the registry or it doesn't. And captures
+ * observe the URL they ran against, so which route a capture covers is matched,
+ * never hand-declared.
+ */
+/**
+ * Turn a Next-style route pattern into an anchored matcher.
+ *   `/[scope]/products/[productId]/edit` → matches `/acme/products/p1/edit`
+ *   `/[...slug]` (catch-all) → matches one or more segments
+ * Returns the literal-segment count as a specificity score, so the most literal
+ * matching pattern wins when several match (e.g. `/x/new` beats `/x/[id]`).
+ */
+declare function compileRoute(pattern: string): {
+    test: (url: string) => boolean;
+    specificity: number;
+};
+/** The route pattern (from the given set) that most-specifically matches a URL. */
+declare function matchUrlToRoute(url: string, routePaths: string[]): string | null;
+declare function checkPageCoverage(registry: Registry, manifest: CapturedStatesManifest, baseline?: CoverageBaseline): Diagnostic[];
+/**
+ * The page half of the shrink-only baseline for `--update-baseline`: every route
+ * with no capture and no SOURCE acknowledgment. Seeds on first run and prunes on
+ * later runs; growth only ever happens through this explicit command, visible in
+ * the file's diff.
+ */
+declare function computePageBacklog(registry: Registry, manifest: CapturedStatesManifest): Record<string, AcknowledgeMap>;
+
+declare function checkStateMatrix(registry: Registry, manifest: CapturedStatesManifest, baseline?: CoverageBaseline): Diagnostic[];
+/**
+ * The matrix half of the shrink-only baseline for `--update-baseline`: every
+ * (captured route, core kind) that is neither captured nor already acknowledged
+ * in SOURCE. Source acknowledgments are excluded so the same gap is never
+ * recorded twice, in two files, saying two things.
+ */
+declare function computeMatrixBacklog(registry: Registry, manifest: CapturedStatesManifest): Record<string, AcknowledgeMap>;
+
+declare function checkComponentCoverage(registry: Registry, manifest: CapturedStatesManifest): Diagnostic[];
+
+/**
+ * Migration diagnostics for one file's `export const uidex` blocks. Emitted as
+ * errors: the fields are gone, so the declaration means nothing until rewritten.
+ */
+declare function migrateLegacyFields(ef: ExtractedFile): Diagnostic[];
+/**
+ * Migration diagnostic for a pre-`acknowledge` coverage baseline. The whole file
+ * is replaced, which is safe because the baseline is a generated artifact: the
+ * same content `--update-baseline` would produce, just without needing a capture
+ * run to regenerate it.
+ */
+declare function migrateLegacyBaseline(opts: {
+    path: string;
+    raw: string;
+    parsed: unknown;
+    displayPath: string;
+}): Diagnostic | undefined;
+
+/**
+ * Fold a PARTIAL capture manifest into the committed one.
  *
- * Anything else is a `core-kind` error. Only *captured* routes are in scope: a
- * route with no capture at all is a page-coverage concern, not a matrix hole.
+ * A filtered run (`--grep`) legitimately captures a subset, so the reporter's
+ * shrink guard diverts it to `<name>.partial.json` rather than overwriting a
+ * fuller manifest. Without a merge path the only ways forward are re-running the
+ * FULL suite or hand-editing JSON — both of which make scoped re-capture
+ * expensive enough that people skip it and let the manifest drift.
+ *
+ * Merge is by `(kind, entity, state)`: rows in the partial REPLACE their
+ * counterparts (that run is the newer evidence) and rows absent from it are
+ * preserved (it never claimed to cover them). So merging is purely additive to
+ * coverage — it can never drop a state, which is what makes it safe to run
+ * without re-reading the whole manifest.
  */
-/** route → core kinds acknowledged as not-yet-captured (the finer ratchet). */
-interface StateMatrixBaseline {
-    missingKinds: Record<string, string[]>;
+interface MergeResult {
+    manifest: CapturedStatesManifest;
+    /** `(kind, entity, state)` keys the partial replaced. */
+    updated: string[];
+    /** Keys the partial contributed that the committed manifest lacked. */
+    added: string[];
+}
+declare function mergeStates(committed: CapturedStatesManifest, partial: CapturedStatesManifest): MergeResult;
+
+declare class ConfigError extends Error {
+    constructor(message: string);
 }
-declare function checkStateMatrix(registry: Registry, manifest: CapturedStatesManifest, baseline?: StateMatrixBaseline): Diagnostic[];
 /**
- * Compute the shrink-only MISSING_KINDS baseline for `--update-baseline`: every
- * (captured route, core kind) that is neither captured nor waived.
+ * Every diagnostic code the scanner can emit — the allow-list `audit.severity`
+ * validates against, so a typo'd key fails loudly instead of silently leaving
+ * the gate it was meant to govern at its default severity.
+ *
+ * Keep in sync when adding a diagnostic; `severity-codes.test.ts` asserts this
+ * set matches the codes actually emitted by the source.
  */
-declare function computeMissingKinds(registry: Registry, manifest: CapturedStatesManifest): Record<string, string[]>;
+declare const DIAGNOSTIC_CODES: readonly ["acceptance-uncovered", "acknowledged-elsewhere", "competing-uidex-export", "component-state-uncaptured", "core-kind", "duplicate-id", "dynamic-attr", "dynamic-flow-reference", "gen-missing", "gen-stale", "legacy-acknowledge-field", "legacy-coverage-baseline", "matrix-backlog", "missing-element-annotation", "missing-state-capture", "orphan-state-capture", "page-backlog", "page-captured", "page-no-capture", "parse-error", "placeholder-reason", "prefer-well-known-file", "rename", "scope-leak", "spread-attr", "stale-acknowledgment", "stale-page-baseline", "uidex-export-ambiguous-kind", "uidex-export-duplicate-field", "uidex-export-duplicate-state", "uidex-export-empty-name", "uidex-export-invalid-field", "uidex-export-invalid-literal", "uidex-export-missing-kind", "uidex-export-satisfies-mismatch", "uidex-export-unknown-field", "unknown-reference", "widget-id-mismatch", "widget-missing-acceptance", "widget-missing-dom"];
+declare function validateConfig(raw: unknown): UidexConfig;
+declare function parseConfig(json: string): UidexConfig;
+declare const DEFAULT_CONVENTIONS: Required<Pick<NonNullable<UidexConfig["conventions"]>, "primitives" | "features" | "pages" | "flows" | "regions">>;
 
 /**
  * Applies the machine-generated fixes attached to diagnostics.
@@ -816,13 +1085,6 @@ interface CliOptions {
 }
 declare function run(opts: CliOptions): Promise<CliResult>;
 
-declare class ConfigError extends Error {
-    constructor(message: string);
-}
-declare function validateConfig(raw: unknown): UidexConfig;
-declare function parseConfig(json: string): UidexConfig;
-declare const DEFAULT_CONVENTIONS: Required<Pick<NonNullable<UidexConfig["conventions"]>, "primitives" | "features" | "pages" | "flows" | "regions">>;
-
 /**
  * Authoring-surface shape types for `export const uidex = { ... }` declarations.
  *
@@ -849,8 +1111,24 @@ declare namespace Uidex {
         acceptance?: readonly string[];
         description?: string;
     }
-    /** Per-core-kind waivers: a kind this route cannot render → reason. */
-    type Waivers = Partial<Record<CoreStateKind, string>>;
+    /** Scope of an acknowledgment: one core kind, or the whole entity. */
+    type AcknowledgeScope = CoreStateKind | "*";
+    /** A permanent design statement — so it has to say why. */
+    interface Impossible {
+        type: "impossible";
+        reason: string;
+    }
+    /** Debt: capturable, not captured yet. No reason required. */
+    interface Backlog {
+        type: "backlog";
+        reason?: string;
+    }
+    type Acknowledgment = Impossible | Backlog;
+    type Acknowledge = Partial<Record<AcknowledgeScope, Acknowledgment>>;
+    /** A component has no route, so only the `"*"` scope applies to one. */
+    type ComponentAcknowledge = {
+        "*"?: Acknowledgment;
+    };
     interface Page<PageIds extends string = string, FeatureIds extends string = string, WidgetIds extends string = string> {
         page: PageIds | false;
         name?: string;
@@ -858,8 +1136,7 @@ declare namespace Uidex {
         widgets?: readonly WidgetIds[];
         acceptance?: readonly string[];
         states?: readonly (string | State)[];
-        capture?: boolean;
-        waivers?: Waivers;
+        acknowledge?: Acknowledge;
         description?: string;
     }
     interface Feature<FeatureIds extends string = string> {
@@ -868,6 +1145,7 @@ declare namespace Uidex {
         features?: readonly FeatureIds[];
         acceptance?: readonly string[];
         states?: readonly (string | State)[];
+        acknowledge?: ComponentAcknowledge;
         description?: string;
     }
     interface Primitive<PrimitiveIds extends string = string> {
@@ -880,6 +1158,7 @@ declare namespace Uidex {
         name?: string;
         acceptance?: readonly string[];
         states?: readonly (string | State)[];
+        acknowledge?: ComponentAcknowledge;
         description?: string;
     }
     interface Flow<FlowIds extends string = string> {
@@ -892,4 +1171,4 @@ declare namespace Uidex {
     }
 }
 
-export { type Annotation, type AnnotationKind, type AppliedFix, type ApplyFixesResult, type AuditConfig, type AuditSummary, CONFIG_FILENAME, type CapturedState, type CapturedStatesManifest, type CliOptions, type CliResult, ConfigError, type ConventionsConfig, DEFAULT_CONVENTIONS, type DetectedRoute, type Diagnostic, type DiagnosticFix, type DiagnosticSeverity, type DiscoveredConfig, type ExtractedFile, type FixEdit, type GitContext, type ImportFact, type LandmarkFact, type MetadataExport, type MetadataExportKind, type PageCoverageBaseline, type ParsedState, type RenameKind, type RenameOptions, type RenameResult, type RunScanOptions, type ScaffoldKind, type ScaffoldOptions, type ScaffoldResult, type ScaffoldSpecOptions, type ScanResult, type ScannedFile, type SourceConfig, type Span, type StateMatrixBaseline, Uidex, type UidexConfig, applyFixes, audit, checkPageCoverage, checkStateCoverage, checkStateMatrix, compileRoute, computeMissingKinds, computePageBaseline, detectRoutes, discover, emit, extract, extractUidexExports, globToRegExp, loadPageBaseline, matchUrlToRoute, pageBaselinePath, parseConfig, pathToId, renameEntity, resolve, resolveGitContext, run as runCli, runScan, scaffoldSpec, scaffoldWidgetSpec, validateConfig, walk, writeScanResult };
+export { ACK_ALL, ACK_SCOPES, type AcknowledgeMap, type AcknowledgeOrigin, type AcknowledgeType, type Acknowledgment, type Annotation, type AnnotationKind, type AppliedFix, type ApplyFixesResult, type AuditConfig, type AuditSummary, CONFIG_FILENAME, type CapturedState, type CapturedStatesManifest, type CliOptions, type CliResult, ConfigError, type ConventionsConfig, type CoverageBaseline, DEFAULT_CONVENTIONS, DIAGNOSTIC_CODES, type DetectedRoute, type Diagnostic, type DiagnosticFix, type DiagnosticSeverity, type DiscoveredConfig, type ExtractedFile, type FixEdit, type GitContext, type ImportFact, type LandmarkFact, type MergeResult, type MetadataExport, type MetadataExportKind, type ParsedAcknowledgment, type ParsedState, type RenameKind, type RenameOptions, type RenameResult, type ResolvedAcknowledgment, type RunScanOptions, type ScaffoldKind, type ScaffoldOptions, type ScaffoldResult, type ScaffoldSpecOptions, type ScanResult, type ScannedFile, type SourceConfig, type Span, type StateCoverageOptions, Uidex, type UidexConfig, type Workspace, type WorkspaceApp, applyFixes, audit, capturedElsewhere, checkComponentCoverage, checkPageCoverage, checkStateCoverage, checkStateMatrix, compileRoute, computeMatrixBacklog, computePageBacklog, coverageBaselinePath, detectRoutes, discover, emit, entityAcknowledge, extract, extractUidexExports, findWorkspaceRoot, globToRegExp, isLegacyBaseline, loadCoverageBaseline, matchUrlToRoute, mergeStates, migrateBaseline, migrateLegacyBaseline, migrateLegacyFields, parseConfig, parseCoverageBaseline, pathToId, renameEntity, resolve, resolveGitContext, resolveWorkspace, routeAcknowledge, run as runCli, runScan, scaffoldSpec, scaffoldWidgetSpec, serializeCoverageBaseline, validateConfig, walk, writeScanResult };