feat(models): add backend registry, TestBackend, hdb_model_calls writer

Part of #628. Three scaffolding files consumed by the upcoming Models
facade — none of them are reachable from app code until that lands.

- `backendRegistry.ts`: process-wide module-scope registry. Backends
  register themselves by `backend.name`. `resolveEmbedding(logicalName)`
  and `resolveGenerative(logicalName)` read
  `models.<kind>.<logicalName>.backend` from config and return the
  registered instance. Errors are `ServerError` subclasses
  (`ModelBackendNotConfiguredError`, `ModelBackendNotRegisteredError`);
  the not-registered error deliberately does not enumerate registered
  backends to avoid leaking the registry shape in error responses.

- `TestBackend.ts`: deterministic in-memory backend for Phase 1 tests.
  `embed()` returns 16-dim Float32Arrays seeded by a FNV-1a hash of the
  input (same text → same vector across runs). `generate()` echoes with
  a prefix; `generateStream()` yields word-by-word.

- `analyticsTable.ts`: lazy-getter declaration of `hdb_model_calls`
  matching the convention in `analytics/write.ts:656-700` and
  `DurableSubscriptionsSession.ts:14-50`. Per-call buffered writer:
  flush every 10s OR at 1000 rows, separate hourly cleanup at 90-day
  retention (configurable via `analytics.modelCallRetentionDays`).
  Both intervals `.unref()`ed; on shutdown, buffered rows are dropped
  (matches existing analytics-writer posture).

No call sites yet. The Models facade in the next commit ties registry +
writer + ALS context together.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: heskew

resources/models/TestBackend.ts

@@ -0,0 +1,83 @@
+import type {
+	BackendOpts,
+	EmbedOpts,
+	GenerateChunk,
+	GenerateInput,
+	GenerateOpts,
+	GenerateResult,
+	ModelBackend,
+	ModelCallResult,
+	ModelCapabilities,
+} from './types.ts';
+
+/**
+ * Deterministic in-memory backend for Phase 1 tests.
+ *
+ * Same input always produces the same output — no external services, no model
+ * files, no network. Lets the facade, registry, accounting, and analytics
+ * paths be exercised end-to-end without an Ollama / OpenAI / fabric backend.
+ */
+export class TestBackend implements ModelBackend {
+	readonly name = 'test';
+
+	capabilities(): ModelCapabilities {
+		return { embed: true, generate: true, stream: true, tools: false, adapters: false };
+	}
+
+	async embed(input: string | string[], _opts: BackendOpts<EmbedOpts>): Promise<ModelCallResult<Float32Array[]>> {
+		const texts = Array.isArray(input) ? input : [input];
+		const vectors = texts.map((t) => deterministicVector(t, 16));
+		const embeddingTokens = texts.reduce((sum, t) => sum + t.length, 0);
+		return { status: 'completed', output: vectors, usage: { embeddingTokens, latencyMs: 0 } };
+	}
+
+	async generate(input: GenerateInput, _opts: BackendOpts<GenerateOpts>): Promise<ModelCallResult<GenerateResult>> {
+		const text = stringFromInput(input);
+		const content = `[TestBackend echoed]: ${text}`;
+		return {
+			status: 'completed',
+			output: { content, finishReason: 'stop' },
+			usage: { promptTokens: text.length, completionTokens: content.length, latencyMs: 0 },
+		};
+	}
+
+	async *generateStream(input: GenerateInput, _opts: BackendOpts<GenerateOpts>): AsyncIterable<GenerateChunk> {
+		const text = stringFromInput(input);
+		const words = `[TestBackend stream]: ${text}`.split(' ');
+		for (const word of words) {
+			yield { deltaContent: word + ' ' };
+		}
+		yield { finishReason: 'stop' };
+	}
+}
+
+function stringFromInput(input: GenerateInput): string {
+	if (typeof input === 'string') return input;
+	const messages = Array.isArray(input) ? input : input.messages;
+	return messages.map((m) => m.content).join(' ');
+}
+
+/**
+ * Hash text into a deterministic Float32Array of the given dimension.
+ *
+ * Uses FNV-1a to seed a Mulberry32 PRNG; values are mapped to [-1, 1).
+ * Same input → same vector across runs and platforms; not a cryptographic hash.
+ */
+function deterministicVector(text: string, dim: number): Float32Array {
+	let seed = 2166136261 >>> 0; // FNV-1a 32-bit offset basis
+	for (let i = 0; i < text.length; i++) {
+		seed ^= text.charCodeAt(i);
+		seed = Math.imul(seed, 16777619) >>> 0;
+	}
+	const vec = new Float32Array(dim);
+	let state = seed;
+	for (let i = 0; i < dim; i++) {
+		state = (state + 0x6d2b79f5) >>> 0;
+		let t = state;
+		t = Math.imul(t ^ (t >>> 15), t | 1) >>> 0;
+		t = (t + Math.imul(t ^ (t >>> 7), t | 61)) >>> 0;
+		const r = ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+		vec[i] = r * 2 - 1; // map [0, 1) → [-1, 1)
+	}
+	return vec;
+}

