@remit/search-index-worker 0.0.21 → 0.0.22

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remit/search-index-worker",
-  "version": "0.0.21",
+  "version": "0.0.22",
   "type": "module",
   "main": "dist/index.js",
   "exports": {

package/src/adaptive-embedder.test.ts

@@ -0,0 +1,523 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import type { EmbeddingService } from "@remit/search-service";
+import {
+	type AdaptiveEmbeddingConfig,
+	createAdaptiveEmbeddingService,
+	type EmbeddingPlan,
+	type GovernorDeps,
+	MemoryGovernor,
+	MemoryStallTimeoutError,
+	readAdaptiveEmbeddingConfigFromEnv,
+} from "./adaptive-embedder.js";
+import type { MemoryReader } from "./memory.js";
+
+const MB = 1024 * 1024;
+
+const CONFIG: AdaptiveEmbeddingConfig = {
+	minBatchSize: 2,
+	maxBatchSize: 8,
+	maxConcurrency: 2,
+	headroomBytes: 768 * MB,
+	rampMarginBytes: 256 * MB,
+	rampAfterReadings: 3,
+	rssCeilingBytes: 1536 * MB,
+	criticalBytes: 384 * MB,
+	pauseMs: 10,
+	stallMaxMs: 100,
+};
+
+/** Comfortably above `headroomBytes + rampMarginBytes`. */
+const ROOMY = 2000;
+/** Above the shed threshold but inside the ramp margin: the dead band. */
+const DEAD_BAND = [800, 780, 900, 820, 1000, 790];
+
+interface Reading {
+	availableMb: number;
+	rssMb?: number;
+}
+
+/** One entry per read; the last value repeats forever. */
+const reads = (script: readonly Reading[]): MemoryReader => {
+	let next = 0;
+	return () => {
+		const entry = script[Math.min(next, script.length - 1)];
+		next += 1;
+		return {
+			availableBytes: entry.availableMb * MB,
+			rssBytes: (entry.rssMb ?? 512) * MB,
+		};
+	};
+};
+
+const available = (...availableMb: number[]): MemoryReader =>
+	reads(availableMb.map((mb) => ({ availableMb: mb })));
+
+class Harness {
+	readonly plans: EmbeddingPlan[] = [];
+	readonly sleeps: number[] = [];
+	readonly lines: string[] = [];
+	stalls = 0;
+	beats = 0;
+	clock = 0;
+	beatFails = false;
+	readonly deps: GovernorDeps;
+
+	constructor(readMemory: MemoryReader) {
+		const record = (message: string) => {
+			this.lines.push(message);
+		};
+		this.deps = {
+			readMemory,
+			// A fake clock advanced by the waits themselves, so the stall budget is
+			// exercised without spending it.
+			sleep: async (ms) => {
+				this.sleeps.push(ms);
+				this.clock += ms;
+			},
+			now: () => this.clock,
+			log: { info: record, warn: record, error: record },
+			beat: async () => {
+				this.beats += 1;
+				if (this.beatFails) throw new Error("no space left on device");
+			},
+			onPlan: (plan) => {
+				this.plans.push(plan);
+			},
+			onStall: () => {
+				this.stalls += 1;
+			},
+		};
+	}
+}
+
+const harness = (readMemory: MemoryReader): Harness => new Harness(readMemory);
+
+const settleTimes = (governor: MemoryGovernor, times: number): void => {
+	for (let i = 0; i < times; i++) governor.settle();
+};
+
+const embedderRecording = (): {
+	service: EmbeddingService;
+	batches: number[];
+	maxInFlight: () => number;
+} => {
+	const batches: number[] = [];
+	let inFlight = 0;
+	let peak = 0;
+	return {
+		batches,
+		maxInFlight: () => peak,
+		service: {
+			dimensions: 3,
+			embeddingId: "fake@3",
+			embed: async (texts: string[]) => {
+				inFlight += 1;
+				peak = Math.max(peak, inFlight);
+				batches.push(texts.length);
+				await Promise.resolve();
+				inFlight -= 1;
+				return texts.map(() => [0, 0, 0]);
+			},
+		},
+	};
+};
+
+describe("the memory governor", () => {
+	it("starts at the floor: the smallest batch, one inference", () => {
+		const governor = new MemoryGovernor(CONFIG, harness(available(ROOMY)).deps);
+		assert.deepEqual(governor.plan, { batchSize: 2, concurrency: 1 });
+	});
+
+	it("ramps the batch first, then parallelism, while headroom holds", () => {
+		const h = harness(available(ROOMY));
+		const governor = new MemoryGovernor(CONFIG, h.deps);
+		settleTimes(governor, CONFIG.rampAfterReadings);
+		assert.deepEqual(governor.plan, { batchSize: 4, concurrency: 1 });
+		settleTimes(governor, CONFIG.rampAfterReadings);
+		assert.deepEqual(governor.plan, { batchSize: 8, concurrency: 1 });
+		settleTimes(governor, CONFIG.rampAfterReadings);
+		assert.deepEqual(governor.plan, { batchSize: 8, concurrency: 2 });
+		assert.deepEqual(h.plans.at(-1), governor.plan);
+	});
+
+	it("makes a ramp cost several consecutive readings", () => {
+		const h = harness(available(ROOMY));
+		const governor = new MemoryGovernor(CONFIG, h.deps);
+		settleTimes(governor, CONFIG.rampAfterReadings - 1);
+		assert.deepEqual(governor.plan, { batchSize: 2, concurrency: 1 });
+		governor.settle();
+		assert.deepEqual(governor.plan, { batchSize: 4, concurrency: 1 });
+	});
+
+	it("never ramps past the configured ceiling, and stops logging there", () => {
+		const h = harness(available(ROOMY));
+		const governor = new MemoryGovernor(CONFIG, h.deps);
+		settleTimes(governor, 60);
+		assert.deepEqual(governor.plan, { batchSize: 8, concurrency: 2 });
+		// One line per change of plan, not one per batch: three changes, three
+		// lines, and nothing for the settles that changed nothing.
+		assert.equal(h.lines.length, 3);
+	});
+
+	// The oscillation this exists to prevent: a box parked near the threshold,
+	// ramping and shedding on alternate batches, logging every one of them.
+	it("holds its plan while readings hover in the dead band", () => {
+		const h = harness(reads(DEAD_BAND.map((mb) => ({ availableMb: mb }))));
+		const governor = new MemoryGovernor(CONFIG, h.deps);
+		settleTimes(governor, 30);
+		assert.deepEqual(governor.plan, { batchSize: 2, concurrency: 1 });
+		assert.deepEqual(h.lines, []);
+	});
+
+	it("holds a ramped plan in the dead band too, rather than shedding it", () => {
+		const script = [
+			...Array(CONFIG.rampAfterReadings).fill({ availableMb: ROOMY }),
+			...DEAD_BAND.map((mb) => ({ availableMb: mb })),
+		];
+		const h = harness(reads(script));
+		const governor = new MemoryGovernor(CONFIG, h.deps);
+		settleTimes(governor, CONFIG.rampAfterReadings);
+		assert.deepEqual(governor.plan, { batchSize: 4, concurrency: 1 });
+
+		settleTimes(governor, 30);
+		assert.deepEqual(governor.plan, { batchSize: 4, concurrency: 1 });
+		assert.equal(h.lines.length, 1);
+	});
+
+	// A shed cannot lower resident memory that onnxruntime's arena has already
+	// claimed, so the ramp is gated on this process's own RSS as well: free
+	// memory on the box is no licence to grow when the worker is already the
+	// reason it might run out.
+	it("never ramps while its own RSS is above the ceiling", () => {
+		const h = harness(reads([{ availableMb: 8000, rssMb: 2000 }]));
+		const governor = new MemoryGovernor(CONFIG, h.deps);
+		settleTimes(governor, 30);
+		assert.deepEqual(governor.plan, { batchSize: 2, concurrency: 1 });
+	});
+
+	it("sheds a ramped plan when its own RSS crosses the ceiling", () => {
+		const script = [
+			...Array(6).fill({ availableMb: ROOMY, rssMb: 512 }),
+			{ availableMb: ROOMY, rssMb: 2000 },
+		];
+		const h = harness(reads(script));
+		const governor = new MemoryGovernor(CONFIG, h.deps);
+		settleTimes(governor, 6);
+		assert.deepEqual(governor.plan, { batchSize: 8, concurrency: 1 });
+		governor.settle();
+		assert.deepEqual(governor.plan, { batchSize: 4, concurrency: 1 });
+	});
+
+	it("halves the batch and drops to one inference when headroom goes", () => {
+		const h = harness(available(ROOMY, ROOMY, ROOMY, 500));
+		const governor = new MemoryGovernor(CONFIG, h.deps);
+		settleTimes(governor, CONFIG.rampAfterReadings);
+		assert.deepEqual(governor.plan, { batchSize: 4, concurrency: 1 });
+		governor.settle();
+		assert.deepEqual(governor.plan, { batchSize: 2, concurrency: 1 });
+	});
+
+	it("paces itself between batches once it has shed", async () => {
+		const h = harness(available(ROOMY, ROOMY, ROOMY, 500));
+		const governor = new MemoryGovernor(CONFIG, h.deps);
+		settleTimes(governor, CONFIG.rampAfterReadings + 1);
+
+		assert.equal(await governor.admit(), "admitted");
+		assert.deepEqual(h.sleeps, [CONFIG.pauseMs]);
+		// The pause is per shed, not sticky: an admit that follows no shed runs on.
+		assert.equal(await governor.admit(), "admitted");
+		assert.deepEqual(h.sleeps, [CONFIG.pauseMs]);
+	});
+
+	it("keeps pacing at the floor, where there is no smaller batch left", async () => {
+		const h = harness(available(500));
+		const governor = new MemoryGovernor(CONFIG, h.deps);
+		governor.settle();
+		assert.deepEqual(governor.plan, { batchSize: 2, concurrency: 1 });
+		assert.deepEqual(h.lines, []);
+		assert.equal(await governor.admit(), "admitted");
+		assert.deepEqual(h.sleeps, [CONFIG.pauseMs]);
+	});
+
+	it("stops and waits below the critical floor, then resumes", async () => {
+		const h = harness(available(ROOMY, ROOMY, ROOMY, 300, 300, 1000));
+		const governor = new MemoryGovernor(CONFIG, h.deps);
+		settleTimes(governor, CONFIG.rampAfterReadings);
+		assert.deepEqual(governor.plan, { batchSize: 4, concurrency: 1 });
+
+		assert.equal(await governor.admit(), "admitted");
+		assert.equal(h.stalls, 1);
+		assert.equal(h.sleeps.length, 2);
+		// A stop is the loudest signal the worker has, and it comes back at the
+		// floor rather than resuming at the size that emptied the box.
+		assert.deepEqual(governor.plan, { batchSize: 2, concurrency: 1 });
+		assert.match(h.lines.at(-2) ?? "", /paused/);
+		assert.match(h.lines.at(-1) ?? "", /resumed/);
+	});
+
+	// The poller's visibility timeout redelivers the record underneath a handler
+	// that waits too long, so the wait ends first and says so.
+	it("gives up once the stall budget is spent", async () => {
+		const h = harness(available(300));
+		const governor = new MemoryGovernor(CONFIG, h.deps);
+
+		assert.equal(await governor.admit(), "expired");
+		assert.equal(h.clock, CONFIG.stallMaxMs);
+		assert.match(h.lines.at(-1) ?? "", /gave up/);
+	});
+
+	it("keeps the poll loop's heartbeat fresh while it waits", async () => {
+		const h = harness(available(300));
+		const governor = new MemoryGovernor(CONFIG, h.deps);
+
+		await governor.admit();
+		assert.equal(h.beats, CONFIG.stallMaxMs / CONFIG.pauseMs);
+	});
+
+	it("stays up when the heartbeat cannot be written", async () => {
+		const h = harness(available(300));
+		h.beatFails = true;
+		const governor = new MemoryGovernor(CONFIG, h.deps);
+
+		assert.equal(await governor.admit(), "expired");
+		assert.ok(h.lines.some((line) => /heartbeat/.test(line)));
+	});
+
+	it("does not stall while the box is merely tight", async () => {
+		const h = harness(available(500));
+		const governor = new MemoryGovernor(CONFIG, h.deps);
+		assert.equal(await governor.admit(), "admitted");
+		assert.equal(h.stalls, 0);
+		assert.deepEqual(h.sleeps, []);
+	});
+});
+
+describe("the governed embedder", () => {
+	it("sends the floor batch first and returns every vector in order", async () => {
+		const inner = embedderRecording();
+		const h = harness(available(ROOMY));
+		const service = createAdaptiveEmbeddingService(
+			inner.service,
+			new MemoryGovernor(CONFIG, h.deps),
+		);
+		const texts = Array.from({ length: 20 }, (_, i) => `chunk ${i}`);
+
+		const vectors = await service.embed(texts);
+
+		assert.equal(inner.batches[0], CONFIG.minBatchSize);
+		assert.equal(
+			inner.batches.reduce((sum, size) => sum + size, 0),
+			texts.length,
+		);
+		assert.equal(vectors.length, texts.length);
+	});
+
+	it("never sends more than the configured maximum in one call", async () => {
+		const inner = embedderRecording();
+		const h = harness(available(ROOMY));
+		const service = createAdaptiveEmbeddingService(
+			inner.service,
+			new MemoryGovernor(CONFIG, h.deps),
+		);
+
+		await service.embed(Array.from({ length: 500 }, (_, i) => `chunk ${i}`));
+
+		assert.ok(Math.max(...inner.batches) <= CONFIG.maxBatchSize);
+		assert.ok(inner.maxInFlight() <= CONFIG.maxConcurrency);
+	});
+
+	it("keeps one inference in flight on a box that never has headroom", async () => {
+		const inner = embedderRecording();
+		const h = harness(available(500));
+		const service = createAdaptiveEmbeddingService(
+			inner.service,
+			new MemoryGovernor(CONFIG, h.deps),
+		);
+
+		await service.embed(Array.from({ length: 40 }, (_, i) => `chunk ${i}`));
+
+		assert.deepEqual(new Set(inner.batches), new Set([CONFIG.minBatchSize]));
+		assert.equal(inner.maxInFlight(), 1);
+	});
+
+	it("embeds nothing, and reads nothing, for an empty list", async () => {
+		const inner = embedderRecording();
+		let readCount = 0;
+		const h = harness(() => {
+			readCount += 1;
+			return { rssBytes: 0, availableBytes: ROOMY * MB };
+		});
+		const service = createAdaptiveEmbeddingService(
+			inner.service,
+			new MemoryGovernor(CONFIG, h.deps),
+		);
+
+		assert.deepEqual(await service.embed([]), []);
+		assert.deepEqual(inner.batches, []);
+		assert.equal(readCount, 0);
+	});
+
+	it("passes the embedding identity through, so no index is invalidated", () => {
+		const inner = embedderRecording();
+		const service = createAdaptiveEmbeddingService(
+			inner.service,
+			new MemoryGovernor(CONFIG, harness(available(ROOMY)).deps),
+		);
+		assert.equal(service.embeddingId, inner.service.embeddingId);
+		assert.equal(service.dimensions, inner.service.dimensions);
+	});
+
+	it("raises a stall timeout rather than embedding past the budget", async () => {
+		const inner = embedderRecording();
+		const h = harness(available(300));
+		const service = createAdaptiveEmbeddingService(
+			inner.service,
+			new MemoryGovernor(CONFIG, h.deps),
+			CONFIG.stallMaxMs,
+		);
+
+		await assert.rejects(
+			() => service.embed(["one"]),
+			(error: unknown) => error instanceof MemoryStallTimeoutError,
+		);
+		assert.deepEqual(inner.batches, []);
+	});
+
+	// The throttle paces work; it never turns a fault into a quiet retry.
+	it("lets a model failure propagate", async () => {
+		const h = harness(available(ROOMY));
+		const service = createAdaptiveEmbeddingService(
+			{
+				dimensions: 3,
+				embeddingId: "broken@3",
+				embed: async () => {
+					throw new Error("model could not be loaded");
+				},
+			},
+			new MemoryGovernor(CONFIG, h.deps),
+		);
+
+		await assert.rejects(
+			() => service.embed(["one"]),
+			/model could not be loaded/,
+		);
+	});
+});
+
+const withEnv = (
+	overrides: Record<string, string | undefined>,
+	fn: () => void,
+): void => {
+	const saved: Record<string, string | undefined> = {};
+	for (const key of Object.keys(overrides)) saved[key] = process.env[key];
+	for (const [key, value] of Object.entries(overrides)) {
+		if (value === undefined) delete process.env[key];
+		else process.env[key] = value;
+	}
+	try {
+		fn();
+	} finally {
+		for (const [key, value] of Object.entries(saved)) {
+			if (value === undefined) delete process.env[key];
+			else process.env[key] = value;
+		}
+	}
+};
+
+const UNSET = {
+	SEARCH_INDEX_EMBED_BATCH_MIN: undefined,
+	SEARCH_INDEX_EMBED_BATCH_MAX: undefined,
+	SEARCH_INDEX_EMBED_CONCURRENCY_MAX: undefined,
+	SEARCH_INDEX_EMBED_RAMP_AFTER: undefined,
+	SEARCH_INDEX_MEMORY_HEADROOM_MB: undefined,
+	SEARCH_INDEX_MEMORY_RAMP_MARGIN_MB: undefined,
+	SEARCH_INDEX_RSS_CEILING_MB: undefined,
+	SEARCH_INDEX_MEMORY_CRITICAL_MB: undefined,
+	SEARCH_INDEX_MEMORY_PAUSE_MS: undefined,
+	SEARCH_INDEX_MEMORY_STALL_MAX_MS: undefined,
+};
+
+describe("the configured thresholds", () => {
+	it("defaults to the documented floor, ceiling and thresholds", () => {
+		withEnv(UNSET, () => {
+			assert.deepEqual(readAdaptiveEmbeddingConfigFromEnv(), {
+				minBatchSize: 4,
+				maxBatchSize: 32,
+				maxConcurrency: 2,
+				rampAfterReadings: 3,
+				headroomBytes: 768 * MB,
+				rampMarginBytes: 256 * MB,
+				rssCeilingBytes: 1536 * MB,
+				criticalBytes: 384 * MB,
+				pauseMs: 2000,
+				stallMaxMs: 240_000,
+			});
+		});
+	});
+
+	// The stall has to end before the queue redelivers the record underneath it.
+	it("gives up well inside the poller's 300 s visibility timeout", () => {
+		withEnv(UNSET, () => {
+			assert.ok(readAdaptiveEmbeddingConfigFromEnv().stallMaxMs < 300_000);
+		});
+	});
+
+	it("reads megabytes from the environment", () => {
+		withEnv(
+			{
+				...UNSET,
+				SEARCH_INDEX_MEMORY_HEADROOM_MB: "2048",
+				SEARCH_INDEX_MEMORY_CRITICAL_MB: "1024",
+				SEARCH_INDEX_RSS_CEILING_MB: "4096",
+			},
+			() => {
+				const config = readAdaptiveEmbeddingConfigFromEnv();
+				assert.equal(config.headroomBytes, 2048 * MB);
+				assert.equal(config.criticalBytes, 1024 * MB);
+				assert.equal(config.rssCeilingBytes, 4096 * MB);
+			},
+		);
+	});
+
+	it("refuses a critical floor at or above the ramp headroom", () => {
+		withEnv(
+			{
+				...UNSET,
+				SEARCH_INDEX_MEMORY_HEADROOM_MB: "512",
+				SEARCH_INDEX_MEMORY_CRITICAL_MB: "512",
+			},
+			() => {
+				assert.throws(
+					readAdaptiveEmbeddingConfigFromEnv,
+					/SEARCH_INDEX_MEMORY_CRITICAL_MB must be below/,
+				);
+			},
+		);
+	});
+
+	it("refuses a floor batch above the ceiling", () => {
+		withEnv(
+			{
+				...UNSET,
+				SEARCH_INDEX_EMBED_BATCH_MIN: "64",
+				SEARCH_INDEX_EMBED_BATCH_MAX: "32",
+			},
+			() => {
+				assert.throws(
+					readAdaptiveEmbeddingConfigFromEnv,
+					/SEARCH_INDEX_EMBED_BATCH_MIN must not exceed/,
+				);
+			},
+		);
+	});
+
+	it("refuses a value that is not a positive integer", () => {
+		withEnv({ ...UNSET, SEARCH_INDEX_EMBED_BATCH_MAX: "0" }, () => {
+			assert.throws(
+				readAdaptiveEmbeddingConfigFromEnv,
+				/SEARCH_INDEX_EMBED_BATCH_MAX must be a positive integer/,
+			);
+		});
+	});
+});

package/src/adaptive-embedder.ts

@@ -0,0 +1,377 @@
+import type { EmbeddingService } from "@remit/search-service";
+import type { MemoryReader, MemoryReading } from "./memory.js";
+
+/**
+ * How much work the worker allows itself right now: how many chunk texts go
+ * into one `embed` call, and how many such calls are in flight at once.
+ */
+export interface EmbeddingPlan {
+	readonly batchSize: number;
+	readonly concurrency: number;
+}
+
+export interface AdaptiveEmbeddingConfig {
+	/** The plan the worker starts at and sheds back to. */
+	readonly minBatchSize: number;
+	readonly maxBatchSize: number;
+	readonly maxConcurrency: number;
+	/** Shed below this much free memory on the box. */
+	readonly headroomBytes: number;
+	/** Ramp only above `headroomBytes + rampMarginBytes`. */
+	readonly rampMarginBytes: number;
+	/** Consecutive comfortable readings a ramp costs. */
+	readonly rampAfterReadings: number;
+	/** Shed at or above this much resident memory in this process. */
+	readonly rssCeilingBytes: number;
+	/** Stop and wait while free memory on the box is below this. */
+	readonly criticalBytes: number;
+	/** Wait between batches after shedding, and between reads while stopped. */
+	readonly pauseMs: number;
+	/** Give the message back to the queue after stopping this long. */
+	readonly stallMaxMs: number;
+}
+
+export interface GovernorLog {
+	info(message: string, fields?: Record<string, unknown>): void;
+	warn(message: string, fields?: Record<string, unknown>): void;
+	error(message: string, fields?: Record<string, unknown>): void;
+}
+
+export interface GovernorDeps {
+	readonly readMemory: MemoryReader;
+	readonly sleep: (ms: number) => Promise<void>;
+	readonly now: () => number;
+	readonly log: GovernorLog;
+	/**
+	 * The poll loop's own liveness file. A stop happens inside a handler, which
+	 * is between two receives and so between two beats — without this the
+	 * container's healthcheck reads a stall as a wedged loop.
+	 */
+	readonly beat?: () => Promise<void>;
+	readonly onPlan?: (plan: EmbeddingPlan) => void;
+	readonly onStall?: () => void;
+}
+
+const MB = 1024 * 1024;
+
+export const DEFAULT_ADAPTIVE_EMBEDDING_CONFIG: AdaptiveEmbeddingConfig = {
+	minBatchSize: 4,
+	maxBatchSize: 32,
+	maxConcurrency: 2,
+	headroomBytes: 768 * MB,
+	rampMarginBytes: 256 * MB,
+	rampAfterReadings: 3,
+	rssCeilingBytes: 1536 * MB,
+	criticalBytes: 384 * MB,
+	pauseMs: 2000,
+	stallMaxMs: 240_000,
+};
+
+/**
+ * Raised when the box stayed below the critical floor for the whole stall
+ * budget. The handler already treats any throw from an upsert as a per-message
+ * failure, which is exactly the wanted outcome: the record is reported as a
+ * batch item failure and redelivered, rather than held past the queue's
+ * visibility timeout while the process waits.
+ */
+export class MemoryStallTimeoutError extends Error {
+	readonly code = "ERR_SEARCH_INDEX_MEMORY_STALL";
+	constructor(waitedMs: number) {
+		super(
+			`Search index waited ${Math.round(waitedMs / 1000)}s for the box to ` +
+				"free memory and gave up; the message goes back on the queue",
+		);
+		this.name = "MemoryStallTimeoutError";
+	}
+}
+
+const positiveInt = (name: string, raw: string): number => {
+	const parsed = Number(raw);
+	if (!Number.isInteger(parsed) || parsed <= 0) {
+		throw new Error(`${name} must be a positive integer, got: ${raw}`);
+	}
+	return parsed;
+};
+
+/** `fallback` is already in the target unit; `scale` converts the env value. */
+const fromEnv = (name: string, fallback: number, scale = 1): number => {
+	const raw = process.env[name];
+	if (!raw) return fallback;
+	return positiveInt(name, raw) * scale;
+};
+
+/**
+ * Every threshold is an env var so the same image bounds itself against a 4 GB
+ * VPS and a 32 GB box without a rebuild. A configuration that cannot hold —
+ * a critical floor at or above the ramp headroom, a floor batch above the
+ * ceiling — is a startup error, not something to correct silently at runtime.
+ */
+export const readAdaptiveEmbeddingConfigFromEnv =
+	(): AdaptiveEmbeddingConfig => {
+		const d = DEFAULT_ADAPTIVE_EMBEDDING_CONFIG;
+		const config: AdaptiveEmbeddingConfig = {
+			minBatchSize: fromEnv("SEARCH_INDEX_EMBED_BATCH_MIN", d.minBatchSize),
+			maxBatchSize: fromEnv("SEARCH_INDEX_EMBED_BATCH_MAX", d.maxBatchSize),
+			maxConcurrency: fromEnv(
+				"SEARCH_INDEX_EMBED_CONCURRENCY_MAX",
+				d.maxConcurrency,
+			),
+			rampAfterReadings: fromEnv(
+				"SEARCH_INDEX_EMBED_RAMP_AFTER",
+				d.rampAfterReadings,
+			),
+			headroomBytes: fromEnv(
+				"SEARCH_INDEX_MEMORY_HEADROOM_MB",
+				d.headroomBytes,
+				MB,
+			),
+			rampMarginBytes: fromEnv(
+				"SEARCH_INDEX_MEMORY_RAMP_MARGIN_MB",
+				d.rampMarginBytes,
+				MB,
+			),
+			rssCeilingBytes: fromEnv(
+				"SEARCH_INDEX_RSS_CEILING_MB",
+				d.rssCeilingBytes,
+				MB,
+			),
+			criticalBytes: fromEnv(
+				"SEARCH_INDEX_MEMORY_CRITICAL_MB",
+				d.criticalBytes,
+				MB,
+			),
+			pauseMs: fromEnv("SEARCH_INDEX_MEMORY_PAUSE_MS", d.pauseMs),
+			stallMaxMs: fromEnv("SEARCH_INDEX_MEMORY_STALL_MAX_MS", d.stallMaxMs),
+		};
+		if (config.minBatchSize > config.maxBatchSize) {
+			throw new Error(
+				"SEARCH_INDEX_EMBED_BATCH_MIN must not exceed SEARCH_INDEX_EMBED_BATCH_MAX",
+			);
+		}
+		if (config.criticalBytes >= config.headroomBytes) {
+			throw new Error(
+				"SEARCH_INDEX_MEMORY_CRITICAL_MB must be below SEARCH_INDEX_MEMORY_HEADROOM_MB",
+			);
+		}
+		return config;
+	};
+
+type Admission = "admitted" | "expired";
+
+/**
+ * Bounds the worker's resident memory against the box it shares, which
+ * `--max-old-space-size` cannot: the embedding model, its inference arenas and
+ * its tensors are native allocations outside V8's old space (#585).
+ *
+ * It steers on two numbers, because neither is sufficient alone. The box's
+ * `MemAvailable` says whether the rest of the stack still has room. This
+ * process's own RSS says whether the worker is the reason it does not — and it
+ * is the one a shed cannot walk back: onnxruntime sizes its CPU arena to the
+ * largest batch it has ever run and does not hand that back, so a plan that
+ * ramps on free memory alone raises a floor it can never lower. Above the RSS
+ * ceiling the worker sheds and stays shed.
+ *
+ * Ramping costs several consecutive comfortable readings and needs a margin
+ * above the shed threshold; shedding is immediate at it. Without that gap a box
+ * sitting near the threshold — the ordinary steady state — would ramp and shed
+ * on alternate batches, logging every one of them and halving throughput for
+ * nothing.
+ *
+ * Below the critical floor it stops entirely rather than pushing the host into
+ * swap, where the kernel picks its OOM victim by size and takes the backend
+ * rather than the indexer. That stop is bounded: past the budget the message
+ * goes back on the queue, because a handler that waits longer than the queue's
+ * visibility timeout has its record redelivered underneath it anyway.
+ */
+export class MemoryGovernor {
+	private batchSize: number;
+	private concurrency = 1;
+	private pauseBeforeNextBatch = false;
+	private comfortableReadings = 0;
+
+	constructor(
+		private readonly config: AdaptiveEmbeddingConfig,
+		private readonly deps: GovernorDeps,
+	) {
+		this.batchSize = config.minBatchSize;
+	}
+
+	get plan(): EmbeddingPlan {
+		return { batchSize: this.batchSize, concurrency: this.concurrency };
+	}
+
+	/** Blocks until the box can afford the next batch, or the budget runs out. */
+	admit = async (): Promise<Admission> => {
+		let reading = this.deps.readMemory();
+		if (reading.availableBytes >= this.config.criticalBytes) {
+			if (!this.pauseBeforeNextBatch) return "admitted";
+			this.pauseBeforeNextBatch = false;
+			await this.deps.sleep(this.config.pauseMs);
+			return "admitted";
+		}
+
+		this.deps.onStall?.();
+		this.deps.log.warn(
+			"Search index paused: the box is below the critical memory floor",
+			this.fields(reading),
+		);
+		this.reset();
+		const startedAt = this.deps.now();
+		while (reading.availableBytes < this.config.criticalBytes) {
+			const waitedMs = this.deps.now() - startedAt;
+			if (waitedMs >= this.config.stallMaxMs) {
+				this.deps.log.warn("Search index gave up waiting for memory", {
+					waitedMs,
+					...this.fields(reading),
+				});
+				return "expired";
+			}
+			await this.keepAlive();
+			await this.deps.sleep(this.config.pauseMs);
+			reading = this.deps.readMemory();
+		}
+		this.pauseBeforeNextBatch = false;
+		this.deps.log.info(
+			"Search index resumed: memory recovered",
+			this.fields(reading),
+		);
+		return "admitted";
+	};
+
+	/** Measures what the batch just cost and moves the plan at most one step. */
+	settle = (): void => {
+		const reading = this.deps.readMemory();
+		if (this.underPressure(reading)) {
+			this.comfortableReadings = 0;
+			this.shed(reading);
+			return;
+		}
+		if (!this.roomToGrow(reading)) {
+			this.comfortableReadings = 0;
+			return;
+		}
+		this.comfortableReadings += 1;
+		if (this.comfortableReadings < this.config.rampAfterReadings) return;
+		this.comfortableReadings = 0;
+		this.ramp(reading);
+	};
+
+	private underPressure(reading: MemoryReading): boolean {
+		return (
+			reading.rssBytes >= this.config.rssCeilingBytes ||
+			reading.availableBytes < this.config.headroomBytes
+		);
+	}
+
+	private roomToGrow(reading: MemoryReading): boolean {
+		return (
+			reading.rssBytes < this.config.rssCeilingBytes &&
+			reading.availableBytes >=
+				this.config.headroomBytes + this.config.rampMarginBytes
+		);
+	}
+
+	// A write that fails must not take the worker down with it, for the same
+	// reason the poll loop's own beat does not: a full disk is the likeliest
+	// cause and the moment to stay up. The missed beat is itself the signal.
+	private keepAlive = async (): Promise<void> => {
+		await this.deps.beat?.().catch((error: unknown) => {
+			this.deps.log.error("Search index heartbeat write failed", {
+				error: String(error),
+			});
+		});
+	};
+
+	private shed(reading: MemoryReading): void {
+		// Pacing applies whenever the box is tight, including at the floor, where
+		// there is no smaller batch left to fall back to.
+		this.pauseBeforeNextBatch = true;
+		const batchSize = Math.max(
+			this.config.minBatchSize,
+			Math.floor(this.batchSize / 2),
+		);
+		if (batchSize === this.batchSize && this.concurrency === 1) return;
+		this.batchSize = batchSize;
+		this.concurrency = 1;
+		this.announce("shed", reading);
+	}
+
+	private ramp(reading: MemoryReading): void {
+		if (this.batchSize < this.config.maxBatchSize) {
+			this.batchSize = Math.min(this.config.maxBatchSize, this.batchSize * 2);
+		} else if (this.concurrency < this.config.maxConcurrency) {
+			this.concurrency += 1;
+		} else {
+			return;
+		}
+		this.announce("ramp", reading);
+	}
+
+	private reset(): void {
+		this.batchSize = this.config.minBatchSize;
+		this.concurrency = 1;
+		this.comfortableReadings = 0;
+		this.deps.onPlan?.(this.plan);
+	}
+
+	// One line per change of plan, never one per batch: a first index is
+	// hundreds of thousands of batches and a per-batch line is not a log.
+	private announce(decision: "ramp" | "shed", reading: MemoryReading): void {
+		this.deps.onPlan?.(this.plan);
+		this.deps.log.info(`Search index embedding ${decision}`, {
+			batchSize: this.batchSize,
+			concurrency: this.concurrency,
+			...this.fields(reading),
+		});
+	}
+
+	private fields(reading: MemoryReading): Record<string, unknown> {
+		return {
+			availableMb: Math.round(reading.availableBytes / MB),
+			rssMb: Math.round(reading.rssBytes / MB),
+			headroomMb: Math.round(this.config.headroomBytes / MB),
+			criticalMb: Math.round(this.config.criticalBytes / MB),
+			rssCeilingMb: Math.round(this.config.rssCeilingBytes / MB),
+		};
+	}
+}
+
+/**
+ * Wraps an embedder so its work passes through the governor. The whole text
+ * list arrives as one call today (one email's chunks); this splits it into
+ * governed batches and holds only the current wave's inputs, so the model's
+ * outputs from a finished batch are unreachable before the next one starts.
+ *
+ * `dimensions` and `embeddingId` pass straight through: `embeddingId` feeds the
+ * content hash that decides what needs re-embedding, so wrapping the embedder
+ * must not invalidate an existing index.
+ */
+export const createAdaptiveEmbeddingService = (
+	inner: EmbeddingService,
+	governor: MemoryGovernor,
+	stallMaxMs: number = DEFAULT_ADAPTIVE_EMBEDDING_CONFIG.stallMaxMs,
+): EmbeddingService => ({
+	dimensions: inner.dimensions,
+	embeddingId: inner.embeddingId,
+	embed: async (texts: string[]): Promise<number[][]> => {
+		const vectors: number[][] = [];
+		let next = 0;
+		while (next < texts.length) {
+			if ((await governor.admit()) === "expired") {
+				throw new MemoryStallTimeoutError(stallMaxMs);
+			}
+			const { batchSize, concurrency } = governor.plan;
+			const wave: string[][] = [];
+			while (wave.length < concurrency && next < texts.length) {
+				wave.push(texts.slice(next, next + batchSize));
+				next += batchSize;
+			}
+			const embedded = await Promise.all(
+				wave.map((batch) => inner.embed(batch)),
+			);
+			for (const batch of embedded) vectors.push(...batch);
+			governor.settle();
+		}
+		return vectors;
+	},
+});

package/src/handler.test.ts

@@ -0,0 +1,87 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import type { Logger } from "@remit/logger-lambda";
+import type { SQSRecord } from "aws-lambda";
+import { MemoryStallTimeoutError } from "./adaptive-embedder.js";
+import { processBatch } from "./handler.js";
+import type { Services } from "./services.js";
+
+const MESSAGE_ID = "11111111-1111-4111-8111-111111111111";
+const ACCOUNT_ID = "22222222-2222-4222-8222-222222222222";
+
+const record = (): SQSRecord =>
+	({
+		messageId: "sqs-1",
+		eventSourceARN: "http://queue:9324/000000000000/remit-search-index",
+		body: JSON.stringify({
+			eventName: "INSERT",
+			entity: "Message",
+			eventID: "e1",
+			eventTimestamp: 0,
+			accountId: ACCOUNT_ID,
+			keys: { pk: "pk", sk: "sk" },
+			messageId: MESSAGE_ID,
+		}),
+	}) as unknown as SQSRecord;
+
+const silent = {
+	info: () => {},
+	error: () => {},
+} as unknown as Logger;
+
+const servicesThatFail = (error: Error): Services =>
+	({
+		accountService: {
+			get: async () => ({
+				accountConfigId: "config-1",
+				deletedAt: undefined,
+			}),
+		},
+		threadMessageService: {
+			findByMessageId: async () => ({
+				accountConfigId: "config-1",
+				threadId: "thread-1",
+				mailboxId: "mailbox-1",
+				sentDate: 0,
+				isRead: false,
+				hasAttachment: false,
+				hasStars: false,
+				category: "primary",
+			}),
+		},
+		storageService: {
+			retrieveParsedBody: async () => ({ text: "hello", html: "" }),
+		},
+		searchService: {
+			prepareVectors: async () => {
+				throw error;
+			},
+		},
+	}) as unknown as Services;
+
+describe("a message the worker cannot index right now", () => {
+	// The governor stops rather than pushing the box into swap, and gives up
+	// before the queue's visibility timeout redelivers the record underneath it
+	// (#585). Reporting the item as failed is what makes that redelivery clean:
+	// the record goes back, its siblings still index, and the retry count is the
+	// queue's rather than something this process tracks.
+	it("goes back on the queue when indexing stalls out of memory", async () => {
+		const response = await processBatch(
+			[record()],
+			servicesThatFail(new MemoryStallTimeoutError(240_000)),
+			silent,
+		);
+
+		assert.deepEqual(response.batchItemFailures, [{ itemIdentifier: "sqs-1" }]);
+	});
+
+	it("reports a model failure the same way, rather than dropping the message", async () => {
+		const response = await processBatch(
+			[record()],
+			servicesThatFail(new Error("model could not be loaded")),
+			silent,
+		);
+
+		assert.deepEqual(response.batchItemFailures, [{ itemIdentifier: "sqs-1" }]);
+	});
+});

package/src/memory.test.ts

@@ -0,0 +1,28 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import { parseMemAvailableBytes } from "./memory.js";
+
+const MEMINFO = [
+	"MemTotal:        3908340 kB",
+	"MemFree:          131072 kB",
+	"MemAvailable:     786432 kB",
+	"Buffers:            1024 kB",
+].join("\n");
+
+describe("reading what the box has left", () => {
+	it("reads MemAvailable, in bytes", () => {
+		assert.equal(parseMemAvailableBytes(MEMINFO), 786432 * 1024);
+	});
+
+	// MemFree on a box with a warm page cache reads near zero, which would stall
+	// the worker permanently; picking the wrong line must fail, not approximate.
+	it("does not settle for MemFree", () => {
+		const withoutAvailable = MEMINFO.split("\n")
+			.filter((line) => !line.startsWith("MemAvailable:"))
+			.join("\n");
+		assert.throws(
+			() => parseMemAvailableBytes(withoutAvailable),
+			/MemAvailable/,
+		);
+	});
+});

package/src/memory.ts

@@ -0,0 +1,38 @@
+import { readFileSync } from "node:fs";
+
+/**
+ * What the governor steers on. `rssBytes` is this process's whole resident set,
+ * which is the number that matters here: the embedding model, its inference
+ * arenas and its per-batch tensors are allocated by onnxruntime's addon, so
+ * none of them appear in the V8 heap and none are bounded by
+ * `--max-old-space-size`. `availableBytes` is the box's, not the container's —
+ * a container with no `mem_limit` reads the host's `/proc/meminfo`, which is
+ * exactly the quantity a first index must not exhaust.
+ */
+export interface MemoryReading {
+	rssBytes: number;
+	availableBytes: number;
+}
+
+export type MemoryReader = () => MemoryReading;
+
+const MEMINFO_PATH = "/proc/meminfo";
+
+/**
+ * `MemAvailable`, not `MemFree`: free memory excludes reclaimable page cache and
+ * reads near zero on any box that has been up a while, which would stall the
+ * worker permanently. `MemAvailable` is the kernel's own estimate of what a new
+ * allocation can take without swapping.
+ */
+export const parseMemAvailableBytes = (meminfo: string): number => {
+	const match = /^MemAvailable:\s+(\d+)\s+kB$/m.exec(meminfo);
+	if (!match) {
+		throw new Error(`${MEMINFO_PATH} has no MemAvailable line`);
+	}
+	return Number(match[1]) * 1024;
+};
+
+export const readSystemMemory: MemoryReader = () => ({
+	rssBytes: process.memoryUsage().rss,
+	availableBytes: parseMemAvailableBytes(readFileSync(MEMINFO_PATH, "utf8")),
+});

package/src/metrics.test.ts

@@ -1,7 +1,10 @@
 import assert from "node:assert/strict";
 import { beforeEach, describe, it } from "node:test";
 import { renderMetrics, resetMetrics } from "@remit/logger-lambda/metrics";
-import { registerSearchIndexBacklog } from "./metrics.js";
+import {
+	registerAdaptiveEmbedding,
+	registerSearchIndexBacklog,
+} from "./metrics.js";
 
 const backlogLines = (text: string): string[] =>
 	text
@@ -45,3 +48,35 @@ describe("the search index backlog series", () => {
 		await assert.rejects(renderMetrics(), /database is locked/);
 	});
 });
