@harperfast/harper 5.0.30 → 5.1.0-beta.2

package/resources/models/analyticsTable.ts

@@ -0,0 +1,199 @@
+import { table, isReadOnlyMode } from '../databases.ts';
+import { getNextMonotonicTime } from '../../utility/lmdb/commonUtility.ts';
+import harperLogger from '../../utility/logging/harper_logger.ts';
+
+const log = harperLogger.forComponent('models').conditional;
+
+const DEFAULT_FLUSH_INTERVAL_MS = 10_000; // 10s
+const DEFAULT_MAX_BUFFER_SIZE = 1000;
+const DEFAULT_CLEANUP_INTERVAL_MS = 60 * 60 * 1000; // 1h
+// 90-day default tuned for billing windows. Operator-tunable config key will land
+// in Phase 2 alongside the YAML→registry bootstrapper (Harper's `getConfigValue`
+// only reads keys registered in `CONFIG_PARAM_MAP`, so we defer config plumbing
+// until the first real backend ships and the key has a documented owner).
+const DEFAULT_RETENTION_MS = 90 * 24 * 60 * 60 * 1000;
+
+/**
+ * One row in `hdb_model_calls`. Field names are snake_case to match the table
+ * schema. Numeric token counts are optional because not every backend reports
+ * every metric.
+ */
+export interface ModelCallRecord {
+	tenant?: string;
+	app?: string;
+	model?: string;
+	backend: string;
+	method: 'embed' | 'generate' | 'generateStream';
+	adapter?: string;
+	conversation_id?: string;
+	prompt_tokens?: number;
+	completion_tokens?: number;
+	embedding_tokens?: number;
+	gpu_ms?: number;
+	latency_ms: number;
+	success: boolean;
+	/** Sanitized code (e.g. 'backend_error', 'aborted', 'capability_unsupported'). Never a raw upstream message. */
+	error_code?: string;
+}
+
+interface BufferedRecord extends ModelCallRecord {
+	id: number;
+}
+
+let _table: any;
+/**
+ * Lazy-getter for `hdb_model_calls`. Matches the convention used by
+ * `getRawAnalyticsTable()` / `getAnalyticsTable()` in
+ * `resources/analytics/write.ts:656-700` and the system-table declarations in
+ * `server/DurableSubscriptionsSession.ts:14-50`.
+ */
+export function getModelCallsTable(): any {
+	if (_table) return _table;
+	_table = table({
+		table: 'hdb_model_calls',
+		database: 'system',
+		audit: true,
+		trackDeletes: false,
+		attributes: [
+			{ name: 'id', isPrimaryKey: true },
+			{ name: 'tenant', type: 'string', indexed: true },
+			{ name: 'app', type: 'string', indexed: true },
+			{ name: 'model', type: 'string', indexed: true },
+			{ name: 'backend', type: 'string', indexed: true },
+			{ name: 'method', type: 'string', indexed: true },
+			{ name: 'adapter', type: 'string', indexed: true },
+			{ name: 'conversation_id', type: 'string', indexed: true },
+			{ name: 'prompt_tokens', type: 'number' },
+			{ name: 'completion_tokens', type: 'number' },
+			{ name: 'embedding_tokens', type: 'number' },
+			{ name: 'gpu_ms', type: 'number' },
+			{ name: 'latency_ms', type: 'number', indexed: true },
+			{ name: 'success', type: 'boolean', indexed: true },
+			{ name: 'error_code', type: 'string' },
+		],
+	});
+	return _table;
+}
+
+export interface ModelCallAnalyticsWriterOpts {
+	/** Default 10s. Buffer is flushed at this cadence regardless of size. */
+	flushIntervalMs?: number;
+	/** Default 1000. Reaching this size triggers an out-of-cadence flush. */
+	maxBufferSize?: number;
+	/** Default 1h. How often `cleanup()` runs to remove expired rows. */
+	cleanupIntervalMs?: number;
+	/** Default 90d. Rows older than this are removed by `cleanup()`. */
+	retentionMs?: number;
+	/** Override the table accessor. Tests inject a mock to avoid touching real LMDB. */
+	getTable?: () => any;
+}
+
+/**
+ * In-memory buffered writer for per-call model analytics. Rows are batched and
+ * flushed periodically (or when the buffer is full) to keep the analytics path
+ * off the hot model-call path. Shape mirrors the pattern in
+ * `resources/analytics/write.ts` but writes per-call rows rather than
+ * aggregating counters.
+ *
+ * The intervals are `.unref()`ed so they never hold the process open during
+ * shutdown; rows buffered at shutdown are dropped (best-effort, same posture
+ * as the existing analytics writer).
+ */
+export class ModelCallAnalyticsWriter {
+	#buffer: BufferedRecord[] = [];
+	#flushTimer?: NodeJS.Timeout;
+	#cleanupTimer?: NodeJS.Timeout;
+	#maxBufferSize: number;
+	#retentionMs: number;
+	#getTable: () => any;
+	#stopped = false;
+
+	constructor(opts: ModelCallAnalyticsWriterOpts = {}) {
+		const flushIntervalMs = opts.flushIntervalMs ?? DEFAULT_FLUSH_INTERVAL_MS;
+		const cleanupIntervalMs = opts.cleanupIntervalMs ?? DEFAULT_CLEANUP_INTERVAL_MS;
+		this.#maxBufferSize = opts.maxBufferSize ?? DEFAULT_MAX_BUFFER_SIZE;
+		this.#retentionMs = opts.retentionMs ?? DEFAULT_RETENTION_MS;
+		this.#getTable = opts.getTable ?? getModelCallsTable;
+		this.#flushTimer = setInterval(() => {
+			this.flush().catch((err) => log.warn?.(`Model-call analytics flush failed: ${err?.message ?? err}`));
+		}, flushIntervalMs);
+		this.#flushTimer.unref?.();
+		this.#cleanupTimer = setInterval(() => {
+			this.cleanup().catch((err) => log.warn?.(`Model-call analytics cleanup failed: ${err?.message ?? err}`));
+		}, cleanupIntervalMs);
+		this.#cleanupTimer.unref?.();
+	}
+
+	write(record: ModelCallRecord): void {
+		if (this.#stopped) return;
+		// id last so a record that accidentally carries an `id` field can't override
+		// the monotonic primary key.
+		this.#buffer.push({ ...record, id: getNextMonotonicTime() });
+		if (this.#buffer.length >= this.#maxBufferSize) {
+			// Out-of-cadence flush; swallow errors so a failing flush doesn't escape into the caller.
+			this.flush().catch((err) => log.warn?.(`Model-call analytics flush failed: ${err?.message ?? err}`));
+		}
+	}
+
+	async flush(): Promise<void> {
+		if (this.#buffer.length === 0) return;
+		// Read-only nodes (followers, recovery mode) shouldn't accumulate doomed writes —
+		// drop the buffer and skip. Matches `resources/analytics/write.ts:643-650`.
+		if (isReadOnlyMode()) {
+			this.#buffer = [];
+			return;
+		}
+		const batch = this.#buffer;
+		this.#buffer = [];
+		const tbl = this.#getTable();
+		const puts: Array<{ id: number; promise: Promise<unknown> }> = [];
+		for (const record of batch) {
+			try {
+				const result = tbl.primaryStore.put(record.id, record);
+				if (result && typeof (result as { then?: unknown }).then === 'function') {
+					puts.push({ id: record.id, promise: result as Promise<unknown> });
+				}
+			} catch (err) {
+				log.warn?.(`Model-call analytics put failed for id=${record.id}: ${(err as Error)?.message ?? err}`);
+			}
+		}
+		if (puts.length > 0) {
+			const results = await Promise.allSettled(puts.map((p) => p.promise));
+			for (let i = 0; i < results.length; i++) {
+				const r = results[i];
+				if (r.status === 'rejected') {
+					const reason = r.reason as { message?: string } | undefined;
+					log.warn?.(`Model-call analytics async put failed for id=${puts[i].id}: ${reason?.message ?? r.reason}`);
+				}
+			}
+		}
+	}
+
+	async cleanup(): Promise<void> {
+		if (isReadOnlyMode()) return;
+		const end = Date.now() - this.#retentionMs;
+		const tbl = this.#getTable();
+		for (const key of tbl.primaryStore.getKeys({ start: false, end })) {
+			tbl.primaryStore.remove(key);
+		}
+	}
+
+	/** Stop the periodic timers. After stop, `write()` is a no-op and `flush()` still works. */
+	stop(): void {
+		this.#stopped = true;
+		if (this.#flushTimer) clearInterval(this.#flushTimer);
+		if (this.#cleanupTimer) clearInterval(this.#cleanupTimer);
+	}
+
+	/** Test-only: inspect current buffer size without flushing. */
+	get bufferSize(): number {
+		return this.#buffer.length;
+	}
+}
+
+let _writer: ModelCallAnalyticsWriter | undefined;
+/** Process-wide singleton writer. Constructed on first access. */
+export function getModelCallAnalyticsWriter(): ModelCallAnalyticsWriter {
+	if (!_writer) _writer = new ModelCallAnalyticsWriter();
+	return _writer;
+}

package/resources/models/backendHelpers.ts

@@ -0,0 +1,116 @@
+/**
+ * Shared helpers for `ModelBackend` implementations.
+ *
+ * Phase 6 of #510 extracted these from the ollama and openai backends after
+ * landing the openai PR — Kris flagged the similarity, and with anthropic +
+ * bedrock adding a third and fourth use the duplication crossed the
+ * "extract" threshold.
+ *
+ * Each helper is provider-agnostic; backend-specific error classes are passed
+ * in via a constructor type so the thrown errors carry the backend's name
+ * for `instanceof` matching in tests.
+ */
+import { isUnresolvedEnvVarPlaceholder } from '../../utility/expandEnvVar.ts';
+import type { TokenUsage } from './types.ts';
+
+/** Constructor signature for backend-specific error classes. */
+export type BackendErrorCtor = new (message: string) => Error;
+
+/**
+ * Combine a caller-supplied AbortSignal with a per-call timeout via
+ * `AbortSignal.any`. Returns the caller signal directly when no timeout is
+ * configured; the timeout signal alone when no caller signal exists; a
+ * composed signal when both apply.
+ */
+export function composeSignal(caller?: AbortSignal, timeoutMs?: number): AbortSignal | undefined {
+	if (!timeoutMs) return caller;
+	const timeout = AbortSignal.timeout(timeoutMs);
+	if (!caller) return timeout;
+	return AbortSignal.any([caller, timeout]);
+}
+
+/**
+ * Write a token count to `usage` only when the value is a finite, non-negative
+ * integer. Drops `NaN`, `Infinity`, negatives, and non-integers silently —
+ * upstream-supplied bad counts would otherwise poison aggregates over
+ * `hdb_model_calls` (`SUM(prompt_tokens)` returns `NaN` for the whole window
+ * if any row carries `NaN`).
+ */
+export function assignFiniteTokenCount(
+	usage: TokenUsage,
+	key: 'promptTokens' | 'completionTokens' | 'embeddingTokens',
+	value: unknown
+): void {
+	if (typeof value !== 'number') return;
+	if (!Number.isFinite(value) || value < 0 || !Number.isInteger(value)) return;
+	usage[key] = value;
+}
+
+/**
+ * Read a JSON response body and throw the backend's error class on parse
+ * failure rather than leaking the raw `SyntaxError` (whose message can
+ * include upstream-derived bytes). Matches the sanitization posture from
+ * `analyticsTable.ts:35` ("Sanitized code (...). Never a raw upstream
+ * message.").
+ */
+export async function parseJsonResponse<T>(res: Response, endpoint: string, Err: BackendErrorCtor): Promise<T> {
+	try {
+		return (await res.json()) as T;
+	} catch {
+		throw new Err(`${endpoint} returned a non-JSON response body`);
+	}
+}
+
+/**
+ * Assert that a model name was specified — either via `opts.model` (per-call
+ * override) or the backend's configured default.
+ */
+export function requireModel(model: string | undefined, op: string, Err: BackendErrorCtor): asserts model is string {
+	if (!model) {
+		throw new Err(`No model specified for ${op}; set 'model' in config or pass opts.model`);
+	}
+}
+
+/**
+ * Validate a configured credential field (typically `apiKey`):
+ * - must be present and non-empty
+ * - must NOT be a literal `${VAR_NAME}` placeholder that survived because the
+ *   env var was unset at boot (the `bootstrap.ts` expansion runs through
+ *   `expandEnvVarsDeep`, but unresolved placeholders pass through unchanged)
+ *
+ * Returns the validated value or throws. The `backendLabel` prefixes the
+ * error message so operators see which backend's config failed.
+ */
+export function requireCredential(
+	value: string | undefined,
+	backendLabel: string,
+	fieldName: string,
+	Err: BackendErrorCtor
+): string {
+	if (!value || value.length === 0) {
+		throw new Err(`${backendLabel} backend requires ${fieldName}`);
+	}
+	if (isUnresolvedEnvVarPlaceholder(value)) {
+		throw new Err(
+			`${backendLabel} ${fieldName} is the literal placeholder ${value}; set the matching env var before starting Harper`
+		);
+	}
+	return value;
+}
+
+/**
+ * Normalize a config-supplied host/origin into a fully-qualified base URL.
+ *
+ * - Falls back to `defaults.host` when value is empty
+ * - Prepends `http://` or `https://` (per `defaults.secure`) when no scheme present
+ * - Strips trailing slashes so callers can `${origin}${path}` cleanly
+ *
+ * Backend-specific behavior collapses to choosing the right `defaults`:
+ * Ollama → `{ host: 'localhost:11434', secure: false }`; OpenAI →
+ * `{ host: 'api.openai.com/v1', secure: true }`; etc.
+ */
+export function normalizeOrigin(value: string | undefined, defaults: { host: string; secure: boolean }): string {
+	const v = value?.trim() || defaults.host;
+	const withScheme = /^https?:\/\//i.test(v) ? v : (defaults.secure ? 'https://' : 'http://') + v;
+	return withScheme.replace(/\/+$/, '');
+}

package/resources/models/backendRegistry.ts

@@ -0,0 +1,66 @@
+import { ServerError } from '../../utility/errors/hdbError.ts';
+import type { ModelBackend } from './types.ts';
+
+/**
+ * Process-wide model backend registry.
+ *
+ * Stores logical-name → backend-instance mappings for embedding and
+ * generative kinds. Boot wiring populates the registry via
+ * `setEmbedding(...)` / `setGenerative(...)`; the `Models` facade reads it
+ * via `resolveEmbedding(...)` / `resolveGenerative(...)`.
+ *
+ * Module-scope state is intentional — one registry per Harper process,
+ * mirroring `contextStorage` at `resources/transaction.ts:6`. Translating
+ * a YAML `models:` config block into registry entries (the bootstrapper
+ * step) lands in Phase 2 alongside the first real backend.
+ */
+
+type ModelKind = 'embedding' | 'generative';
+
+const embedding: Map<string, ModelBackend> = new Map();
+const generative: Map<string, ModelBackend> = new Map();
+
+/** Map `logicalName` to a backend for embedding calls. Re-set replaces. */
+export function setEmbedding(logicalName: string, backend: ModelBackend): void {
+	embedding.set(logicalName, backend);
+}
+
+/** Map `logicalName` to a backend for generative calls. Re-set replaces. */
+export function setGenerative(logicalName: string, backend: ModelBackend): void {
+	generative.set(logicalName, backend);
+}
+
+/**
+ * Resolve the embedding backend mapped to `logicalName` (default: `'default'`).
+ * Throws `ModelBackendNotFoundError` if no backend is mapped.
+ */
+export function resolveEmbedding(logicalName: string = 'default'): ModelBackend {
+	const backend = embedding.get(logicalName);
+	if (!backend) throw new ModelBackendNotFoundError('embedding', logicalName);
+	return backend;
+}
+
+/**
+ * Resolve the generative backend mapped to `logicalName` (default: `'default'`).
+ * Throws `ModelBackendNotFoundError` if no backend is mapped.
+ */
+export function resolveGenerative(logicalName: string = 'default'): ModelBackend {
+	const backend = generative.get(logicalName);
+	if (!backend) throw new ModelBackendNotFoundError('generative', logicalName);
+	return backend;
+}
+
+/** Remove all registrations. Test-only hygiene. */
+export function clearRegistry(): void {
+	embedding.clear();
+	generative.clear();
+}
+
+export class ModelBackendNotFoundError extends ServerError {
+	// Message identifies the kind + logical name only; never enumerates other
+	// registered names to avoid leaking the registry shape in error responses.
+	constructor(kind: ModelKind, logicalName: string) {
+		super(`No backend registered for '${kind}.${logicalName}'`);
+		this.name = 'ModelBackendNotFoundError';
+	}
+}

package/resources/models/bootstrap.ts

@@ -0,0 +1,135 @@
+/**
+ * YAML→registry boot bridge (#629 / #630 of #510).
+ *
+ * Reads the top-level `models` block from the root config and dispatches each
+ * `models.embedding.<name>` / `models.generative.<name>` entry to the matching
+ * per-backend register function. Backends self-contain in `components/<name>/`
+ * (matches the pattern in `components/mcp/index.ts` from PR #649).
+ *
+ * Boot site: `components/componentLoader.ts` calls this after `getConfigObj()`
+ * returns the root config and before per-component iteration, so that
+ * `scope.models.embed(...)` works from `handleApplication(scope)`.
+ *
+ * Env-var expansion: each entry's string leaves are run through
+ * `expandEnvVarsDeep` before dispatch — `apiKey: ${OPENAI_API_KEY}` in YAML
+ * becomes the resolved process.env value at the backend. Matches the
+ * convention from `@harperfast/oauth`'s config loader.
+ *
+ * Errors per entry are logged and skipped, not thrown — one misconfigured
+ * backend should not block Harper boot.
+ */
+import harperLogger from '../../utility/logging/harper_logger.ts';
+import { expandEnvVarsDeep, isUnresolvedEnvVarPlaceholder } from '../../utility/expandEnvVar.ts';
+import { registerOllamaBackend, type OllamaBackendConfig } from '../../components/ollama/index.ts';
+import { registerOpenAIBackend, type OpenAIBackendConfig } from '../../components/openai/index.ts';
+import { registerAnthropicBackend, type AnthropicBackendConfig } from '../../components/anthropic/index.ts';
+import { registerBedrockBackend, type BedrockBackendConfig } from '../../components/bedrock/index.ts';
+
+/**
+ * Field names treated as credentials. When present in config as a literal
+ * value (not a `${VAR}` placeholder), bootstrap warns the operator at boot
+ * — `harperdb-config.yaml` on disk in plaintext is a real anti-pattern.
+ * Extend this list as future backends add credential fields.
+ */
+const CREDENTIAL_FIELDS = new Set(['apiKey']);
+
+type ModelKind = 'embedding' | 'generative';
+
+interface ModelEntry {
+	backend?: string;
+	host?: string;
+	model?: string;
+	requestTimeoutMs?: number;
+	// openai + anthropic credentials
+	apiKey?: string;
+	baseUrl?: string;
+	organization?: string;
+	// bedrock
+	region?: string;
+}
+
+interface ModelsConfig {
+	embedding?: Record<string, ModelEntry>;
+	generative?: Record<string, ModelEntry>;
+}
+
+interface RootConfig {
+	models?: ModelsConfig;
+}
+
+type BackendRegisterFn = (args: { logicalName: string; kind: ModelKind; config: object }) => void;
+
+const FACTORIES: Record<string, BackendRegisterFn> = {
+	ollama: (args) => registerOllamaBackend({ ...args, config: args.config as OllamaBackendConfig }),
+	openai: (args) => registerOpenAIBackend({ ...args, config: args.config as OpenAIBackendConfig }),
+	anthropic: (args) => registerAnthropicBackend({ ...args, config: args.config as AnthropicBackendConfig }),
+	bedrock: (args) => registerBedrockBackend({ ...args, config: args.config as BedrockBackendConfig }),
+};
+
+/**
+ * Populate the model registry from `rootConfig.models`. No-op if the block
+ * is absent or empty. Idempotent within a process: each entry overwrites any
+ * prior registration under the same logical name (registry uses `.set()`).
+ */
+export function bootstrapModels(rootConfig: RootConfig | undefined | null): void {
+	const block = rootConfig?.models;
+	if (!block) return;
+	registerKind('embedding', block.embedding);
+	registerKind('generative', block.generative);
+}
+
+function warnOnLiteralCredentials(kind: ModelKind, logicalName: string, entry: ModelEntry): void {
+	for (const field of CREDENTIAL_FIELDS) {
+		const value = (entry as Record<string, unknown>)[field];
+		if (typeof value !== 'string' || value.length === 0) continue;
+		if (isUnresolvedEnvVarPlaceholder(value)) continue; // operator is using ${VAR} indirection
+		harperLogger.warn(
+			`models.${kind}.${logicalName}: '${field}' is a literal value in harperdb-config.yaml; ` +
+				`prefer \${ENV_VAR} indirection for credentials to keep them off disk`
+		);
+	}
+}
+
+function registerKind(kind: ModelKind, entries: Record<string, ModelEntry> | undefined): void {
+	if (!entries) return;
+	for (const [logicalName, entry] of Object.entries(entries)) {
+		if (!entry || typeof entry !== 'object') {
+			// Schema validation (configValidator.ts) catches this before bootstrap
+			// runs, so reaching here means config was loaded by an unusual path
+			// (test, programmatic). Log at error so it's visible.
+			harperLogger.error(`models.${kind}.${logicalName} is not an object; skipping`);
+			continue;
+		}
+		const factory = entry.backend ? FACTORIES[entry.backend] : undefined;
+		if (!factory) {
+			// Loud because the operator opted into `models:` specifically to enable
+			// a backend — silently registering nothing is a footgun. Schema-level
+			// typo guards (`.unknown(false)` on modelEntrySchema) catch field-name
+			// typos before this point; reaching here means `backend:` itself names
+			// a type Harper doesn't ship a factory for in this version. List the
+			// known backends so operators can spot value-name typos
+			// (`backend: 'openi'` instead of `'openai'`).
+			const known = Object.keys(FACTORIES).sort().join(', ');
+			harperLogger.error(
+				`models.${kind}.${logicalName}: unknown backend '${entry.backend ?? '(missing)'}'; skipping. Known backends: ${known}.`
+			);
+			continue;
+		}
+		// Warn before expansion: literal credentials in `harperdb-config.yaml`
+		// land on disk, in backups, and (depending on deployment) in replicated
+		// config tables. The `${VAR}` indirection pattern from
+		// `@harperfast/oauth` is documented but not enforced.
+		warnOnLiteralCredentials(kind, logicalName, entry);
+		try {
+			// Resolve `${VAR}` placeholders on every string leaf before handing the
+			// entry to the backend factory. Backends receive concrete values and
+			// don't need to know about env-var syntax. Unresolved placeholders
+			// (env var unset) pass through unchanged — backend's required-field
+			// validation catches them with a meaningful error.
+			const resolved = expandEnvVarsDeep(entry);
+			factory({ logicalName, kind, config: resolved });
+		} catch (err) {
+			harperLogger.error(`models.${kind}.${logicalName}: registration failed (${(err as Error)?.message ?? err})`);
+		}
+	}
+}

package/resources/models/embedHook.ts

@@ -0,0 +1,138 @@
+/**
+ * `@embed` directive write-time hook. `createDefaultEmbedder` builds the embedder
+ * a table registers for an `@embed` attribute; `buildEmbedBefore` produces the
+ * pre-commit callback that runs registered embedders and writes their vectors onto
+ * the record before it commits.
+ */
+
+// Lazily resolved to avoid a require cycle on the unit-test load path; only needed on failure.
+function getLogger(): { error?: (...args: any[]) => void } {
+	try {
+		// eslint-disable-next-line @typescript-eslint/no-var-requires
+		return require('#src/utility/logging/logger').logger ?? {};
+	} catch {
+		return {};
+	}
+}
+
+export type EmbedConfig = {
+	source: string;
+	model: string;
+};
+
+export type EmbedAttribute = {
+	name: string;
+	embed: EmbedConfig;
+};
+
+export type Embedder = (record: any) => Promise<number[] | Float32Array | null | undefined>;
+
+// Matches the public `Models.embed` signature; a named type so tests can inject a fake.
+type EmbedFn = (
+	input: string | string[],
+	opts: { model?: string; inputType?: 'document' | 'query' }
+) => Promise<Float32Array[]>;
+
+// Lazy-imported so this module can be unit-tested without loading the transaction
+// stack `Models.ts` pulls in. Overridable via `__setEmbedFnForTest`.
+let _embedFn: EmbedFn | undefined;
+function resolveEmbedFn(): EmbedFn {
+	if (_embedFn) return _embedFn;
+	const { Models } = require('#src/resources/models/Models'); // eslint-disable-line @typescript-eslint/no-var-requires
+	const models = new Models();
+	_embedFn = (input, opts) => models.embed(input, opts);
+	return _embedFn;
+}
+
+/** Test seam: override the embed function. Pass `undefined` to reset to `Models.embed`. */
+export function __setEmbedFnForTest(fn: EmbedFn | undefined): void {
+	_embedFn = fn;
+}
+
+export function createDefaultEmbedder(embedConfig: EmbedConfig): Embedder {
+	const { source, model } = embedConfig;
+	return async (record: any): Promise<number[] | null | undefined> => {
+		const sourceValue = record?.[source];
+		if (sourceValue == null) return null;
+		const vectors = await resolveEmbedFn()(String(sourceValue), {
+			model,
+			inputType: 'document',
+		});
+		const v = vectors?.[0];
+		if (v == null) return undefined;
+		// Store as a plain array — typed arrays don't round-trip through the record encoder.
+		return v instanceof Float32Array ? Array.from(v) : Array.from(v as any);
+	};
+}
+
+/**
+ * Build the pre-commit callback that runs embedders for every `@embed` attribute whose
+ * source field is present in this write. Returns `undefined` when there's nothing to do
+ * (no `@embed` attributes, a replication-receiver write, or no source field in the payload),
+ * so the call site can skip it.
+ *
+ * Source-field semantics: embed only when the source field is in the payload. A PATCH that
+ * omits it leaves the existing vector untouched; an explicit `source: null` clears the vector.
+ */
+export function buildEmbedBefore(
+	record: any,
+	context: any,
+	options: any,
+	embedAttributes: EmbedAttribute[] | undefined,
+	userEmbedders: Record<string, Embedder>
+): (() => Promise<void>) | undefined {
+	if (!embedAttributes || embedAttributes.length === 0) return undefined;
+	// Skip when the write already carries the vector: cluster-replication receiver
+	// (isNotification), REST x-replicate-from:none, or audit-log replay. Note that
+	// proactive source-subscribe pushes also set isNotification and so skip embedding.
+	if (options?.isNotification === true || context?.replicateFrom === false || context?.alreadyLogged === true) {
+		return undefined;
+	}
+	if (!record || typeof record !== 'object') return undefined;
+	let anySourcePresent = false;
+	for (const attr of embedAttributes) {
+		const sourceKey = attr.embed?.source;
+		if (sourceKey && sourceKey in record) {
+			anySourcePresent = true;
+			break;
+		}
+	}
+	if (!anySourcePresent) return undefined;
+	return async (): Promise<void> => {
+		// Parallel: each embedder mutates a distinct attribute, so there's no ordering hazard.
+		await Promise.all(
+			embedAttributes.map(async (attr) => {
+				const sourceKey = attr.embed?.source;
+				if (!sourceKey) return;
+				if (!(sourceKey in record)) return;
+				const sourceValue = record[sourceKey];
+				if (sourceValue == null) {
+					record[attr.name] = null;
+					return;
+				}
+				// CRDT op payloads (`{__op__, value}`) aren't a meaningful embed source; skip.
+				if (sourceValue && typeof sourceValue === 'object' && (sourceValue as any).__op__) return;
+				const embedder = userEmbedders[attr.name];
+				if (!embedder) return;
+				let vector;
+				try {
+					vector = await embedder(record);
+				} catch (err) {
+					// Backend errors can carry URLs / key tails; log raw, rethrow sanitized.
+					getLogger().error?.(`Embedder for attribute "${attr.name}" failed:`, err);
+					throw new Error(`Failed to compute embedding for attribute "${attr.name}"`);
+				}
+				record[attr.name] = normalizeVector(vector);
+			})
+		);
+	};
+}
+
+// Custom embedders may return any typed array; flatten to a plain array so it round-trips
+// through the record encoder. NaN is left for HNSW to reject at index time.
+function normalizeVector(vector: any): number[] | null {
+	if (vector == null) return null;
+	if (Array.isArray(vector)) return vector;
+	if (ArrayBuffer.isView(vector)) return Array.from(vector as any);
+	return vector;
+}