@camstack/system 1.2.364 → 1.2.366

package/dist/{dist-DiScyAO6.js → dist-ub3muPSW.js}

@@ -7917,16 +7917,53 @@ var ModelFormatEntrySchema = zod.z.object({
 	/** Runtime(s) that can use this format. If omitted, inferred from ModelFormat key */
 	runtimes: zod.z.array(zod.z.enum(["python"])).readonly().optional(),
 	/**
-	* Content revision of the hosted artefact. Set it, or change it, whenever
-	* the bytes at `url` are replaced in place (same path, new content). A node
-	* records the revision it downloaded next to the file
+	* Content revision of the artefact, for one hosted OFF the CamStack mirror.
+	* A format on the mirror leaves it unset: its revision (the sha256 of its
+	* weight file) comes from the downloader's generated table, kept in step
+	* with the mirror by `scripts/check-hosted-model-revisions.ts` (D744). A
+	* node records the revision it downloaded next to the file
 	* (`<file>.revision`); a copy with no record or a different one is stale
-	* and is downloaded again, the old copy serving until the new one is
-	* complete. Omitted ⇒ a file on disk is current, whatever it holds (D743).
+	* unless its weight file hashes to the revision, and a stale copy is
+	* downloaded again, the old one serving until the new one is complete. No
+	* revision at all ⇒ a file on disk is current, whatever it holds (D743).
 	*/
 	revision: zod.z.string().min(1).optional()
 });
 /**
+* What a node holds for one (model, format) (D746). `current` is a complete
+* copy at its catalog revision — exactly what `downloaded: true` means.
+* `stale` is bytes on disk that are not (yet) proven current under D743/D744:
+* no or a different revision record, or a missing sibling. `missing` is no
+* copy. `downloaded` alone folds `stale` into "not downloaded", which hid
+* reclaimable bytes and a copy about to be replaced.
+*/
+var ModelOnDiskStateSchema = zod.z.enum([
+	"current",
+	"stale",
+	"missing"
+]);
+/**
+* The numeric precision of one format's BUILD (D746) — reported only when the
+* build states it (file-name token, an INT8 variant, an EdgeTPU compile, a
+* CamStack Core ML export). Absent means "not stated", never "fp32".
+*/
+var ModelFormatPrecisionSchema = zod.z.enum([
+	"fp32",
+	"fp16",
+	"int8"
+]);
+/**
+* One format of one model as a node's `pipelineExecutor.getSchema` reports it.
+* `onDisk` / `precision` are optional for version skew: a runner that predates
+* them omits them, and a reader falls back to `downloaded`.
+*/
+var PipelineModelFormatStatusSchema = zod.z.object({
+	downloaded: zod.z.boolean(),
+	sizeMB: zod.z.number(),
+	onDisk: ModelOnDiskStateSchema.optional(),
+	precision: ModelFormatPrecisionSchema.optional()
+});
+/**
 * Extra file that must be downloaded alongside the model (e.g., labels JSON, dict.txt).
 * The downloader fetches from `url` and saves to `{modelsDir}/{filename}`.
 */
@@ -25966,7 +26003,7 @@ var FrameRefSchema = zod.z.object({
 	timestamp: zod.z.number(),
 	capturedAt: zod.z.number().optional()
 });