+
+describe("the adaptive embedding series", () => {
+	beforeEach(() => resetMetrics());
+
+	it("reports the plan it starts at, and each change after it", async () => {
+		const metrics = registerAdaptiveEmbedding({
+			batchSize: 4,
+			concurrency: 1,
+		});
+		const start = await renderMetrics();
+		assert.match(start, /^remit_search_index_embed_batch_size 4$/m);
+		assert.match(start, /^remit_search_index_embed_concurrency 1$/m);
+
+		metrics.recordPlan({ batchSize: 16, concurrency: 2 });
+		const ramped = await renderMetrics();
+		assert.match(ramped, /^remit_search_index_embed_batch_size 16$/m);
+		assert.match(ramped, /^remit_search_index_embed_concurrency 2$/m);
+	});
+
+	it("counts every stop, which is what a slow first index is diagnosed from", async () => {
+		const metrics = registerAdaptiveEmbedding({
+			batchSize: 4,
+			concurrency: 1,
+		});
+		metrics.recordStall();
+		metrics.recordStall();
+		assert.match(
+			await renderMetrics(),
+			/^remit_search_index_memory_stalls_total 2$/m,
+		);
+	});
+});

package/src/metrics.ts

@@ -1,5 +1,6 @@
 import { onScrape, registry } from "@remit/logger-lambda/metrics";