resources/models/analyticsTable.ts

@@ -0,0 +1,175 @@
+import { table } from '../databases.ts';
+import { get as envGet } from '../../utility/environment/environmentManager.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
+const DEFAULT_RETENTION_DAYS = 90;
+
+/**
+ * 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;
+}
+
+/**
+ * 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;
+	#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 ?? resolveRetentionMs();
+		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;
+		this.#buffer.push({ id: getNextMonotonicTime(), ...record });
+		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;
+		const batch = this.#buffer;
+		this.#buffer = [];
+		const tbl = getModelCallsTable();
+		for (const record of batch) {
+			try {
+				tbl.primaryStore.put(record.id, record);
+			} catch (err) {
+				log.warn?.(`Model-call analytics put failed for id=${record.id}: ${(err as Error)?.message ?? err}`);
+			}
+		}
+	}
+
+	async cleanup(): Promise<void> {
+		const end = Date.now() - this.#retentionMs;
+		const tbl = getModelCallsTable();
+		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;
+	}
+}
+
+function resolveRetentionMs(): number {
+	const days = envGet('analytics.modelCallRetentionDays');
+	const n = typeof days === 'number' && days > 0 ? days : DEFAULT_RETENTION_DAYS;
+	return n * 24 * 60 * 60 * 1000;
+}
+
+let _writer: ModelCallAnalyticsWriter | undefined;
+/** Process-wide singleton writer. Constructed on first access. */
+export function getModelCallAnalyticsWriter(): ModelCallAnalyticsWriter {
+	if (!_writer) _writer = new ModelCallAnalyticsWriter();
+	return _writer;
+}

resources/models/backendRegistry.ts

@@ -0,0 +1,76 @@
+import { get as envGet } from '../../utility/environment/environmentManager.ts';
+import { ServerError } from '../../utility/errors/hdbError.ts';
+import type { ModelBackend } from './types.ts';
+
+/**
+ * Process-wide model backend registry.
+ *
+ * Backends register themselves by `backend.name` (e.g. `'test'`, `'ollama'`,
+ * `'ollama:fast'`). Per-kind logical-name resolution is config-driven:
+ * `resolveEmbedding('default')` reads `models.embedding.default.backend` from
+ * config and returns the registered backend with that name.
+ *
+ * Module-scope state is intentional — one registry per Harper process,
+ * mirroring `contextStorage` at `resources/transaction.ts:6`.
+ */
+
+type ModelKind = 'embedding' | 'generative';
+
+const byName: Map<string, ModelBackend> = new Map();
+
+/**
+ * Register a backend instance. Idempotent on `backend.name` — re-registering
+ * with the same name replaces the prior instance (convenient for tests).
+ */
+export function registerBackend(backend: ModelBackend): void {
+	byName.set(backend.name, backend);
+}
+
+/**
+ * Resolve the backend configured as the embedding provider for `logicalName`
+ * (default: `'default'`). Throws if no config entry exists or the named
+ * backend is not registered.
+ */
+export function resolveEmbedding(logicalName: string = 'default'): ModelBackend {
+	return resolve('embedding', logicalName);
+}
+
+/**
+ * Resolve the backend configured as the generative provider for `logicalName`
+ * (default: `'default'`). Throws if no config entry exists or the named
+ * backend is not registered.
+ */
+export function resolveGenerative(logicalName: string = 'default'): ModelBackend {
+	return resolve('generative', logicalName);
+}
+
+/** Remove all registered backends. Test-only hygiene. */
+export function clearRegistry(): void {
+	byName.clear();
+}
+
+function resolve(kind: ModelKind, logicalName: string): ModelBackend {
+	const backendName = envGet(`models.${kind}.${logicalName}.backend`);
+	if (typeof backendName !== 'string' || !backendName) {
+		throw new ModelBackendNotConfiguredError(kind, logicalName);
+	}
+	const backend = byName.get(backendName);
+	if (!backend) throw new ModelBackendNotRegisteredError(kind, logicalName);
+	return backend;
+}
+
+export class ModelBackendNotConfiguredError extends ServerError {
+	constructor(kind: ModelKind, logicalName: string) {
+		super(`No '${kind}.${logicalName}.backend' configured`);
+		this.name = 'ModelBackendNotConfiguredError';
+	}
+}
+
+export class ModelBackendNotRegisteredError extends ServerError {
+	// Deliberately does not name which backend was configured — avoids leaking
+	// the set of registered backend identifiers in error responses.
+	constructor(kind: ModelKind, logicalName: string) {
+		super(`Backend configured for '${kind}.${logicalName}' is not registered`);
+		this.name = 'ModelBackendNotRegisteredError';
+	}
+}