@ai-matrx/agents 0.59.257 → 0.59.258

package/CHANGELOG.md

@@ -1,10 +1,15 @@
 # Changelog
 
-## 0.59.257
+## 0.59.258
 
 UNVERIFIED: this release has no Unreleased entry and the source comparison could not be made (the caller supplied no source comparison). Whether source changed is unknown; consumer action is unknown.
 Check the package's gitHead on npm against this version's gitHead: `git diff <previous gitHead> <this gitHead> -- apps/shared/matrx-agents/src`.
 
+## 0.59.257
+
+Automatic changed-only republish (docs/metadata drift since the last published version; verified: `git diff 76b41cb76b 0a2b8c9356 -- apps/shared/matrx-agents/src`
+has no shipped-source changes outside tests, fixtures and docs). No consumer action required.
+
 ## 0.59.256
 
 Automatic changed-only republish (docs/metadata drift since the last published version; verified: `git diff be3d056be5 76b41cb76b -- apps/shared/matrx-agents/src`

package/dist/models/index.cjs

@@ -42,6 +42,7 @@ __export(models_exports, {
   TOP_TIER_COST_RATING: () => TOP_TIER_COST_RATING,
   TOP_TIER_LOCKED_TITLE: () => TOP_TIER_LOCKED_TITLE,
   acceptsTextInstructions: () => acceptsTextInstructions,
+  announceModelCatalogChanged: () => announceModelCatalogChanged,
   blendedPrice: () => blendedPrice,
   buildModelClassIndex: () => buildModelClassIndex,
   buildSuccessionIndex: () => buildSuccessionIndex,
@@ -65,6 +66,7 @@ __export(models_exports, {
   fitsMemory: () => fitsMemory,
   fitsNeed: () => fitsNeed,
   fitsThisComputer: () => fitsThisComputer,
+  followModelCatalogChanges: () => followModelCatalogChanges,
   formatMemoryBytes: () => formatMemoryBytes,
   fromDiscovery: () => fromDiscovery,
   ggufEngine: () => ggufEngine,
@@ -82,21 +84,25 @@ __export(models_exports, {
   isListedVariant: () => isListedVariant,
   isLocalModelCatalog: () => isLocalModelCatalog,
   isManagedAgentModelCapability: () => isManagedAgentModelCapability,
+  isModelCatalogChange: () => isModelCatalogChange,
   isProjectorName: () => isProjectorName,
   isSupersedable: () => isSupersedable,
   isTopTierRating: () => isTopTierRating,
   judgeHeaderFacts: () => judgeHeaderFacts,
   mergeAuditRecordIntoCapabilities: () => mergeAuditRecordIntoCapabilities,
   missingShards: () => missingShards,
+  modelCatalogRevision: () => modelCatalogRevision,
   modelClassKnobFor: () => modelClassKnobFor,
   modelClassName: () => modelClassName,
   modelClassPinOf: () => modelClassPinOf,
+  modelDisplayLabel: () => modelDisplayLabel,
   modelsForSelectionPurpose: () => modelsForSelectionPurpose,
   normalizeArch: () => normalizeArch,
   normalizeModel: () => normalizeModel,
   normalizeModels: () => normalizeModels,
   normalizeOs: () => normalizeOs,
   normalizePromptSettings: () => normalizePromptSettings,
+  onModelCatalogChanged: () => onModelCatalogChanged,
   orderCatalogGroups: () => orderCatalogGroups,
   orderCatalogModels: () => orderCatalogModels,
   outputFormatControlKey: () => outputFormatControlKey,
@@ -108,6 +114,8 @@ __export(models_exports, {
   readCuratedRows: () => readCuratedRows,
   readGgufHeader: () => readGgufHeader,
   readModelCatalog: () => readModelCatalog,
+  readModelIdentities: () => readModelIdentities,
+  readPublicModel: () => readPublicModel,
   reconcileModelFavoriteIds: () => reconcileModelFavoriteIds,
   reportModelDiagnostic: () => reportModelDiagnostic,
   requireCanonicalCapabilities: () => requireCanonicalCapabilities,
@@ -918,6 +926,48 @@ var OUTPUT_MODALITIES = [
   "decision"
 ];
 
+// models/catalog/changes.ts
+var KEY2 = /* @__PURE__ */ Symbol.for("ai-matrx.agents.model-catalog-changes");
+function hub() {
+  const g = globalThis;
+  return g[KEY2] ??= { listeners: /* @__PURE__ */ new Set(), revision: 0 };
+}
+function isModelCatalogChange(payload) {
+  const catalog = payload?.["catalog"];
+  return catalog === void 0 || catalog === null || catalog === "models";
+}
+function onModelCatalogChanged(listener) {
+  const h = hub();
+  h.listeners.add(listener);
+  return () => {
+    h.listeners.delete(listener);
+  };
+}
+function modelCatalogRevision() {
+  return hub().revision;
+}
+function announceModelCatalogChanged(payload = {}) {
+  if (!isModelCatalogChange(payload)) return;
+  const h = hub();
+  h.revision += 1;
+  for (const l of [...h.listeners]) {
+    try {
+      l(payload);
+    } catch (err) {
+      console.error("[@ai-matrx/agents/models] a catalog_changed listener threw", err);
+    }
+  }
+}
+function followModelCatalogChanges(subscribe) {
+  return subscribe("catalog_changed", (payload) => announceModelCatalogChanged(payload ?? {}));
+}
+
+// models/label.ts
+function modelDisplayLabel(row) {
+  if (!row) return void 0;
+  return row.common_name || row.name || void 0;
+}
+
 // models/catalog/records.ts
 var classConfigKey = (modelId, offeringId) => `${modelId}:${offeringId}`;
 var EMPTY_MODEL_RECORDS = Object.freeze({
@@ -986,7 +1036,7 @@ function withIdLists(state2) {
   const active = [];
   const deprecated = [];
   for (const [id, record] of Object.entries(state2.entities)) (record.is_deprecated === true ? deprecated : active).push(id);
-  const label = (id) => state2.entities[id]?.common_name ?? state2.entities[id]?.name ?? "";
+  const label = (id) => modelDisplayLabel(state2.entities[id]) ?? "";
   const sort = (ids) => ids.sort((a, b) => label(a).localeCompare(label(b)));
   return { ...state2, activeIds: sort(active), deprecatedIds: sort(deprecated) };
 }
@@ -1407,13 +1457,13 @@ function selectDeprecatedModels(s3) {
 var allOf = memo((entities) => Object.values(entities));
 var selectAllModels = (s3) => allOf(s3.entities);
 var optionsOf = memo(
-  (models) => models.map((m) => ({ value: m.id, label: m.common_name || m.name || m.id, maker: m.maker, costRating: m.cost_rating, speedRating: m.speed_rating }))
+  (models) => models.map((m) => ({ value: m.id, label: modelDisplayLabel(m) || m.id, maker: m.maker, costRating: m.cost_rating, speedRating: m.speed_rating }))
 );
 var selectModelOptions = (s3) => optionsOf(selectActiveModels(s3));
 var allOptionsOf = memo(
   (entities) => Object.values(entities).map((m) => ({
     value: m.id,
-    label: m.common_name || m.name || m.id,
+    label: modelDisplayLabel(m) || m.id,
     maker: m.maker,
     isDeprecated: m.is_deprecated ?? false,
     isRetired: m.retired_at != null,
@@ -1426,7 +1476,7 @@ function selectModelLabelById(s3, modelId) {
   if (!modelId) return void 0;
   const m = s3.entities[modelId];
   const identity = s3.identityById[modelId];
-  return m?.common_name || m?.name || identity?.common_name || identity?.name || void 0;
+  return modelDisplayLabel(m) || modelDisplayLabel(identity);
 }
 var selectModelNameById = (s3, modelId) => modelId ? s3.entities[modelId]?.name : void 0;
 var selectModelClassName = (s3, modelId, offeringId) => modelClassName(s3.modelClassIndex, modelId, offeringId);
@@ -1444,6 +1494,18 @@ var selectDeprecatedModelsReady = (s3) => (s3.fetchScope === "deprecated" || s3.
 var selectAllModelsReady = (s3) => s3.fetchScope === "all";
 var selectModelIdentityById = (s3, modelId) => s3.identityById[modelId];
 var selectModelIdentityLookupStatus = (s3, modelId) => s3.identityStatusById[modelId] ?? "idle";
+async function readModelIdentities(client, modelIds) {
+  const ids = [...new Set(modelIds.filter(Boolean))];
+  if (ids.length === 0) return [];
+  const { data, error } = await client.schema("ai").from("model_definition").select("id, name, common_name, is_deprecated").in("id", ids);
+  if (error) throw new Error(error.message);
+  return Array.isArray(data) ? data : [];
+}
+async function readPublicModel(client, key) {
+  const { data, error } = await client.schema("ai").from("model_public").select("id, name").eq(catalogKeyColumn(key), key.trim()).maybeSingle();
+  if (error) return { row: null, error: error.message };
+  return { row: data ?? null, error: null };
+}
 
 // models/catalog/store.ts
 var IDLE = { status: "idle", models: [], error: null, loadedAt: null };
@@ -1713,8 +1775,16 @@ function createModelCatalog(config) {
     errorSink,
     ...config.isSignedIn ? { isSignedIn: config.isSignedIn } : {}
   });
+  const refresh = async () => {
+    const variants = Object.keys(state2).filter((v) => state2[v].status !== "idle");
+    await Promise.all([records.refresh(), ...variants.map((v) => run(v))]);
+  };
+  const stopFollowing = config.followChanges === false ? () => {
+  } : onModelCatalogChanged(() => void refresh());
   return {
     records,
+    refresh,
+    dispose: stopFollowing,
     getState: () => state2,
     subscribe(listener) {
       listeners.add(listener);

package/dist/models/index.d.cts

@@ -750,6 +750,41 @@ declare const selectDeprecatedModelsReady: (s: ModelRecordsState) => boolean;
 declare const selectAllModelsReady: (s: ModelRecordsState) => boolean;
 declare const selectModelIdentityById: (s: ModelRecordsState, modelId: string) => ModelIdentityRow | undefined;
 declare const selectModelIdentityLookupStatus: (s: ModelRecordsState, modelId: string) => "loading" | "succeeded" | "failed" | "idle";
+/**
+ * The durable identities (id, name, common_name, is_deprecated) of these models, read from
+ * `ai.model_definition` — the same read `records.loadIdentity` makes. For a process with no records
+ * store that stamps a name ONCE (a sync snapshot); a screen names models through the records hooks.
+ * Rows the database does not return are absent. Throws the database's error.
+ */
+declare function readModelIdentities(client: ModelRecordsClient, modelIds: readonly string[]): Promise<ModelIdentityRow[]>;
+/** The structural read `readPublicModel` needs (a supabase-js client fits it as is). */
+interface PublicModelClient {
+    schema(name: "ai"): {
+        from(table: "model_public"): {
+            select(columns: string): {
+                eq(column: string, value: string): {
+                    maybeSingle(): PromiseLike<{
+                        data: unknown;
+                        error: {
+                            message: string;
+                        } | null;
+                    }>;
+                };
+            };
+        };
+    };
+}
+/**
+ * One `ai.model_public` row (id + canonical name) by id or name, read fresh — for a value sent on the wire at
+ * the moment it is used (a voice session's transcription model), never for a label on screen.
+ */
+declare function readPublicModel(client: PublicModelClient, key: string): Promise<{
+    row: {
+        id?: unknown;
+        name?: unknown;
+    } | null;
+    error: string | null;
+}>;
 
 /**
  * `@ai-matrx/agents/models` — `createModelCatalog`: the headless model catalog store.
@@ -802,6 +837,8 @@ type ModelCatalogErrorSink = (event: {
     context?: object;
 }) => void;
 interface ModelCatalogConfig {
+    /** Re-read on every model catalog change notice (catalog/changes.ts). Default true. */
+    followChanges?: boolean;
     client: ModelCatalogClient;
     /** OPTIONAL — DEFAULT: a tagged `console.error` (the in-picker error banner always renders too). */
     errorSink?: ModelCatalogErrorSink;
@@ -828,6 +865,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.
@@ -1818,4 +1863,49 @@ catalog?: SuccessionClient): Promise<NewAgentModel>;
  */
 declare function resolveModelMapKnob(value: unknown, catalog: SuccessionClient): Promise<Record<string, string>>;
 
-export { type AdminOffering, type AdminPricingBand, type ArtifactUse, type AuditCapabilitiesRecord, CHAT_DEFAULT_MODEL_KNOB, CONTENT_TYPES, type CapabilitiesParseContext, type CatalogKeyColumn, type CatalogKindInput, type CatalogModel, type CatalogTier, type CheapestAdequateOptions, type CompatStatus, type ContentType, type CuratedCatalogClient, type CuratedModel, type CuratedPresentation, type CuratedRows, type CuratedVariant, DEFAULT_CAPABILITIES, type DecidedBy, type DeviceGraphics, type DeviceHardware, type DiscoveryAmbiguity, type DiscoveryArtifact, type DiscoveryMedia, type DiscoveryResult, type DiscoveryRuntime, type DiscoverySource, type DiscoveryVariant, EMPTY_MODEL_RECORDS, EXCLUDED_REVIEW_STATES, FEATURE_BUCKETS, FEATURE_BUCKET_ORDER, FEATURE_KEYS, FILE_TYPE_QUANT, type FeatureBucket, type FeatureBucketMeta, type FeatureKey, type FitCapabilities, GgufError, type GgufHeader, type GgufRead, type GgufTensor, type GroupedFeatures, type HardwareClass, type HardwareClasses, type HeaderFlag, type HeaderJudgement, type HeaderRefusal, INPUT_MODALITIES, INTERACTION_MODES, type Interaction, type InteractionMode, type LocalArtifact, type LocalCatalogClient, type LocalCatalogQuery, type LocalCompatRow, type LocalModel, type LocalModelCatalog, type LocalPresentation, type LocalRuntime, type LocalRuntimeBuild, type LocalVariant, MAX_SUCCESSION_HOPS, MODEL_CATALOG_KINDS, MODEL_FAVORITE_ENTITY_TYPE, type Modality, type ModelCapabilities, type ModelCatalog, type ModelCatalogClient, type ModelCatalogConfig, type ModelCatalogErrorSink, type ModelCatalogPgError, type ModelCatalogPgResult, type ModelCatalogQuery, type ModelCatalogState, type ModelCatalogVariant, type ModelCatalogVariantState, type ModelClassConfig, type ModelClassEntry, type ModelClassIndex, type ModelDiagnosticEntry, type ModelDiagnosticsSink, type ModelFavorites, type ModelFavoritesCache, type ModelFavoritesClient, type ModelFavoritesConfig, type ModelFavoritesErrorSink, type ModelFavoritesState, type ModelFetchScope, type ModelFileHandle, type ModelFit, type ModelIdentityRow, type ModelJson, type ModelNeed, type ModelOfferingRow, type ModelOption, type ModelOptionWithLifecycle, type ModelRecord, type ModelRecordFetchType, type ModelRecords, type ModelRecordsClient, type ModelRecordsConfig, type ModelRecordsState, type ModelSelectionPurpose, type ModelSetEnv, type ModelSetFacts, type ModelSetValidation, NEW_AGENT_DEFAULT_MODEL_KNOB, type NewAgentModel, type NoSelection, OUTPUT_MODALITIES, type OrderedLike, type PreferredModelChoice, type PreferredModelChoicePorts, type PriceTier, type PricedCatalogModel, type RankOptions, type RankedVariant, type ReadModelCatalogOptions, SERVICE_LABEL, SERVICE_LABEL_PLURAL, type SelectDevice, type Selection, type ShardName, type SuccessionClient, type SuccessionIndex, type SuccessionNode, TOP_TIER_COST_RATING, TOP_TIER_LOCKED_TITLE, type VariantDiscovery, type VariantVerdict, type Want, acceptsTextInstructions, blendedPrice, buildModelClassIndex, buildSuccessionIndex, catalogFingerprint, catalogForApp, catalogKeyColumn, catalogKindOf, cheapestAdequateModel, classConfigKey, collapseTiersByClass, costRatingTier, costRatingWord, createModelCatalog, createModelFavorites, createModelRecords, curatedList, displayOrderOf, favoriteIdsEqual, fetchCuratedModels, findNonCanonicalCapabilityValues, fitsMemory, fitsNeed, fitsThisComputer, formatMemoryBytes, fromDiscovery, ggufEngine, ggufFacts, groupFeatures, hardwareClassesOf, hasCompatibleDecisionInteraction, isChatModelCapability, isContentType, isConversationalModelCapability, isDecisionModelCapability, isFeatureKey, isHelperGguf, isInteractionMode, isListedVariant, isLocalModelCatalog, isManagedAgentModelCapability, isProjectorName, isSupersedable, isTopTierRating, judgeHeaderFacts, mergeAuditRecordIntoCapabilities, missingShards, modelClassKnobFor, modelClassName, modelClassPinOf, modelsForSelectionPurpose, normalizeArch, normalizeModel, normalizeModels, normalizeOs, normalizePromptSettings, orderCatalogGroups, orderCatalogModels, outputFormatControlKey, parseCapabilities, pickProjector, priceTierRating, quantFromName, rankVariants, readCuratedRows, readGgufHeader, readModelCatalog, reconcileModelFavoriteIds, reportModelDiagnostic, requireCanonicalCapabilities, requiredArtifacts, resetSuccessionLogForTests, resolveLiveModelId, resolveModelMapKnob, resolveNewAgentModelId, resolvePreferredModelChoice, resolveSuccessor, runtimesOnEngine, seesImages, selectActiveModels, selectActiveModelsReady, selectAllModelOptions, selectAllModels, selectAllModelsReady, selectDeprecatedModels, selectDeprecatedModelsReady, selectModelById, selectModelClassConfig, selectModelClassName, selectModelControls, selectModelDetailError, selectModelFetchType, selectModelFullyLoaded, selectModelIdentityById, selectModelIdentityLookupStatus, selectModelLabelById, selectModelLabelWithClass, selectModelNameById, selectModelOptions, selectVariant, serviceCountLabel, setModelDiagnosticsSink, shapeCuratedModels, shardFileName, shardName, speedRatingLabel, speedRatingWord, splitSetProblems, takesInput, toAuditRecord, validateModelSet, variantVerdict, withModelClass };
+/**
+ * `@ai-matrx/agents/models` — THE model label formula. Every surface that names a model computes the
+ * name here: the person-facing `common_name`, else the canonical `name`. An empty `common_name` counts
+ * as absent. Pure; the row it is handed must come from the subscribed catalog (records / readModelCatalog),
+ * so a `catalog_changed` notice re-renders it. Guard: `scripts/check-model-catalog-reads.mjs`.
+ */
+/** The two columns a model label is made from (cloud records, identities, local catalog rows). */
+interface ModelLabelSource {
+    common_name?: string | null;
+    name?: string | null;
+}
+/** A row that always has a canonical name always has a label. */
+declare function modelDisplayLabel(row: {
+    common_name?: string | null;
+    name: string;
+}): string;
+declare function modelDisplayLabel(row: ModelLabelSource | null | undefined): string | undefined;
+
+/**
+ * `@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>;
+/** The bus client's subscribe call: `(action, handler) => unsubscribe` (the web's `registerDirectiveHandler`). */
+type ModelCatalogDirectiveSubscribe = (action: "catalog_changed", handler: (payload: ModelCatalogChangePayload) => void) => () => void;
+/** Is this notice about the MODEL catalog? (`catalog` absent or `"models"`; the tool catalog shares the action.) */
+declare function isModelCatalogChange(payload: ModelCatalogChangePayload | null | undefined): boolean;
+/** Listen for model catalog changes. Returns the unsubscribe. */
+declare function onModelCatalogChanged(listener: (payload: ModelCatalogChangePayload) => void): () => void;
+/** How many model catalog changes this page has seen (a React key / effect dependency). */
+declare function modelCatalogRevision(): number;
+/** Announce a model catalog change to every listener (a notice that is not about models is ignored). */
+declare function announceModelCatalogChanged(payload?: ModelCatalogChangePayload): void;
+/** Bind the host's bus client: every `catalog_changed` it delivers reaches every model reader. Returns the unbind. */
+declare function followModelCatalogChanges(subscribe: ModelCatalogDirectiveSubscribe): () => void;
+
+export { type AdminOffering, type AdminPricingBand, type ArtifactUse, type AuditCapabilitiesRecord, CHAT_DEFAULT_MODEL_KNOB, CONTENT_TYPES, type CapabilitiesParseContext, type CatalogKeyColumn, type CatalogKindInput, type CatalogModel, type CatalogTier, type CheapestAdequateOptions, type CompatStatus, type ContentType, type CuratedCatalogClient, type CuratedModel, type CuratedPresentation, type CuratedRows, type CuratedVariant, DEFAULT_CAPABILITIES, type DecidedBy, type DeviceGraphics, type DeviceHardware, type DiscoveryAmbiguity, type DiscoveryArtifact, type DiscoveryMedia, type DiscoveryResult, type DiscoveryRuntime, type DiscoverySource, type DiscoveryVariant, EMPTY_MODEL_RECORDS, EXCLUDED_REVIEW_STATES, FEATURE_BUCKETS, FEATURE_BUCKET_ORDER, FEATURE_KEYS, FILE_TYPE_QUANT, type FeatureBucket, type FeatureBucketMeta, type FeatureKey, type FitCapabilities, GgufError, type GgufHeader, type GgufRead, type GgufTensor, type GroupedFeatures, type HardwareClass, type HardwareClasses, type HeaderFlag, type HeaderJudgement, type HeaderRefusal, INPUT_MODALITIES, INTERACTION_MODES, type Interaction, type InteractionMode, type LocalArtifact, type LocalCatalogClient, type LocalCatalogQuery, type LocalCompatRow, type LocalModel, type LocalModelCatalog, type LocalPresentation, type LocalRuntime, type LocalRuntimeBuild, type LocalVariant, MAX_SUCCESSION_HOPS, MODEL_CATALOG_KINDS, MODEL_FAVORITE_ENTITY_TYPE, type Modality, type ModelCapabilities, type ModelCatalog, type ModelCatalogChangePayload, type ModelCatalogClient, type ModelCatalogConfig, type ModelCatalogDirectiveSubscribe, type ModelCatalogErrorSink, type ModelCatalogPgError, type ModelCatalogPgResult, type ModelCatalogQuery, type ModelCatalogState, type ModelCatalogVariant, type ModelCatalogVariantState, type ModelClassConfig, type ModelClassEntry, type ModelClassIndex, type ModelDiagnosticEntry, type ModelDiagnosticsSink, type ModelFavorites, type ModelFavoritesCache, type ModelFavoritesClient, type ModelFavoritesConfig, type ModelFavoritesErrorSink, type ModelFavoritesState, type ModelFetchScope, type ModelFileHandle, type ModelFit, type ModelIdentityRow, type ModelJson, type ModelLabelSource, type ModelNeed, type ModelOfferingRow, type ModelOption, type ModelOptionWithLifecycle, type ModelRecord, type ModelRecordFetchType, type ModelRecords, type ModelRecordsClient, type ModelRecordsConfig, type ModelRecordsState, type ModelSelectionPurpose, type ModelSetEnv, type ModelSetFacts, type ModelSetValidation, NEW_AGENT_DEFAULT_MODEL_KNOB, type NewAgentModel, type NoSelection, OUTPUT_MODALITIES, type OrderedLike, type PreferredModelChoice, type PreferredModelChoicePorts, type PriceTier, type PricedCatalogModel, type PublicModelClient, type RankOptions, type RankedVariant, type ReadModelCatalogOptions, SERVICE_LABEL, SERVICE_LABEL_PLURAL, type SelectDevice, type Selection, type ShardName, type SuccessionClient, type SuccessionIndex, type SuccessionNode, TOP_TIER_COST_RATING, TOP_TIER_LOCKED_TITLE, type VariantDiscovery, type VariantVerdict, type Want, acceptsTextInstructions, announceModelCatalogChanged, blendedPrice, buildModelClassIndex, buildSuccessionIndex, catalogFingerprint, catalogForApp, catalogKeyColumn, catalogKindOf, cheapestAdequateModel, classConfigKey, collapseTiersByClass, costRatingTier, costRatingWord, createModelCatalog, createModelFavorites, createModelRecords, curatedList, displayOrderOf, favoriteIdsEqual, fetchCuratedModels, findNonCanonicalCapabilityValues, fitsMemory, fitsNeed, fitsThisComputer, followModelCatalogChanges, formatMemoryBytes, fromDiscovery, ggufEngine, ggufFacts, groupFeatures, hardwareClassesOf, hasCompatibleDecisionInteraction, isChatModelCapability, isContentType, isConversationalModelCapability, isDecisionModelCapability, isFeatureKey, isHelperGguf, isInteractionMode, isListedVariant, isLocalModelCatalog, isManagedAgentModelCapability, isModelCatalogChange, isProjectorName, isSupersedable, isTopTierRating, judgeHeaderFacts, mergeAuditRecordIntoCapabilities, missingShards, modelCatalogRevision, modelClassKnobFor, modelClassName, modelClassPinOf, modelDisplayLabel, modelsForSelectionPurpose, normalizeArch, normalizeModel, normalizeModels, normalizeOs, normalizePromptSettings, onModelCatalogChanged, orderCatalogGroups, orderCatalogModels, outputFormatControlKey, parseCapabilities, pickProjector, priceTierRating, quantFromName, rankVariants, readCuratedRows, readGgufHeader, readModelCatalog, readModelIdentities, readPublicModel, reconcileModelFavoriteIds, reportModelDiagnostic, requireCanonicalCapabilities, requiredArtifacts, resetSuccessionLogForTests, resolveLiveModelId, resolveModelMapKnob, resolveNewAgentModelId, resolvePreferredModelChoice, resolveSuccessor, runtimesOnEngine, seesImages, selectActiveModels, selectActiveModelsReady, selectAllModelOptions, selectAllModels, selectAllModelsReady, selectDeprecatedModels, selectDeprecatedModelsReady, selectModelById, selectModelClassConfig, selectModelClassName, selectModelControls, selectModelDetailError, selectModelFetchType, selectModelFullyLoaded, selectModelIdentityById, selectModelIdentityLookupStatus, selectModelLabelById, selectModelLabelWithClass, selectModelNameById, selectModelOptions, selectVariant, serviceCountLabel, setModelDiagnosticsSink, shapeCuratedModels, shardFileName, shardName, speedRatingLabel, speedRatingWord, splitSetProblems, takesInput, toAuditRecord, validateModelSet, variantVerdict, withModelClass };

package/dist/models/index.d.ts

@@ -750,6 +750,41 @@ declare const selectDeprecatedModelsReady: (s: ModelRecordsState) => boolean;
 declare const selectAllModelsReady: (s: ModelRecordsState) => boolean;
 declare const selectModelIdentityById: (s: ModelRecordsState, modelId: string) => ModelIdentityRow | undefined;
 declare const selectModelIdentityLookupStatus: (s: ModelRecordsState, modelId: string) => "loading" | "succeeded" | "failed" | "idle";
+/**
+ * The durable identities (id, name, common_name, is_deprecated) of these models, read from
+ * `ai.model_definition` — the same read `records.loadIdentity` makes. For a process with no records
+ * store that stamps a name ONCE (a sync snapshot); a screen names models through the records hooks.
+ * Rows the database does not return are absent. Throws the database's error.
+ */
+declare function readModelIdentities(client: ModelRecordsClient, modelIds: readonly string[]): Promise<ModelIdentityRow[]>;
+/** The structural read `readPublicModel` needs (a supabase-js client fits it as is). */
+interface PublicModelClient {
+    schema(name: "ai"): {
+        from(table: "model_public"): {
+            select(columns: string): {
+                eq(column: string, value: string): {
+                    maybeSingle(): PromiseLike<{
+                        data: unknown;
+                        error: {
+                            message: string;
+                        } | null;
+                    }>;
+                };
+            };
+        };
+    };
+}
+/**
+ * One `ai.model_public` row (id + canonical name) by id or name, read fresh — for a value sent on the wire at
+ * the moment it is used (a voice session's transcription model), never for a label on screen.
+ */
+declare function readPublicModel(client: PublicModelClient, key: string): Promise<{
+    row: {
+        id?: unknown;
+        name?: unknown;
+    } | null;
+    error: string | null;
+}>;
 
 /**
  * `@ai-matrx/agents/models` — `createModelCatalog`: the headless model catalog store.
@@ -802,6 +837,8 @@ type ModelCatalogErrorSink = (event: {
     context?: object;
 }) => void;
 interface ModelCatalogConfig {
+    /** Re-read on every model catalog change notice (catalog/changes.ts). Default true. */
+    followChanges?: boolean;
     client: ModelCatalogClient;
     /** OPTIONAL — DEFAULT: a tagged `console.error` (the in-picker error banner always renders too). */
     errorSink?: ModelCatalogErrorSink;
@@ -828,6 +865,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.
@@ -1818,4 +1863,49 @@ catalog?: SuccessionClient): Promise<NewAgentModel>;
  */
 declare function resolveModelMapKnob(value: unknown, catalog: SuccessionClient): Promise<Record<string, string>>;
 
-export { type AdminOffering, type AdminPricingBand, type ArtifactUse, type AuditCapabilitiesRecord, CHAT_DEFAULT_MODEL_KNOB, CONTENT_TYPES, type CapabilitiesParseContext, type CatalogKeyColumn, type CatalogKindInput, type CatalogModel, type CatalogTier, type CheapestAdequateOptions, type CompatStatus, type ContentType, type CuratedCatalogClient, type CuratedModel, type CuratedPresentation, type CuratedRows, type CuratedVariant, DEFAULT_CAPABILITIES, type DecidedBy, type DeviceGraphics, type DeviceHardware, type DiscoveryAmbiguity, type DiscoveryArtifact, type DiscoveryMedia, type DiscoveryResult, type DiscoveryRuntime, type DiscoverySource, type DiscoveryVariant, EMPTY_MODEL_RECORDS, EXCLUDED_REVIEW_STATES, FEATURE_BUCKETS, FEATURE_BUCKET_ORDER, FEATURE_KEYS, FILE_TYPE_QUANT, type FeatureBucket, type FeatureBucketMeta, type FeatureKey, type FitCapabilities, GgufError, type GgufHeader, type GgufRead, type GgufTensor, type GroupedFeatures, type HardwareClass, type HardwareClasses, type HeaderFlag, type HeaderJudgement, type HeaderRefusal, INPUT_MODALITIES, INTERACTION_MODES, type Interaction, type InteractionMode, type LocalArtifact, type LocalCatalogClient, type LocalCatalogQuery, type LocalCompatRow, type LocalModel, type LocalModelCatalog, type LocalPresentation, type LocalRuntime, type LocalRuntimeBuild, type LocalVariant, MAX_SUCCESSION_HOPS, MODEL_CATALOG_KINDS, MODEL_FAVORITE_ENTITY_TYPE, type Modality, type ModelCapabilities, type ModelCatalog, type ModelCatalogClient, type ModelCatalogConfig, type ModelCatalogErrorSink, type ModelCatalogPgError, type ModelCatalogPgResult, type ModelCatalogQuery, type ModelCatalogState, type ModelCatalogVariant, type ModelCatalogVariantState, type ModelClassConfig, type ModelClassEntry, type ModelClassIndex, type ModelDiagnosticEntry, type ModelDiagnosticsSink, type ModelFavorites, type ModelFavoritesCache, type ModelFavoritesClient, type ModelFavoritesConfig, type ModelFavoritesErrorSink, type ModelFavoritesState, type ModelFetchScope, type ModelFileHandle, type ModelFit, type ModelIdentityRow, type ModelJson, type ModelNeed, type ModelOfferingRow, type ModelOption, type ModelOptionWithLifecycle, type ModelRecord, type ModelRecordFetchType, type ModelRecords, type ModelRecordsClient, type ModelRecordsConfig, type ModelRecordsState, type ModelSelectionPurpose, type ModelSetEnv, type ModelSetFacts, type ModelSetValidation, NEW_AGENT_DEFAULT_MODEL_KNOB, type NewAgentModel, type NoSelection, OUTPUT_MODALITIES, type OrderedLike, type PreferredModelChoice, type PreferredModelChoicePorts, type PriceTier, type PricedCatalogModel, type RankOptions, type RankedVariant, type ReadModelCatalogOptions, SERVICE_LABEL, SERVICE_LABEL_PLURAL, type SelectDevice, type Selection, type ShardName, type SuccessionClient, type SuccessionIndex, type SuccessionNode, TOP_TIER_COST_RATING, TOP_TIER_LOCKED_TITLE, type VariantDiscovery, type VariantVerdict, type Want, acceptsTextInstructions, blendedPrice, buildModelClassIndex, buildSuccessionIndex, catalogFingerprint, catalogForApp, catalogKeyColumn, catalogKindOf, cheapestAdequateModel, classConfigKey, collapseTiersByClass, costRatingTier, costRatingWord, createModelCatalog, createModelFavorites, createModelRecords, curatedList, displayOrderOf, favoriteIdsEqual, fetchCuratedModels, findNonCanonicalCapabilityValues, fitsMemory, fitsNeed, fitsThisComputer, formatMemoryBytes, fromDiscovery, ggufEngine, ggufFacts, groupFeatures, hardwareClassesOf, hasCompatibleDecisionInteraction, isChatModelCapability, isContentType, isConversationalModelCapability, isDecisionModelCapability, isFeatureKey, isHelperGguf, isInteractionMode, isListedVariant, isLocalModelCatalog, isManagedAgentModelCapability, isProjectorName, isSupersedable, isTopTierRating, judgeHeaderFacts, mergeAuditRecordIntoCapabilities, missingShards, modelClassKnobFor, modelClassName, modelClassPinOf, modelsForSelectionPurpose, normalizeArch, normalizeModel, normalizeModels, normalizeOs, normalizePromptSettings, orderCatalogGroups, orderCatalogModels, outputFormatControlKey, parseCapabilities, pickProjector, priceTierRating, quantFromName, rankVariants, readCuratedRows, readGgufHeader, readModelCatalog, reconcileModelFavoriteIds, reportModelDiagnostic, requireCanonicalCapabilities, requiredArtifacts, resetSuccessionLogForTests, resolveLiveModelId, resolveModelMapKnob, resolveNewAgentModelId, resolvePreferredModelChoice, resolveSuccessor, runtimesOnEngine, seesImages, selectActiveModels, selectActiveModelsReady, selectAllModelOptions, selectAllModels, selectAllModelsReady, selectDeprecatedModels, selectDeprecatedModelsReady, selectModelById, selectModelClassConfig, selectModelClassName, selectModelControls, selectModelDetailError, selectModelFetchType, selectModelFullyLoaded, selectModelIdentityById, selectModelIdentityLookupStatus, selectModelLabelById, selectModelLabelWithClass, selectModelNameById, selectModelOptions, selectVariant, serviceCountLabel, setModelDiagnosticsSink, shapeCuratedModels, shardFileName, shardName, speedRatingLabel, speedRatingWord, splitSetProblems, takesInput, toAuditRecord, validateModelSet, variantVerdict, withModelClass };
+/**
+ * `@ai-matrx/agents/models` — THE model label formula. Every surface that names a model computes the
+ * name here: the person-facing `common_name`, else the canonical `name`. An empty `common_name` counts
+ * as absent. Pure; the row it is handed must come from the subscribed catalog (records / readModelCatalog),
+ * so a `catalog_changed` notice re-renders it. Guard: `scripts/check-model-catalog-reads.mjs`.
+ */
+/** The two columns a model label is made from (cloud records, identities, local catalog rows). */
+interface ModelLabelSource {
+    common_name?: string | null;
+    name?: string | null;
+}
+/** A row that always has a canonical name always has a label. */
+declare function modelDisplayLabel(row: {
+    common_name?: string | null;
+    name: string;
+}): string;
+declare function modelDisplayLabel(row: ModelLabelSource | null | undefined): string | undefined;
+
+/**
+ * `@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>;
+/** The bus client's subscribe call: `(action, handler) => unsubscribe` (the web's `registerDirectiveHandler`). */
+type ModelCatalogDirectiveSubscribe = (action: "catalog_changed", handler: (payload: ModelCatalogChangePayload) => void) => () => void;
+/** Is this notice about the MODEL catalog? (`catalog` absent or `"models"`; the tool catalog shares the action.) */
+declare function isModelCatalogChange(payload: ModelCatalogChangePayload | null | undefined): boolean;
+/** Listen for model catalog changes. Returns the unsubscribe. */
+declare function onModelCatalogChanged(listener: (payload: ModelCatalogChangePayload) => void): () => void;
+/** How many model catalog changes this page has seen (a React key / effect dependency). */
+declare function modelCatalogRevision(): number;
+/** Announce a model catalog change to every listener (a notice that is not about models is ignored). */
+declare function announceModelCatalogChanged(payload?: ModelCatalogChangePayload): void;
+/** Bind the host's bus client: every `catalog_changed` it delivers reaches every model reader. Returns the unbind. */
+declare function followModelCatalogChanges(subscribe: ModelCatalogDirectiveSubscribe): () => void;
+
+export { type AdminOffering, type AdminPricingBand, type ArtifactUse, type AuditCapabilitiesRecord, CHAT_DEFAULT_MODEL_KNOB, CONTENT_TYPES, type CapabilitiesParseContext, type CatalogKeyColumn, type CatalogKindInput, type CatalogModel, type CatalogTier, type CheapestAdequateOptions, type CompatStatus, type ContentType, type CuratedCatalogClient, type CuratedModel, type CuratedPresentation, type CuratedRows, type CuratedVariant, DEFAULT_CAPABILITIES, type DecidedBy, type DeviceGraphics, type DeviceHardware, type DiscoveryAmbiguity, type DiscoveryArtifact, type DiscoveryMedia, type DiscoveryResult, type DiscoveryRuntime, type DiscoverySource, type DiscoveryVariant, EMPTY_MODEL_RECORDS, EXCLUDED_REVIEW_STATES, FEATURE_BUCKETS, FEATURE_BUCKET_ORDER, FEATURE_KEYS, FILE_TYPE_QUANT, type FeatureBucket, type FeatureBucketMeta, type FeatureKey, type FitCapabilities, GgufError, type GgufHeader, type GgufRead, type GgufTensor, type GroupedFeatures, type HardwareClass, type HardwareClasses, type HeaderFlag, type HeaderJudgement, type HeaderRefusal, INPUT_MODALITIES, INTERACTION_MODES, type Interaction, type InteractionMode, type LocalArtifact, type LocalCatalogClient, type LocalCatalogQuery, type LocalCompatRow, type LocalModel, type LocalModelCatalog, type LocalPresentation, type LocalRuntime, type LocalRuntimeBuild, type LocalVariant, MAX_SUCCESSION_HOPS, MODEL_CATALOG_KINDS, MODEL_FAVORITE_ENTITY_TYPE, type Modality, type ModelCapabilities, type ModelCatalog, type ModelCatalogChangePayload, type ModelCatalogClient, type ModelCatalogConfig, type ModelCatalogDirectiveSubscribe, type ModelCatalogErrorSink, type ModelCatalogPgError, type ModelCatalogPgResult, type ModelCatalogQuery, type ModelCatalogState, type ModelCatalogVariant, type ModelCatalogVariantState, type ModelClassConfig, type ModelClassEntry, type ModelClassIndex, type ModelDiagnosticEntry, type ModelDiagnosticsSink, type ModelFavorites, type ModelFavoritesCache, type ModelFavoritesClient, type ModelFavoritesConfig, type ModelFavoritesErrorSink, type ModelFavoritesState, type ModelFetchScope, type ModelFileHandle, type ModelFit, type ModelIdentityRow, type ModelJson, type ModelLabelSource, type ModelNeed, type ModelOfferingRow, type ModelOption, type ModelOptionWithLifecycle, type ModelRecord, type ModelRecordFetchType, type ModelRecords, type ModelRecordsClient, type ModelRecordsConfig, type ModelRecordsState, type ModelSelectionPurpose, type ModelSetEnv, type ModelSetFacts, type ModelSetValidation, NEW_AGENT_DEFAULT_MODEL_KNOB, type NewAgentModel, type NoSelection, OUTPUT_MODALITIES, type OrderedLike, type PreferredModelChoice, type PreferredModelChoicePorts, type PriceTier, type PricedCatalogModel, type PublicModelClient, type RankOptions, type RankedVariant, type ReadModelCatalogOptions, SERVICE_LABEL, SERVICE_LABEL_PLURAL, type SelectDevice, type Selection, type ShardName, type SuccessionClient, type SuccessionIndex, type SuccessionNode, TOP_TIER_COST_RATING, TOP_TIER_LOCKED_TITLE, type VariantDiscovery, type VariantVerdict, type Want, acceptsTextInstructions, announceModelCatalogChanged, blendedPrice, buildModelClassIndex, buildSuccessionIndex, catalogFingerprint, catalogForApp, catalogKeyColumn, catalogKindOf, cheapestAdequateModel, classConfigKey, collapseTiersByClass, costRatingTier, costRatingWord, createModelCatalog, createModelFavorites, createModelRecords, curatedList, displayOrderOf, favoriteIdsEqual, fetchCuratedModels, findNonCanonicalCapabilityValues, fitsMemory, fitsNeed, fitsThisComputer, followModelCatalogChanges, formatMemoryBytes, fromDiscovery, ggufEngine, ggufFacts, groupFeatures, hardwareClassesOf, hasCompatibleDecisionInteraction, isChatModelCapability, isContentType, isConversationalModelCapability, isDecisionModelCapability, isFeatureKey, isHelperGguf, isInteractionMode, isListedVariant, isLocalModelCatalog, isManagedAgentModelCapability, isModelCatalogChange, isProjectorName, isSupersedable, isTopTierRating, judgeHeaderFacts, mergeAuditRecordIntoCapabilities, missingShards, modelCatalogRevision, modelClassKnobFor, modelClassName, modelClassPinOf, modelDisplayLabel, modelsForSelectionPurpose, normalizeArch, normalizeModel, normalizeModels, normalizeOs, normalizePromptSettings, onModelCatalogChanged, orderCatalogGroups, orderCatalogModels, outputFormatControlKey, parseCapabilities, pickProjector, priceTierRating, quantFromName, rankVariants, readCuratedRows, readGgufHeader, readModelCatalog, readModelIdentities, readPublicModel, reconcileModelFavoriteIds, reportModelDiagnostic, requireCanonicalCapabilities, requiredArtifacts, resetSuccessionLogForTests, resolveLiveModelId, resolveModelMapKnob, resolveNewAgentModelId, resolvePreferredModelChoice, resolveSuccessor, runtimesOnEngine, seesImages, selectActiveModels, selectActiveModelsReady, selectAllModelOptions, selectAllModels, selectAllModelsReady, selectDeprecatedModels, selectDeprecatedModelsReady, selectModelById, selectModelClassConfig, selectModelClassName, selectModelControls, selectModelDetailError, selectModelFetchType, selectModelFullyLoaded, selectModelIdentityById, selectModelIdentityLookupStatus, selectModelLabelById, selectModelLabelWithClass, selectModelNameById, selectModelOptions, selectVariant, serviceCountLabel, setModelDiagnosticsSink, shapeCuratedModels, shardFileName, shardName, speedRatingLabel, speedRatingWord, splitSetProblems, takesInput, toAuditRecord, validateModelSet, variantVerdict, withModelClass };

package/dist/models/index.js

@@ -759,6 +759,48 @@ var OUTPUT_MODALITIES = [
   "decision"
 ];
 
+// models/catalog/changes.ts
+var KEY2 = /* @__PURE__ */ Symbol.for("ai-matrx.agents.model-catalog-changes");
+function hub() {
+  const g = globalThis;
+  return g[KEY2] ??= { listeners: /* @__PURE__ */ new Set(), revision: 0 };
+}
+function isModelCatalogChange(payload) {
+  const catalog = payload?.["catalog"];
+  return catalog === void 0 || catalog === null || catalog === "models";
+}
+function onModelCatalogChanged(listener) {
+  const h = hub();
+  h.listeners.add(listener);
+  return () => {
+    h.listeners.delete(listener);
+  };
+}
+function modelCatalogRevision() {
+  return hub().revision;
+}
+function announceModelCatalogChanged(payload = {}) {
+  if (!isModelCatalogChange(payload)) return;
+  const h = hub();
+  h.revision += 1;
+  for (const l of [...h.listeners]) {
+    try {
+      l(payload);
+    } catch (err) {
+      console.error("[@ai-matrx/agents/models] a catalog_changed listener threw", err);
+    }
+  }
+}
+function followModelCatalogChanges(subscribe) {
+  return subscribe("catalog_changed", (payload) => announceModelCatalogChanged(payload ?? {}));
+}
+
+// models/label.ts
+function modelDisplayLabel(row) {
+  if (!row) return void 0;
+  return row.common_name || row.name || void 0;
+}
+
 // models/catalog/records.ts
 var classConfigKey = (modelId, offeringId) => `${modelId}:${offeringId}`;
 var EMPTY_MODEL_RECORDS = Object.freeze({
@@ -827,7 +869,7 @@ function withIdLists(state2) {
   const active = [];
   const deprecated = [];
   for (const [id, record] of Object.entries(state2.entities)) (record.is_deprecated === true ? deprecated : active).push(id);
-  const label = (id) => state2.entities[id]?.common_name ?? state2.entities[id]?.name ?? "";
+  const label = (id) => modelDisplayLabel(state2.entities[id]) ?? "";
   const sort = (ids) => ids.sort((a, b) => label(a).localeCompare(label(b)));
   return { ...state2, activeIds: sort(active), deprecatedIds: sort(deprecated) };
 }
@@ -1248,13 +1290,13 @@ function selectDeprecatedModels(s3) {
 var allOf = memo((entities) => Object.values(entities));
 var selectAllModels = (s3) => allOf(s3.entities);
 var optionsOf = memo(
-  (models) => models.map((m) => ({ value: m.id, label: m.common_name || m.name || m.id, maker: m.maker, costRating: m.cost_rating, speedRating: m.speed_rating }))
+  (models) => models.map((m) => ({ value: m.id, label: modelDisplayLabel(m) || m.id, maker: m.maker, costRating: m.cost_rating, speedRating: m.speed_rating }))
 );
 var selectModelOptions = (s3) => optionsOf(selectActiveModels(s3));
 var allOptionsOf = memo(
   (entities) => Object.values(entities).map((m) => ({
     value: m.id,
-    label: m.common_name || m.name || m.id,
+    label: modelDisplayLabel(m) || m.id,
     maker: m.maker,
     isDeprecated: m.is_deprecated ?? false,
     isRetired: m.retired_at != null,
@@ -1267,7 +1309,7 @@ function selectModelLabelById(s3, modelId) {
   if (!modelId) return void 0;
   const m = s3.entities[modelId];
   const identity = s3.identityById[modelId];
-  return m?.common_name || m?.name || identity?.common_name || identity?.name || void 0;
+  return modelDisplayLabel(m) || modelDisplayLabel(identity);
 }
 var selectModelNameById = (s3, modelId) => modelId ? s3.entities[modelId]?.name : void 0;
 var selectModelClassName = (s3, modelId, offeringId) => modelClassName(s3.modelClassIndex, modelId, offeringId);
@@ -1285,6 +1327,18 @@ var selectDeprecatedModelsReady = (s3) => (s3.fetchScope === "deprecated" || s3.
 var selectAllModelsReady = (s3) => s3.fetchScope === "all";
 var selectModelIdentityById = (s3, modelId) => s3.identityById[modelId];
 var selectModelIdentityLookupStatus = (s3, modelId) => s3.identityStatusById[modelId] ?? "idle";
+async function readModelIdentities(client, modelIds) {
+  const ids = [...new Set(modelIds.filter(Boolean))];
+  if (ids.length === 0) return [];
+  const { data, error } = await client.schema("ai").from("model_definition").select("id, name, common_name, is_deprecated").in("id", ids);
+  if (error) throw new Error(error.message);
+  return Array.isArray(data) ? data : [];
+}
+async function readPublicModel(client, key) {
+  const { data, error } = await client.schema("ai").from("model_public").select("id, name").eq(catalogKeyColumn(key), key.trim()).maybeSingle();
+  if (error) return { row: null, error: error.message };
+  return { row: data ?? null, error: null };
+}
 
 // models/catalog/store.ts
 var IDLE = { status: "idle", models: [], error: null, loadedAt: null };
@@ -1554,8 +1608,16 @@ function createModelCatalog(config) {
     errorSink,
     ...config.isSignedIn ? { isSignedIn: config.isSignedIn } : {}
   });
+  const refresh = async () => {
+    const variants = Object.keys(state2).filter((v) => state2[v].status !== "idle");
+    await Promise.all([records.refresh(), ...variants.map((v) => run(v))]);
+  };
+  const stopFollowing = config.followChanges === false ? () => {
+  } : onModelCatalogChanged(() => void refresh());
   return {
     records,
+    refresh,
+    dispose: stopFollowing,
     getState: () => state2,
     subscribe(listener) {
       listeners.add(listener);
@@ -2771,6 +2833,7 @@ export {
   TOP_TIER_COST_RATING,
   TOP_TIER_LOCKED_TITLE,
   acceptsTextInstructions,
+  announceModelCatalogChanged,
   blendedPrice,
   buildModelClassIndex,
   buildSuccessionIndex,
@@ -2794,6 +2857,7 @@ export {
   fitsMemory,
   fitsNeed,
   fitsThisComputer,
+  followModelCatalogChanges,
   formatMemoryBytes,
   fromDiscovery,
   ggufEngine,
@@ -2811,21 +2875,25 @@ export {
   isListedVariant,
   isLocalModelCatalog,
   isManagedAgentModelCapability,
+  isModelCatalogChange,
   isProjectorName,
   isSupersedable,
   isTopTierRating,
   judgeHeaderFacts,
   mergeAuditRecordIntoCapabilities,
   missingShards,
+  modelCatalogRevision,
   modelClassKnobFor,
   modelClassName,
   modelClassPinOf,
+  modelDisplayLabel,
   modelsForSelectionPurpose,
   normalizeArch,
   normalizeModel,
   normalizeModels,
   normalizeOs,
   normalizePromptSettings,
+  onModelCatalogChanged,
   orderCatalogGroups,
   orderCatalogModels,
   outputFormatControlKey,
@@ -2837,6 +2905,8 @@ export {
   readCuratedRows,
   readGgufHeader,
   readModelCatalog,
+  readModelIdentities,
+  readPublicModel,
   reconcileModelFavoriteIds,
   reportModelDiagnostic,
   requireCanonicalCapabilities,

package/dist/models/react/index.cjs

@@ -29,10 +29,12 @@ __export(react_exports, {
   useLocalModels: () => useLocalModels,
   useModelAccess: () => useModelAccess,
   useModelCatalog: () => useModelCatalog,
+  useModelCatalogRevision: () => useModelCatalogRevision,
   useModelCatalogStore: () => useModelCatalogStore,
   useModelCatalogUiPorts: () => useModelCatalogUiPorts,
   useModelFavorites: () => useModelFavorites,
-  useModelRecordsSelector: () => useModelRecordsSelector
+  useModelRecordsSelector: () => useModelRecordsSelector,
+  useOnModelCatalogChanged: () => useOnModelCatalogChanged
 });
 module.exports = __toCommonJS(react_exports);
 
@@ -2289,6 +2291,25 @@ function ModelListDropdown({
 
 // models/react/records.ts
 var import_react3 = require("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 (0, import_react3.useSyncExternalStore)(
     records.subscribe,
@@ -2296,6 +2317,15 @@ function useModelRecordsSelector(records, select) {
     () => select(records.getState())
   );
 }
+var subscribeRevision = (listener) => onModelCatalogChanged(() => listener());
+function useModelCatalogRevision() {
+  return (0, import_react3.useSyncExternalStore)(subscribeRevision, modelCatalogRevision, modelCatalogRevision);
+}
+function useOnModelCatalogChanged(onChange) {
+  const latest = (0, import_react3.useRef)(onChange);
+  latest.current = onChange;
+  (0, import_react3.useEffect)(() => onModelCatalogChanged((payload) => latest.current(payload)), []);
+}
 
 // models/react/ModelDiscovery.tsx
 var import_format3 = require("@ai-matrx/kit/format");

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-matrx/agents",
-  "version": "0.59.257",
+  "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"
@@ -509,11 +510,11 @@
   "sideEffects": false,
   "dependencies": {
     "@ai-matrx/alchemy": "latest",
+    "@ai-matrx/api": "latest",
     "@ai-matrx/associations": "latest",
     "@ai-matrx/content-ir": "latest",
-    "@ai-matrx/api": "latest",
-    "@ai-matrx/design-system": "latest",
     "@ai-matrx/data": "latest",
+    "@ai-matrx/design-system": "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": "0a2b8c9356bcba5cf0338a6c2c63b1c6058374ef"
+  "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).`);