-import { Gauge } from "prom-client";
+import { Counter, Gauge } from "prom-client";
+import type { EmbeddingPlan } from "./adaptive-embedder.js";
 
 /**
  * Put the search index backlog (standalone-observability D3) on this process's
@@ -29,3 +30,47 @@ export const registerSearchIndexBacklog = (
 	});
 	onScrape(async () => backlogRows.set(await count()));
 };
+
+const BATCH_SIZE = "remit_search_index_embed_batch_size";
+const CONCURRENCY = "remit_search_index_embed_concurrency";
+const STALLS = "remit_search_index_memory_stalls_total";
+
+export interface AdaptiveEmbeddingMetrics {
+	recordPlan(plan: EmbeddingPlan): void;
+	recordStall(): void;
+}
+
+/**
+ * What the governor (#585) decided, for the same reason as the backlog above:
+ * the three series exist only in the process that computes them. Together they
+ * answer the question a slow first index raises — whether the worker is being
+ * held back by the box, and how often it had to stop outright.
+ */
+export const registerAdaptiveEmbedding = (
+	initial: EmbeddingPlan,
+): AdaptiveEmbeddingMetrics => {
+	for (const name of [BATCH_SIZE, CONCURRENCY, STALLS]) {
+		registry.removeSingleMetric(name);
+	}
+	const batchSize = new Gauge({
+		name: BATCH_SIZE,
+		help: "Chunk texts the search-index worker sends to the embedder per call.",
+		registers: [registry],
+	});
+	const concurrency = new Gauge({
+		name: CONCURRENCY,
+		help: "Embedding calls the search-index worker keeps in flight at once.",
+		registers: [registry],
+	});
+	const stalls = new Counter({
+		name: STALLS,
+		help: "Times indexing stopped and waited for the box to free memory.",
+		registers: [registry],
+	});
+	const recordPlan = (plan: EmbeddingPlan): void => {
+		batchSize.set(plan.batchSize);
+		concurrency.set(plan.concurrency);
+	};
+	recordPlan(initial);
+	return { recordPlan, recordStall: () => stalls.inc() };
+};

