@camstack/addon-post-analysis 1.2.285 → 1.2.286

package/dist/embedding-encoder/index.js

@@ -2,11 +2,11 @@ Object.defineProperties(exports, {
 	__esModule: { value: true },
 	[Symbol.toStringTag]: { value: "Module" }
 });
-const require_dist = require("../dist-ITESpHou.js");
+const require_clip_model_registry = require("../clip-model-registry-CY0FGcpQ.js");
 let node_fs = require("node:fs");
-node_fs = require_dist.__toESM(node_fs);
+node_fs = require_clip_model_registry.__toESM(node_fs);
 let node_path = require("node:path");
-node_path = require_dist.__toESM(node_path);
+node_path = require_clip_model_registry.__toESM(node_path);
 let node_child_process = require("node:child_process");
 let _camstack_system_addon_utils = require("@camstack/system/addon-utils");
 //#region src/embedding-encoder/shared/process-memory.ts
@@ -28,7 +28,7 @@ let _camstack_system_addon_utils = require("@camstack/system/addon-utils");
 var IS_LINUX = process.platform === "linux";
 async function readProcessMemory(pid) {
 	if (IS_LINUX) try {
-		return require_dist.parseProcStatus(await node_fs.promises.readFile(`/proc/${pid}/status`, "utf8"));
+		return require_clip_model_registry.parseProcStatus(await node_fs.promises.readFile(`/proc/${pid}/status`, "utf8"));
 	} catch {
 		return null;
 	}
@@ -56,232 +56,101 @@ function readViaPs(pid) {
 	});
 }
 //#endregion
-//#region src/embedding-encoder/catalogs/embedding-models.ts
-var HF_REPO = "camstack/camstack-models";
-var hf = (path) => require_dist.hfModelUrl(HF_REPO, path);
+//#region src/embedding-encoder/shared/framed-python-process.ts
 /**
-* The CLIP BPE tokenizer (HF `tokenizers` format: vocab 49408 + 48894 merges).
-* Hosted next to every text-encoder onnx (`.../onnx/tokenizer.json`) and fetched
-* as a sibling file so it lands beside the model in the shared models dir.
-*/
-var TOKENIZER_FILE = "tokenizer.json";
-var ovFormat = (url, sizeMB) => {
-	const base = url.split("/").pop() ?? "";
-	const files = base.endsWith(".xml") ? [base.replace(/\.xml$/, ".bin")] : void 0;
-	return {
-		url,
-		sizeMB,
-		runtimes: ["python"],
-		...files ? { files } : {}
-	};
-};
-/**
-* Files inside an .mlpackage directory bundle.
-* Must be fetched alongside the package root when isDirectory is true.
-*/
-var MLPACKAGE_FILES = [
-	"Manifest.json",
-	"Data/com.apple.CoreML/model.mlmodel",
-	"Data/com.apple.CoreML/weights/weight.bin"
-];
-/**
-* NO onnx vision builds, deliberately (2026-08-21). The int8 ONNX vision
-* exports were measured misaligned with the text encoders (matched image↔text
-* cosine ≈ 0.01 vs ≈ 0.22 for the fp16 openvino/coreml builds) — see the
-* catalog note in `addon-pipeline/.../model-catalogs.ts`. The image-encode leg
-* that consumed them here (`embeddingEncoder.encode` → PythonRawTensorEngine)
-* is retired with them: its only caller discarded the vector, and its
-* `preprocessForClip` applied OpenAI mean/std that MobileCLIP never used.
-* S0 was retired the same day (measured worst of the family on fleet crops).
-*/
-var CLIP_IMAGE_MODELS = [{
-	id: "mobileclip-s1",
-	name: "MobileCLIP S1",
-	description: "Apple MobileCLIP S1 — balanced vision encoder, 512-dim, 256×256 (fp16 OpenVINO/CoreML)",
-	inputSize: {
-		width: 256,
-		height: 256
-	},
-	labels: [],
-	inputNormalization: "none",
-	formats: {
-		openvino: ovFormat(hf("clip/mobileclip-s1/openvino/camstack-mobileclip-s1-vision.xml"), 55),
-		coreml: {
-			url: hf("clip/mobileclip-s1/coreml/camstack-mobileclip-s1-vision.mlpackage"),
-			sizeMB: 65,
-			isDirectory: true,
-			files: [...MLPACKAGE_FILES],
-			runtimes: ["python"]
-		}
-	}
-}, {
-	id: "mobileclip-s2",
-	name: "MobileCLIP S2",
-	description: "Apple MobileCLIP S2 — high-accuracy vision encoder, 512-dim, 256×256 (fp16 OpenVINO/CoreML)",
-	inputSize: {
-		width: 256,
-		height: 256
-	},
-	labels: [],
-	inputNormalization: "none",
-	formats: {
-		openvino: ovFormat(hf("clip/mobileclip-s2/openvino/camstack-mobileclip-s2-vision.xml"), 90),
-		coreml: {
-			url: hf("clip/mobileclip-s2/coreml/camstack-mobileclip-s2-vision.mlpackage"),
-			sizeMB: 110,
-			isDirectory: true,
-			files: [...MLPACKAGE_FILES],
-			runtimes: ["python"]
-		}
-	}
-}];
-/**
-* The int8 TEXT onnx encoders are healthy — unlike the retired int8 vision
-* exports. Verified 2026-08-21: the live search path (fp16 openvino vision
-* vectors ⋅ int8 onnx text queries) ranks correctly on the real index, and the
-* local cross-check aligns them with the fp16 vision space (cos ≈ 0.22 on
-* matched pairs).
-*/
-var CLIP_TEXT_MODELS = [{
-	id: "mobileclip-s1-text",
-	name: "MobileCLIP S1 Text Encoder",
-	description: "Text encoder for MobileCLIP S1, 512-dim, int8 quantized (61 MB)",
-	inputSize: {
-		width: 0,
-		height: 0
-	},
-	labels: [],
-	formats: {
-		onnx: {
-			url: hf("clip/mobileclip-s1/onnx/camstack-mobileclip-s1-text.onnx"),
-			sizeMB: 61,
-			files: [TOKENIZER_FILE]
-		},
-		openvino: ovFormat(hf("clip/mobileclip-s1/openvino/camstack-mobileclip-s1-text.xml"), 121)
-	}
-}, {
-	id: "mobileclip-s2-text",
-	name: "MobileCLIP S2 Text Encoder",
-	description: "Text encoder for MobileCLIP S2, 512-dim, int8 quantized (61 MB)",
-	inputSize: {
-		width: 0,
-		height: 0
-	},
-	labels: [],
-	formats: {
-		onnx: {
-			url: hf("clip/mobileclip-s2/onnx/camstack-mobileclip-s2-text.onnx"),
-			sizeMB: 61,
-			files: [TOKENIZER_FILE]
-		},
-		openvino: ovFormat(hf("clip/mobileclip-s2/openvino/camstack-mobileclip-s2-text.xml"), 121)
-	}
-}];
-//#endregion
-//#region src/embedding-encoder/shared/noop-logger.ts
-var noop = () => {};
-function createNoopLogger() {
-	const logger = {
-		debug: noop,
-		info: noop,
-		warn: noop,
-		error: noop,
-		child: () => logger,
-		withTags: (_tags) => logger
-	};
-	return logger;
-}
-//#endregion
-//#region src/embedding-encoder/shared/python-raw-tensor-engine.ts
-/**
-* Raw-tensor ONNX engine backed by an embedded-Python subprocess
-* (`raw_tensor_inference.py`). Replaces the Node `onnxruntime-node` raw-tensor
-* engine so the platform ships no Node ONNX runtime. The caller preprocesses to
-* a Float32Array; this engine ships it to Python, which runs onnxruntime and
-* returns the output tensor. Wire protocol = length-prefixed binary frames
-* ([4B LE length][payload]).
+* One embedded-Python subprocess speaking the length-prefixed frame protocol
+* (`[4B LE len][payload]`, ready = `[0x01]`) — the lifecycle both embedding
+* engines share, written once.
+*
+* ## What it guarantees (D649 review)
+*
+* - **Every awaited frame settles.** Waiters are a FIFO queue (the process
+*   answers in order). On ANY exit — a crash, an OOM kill, a clean 0, the
+*   SIGTERM of `dispose` (code null) — and on a stdin error, every waiter is
+*   rejected. The old guard (`code !== 0 && code !== null`) hung the encode.
+* - **A dead process is dead, by name.** After an unexpected exit the engine
+*   is marked dead with the exit code/signal, the exit is logged, and every
+*   later request rejects immediately with that reason instead of writing to
+*   a closed pipe and waiting forever. Holders check {@link isAlive} and
+*   rebuild — so a crash costs one failed request, not a silent stop.
+* - **EPIPE never escapes.** stdin carries an `error` listener: a write into a
+*   process that just died becomes a rejected request, never an uncaught
+*   exception in the addon.
 */
