@ai-matrx/content-ir-react 0.7.1 → 0.8.0

package/CHANGELOG.md

@@ -1,5 +1,66 @@
 # Changelog
 
+## 0.8.0 — 2026-08-30
+
+The CONTENT-IR-REACT row of the C23 all-inclusive retrofit register: the
+DB-component compile cache moves IN, the default error boundary ships, and the
+five areas become subpath entries.
+
+- **`/db-component` — the DB-component compile cache is package policy.**
+  matrx-frontend's 316-line `dbKindComponentCache.ts` (session compile cache
+  keyed per winning row VERSION, the scream-once console latch, loud-but-never-
+  fatal `props_transform` recovery, config narrowing, allowed-imports
+  resolution, key-family invalidation) was pure C22 violation living in one
+  host. `createDbKindComponentCache(ports)` now owns all of it; the host
+  injects only what is host-shaped: the sandbox COMPILER (security-shaped —
+  the package never bundles Babel), the default allowlist, the error reporter,
+  the durable incident sink, and the invalidation TRIGGER via the
+  `registerInvalidation` port (the host wires its invalidation-registry keys;
+  the cache owns what invalidation means). Also ships the kind prop contract
+  (`DbKindComponentRenderProps`, `KindComponentUiOptions`, `ResolveKindValue`,
+  `RunDbKindAction`) and `isDbKindComponentBodyPending`.
+- **`DbKindComponentErrorBoundary` — the default error boundary the register
+  named.** Catch → fallback (never a blank hole) → scream through the
+  `onCaught` seam (host binds structured capture + incident filing; the
+  default is an honest console scream). `resetSignal` (the row's `updated_at`)
+  un-latches the boundary when a NEW component version arrives, so a fixed
+  component renders without a full unmount.
+- **Subpath entries for the five areas:** `/host`, `/resolver`, `/route`,
+  `/react`, `/db-component` — dual ESM/CJS with matching declarations, per the
+  fleet banner rule: `/host`, `/react`, `/db-component` are stamped
+  `"use client"`; `/resolver` and `/route` are pure and deliberately
+  unstamped; the root `.` keeps the full surface, unstamped (it mixes pure
+  route logic that server modules import with client components — parity with
+  every existing consumer). tsup moved to the two-config kit shape
+  (`treeshake: false` so the banner survives to dist).
+- **`createKindRouteBinding(env, options)`** — the per-host partial
+  application every host was hand-writing as wrapper modules
+  (`applyIrKindRoute` / `kindServerDataFromStoredValue` /
+  `isPartialReadyKind` / `resolveProvisionalKindRender` with env + ownedTypes
+  threaded). Host route wrappers collapse to injection + re-export.
+- **Session latches moved to `globalThis` slots**
+  (`Symbol.for("ai-matrx.content-ir-react.partial-unsafe-kinds")`, same for
+  the sourceless-db-row report latch): with `splitting: false` dual-format
+  subpath builds, a module-level Set would silently split the
+  `markKindPartialUnsafe` writer (in `/react`'s graph) from the
+  `isPartialReadyKind` reader (in `/route`'s) — the kit confirm-opener
+  precedent. The tarball canary now proves the slot across loader graphs and
+  the `"use client"` stamp per chunk.
+- 20 new tests (cache policy, boundary latch/un-latch, route binding).
+
+### Consumer action
+
+- Hosts that carry their own DB-component compile cache (matrx-frontend:
+  `features/content-ir/react/db-component/dbKindComponentCache.ts`) must
+  collapse it to `createDbKindComponentCache` port wiring and delete the
+  mechanics; a host error boundary around compiled DB components becomes a
+  binding of `DbKindComponentErrorBoundary` with `onCaught`.
+- Host route wrapper modules should re-export from `createKindRouteBinding`
+  instead of hand-forwarding env/ownedTypes (signatures unchanged for their
+  own call sites).
+- No import-path changes are REQUIRED — the root export keeps the full
+  surface. New code (and any RSC-adjacent graph) should prefer the subpaths.
+
 ## 0.7.1 — 2026-08-30
 
 - `@ai-matrx/content-ir` is now a REAL dependency (`^0.9.0`) instead of a peer

package/dist/component-resolution.types-BS1ySIg-.d.cts

@@ -0,0 +1,104 @@
+/**
+ * THE SCREAM SEAM.
+ *
+ * Every recovery path in this package is loud: a defective component row, a
+ * failed resolver load, a kind whose component throws on a provisional value.
+ * The package refuses to own where those screams land — matrx-frontend routes
+ * them to the Error Inspector, the dashboard to its own log, the extension to
+ * its background page. Each host binds one function.
+ *
+ * A host that binds a no-op has chosen silence, which is a defect in itself;
+ * {@link consoleErrorReporter} is the honest default.
+ */
+interface ContentIrErrorReport {
+    /** Always `"content-ir"` — hosts key their capture stores on it. */
+    source: "content-ir";
+    message: string;
+    name?: string;
+    stack?: string;
+    /** Free-form grouping key (the host's `relation`), e.g. `"partial-kind"`. */
+    relation?: string;
+    raw?: unknown;
+}
+type ContentIrErrorReporter = (report: ContentIrErrorReport) => void;
+/** The default when a host binds nothing: never silent. */
+declare const consoleErrorReporter: ContentIrErrorReporter;
+
+/**
+ * The (kind, platform, role) → component vocabulary — the Shape System's
+ * resolver contract (rulings R1 + R6), stated once for every UI.
+ *
+ * Cross-repo system-of-record:
+ * `common-docs/systems/content-ir-twin/FEATURE.md` (package boundary) and
+ * `matrx-frontend/features/content-ir/docs/SHAPE_SYSTEM.md` (the semantics).
+ *
+ * Nothing here knows where a row comes from. A host supplies rows from
+ * `content_ir.kind_component` (Supabase, a REST call, a fixture); the resolver
+ * only knows the shape.
+ */
+/** JSON object, restated locally so this package depends on no host type. */
+type JsonObject = Record<string, unknown>;
+/**
+ * Which face of the shape a component draws.
+ *
+ * - `output` — the shape's finished value, the component a reader sees.
+ * - `input`  — the authoring form for a value of this shape.
+ * - `loading` — the shape's LOADING face: what renders from the instant the
+ *   kind is identified until its output component has a renderable frame.
+ *   Authored per kind like any other component and fed the region's partial
+ *   value each frame, so it can PERFORM the arrival (surface real text as it
+ *   lands) instead of drawing a shapeless skeleton. Optional: a kind with no
+ *   `loading` component falls back to the host's loading library.
+ */
+type ComponentRole = "output" | "input" | "loading";
+/** The resolver's answer for one (kind, platform, role). */
+interface ComponentResolution {
+    /** The component key the renderer routes on (e.g. "flashcards"). */
+    componentKey: string;
+    source: string;
+    config: JsonObject;
+    /**
+     * Render-trust verdict (R6). Compiled entries are always active (trusted at
+     * bootstrap); DB rows carry their own `is_active`.
+     */
+    isActive: boolean;
+    /** Which tier produced this answer — the verification hook's `by`. */
+    resolvedBy: "compiled" | "db";
+    componentSource: string | null;
+    propsTransform: string | null;
+    /**
+     * TRUE when the row owns a real component body — even if `componentSource`
+     * is null because the host's warm list is body-less and the cold fetch has
+     * not landed it yet. THE routing gate: `routeToDbComponent` re-types on
+     * this flag, never on body presence, so a body-less row still routes and
+     * the renderer fetches/compiles the body lazily.
+     */
+    hasComponentSource: boolean;
+    pinnedKindVersion: number | null;
+    /** The db row's `updated_at` — the compile-cache staleness key. */
+    updatedAt: string | null;
+    createdBy: string | null;
+}
+/**
+ * The read side of a component resolver, as the render layer consumes it.
+ * The package ships {@link ComponentResolver}; a host with its own resolver
+ * only has to satisfy this.
+ */
+interface ComponentResolutionSource {
+    /** Synchronous — the render seam's per-block call. */
+    resolve(kind: string, platform: string, role: ComponentRole): ComponentResolution | null;
+    /** Eager targeted fetch for one kind; fire-and-forget, never awaited on the hot path. */
+    requestComponent(kind: string, platform: string, role: ComponentRole): void;
+    /** One list fetch per session. */
+    ensureWarm(): Promise<void>;
+    /** Refresh-on-view; rate-limited and deduped by the implementation. */
+    refresh(maxAgeMs?: number): Promise<void>;
+    /** Monotonic tier version — has anything at all changed? */
+    getVersion(): number;
+    /** Monotonic per-kind version (+ wholesale epoch) — the granular repaint key. */
+    getKindVersion(kind: string): number;
+    subscribe(listener: () => void): () => void;
+    subscribeKind(kind: string, listener: () => void): () => void;
+}
+
+export { type ComponentResolution as C, type ContentIrErrorReporter as a, type ContentIrErrorReport as b, consoleErrorReporter as c, type ComponentResolutionSource as d };

package/dist/component-resolution.types-BS1ySIg-.d.ts

@@ -0,0 +1,104 @@
+/**
+ * THE SCREAM SEAM.
+ *
+ * Every recovery path in this package is loud: a defective component row, a
+ * failed resolver load, a kind whose component throws on a provisional value.
+ * The package refuses to own where those screams land — matrx-frontend routes
+ * them to the Error Inspector, the dashboard to its own log, the extension to
+ * its background page. Each host binds one function.
+ *
+ * A host that binds a no-op has chosen silence, which is a defect in itself;
+ * {@link consoleErrorReporter} is the honest default.
+ */
+interface ContentIrErrorReport {
+    /** Always `"content-ir"` — hosts key their capture stores on it. */
+    source: "content-ir";
+    message: string;
+    name?: string;
+    stack?: string;
+    /** Free-form grouping key (the host's `relation`), e.g. `"partial-kind"`. */
+    relation?: string;
+    raw?: unknown;
+}
+type ContentIrErrorReporter = (report: ContentIrErrorReport) => void;
+/** The default when a host binds nothing: never silent. */
+declare const consoleErrorReporter: ContentIrErrorReporter;
+
+/**
+ * The (kind, platform, role) → component vocabulary — the Shape System's
+ * resolver contract (rulings R1 + R6), stated once for every UI.
+ *
+ * Cross-repo system-of-record:
+ * `common-docs/systems/content-ir-twin/FEATURE.md` (package boundary) and
+ * `matrx-frontend/features/content-ir/docs/SHAPE_SYSTEM.md` (the semantics).
+ *
+ * Nothing here knows where a row comes from. A host supplies rows from
+ * `content_ir.kind_component` (Supabase, a REST call, a fixture); the resolver
+ * only knows the shape.
+ */
+/** JSON object, restated locally so this package depends on no host type. */
+type JsonObject = Record<string, unknown>;
+/**
+ * Which face of the shape a component draws.
+ *
+ * - `output` — the shape's finished value, the component a reader sees.
+ * - `input`  — the authoring form for a value of this shape.
+ * - `loading` — the shape's LOADING face: what renders from the instant the
+ *   kind is identified until its output component has a renderable frame.
+ *   Authored per kind like any other component and fed the region's partial
+ *   value each frame, so it can PERFORM the arrival (surface real text as it
+ *   lands) instead of drawing a shapeless skeleton. Optional: a kind with no
+ *   `loading` component falls back to the host's loading library.
+ */
+type ComponentRole = "output" | "input" | "loading";
+/** The resolver's answer for one (kind, platform, role). */
+interface ComponentResolution {
+    /** The component key the renderer routes on (e.g. "flashcards"). */
+    componentKey: string;
+    source: string;
+    config: JsonObject;
+    /**
+     * Render-trust verdict (R6). Compiled entries are always active (trusted at
+     * bootstrap); DB rows carry their own `is_active`.
+     */
+    isActive: boolean;
+    /** Which tier produced this answer — the verification hook's `by`. */
+    resolvedBy: "compiled" | "db";
+    componentSource: string | null;
+    propsTransform: string | null;
+    /**
+     * TRUE when the row owns a real component body — even if `componentSource`
+     * is null because the host's warm list is body-less and the cold fetch has
+     * not landed it yet. THE routing gate: `routeToDbComponent` re-types on
+     * this flag, never on body presence, so a body-less row still routes and
+     * the renderer fetches/compiles the body lazily.
+     */
+    hasComponentSource: boolean;
+    pinnedKindVersion: number | null;
+    /** The db row's `updated_at` — the compile-cache staleness key. */
+    updatedAt: string | null;
+    createdBy: string | null;
+}
+/**
+ * The read side of a component resolver, as the render layer consumes it.
+ * The package ships {@link ComponentResolver}; a host with its own resolver
+ * only has to satisfy this.
+ */
+interface ComponentResolutionSource {
+    /** Synchronous — the render seam's per-block call. */
+    resolve(kind: string, platform: string, role: ComponentRole): ComponentResolution | null;
+    /** Eager targeted fetch for one kind; fire-and-forget, never awaited on the hot path. */
+    requestComponent(kind: string, platform: string, role: ComponentRole): void;
+    /** One list fetch per session. */
+    ensureWarm(): Promise<void>;
+    /** Refresh-on-view; rate-limited and deduped by the implementation. */
+    refresh(maxAgeMs?: number): Promise<void>;
+    /** Monotonic tier version — has anything at all changed? */
+    getVersion(): number;
+    /** Monotonic per-kind version (+ wholesale epoch) — the granular repaint key. */
+    getKindVersion(kind: string): number;
+    subscribe(listener: () => void): () => void;
+    subscribeKind(kind: string, listener: () => void): () => void;
+}
+
+export { type ComponentResolution as C, type ContentIrErrorReporter as a, type ContentIrErrorReport as b, consoleErrorReporter as c, type ComponentResolutionSource as d };

package/dist/component-resolution.types-fvR92hW7.d.cts

@@ -0,0 +1,142 @@
+/**
+ * THE SCREAM SEAM.
+ *
+ * Every recovery path in this package is loud: a defective component row, a
+ * failed resolver load, a kind whose component throws on a provisional value.
+ * The package refuses to own where those screams land — matrx-frontend routes
+ * them to the Error Inspector, the dashboard to its own log, the extension to
+ * its background page. Each host binds one function.
+ *
+ * A host that binds a no-op has chosen silence, which is a defect in itself;
+ * {@link consoleErrorReporter} is the honest default.
+ */
+interface ContentIrErrorReport {
+    /** Always `"content-ir"` — hosts key their capture stores on it. */
+    source: "content-ir";
+    message: string;
+    name?: string;
+    stack?: string;
+    /** Free-form grouping key (the host's `relation`), e.g. `"partial-kind"`. */
+    relation?: string;
+    raw?: unknown;
+}
+type ContentIrErrorReporter = (report: ContentIrErrorReport) => void;
+/** The default when a host binds nothing: never silent. */
+declare const consoleErrorReporter: ContentIrErrorReporter;
+
+/**
+ * The (kind, platform, role) → component vocabulary — the Shape System's
+ * resolver contract (rulings R1 + R6), stated once for every UI.
+ *
+ * Cross-repo system-of-record:
+ * `common-docs/systems/content-ir-twin/FEATURE.md` (package boundary) and
+ * `matrx-frontend/features/content-ir/docs/SHAPE_SYSTEM.md` (the semantics).
+ *
+ * Nothing here knows where a row comes from. A host supplies rows from
+ * `content_ir.kind_component` (Supabase, a REST call, a fixture); the resolver
+ * only knows the shape.
+ */
+/** JSON object, restated locally so this package depends on no host type. */
+type JsonObject = Record<string, unknown>;
+/**
+ * Which face of the shape a component draws.
+ *
+ * - `output` — the shape's finished value, the component a reader sees.
+ * - `input`  — the authoring form for a value of this shape.
+ * - `loading` — the shape's LOADING face: what renders from the instant the
+ *   kind is identified until its output component has a renderable frame.
+ *   Authored per kind like any other component and fed the region's partial
+ *   value each frame, so it can PERFORM the arrival (surface real text as it
+ *   lands) instead of drawing a shapeless skeleton. Optional: a kind with no
+ *   `loading` component falls back to the host's loading library.
+ */
+type ComponentRole = "output" | "input" | "loading";
+/**
+ * One `content_ir.kind_component` row, projected to exactly what rendering
+ * needs. Hosts map their own query result onto this.
+ */
+interface KindComponentRow {
+    kind: string;
+    platform: string;
+    role: ComponentRole;
+    componentKey: string;
+    /** `source` column vocabulary: "bundled" | "db" (db = web sandbox only). */
+    source: string;
+    config: JsonObject;
+    isActive: boolean;
+    componentSource: string | null;
+    propsTransform: string | null;
+    /**
+     * Whether the row carries a real `component_source` body — supplied by the
+     * host when its warm list is BODY-LESS (the lazy design: metadata travels
+     * on the list, the body arrives per kind via the cold fetch). Omitted →
+     * derived from `componentSource` itself, so eager hosts change nothing.
+     */
+    hasComponentSource?: boolean;
+    pinnedKindVersion: number | null;
+    updatedAt: string | null;
+    createdBy: string | null;
+}
+/**
+ * One COMPILED bootstrap entry — the trusted-at-boot floor a host ships in its
+ * bundle, available synchronously from the first streamed byte.
+ */
+interface SystemComponentEntry {
+    kind: string;
+    platform: string;
+    role: ComponentRole;
+    componentKey: string;
+    source: string;
+    config: JsonObject;
+}
+/** The resolver's answer for one (kind, platform, role). */
+interface ComponentResolution {
+    /** The component key the renderer routes on (e.g. "flashcards"). */
+    componentKey: string;
+    source: string;
+    config: JsonObject;
+    /**
+     * Render-trust verdict (R6). Compiled entries are always active (trusted at
+     * bootstrap); DB rows carry their own `is_active`.
+     */
+    isActive: boolean;
+    /** Which tier produced this answer — the verification hook's `by`. */
+    resolvedBy: "compiled" | "db";
+    componentSource: string | null;
+    propsTransform: string | null;
+    /**
+     * TRUE when the row owns a real component body — even if `componentSource`
+     * is null because the host's warm list is body-less and the cold fetch has
+     * not landed it yet. THE routing gate: `routeToDbComponent` re-types on
+     * this flag, never on body presence, so a body-less row still routes and
+     * the renderer fetches/compiles the body lazily.
+     */
+    hasComponentSource: boolean;
+    pinnedKindVersion: number | null;
+    /** The db row's `updated_at` — the compile-cache staleness key. */
+    updatedAt: string | null;
+    createdBy: string | null;
+}
+/**
+ * The read side of a component resolver, as the render layer consumes it.
+ * The package ships {@link ComponentResolver}; a host with its own resolver
+ * only has to satisfy this.
+ */
+interface ComponentResolutionSource {
+    /** Synchronous — the render seam's per-block call. */
+    resolve(kind: string, platform: string, role: ComponentRole): ComponentResolution | null;
+    /** Eager targeted fetch for one kind; fire-and-forget, never awaited on the hot path. */
+    requestComponent(kind: string, platform: string, role: ComponentRole): void;
+    /** One list fetch per session. */
+    ensureWarm(): Promise<void>;
+    /** Refresh-on-view; rate-limited and deduped by the implementation. */
+    refresh(maxAgeMs?: number): Promise<void>;
+    /** Monotonic tier version — has anything at all changed? */
+    getVersion(): number;
+    /** Monotonic per-kind version (+ wholesale epoch) — the granular repaint key. */
+    getKindVersion(kind: string): number;
+    subscribe(listener: () => void): () => void;
+    subscribeKind(kind: string, listener: () => void): () => void;
+}
+
+export { type ComponentResolutionSource as C, type JsonObject as J, type KindComponentRow as K, type SystemComponentEntry as S, type ComponentResolution as a, type ContentIrErrorReporter as b, type ComponentRole as c, type ContentIrErrorReport as d, consoleErrorReporter as e };

package/dist/component-resolution.types-fvR92hW7.d.ts

@@ -0,0 +1,142 @@
+/**
+ * THE SCREAM SEAM.
+ *
+ * Every recovery path in this package is loud: a defective component row, a
+ * failed resolver load, a kind whose component throws on a provisional value.
+ * The package refuses to own where those screams land — matrx-frontend routes
+ * them to the Error Inspector, the dashboard to its own log, the extension to
+ * its background page. Each host binds one function.
+ *
+ * A host that binds a no-op has chosen silence, which is a defect in itself;
+ * {@link consoleErrorReporter} is the honest default.
+ */
+interface ContentIrErrorReport {
+    /** Always `"content-ir"` — hosts key their capture stores on it. */
+    source: "content-ir";
+    message: string;
+    name?: string;
+    stack?: string;
+    /** Free-form grouping key (the host's `relation`), e.g. `"partial-kind"`. */
+    relation?: string;
+    raw?: unknown;
+}
+type ContentIrErrorReporter = (report: ContentIrErrorReport) => void;
+/** The default when a host binds nothing: never silent. */
+declare const consoleErrorReporter: ContentIrErrorReporter;
+
+/**
+ * The (kind, platform, role) → component vocabulary — the Shape System's
+ * resolver contract (rulings R1 + R6), stated once for every UI.
+ *
+ * Cross-repo system-of-record:
+ * `common-docs/systems/content-ir-twin/FEATURE.md` (package boundary) and
+ * `matrx-frontend/features/content-ir/docs/SHAPE_SYSTEM.md` (the semantics).
+ *
+ * Nothing here knows where a row comes from. A host supplies rows from
+ * `content_ir.kind_component` (Supabase, a REST call, a fixture); the resolver
+ * only knows the shape.
+ */
+/** JSON object, restated locally so this package depends on no host type. */
+type JsonObject = Record<string, unknown>;
+/**
+ * Which face of the shape a component draws.
+ *
+ * - `output` — the shape's finished value, the component a reader sees.
+ * - `input`  — the authoring form for a value of this shape.
+ * - `loading` — the shape's LOADING face: what renders from the instant the
+ *   kind is identified until its output component has a renderable frame.
+ *   Authored per kind like any other component and fed the region's partial
+ *   value each frame, so it can PERFORM the arrival (surface real text as it
+ *   lands) instead of drawing a shapeless skeleton. Optional: a kind with no
+ *   `loading` component falls back to the host's loading library.
+ */
+type ComponentRole = "output" | "input" | "loading";
+/**
+ * One `content_ir.kind_component` row, projected to exactly what rendering
+ * needs. Hosts map their own query result onto this.
+ */
+interface KindComponentRow {
+    kind: string;
+    platform: string;
+    role: ComponentRole;
+    componentKey: string;
+    /** `source` column vocabulary: "bundled" | "db" (db = web sandbox only). */
+    source: string;
+    config: JsonObject;
+    isActive: boolean;
+    componentSource: string | null;
+    propsTransform: string | null;
+    /**
+     * Whether the row carries a real `component_source` body — supplied by the
+     * host when its warm list is BODY-LESS (the lazy design: metadata travels
+     * on the list, the body arrives per kind via the cold fetch). Omitted →
+     * derived from `componentSource` itself, so eager hosts change nothing.
+     */
+    hasComponentSource?: boolean;
+    pinnedKindVersion: number | null;
+    updatedAt: string | null;
+    createdBy: string | null;
+}
+/**
+ * One COMPILED bootstrap entry — the trusted-at-boot floor a host ships in its
+ * bundle, available synchronously from the first streamed byte.
+ */
+interface SystemComponentEntry {
+    kind: string;
+    platform: string;
+    role: ComponentRole;
+    componentKey: string;
+    source: string;
+    config: JsonObject;
+}
+/** The resolver's answer for one (kind, platform, role). */
+interface ComponentResolution {
+    /** The component key the renderer routes on (e.g. "flashcards"). */
+    componentKey: string;
+    source: string;
+    config: JsonObject;
+    /**
+     * Render-trust verdict (R6). Compiled entries are always active (trusted at
+     * bootstrap); DB rows carry their own `is_active`.
+     */
+    isActive: boolean;
+    /** Which tier produced this answer — the verification hook's `by`. */
+    resolvedBy: "compiled" | "db";
+    componentSource: string | null;
+    propsTransform: string | null;
+    /**
+     * TRUE when the row owns a real component body — even if `componentSource`
+     * is null because the host's warm list is body-less and the cold fetch has
+     * not landed it yet. THE routing gate: `routeToDbComponent` re-types on
+     * this flag, never on body presence, so a body-less row still routes and
+     * the renderer fetches/compiles the body lazily.
+     */
+    hasComponentSource: boolean;
+    pinnedKindVersion: number | null;
+    /** The db row's `updated_at` — the compile-cache staleness key. */
+    updatedAt: string | null;
+    createdBy: string | null;
+}
+/**
+ * The read side of a component resolver, as the render layer consumes it.
+ * The package ships {@link ComponentResolver}; a host with its own resolver
+ * only has to satisfy this.
+ */
+interface ComponentResolutionSource {
+    /** Synchronous — the render seam's per-block call. */
+    resolve(kind: string, platform: string, role: ComponentRole): ComponentResolution | null;
+    /** Eager targeted fetch for one kind; fire-and-forget, never awaited on the hot path. */
+    requestComponent(kind: string, platform: string, role: ComponentRole): void;
+    /** One list fetch per session. */
+    ensureWarm(): Promise<void>;
+    /** Refresh-on-view; rate-limited and deduped by the implementation. */
+    refresh(maxAgeMs?: number): Promise<void>;
+    /** Monotonic tier version — has anything at all changed? */
+    getVersion(): number;
+    /** Monotonic per-kind version (+ wholesale epoch) — the granular repaint key. */
+    getKindVersion(kind: string): number;
+    subscribe(listener: () => void): () => void;
+    subscribeKind(kind: string, listener: () => void): () => void;
+}
+
+export { type ComponentResolutionSource as C, type JsonObject as J, type KindComponentRow as K, type SystemComponentEntry as S, type ComponentResolution as a, type ContentIrErrorReporter as b, type ComponentRole as c, type ContentIrErrorReport as d, consoleErrorReporter as e };