@ai-matrx/agents 0.59.256 → 0.59.258

package/dist/models/react/index.d.cts

@@ -398,6 +398,14 @@ interface ModelCatalog {
     load(variant: ModelCatalogVariant): Promise<void>;
     /** Re-read the variant now (rows stay visible while it runs). Never throws. */
     reload(variant: ModelCatalogVariant): Promise<void>;
+    /**
+     * The catalog changed upstream (`catalog_changed`): re-read every picker variant already read and every
+     * record already read (`records.refresh()`). Called by itself on every `announceModelCatalogChanged`
+     * (catalog/changes.ts) unless `followChanges: false`. Never throws.
+     */
+    refresh(): Promise<void>;
+    /** Stop following `catalog_changed` (a test, or a catalog a host discards). */
+    dispose(): void;
     /**
      * The RECORDS part (agent core B3): options list, full records with resolved controls, class
      * configs, the class index and identities — what chat's retired `modelRegistry` slice held.
@@ -650,8 +658,30 @@ interface ModelListDropdownBaseProps {
 }
 declare function ModelListDropdown({ value: savedValue, localModels: localModelsProp, access: accessProp, onValueChange, inputModalities, outputModalities, selectionPurpose, allowedModelIds, catalogVariant, emptyOptionLabel, onClear, placeholder, priorityModelIds, pinnedOfferingId, onOfferingPinChange, modelOnly, className, triggerVariant, presentation, id, disabled, disabledTitle, "aria-label": ariaLabel, "aria-labelledby": ariaLabelledBy, }: ModelListDropdownProps): react.JSX.Element;
 
+/**
+ * `@ai-matrx/agents/models` — the ONE subscription to `catalog_changed`.
+ *
+ * The server publishes `catalog_changed` on the platform bus for every admin edit and direct SQL write to
+ * the model catalog. A host binds its bus client ONCE with `followModelCatalogChanges(subscribe)` (the web's
+ * directive registry, Matrx 2's IPC forward of the main-process bus); every model catalog
+ * (`createModelCatalog`: picker rows + records) re-reads itself on the notice, and any other reader
+ * subscribes here (`onModelCatalogChanged`, or `useModelCatalogRevision` / `useOnModelCatalogChanged` in
+ * `@ai-matrx/agents/models/react`). No surface keeps a model cache that misses the event.
+ *
+ * The hub lives on `globalThis` so two bundled copies of this module share one set of listeners.
+ */
+/** A `catalog_changed` payload: `{ catalog?: "models" | ..., change?, model_id? }`. */
+type ModelCatalogChangePayload = Record<string, unknown>;
+
 /** Subscribe to a slice of a model catalog's records. `select` must return a stable value for unchanged state. */
 declare function useModelRecordsSelector<T>(records: ModelRecords, select: (state: ModelRecordsState) => T): T;
+/**
+ * How many `catalog_changed` notices this page has seen. A reader that holds its OWN rows (the admin model
+ * editor) puts it in its effect dependencies / query key, so an edit made anywhere re-reads it.
+ */
+declare function useModelCatalogRevision(): number;
+/** Run `onChange` on every model catalog change notice (the latest callback; never stale). */
+declare function useOnModelCatalogChanged(onChange: (payload: ModelCatalogChangePayload) => void): void;
 
 /**
  * `@ai-matrx/agents/models` — downloadable (local) models: the catalog shape every client reads, the
@@ -1010,4 +1040,4 @@ interface DiscoveryResultViewProps {
 /** A resolved model: its header, the source's reason when the originals will not run, and every version judged. */
 declare function DiscoveryResultView({ result, device, runtimes, want, chooseLabel, mode, onChoose, renderVariantActions, renderActions }: DiscoveryResultViewProps): react.JSX.Element;
 
-export { type DiscoveryKind, type DiscoveryMode, type DiscoveryPort, DiscoveryResultView, type DiscoveryResultViewProps, type DiscoverySearchHit, type DiscoverySearchPage, type DiscoverySearchQuery, type DiscoverySort, type LocalModelEntry, type LocalModelsPort, type ModelAccessPort, type ModelCatalogLinkComponent, ModelCatalogProvider, type ModelCatalogProviderProps, type ModelCatalogUiPorts, ModelDiscovery, type ModelDiscoveryProps, ModelListDropdown, type ModelListDropdownProps, YOUR_KEY_LABEL, useLocalModels, useModelAccess, useModelCatalog, useModelCatalogStore, useModelCatalogUiPorts, useModelFavorites, useModelRecordsSelector };
+export { type DiscoveryKind, type DiscoveryMode, type DiscoveryPort, DiscoveryResultView, type DiscoveryResultViewProps, type DiscoverySearchHit, type DiscoverySearchPage, type DiscoverySearchQuery, type DiscoverySort, type LocalModelEntry, type LocalModelsPort, type ModelAccessPort, type ModelCatalogLinkComponent, ModelCatalogProvider, type ModelCatalogProviderProps, type ModelCatalogUiPorts, ModelDiscovery, type ModelDiscoveryProps, ModelListDropdown, type ModelListDropdownProps, YOUR_KEY_LABEL, useLocalModels, useModelAccess, useModelCatalog, useModelCatalogRevision, useModelCatalogStore, useModelCatalogUiPorts, useModelFavorites, useModelRecordsSelector, useOnModelCatalogChanged };

package/dist/models/react/index.d.ts

@@ -398,6 +398,14 @@ interface ModelCatalog {
     load(variant: ModelCatalogVariant): Promise<void>;
     /** Re-read the variant now (rows stay visible while it runs). Never throws. */
     reload(variant: ModelCatalogVariant): Promise<void>;
+    /**
+     * The catalog changed upstream (`catalog_changed`): re-read every picker variant already read and every
+     * record already read (`records.refresh()`). Called by itself on every `announceModelCatalogChanged`
+     * (catalog/changes.ts) unless `followChanges: false`. Never throws.
+     */
+    refresh(): Promise<void>;
+    /** Stop following `catalog_changed` (a test, or a catalog a host discards). */
+    dispose(): void;
     /**
      * The RECORDS part (agent core B3): options list, full records with resolved controls, class
      * configs, the class index and identities — what chat's retired `modelRegistry` slice held.
@@ -650,8 +658,30 @@ interface ModelListDropdownBaseProps {
 }
 declare function ModelListDropdown({ value: savedValue, localModels: localModelsProp, access: accessProp, onValueChange, inputModalities, outputModalities, selectionPurpose, allowedModelIds, catalogVariant, emptyOptionLabel, onClear, placeholder, priorityModelIds, pinnedOfferingId, onOfferingPinChange, modelOnly, className, triggerVariant, presentation, id, disabled, disabledTitle, "aria-label": ariaLabel, "aria-labelledby": ariaLabelledBy, }: ModelListDropdownProps): react.JSX.Element;
 
+/**
+ * `@ai-matrx/agents/models` — the ONE subscription to `catalog_changed`.
+ *
+ * The server publishes `catalog_changed` on the platform bus for every admin edit and direct SQL write to
+ * the model catalog. A host binds its bus client ONCE with `followModelCatalogChanges(subscribe)` (the web's
+ * directive registry, Matrx 2's IPC forward of the main-process bus); every model catalog
+ * (`createModelCatalog`: picker rows + records) re-reads itself on the notice, and any other reader
+ * subscribes here (`onModelCatalogChanged`, or `useModelCatalogRevision` / `useOnModelCatalogChanged` in
+ * `@ai-matrx/agents/models/react`). No surface keeps a model cache that misses the event.
+ *
+ * The hub lives on `globalThis` so two bundled copies of this module share one set of listeners.
+ */
+/** A `catalog_changed` payload: `{ catalog?: "models" | ..., change?, model_id? }`. */
+type ModelCatalogChangePayload = Record<string, unknown>;
+
 /** Subscribe to a slice of a model catalog's records. `select` must return a stable value for unchanged state. */
 declare function useModelRecordsSelector<T>(records: ModelRecords, select: (state: ModelRecordsState) => T): T;
+/**
+ * How many `catalog_changed` notices this page has seen. A reader that holds its OWN rows (the admin model
+ * editor) puts it in its effect dependencies / query key, so an edit made anywhere re-reads it.
+ */
+declare function useModelCatalogRevision(): number;
+/** Run `onChange` on every model catalog change notice (the latest callback; never stale). */
+declare function useOnModelCatalogChanged(onChange: (payload: ModelCatalogChangePayload) => void): void;
 
 /**
  * `@ai-matrx/agents/models` — downloadable (local) models: the catalog shape every client reads, the
@@ -1010,4 +1040,4 @@ interface DiscoveryResultViewProps {
 /** A resolved model: its header, the source's reason when the originals will not run, and every version judged. */
 declare function DiscoveryResultView({ result, device, runtimes, want, chooseLabel, mode, onChoose, renderVariantActions, renderActions }: DiscoveryResultViewProps): react.JSX.Element;
 
-export { type DiscoveryKind, type DiscoveryMode, type DiscoveryPort, DiscoveryResultView, type DiscoveryResultViewProps, type DiscoverySearchHit, type DiscoverySearchPage, type DiscoverySearchQuery, type DiscoverySort, type LocalModelEntry, type LocalModelsPort, type ModelAccessPort, type ModelCatalogLinkComponent, ModelCatalogProvider, type ModelCatalogProviderProps, type ModelCatalogUiPorts, ModelDiscovery, type ModelDiscoveryProps, ModelListDropdown, type ModelListDropdownProps, YOUR_KEY_LABEL, useLocalModels, useModelAccess, useModelCatalog, useModelCatalogStore, useModelCatalogUiPorts, useModelFavorites, useModelRecordsSelector };
+export { type DiscoveryKind, type DiscoveryMode, type DiscoveryPort, DiscoveryResultView, type DiscoveryResultViewProps, type DiscoverySearchHit, type DiscoverySearchPage, type DiscoverySearchQuery, type DiscoverySort, type LocalModelEntry, type LocalModelsPort, type ModelAccessPort, type ModelCatalogLinkComponent, ModelCatalogProvider, type ModelCatalogProviderProps, type ModelCatalogUiPorts, ModelDiscovery, type ModelDiscoveryProps, ModelListDropdown, type ModelListDropdownProps, YOUR_KEY_LABEL, useLocalModels, useModelAccess, useModelCatalog, useModelCatalogRevision, useModelCatalogStore, useModelCatalogUiPorts, useModelFavorites, useModelRecordsSelector, useOnModelCatalogChanged };

package/dist/models/react/index.js

@@ -2280,7 +2280,26 @@ function ModelListDropdown({
 }
 
 // models/react/records.ts
-import { useSyncExternalStore as useSyncExternalStore2 } from "react";
+import { useEffect as useEffect3, useRef as useRef2, useSyncExternalStore as useSyncExternalStore2 } from "react";
+
+// models/catalog/changes.ts
+var KEY = /* @__PURE__ */ Symbol.for("ai-matrx.agents.model-catalog-changes");
+function hub() {
+  const g = globalThis;
+  return g[KEY] ??= { listeners: /* @__PURE__ */ new Set(), revision: 0 };
+}
+function onModelCatalogChanged(listener) {
+  const h = hub();
+  h.listeners.add(listener);
+  return () => {
+    h.listeners.delete(listener);
+  };
+}
+function modelCatalogRevision() {
+  return hub().revision;
+}
+
+// models/react/records.ts
 function useModelRecordsSelector(records, select) {
   return useSyncExternalStore2(
     records.subscribe,
@@ -2288,10 +2307,19 @@ function useModelRecordsSelector(records, select) {
     () => select(records.getState())
   );
 }
+var subscribeRevision = (listener) => onModelCatalogChanged(() => listener());
+function useModelCatalogRevision() {
+  return useSyncExternalStore2(subscribeRevision, modelCatalogRevision, modelCatalogRevision);
+}
+function useOnModelCatalogChanged(onChange) {
+  const latest = useRef2(onChange);
+  latest.current = onChange;
+  useEffect3(() => onModelCatalogChanged((payload) => latest.current(payload)), []);
+}
 
 // models/react/ModelDiscovery.tsx
 import { formatCount as formatCount2, formatFileSize } from "@ai-matrx/kit/format";
-import { useEffect as useEffect3, useMemo as useMemo3, useRef as useRef2, useState as useState2 } from "react";
+import { useEffect as useEffect4, useMemo as useMemo3, useRef as useRef3, useState as useState2 } from "react";
 import { Avatar, AvatarFallback, AvatarImage, Collapsible, CollapsibleContent, CollapsibleTrigger, ErrorNotice } from "@ai-matrx/design-system";
 import { Badge, Button, Field, SearchField, Select, Tabs } from "@ai-matrx/design-system/controls";
 
@@ -2570,8 +2598,8 @@ function ModelDiscovery({
   const result = controlled !== void 0 ? controlled : own;
   const [resolving, setResolving] = useState2(null);
   const [resolveError, setResolveError] = useState2(null);
-  const abortRef = useRef2(null);
-  useEffect3(() => () => abortRef.current?.abort(), []);
+  const abortRef = useRef3(null);
+  useEffect4(() => () => abortRef.current?.abort(), []);
   const resolve = async (link) => {
     const trimmed = link.trim();
     if (!trimmed) return;
@@ -2661,7 +2689,7 @@ function SearchTab({ port, onPick }) {
   const [page, setPage] = useState2(null);
   const [busy, setBusy] = useState2(false);
   const [error, setError] = useState2(null);
-  const seq = useRef2(0);
+  const seq = useRef3(0);
   const run = async (cursor) => {
     if (!port.search) return;
     const mine = ++seq.current;
@@ -2677,7 +2705,7 @@ function SearchTab({ port, onPick }) {
       if (mine === seq.current) setBusy(false);
     }
   };
-  useEffect3(() => {
+  useEffect4(() => {
     if (port.search) void run(null);
   }, [kind, sort]);
   if (!port.search) return /* @__PURE__ */ jsx4("p", { className: "text-sm text-muted-foreground", children: "Search is not available here yet. Paste a link instead." });
@@ -2814,8 +2842,10 @@ export {
   useLocalModels,
   useModelAccess,
   useModelCatalog,
+  useModelCatalogRevision,
   useModelCatalogStore,
   useModelCatalogUiPorts,
   useModelFavorites,
-  useModelRecordsSelector
+  useModelRecordsSelector,
+  useOnModelCatalogChanged
 };

package/dist/runtime/react/index.cjs

@@ -1,6 +1,5 @@
 "use client";
 "use strict";
-"use client";
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;

package/dist/runtime/react/index.js

@@ -1,5 +1,4 @@
 "use client";
-"use client";
 
 // runtime/react/index.ts
 import { useEffect, useSyncExternalStore } from "react";

package/dist/settings/react/index.cjs

@@ -1,6 +1,5 @@
 "use client";
 "use strict";
-"use client";
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;

package/dist/settings/react/index.js

@@ -1,5 +1,4 @@
 "use client";
-"use client";
 
 // settings/react/index.ts
 import { useSyncExternalStore } from "react";

package/dist/skills/react/index.cjs

@@ -1,6 +1,5 @@
 "use client";
 "use strict";
-"use client";
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;

package/dist/skills/react/index.js

@@ -1,5 +1,4 @@
 "use client";
-"use client";
 
 // skills/react/useSkillCatalog.ts
 import { useEffect, useMemo, useSyncExternalStore } from "react";

package/dist/sources/index.d.cts

@@ -47,7 +47,13 @@ interface SourceRef {
     promote?: ResourcePromotion | ResourcePromotion[];
     exclude?: string[];
 }
-interface SourceSet {
+/**
+ * A TYPE, not an interface (2026-10-23): it IS a JSON object, so it is assignable wherever the server
+ * contract types the field as a JSON object (@ai-matrx/api's request bodies carry `source_set` as
+ * `{ [key: string]: JsonValue }` — the podcast generate request). An interface has no implicit index
+ * signature and would need a cast at every send.
+ */
+type SourceSet = {
     __kind: typeof SOURCE_SET_KIND;
     version: typeof SOURCE_SET_VERSION;
     sources: SourceRef[];
@@ -59,7 +65,7 @@ interface SourceSet {
     retrieve_query?: string;
     /** The model whose context window sets the budget. */
     target_model_id?: string;
-}
+};
 type SourceState = "ready" | "processing" | "failed" | "unavailable";
 interface SourceManifestForm {
     form: string;

package/dist/sources/index.d.ts

@@ -47,7 +47,13 @@ interface SourceRef {
     promote?: ResourcePromotion | ResourcePromotion[];
     exclude?: string[];
 }
-interface SourceSet {
+/**
+ * A TYPE, not an interface (2026-10-23): it IS a JSON object, so it is assignable wherever the server
+ * contract types the field as a JSON object (@ai-matrx/api's request bodies carry `source_set` as
+ * `{ [key: string]: JsonValue }` — the podcast generate request). An interface has no implicit index
+ * signature and would need a cast at every send.
+ */
+type SourceSet = {
     __kind: typeof SOURCE_SET_KIND;
     version: typeof SOURCE_SET_VERSION;
     sources: SourceRef[];
@@ -59,7 +65,7 @@ interface SourceSet {
     retrieve_query?: string;
     /** The model whose context window sets the budget. */
     target_model_id?: string;
-}
+};
 type SourceState = "ready" | "processing" | "failed" | "unavailable";
 interface SourceManifestForm {
     form: string;

package/dist/sources/react/index.d.cts

@@ -47,7 +47,13 @@ interface SourceRef {
     promote?: ResourcePromotion | ResourcePromotion[];
     exclude?: string[];
 }
-interface SourceSet {
+/**
+ * A TYPE, not an interface (2026-10-23): it IS a JSON object, so it is assignable wherever the server
+ * contract types the field as a JSON object (@ai-matrx/api's request bodies carry `source_set` as
+ * `{ [key: string]: JsonValue }` — the podcast generate request). An interface has no implicit index
+ * signature and would need a cast at every send.
+ */
+type SourceSet = {
     __kind: typeof SOURCE_SET_KIND;
     version: typeof SOURCE_SET_VERSION;
     sources: SourceRef[];
@@ -59,7 +65,7 @@ interface SourceSet {
     retrieve_query?: string;
     /** The model whose context window sets the budget. */
     target_model_id?: string;
-}
+};
 type SourceState = "ready" | "processing" | "failed" | "unavailable";
 interface SourceManifestForm {
     form: string;
@@ -705,21 +711,6 @@ interface FileRecoveryDeps {
     fileOrganizationId?: ((fileId: string) => string | null | undefined) | undefined;
 }
 
-/**
- * `@ai-matrx/agents/sources/react` — thin React hooks over the Source runtime
- * (`@ai-matrx/agents/sources/runtime`). No logic lives here that a non-React
- * client could not reach through the runtime itself: the hooks subscribe,
- * schedule, and hand back the same controller.
- *
- *   const set = useSourceSet(adapter, { persistenceReady });
- *   const intake = useSourceIntake(set, deps);
- *   useSourceRecovery(set, intake, runner, { organizationId, readFileState });
- *   const search = useSourcePartsSearch(client, ref, query);
- *
- * A host binds the adapter to its own store once (memoized per surface) —
- * the web app binds Redux; another client binds its own.
- */
-
 interface UseSourceSetOptions {
     /**
      * The draft store has been read back (a device store loads a moment after

package/dist/sources/react/index.d.ts

@@ -47,7 +47,13 @@ interface SourceRef {
     promote?: ResourcePromotion | ResourcePromotion[];
     exclude?: string[];
 }
-interface SourceSet {
+/**
+ * A TYPE, not an interface (2026-10-23): it IS a JSON object, so it is assignable wherever the server
+ * contract types the field as a JSON object (@ai-matrx/api's request bodies carry `source_set` as
+ * `{ [key: string]: JsonValue }` — the podcast generate request). An interface has no implicit index
+ * signature and would need a cast at every send.
+ */
+type SourceSet = {
     __kind: typeof SOURCE_SET_KIND;
     version: typeof SOURCE_SET_VERSION;
     sources: SourceRef[];
@@ -59,7 +65,7 @@ interface SourceSet {
     retrieve_query?: string;
     /** The model whose context window sets the budget. */
     target_model_id?: string;
-}
+};
 type SourceState = "ready" | "processing" | "failed" | "unavailable";
 interface SourceManifestForm {
     form: string;
@@ -705,21 +711,6 @@ interface FileRecoveryDeps {
     fileOrganizationId?: ((fileId: string) => string | null | undefined) | undefined;
 }
 
-/**
- * `@ai-matrx/agents/sources/react` — thin React hooks over the Source runtime
- * (`@ai-matrx/agents/sources/runtime`). No logic lives here that a non-React
- * client could not reach through the runtime itself: the hooks subscribe,
- * schedule, and hand back the same controller.
- *
- *   const set = useSourceSet(adapter, { persistenceReady });
- *   const intake = useSourceIntake(set, deps);
- *   useSourceRecovery(set, intake, runner, { organizationId, readFileState });
- *   const search = useSourcePartsSearch(client, ref, query);
- *
- * A host binds the adapter to its own store once (memoized per surface) —
- * the web app binds Redux; another client binds its own.
- */
-
 interface UseSourceSetOptions {
     /**
      * The draft store has been read back (a device store loads a moment after

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-matrx/agents",
-  "version": "0.59.256",
+  "version": "0.59.258",
   "description": "Portable AI Matrx agent stream protocol, event projection, and safe result-presentation primitives.",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -24,6 +24,7 @@
   },
   "files": [
     "dist",
+    "scripts/check-model-catalog-reads.mjs",
     "README.md",
     "LICENSE",
     "CHANGELOG.md"
@@ -508,12 +509,12 @@
   },
   "sideEffects": false,
   "dependencies": {
-    "@ai-matrx/api": "latest",
-    "@ai-matrx/data": "latest",
     "@ai-matrx/alchemy": "latest",
+    "@ai-matrx/api": "latest",
+    "@ai-matrx/associations": "latest",
     "@ai-matrx/content-ir": "latest",
+    "@ai-matrx/data": "latest",
     "@ai-matrx/design-system": "latest",
-    "@ai-matrx/associations": "latest",
     "@ai-matrx/diff": "latest",
     "@ai-matrx/icons": "latest",
     "@ai-matrx/kit": "latest"
@@ -555,11 +556,11 @@
   "scripts": {
     "build": "pnpm clean && node ./scripts/build-parts.mjs && node ../scripts/guard-exit.mjs ../scripts/check-node-env-not-inlined.mjs",
     "clean": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"",
-    "check:package": "node ./scripts/check-catalog-reader-columns.mjs && node ./scripts/check-catalog-reader-columns.mjs --self-test && node ../scripts/check-no-model-literals.mjs && node ../scripts/check-no-model-literals.mjs --self-test && node ../scripts/check-agents-below-chat.mjs && node ../scripts/check-agents-below-chat.mjs --self-test && pnpm build && node ../scripts/check-exports-agreement.mjs && publint && pnpm verify:tarball && node ../scripts/check-tarball-relative-imports.mjs --self-test && node ../scripts/check-tarball-relative-imports.mjs --pack . && node ../scripts/check-package-rules.mjs --self-test && node ../scripts/check-package-rules.mjs .",
+    "check:package": "node ./scripts/check-model-catalog-reads.mjs && node ./scripts/check-model-catalog-reads.mjs --self-test && node ./scripts/check-catalog-reader-columns.mjs && node ./scripts/check-catalog-reader-columns.mjs --self-test && node ../scripts/check-no-model-literals.mjs && node ../scripts/check-no-model-literals.mjs --self-test && node ../scripts/check-agents-below-chat.mjs && node ../scripts/check-agents-below-chat.mjs --self-test && pnpm build && node ../scripts/check-exports-agreement.mjs && publint && pnpm verify:tarball && node ../scripts/check-tarball-relative-imports.mjs --self-test && node ../scripts/check-tarball-relative-imports.mjs --pack . && node ../scripts/check-package-rules.mjs --self-test && node ../scripts/check-package-rules.mjs .",
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
     "verify:tarball": "node ./scripts/verify-tarball.mjs",
     "typegen:self-test": "node scripts/typegen/drop-guard.self-test.mjs && node scripts/typegen/check-api-types-fresh.mjs --self-test"
   },
-  "gitHead": "76b41cb76b379c9c04a1e26535fcf64606f59595"
+  "gitHead": "48dc0c53e766ad507fa37f41893b2b358be229f4"
 }

package/scripts/check-model-catalog-reads.mjs

@@ -0,0 +1,122 @@
+#!/usr/bin/env node
+/**
+ * ONE MODEL CATALOG READER (owner ruling 2026-10-23). Every surface that names or lists a model reads the
+ * model catalog through `@ai-matrx/agents/models` (records / readModelCatalog, subscribed to
+ * `catalog_changed` in models/catalog/changes.ts) and computes the name with `modelDisplayLabel`
+ * (models/label.ts), so an admin edit reaches every open app within seconds.
+ *
+ * Fails when a file outside apps/shared/matrx-agents/models/:
+ *   R1  reads ai.model_definition / model_public / model_offering / model_config / model_variant /
+ *       model_presentation (`.from("…")`) or the catalog RPCs (`admin_model_catalog`, `resolve_model_config`);
+ *   R2  computes a model label by hand (`x.common_name || x.name`, `?? …name`) instead of `modelDisplayLabel`.
+ * ALLOWED lists the few readers that keep their own read on purpose, each with why and how it follows the
+ * event. Test files are fixtures and are not scanned.
+ *
+ *   node apps/shared/matrx-agents/scripts/check-model-catalog-reads.mjs [--root <repo>] [--extra <dir>]... [--self-test]
+ * `--extra` adds a scan root (the red proof plants an untracked scratch file there). `--scan` replaces the
+ * default roots (Matrx 2: `node node_modules/@ai-matrx/agents/scripts/check-model-catalog-reads.mjs --root . --scan app`).
+ */
+import { mkdtempSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, relative, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const here = fileURLToPath(new URL(".", import.meta.url));
+const args = process.argv.slice(2);
+const flag = (name) => {
+  const out = [];
+  for (let i = 0; i < args.length; i++) if (args[i] === name && args[i + 1]) out.push(args[++i]);
+  return out;
+};
+const ROOT = resolve(flag("--root")[0] ?? join(here, "../../../.."));
+// `--scan <dir>` replaces the aidream roots: Matrx 2 runs this file from its installed
+// node_modules/@ai-matrx/agents with `--root . --scan app` (one guard, two repos).
+const ROOTS = [...(flag("--scan").length ? flag("--scan") : ["apps/shared", "apps/matrx-frontend"]), ...flag("--extra")];
+
+/** The reader module: the only place the catalog relations are read and the label is computed. */
+const HOME = "apps/shared/matrx-agents/models/";
+
+/** Files that keep their own catalog read, on purpose. Each says why and how it follows catalog_changed. */
+export const ALLOWED = {
+  // The admin model EDITOR: reads and writes every column of the rows it edits. Every container that shows
+  // its rows re-reads on the event (useOnModelCatalogChanged / useModelCatalogRevision).
+  "apps/matrx-frontend/features/ai-models/service.ts": "admin editor CRUD; containers follow catalog_changed",
+  "apps/matrx-frontend/features/ai-models/discovery/api.ts": "admin discovery CRUD; UnifiedModelKindTable follows catalog_changed",
+  "apps/matrx-frontend/features/ai-models/translation/data.ts": "admin translation grid; settings-translation keys its query on the revision",
+  // cx-dashboard names models on the server per request; CxDashboardLayoutClient router.refresh()es on the event.
+  "apps/matrx-frontend/features/cx-dashboard/service.ts": "server-rendered admin page; layout refreshes on catalog_changed",
+  // The public JSON API for external callers (anon key, CDN cached by design) — not a screen.
+  "apps/matrx-frontend/app/api/ai-models/route.ts": "public CDN-cached JSON API for external callers, not a screen",
+  // A security probe that reads the relations to prove their grants.
+  "apps/matrx-frontend/scripts/check-rls-on.ts": "RLS probe, not a reader",
+};
+
+const SKIP_DIR = new Set(["node_modules", "dist", ".next", ".turbo", "coverage", "generated", "__tests__", "__fixtures__"]);
+const isTest = (p) => /\.(test|spec)\.[cm]?[jt]sx?$/.test(p) || /\.d\.ts$/.test(p) || /\.generated\./.test(p);
+
+const R1 = /\.from\(\s*["'`](model_definition|model_public|model_offering|model_config|model_variant|model_presentation)["'`]|\.rpc\(\s*["'`](admin_model_catalog|resolve_model_config)["'`]/g;
+const R2 = /\bcommon_name\s*(\|\||\?\?)\s*[\w$?.]*\bname\b/g;
+
+function* walk(dir) {
+  let names;
+  try {
+    names = readdirSync(dir);
+  } catch {
+    return;
+  }
+  for (const n of names) {
+    if (SKIP_DIR.has(n)) continue;
+    const p = join(dir, n);
+    const st = statSync(p);
+    if (st.isDirectory()) yield* walk(p);
+    else if (/\.(ts|tsx|mts|cts|js|jsx|mjs)$/.test(n) && !isTest(n)) yield p;
+  }
+}
+
+const lineOf = (src, index) => src.slice(0, index).split("\n").length;
+function scan(roots) {
+  const findings = [];
+  for (const r of roots) {
+    for (const file of walk(resolve(ROOT, r))) {
+      const rel = relative(ROOT, file).split("\\").join("/");
+      if (rel.startsWith(HOME) || rel === "apps/shared/matrx-agents/scripts/check-model-catalog-reads.mjs") continue;
+      if (ALLOWED[rel]) continue;
+      const src = readFileSync(file, "utf8");
+      for (const [rule, re, what] of [
+        ["R1", R1, "reads the model catalog directly — use @ai-matrx/agents/models (records / chat's useModelLabel / readModelIdentities)"],
+        ["R2", R2, "computes a model label by hand — use modelDisplayLabel(row) from @ai-matrx/agents/models"],
+      ]) {
+        re.lastIndex = 0;
+        for (let m; (m = re.exec(src)); ) findings.push(`${rel}:${lineOf(src, m.index)}  ${rule} ${what}  [${m[0].replace(/\s+/g, " ")}]`);
+      }
+    }
+  }
+  return findings;
+}
+
+if (args.includes("--self-test")) {
+  // Falsifiability: a planted direct read and a hand-made label must each fail; the lawful form must pass.
+  const dir = mkdtempSync(join(tmpdir(), "model-catalog-reads-"));
+  try {
+    writeFileSync(join(dir, "bad.ts"), 'export const r = (db: any) => db.schema("ai").from("model_definition").select("id");\nexport const l = (m: any) =>\n  m?.common_name ??\n  m?.name;\n');
+    writeFileSync(join(dir, "good.ts"), 'import { modelDisplayLabel } from "@ai-matrx/agents/models";\nexport const l = (m: any) => modelDisplayLabel(m) ?? m.common_name ?? null;\n');
+    const got = scan([dir]);
+    const ok = got.length === 2 && got.some((f) => f.includes("bad.ts:1  R1")) && got.some((f) => f.includes("bad.ts:3  R2"));
+    if (!ok) {
+      console.error(`check-model-catalog-reads --self-test: FAILED — expected R1+R2 on bad.ts only, got:\n  ${got.join("\n  ") || "(nothing)"}`);
+      process.exit(1);
+    }
+    console.log("check-model-catalog-reads --self-test: OK — a planted read and a hand-made label both go red; modelDisplayLabel passes.");
+    process.exit(0);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+const findings = scan(ROOTS);
+if (findings.length) {
+  console.error(`check-model-catalog-reads: ${findings.length} finding(s) — every model name and list goes through @ai-matrx/agents/models so catalog_changed reaches it:`);
+  for (const f of findings) console.error(`  ${f}`);
+  process.exit(1);
+}
+console.log(`check-model-catalog-reads: OK — no model catalog read or hand-made model label outside ${HOME} (${Object.keys(ALLOWED).length} allowed readers).`);