test(models): unit tests + simplify registry + writer mock seam

Part of #628 (Phase 1 step 7). 47 new unit tests + 1 Scope.test addition.

backendRegistry.test.js (8 tests): direct-mapping API, default
logicalName, multiple names, kind isolation, not-found error,
re-mapping replaces, clearRegistry empties, error message does not
enumerate registrations.

TestBackend.test.js (11 tests): capabilities + name, embed shape +
determinism + token math, generate string + Message[] + {messages}
inputs + usage, generateStream chunks + finishReason.

Models.test.js (17 tests): unwraps to Float32Array[], analytics
record on success/failure, no-ALS fallback (tenant/app undefined),
ALS-bound accounting, extractTenantId user.tenant→user.tenantId
fallback, AbortSignal precedence (opts > ctx), ctx.signal forwarded
when opts.signal absent, ModelCapabilityError, ModelPendingNotSupportedError,
sanitized error_code (backend_error/aborted), no leak of raw
upstream message into the row, generate adapter+conversation_id,
generateStream success record at stream end, generateStream
mid-stream throw → success=false.

analyticsTable.test.js (11 tests): pure-buffer behavior via a mock
table. write buffers without writing, multiple writes accumulate,
write after stop is a no-op, flush writes batch + clears buffer,
flush no-op on empty buffer, flush works after stop (drain),
records carry the expected schema fields, put-throw doesn't drop
remaining records, maxBufferSize triggers out-of-cadence flush,
cleanup removes old rows, cleanup is a no-op when nothing is old.
Real-LMDB analytics coverage is intentionally not unit-tested —
mirrors `analytics/write.ts`'s posture (unit tests only the pure
helpers; LMDB writes are end-to-end-only).

Scope.test.js: extends the existing 'should create a default entry
handler' test to assert `scope.models` is a `Models` instance and
exposes the three callable methods. The wiring point itself, in
the right place.

Registry refactor (resources/models/backendRegistry.ts): the prior
commit's `envGet('models.<kind>.<logicalName>.backend')` doesn't
work — Harper's `getConfigValue` only reads keys in
`CONFIG_PARAM_MAP`, so dynamic config paths return undefined.
Adding entries per logical name is impossible (logical names are
user-defined). Refactored to direct `setEmbedding(name, backend)` /
`setGenerative(name, backend)`. Phase 2 will add a YAML→registry
bootstrapper alongside the first real backend, calling these
setters at boot. Error class collapsed to one
`ModelBackendNotFoundError`; message identifies kind + logical name
without enumerating other registrations. Models.ts is unaffected —
it only uses `resolveEmbedding` / `resolveGenerative`, whose
signatures didn't change.

Writer testability (resources/models/analyticsTable.ts): added
`getTable` to `ModelCallAnalyticsWriterOpts` so tests inject a
mock table. Default still resolves to the real
`getModelCallsTable()`. Also: `flush()` now awaits each
`primaryStore.put()` return value (when promise-shaped) before
resolving, so callers can read back inserted rows
deterministically.

Cycle workaround in Models.test.js: requires
`#src/resources/databases` before `#src/resources/transaction` to
mirror the load order in other unit tests; mocha's ESM-first
loader otherwise hits a transaction.ts ↔ DatabaseTransaction/blob
cycle when transaction is the first edge into the graph.

Coverage on `resources/models/`: 94% statements, 92.6% branches.
Models.ts and TestBackend.ts at 100%. analyticsTable.ts at 82%
with the lazy-getter for the real LMDB table the deliberate gap.

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

Author: heskew

resources/models/analyticsTable.ts