package/src/poller.ts

@@ -3,6 +3,7 @@ import { runQueuePoller } from "@remit/sqs-client/poller";
 import { env } from "expect-env";
 import { handler } from "./index.js";
 import { registerSearchIndexBacklog } from "./metrics.js";
+import { getMemoryGovernor } from "./services.js";
 import { maybeStartSqliteOutboxDrain } from "./sqlite-outbox-drain.js";
 
 /** Production queue poller — no e2e shim exists for this queue today (the
@@ -24,6 +25,11 @@ if (drain) {
 	registerSearchIndexBacklog(() => drain.countBacklog());
 }
 
+// The memory governor (#585) is built here, before the first message: a
+// threshold the operator typed wrong must fail the container rather than one
+// email, and its gauges must be on the registry before the first scrape.
+getMemoryGovernor();
+
 // /metrics and nothing else, on the compose network (D2). Started before the
 // poll loop, which blocks until shutdown.
 startMetricsServer();

package/src/services.ts

@@ -1,15 +1,30 @@
-import { createSearchService, type SearchService } from "@remit/search-service";
+import { setTimeout as delay } from "node:timers/promises";
+import { createLogger } from "@remit/logger-lambda";
+import {
+	createSearchService,
+	type EmbeddingService,
+	type SearchService,
+} from "@remit/search-service";
 import {
 	buildEmbeddingServiceFromEnv,
 	buildVectorStoreFromEnv,
 } from "@remit/search-service/from-env";
+import { createHeartbeat } from "@remit/sqs-client/heartbeat";
 import type { StorageService } from "@remit/storage-service";
 import { createStorageService } from "@remit/storage-service/s3";
+import {
+	type AdaptiveEmbeddingConfig,
+	createAdaptiveEmbeddingService,
+	MemoryGovernor,
+	readAdaptiveEmbeddingConfigFromEnv,
+} from "./adaptive-embedder.js";
 import {
 	buildDataPortsFromEnv,
 	type SearchIndexDataPorts,
 } from "./data-ports.js";
 import type { IndexOutcome } from "./handler.js";
+import { readSystemMemory } from "./memory.js";
+import { registerAdaptiveEmbedding } from "./metrics.js";
 
 export interface Services {
 	accountService: SearchIndexDataPorts["account"];
@@ -27,6 +42,79 @@ export interface Services {
 
 let cached: Services | undefined;
 
+const MB = 1024 * 1024;
+
+/**
+ * The stall's heartbeat writes the poll loop's own file, not a second one. A
+ * file of its own would be fresh only while stalling and stale the rest of the
+ * time, and the healthcheck reads the oldest file it finds — an idle worker
+ * would report unhealthy. Undefined off the standalone deployment, where
+ * `createHeartbeat` writes nothing anyway.
+ */
+const searchIndexQueueName = (): string | undefined => {
+	const url = process.env.SQS_QUEUE_URL_SEARCH_INDEX;
+	if (!url) return undefined;
+	return new URL(url).pathname.split("/").pop();
+};
+
+let governor: MemoryGovernor | undefined;
+let governorConfig: AdaptiveEmbeddingConfig | undefined;
+let governorResolved = false;
+
+/**
+ * Built at startup rather than on the first message, so a threshold the
+ * operator typed wrong fails the container instead of one email, and so the
+ * gauges render from the first scrape instead of from whenever mail arrives.
+ *
+ * Only the in-process embedder gets one: its memory is native and unbounded —
+ * the model, its arenas and its tensors are onnxruntime allocations that no V8
+ * heap ceiling covers (#585). Bedrock and the deterministic test embedder hold
+ * nothing on this box and are left alone.
+ */
+export const getMemoryGovernor = (): MemoryGovernor | undefined => {
+	if (governorResolved) return governor;
+	governorResolved = true;
+	if (process.env.SEARCH_EMBEDDING_PROVIDER !== "local") return undefined;
+
+	const config = readAdaptiveEmbeddingConfigFromEnv();
+	const metrics = registerAdaptiveEmbedding({
+		batchSize: config.minBatchSize,
+		concurrency: 1,
+	});
+	const log = createLogger();
+	log.info("Search index embedding governed by memory", {
+		batchSize: config.minBatchSize,
+		maxBatchSize: config.maxBatchSize,
+		maxConcurrency: config.maxConcurrency,
+		headroomMb: Math.round(config.headroomBytes / MB),
+		criticalMb: Math.round(config.criticalBytes / MB),
+		rssCeilingMb: Math.round(config.rssCeilingBytes / MB),
+		stallMaxMs: config.stallMaxMs,
+	});
+	const queueName = searchIndexQueueName();
+	governorConfig = config;
+	governor = new MemoryGovernor(config, {
+		readMemory: readSystemMemory,
+		sleep: (ms) => delay(ms),
+		now: () => Date.now(),
+		log,
+		beat: queueName ? createHeartbeat(queueName) : undefined,
+		onPlan: metrics.recordPlan,
+		onStall: metrics.recordStall,
+	});
+	return governor;
+};
+
+const governed = (embedder: EmbeddingService): EmbeddingService => {
+	const memoryGovernor = getMemoryGovernor();
+	if (!memoryGovernor) return embedder;
+	return createAdaptiveEmbeddingService(
+		embedder,
+		memoryGovernor,
+		governorConfig?.stallMaxMs,
+	);
+};
+
 export const getServices = async (): Promise<Services> => {
 	if (cached) return cached;
 
@@ -50,7 +138,7 @@ export const getServices = async (): Promise<Services> => {
 
 	// Build the embedder first so we can pass its dimension count to the
 	// sqlite-vec store — the vec0 table dimension must match the embedder.
-	const embedder = buildEmbeddingServiceFromEnv();
+	const embedder = governed(buildEmbeddingServiceFromEnv());
 	const searchService = createSearchService({
 		store: buildVectorStoreFromEnv(embedder.dimensions),
 		embedder,