-var ModelFormatSchema$1 = zod.z.enum([
+var ModelFormatSchema$2 = zod.z.enum([
 	"onnx",
 	"coreml",
 	"openvino",
@@ -25984,7 +26021,7 @@ var PipelineSlotSchema = zod.z.enum([
 var PipelineEngineChoiceSchema = zod.z.object({
 	runtime: zod.z.literal("python"),
 	backend: zod.z.string(),
-	format: ModelFormatSchema$1,
+	format: ModelFormatSchema$2,
 	device: zod.z.string().optional()
 });
 /**
@@ -26042,10 +26079,7 @@ var PipelineTemplateSchema$1 = zod.z.object({
 var PipelineModelOptionSchema = zod.z.object({
 	id: zod.z.string(),
 	name: zod.z.string(),
-	formats: zod.z.record(zod.z.string(), zod.z.object({
-		downloaded: zod.z.boolean(),
-		sizeMB: zod.z.number()
-	})),
+	formats: zod.z.record(zod.z.string(), PipelineModelFormatStatusSchema),
 	group: ModelVariantGroupSchema.optional(),
 	legacy: zod.z.boolean().optional(),
 	provider: ModelProviderIdSchema.optional(),
@@ -26260,6 +26294,32 @@ var pipelineExecutorCapability = {
 			auth: "admin"
 		}),
 		/**
+		* Best settings (D745): the MODEL-BOUND thresholds (`bindsToModel` keys of
+		* the object-detection root, and their binding keys) stored in THIS node's
+		* per-camera detector settings — and, unless `dryRun`, remove them so the
+		* running model's own defaults apply. Every other key of a camera's store
+		* is kept. `nodeId` is the ROUTING key. `deviceIds` absent ⇒ every camera
+		* with a store. A camera whose store could not be read is `refused`, never
+		* reported as clean.
+		*/
+		clearModelBoundDeviceOverrides: method(zod.z.object({
+			nodeId: zod.z.string(),
+			deviceIds: zod.z.array(zod.z.number()).readonly().optional(),
+			dryRun: zod.z.boolean()
+		}), zod.z.object({
+			entries: zod.z.array(zod.z.object({
+				deviceId: zod.z.number(),
+				keys: zod.z.array(zod.z.string()).readonly()
+			})).readonly(),
+			refused: zod.z.array(zod.z.object({
+				deviceId: zod.z.number(),
+				reason: zod.z.string()
+			})).readonly()
+		}), {
+			kind: "mutation",
+			auth: "admin"
+		}),
+		/**
 		* Which of THIS node's inference devices the executor currently refuses,
 		* and why. `nodeId` is the ROUTING key (stripped by the generated router).
 		*
@@ -26354,12 +26414,12 @@ var pipelineExecutorCapability = {
 		downloadModel: method(zod.z.object({
 			addonId: zod.z.string(),
 			modelId: zod.z.string(),
-			format: ModelFormatSchema$1
+			format: ModelFormatSchema$2
 		}), DownloadModelResultSchema, { kind: "mutation" }),
 		deleteModel: method(zod.z.object({
 			addonId: zod.z.string(),
 			modelId: zod.z.string(),
-			format: ModelFormatSchema$1
+			format: ModelFormatSchema$2
 		}), zod.z.object({ success: zod.z.literal(true) }), { kind: "mutation" }),
 		/**
 		* Stateless single-frame execution. Callers (runner, benchmark) pass
@@ -26605,6 +26665,204 @@ var pipelineExecutorCapability = {
 		getDetectionConfigSchema: method(zod.z.void(), ConfigUISchemaNullableBridge)
 	}
 };
+/**
+* The wire shapes of the Best settings plan and apply (D745), used by the
+* `pipeline-orchestrator` cap. The recommender's own types
+* (`recommend.ts`, `demand.ts`) are the TS face of the same data; these
+* schemas are what crosses the cap boundary.
+*/
+var ModelFormatSchema$1 = zod.z.enum(MODEL_FORMATS);
+var HardwareClassIdSchema = zod.z.enum([
+	"intel-core-ultra",
+	"intel-n-series",
+	"apple-m-base",
+	"apple-m-pro",
+	"unknown"
+]);
+var AcceleratorKindSchema = zod.z.enum([
+	"intel-npu",
+	"intel-igpu",
+	"x86-cpu",
+	"arm-cpu",
+	"apple-ane",
+	"coral"
+]);
+var RecommendationReasonSchema = zod.z.discriminatedUnion("kind", [
+	zod.z.object({
+		kind: zod.z.literal("fits"),
+		utilisation: zod.z.number()
+	}),
+	zod.z.object({
+		kind: zod.z.literal("tie-faster"),
+		over: zod.z.string(),
+		recallDelta: zod.z.number()
+	}),
+	zod.z.object({
+		kind: zod.z.literal("stepped-down"),
+		from: zod.z.string(),
+		to: zod.z.string(),
+		limitedBy: zod.z.string()
+	}),
+	zod.z.object({
+		kind: zod.z.literal("no-fit-lightest"),
+		utilisation: zod.z.number()
+	}),
+	zod.z.object({
+		kind: zod.z.literal("derived-latency"),
+		modelId: zod.z.string()
+	}),
+	zod.z.object({
+		kind: zod.z.literal("estimated-load"),
+		observedForMs: zod.z.number().nullable()
+	}),
+	zod.z.object({ kind: zod.z.literal("cpu-device") }),
+	zod.z.object({ kind: zod.z.literal("coral-untouched") }),
+	zod.z.object({ kind: zod.z.literal("device-disabled") }),
+	zod.z.object({ kind: zod.z.literal("device-unavailable") }),
+	zod.z.object({ kind: zod.z.literal("node-offline") }),
+	zod.z.object({ kind: zod.z.literal("no-hardware-facts") }),
+	zod.z.object({
+		kind: zod.z.literal("no-measured-data"),
+		hardwareClass: HardwareClassIdSchema
+	}),
+	zod.z.object({
+		kind: zod.z.literal("no-family-build"),
+		format: ModelFormatSchema$1
+	})
+]);
+var DeviceDemandSchema = zod.z.object({
+	nodeId: zod.z.string(),
+	deviceKey: zod.z.string(),
+	demandFps: zod.z.number(),
+	maxCameraFps: zod.z.number(),
+	alwaysOnCameras: zod.z.number(),
+	onMotionSessions: zod.z.number(),
+	onMotionSource: zod.z.enum([
+		"observed-24h",
+		"estimate",
+		"none"
+	]),
+	observedForMs: zod.z.number().nullable()
+});
+var DeviceModelChoiceSchema = zod.z.object({
+	modelId: zod.z.string(),
+	p50Ms: zod.z.number(),
+	fps: zod.z.number(),
+	measured: zod.z.boolean(),
+	utilisation: zod.z.number(),
+	personRecall: zod.z.number()
+});
+var DeviceRecommendationSchema = zod.z.object({
+	deviceKey: zod.z.string(),
+	accelerator: AcceleratorKindSchema.nullable(),
+	enabled: zod.z.boolean(),
+	available: zod.z.boolean(),
+	demand: DeviceDemandSchema.nullable(),
+	chosen: DeviceModelChoiceSchema.nullable(),
+	reasons: zod.z.array(RecommendationReasonSchema).readonly()
+});
+var NodeRecommendationSchema = zod.z.object({
+	nodeId: zod.z.string(),
+	reachable: zod.z.boolean(),
+	hardwareClass: HardwareClassIdSchema.nullable(),
+	cpuModel: zod.z.string().nullable(),
+	skipped: zod.z.boolean(),
+	acceleratorModelId: zod.z.string().nullable(),
+	devices: zod.z.array(DeviceRecommendationSchema).readonly(),
+	reasons: zod.z.array(RecommendationReasonSchema).readonly()
+});
+var ModelPinChangeSchema = zod.z.object({
+	stepId: zod.z.string(),
+	before: zod.z.string().nullable(),
+	after: zod.z.string().nullable()
+});
+var NodeDeviceChangeSchema = zod.z.object({
+	nodeId: zod.z.string(),
+	deviceKey: zod.z.string(),
+	madeExplicit: zod.z.boolean(),
+	modelPins: zod.z.array(ModelPinChangeSchema).readonly(),
+	thresholds: zod.z.array(zod.z.object({
+		stepId: zod.z.string(),
+		keys: zod.z.array(zod.z.string()).readonly()
+	})).readonly()
+});
+var CameraOverrideClearSchema = zod.z.object({
+	deviceId: zod.z.number(),
+	source: zod.z.enum(["step-override", "wholesale"]),
+	nodeId: zod.z.string(),
+	deviceKey: zod.z.string().nullable(),
+	stepId: zod.z.string(),
+	modelIdBefore: zod.z.string().nullable(),
+	keys: zod.z.array(zod.z.string()).readonly()
+});
+var DetectorStoreClearSchema = zod.z.object({
+	deviceId: zod.z.number(),
+	keys: zod.z.array(zod.z.string()).readonly()
+});
+var BestSettingsWarningSchema = zod.z.discriminatedUnion("kind", [
+	zod.z.object({
+		kind: zod.z.literal("detector-store-cluster-wide"),
+		skippedNodes: zod.z.array(zod.z.string()).readonly()
+	}),
+	zod.z.object({
+		kind: zod.z.literal("detector-store-unreadable"),
+		error: zod.z.string()
+	}),
+	zod.z.object({
+		kind: zod.z.literal("coral-enabled"),
+		nodeId: zod.z.string(),
+		deviceKey: zod.z.string()
+	})
+]);
+var BestSettingsOptionsSchema = zod.z.object({ 
+/** Share of each accelerator's throughput kept free (0.3–0.5). */
+headroom: zod.z.number().min(.3).max(.5).default(.4) });
+var BestSettingsPlanSchema = zod.z.object({
+	/** Hash of everything the apply will write — the apply refuses a different one. */
+	planHash: zod.z.string(),
+	family: zod.z.literal("yolov9"),
+	headroom: zod.z.number(),
+	generatedAt: zod.z.number(),
+	nodes: zod.z.array(NodeRecommendationSchema).readonly(),
+	nodeChanges: zod.z.array(NodeDeviceChangeSchema).readonly(),
+	cameraClears: zod.z.array(CameraOverrideClearSchema).readonly(),
+	detectorStoreClears: zod.z.array(DetectorStoreClearSchema).readonly(),
+	warnings: zod.z.array(BestSettingsWarningSchema).readonly()
+});
+var BestSettingsApplyInputSchema = zod.z.object({
+	planHash: zod.z.string(),
+	headroom: zod.z.number().min(.3).max(.5).default(.4)
+});
+var BestSettingsPhaseResultSchema = zod.z.object({
+	phase: zod.z.enum([
+		"download",
+		"camera-overrides",
+		"detector-thresholds",
+		"node-models",
+		"redispatch"
+	]),
+	ok: zod.z.boolean(),
+	detail: zod.z.string()
+});
+var BestSettingsApplyResultSchema = zod.z.discriminatedUnion("kind", [
+	zod.z.object({
+		kind: zod.z.literal("applied"),
+		planHash: zod.z.string(),
+		phases: zod.z.array(BestSettingsPhaseResultSchema).readonly()
+	}),
+	zod.z.object({
+		kind: zod.z.literal("aborted"),
+		phases: zod.z.array(BestSettingsPhaseResultSchema).readonly()
+	}),
+	zod.z.object({
+		kind: zod.z.literal("stale"),
+		plan: BestSettingsPlanSchema
+	}),
+	zod.z.object({
+		kind: zod.z.literal("refused"),
+		reason: zod.z.enum(["apply-in-progress"])
+	})
+]);
 zod.z.object({
 	activeCameras: zod.z.number(),
 	throttledCameras: zod.z.number(),
@@ -28825,6 +29083,27 @@ var pipelineOrchestratorCapability = {
 			kind: "mutation",
 			auth: "admin"
 		}),
+		/**
+		* Best settings (D745) — DRY RUN. Recommends ONE detector family (YOLOv9)
+		* for the whole cluster from each node's static hardware class, the
+		* measured latency table and the detection demand, and lists every write
+		* the apply would make: the node model pins set, the enrichment pins and
+		* model-bound thresholds removed (node level and per camera), and the
+		* per-camera detector thresholds cleared. Writes nothing. Step
+		* enablement, device enablement, pins, recording, notifications, zones and
+		* rules are never part of it. `planHash` names exactly this diff.
+		*/
+		planBestSettings: method(BestSettingsOptionsSchema, BestSettingsPlanSchema, { auth: "admin" }),
+		/**
+		* Best settings (D745) — APPLY the plan the operator confirmed. Recomputes
+		* the plan and refuses (`stale`, with the fresh plan) when its hash is not
+		* `planHash`, so what is written is exactly the confirmed diff. Offline
+		* nodes are skipped; there is no undo.
+		*/
+		applyBestSettings: method(BestSettingsApplyInputSchema, BestSettingsApplyResultSchema, {
+			kind: "mutation",
+			auth: "admin"
+		}),
 		/** Read one camera's settings. Null when never touched (inherits agent defaults fully). */
 		getCameraSettings: method(zod.z.object({ deviceId: zod.z.number() }), CameraPipelineSettingsSchema.nullable()),
 		/** Set or clear the 3-state toggle for one (camera, addonId). Pass `enabled: null` to clear and revert to agent default. */
@@ -45922,6 +46201,8 @@ Object.freeze({
 	vehicle: .65,
 	animal: .65
 });
+var HF_REPO = "camstack/camstack-models";
+`${HF_REPO}`;
 /**
 * Runtime defaults -- used by ConfigManager.get() for backward compatibility
 * until Plan B wires all runtime settings to the system_settings SQL table.
@@ -51783,6 +52064,12 @@ var METHOD_ACCESS_MAP = Object.freeze({
 		addonId: null,
 		access: "delete"
 	},
+	"pipelineExecutor.clearModelBoundDeviceOverrides": {
+		capName: "pipeline-executor",
+		capScope: "system",
+		addonId: null,
+		access: "delete"
+	},
 	"pipelineExecutor.deleteModel": {
 		capName: "pipeline-executor",
 		capScope: "system",
@@ -51999,6 +52286,12 @@ var METHOD_ACCESS_MAP = Object.freeze({
 		addonId: null,
 		access: "view"
 	},
+	"pipelineOrchestrator.applyBestSettings": {
+		capName: "pipeline-orchestrator",
+		capScope: "system",
+		addonId: null,
+		access: "create"
+	},
 	"pipelineOrchestrator.applyDeviceSettingsPatch": {
 		capName: "pipeline-orchestrator",
 		capScope: "system",
@@ -52173,6 +52466,12 @@ var METHOD_ACCESS_MAP = Object.freeze({
 		addonId: null,
 		access: "create"
 	},
+	"pipelineOrchestrator.planBestSettings": {
+		capName: "pipeline-orchestrator",
+		capScope: "system",
+		addonId: null,
+		access: "view"
+	},
 	"pipelineOrchestrator.rebalance": {
 		capName: "pipeline-orchestrator",
 		capScope: "system",
@@ -57850,6 +58149,11 @@ Object.freeze({
 		form: "single",
 		optional: false
 	}],
+	"pipelineExecutor.clearModelBoundDeviceOverrides": [{
+		name: "deviceIds",
+		form: "array",
+		optional: true
+	}],
 	"pipelineExecutor.runPipeline": [{
 		name: "deviceId",
 		form: "single",
@@ -60200,6 +60504,9 @@ var ADDON_ID_PREFIX = "addon:";
 function bareAddonId(id) {
 	return id.startsWith(ADDON_ID_PREFIX) ? id.slice(6) : id;
 }
+function hfModelUrl(repo, path) {
+	return `https://huggingface.co/${repo}/resolve/main/${path}`;
+}
 var MB = 1024 * 1024;
 1024 * MB, 3072 * MB;
 /**
@@ -60532,6 +60839,12 @@ Object.defineProperty(exports, "FieldClaimSchema", {
 		return FieldClaimSchema;
 	}
 });
+Object.defineProperty(exports, "HF_REPO", {
+	enumerable: true,
+	get: function() {
+		return HF_REPO;
+	}
+});
 Object.defineProperty(exports, "LOG_LEVEL_RANK", {
 	enumerable: true,
 	get: function() {
@@ -60562,6 +60875,12 @@ Object.defineProperty(exports, "MINUTES_PER_DAY", {
 		return MINUTES_PER_DAY;
 	}
 });
+Object.defineProperty(exports, "MODEL_FORMATS", {
+	enumerable: true,
+	get: function() {
+		return MODEL_FORMATS;
+	}
+});
 Object.defineProperty(exports, "MOTION_CLOSE_AFTER_MS", {
 	enumerable: true,
 	get: function() {
@@ -61042,6 +61361,12 @@ Object.defineProperty(exports, "gbToBytes", {
 		return gbToBytes;
 	}
 });
+Object.defineProperty(exports, "hfModelUrl", {
+	enumerable: true,
+	get: function() {
+		return hfModelUrl;
+	}
+});
 Object.defineProperty(exports, "hydrateSchema", {
 	enumerable: true,
 	get: function() {

package/dist/download/hosted-model-revisions.d.ts

@@ -0,0 +1,10 @@
+/**
+ * GENERATED by `scripts/check-hosted-model-revisions.ts --write` — DO NOT EDIT.
+ *
+ * The revision of every artefact on the CamStack model mirror, keyed by its
+ * path under `https://huggingface.co/camstack/camstack-models/resolve/main/`: the sha256 (`lfs.oid`)
+ * of its weight file (`revisionWeightUrl`). `resolveFormatRevision` reads
+ * it for every catalog format hosted there (D743, D744). Regenerate after
+ * any upload to the mirror; the script without `--write` says when it is due.
+ */
+export declare const HOSTED_MODEL_REVISIONS: Readonly<Record<string, string>>;

package/dist/download/model-download-service.d.ts

@@ -1,10 +1,12 @@
 import { ModelCatalogEntry, ModelFormat, IAddonModelManager } from '@camstack/types';
 /**
- * Unified model download service.
+ * A catalog-bound face over the shared downloader.
  *
- * Handles downloading model files and extra files (labels, dicts) from a
- * catalog of ModelCatalogEntry items. Supports single-file models and
- * directory bundles (e.g., .mlpackage for CoreML).
+ * Downloading, completeness and the revision contract (D743) are
+ * `ensureModel` / `isModelDownloaded`'s — this class only resolves a model id
+ * (and a default format) against its catalog and keys progress by model id.
+ * It used to carry its own copy of the download loop, which never learnt the
+ * revision; one rule now lives in one place.
  *
  * Addons use this via `context.models.ensure(modelId, format)`.
  */
@@ -14,7 +16,7 @@ export declare class ModelDownloadService implements IAddonModelManager {
     private readonly catalog;
     constructor(modelsDir: string, catalog: readonly ModelCatalogEntry[], onProgress?: ((modelId: string, downloaded: number, total: number) => void) | undefined);
     /**
-     * Ensure a model (and its extra files) is downloaded.
+     * Ensure a model (and its extra files) is downloaded and current.
      * Returns the local filesystem path to the model file/directory.
      */
     ensure(modelId: string, format?: ModelFormat): Promise<string>;
@@ -25,17 +27,9 @@ export declare class ModelDownloadService implements IAddonModelManager {
     ensureExtraFiles(modelId: string): Promise<readonly string[]>;
     /** Absolute path to the shared models directory. */
     getModelsDir(): string;
-    /** Check if a model file is already present on disk. */
+    /** True when the model is on disk, complete, and at its revision (D743). */
     isDownloaded(modelId: string, format?: ModelFormat): boolean;
     /** Get the catalog entry for a model by ID. */
     getEntry(modelId: string): ModelCatalogEntry | undefined;
     private pickDefaultFormat;
-    private modelFilePath;
-    /**
-     * Download a directory bundle (e.g., .mlpackage) from HuggingFace.
-     * ATOMIC: downloads to temp dir, renames only on complete success.
-     */
-    private downloadDirectory;
-    /** Recursively list all files in a HuggingFace directory via API. */
-    private listHfFiles;
 }

package/dist/download/model-downloader.d.ts

@@ -79,18 +79,60 @@ export type DownloadProgressCallback = (downloaded: number, total: number | unde
  * bundle, so a `.mlpackage` keeps exactly the hosted files.
  */
 export declare function revisionRecordPath(modelPath: string): string;
+/** The CamStack model mirror. Every artefact under it has a generated revision. */
+export declare const HOSTED_MODEL_MIRROR_PREFIX: string;
+/**
+ * The revision a format must be at — the ONE rule every model download path
+ * reads (D743, D744). An inline `revision` wins; otherwise a format hosted on
+ * the CamStack mirror takes the revision generated for its path from the
+ * mirror's LFS metadata (`hosted-model-revisions.ts`); anything else has none.
+ */
+export declare function resolveFormatRevision(formatEntry: ModelFormatEntry): string | undefined;
+/**
+ * The file whose sha256 IS a format's revision: a Core ML package's
+ * `weight.bin`, an OpenVINO IR's `.bin` sibling, otherwise the file itself.
+ * `null` for a bundle that is not a Core ML package (nothing to hash).
+ */
+export type RevisionWeightFile = {
+    readonly in: 'bundle';
+    readonly member: string;
+} | {
+    readonly in: 'sibling';
+    readonly name: string;
+} | {
+    readonly in: 'main';
+};
+export declare function revisionWeightFile(formatEntry: ModelFormatEntry): RevisionWeightFile | null;
+/** Where the revision's weight file is hosted — what the mirror's `lfs.oid` describes. */
+export declare function revisionWeightUrl(formatEntry: ModelFormatEntry): string | null;
 /**
  * Resolve a `ModelCatalogEntry` against `modelsDir`: download model file
  * (or directory bundle) + extra files (labels JSON, charset dict, …),
  * skip if already on disk. Returns the local model path.
  */
 export declare function ensureModel(modelsDir: string, entry: ModelCatalogEntry, format: ModelFormat, onProgress?: DownloadProgressCallback): Promise<string>;
+/** What {@link adoptModelRevisions} found: `<modelId>/<format>` keys. */
+export interface ModelRevisionAdoption {
+    /** Copies proven current by hash and recorded — no download needed. */
+    readonly adopted: readonly string[];
+    /** Complete copies holding other bytes — `ensureModel` fetches them again. */
+    readonly stale: readonly string[];
+}
+/**
+ * Walk `entries` and record the revision of every complete copy on disk that
+ * hashes to it, so a node's listing reports present models as downloaded
+ * without waiting for something to `ensureModel` them. Offline: it reads
+ * files and never fetches. A copy already recorded current is not re-hashed.
+ */
+export declare function adoptModelRevisions(modelsDir: string, entries: readonly ModelCatalogEntry[]): Promise<ModelRevisionAdoption>;
 /** Compute the on-disk path for a given model + format, even when not yet downloaded. */
 export declare function getModelFilePath(modelsDir: string, entry: ModelCatalogEntry, format: ModelFormat): string | null;
 /**
  * True iff the model file (or `Manifest.json` for directory bundles) exists and
- * is non-empty, and — when the catalog names a `revision` — the node recorded
- * that same revision for it (D743).
+ * is non-empty, and — when the format has a revision ({@link
+ * resolveFormatRevision}) — the node recorded that same revision for it
+ * (D743). Synchronous, so it never hashes: a copy not yet proven current
+ * answers false until `ensureModel` or {@link adoptModelRevisions} records it.
  */
 export declare function isModelDownloaded(modelsDir: string, entry: ModelCatalogEntry, format: ModelFormat): boolean;
 /** Remove the on-disk model file/directory. Returns true if something was deleted. */