@ai-matrx/agents 0.59.268 → 0.59.269

package/dist/models/index.d.cts

@@ -1106,7 +1106,15 @@ interface LocalModel {
     /** At least one variant is offered (Matrx 2 lists it). */
     offered?: boolean;
     /** The later of the model's and its presentation's updated_at: what an admin edit sends as expected_updated_at. */
-    updated_at?: string | null;
+    updated_at?: string | null; /**
+     * Set only when `readModelCatalog(client, { devices })` asked: the computers that hold every required file of
+     * one of this model's listed variants (models/device-models.ts `availableOnDevices`). Absent otherwise.
+     */
+    available_on?: Array<{
+        app_instance_id: string;
+        variant_id: string;
+        device_model_file_ids: string[];
+    }>;
 }
 interface LocalCompatRow {
     hardware_class: HardwareClass;
@@ -1595,13 +1603,13 @@ declare function orderCatalogGroups<T extends OrderedLike>(models: readonly T[],
  * one order (`orderCatalogModels` over ai.model_presentation.display_order). `curatedList` is the
  * only way a surface turns rows into its list, so two surfaces cannot drift apart.
  */
-type Row$1 = Record<string, unknown>;
+type Row$2 = Record<string, unknown>;
 /** A structural subset of `SupabaseClient` (only `schema().from().select()` is used). */
 interface CuratedCatalogClient {
     schema(name: string): {
         from(table: string): {
             select(columns: string): PromiseLike<{
-                data: Row$1[] | null;
+                data: Row$2[] | null;
                 error: {
                     message: string;
                 } | null;
@@ -1655,20 +1663,20 @@ interface CuratedModel {
  */
 declare const EXCLUDED_REVIEW_STATES: ReadonlySet<string>;
 /** Whether a variant row stays on the curated list (live, and not rejected or withdrawn). */
-declare const isListedVariant: (v: Row$1) => boolean;
+declare const isListedVariant: (v: Row$2) => boolean;
 /** The four raw ai.* reads the curated list is shaped from (live rows only; RLS applies). */
 interface CuratedRows {
-    models: Row$1[];
-    variants: Row$1[];
-    presentations: Row$1[];
-    providers: Row$1[];
+    models: Row$2[];
+    variants: Row$2[];
+    presentations: Row$2[];
+    providers: Row$2[];
 }
 /** Shape raw ai.* rows into the curated models (pure; the query below feeds it). Rejected and withdrawn variants are left out. */
 declare function shapeCuratedModels(input: {
-    models: Row$1[];
-    variants: Row$1[];
-    presentations: Row$1[];
-    providers: Row$1[];
+    models: Row$2[];
+    variants: Row$2[];
+    presentations: Row$2[];
+    providers: Row$2[];
 }): CuratedModel[];
 /** The four reads behind the curated list (live rows of ai.model_definition, model_variant, model_presentation, provider). */
 declare function readCuratedRows(client: CuratedCatalogClient): Promise<CuratedRows>;
@@ -1683,6 +1691,94 @@ declare function curatedList<T extends CuratedModel>(models: readonly T[], { off
     offeredOnly: boolean;
 }): T[];
 
+/**
+ * `@ai-matrx/agents/models` — WHICH COMPUTER HOLDS WHICH CATALOG MODEL. A local model is ONE catalog row
+ * (ai.model_definition / model_variant / model_artifact); there are no per-device catalog rows. Placement
+ * lives in ai.device_model_file (one row per model file a computer found, `artifact_id` → ai.model_artifact).
+ * `readModelCatalog(client, { devices })` and `resolveDeviceModel` (catalog-reader.ts) read it through here.
+ *
+ * The rules (mirrored by the server's device provider; FEATURE.md § Device-served models):
+ *   - a file counts only when it is not deleted and its `state` is in DEVICE_FILE_USABLE_STATES;
+ *   - a variant is available on a computer only when EVERY required artifact of it has a usable file there.
+ *     Required = the artifacts whose `required_for` holds `core` (the same set `requiredArtifacts(v, [])`
+ *     fetches); a variant with no `core` artifact requires all of its artifacts; a variant with no artifact
+ *     is never available. Optional files (an mmproj, `required_for: ["vision"]`) never block it, and are
+ *     listed in `device_model_file_ids` when present.
+ */
+type Row$1 = Record<string, unknown>;
+/** How a device-served run says it is served: run settings `{ served_via: "device", … }`. */
+declare const DEVICE_SERVED_VIA: "device";
+/**
+ * The ai.device_model_file states whose catalog file can be loaded (the column holds present, missing,
+ * corrupt, unmatched, hashing, unverified_match). Only `present` is a verified copy of the catalog artifact;
+ * `unverified_match` is a same-size file whose hash is not proven, `hashing` is not finished.
+ */
+declare const DEVICE_FILE_USABLE_STATES: readonly string[];
+/**
+ * The states in which a person's OWN file (artifact_id null: no catalog artifact) can be loaded: it is on
+ * disk with its content known. Matrx 2 records a scanned file that matches no catalog artifact as `unmatched`.
+ */
+declare const DEVICE_OWN_FILE_USABLE_STATES: readonly string[];
+/** One computer that holds every required file of one variant. */
+interface DeviceAvailability {
+    app_instance_id: string;
+    variant_id: string;
+    /** The usable ai.device_model_file ids of this variant on that computer (required and optional), in artifact order. */
+    device_model_file_ids: string[];
+}
+/** The run settings of a device-served model. There is no ai.provider row and no pricing row: the ledger counts 0 points. */
+interface DeviceServedSettings {
+    served_via: typeof DEVICE_SERVED_VIA;
+    /** The computer (public.app_instances.id). */
+    app_instance_id: string;
+    /** ai.model_definition.id, or an ai.device_model_file.id (artifact_id null) for a person's own model. */
+    local_model_id: string;
+    /** ai.model_variant.id; absent = the device's best available variant (default first, then selection_rank). */
+    variant_id?: string;
+}
+/** One ai.device_model_file row, as the reader returns it. */
+interface DeviceModelFile {
+    id: string;
+    app_instance_id: string;
+    root_id: string;
+    /** Null when the person does not share folder paths (the path stays in the computer's local store). */
+    rel_path: string | null;
+    size_bytes: number | null;
+    sha256: string | null;
+    artifact_id: string | null;
+    state: string;
+    organization_id: string | null;
+}
+declare function toDeviceModelFile(r: Row$1): DeviceModelFile;
+/**
+ * THE ai.device_model_file read: live rows in `states`, on the given computers (all the caller can see when
+ * omitted; RLS keeps it to the person's own). A failed read throws, naming the table.
+ */
+declare function readDeviceModelFiles(client: unknown, opts?: {
+    appInstanceIds?: readonly string[];
+    states?: readonly string[];
+}): Promise<DeviceModelFile[]>;
+/** A variant's artifacts as the availability rule reads them (raw ai.model_artifact ids). */
+interface AvailabilityVariant {
+    id: string;
+    artifacts: ReadonlyArray<{
+        id: string;
+        required_for: readonly string[];
+    }>;
+}
+/** The artifacts a computer must hold for the variant to be available: `core`, or all when none is `core`. */
+declare function requiredArtifactIds(v: AvailabilityVariant): string[];
+/**
+ * Pure: for each variant, the computers that hold every required artifact of it (DEVICE_FILE_USABLE_STATES
+ * files only; others are ignored). Computers in code-point order.
+ */
+declare function availableOnDevices(variants: readonly AvailabilityVariant[], files: readonly DeviceModelFile[]): Map<string, DeviceAvailability[]>;
+/** A device-model request the device cannot serve. `code` says why; the message names the model and computer. */
+declare class DeviceModelUnavailableError extends Error {
+    readonly code: "not_on_device" | "unknown_model" | "unknown_variant" | "file_not_usable" | "not_own_file";
+    constructor(code: DeviceModelUnavailableError["code"], message: string);
+}
+
 /**
  * `@ai-matrx/agents/models` — THE model-catalog reader. Every surface that shows the downloadable-model
  * catalog (AI Matrx admin › Applications › Catalogs, Matrx 2 › Models, any later client) reads it here,
@@ -1725,6 +1821,13 @@ interface LocalCatalogClient {
 interface ReadModelCatalogOptions {
     /** Apps (default true): only offered models and their offered variants. The admin page passes false. */
     offeredOnly?: boolean;
+    /**
+     * Also read ai.device_model_file and give each model `available_on` (default off: output unchanged).
+     * `true` = every computer the caller can see; `{ appInstanceIds }` = only those computers.
+     */
+    devices?: boolean | {
+        appInstanceIds?: readonly string[];
+    };
 }
 /** The catalog kinds whose rows live in the unified catalog (ai.*): the admin Catalogs page's model kinds. */
 declare const MODEL_CATALOG_KINDS: ReadonlySet<string>;
@@ -1757,6 +1860,29 @@ declare function catalogFingerprint(catalog: LocalModelCatalog): string;
  * by what they do and is said in `warnings`.
  */
 declare function readModelCatalog(client: CuratedCatalogClient, opts?: ReadModelCatalogOptions): Promise<LocalModelCatalog>;
+/** What `resolveDeviceModel` returns: a catalog model to load from the device's files, or a person's own file. */
+type DeviceModelResolution = {
+    own: false;
+    model: LocalModel;
+    variant: LocalVariant;
+    files: DeviceModelFile[];
+} | {
+    own: true;
+    file: DeviceModelFile;
+};
+/**
+ * THE device-served model lookup (the client's local chat and the server's device provider both use it;
+ * FEATURE.md § Device-served models). `local_model_id` is an ai.model_definition.id, or an
+ * ai.device_model_file.id with no artifact (a person's own model, `{ own: true, file }`). Returns the catalog
+ * model, the variant (`variant_id`, else the device's default-then-best-ranked available one) and the
+ * device's file rows to load. Refuses with DeviceModelUnavailableError, by name, when the device does not
+ * hold it. Reads listed variants (offeredOnly false): a model on the computer runs even after it is unoffered.
+ */
+declare function resolveDeviceModel(client: CuratedCatalogClient, req: {
+    app_instance_id: string;
+    local_model_id: string;
+    variant_id?: string;
+}): Promise<DeviceModelResolution>;
 
 /**
  * `@ai-matrx/agents/models` — THE fit rules: what a model can do for a purpose, read from the
@@ -1914,5 +2040,5 @@ declare function announceModelCatalogChanged(payload?: ModelCatalogChangePayload
 /** 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 { CHAT_DEFAULT_MODEL_KNOB, CONTENT_TYPES, DEFAULT_CAPABILITIES, EMPTY_MODEL_RECORDS, EXCLUDED_REVIEW_STATES, FEATURE_BUCKETS, FEATURE_BUCKET_ORDER, FEATURE_KEYS, FILE_TYPE_QUANT, GgufError, INPUT_MODALITIES, INTERACTION_MODES, MAX_SUCCESSION_HOPS, MODEL_CATALOG_KINDS, MODEL_FAVORITE_ENTITY_TYPE, NEW_AGENT_DEFAULT_MODEL_KNOB, OUTPUT_MODALITIES, SERVICE_LABEL, SERVICE_LABEL_PLURAL, TOP_TIER_COST_RATING, TOP_TIER_LOCKED_TITLE, 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 };
-export type { AdminOffering, AdminPricingBand, ArtifactUse, AuditCapabilitiesRecord, CapabilitiesParseContext, CatalogKeyColumn, CatalogKindInput, CatalogModel, CatalogTier, CheapestAdequateOptions, CompatStatus, ContentType, CuratedCatalogClient, CuratedModel, CuratedPresentation, CuratedRows, CuratedVariant, DecidedBy, DeviceGraphics, DeviceHardware, DiscoveryAmbiguity, DiscoveryArtifact, DiscoveryMedia, DiscoveryResult, DiscoveryRuntime, DiscoverySource, DiscoveryVariant, FeatureBucket, FeatureBucketMeta, FeatureKey, FitCapabilities, GgufHeader, GgufRead, GgufTensor, GroupedFeatures, HardwareClass, HardwareClasses, HeaderFlag, HeaderJudgement, HeaderRefusal, Interaction, InteractionMode, LocalArtifact, LocalCatalogClient, LocalCatalogQuery, LocalCompatRow, LocalModel, LocalModelCatalog, LocalPresentation, LocalRuntime, LocalRuntimeBuild, LocalVariant, Modality, ModelCapabilities, ModelCatalog, ModelCatalogChangePayload, ModelCatalogClient, ModelCatalogConfig, ModelCatalogDirectiveSubscribe, ModelCatalogErrorSink, ModelCatalogPgError, ModelCatalogPgResult, ModelCatalogQuery, ModelCatalogState, ModelCatalogVariant, ModelCatalogVariantState, ModelClassConfig, ModelClassEntry, ModelClassIndex, ModelDiagnosticEntry, ModelDiagnosticsSink, ModelFavorites, ModelFavoritesCache, ModelFavoritesClient, ModelFavoritesConfig, ModelFavoritesErrorSink, ModelFavoritesState, ModelFetchScope, ModelFileHandle, ModelFit, ModelIdentityRow, ModelJson, ModelLabelSource, ModelNeed, ModelOfferingRow, ModelOption, ModelOptionWithLifecycle, ModelRecord, ModelRecordFetchType, ModelRecords, ModelRecordsClient, ModelRecordsConfig, ModelRecordsState, ModelSelectionPurpose, ModelSetEnv, ModelSetFacts, ModelSetValidation, NewAgentModel, NoSelection, OrderedLike, PreferredModelChoice, PreferredModelChoicePorts, PriceTier, PricedCatalogModel, PublicModelClient, RankOptions, RankedVariant, ReadModelCatalogOptions, SelectDevice, Selection, ShardName, SuccessionClient, SuccessionIndex, SuccessionNode, VariantDiscovery, VariantVerdict, Want };
+export { CHAT_DEFAULT_MODEL_KNOB, CONTENT_TYPES, DEFAULT_CAPABILITIES, DEVICE_FILE_USABLE_STATES, DEVICE_OWN_FILE_USABLE_STATES, DEVICE_SERVED_VIA, DeviceModelUnavailableError, EMPTY_MODEL_RECORDS, EXCLUDED_REVIEW_STATES, FEATURE_BUCKETS, FEATURE_BUCKET_ORDER, FEATURE_KEYS, FILE_TYPE_QUANT, GgufError, INPUT_MODALITIES, INTERACTION_MODES, MAX_SUCCESSION_HOPS, MODEL_CATALOG_KINDS, MODEL_FAVORITE_ENTITY_TYPE, NEW_AGENT_DEFAULT_MODEL_KNOB, OUTPUT_MODALITIES, SERVICE_LABEL, SERVICE_LABEL_PLURAL, TOP_TIER_COST_RATING, TOP_TIER_LOCKED_TITLE, acceptsTextInstructions, announceModelCatalogChanged, availableOnDevices, 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, readDeviceModelFiles, readGgufHeader, readModelCatalog, readModelIdentities, readPublicModel, reconcileModelFavoriteIds, reportModelDiagnostic, requireCanonicalCapabilities, requiredArtifactIds, requiredArtifacts, resetSuccessionLogForTests, resolveDeviceModel, 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, toDeviceModelFile, validateModelSet, variantVerdict, withModelClass };
+export type { AdminOffering, AdminPricingBand, ArtifactUse, AuditCapabilitiesRecord, AvailabilityVariant, CapabilitiesParseContext, CatalogKeyColumn, CatalogKindInput, CatalogModel, CatalogTier, CheapestAdequateOptions, CompatStatus, ContentType, CuratedCatalogClient, CuratedModel, CuratedPresentation, CuratedRows, CuratedVariant, DecidedBy, DeviceAvailability, DeviceGraphics, DeviceHardware, DeviceModelFile, DeviceModelResolution, DeviceServedSettings, DiscoveryAmbiguity, DiscoveryArtifact, DiscoveryMedia, DiscoveryResult, DiscoveryRuntime, DiscoverySource, DiscoveryVariant, FeatureBucket, FeatureBucketMeta, FeatureKey, FitCapabilities, GgufHeader, GgufRead, GgufTensor, GroupedFeatures, HardwareClass, HardwareClasses, HeaderFlag, HeaderJudgement, HeaderRefusal, Interaction, InteractionMode, LocalArtifact, LocalCatalogClient, LocalCatalogQuery, LocalCompatRow, LocalModel, LocalModelCatalog, LocalPresentation, LocalRuntime, LocalRuntimeBuild, LocalVariant, Modality, ModelCapabilities, ModelCatalog, ModelCatalogChangePayload, ModelCatalogClient, ModelCatalogConfig, ModelCatalogDirectiveSubscribe, ModelCatalogErrorSink, ModelCatalogPgError, ModelCatalogPgResult, ModelCatalogQuery, ModelCatalogState, ModelCatalogVariant, ModelCatalogVariantState, ModelClassConfig, ModelClassEntry, ModelClassIndex, ModelDiagnosticEntry, ModelDiagnosticsSink, ModelFavorites, ModelFavoritesCache, ModelFavoritesClient, ModelFavoritesConfig, ModelFavoritesErrorSink, ModelFavoritesState, ModelFetchScope, ModelFileHandle, ModelFit, ModelIdentityRow, ModelJson, ModelLabelSource, ModelNeed, ModelOfferingRow, ModelOption, ModelOptionWithLifecycle, ModelRecord, ModelRecordFetchType, ModelRecords, ModelRecordsClient, ModelRecordsConfig, ModelRecordsState, ModelSelectionPurpose, ModelSetEnv, ModelSetFacts, ModelSetValidation, NewAgentModel, NoSelection, OrderedLike, PreferredModelChoice, PreferredModelChoicePorts, PriceTier, PricedCatalogModel, PublicModelClient, RankOptions, RankedVariant, ReadModelCatalogOptions, SelectDevice, Selection, ShardName, SuccessionClient, SuccessionIndex, SuccessionNode, VariantDiscovery, VariantVerdict, Want };

package/dist/models/index.d.ts

@@ -1106,7 +1106,15 @@ interface LocalModel {
     /** At least one variant is offered (Matrx 2 lists it). */
     offered?: boolean;
     /** The later of the model's and its presentation's updated_at: what an admin edit sends as expected_updated_at. */
-    updated_at?: string | null;
+    updated_at?: string | null; /**
+     * Set only when `readModelCatalog(client, { devices })` asked: the computers that hold every required file of
+     * one of this model's listed variants (models/device-models.ts `availableOnDevices`). Absent otherwise.
+     */
+    available_on?: Array<{
+        app_instance_id: string;
+        variant_id: string;
+        device_model_file_ids: string[];
+    }>;
 }
 interface LocalCompatRow {
     hardware_class: HardwareClass;
@@ -1595,13 +1603,13 @@ declare function orderCatalogGroups<T extends OrderedLike>(models: readonly T[],
  * one order (`orderCatalogModels` over ai.model_presentation.display_order). `curatedList` is the
  * only way a surface turns rows into its list, so two surfaces cannot drift apart.
  */
-type Row$1 = Record<string, unknown>;
+type Row$2 = Record<string, unknown>;
 /** A structural subset of `SupabaseClient` (only `schema().from().select()` is used). */
 interface CuratedCatalogClient {
     schema(name: string): {
         from(table: string): {
             select(columns: string): PromiseLike<{
-                data: Row$1[] | null;
+                data: Row$2[] | null;
                 error: {
                     message: string;
                 } | null;
@@ -1655,20 +1663,20 @@ interface CuratedModel {
  */
 declare const EXCLUDED_REVIEW_STATES: ReadonlySet<string>;
 /** Whether a variant row stays on the curated list (live, and not rejected or withdrawn). */
-declare const isListedVariant: (v: Row$1) => boolean;
+declare const isListedVariant: (v: Row$2) => boolean;
 /** The four raw ai.* reads the curated list is shaped from (live rows only; RLS applies). */
 interface CuratedRows {
-    models: Row$1[];
-    variants: Row$1[];
-    presentations: Row$1[];
-    providers: Row$1[];
+    models: Row$2[];
+    variants: Row$2[];
+    presentations: Row$2[];
+    providers: Row$2[];
 }
 /** Shape raw ai.* rows into the curated models (pure; the query below feeds it). Rejected and withdrawn variants are left out. */
 declare function shapeCuratedModels(input: {
-    models: Row$1[];
-    variants: Row$1[];
-    presentations: Row$1[];
-    providers: Row$1[];
+    models: Row$2[];
+    variants: Row$2[];
+    presentations: Row$2[];
+    providers: Row$2[];
 }): CuratedModel[];
 /** The four reads behind the curated list (live rows of ai.model_definition, model_variant, model_presentation, provider). */
 declare function readCuratedRows(client: CuratedCatalogClient): Promise<CuratedRows>;
@@ -1683,6 +1691,94 @@ declare function curatedList<T extends CuratedModel>(models: readonly T[], { off
     offeredOnly: boolean;
 }): T[];
 
+/**
+ * `@ai-matrx/agents/models` — WHICH COMPUTER HOLDS WHICH CATALOG MODEL. A local model is ONE catalog row
+ * (ai.model_definition / model_variant / model_artifact); there are no per-device catalog rows. Placement
+ * lives in ai.device_model_file (one row per model file a computer found, `artifact_id` → ai.model_artifact).
+ * `readModelCatalog(client, { devices })` and `resolveDeviceModel` (catalog-reader.ts) read it through here.
+ *
+ * The rules (mirrored by the server's device provider; FEATURE.md § Device-served models):
+ *   - a file counts only when it is not deleted and its `state` is in DEVICE_FILE_USABLE_STATES;
+ *   - a variant is available on a computer only when EVERY required artifact of it has a usable file there.
+ *     Required = the artifacts whose `required_for` holds `core` (the same set `requiredArtifacts(v, [])`
+ *     fetches); a variant with no `core` artifact requires all of its artifacts; a variant with no artifact
+ *     is never available. Optional files (an mmproj, `required_for: ["vision"]`) never block it, and are
+ *     listed in `device_model_file_ids` when present.
+ */
+type Row$1 = Record<string, unknown>;
+/** How a device-served run says it is served: run settings `{ served_via: "device", … }`. */
+declare const DEVICE_SERVED_VIA: "device";
+/**
+ * The ai.device_model_file states whose catalog file can be loaded (the column holds present, missing,
+ * corrupt, unmatched, hashing, unverified_match). Only `present` is a verified copy of the catalog artifact;
+ * `unverified_match` is a same-size file whose hash is not proven, `hashing` is not finished.
+ */
+declare const DEVICE_FILE_USABLE_STATES: readonly string[];
+/**
+ * The states in which a person's OWN file (artifact_id null: no catalog artifact) can be loaded: it is on
+ * disk with its content known. Matrx 2 records a scanned file that matches no catalog artifact as `unmatched`.
+ */
+declare const DEVICE_OWN_FILE_USABLE_STATES: readonly string[];
+/** One computer that holds every required file of one variant. */
+interface DeviceAvailability {
+    app_instance_id: string;
+    variant_id: string;
+    /** The usable ai.device_model_file ids of this variant on that computer (required and optional), in artifact order. */
+    device_model_file_ids: string[];
+}
+/** The run settings of a device-served model. There is no ai.provider row and no pricing row: the ledger counts 0 points. */
+interface DeviceServedSettings {
+    served_via: typeof DEVICE_SERVED_VIA;
+    /** The computer (public.app_instances.id). */
+    app_instance_id: string;
+    /** ai.model_definition.id, or an ai.device_model_file.id (artifact_id null) for a person's own model. */
+    local_model_id: string;
+    /** ai.model_variant.id; absent = the device's best available variant (default first, then selection_rank). */
+    variant_id?: string;
+}
+/** One ai.device_model_file row, as the reader returns it. */
+interface DeviceModelFile {
+    id: string;
+    app_instance_id: string;
+    root_id: string;
+    /** Null when the person does not share folder paths (the path stays in the computer's local store). */
+    rel_path: string | null;
+    size_bytes: number | null;
+    sha256: string | null;
+    artifact_id: string | null;
+    state: string;
+    organization_id: string | null;
+}
+declare function toDeviceModelFile(r: Row$1): DeviceModelFile;
+/**
+ * THE ai.device_model_file read: live rows in `states`, on the given computers (all the caller can see when
+ * omitted; RLS keeps it to the person's own). A failed read throws, naming the table.
+ */
+declare function readDeviceModelFiles(client: unknown, opts?: {
+    appInstanceIds?: readonly string[];
+    states?: readonly string[];
+}): Promise<DeviceModelFile[]>;
+/** A variant's artifacts as the availability rule reads them (raw ai.model_artifact ids). */
+interface AvailabilityVariant {
+    id: string;
+    artifacts: ReadonlyArray<{
+        id: string;
+        required_for: readonly string[];
+    }>;
+}
+/** The artifacts a computer must hold for the variant to be available: `core`, or all when none is `core`. */
+declare function requiredArtifactIds(v: AvailabilityVariant): string[];
+/**
+ * Pure: for each variant, the computers that hold every required artifact of it (DEVICE_FILE_USABLE_STATES
+ * files only; others are ignored). Computers in code-point order.
+ */
+declare function availableOnDevices(variants: readonly AvailabilityVariant[], files: readonly DeviceModelFile[]): Map<string, DeviceAvailability[]>;
+/** A device-model request the device cannot serve. `code` says why; the message names the model and computer. */
+declare class DeviceModelUnavailableError extends Error {
+    readonly code: "not_on_device" | "unknown_model" | "unknown_variant" | "file_not_usable" | "not_own_file";
+    constructor(code: DeviceModelUnavailableError["code"], message: string);
+}
+
 /**
  * `@ai-matrx/agents/models` — THE model-catalog reader. Every surface that shows the downloadable-model
  * catalog (AI Matrx admin › Applications › Catalogs, Matrx 2 › Models, any later client) reads it here,
@@ -1725,6 +1821,13 @@ interface LocalCatalogClient {
 interface ReadModelCatalogOptions {
     /** Apps (default true): only offered models and their offered variants. The admin page passes false. */
     offeredOnly?: boolean;
+    /**
+     * Also read ai.device_model_file and give each model `available_on` (default off: output unchanged).
+     * `true` = every computer the caller can see; `{ appInstanceIds }` = only those computers.
+     */
+    devices?: boolean | {
+        appInstanceIds?: readonly string[];
+    };
 }
 /** The catalog kinds whose rows live in the unified catalog (ai.*): the admin Catalogs page's model kinds. */
 declare const MODEL_CATALOG_KINDS: ReadonlySet<string>;
@@ -1757,6 +1860,29 @@ declare function catalogFingerprint(catalog: LocalModelCatalog): string;
  * by what they do and is said in `warnings`.
  */
 declare function readModelCatalog(client: CuratedCatalogClient, opts?: ReadModelCatalogOptions): Promise<LocalModelCatalog>;
+/** What `resolveDeviceModel` returns: a catalog model to load from the device's files, or a person's own file. */
+type DeviceModelResolution = {
+    own: false;
+    model: LocalModel;
+    variant: LocalVariant;
+    files: DeviceModelFile[];
+} | {
+    own: true;
+    file: DeviceModelFile;
+};
+/**
+ * THE device-served model lookup (the client's local chat and the server's device provider both use it;
+ * FEATURE.md § Device-served models). `local_model_id` is an ai.model_definition.id, or an
+ * ai.device_model_file.id with no artifact (a person's own model, `{ own: true, file }`). Returns the catalog
+ * model, the variant (`variant_id`, else the device's default-then-best-ranked available one) and the
+ * device's file rows to load. Refuses with DeviceModelUnavailableError, by name, when the device does not
+ * hold it. Reads listed variants (offeredOnly false): a model on the computer runs even after it is unoffered.
+ */
+declare function resolveDeviceModel(client: CuratedCatalogClient, req: {
+    app_instance_id: string;
+    local_model_id: string;
+    variant_id?: string;
+}): Promise<DeviceModelResolution>;
 
 /**
  * `@ai-matrx/agents/models` — THE fit rules: what a model can do for a purpose, read from the
@@ -1914,5 +2040,5 @@ declare function announceModelCatalogChanged(payload?: ModelCatalogChangePayload
 /** 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 { CHAT_DEFAULT_MODEL_KNOB, CONTENT_TYPES, DEFAULT_CAPABILITIES, EMPTY_MODEL_RECORDS, EXCLUDED_REVIEW_STATES, FEATURE_BUCKETS, FEATURE_BUCKET_ORDER, FEATURE_KEYS, FILE_TYPE_QUANT, GgufError, INPUT_MODALITIES, INTERACTION_MODES, MAX_SUCCESSION_HOPS, MODEL_CATALOG_KINDS, MODEL_FAVORITE_ENTITY_TYPE, NEW_AGENT_DEFAULT_MODEL_KNOB, OUTPUT_MODALITIES, SERVICE_LABEL, SERVICE_LABEL_PLURAL, TOP_TIER_COST_RATING, TOP_TIER_LOCKED_TITLE, 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 };
-export type { AdminOffering, AdminPricingBand, ArtifactUse, AuditCapabilitiesRecord, CapabilitiesParseContext, CatalogKeyColumn, CatalogKindInput, CatalogModel, CatalogTier, CheapestAdequateOptions, CompatStatus, ContentType, CuratedCatalogClient, CuratedModel, CuratedPresentation, CuratedRows, CuratedVariant, DecidedBy, DeviceGraphics, DeviceHardware, DiscoveryAmbiguity, DiscoveryArtifact, DiscoveryMedia, DiscoveryResult, DiscoveryRuntime, DiscoverySource, DiscoveryVariant, FeatureBucket, FeatureBucketMeta, FeatureKey, FitCapabilities, GgufHeader, GgufRead, GgufTensor, GroupedFeatures, HardwareClass, HardwareClasses, HeaderFlag, HeaderJudgement, HeaderRefusal, Interaction, InteractionMode, LocalArtifact, LocalCatalogClient, LocalCatalogQuery, LocalCompatRow, LocalModel, LocalModelCatalog, LocalPresentation, LocalRuntime, LocalRuntimeBuild, LocalVariant, Modality, ModelCapabilities, ModelCatalog, ModelCatalogChangePayload, ModelCatalogClient, ModelCatalogConfig, ModelCatalogDirectiveSubscribe, ModelCatalogErrorSink, ModelCatalogPgError, ModelCatalogPgResult, ModelCatalogQuery, ModelCatalogState, ModelCatalogVariant, ModelCatalogVariantState, ModelClassConfig, ModelClassEntry, ModelClassIndex, ModelDiagnosticEntry, ModelDiagnosticsSink, ModelFavorites, ModelFavoritesCache, ModelFavoritesClient, ModelFavoritesConfig, ModelFavoritesErrorSink, ModelFavoritesState, ModelFetchScope, ModelFileHandle, ModelFit, ModelIdentityRow, ModelJson, ModelLabelSource, ModelNeed, ModelOfferingRow, ModelOption, ModelOptionWithLifecycle, ModelRecord, ModelRecordFetchType, ModelRecords, ModelRecordsClient, ModelRecordsConfig, ModelRecordsState, ModelSelectionPurpose, ModelSetEnv, ModelSetFacts, ModelSetValidation, NewAgentModel, NoSelection, OrderedLike, PreferredModelChoice, PreferredModelChoicePorts, PriceTier, PricedCatalogModel, PublicModelClient, RankOptions, RankedVariant, ReadModelCatalogOptions, SelectDevice, Selection, ShardName, SuccessionClient, SuccessionIndex, SuccessionNode, VariantDiscovery, VariantVerdict, Want };
+export { CHAT_DEFAULT_MODEL_KNOB, CONTENT_TYPES, DEFAULT_CAPABILITIES, DEVICE_FILE_USABLE_STATES, DEVICE_OWN_FILE_USABLE_STATES, DEVICE_SERVED_VIA, DeviceModelUnavailableError, EMPTY_MODEL_RECORDS, EXCLUDED_REVIEW_STATES, FEATURE_BUCKETS, FEATURE_BUCKET_ORDER, FEATURE_KEYS, FILE_TYPE_QUANT, GgufError, INPUT_MODALITIES, INTERACTION_MODES, MAX_SUCCESSION_HOPS, MODEL_CATALOG_KINDS, MODEL_FAVORITE_ENTITY_TYPE, NEW_AGENT_DEFAULT_MODEL_KNOB, OUTPUT_MODALITIES, SERVICE_LABEL, SERVICE_LABEL_PLURAL, TOP_TIER_COST_RATING, TOP_TIER_LOCKED_TITLE, acceptsTextInstructions, announceModelCatalogChanged, availableOnDevices, 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, readDeviceModelFiles, readGgufHeader, readModelCatalog, readModelIdentities, readPublicModel, reconcileModelFavoriteIds, reportModelDiagnostic, requireCanonicalCapabilities, requiredArtifactIds, requiredArtifacts, resetSuccessionLogForTests, resolveDeviceModel, 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, toDeviceModelFile, validateModelSet, variantVerdict, withModelClass };
+export type { AdminOffering, AdminPricingBand, ArtifactUse, AuditCapabilitiesRecord, AvailabilityVariant, CapabilitiesParseContext, CatalogKeyColumn, CatalogKindInput, CatalogModel, CatalogTier, CheapestAdequateOptions, CompatStatus, ContentType, CuratedCatalogClient, CuratedModel, CuratedPresentation, CuratedRows, CuratedVariant, DecidedBy, DeviceAvailability, DeviceGraphics, DeviceHardware, DeviceModelFile, DeviceModelResolution, DeviceServedSettings, DiscoveryAmbiguity, DiscoveryArtifact, DiscoveryMedia, DiscoveryResult, DiscoveryRuntime, DiscoverySource, DiscoveryVariant, FeatureBucket, FeatureBucketMeta, FeatureKey, FitCapabilities, GgufHeader, GgufRead, GgufTensor, GroupedFeatures, HardwareClass, HardwareClasses, HeaderFlag, HeaderJudgement, HeaderRefusal, Interaction, InteractionMode, LocalArtifact, LocalCatalogClient, LocalCatalogQuery, LocalCompatRow, LocalModel, LocalModelCatalog, LocalPresentation, LocalRuntime, LocalRuntimeBuild, LocalVariant, Modality, ModelCapabilities, ModelCatalog, ModelCatalogChangePayload, ModelCatalogClient, ModelCatalogConfig, ModelCatalogDirectiveSubscribe, ModelCatalogErrorSink, ModelCatalogPgError, ModelCatalogPgResult, ModelCatalogQuery, ModelCatalogState, ModelCatalogVariant, ModelCatalogVariantState, ModelClassConfig, ModelClassEntry, ModelClassIndex, ModelDiagnosticEntry, ModelDiagnosticsSink, ModelFavorites, ModelFavoritesCache, ModelFavoritesClient, ModelFavoritesConfig, ModelFavoritesErrorSink, ModelFavoritesState, ModelFetchScope, ModelFileHandle, ModelFit, ModelIdentityRow, ModelJson, ModelLabelSource, ModelNeed, ModelOfferingRow, ModelOption, ModelOptionWithLifecycle, ModelRecord, ModelRecordFetchType, ModelRecords, ModelRecordsClient, ModelRecordsConfig, ModelRecordsState, ModelSelectionPurpose, ModelSetEnv, ModelSetFacts, ModelSetValidation, NewAgentModel, NoSelection, OrderedLike, PreferredModelChoice, PreferredModelChoicePorts, PriceTier, PricedCatalogModel, PublicModelClient, RankOptions, RankedVariant, ReadModelCatalogOptions, SelectDevice, Selection, ShardName, SuccessionClient, SuccessionIndex, SuccessionNode, VariantDiscovery, VariantVerdict, Want };