-var PythonRawTensorEngine = class {
+var FramedPythonProcess = class {
+	name;
 	pythonPath;
-	scriptPath;
-	modelPath;
-	runtime = "onnx";
-	device = "cpu";
+	args;
+	log;
 	process = null;
 	receiveBuffer = Buffer.alloc(0);
-	pendingResolve = null;
-	pendingReject = null;
-	log;
-	constructor(pythonPath, scriptPath, modelPath, logger) {
+	pending = [];
+	dead = null;
+	disposing = false;
+	constructor(name, pythonPath, args, log) {
+		this.name = name;
 		this.pythonPath = pythonPath;
-		this.scriptPath = scriptPath;
-		this.modelPath = modelPath;
-		this.log = logger ?? createNoopLogger();
+		this.args = args;
+		this.log = log;
 	}
-	async initialize() {
-		this.process = (0, node_child_process.spawn)(this.pythonPath, [this.scriptPath, this.modelPath], { stdio: [
+	/** Spawn and wait for the ready frame. */
+	async start() {
+		const proc = (0, node_child_process.spawn)(this.pythonPath, [...this.args], { stdio: [
 			"pipe",
 			"pipe",
 			"pipe"
 		] });
-		this.process.stderr?.on("data", (chunk) => {
+		this.process = proc;
+		proc.stderr?.on("data", (chunk) => {
 			const text = chunk.toString().trim();
 			if (text) this.log.warn(text);
 		});
-		this.process.on("error", (err) => {
-			this.log.error("Python raw-tensor process error", { meta: { error: err.message } });
-			this.pendingReject?.(err);
-			this.pendingReject = null;
-			this.pendingResolve = null;
+		proc.on("error", (err) => {
+			this.log.error(`${this.name}: process error`, { meta: { error: err.message } });
+			this.markDead(`process error: ${err.message}`);
 		});
-		this.process.on("exit", (code) => {
-			if (code !== 0 && code !== null) {
-				const err = /* @__PURE__ */ new Error(`PythonRawTensorEngine: process exited with code ${code}`);
-				this.pendingReject?.(err);
-				this.pendingReject = null;
-				this.pendingResolve = null;
-			}
+		proc.stdin?.on("error", (err) => {
+			this.markDead(`stdin error: ${err.message}`);
+		});
+		proc.on("exit", (code, signal) => {
+			if (this.process === proc) this.process = null;
+			const reason = `process exited (code ${String(code)}, signal ${String(signal)})`;
+			if (!this.disposing) this.log.warn(`${this.name}: process exited unexpectedly — the engine is dead`, { meta: {
+				code,
+				signal,
+				pid: proc.pid ?? null
+			} });
+			this.markDead(reason);
 		});
-		this.process.stdout.on("data", (chunk) => {
+		proc.stdout?.on("data", (chunk) => {
 			this.receiveBuffer = Buffer.concat([this.receiveBuffer, chunk]);
 			this.tryReceive();
 		});
 		const ready = await this.receiveFrame();
-		if (ready.length !== 1 || ready[0] !== 1) throw new Error("PythonRawTensorEngine: unexpected ready frame");
-		this.log.info("ONNX raw-tensor engine ready (embedded Python)", { meta: { modelPath: this.modelPath } });
+		if (ready.length !== 1 || ready[0] !== 1) throw new Error(`${this.name}: unexpected ready frame`);
+	}
+	/** False once the process died or was disposed — a holder must rebuild. */
+	isAlive() {
+		return this.process !== null && this.dead === null;
 	}
-	/** Native pid of the Python subprocess — sampled by the pool memory
-	*  watchdog (`/proc/<pid>/status`). */
 	getPid() {
 		return this.process?.pid ?? null;
 	}
-	/** Inference requests served since spawn — the denominator that separates
-	*  "RSS grew per unit of work" (leak) from "RSS grew because it worked". */
-	getRequestCount() {
-		return this.requestCount;
-	}
-	requestCount = 0;
-	async run(input, inputShape) {
-		if (!this.process?.stdin) throw new Error("PythonRawTensorEngine: not initialized — call initialize() first");
-		this.requestCount++;
-		const ndims = inputShape.length;
-		const meta = Buffer.allocUnsafe(1 + ndims * 4);
-		meta.writeUInt8(ndims, 0);
-		for (let i = 0; i < ndims; i++) meta.writeUInt32LE(inputShape[i], 1 + i * 4);
-		const dataBuf = Buffer.from(input.buffer, input.byteOffset, input.byteLength);
-		const payload = Buffer.concat([meta, dataBuf]);
-		const lenBuf = Buffer.allocUnsafe(4);
-		lenBuf.writeUInt32LE(payload.length, 0);
-		this.process.stdin.write(Buffer.concat([lenBuf, payload]));
-		const resp = await this.receiveFrame();
-		const floatStart = 1 + resp.readUInt8(0) * 4;
-		const count = (resp.length - floatStart) / 4;
-		const out = new Float32Array(count);
-		for (let i = 0; i < count; i++) out[i] = resp.readFloatLE(floatStart + i * 4);
-		return out;
+	/** Send one request frame and await its answer. Rejects AT ONCE when dead. */
+	async request(payload) {
+		if (this.dead !== null) throw new Error(`${this.name}: engine is dead — ${this.dead}`);
+		const stdin = this.process?.stdin;
+		if (!stdin) throw new Error(`${this.name}: not initialized — call initialize() first`);
+		const answer = this.receiveFrame();
+		const len = Buffer.allocUnsafe(4);
+		len.writeUInt32LE(payload.length, 0);
+		stdin.write(Buffer.concat([len, payload]));
+		return answer;
 	}
 	async dispose() {
 		const proc = this.process;
+		this.disposing = true;
+		this.markDead("disposed");
 		if (!proc) return;
 		this.process = null;
 		proc.stdin?.end();
@@ -299,185 +168,546 @@ var PythonRawTensorEngine = class {
 			});
 		});
 	}
+	markDead(reason) {
+		if (this.dead === null) this.dead = reason;
+		const err = /* @__PURE__ */ new Error(`${this.name}: ${reason}`);
+		for (const waiter of this.pending.splice(0)) waiter.reject(err);
+	}
 	receiveFrame() {
 		return new Promise((resolve, reject) => {
-			this.pendingResolve = resolve;
-			this.pendingReject = reject;
+			this.pending.push({
+				resolve,
+				reject
+			});
 		});
 	}
 	tryReceive() {
-		if (this.receiveBuffer.length < 4) return;
-		const length = this.receiveBuffer.readUInt32LE(0);
-		if (this.receiveBuffer.length < 4 + length) return;
-		const payload = Buffer.from(this.receiveBuffer.subarray(4, 4 + length));
-		this.receiveBuffer = this.receiveBuffer.subarray(4 + length);
-		const resolve = this.pendingResolve;
-		this.pendingResolve = null;
-		this.pendingReject = null;
-		resolve?.(payload);
+		while (this.receiveBuffer.length >= 4) {
+			const length = this.receiveBuffer.readUInt32LE(0);
+			if (this.receiveBuffer.length < 4 + length) return;
+			const payload = Buffer.from(this.receiveBuffer.subarray(4, 4 + length));
+			this.receiveBuffer = this.receiveBuffer.subarray(4 + length);
+			this.pending.shift()?.resolve(payload);
+		}
 	}
 };
 //#endregion
+//#region src/embedding-encoder/shared/noop-logger.ts
+var noop = () => {};
+function createNoopLogger() {
+	const logger = {
+		debug: noop,
+		info: noop,
+		warn: noop,
+		error: noop,
+		child: () => logger,
+		withTags: (_tags) => logger
+	};
+	return logger;
+}
+//#endregion
 //#region src/embedding-encoder/shared/python-text-encoder-engine.ts
-/**
-* CLIP text-encoder engine backed by an embedded-Python subprocess
-* (`text_encoder_inference.py`). Tokenization happens IN Python via the HF
-* `tokenizers` Rust BPE (exact by construction) — this replaces the former
-* hand-rolled TypeScript CLIP BPE.
-*
-* The caller sends raw UTF-8 text; Python tokenizes (truncate/pad to 77), runs
-* onnxruntime, and returns the embedding tensor. Wire protocol = length-prefixed
-* binary frames ([4B LE length][payload]):
-*   ready    (in):  [0x01]
-*   request  (out): UTF-8 text bytes
-*   response (in):  [1B ndims][dims × 4B LE uint32][float32 LE data]
-*/
 var PythonTextEncoderEngine = class {
-	pythonPath;
 	scriptPath;
 	modelPath;
 	tokenizerPath;
-	process = null;
-	receiveBuffer = Buffer.alloc(0);
-	pendingResolve = null;
-	pendingReject = null;
+	window;
+	proc;
 	log;
-	constructor(pythonPath, scriptPath, modelPath, tokenizerPath, logger) {
-		this.pythonPath = pythonPath;
+	requestCount = 0;
+	constructor(pythonPath, scriptPath, modelPath, tokenizerPath, window, logger) {
 		this.scriptPath = scriptPath;
 		this.modelPath = modelPath;
 		this.tokenizerPath = tokenizerPath;
+		this.window = window;
 		this.log = logger ?? createNoopLogger();
+		this.proc = new FramedPythonProcess("PythonTextEncoderEngine", pythonPath, this.spawnArgs(), this.log);
 	}
 	async initialize() {
-		this.process = (0, node_child_process.spawn)(this.pythonPath, [
-			this.scriptPath,
-			this.modelPath,
-			this.tokenizerPath
-		], { stdio: [
-			"pipe",
-			"pipe",
-			"pipe"
-		] });
-		this.process.stderr?.on("data", (chunk) => {
-			const text = chunk.toString().trim();
-			if (text) this.log.warn(text);
-		});
-		this.process.on("error", (err) => {
-			this.log.error("Python text-encoder process error", { meta: { error: err.message } });
-			this.pendingReject?.(err);
-			this.pendingReject = null;
-			this.pendingResolve = null;
-		});
-		this.process.on("exit", (code) => {
-			if (code !== 0 && code !== null) {
-				const err = /* @__PURE__ */ new Error(`PythonTextEncoderEngine: process exited with code ${code}`);
-				this.pendingReject?.(err);
-				this.pendingReject = null;
-				this.pendingResolve = null;
-			}
-		});
-		this.process.stdout.on("data", (chunk) => {
-			this.receiveBuffer = Buffer.concat([this.receiveBuffer, chunk]);
-			this.tryReceive();
-		});
-		const ready = await this.receiveFrame();
-		if (ready.length !== 1 || ready[0] !== 1) throw new Error("PythonTextEncoderEngine: unexpected ready frame");
+		await this.proc.start();
 		this.log.info("CLIP text-encoder engine ready (embedded Python)", { meta: {
 			modelPath: this.modelPath,
-			tokenizerPath: this.tokenizerPath
+			tokenizerPath: this.tokenizerPath,
+			contextLength: this.window.contextLength,
+			padId: this.window.padId
 		} });
 	}
+	/** The subprocess argv after the interpreter — the window rides on it. */
+	spawnArgs() {
+		return [
+			this.scriptPath,
+			this.modelPath,
+			this.tokenizerPath,
+			"--context-length",
+			String(this.window.contextLength),
+			"--pad-id",
+			String(this.window.padId)
+		];
+	}
+	/** False once the process died (crash, OOM kill) or was disposed. */
+	isAlive() {
+		return this.proc.isAlive();
+	}
 	/** Native pid of the Python subprocess — sampled by the pool memory
 	*  watchdog (`/proc/<pid>/status`). */
 	getPid() {
-		return this.process?.pid ?? null;
+		return this.proc.getPid();
 	}
 	/** Encode requests served since spawn — the denominator that separates
 	*  "RSS grew per unit of work" (leak) from "RSS grew because it worked". */
 	getRequestCount() {
 		return this.requestCount;
 	}
-	requestCount = 0;
 	/** Tokenize + encode `text` into the model embedding (float32). */
 	async encode(text) {
-		if (!this.process?.stdin) throw new Error("PythonTextEncoderEngine: not initialized — call initialize() first");
 		this.requestCount++;
-		const payload = Buffer.from(text, "utf-8");
-		const lenBuf = Buffer.allocUnsafe(4);
-		lenBuf.writeUInt32LE(payload.length, 0);
-		this.process.stdin.write(Buffer.concat([lenBuf, payload]));
-		const resp = await this.receiveFrame();
-		const floatStart = 1 + resp.readUInt8(0) * 4;
-		const count = (resp.length - floatStart) / 4;
-		const out = new Float32Array(count);
-		for (let i = 0; i < count; i++) out[i] = resp.readFloatLE(floatStart + i * 4);
-		return out;
+		return decodeTensorFrame(await this.proc.request(Buffer.from(text, "utf-8")));
 	}
 	async dispose() {
-		const proc = this.process;
-		if (!proc) return;
-		this.process = null;
-		proc.stdin?.end();
-		proc.kill("SIGTERM");
-		await new Promise((resolve) => {
-			const timer = setTimeout(() => {
-				try {
-					proc.kill("SIGKILL");
-				} catch {}
-				resolve();
-			}, 5e3);
-			proc.once("exit", () => {
-				clearTimeout(timer);
-				resolve();
-			});
-		});
+		await this.proc.dispose();
 	}
-	receiveFrame() {
-		return new Promise((resolve, reject) => {
-			this.pendingResolve = resolve;
-			this.pendingReject = reject;
-		});
+};
+/** Decode `[1B ndims][dims × 4B][float32 data]`. */
+function decodeTensorFrame(resp) {
+	const floatStart = 1 + resp.readUInt8(0) * 4;
+	const count = (resp.length - floatStart) / 4;
+	const out = new Float32Array(count);
+	for (let i = 0; i < count; i++) out[i] = resp.readFloatLE(floatStart + i * 4);
+	return out;
+}
+//#endregion
+//#region src/embedding-encoder/shared/python-raw-tensor-engine.ts
+/**
+* Raw-tensor ONNX engine backed by an embedded-Python subprocess
+* (`raw_tensor_inference.py`). Replaces the Node `onnxruntime-node` raw-tensor
+* engine so the platform ships no Node ONNX runtime. The caller preprocesses to
+* a Float32Array; this engine ships it to Python, which runs onnxruntime and
+* returns the output tensor. Wire protocol = length-prefixed binary frames
+* ([4B LE length][payload]); the process lifecycle is `FramedPythonProcess`.
+*/
+var PythonRawTensorEngine = class {
+	modelPath;
+	runtime = "onnx";
+	device = "cpu";
+	proc;
+	log;
+	requestCount = 0;
+	constructor(pythonPath, scriptPath, modelPath, logger) {
+		this.modelPath = modelPath;
+		this.log = logger ?? createNoopLogger();
+		this.proc = new FramedPythonProcess("PythonRawTensorEngine", pythonPath, [scriptPath, modelPath], this.log);
 	}
-	tryReceive() {
-		if (this.receiveBuffer.length < 4) return;
-		const length = this.receiveBuffer.readUInt32LE(0);
-		if (this.receiveBuffer.length < 4 + length) return;
-		const payload = Buffer.from(this.receiveBuffer.subarray(4, 4 + length));
-		this.receiveBuffer = this.receiveBuffer.subarray(4 + length);
-		const resolve = this.pendingResolve;
-		this.pendingResolve = null;
-		this.pendingReject = null;
-		resolve?.(payload);
+	async initialize() {
+		await this.proc.start();
+		this.log.info("ONNX raw-tensor engine ready (embedded Python)", { meta: { modelPath: this.modelPath } });
+	}
+	/** False once the process died (crash, OOM kill) or was disposed. */
+	isAlive() {
+		return this.proc.isAlive();
+	}
+	/** Native pid of the Python subprocess — sampled by the pool memory
+	*  watchdog (`/proc/<pid>/status`). */
+	getPid() {
+		return this.proc.getPid();
+	}
+	/** Inference requests served since spawn — the denominator that separates
+	*  "RSS grew per unit of work" (leak) from "RSS grew because it worked". */
+	getRequestCount() {
+		return this.requestCount;
+	}
+	async run(input, inputShape) {
+		this.requestCount++;
+		const ndims = inputShape.length;
+		const meta = Buffer.allocUnsafe(1 + ndims * 4);
+		meta.writeUInt8(ndims, 0);
+		for (let i = 0; i < ndims; i++) meta.writeUInt32LE(inputShape[i], 1 + i * 4);
+		const dataBuf = Buffer.from(input.buffer, input.byteOffset, input.byteLength);
+		return decodeTensorFrame(await this.proc.request(Buffer.concat([meta, dataBuf])));
+	}
+	async dispose() {
+		await this.proc.dispose();
+	}
+};
+var ActiveClipModel = class {
+	deps;
+	cached = null;
+	lastRead = null;
+	constructor(deps) {
+		this.deps = deps;
+	}
+	/**
+	* The last row a read RETURNED, without reading — `null` while no read has
+	* ever succeeded (the config fallback is a guess, not a known model). The
+	* idle sweep exempts this model's text tower (`clip-text-engines.ts`).
+	*/
+	known() {
+		return this.lastRead;
+	}
+	async get() {
+		const now = this.deps.now();
+		if (this.cached !== null && now - this.cached.at < 3e4) return this.cached.modelId;
+		const row = await this.deps.readRow();
+		if (row === null) {
+			const kept = this.lastRead ?? this.deps.fallbackModelId();
+			this.deps.logger.warn("CLIP encoder kept its model — the cluster row could not be read", { meta: {
+				modelId: kept,
+				source: this.lastRead !== null ? "last-read" : "addon-config"
+			} });
+			return kept;
+		}
+		const previous = this.lastRead;
+		if (row !== previous) this.deps.logger.info("CLIP encoder follows the cluster model", { meta: {
+			modelId: row,
+			previous
+		} });
+		this.lastRead = row;
+		this.cached = {
+			modelId: row,
+			at: now
+		};
+		if (previous !== null && row !== previous) this.deps.onChange?.(row, previous);
+		return row;
+	}
+};
+var CrashBudget = class {
+	deps;
+	recent = /* @__PURE__ */ new Map();
+	failedModels = /* @__PURE__ */ new Map();
+	constructor(deps) {
+		this.deps = deps;
+	}
+	/** Throw the named refusal when the model is in `failed`. Spawns nothing. */
+	check(modelId) {
+		const failed = this.failedModels.get(modelId);
+		if (failed === void 0) return;
+		throw require_clip_model_registry.embeddingModelFailedError(failed);
+	}
+	/** Record one crash or load failure. Returns true when it made the model `failed`. */
+	record(modelId, reason) {
+		if (this.failedModels.has(modelId)) return false;
+		const now = this.now();
+		const windowMs = this.deps.windowMs ?? 6e5;
+		const times = (this.recent.get(modelId) ?? []).filter((t) => now - t < windowMs);
+		times.push(now);
+		this.recent.set(modelId, times);
+		if (times.length < (this.deps.maxCrashes ?? 3)) return false;
+		const failed = {
+			modelId,
+			tower: this.deps.tower,
+			nodeId: this.deps.nodeId(),
+			crashes: times.length,
+			windowMs,
+			sinceMs: now,
+			lastReason: reason
+		};
+		this.failedModels.set(modelId, failed);
+		this.recent.delete(modelId);
+		this.deps.logger.error("CLIP tower FAILED — crash budget exhausted, requests refused until reset", { meta: { ...failed } });
+		return true;
+	}
+	failed() {
+		return [...this.failedModels.values()];
+	}
+	/** Clear one model (or all). Returns the ids that were failed. */
+	reset(modelId, why = "operator") {
+		const ids = modelId !== void 0 ? [modelId] : [...this.failedModels.keys()];
+		const cleared = ids.filter((id) => this.failedModels.delete(id));
+		for (const id of ids) this.recent.delete(id);
+		if (cleared.length > 0) this.deps.logger.info("CLIP tower failed state cleared", { meta: {
+			tower: this.deps.tower,
+			nodeId: this.deps.nodeId(),
+			cleared,
+			why
+		} });
+		return cleared;
+	}
+	now() {
+		return (this.deps.now ?? Date.now)();
 	}
 };
 //#endregion
-//#region src/embedding-encoder/addon/clip-models.ts
+//#region src/embedding-encoder/addon/failed-models-report.ts
 /**
-* `mobileclip-s0` was retired on 2026-08-21 (measured worst of the family on
-* real fleet crops). A stored config still naming it resolves to the default
-* via {@link getModelMeta}'s fallback — never to a dangling id.
+* Every failed tower on this node. Each row already names the node: the budget
+* stamps it when the model goes `failed` (it is in the refusal too), and this
+* report does not re-derive it — one authority for the fact.
 */
-var CLIP_MODEL_META = {
-	"mobileclip-s1": {
-		imageModelId: "mobileclip-s1",
-		textModelId: "mobileclip-s1-text",
-		embeddingDim: 512,
-		inputSize: 256,
-		tokenizerType: "clip"
-	},
-	"mobileclip-s2": {
-		imageModelId: "mobileclip-s2",
-		textModelId: "mobileclip-s2-text",
-		embeddingDim: 512,
-		inputSize: 256,
-		tokenizerType: "clip"
+function reportFailedModels(budgets) {
+	return [...budgets.image.failed(), ...budgets.text.failed()];
+}
+/** Every model whose requirements are terminally unmeetable on this node; rows stamped by the gate. */
+function reportFailedRequirements(requirements) {
+	return [...requirements.image.failed(), ...requirements.text.failed()];
+}
+/** The operator's clear (one model, or all) of BOTH terminal states on this node — the result names it. */
+function resetFailedModelsOn(nodeId, towers, modelId) {
+	const cleared = [
+		...towers.budgets.image.reset(modelId),
+		...towers.budgets.text.reset(modelId),
+		...towers.requirements.image.reset(modelId),
+		...towers.requirements.text.reset(modelId)
+	];
+	return {
+		cleared: [...new Set(cleared)],
+		nodeId
+	};
+}
+/**
+* The cluster row now names `modelId`: a fresh start for THAT model's towers
+* only (D6's second exit from `failed`). The model the row left keeps its
+* state — a rollback to a model that crashed three times must not buy three
+* more spawns nobody asked for, and a search that still names it
+* (`searchObjectEvents({ modelId })`) is refused with the reset hint, as
+* before the flip.
+*/
+function clearFailedOnModelChange(towers, modelId) {
+	return [...new Set([
+		...towers.budgets.image.reset(modelId, "model-change"),
+		...towers.budgets.text.reset(modelId, "model-change"),
+		...towers.requirements.image.reset(modelId, "model-change"),
+		...towers.requirements.text.reset(modelId, "model-change")
+	])];
+}
+//#endregion
+//#region src/embedding-encoder/addon/model-engine-slot.ts
+var ModelEngineSlot = class {
+	build;
+	budget;
+	requirements;
+	onDead;
+	current = null;
+	inflight = /* @__PURE__ */ new Map();
+	/** The last model asked for — a build for any other model is stale on arrival. */
+	wanted = null;
+	/** Serialises switches so two models never tear the slot down concurrently. */
+	switching = Promise.resolve();
+	/**
+	* Bumped by {@link dispose}: a build that started before it is stale when it
+	* lands and is disposed on arrival — shutdown leaves no process behind.
+	*/
+	generation = 0;
+	constructor(build, budget, requirements, onDead = () => {}) {
+		this.build = build;
+		this.budget = budget;
+		this.requirements = requirements;
+		this.onDead = onDead;
+	}
+	held() {
+		return this.current;
+	}
+	async ensure(modelId) {
+		this.wanted = modelId;
+		this.dropIfDead();
+		if (this.current?.modelId === modelId) return this.current.engine;
+		this.budget.check(modelId);
+		this.requirements.check(modelId);
+		const pending = this.inflight.get(modelId);
+		if (pending !== void 0) return pending;
+		const generation = this.generation;
+		const guarded = this.switching.then(async () => {
+			this.dropIfDead();
+			if (this.current?.modelId === modelId) return this.current.engine;
+			this.budget.check(modelId);
+			this.requirements.check(modelId);
+			await this.disposeCurrent();
+			let engine;
+			try {
+				engine = await this.build(modelId);
+			} catch (err) {
+				throw this.requirements.refuse(modelId, err);
+			}
+			this.requirements.satisfied(modelId);
+			try {
+				await engine.initialize();
+			} catch (err) {
+				this.budget.record(modelId, `load failed: ${err instanceof Error ? err.message : String(err)}`);
+				throw err;
+			}
+			if (this.generation !== generation) {
+				await engine.dispose();
+				throw new Error(`engine for "${modelId}" cancelled: the slot was disposed while building`);
+			}
+			if (this.wanted !== modelId) {
+				await engine.dispose();
+				throw new Error(`engine for "${modelId}" superseded while building`);
+			}
+			this.current = {
+				modelId,
+				engine
+			};
+			return engine;
+		}).finally(() => {
+			this.inflight.delete(modelId);
+		});
+		this.inflight.set(modelId, guarded);
+		this.switching = guarded.then(() => void 0, () => void 0);
+		return guarded;
+	}
+	/**
+	* Dispose the held engine AND cancel every build in flight: each is disposed
+	* when it lands (see `generation`). Resolves once in-flight builds settled.
+	*/
+	async dispose() {
+		this.generation += 1;
+		await this.disposeCurrent();
+		await this.switching;
+	}
+	async disposeCurrent() {
+		const held = this.current;
+		this.current = null;
+		await held?.engine.dispose();
+	}
+	dropIfDead() {
+		const held = this.current;
+		if (held === null || held.engine.isAlive()) return;
+		this.current = null;
+		this.onDead(held.modelId);
+		this.budget.record(held.modelId, "process died after loading");
+		held.engine.dispose().catch(() => {});
+	}
+};
+/**
+* Thrown by the requirements stage when a retry can never help: the catalog
+* does not know the id, the server said the file does not exist (404/410), a
+* declared sibling is missing. Same process as the gate, so the class is the
+* marker; the gate never matches wording.
+*/
+var PermanentRequirementsFailure = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "PermanentRequirementsFailure";
 	}
 };
-var DEFAULT_CLIP_MODEL = "mobileclip-s1";
-function getModelMeta(modelId) {
-	return CLIP_MODEL_META[modelId] ?? CLIP_MODEL_META["mobileclip-s1"];
+function isPermanentRequirementsFailure(err) {
+	return err instanceof PermanentRequirementsFailure;
 }
+var RequirementsGate = class {
+	deps;
+	unavailable = /* @__PURE__ */ new Map();
+	constructor(deps) {
+		this.deps = deps;
+	}
+	/**
+	* Consulted BEFORE a build. Throws the named refusal — and downloads nothing
+	* — while the model is terminal or inside its cooldown. Returns otherwise.
+	*/
+	check(modelId) {
+		const state = this.unavailable.get(modelId);
+		if (state === void 0) return;
+		if (state.terminal !== null) {
+			this.unavailable.set(modelId, {
+				...state,
+				refused: state.refused + 1
+			});
+			throw require_clip_model_registry.embeddingRequirementsFailedError(state.terminal);
+		}
+		const now = this.now();
+		if (now >= state.cooldownUntilMs) return;
+		this.unavailable.set(modelId, {
+			...state,
+			refused: state.refused + 1
+		});
+		throw require_clip_model_registry.embeddingRequirementsUnavailableError(this.on(modelId), `retry in ${String(Math.ceil((state.cooldownUntilMs - now) / 1e3))}s — ${state.reason}`);
+	}
+	/**
+	* A build failed before any process existed. Starts (or doubles) the
+	* cooldown; a PERMANENT failure past the bound makes the model terminal.
+	* Logs at the transitions only and returns the named refusal to throw.
+	*/
+	refuse(modelId, err) {
+		const reason = err instanceof Error ? err.message : String(err);
+		const now = this.now();
+		const prior = this.unavailable.get(modelId);
+		const attempts = (prior?.attempts ?? 0) + 1;
+		const permanent = isPermanentRequirementsFailure(err);
+		const permanentAttempts = (prior?.permanentAttempts ?? 0) + (permanent ? 1 : 0);
+		const cooldownMs = Math.min(this.deps.cooldownMaxMs ?? 3e5, (this.deps.cooldownBaseMs ?? 5e3) * 2 ** (attempts - 1));
+		const base = {
+			sinceMs: prior?.sinceMs ?? now,
+			reason,
+			refused: (prior?.refused ?? 0) + 1,
+			attempts,
+			permanentAttempts,
+			cooldownUntilMs: now + cooldownMs,
+			terminal: null
+		};
+		if (prior === void 0) this.deps.logger.warn("CLIP model requirements unavailable — requests refused until they are; the crash budget is untouched", { meta: {
+			modelId,
+			tower: this.deps.tower,
+			nodeId: this.deps.nodeId(),
+			reason,
+			cooldownMs
+		} });
+		if (permanent && permanentAttempts >= (this.deps.maxAttempts ?? 3)) {
+			const terminal = {
+				...this.on(modelId),
+				attempts: permanentAttempts,
+				sinceMs: now,
+				lastReason: reason
+			};
+			this.unavailable.set(modelId, {
+				...base,
+				terminal
+			});
+			this.deps.logger.error("CLIP model requirements can never be met — terminally failed, requests refused until reset", { meta: {
+				...terminal,
+				refusedSoFar: base.refused
+			} });
+			return require_clip_model_registry.embeddingRequirementsFailedError(terminal);
+		}
+		this.unavailable.set(modelId, base);
+		return require_clip_model_registry.embeddingRequirementsUnavailableError(this.on(modelId), reason);
+	}
+	/** A build got its engine: the requirements are met again. Logs the recovery once. */
+	satisfied(modelId) {
+		const prior = this.unavailable.get(modelId);
+		if (prior === void 0) return;
+		this.unavailable.delete(modelId);
+		this.deps.logger.info("CLIP model requirements available again", { meta: {
+			modelId,
+			tower: this.deps.tower,
+			nodeId: this.deps.nodeId(),
+			unavailableMs: this.now() - prior.sinceMs,
+			refused: prior.refused,
+			attempts: prior.attempts,
+			lastReason: prior.reason
+		} });
+	}
+	/** Models terminally `requirements-failed` on this node, as `getInfo` reports them. */
+	failed() {
+		return [...this.unavailable.values()].map((s) => s.terminal).filter((t) => t !== null);
+	}
+	/**
+	* Clear one model (or all): terminal state AND cooldown. Returns the ids
+	* that were TERMINAL — a cooldown is not a state an operator is told about.
+	*/
+	reset(modelId, why = "operator") {
+		const ids = modelId !== void 0 ? [modelId] : [...this.unavailable.keys()];
+		const cleared = ids.filter((id) => this.unavailable.get(id)?.terminal !== null && this.unavailable.has(id));
+		for (const id of ids) this.unavailable.delete(id);
+		if (cleared.length > 0) this.deps.logger.info("CLIP model requirements-failed state cleared", { meta: {
+			tower: this.deps.tower,
+			nodeId: this.deps.nodeId(),
+			cleared,
+			why
+		} });
+		return cleared;
+	}
+	/** Models currently refused (cooldown or terminal) — exposed for tests. */
+	pending() {
+		return [...this.unavailable.keys()];
+	}
+	on(modelId) {
+		return {
+			modelId,
+			tower: this.deps.tower,
+			nodeId: this.deps.nodeId()
+		};
+	}
+	now() {
+		return (this.deps.now ?? Date.now)();
+	}
+};
 //#endregion
 //#region src/embedding-encoder/addon/clip-preprocessing.ts
 var CLIP_MEAN = [
@@ -520,11 +750,286 @@ function l2Normalize(vec) {
 	if (norm > 0) for (let i = 0; i < vec.length; i++) vec[i] /= norm;
 	return vec;
 }
+/**
+* A tower unused this long is disposed ({@link ClipTextEngines.evictIdle}) —
+* EXCEPT the tower of the model the cluster row names, which stays loaded for
+* the life of the process exactly as it did before D649: the steady-state
+* search must not pay a Python spawn plus a model load after a quiet quarter
+* hour. Only the OTHER towers (SigLIP2 after a comparison, the old model after
+* a flip) are let go when idle. When the active model is unknown (the row was
+* never read), nothing is evicted — the side that keeps memory as before.
+* The encoder is `placement: any-node` and cannot tell locally whether it is
+* the node that answers text queries, so towers are loaded ON DEMAND — never
+* prefetched on a model flip (565 MB on every node). The first query after a
+* flip pays the load; if it fails, the search fails loudly rather than reading
+* as "no results".
+*/
+var TEXT_ENGINE_IDLE_MS = 15 * 6e4;
+var ClipTextEngines = class {
+	deps;
+	/** Insertion order is recency: a hit is re-inserted at the end. */
+	engines = /* @__PURE__ */ new Map();
+	/** Single-flight per model: two concurrent first queries spawn one engine. */
+	inflight = /* @__PURE__ */ new Map();
+	/**
+	* Encodes in flight per model. An engine with any is NEVER evicted: disposing
+	* it would fail a search that is already running. When every held engine is
+	* busy the set goes over `maxEngines` temporarily and shrinks when one drains.
+	*/
+	busy = /* @__PURE__ */ new Map();
+	/** When each held tower last finished an encode (or was built). */
+	lastUsed = /* @__PURE__ */ new Map();
+	/** Bumped by {@link disposeAll}: a build landing after it is disposed on arrival. */
+	generation = 0;
+	constructor(deps) {
+		this.deps = deps;
+	}
+	/** Resolve a model id to its CLIP model, or throw naming the id. */
+	requireModel(modelId) {
+		const model = this.deps.registry.resolve(modelId);
+		if (model === null) throw new Error(`EmbeddingEncoder: "${modelId}" has no CLIP metadata — not a CLIP model`);
+		return model;
+	}
+	async encode(modelId, text) {
+		const model = this.requireModel(modelId);
+		this.busy.set(modelId, (this.busy.get(modelId) ?? 0) + 1);
+		let vector;
+		try {
+			vector = await (await this.engineFor(model)).encode(text);
+		} finally {
+			const left = (this.busy.get(modelId) ?? 1) - 1;
+			if (left > 0) this.busy.set(modelId, left);
+			else this.busy.delete(modelId);
+			if (this.engines.has(modelId)) this.lastUsed.set(modelId, this.now());
+			this.scheduleEviction();
+		}
+		if (vector.length !== model.meta.embeddingDim) throw new Error(`EmbeddingEncoder: ${model.meta.textModelId} produced ${String(vector.length)} dims, its metadata declares ${String(model.meta.embeddingDim)} — refusing the query rather than truncating it`);
+		return {
+			vector,
+			model
+		};
+	}
+	/**
+	* Dispose every IDLE tower unused for {@link TEXT_ENGINE_IDLE_MS} (a timer in
+	* the addon calls this), except the active model's. Returns the evicted
+	* model ids; each is logged. An unknown active model evicts nothing.
+	*/
+	async evictIdle(idleMs = TEXT_ENGINE_IDLE_MS) {
+		const active = this.deps.activeModelId();
+		if (active === null) return [];
+		const now = this.now();
+		const idle = [...this.engines.keys()].filter((id) => id !== active && (this.busy.get(id) ?? 0) === 0 && now - (this.lastUsed.get(id) ?? now) >= idleMs);
+		const evicted = [];
+		for (const modelId of idle) {
+			if ((this.busy.get(modelId) ?? 0) > 0 || !this.engines.has(modelId)) continue;
+			evicted.push(modelId);
+			this.deps.logger.info("CLIP text tower evicted — idle", { meta: {
+				modelId,
+				idleMs: now - (this.lastUsed.get(modelId) ?? now)
+			} });
+			await this.restart(modelId);
+		}
+		return evicted;
+	}
+	/** Live engines, for the memory watchdog. */
+	live() {
+		return this.engines;
+	}
+	/** Dispose one engine; the next query rebuilds it. */
+	async restart(modelId) {
+		const engine = this.engines.get(modelId);
+		if (engine === void 0) return;
+		this.engines.delete(modelId);
+		this.lastUsed.delete(modelId);
+		await engine.dispose();
+	}
+	/** Dispose every tower AND cancel the builds in flight (disposed as they land). */
+	async disposeAll() {
+		this.generation += 1;
+		const all = [...this.engines.values()];
+		this.engines.clear();
+		this.lastUsed.clear();
+		await Promise.all(all.map((e) => e.dispose()));
+		await Promise.allSettled(this.inflight.values());
+	}
+	async engineFor(model) {
+		const held = this.engines.get(model.modelId);
+		if (held !== void 0 && held.isAlive()) {
+			this.engines.delete(model.modelId);
+			this.engines.set(model.modelId, held);
+			return held;
+		}
+		if (held !== void 0) {
+			this.deps.logger.warn("CLIP text tower died — dropping it and rebuilding", { meta: {
+				modelId: model.modelId,
+				textModelId: model.meta.textModelId
+			} });
+			this.engines.delete(model.modelId);
+			this.lastUsed.delete(model.modelId);
+			this.deps.budget.record(model.modelId, "process died after loading");
+			held.dispose().catch(() => {});
+		}
+		const pending = this.inflight.get(model.modelId);
+		if (pending !== void 0) return pending;
+		this.deps.budget.check(model.modelId);
+		this.deps.requirements.check(model.modelId);
+		const textEntry = this.deps.textCatalog.find((e) => e.id === model.meta.textModelId);
+		if (textEntry === void 0) throw this.deps.requirements.refuse(model.modelId, new PermanentRequirementsFailure(`EmbeddingEncoder: text model "${model.meta.textModelId}" (for ${model.modelId}) is not in the text catalog`));
+		const generation = this.generation;
+		const build = this.buildAndLoad(model, textEntry);
+		this.inflight.set(model.modelId, build);
+		try {
+			const engine = await build;
+			if (this.generation !== generation) {
+				await engine.dispose();
+				throw new Error(`text tower for "${model.modelId}" cancelled: disposed while building`);
+			}
+			this.engines.set(model.modelId, engine);
+			this.lastUsed.set(model.modelId, this.now());
+			this.deps.logger.info("CLIP text tower loaded", { meta: {
+				modelId: model.modelId,
+				textModelId: model.meta.textModelId
+			} });
+			this.scheduleEviction();
+			return engine;
+		} finally {
+			this.inflight.delete(model.modelId);
+		}
+	}
+	/**
+	* Two stages, two owners (`model-requirements.ts`): `build` resolves files
+	* and runtime and constructs the tower — a throw there is refused by name
+	* and spends nothing; `initialize()` spawns and loads — a throw there is a
+	* load failure and spends the crash budget.
+	*/
+	async buildAndLoad(model, textEntry) {
+		let engine;
+		try {
+			engine = await this.deps.build({
+				model,
+				textEntry,
+				meta: model.meta
+			});
+		} catch (err) {
+			throw this.deps.requirements.refuse(model.modelId, err);
+		}
+		this.deps.requirements.satisfied(model.modelId);
+		try {
+			await engine.initialize();
+		} catch (err) {
+			this.deps.budget.record(model.modelId, `load failed: ${err instanceof Error ? err.message : String(err)}`);
+			throw err;
+		}
+		return engine;
+	}
+	now() {
+		return (this.deps.now ?? Date.now)();
+	}
+	/** Fire-and-log: eviction errors never reach an encode. */
+	scheduleEviction() {
+		this.evictBeyond(this.deps.maxEngines ?? 2).catch((err) => {
+			this.deps.logger.warn("CLIP text tower eviction failed", { meta: { error: err instanceof Error ? err.message : String(err) } });
+		});
+	}
+	/** Evict the coldest IDLE engines until at most `max` remain, or none is idle. */
+	async evictBeyond(max) {
+		while (this.engines.size > max) {
+			const coldestIdle = [...this.engines.keys()].find((id) => (this.busy.get(id) ?? 0) === 0);
+			if (coldestIdle === void 0) return;
+			await this.restart(coldestIdle);
+		}
+	}
+	/** Encodes in flight on a model — exposed for the eviction tests. */
+	inFlight(modelId) {
+		return this.busy.get(modelId) ?? 0;
+	}
+};
 //#endregion
 //#region src/embedding-encoder/addon/index.ts
-var EmbeddingEncoderAddon = class extends require_dist.BaseAddon {
-	imageRawEngine = null;
-	textEngine = null;
+/** Memory-watchdog key prefix of a text tower; the suffix is its CLIP model id. */
+var TEXT_ENGINE_KEY_PREFIX = "clip-text:";
+/** How often idle text towers are looked for (see `TEXT_ENGINE_IDLE_MS`). */
+var IDLE_SWEEP_MS = 6e4;
+/** A model URL answering one of these does not exist; retrying changes nothing. */
+var PERMANENT_HTTP_STATUS = new Set([404, 410]);
+var EmbeddingEncoderAddon = class extends require_clip_model_registry.BaseAddon {
+	/**
+	* Everything on this node that can be terminally refused (`failed-models-report.ts`):
+	* the respawn budgets per tower (D6, `crash-budget.ts`) and the requirements
+	* gates (`model-requirements.ts` — cooldown, and terminal for what can never
+	* be met). All in memory: a runner respawn starts them from zero. Every row
+	* and refusal names this node.
+	*/
+	towers = {
+		budgets: {
+			image: new CrashBudget({
+				tower: "image",
+				nodeId: () => this.localNodeId(),
+				logger: {
+					info: (message, extras) => this.ctx.logger.info(message, extras),
+					error: (message, extras) => this.ctx.logger.error(message, extras)
+				}
+			}),
+			text: new CrashBudget({
+				tower: "text",
+				nodeId: () => this.localNodeId(),
+				logger: {
+					info: (message, extras) => this.ctx.logger.info(message, extras),
+					error: (message, extras) => this.ctx.logger.error(message, extras)
+				}
+			})
+		},
+		requirements: {
+			image: new RequirementsGate({
+				tower: "image",
+				nodeId: () => this.localNodeId(),
+				logger: {
+					info: (message, extras) => this.ctx.logger.info(message, extras),
+					warn: (message, extras) => this.ctx.logger.warn(message, extras),
+					error: (message, extras) => this.ctx.logger.error(message, extras)
+				}
+			}),
+			text: new RequirementsGate({
+				tower: "text",
+				nodeId: () => this.localNodeId(),
+				logger: {
+					info: (message, extras) => this.ctx.logger.info(message, extras),
+					warn: (message, extras) => this.ctx.logger.warn(message, extras),
+					error: (message, extras) => this.ctx.logger.error(message, extras)
+				}
+			})
+		}
+	};
+	/** The image tower, one model at a time, single-flight per model (`model-engine-slot.ts`). */
+	imageEngine = new ModelEngineSlot((modelId) => this.buildImageEngine(modelId), this.towers.budgets.image, this.towers.requirements.image, (modelId) => this.ctx.logger.warn("CLIP image tower died — dropping it and rebuilding", { meta: { modelId } }));
+	/** One text tower per CLIP model, bounded (see `clip-text-engines.ts`). */
+	textEngines = new ClipTextEngines({
+		registry: require_clip_model_registry.BUILTIN_CLIP_MODELS,
+		textCatalog: require_clip_model_registry.CLIP_TEXT_MODELS,
+		build: (spec) => this.buildTextEngine(spec),
+		budget: this.towers.budgets.text,
+		requirements: this.towers.requirements.text,
+		activeModelId: () => this.activeModel.known(),
+		logger: {
+			info: (message, extras) => this.ctx.logger.info(message, extras),
+			warn: (message, extras) => this.ctx.logger.warn(message, extras)
+		}
+	});
+	/** Disposes NON-active text towers idle for `TEXT_ENGINE_IDLE_MS` (never prefetched). */
+	idleSweep = null;
+	/** The cluster row's CLIP model — what an unnamed request encodes in (D649). */
+	activeModel = new ActiveClipModel({
+		readRow: () => this.readClusterRow(),
+		fallbackModelId: () => require_clip_model_registry.BUILTIN_CLIP_MODELS.resolve(this.config.modelId) !== null ? this.config.modelId : require_clip_model_registry.DEFAULT_CLIP_MODEL,
+		now: () => Date.now(),
+		logger: {
+			info: (message, extras) => this.ctx.logger.info(message, extras),
+			warn: (message, extras) => this.ctx.logger.warn(message, extras)
+		},
+		onChange: (modelId) => {
+			clearFailedOnModelChange(this.towers, modelId);
+		}
+	});
 	models = null;
 	/**
 	* RSS bound + periodic memory telemetry for the two Python engines
@@ -536,27 +1041,27 @@ var EmbeddingEncoderAddon = class extends require_dist.BaseAddon {
 	* stopped in `onShutdown`.
 	*/
 	memoryGuard = null;
-	/** Single-flight guards for the lazy engine builds — a watchdog restart
-	*  followed by two concurrent encodes must not spawn the engine twice
-	*  (the same bug detection-pipeline fixed three times; see its
-	*  `engineFactoryInflight`). */
-	imageEngineInflight = null;
-	textEngineInflight = null;
 	constructor() {
-		super({ modelId: DEFAULT_CLIP_MODEL });
+		super({ modelId: require_clip_model_registry.DEFAULT_CLIP_MODEL });
 	}
 	async onInitialize() {
 		const modelsDir = await this.resolveModelsDir();
-		this.models = new _camstack_system_addon_utils.ModelDownloadService(modelsDir, [...CLIP_IMAGE_MODELS, ...CLIP_TEXT_MODELS]);
-		this.memoryGuard = new require_dist.PoolMemoryWatchdog({
-			policy: require_dist.resolvePoolMemoryPolicy(process.env),
+		this.models = new _camstack_system_addon_utils.ModelDownloadService(modelsDir, [...require_clip_model_registry.CLIP_IMAGE_MODELS, ...require_clip_model_registry.CLIP_TEXT_MODELS]);
+		this.memoryGuard = new require_clip_model_registry.PoolMemoryWatchdog({
+			policy: require_clip_model_registry.resolvePoolMemoryPolicy(process.env),
 			log: this.ctx.logger.child("pool-memory"),
 			sample: () => this.sampleEngineMemory(),
 			restart: (key) => this.restartEngineForMemory(key)
 		});
 		this.memoryGuard.start();
+		this.idleSweep = setInterval(() => {
+			this.textEngines.evictIdle().catch((err) => {
+				this.ctx.logger.warn("CLIP text tower idle sweep failed", { meta: { error: err instanceof Error ? err.message : String(err) } });
+			});
+		}, IDLE_SWEEP_MS);
+		this.idleSweep.unref?.();
 		return [{
-			capability: require_dist.embeddingEncoderCapability,
+			capability: require_clip_model_registry.embeddingEncoderCapability,
 			provider: this
 		}];
 	}
@@ -565,13 +1070,15 @@ var EmbeddingEncoderAddon = class extends require_dist.BaseAddon {
 	async sampleEngineMemory() {
 		const engines = [{
 			key: "clip-image",
-			pid: this.imageRawEngine?.getPid() ?? null,
-			requests: this.imageRawEngine?.getRequestCount() ?? 0
-		}, {
-			key: "clip-text",
-			pid: this.textEngine?.getPid() ?? null,
-			requests: this.textEngine?.getRequestCount() ?? 0
-		}];
+			modelId: this.imageEngine.held()?.modelId ?? null,
+			pid: this.imageEngine.held()?.engine.getPid() ?? null,
+			requests: this.imageEngine.held()?.engine.getRequestCount() ?? 0
+		}, ...[...this.textEngines.live()].map(([modelId, engine]) => ({
+			key: `${TEXT_ENGINE_KEY_PREFIX}${modelId}`,
+			modelId,
+			pid: engine.getPid(),
+			requests: engine.getRequestCount()
+		}))];
 		const out = [];
 		for (const engine of engines) {
 			if (engine.pid === null) continue;
@@ -589,7 +1096,7 @@ var EmbeddingEncoderAddon = class extends require_dist.BaseAddon {
 				pids: [engine.pid],
 				rssBytes: mem.rssBytes,
 				meta: {
-					modelId: this.config.modelId,
+					modelId: engine.modelId,
 					vmMb: mb(mem.vmBytes),
 					peakRssMb: mb(mem.hwmBytes),
 					swapMb: mb(mem.swapBytes),
@@ -606,110 +1113,125 @@ var EmbeddingEncoderAddon = class extends require_dist.BaseAddon {
 	*  surface errors, never silent loss. */
 	async restartEngineForMemory(key) {
 		if (key === "clip-image") {
-			const engine = this.imageRawEngine;
-			if (!engine) return;
-			this.imageRawEngine = null;
-			await engine.dispose();
+			await this.imageEngine.dispose();
 			return;
 		}
-		const engine = this.textEngine;
-		if (!engine) return;
-		this.textEngine = null;
-		await engine.dispose();
+		if (key.startsWith(TEXT_ENGINE_KEY_PREFIX)) await this.textEngines.restart(key.slice(10));
+	}
+	/** The cluster row's `clip-embedding` model, or `null` when unreadable. */
+	async readClusterRow() {
+		return require_clip_model_registry.resolveClusterModelPin(this.ctx.api, require_clip_model_registry.CLIP_EMBEDDING_STEP_ID, { warn: (message, extras) => this.ctx.logger.warn(message, extras) });
 	}
 	async encode(input) {
 		const { crop, width, height } = input;
-		await this.ensureImageEngine();
-		const meta = getModelMeta(this.config.modelId);
+		const model = this.textEngines.requireModel(await this.activeModel.get());
+		const imageEngine = await this.imageEngine.ensure(model.modelId);
+		const meta = model.meta;
 		const start = Date.now();
-		const preprocessed = preprocessForClip(Buffer.isBuffer(crop) ? crop : Buffer.from(crop), width, height, meta.inputSize, meta.inputSize);
-		const output = await this.imageRawEngine.run(preprocessed, [
+		const preprocessed = preprocessForClip(Buffer.isBuffer(crop) ? crop : Buffer.from(crop), width, height, model.inputSize, model.inputSize);
+		const output = await imageEngine.run(preprocessed, [
 			1,
 			3,
-			meta.inputSize,
-			meta.inputSize
+			model.inputSize,
+			model.inputSize
 		]);
-		const sliced = output.length > meta.embeddingDim ? output.slice(0, meta.embeddingDim) : output;
-		const normalized = l2Normalize(new Float32Array(sliced));
+		if (output.length !== meta.embeddingDim) throw new Error(`EmbeddingEncoder: ${model.modelId} image tower produced ${String(output.length)} dims, its metadata declares ${String(meta.embeddingDim)}`);
+		const normalized = l2Normalize(new Float32Array(output));
 		return {
 			embedding: Array.from(normalized),
 			inferenceMs: Date.now() - start
 		};
 	}
+	/**
+	* Encode a query in ONE model's space: the named `modelId`, else the cluster
+	* row's (D649). The token window, pad id, tokenizer and dimension all come
+	* from that model's catalog metadata.
+	*/
 	async encodeText(input) {
-		const { text } = input;
-		await this.ensureTextEngine();
-		const meta = getModelMeta(this.config.modelId);
+		const modelId = input.modelId ?? await this.activeModel.get();
 		const start = Date.now();
-		if (!this.textEngine) throw new Error("EmbeddingEncoder: text engine not loaded — ensureTextEngine() must run first");
-		const output = await this.textEngine.encode(text);
-		const sliced = output.length > meta.embeddingDim ? output.slice(0, meta.embeddingDim) : output;
-		const normalized = l2Normalize(new Float32Array(sliced));
+		const { vector } = await this.textEngines.encode(modelId, input.text);
 		return {
-			embedding: Array.from(normalized),
+			embedding: Array.from(l2Normalize(new Float32Array(vector))),
 			inferenceMs: Date.now() - start
 		};
 	}
+	/** THIS node's answer — the cap is one provider per node (see the cap's docblock). */
 	async getInfo() {
-		const meta = getModelMeta(this.config.modelId);
+		const model = this.textEngines.requireModel(await this.activeModel.get());
+		const nodeId = this.localNodeId();
 		return {
-			modelId: this.config.modelId,
-			embeddingDim: meta.embeddingDim,
-			ready: this.imageRawEngine !== null
+			modelId: model.modelId,
+			embeddingDim: model.meta.embeddingDim,
+			ready: this.imageEngine.held()?.modelId === model.modelId,
+			nodeId,
+			failedModels: [...reportFailedModels(this.towers.budgets)],
+			failedRequirements: [...reportFailedRequirements(this.towers.requirements)]
 		};
 	}
-	async ensureImageEngine() {
-		if (this.imageRawEngine) return;
-		if (this.imageEngineInflight) return this.imageEngineInflight;
-		const meta = getModelMeta(this.config.modelId);
-		const imageEntry = CLIP_IMAGE_MODELS.find((m) => m.id === meta.imageModelId);
-		if (!imageEntry) throw new Error(`EmbeddingEncoderAddon: unknown image model "${meta.imageModelId}"`);
-		const inflight = this.resolveForEntry(imageEntry, "image");
-		this.imageEngineInflight = inflight;
-		try {
-			await inflight;
-		} finally {
-			this.imageEngineInflight = null;
-		}
+	/** The operator's explicit clear of THIS node's `failed` state (D6); names the node. */
+	async resetFailedModels(input) {
+		return resetFailedModelsOn(this.localNodeId(), this.towers, input.modelId);
 	}
-	async ensureTextEngine() {
-		if (this.textEngine) return;
-		if (this.textEngineInflight) return this.textEngineInflight;
-		const meta = getModelMeta(this.config.modelId);
-		const textEntry = CLIP_TEXT_MODELS.find((m) => m.id === meta.textModelId);
-		if (!textEntry) throw new Error(`EmbeddingEncoderAddon: unknown text model "${meta.textModelId}"`);
-		const inflight = this.resolveForEntry(textEntry, "text");
-		this.textEngineInflight = inflight;
-		try {
-			await inflight;
-		} finally {
-			this.textEngineInflight = null;
-		}
+	/** The logical node (a forked child's `<node>/<addon>` id stripped to the node). */
+	localNodeId() {
+		return require_clip_model_registry.normalizeNodeId(this.ctx.kernel?.localNodeId);
 	}
-	async resolveForEntry(entry, target) {
-		const engineLogger = this.ctx.logger.withTags({ modelId: entry.id });
-		const modelPath = await this.models.ensure(entry.id, "onnx");
+	/**
+	* The REQUIREMENTS stage, shared by both towers: the embedded Python, its
+	* requirements, then the model file (downloaded on first use). Anything that
+	* throws here is refused as `model-requirements-unavailable` and spends no
+	* crash budget (`model-requirements.ts`). The runtime is asked for first —
+	* the cheap question before the 185–565 MB download (D54's rule).
+	*/
+	async prepareOnnx(entry) {
 		const pythonPath = await this.ctx.deps.ensurePython();
 		if (!pythonPath) throw new Error("EmbeddingEncoder: embedded Python is unavailable — cannot run ONNX embeddings. ctx.deps.ensurePython() returned null (portable Python download likely failed).");
 		const pythonDir = resolveEmbeddingPythonDir();
 		await this.ctx.deps.installPythonRequirements(node_path.join(pythonDir, "requirements-embedding.txt"));
-		if (target === "image") {
-			const rawEngine = new PythonRawTensorEngine(pythonPath, node_path.join(pythonDir, "raw_tensor_inference.py"), modelPath, engineLogger);
-			await rawEngine.initialize();
-			this.imageRawEngine = rawEngine;
-			return;
+		if (entry.formats.onnx === void 0) throw new PermanentRequirementsFailure(`EmbeddingEncoder: ${entry.id} has no onnx build in its catalog entry (formats: ${Object.keys(entry.formats).join(", ") || "none"}) — no download can supply it`);
+		let modelPath;
+		try {
+			modelPath = await this.models.ensure(entry.id, "onnx");
+		} catch (err) {
+			const status = downloadHttpStatusOf(err);
+			if (status !== null && PERMANENT_HTTP_STATUS.has(status)) throw new PermanentRequirementsFailure(`EmbeddingEncoder: ${entry.id} is not at its catalog URL (HTTP ${String(status)}) — fix the catalog entry`);
+			throw err;
 		}
-		const tokenizerPath = node_path.join(node_path.dirname(modelPath), TOKENIZER_FILE);
-		if (!node_fs.existsSync(tokenizerPath)) throw new Error(`EmbeddingEncoder: CLIP tokenizer not found at "${tokenizerPath}" — the tokenizer.json sibling download likely failed.`);
-		const textEngine = new PythonTextEncoderEngine(pythonPath, node_path.join(pythonDir, "text_encoder_inference.py"), modelPath, tokenizerPath, engineLogger);
-		await textEngine.initialize();
-		this.textEngine = textEngine;
+		return {
+			modelPath,
+			pythonPath,
+			pythonDir
+		};
+	}
+	async buildImageEngine(modelId) {
+		const entry = require_clip_model_registry.CLIP_IMAGE_MODELS.find((m) => m.id === modelId);
+		if (!entry) throw new PermanentRequirementsFailure(`EmbeddingEncoderAddon: unknown image model "${modelId}" — not in the CLIP image catalog`);
+		const { modelPath, pythonPath, pythonDir } = await this.prepareOnnx(entry);
+		return new PythonRawTensorEngine(pythonPath, node_path.join(pythonDir, "raw_tensor_inference.py"), modelPath, this.ctx.logger.withTags({ modelId: entry.id }));
+	}
+	/**
+	* One text tower. Tokenization happens IN Python via the HF `tokenizers`
+	* library, with the tokenizer the model's metadata names — a declared sibling
+	* of the text onnx, so `ModelDownloadService.ensure()` fetched it next to the
+	* model file — and the model's own token window.
+	*/
+	async buildTextEngine(spec) {
+		const { modelPath, pythonPath, pythonDir } = await this.prepareOnnx(spec.textEntry);
+		const tokenizerPath = node_path.join(node_path.dirname(modelPath), spec.meta.tokenizerFile);
+		if (!node_fs.existsSync(tokenizerPath)) throw new PermanentRequirementsFailure(`EmbeddingEncoder: tokenizer not found at "${tokenizerPath}" — the ${spec.meta.tokenizerFile} sibling download of ${spec.textEntry.id} likely failed.`);
+		return new PythonTextEncoderEngine(pythonPath, node_path.join(pythonDir, "text_encoder_inference.py"), modelPath, tokenizerPath, {
+			contextLength: spec.meta.contextLength,
+			padId: spec.meta.padId
+		}, this.ctx.logger.withTags({ modelId: spec.textEntry.id }));
 	}
 	async onShutdown() {
 		this.memoryGuard?.stop();
+		if (this.idleSweep !== null) clearInterval(this.idleSweep);
+		this.idleSweep = null;
 		this.memoryGuard = null;
-		await this.imageRawEngine?.dispose();
-		await this.textEngine?.dispose();
+		await this.imageEngine.dispose();
+		await this.textEngines.disposeAll();
 	}
 	globalSettingsSchema() {
 		return this.schema({ sections: [{
@@ -719,9 +1241,9 @@ var EmbeddingEncoderAddon = class extends require_dist.BaseAddon {
 			fields: [{
 				type: "text",
 				key: "modelId",
-				label: "Model ID",
-				description: "CLIP model identifier to use for image/text embedding",
-				default: DEFAULT_CLIP_MODEL
+				label: "Fallback model ID",
+				description: "Used only until the cluster \"Semantic search model\" row has been read once. The encoder follows that row (D649).",
+				default: require_clip_model_registry.DEFAULT_CLIP_MODEL
 			}]
 		}] });
 	}
@@ -742,6 +1264,18 @@ function resolveEmbeddingPythonDir() {
 	for (const c of candidates) if (node_fs.existsSync(node_path.join(c, "raw_tensor_inference.py"))) return c;
 	throw new Error(`EmbeddingEncoder: python/ dir (raw_tensor_inference.py) not found. Searched:\n${candidates.join("\n")}`);
 }
+/**
+* HTTP status of a model-download failure, recognised by SHAPE (`name` +
+* numeric `status`), never by `instanceof` or a framework import.
+* `@camstack/system` is host-resolved (not bundled), so importing a guard it
+* only exports from a newer server would stop this whole entry from linking
+* on a node still running the older server — a deploy-order hazard for a
+* one-line classification. `null` = not an HTTP answer (unreachable, other).
+*/
+function downloadHttpStatusOf(err) {
+	if (err instanceof Error && err.name === "ModelDownloadHttpError" && "status" in err && typeof err.status === "number") return err.status;
+	return null;
+}
 //#endregion
 exports.EmbeddingEncoderAddon = EmbeddingEncoderAddon;
 exports.default = EmbeddingEncoderAddon;