@@ -81,6 +81,8 @@ export interface ModelCallAnalyticsWriterOpts {
 	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;
 }
 
 /**
@@ -100,13 +102,15 @@ export class ModelCallAnalyticsWriter {
 	#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 ?? resolveRetentionMs();
+		this.#getTable = opts.getTable ?? getModelCallsTable;
 		this.#flushTimer = setInterval(() => {
 			this.flush().catch((err) => log.warn?.(`Model-call analytics flush failed: ${err?.message ?? err}`));
 		}, flushIntervalMs);
@@ -130,19 +134,26 @@ export class ModelCallAnalyticsWriter {
 		if (this.#buffer.length === 0) return;
 		const batch = this.#buffer;
 		this.#buffer = [];
-		const tbl = getModelCallsTable();
+		const tbl = this.#getTable();
+		const puts: Promise<unknown>[] = [];
 		for (const record of batch) {
 			try {
-				tbl.primaryStore.put(record.id, record);
+				const result = tbl.primaryStore.put(record.id, record);
+				if (result && typeof (result as { then?: unknown }).then === 'function') {
+					puts.push(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) {
+			await Promise.allSettled(puts);
+		}
 	}
 
 	async cleanup(): Promise<void> {
 		const end = Date.now() - this.#retentionMs;
-		const tbl = getModelCallsTable();
+		const tbl = this.#getTable();
 		for (const key of tbl.primaryStore.getKeys({ start: false, end })) {
 			tbl.primaryStore.remove(key);
 		}

resources/models/backendRegistry.ts

@@ -1,76 +1,66 @@
-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.
+ * Stores logical-name → backend-instance mappings for embedding and
+ * generative kinds. App code or 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`.
+ * 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 byName: Map<string, ModelBackend> = new Map();
+const embedding: Map<string, ModelBackend> = new Map();
+const generative: 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);
+/** 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 backend configured as the embedding provider for `logicalName`
- * (default: `'default'`). Throws if no config entry exists or the named
- * backend is not registered.
+ * Resolve the embedding backend mapped to `logicalName` (default: `'default'`).
+ * Throws `ModelBackendNotFoundError` if no backend is mapped.
  */
 export function resolveEmbedding(logicalName: string = 'default'): ModelBackend {
-	return resolve('embedding', logicalName);
+	const backend = embedding.get(logicalName);
+	if (!backend) throw new ModelBackendNotFoundError('embedding', logicalName);
+	return backend;
 }
 
 /**
- * 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.
+ * Resolve the generative backend mapped to `logicalName` (default: `'default'`).
+ * Throws `ModelBackendNotFoundError` if no backend is mapped.
  */
 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);
+	const backend = generative.get(logicalName);
+	if (!backend) throw new ModelBackendNotFoundError('generative', logicalName);
 	return backend;
 }
 
-export class ModelBackendNotConfiguredError extends ServerError {
-	constructor(kind: ModelKind, logicalName: string) {
-		super(`No '${kind}.${logicalName}.backend' configured`);
-		this.name = 'ModelBackendNotConfiguredError';
-	}
+/** Remove all registrations. Test-only hygiene. */
+export function clearRegistry(): void {
+	embedding.clear();
+	generative.clear();
 }
 
-export class ModelBackendNotRegisteredError extends ServerError {
-	// Deliberately does not name which backend was configured — avoids leaking
-	// the set of registered backend identifiers in error responses.
+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(`Backend configured for '${kind}.${logicalName}' is not registered`);
-		this.name = 'ModelBackendNotRegisteredError';
+		super(`No backend registered for '${kind}.${logicalName}'`);
+		this.name = 'ModelBackendNotFoundError';
 	}
 }

unitTests/components/Scope.test.js

@@ -1,4 +1,5 @@
 const { Scope, MissingDefaultFilesOptionError } = require('#src/components/Scope');
+const { Models } = require('#src/resources/models/Models');
 const { EventEmitter } = require('node:events');
 const assert = require('node:assert/strict');
 const { join, basename } = require('node:path');
@@ -59,6 +60,14 @@ describe('Scope', () => {
 		assert.ok(scope.options instanceof OptionsWatcher, 'Scope should have an OptionsWatcher instance');
 		assert.ok(scope.resources instanceof Resources, 'Scope should have a resources property of type Map');
 		assert.ok(scope.server !== undefined, 'Scope should have a server property');
+		assert.ok(scope.models instanceof Models, 'Scope should expose a Models facade as scope.models');
+		assert.strictEqual(typeof scope.models.embed, 'function', 'scope.models.embed should be callable');
+		assert.strictEqual(typeof scope.models.generate, 'function', 'scope.models.generate should be callable');
+		assert.strictEqual(
+			typeof scope.models.generateStream,
+			'function',
+			'scope.models.generateStream should be callable'
+		);
 
 		// Even though scope is ready, we haven't provided an entry handler yet so modifying a file matched by files option should not request a restart
 		await writeFile(this.testFilePath, '"bar";');