@harperfast/harper 5.2.13 → 5.3.0-beta.1

package/dist/resources/longLivedTransactions.d.ts

@@ -0,0 +1,71 @@
+import { registryStatus } from '@harperfast/rocksdb-js';
+export declare const MAX_LONG_LIVED_TRANSACTION_REPORTS_PER_PASS = 10;
+type RegistryStatusFn = typeof registryStatus;
+/**
+ * Apply a live threshold at the start of every reporting pass, including one that finds no eligible
+ * holder. Otherwise a threshold raised above a holder's age leaves its old attribution backoff in
+ * place when the threshold is lowered again.
+ */
+export declare function rebaseLongLivedTransactionReports(thresholdMs: number): void;
+/**
+ * How old a native transaction handle must be before it is reported, in ms; 0 disables every surface
+ * here. Read per pass rather than cached so a live config reload takes effect. A value that cannot
+ * be a duration falls back to the default instead of silently disabling reporting.
+ */
+export declare function getReportThresholdMs(): number;
+/**
+ * Report every native transaction handle in the process-global rocksdb-js registry that has been open
+ * past the threshold — including handles no `DatabaseTransaction` owns, which is the one class of
+ * holder no other surface can see (harper#2471). The registry spans worker threads, so this runs on
+ * the main thread only; a per-thread sweep would report each handle once per worker.
+ */
+export declare function runLongLivedTransactionSweep(): void;
+/**
+ * Start the periodic sweep. Armed unconditionally on the main thread — the pass itself honors a live
+ * threshold change, including one that disables it — and idempotent because the thread startup path
+ * that calls it can run more than once.
+ */
+export declare function startLongLivedTransactionReporting(): void;
+export type LongLivedHolder = {
+    databasePath: string | undefined;
+    nativeId: number;
+    openedAt: number;
+    ageMs: number;
+    databaseName?: string;
+    tableName?: string;
+    countPendingWrites: () => number;
+    states: string[];
+    timeoutBudget?: number;
+    startedFrom?: {
+        resourceName: string;
+        method: string;
+    };
+};
+export type LongLivedHolderReportBudget = {
+    remaining: number;
+    skipped: number;
+    thresholdMs: number;
+};
+export declare function createLongLivedHolderReportBudget(thresholdMs: number): LongLivedHolderReportBudget;
+export declare function finishLongLivedHolderReports(reportBudget: LongLivedHolderReportBudget): void;
+/**
+ * Report a handle this thread owns, with the attribution the registry sweep cannot supply. The native
+ * id is the join key between the two: the sweep names an id, this names who holds it and which state
+ * kept the open-transaction monitor from reaping it (harper#2471). Never throws — the monitor
+ * interval that calls it has no handler.
+ */
+export declare function reportLongLivedHolder(holder: LongLivedHolder, reportBudget?: LongLivedHolderReportBudget): void;
+/**
+ * The live handles that could be holding the write intent a stuck commit is parked on, as a sentence
+ * to append to that commit's log. A handle on another database is offered too, labelled with its path:
+ * the verification table is one process-global slot array whose hash mixes in the database id, so a
+ * holder in `system` or `oauth` collides with — and parks — a `data` commit at the same rate two `data`
+ * keys do. Rank puts the stuck commit's own database first, then age. Age only ranks: a coordinated
+ * retry parks on whichever transaction holds the slot when the commit reaches it, which can be younger
+ * than the commit itself, so filtering by age could drop the real holder.
+ * Returns '' rather than throwing — the caller's own 503 must survive a failure here.
+ */
+export declare function describeHolderCandidates(databasePath: string | undefined, excludeNativeId: number | undefined): string;
+export declare function setRegistryStatusForTests(fn?: RegistryStatusFn): void;
+export declare function resetLongLivedTransactionReportsForTests(): void;
+export {};

package/dist/resources/longLivedTransactions.js

@@ -0,0 +1,358 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_LONG_LIVED_TRANSACTION_REPORTS_PER_PASS = void 0;
+exports.rebaseLongLivedTransactionReports = rebaseLongLivedTransactionReports;
+exports.getReportThresholdMs = getReportThresholdMs;
+exports.runLongLivedTransactionSweep = runLongLivedTransactionSweep;
+exports.startLongLivedTransactionReporting = startLongLivedTransactionReporting;
+exports.createLongLivedHolderReportBudget = createLongLivedHolderReportBudget;
+exports.finishLongLivedHolderReports = finishLongLivedHolderReports;
+exports.reportLongLivedHolder = reportLongLivedHolder;
+exports.describeHolderCandidates = describeHolderCandidates;
+exports.setRegistryStatusForTests = setRegistryStatusForTests;
+exports.resetLongLivedTransactionReportsForTests = resetLongLivedTransactionReportsForTests;
+const node_worker_threads_1 = require("node:worker_threads");
+const node_path_1 = require("node:path");
+const rocksdb_js_1 = require("@harperfast/rocksdb-js");
+const logger_ts_1 = require("../utility/logging/logger.js");
+const hdbTerms_ts_1 = require("../utility/hdbTerms.js");
+const envMngr = __importStar(require("../utility/environment/environmentManager.js"));
+const common_utils_ts_1 = require("../utility/common_utils.js");
+const DEFAULT_REPORT_THRESHOLD_MS = 300000;
+const SWEEP_INTERVAL_MS = 60000;
+// One line per over-age handle would, against a large leak, block the main thread's socket routing
+// for as long as it took to format them. The per-handle backoff below rotates the cap over the whole
+// set across passes, so every holder is still named eventually.
+exports.MAX_LONG_LIVED_TRANSACTION_REPORTS_PER_PASS = 10;
+const MAX_HOLDER_CANDIDATES = 3;
+// The sweep prunes against the handles it just enumerated; the attribution map has no such
+// enumeration, so its entries expire instead. Far longer than a sweep interval, so a still-live
+// holder keeps its backoff.
+const ATTRIBUTION_STATE_TTL_MS = 3600000;
+// The prune is O(map) and the monitor calls reportLongLivedHolder once per over-threshold transaction
+// per tick, so pruning per call is O(N^2) in exactly the leak this reporting exists to describe.
+const ATTRIBUTION_PRUNE_INTERVAL_MS = 60000;
+let registryStatusFn = typeof rocksdb_js_1.registryStatus === 'function' ? rocksdb_js_1.registryStatus : undefined;
+const sweepReports = new Map();
+const attributionReports = new Map();
+let sweepTimer;
+let invalidThresholdWarned = false;
+let missingDetailsWarned = false;
+let lastAttributionPruneAt = 0;
+let thresholdInEffectMs = -1;
+function reportKey(databasePath, nativeId, openedAt) {
+    return `${databasePath ?? '?'} ${nativeId}${openedAt == null ? '' : ` ${openedAt}`}`;
+}
+/**
+ * Record this observation of a handle and return its report state. A shrinking age means the id was
+ * reused by a reopened descriptor, so the previous holder's backoff must not suppress the new one.
+ */
+function observeHandle(reports, key, ageMs, thresholdMs) {
+    let state = reports.get(key);
+    if (state && ageMs < state.lastAgeMs)
+        state = undefined;
+    if (!state) {
+        state = { nextReportAgeMs: thresholdMs, lastAgeMs: ageMs, touchedAt: 0 };
+        reports.set(key, state);
+    }
+    state.lastAgeMs = ageMs;
+    state.touchedAt = Date.now();
+    return state;
+}
+/**
+ * Drop the accrued backoff when the configured threshold changes, so a handle already under
+ * observation is re-measured against the new one. Without this, `nextReportAgeMs` keeps whatever it
+ * was given at first observation: lowering the threshold during an incident would not bring a
+ * silent handle's first report forward, and raising it would not quiet one. Reporting each live
+ * holder once more at the new threshold is what an operator who just changed it is asking for.
+ */
+function rebaseIfThresholdChanged(thresholdMs) {
+    if (thresholdMs === thresholdInEffectMs)
+        return;
+    thresholdInEffectMs = thresholdMs;
+    sweepReports.clear();
+    attributionReports.clear();
+}
+/**
+ * Apply a live threshold at the start of every reporting pass, including one that finds no eligible
+ * holder. Otherwise a threshold raised above a holder's age leaves its old attribution backoff in
+ * place when the threshold is lowered again.
+ */
+function rebaseLongLivedTransactionReports(thresholdMs) {
+    rebaseIfThresholdChanged(thresholdMs);
+}
+/**
+ * Push this handle's next report out to twice its current age, so one held for hours produces a
+ * handful of lines rather than one per pass. Called only where a line was actually emitted: advancing
+ * it for a handle the per-pass cap skipped would silence that handle without ever naming it.
+ */
+function markReported(state, ageMs) {
+    state.nextReportAgeMs = ageMs * 2;
+}
+/**
+ * How old a native transaction handle must be before it is reported, in ms; 0 disables every surface
+ * here. Read per pass rather than cached so a live config reload takes effect. A value that cannot
+ * be a duration falls back to the default instead of silently disabling reporting.
+ */
+function getReportThresholdMs() {
+    const configured = envMngr.get(hdbTerms_ts_1.CONFIG_PARAMS.STORAGE_LONGTRANSACTIONREPORTTHRESHOLD);
+    if (configured == null)
+        return DEFAULT_REPORT_THRESHOLD_MS;
+    // convertToMS returns 0 for anything that is neither string nor number, which YAML hands us for
+    // `yes`/`no` (booleans) and for an object left by a config merge — indistinguishable from the
+    // documented 0 that disables reporting, so it would silently switch off what the operator configured.
+    const ms = typeof configured === 'string' || typeof configured === 'number' ? (0, common_utils_ts_1.convertToMS)(configured) : NaN;
+    if (ms === 0)
+        return 0;
+    if (!Number.isFinite(ms) || ms < 0) {
+        if (!invalidThresholdWarned) {
+            invalidThresholdWarned = true;
+            logger_ts_1.logger.warn?.(`Invalid storage.longTransactionReportThreshold "${configured}"; using default ${DEFAULT_REPORT_THRESHOLD_MS}ms`);
+        }
+        return DEFAULT_REPORT_THRESHOLD_MS;
+    }
+    return ms;
+}
+/**
+ * Report every native transaction handle in the process-global rocksdb-js registry that has been open
+ * past the threshold — including handles no `DatabaseTransaction` owns, which is the one class of
+ * holder no other surface can see (harper#2471). The registry spans worker threads, so this runs on
+ * the main thread only; a per-thread sweep would report each handle once per worker.
+ */
+function runLongLivedTransactionSweep() {
+    try {
+        const thresholdMs = getReportThresholdMs();
+        rebaseLongLivedTransactionReports(thresholdMs);
+        if (thresholdMs === 0 || !registryStatusFn)
+            return;
+        const status = registryStatusFn();
+        const seen = new Set();
+        const due = [];
+        let missingDetails = false;
+        for (const database of status) {
+            const details = database.transactionDetails;
+            if (!details) {
+                missingDetails = true;
+                continue;
+            }
+            for (const handle of details) {
+                if (handle.ageMs < thresholdMs)
+                    continue;
+                const key = reportKey(database.path, handle.id);
+                seen.add(key);
+                const state = observeHandle(sweepReports, key, handle.ageMs, thresholdMs);
+                if (handle.ageMs >= state.nextReportAgeMs)
+                    due.push({ path: database.path, id: handle.id, ageMs: handle.ageMs, state });
+            }
+        }
+        for (const key of sweepReports.keys())
+            if (!seen.has(key))
+                sweepReports.delete(key);
+        if (missingDetails && !missingDetailsWarned) {
+            missingDetailsWarned = true;
+            logger_ts_1.logger.warn?.('Long-lived transaction reporting is degraded: the installed @harperfast/rocksdb-js does not expose registryStatus().transactionDetails (requires 2.8.0)');
+        }
+        if (due.length === 0)
+            return;
+        due.sort((a, b) => b.ageMs - a.ageMs);
+        for (const handle of due.slice(0, exports.MAX_LONG_LIVED_TRANSACTION_REPORTS_PER_PASS)) {
+            markReported(handle.state, handle.ageMs);
+            logger_ts_1.logger.warn?.(`Long-lived RocksDB transaction handle: id ${handle.id} has been open for ${(0, common_utils_ts_1.prettyDuration)(handle.ageMs)} on database ${handle.path ?? '?'}. ` +
+                `A handle this old can hold write intents that park other writers' commits, and may pin a read snapshot that blocks version reclamation.`);
+        }
+        if (due.length > exports.MAX_LONG_LIVED_TRANSACTION_REPORTS_PER_PASS) {
+            logger_ts_1.logger.warn?.(`${due.length - exports.MAX_LONG_LIVED_TRANSACTION_REPORTS_PER_PASS} further RocksDB transaction handle(s) are open past the ${(0, common_utils_ts_1.prettyDuration)(thresholdMs)} reporting threshold and were not listed individually.`);
+        }
+    }
+    catch (error) {
+        logger_ts_1.logger.error?.('Error sweeping for long-lived transaction handles', error);
+    }
+}
+/**
+ * Start the periodic sweep. Armed unconditionally on the main thread — the pass itself honors a live
+ * threshold change, including one that disables it — and idempotent because the thread startup path
+ * that calls it can run more than once.
+ */
+function startLongLivedTransactionReporting() {
+    if (!node_worker_threads_1.isMainThread || sweepTimer)
+        return;
+    if (!registryStatusFn) {
+        logger_ts_1.logger.debug?.('Long-lived transaction reporting unavailable; @harperfast/rocksdb-js exposes no registryStatus()');
+        return;
+    }
+    sweepTimer = setInterval(runLongLivedTransactionSweep, SWEEP_INTERVAL_MS).unref();
+}
+function createLongLivedHolderReportBudget(thresholdMs) {
+    return { remaining: exports.MAX_LONG_LIVED_TRANSACTION_REPORTS_PER_PASS, skipped: 0, thresholdMs };
+}
+function finishLongLivedHolderReports(reportBudget) {
+    if (reportBudget.skipped === 0)
+        return;
+    try {
+        logger_ts_1.logger.warn?.(`${reportBudget.skipped} further Harper transaction holder(s) are open past the ${(0, common_utils_ts_1.prettyDuration)(reportBudget.thresholdMs)} reporting threshold and were deferred.`);
+    }
+    catch { }
+}
+/**
+ * Report a handle this thread owns, with the attribution the registry sweep cannot supply. The native
+ * id is the join key between the two: the sweep names an id, this names who holds it and which state
+ * kept the open-transaction monitor from reaping it (harper#2471). Never throws — the monitor
+ * interval that calls it has no handler.
+ */
+function reportLongLivedHolder(holder, reportBudget) {
+    try {
+        if (!registryStatusFn)
+            return;
+        const thresholdMs = reportBudget?.thresholdMs ?? getReportThresholdMs();
+        rebaseLongLivedTransactionReports(thresholdMs);
+        if (thresholdMs === 0)
+            return;
+        const now = Date.now();
+        if (now - lastAttributionPruneAt >= ATTRIBUTION_PRUNE_INTERVAL_MS) {
+            lastAttributionPruneAt = now;
+            const expiredBefore = now - ATTRIBUTION_STATE_TTL_MS;
+            for (const [key, state] of attributionReports)
+                if (state.touchedAt < expiredBefore)
+                    attributionReports.delete(key);
+        }
+        const state = observeHandle(attributionReports, reportKey(holder.databasePath, holder.nativeId, holder.openedAt), holder.ageMs, thresholdMs);
+        if (holder.ageMs < state.nextReportAgeMs)
+            return;
+        if (reportBudget && reportBudget.remaining <= 0) {
+            reportBudget.skipped++;
+            return;
+        }
+        markReported(state, holder.ageMs);
+        if (reportBudget)
+            reportBudget.remaining--;
+        const table = holder.tableName ? `.${holder.tableName}` : '';
+        logger_ts_1.logger.warn?.(`Harper transaction has held RocksDB transaction ${holder.nativeId} for ${(0, common_utils_ts_1.prettyDuration)(holder.ageMs)} ` +
+            `on thread ${node_worker_threads_1.threadId}, database ${holder.databaseName ?? '?'}${table} (${holder.databasePath ?? '?'}), ` +
+            `holding ${holder.countPendingWrites()} staged write(s), state: ${holder.states.join('+')}` +
+            (holder.timeoutBudget ? `, open-transaction budget ${holder.timeoutBudget}ms` : '') +
+            (holder.startedFrom?.resourceName
+                ? `, started from ${holder.startedFrom.resourceName}${holder.startedFrom.method ? '.' + holder.startedFrom.method : ''}`
+                : '') +
+            '. It is not being reaped by the open-transaction monitor; the state tells you why.');
+    }
+    catch (error) {
+        logger_ts_1.logger.debug?.('Failed to report a long-lived transaction holder', error);
+    }
+}
+/**
+ * The live handles that could be holding the write intent a stuck commit is parked on, as a sentence
+ * to append to that commit's log. A handle on another database is offered too, labelled with its path:
+ * the verification table is one process-global slot array whose hash mixes in the database id, so a
+ * holder in `system` or `oauth` collides with — and parks — a `data` commit at the same rate two `data`
+ * keys do. Rank puts the stuck commit's own database first, then age. Age only ranks: a coordinated
+ * retry parks on whichever transaction holds the slot when the commit reaches it, which can be younger
+ * than the commit itself, so filtering by age could drop the real holder.
+ * Returns '' rather than throwing — the caller's own 503 must survive a failure here.
+ */
+function describeHolderCandidates(databasePath, excludeNativeId) {
+    if (!databasePath || !registryStatusFn)
+        return '';
+    try {
+        if (getReportThresholdMs() === 0)
+            return '';
+        const target = (0, node_path_1.resolve)(databasePath);
+        const candidates = [];
+        let targetSeen = false;
+        let targetHasDetails = false;
+        for (const database of registryStatusFn()) {
+            // An entry with no path can never be the target, and resolve() would throw on it — which,
+            // inside this loop, would drop the candidate list for every database rather than just this one.
+            const sameDatabase = database.path != null && (0, node_path_1.resolve)(database.path) === target;
+            const details = database.transactionDetails;
+            if (sameDatabase) {
+                targetSeen = true;
+                if (details)
+                    targetHasDetails = true;
+            }
+            if (!details)
+                continue;
+            for (const handle of details)
+                if (!sameDatabase || handle.id !== excludeNativeId)
+                    candidates.push({ id: handle.id, ageMs: handle.ageMs, sameDatabase, path: database.path });
+        }
+        if (!targetHasDetails) {
+            // A database with no other handles is normal; no entry at all means the join between a store's
+            // path and the registry's path has drifted, which is the one worth telling an operator apart.
+            logger_ts_1.logger.debug?.(targetSeen
+                ? `Registry entry for ${target} exposes no transactionDetails; only other databases' handles can be offered as holder candidates for its stuck commit`
+                : `No registry entry for ${target}; only other databases' handles can be offered as holder candidates for its stuck commit`);
+        }
+        if (candidates.length === 0)
+            return '';
+        candidates.sort((a, b) => Number(b.sameDatabase) - Number(a.sameDatabase) || b.ageMs - a.ageMs);
+        const shortlist = candidates.slice(0, MAX_HOLDER_CANDIDATES);
+        // Ranking this database first and then capping can bury the one candidate the cross-database
+        // search exists to surface: a busy database routinely has MAX_HOLDER_CANDIDATES handles of its
+        // own, so a foreign holder would only ever appear inside the "and N more" count. Give the oldest
+        // one the last slot instead.
+        if (shortlist.length === MAX_HOLDER_CANDIDATES && shortlist.every((candidate) => candidate.sameDatabase)) {
+            const foreign = candidates.find((candidate) => !candidate.sameDatabase);
+            if (foreign)
+                shortlist[MAX_HOLDER_CANDIDATES - 1] = foreign;
+        }
+        const named = shortlist
+            .map((candidate) => `${candidate.id} (open ${(0, common_utils_ts_1.prettyDuration)(candidate.ageMs)}${candidate.sameDatabase ? '' : ` on ${candidate.path ?? '?'}`})`)
+            .join(', ');
+        return (` Live transaction handles, any of which could hold the write intent this commit is parked on ` +
+            `(the verification table is one process-global slot array, so a handle on another database can hold it), ` +
+            `this database first, oldest first: ${named}` +
+            (candidates.length > MAX_HOLDER_CANDIDATES ? `, and ${candidates.length - MAX_HOLDER_CANDIDATES} more.` : '.'));
+    }
+    catch {
+        return '';
+    }
+}
+function setRegistryStatusForTests(fn) {
+    registryStatusFn = fn;
+}
+function resetLongLivedTransactionReportsForTests() {
+    sweepReports.clear();
+    attributionReports.clear();
+    invalidThresholdWarned = false;
+    missingDetailsWarned = false;
+    lastAttributionPruneAt = 0;
+    thresholdInEffectMs = -1;
+    if (sweepTimer) {
+        clearInterval(sweepTimer);
+        sweepTimer = undefined;
+    }
+}
+//# sourceMappingURL=longLivedTransactions.js.map

package/dist/resources/longLivedTransactions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"longLivedTransactions.js","sourceRoot":"","sources":["../../resources/longLivedTransactions.ts"],"names":[],"mappings":"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"}

package/dist/resources/models/backendRegistry.d.ts

@@ -18,10 +18,36 @@ import type { DefineBackendSpec, ModelBackend } from './types.ts';
  * step) lands in Phase 2 alongside the first real backend.
  */
 type ModelKind = 'embedding' | 'generative';
+/** A registration a factory made during construction, deferred to the caller. */
+export interface CapturedInstall {
+    kind: ModelKind;
+    logicalName: string;
+    backend: ModelBackend;
+}
 /** Map `logicalName` to a backend for embedding calls. Re-set replaces. */
 export declare function setEmbedding(logicalName: string, backend: ModelBackend): void;
 /** Map `logicalName` to a backend for generative calls. Re-set replaces. */
 export declare function setGenerative(logicalName: string, backend: ModelBackend): void;
+/**
+ * Build a backend through its normal registration path but return it instead of installing it, so a
+ * config reload can install it conditionally. A scratch logical name would be briefly visible
+ * through `listBackends`, which backs the public `GET /v1/models`.
+ */
+export declare function constructBackend(kind: ModelKind, logicalName: string, register: () => void | Promise<void>): Promise<{
+    backend?: ModelBackend;
+    extras: CapturedInstall[];
+}>;
+/**
+ * Replace `logicalName`'s backend for `kind` only if it is still `expected`. A plain `set` is atomic
+ * but unconditional, so concurrent writers resolve by arrival order rather than by which value is
+ * newer. A caller that loses the swap must re-derive from current state rather than overwrite.
+ */
+export declare function replaceIfCurrent(kind: ModelKind, logicalName: string, expected: ModelBackend | undefined, next: ModelBackend): boolean;
+/**
+ * Remove `logicalName`'s backend for `kind` only if it is still `expected`, returning whether it was
+ * removed. Withdrawing a credential must not delete a slot another writer has since taken over.
+ */
+export declare function removeIfCurrent(kind: ModelKind, logicalName: string, expected: ModelBackend | undefined): boolean;
 /** Non-throwing lookup of the backend mapped to `logicalName` for `kind`, or `undefined`. Used by the router to assemble + filter candidate lists without exceptions. */
 export declare function getBackend(kind: ModelKind, logicalName: string): ModelBackend | undefined;
 /**

package/dist/resources/models/backendRegistry.js

@@ -3,6 +3,9 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.ModelBackendRegistrationError = exports.ModelBackendNotFoundError = void 0;
 exports.setEmbedding = setEmbedding;
 exports.setGenerative = setGenerative;
+exports.constructBackend = constructBackend;
+exports.replaceIfCurrent = replaceIfCurrent;
+exports.removeIfCurrent = removeIfCurrent;
 exports.getBackend = getBackend;
 exports.listBackends = listBackends;
 exports.resolveEmbedding = resolveEmbedding;
@@ -10,16 +13,71 @@ exports.resolveGenerative = resolveGenerative;
 exports.registerBackend = registerBackend;
 exports.defineBackend = defineBackend;
 exports.clearRegistry = clearRegistry;
+const node_async_hooks_1 = require("node:async_hooks");
 const hdbError_ts_1 = require("../../utility/errors/hdbError.js");
 const embedding = new Map();
 const generative = new Map();
+// Async-context scoped: a module-global slot would divert unrelated registrations and collide
+// concurrent constructions.
+const captureScope = new node_async_hooks_1.AsyncLocalStorage();
+function install(kind, logicalName, backend) {
+    const slot = captureScope.getStore();
+    if (slot?.active) {
+        if (slot.kind === kind && slot.logicalName === logicalName)
+            slot.backend = backend;
+        else
+            slot.extras.push({ kind, logicalName, backend });
+        return;
+    }
+    (kind === 'embedding' ? embedding : generative).set(logicalName, backend);
+}
 /** Map `logicalName` to a backend for embedding calls. Re-set replaces. */
 function setEmbedding(logicalName, backend) {
-    embedding.set(logicalName, backend);
+    install('embedding', logicalName, backend);
 }
 /** Map `logicalName` to a backend for generative calls. Re-set replaces. */
 function setGenerative(logicalName, backend) {
-    generative.set(logicalName, backend);
+    install('generative', logicalName, backend);
+}
+/**
+ * Build a backend through its normal registration path but return it instead of installing it, so a
+ * config reload can install it conditionally. A scratch logical name would be briefly visible
+ * through `listBackends`, which backs the public `GET /v1/models`.
+ */
+async function constructBackend(kind, logicalName, register) {
+    const slot = { kind, logicalName, extras: [], active: true };
+    try {
+        await captureScope.run(slot, async () => {
+            await register();
+        });
+    }
+    finally {
+        slot.active = false;
+    }
+    return { backend: slot.backend, extras: slot.extras };
+}
+/**
+ * Replace `logicalName`'s backend for `kind` only if it is still `expected`. A plain `set` is atomic
+ * but unconditional, so concurrent writers resolve by arrival order rather than by which value is
+ * newer. A caller that loses the swap must re-derive from current state rather than overwrite.
+ */
+function replaceIfCurrent(kind, logicalName, expected, next) {
+    const map = kind === 'embedding' ? embedding : generative;
+    if (map.get(logicalName) !== expected)
+        return false;
+    map.set(logicalName, next);
+    return true;
+}
+/**
+ * Remove `logicalName`'s backend for `kind` only if it is still `expected`, returning whether it was
+ * removed. Withdrawing a credential must not delete a slot another writer has since taken over.
+ */
+function removeIfCurrent(kind, logicalName, expected) {
+    const map = kind === 'embedding' ? embedding : generative;
+    if (map.get(logicalName) !== expected)
+        return false;
+    map.delete(logicalName);
+    return true;
 }
 /** Non-throwing lookup of the backend mapped to `logicalName` for `kind`, or `undefined`. Used by the router to assemble + filter candidate lists without exceptions. */
 function getBackend(kind, logicalName) {

package/dist/resources/models/backendRegistry.js.map

@@ -1 +1 @@
-{"version":3,"file":"backendRegistry.js","sourceRoot":"","sources":["../../../resources/models/backendRegistry.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"backendRegistry.js","sourceRoot":"","sources":["../../../resources/models/backendRegistry.ts"],"names":[],"mappings":"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"}

package/dist/resources/models/bootstrap.d.ts

@@ -1,3 +1,4 @@
+import { RootConfigWatcher } from '../../config/RootConfigWatcher.ts';
 interface ModelEntry {
     backend?: string;
     host?: string;
@@ -20,7 +21,38 @@ interface RootConfig {
 /**
  * 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()`).
+ * prior registration under the same logical name.
  */
 export declare function bootstrapModels(rootConfig: RootConfig | undefined | null): Promise<void>;
+/** Forget everything the projection installed. Test isolation only — never part of a reload. */
+export declare function resetModelsProjection(): void;
+/**
+ * Apply a `models:` block as a hot reload: changed entries are rebuilt through the same factories
+ * boot uses and swapped in atomically, removed entries stop serving, and programmatic
+ * registrations that overrode a config entry are left in place. Serialized and coalesced —
+ * concurrent calls settle on the latest block.
+ */
+export declare function applyModelsConfig(models: ModelsConfig | undefined): Promise<void>;
+/**
+ * Watch the root config file and hot-apply `models:` changes. Follows `harper_logger`'s
+ * root-config-watch pattern: one watcher per worker, each worker reprojecting its own registry.
+ *
+ * The watcher sees the FILE, but `HARPER_DEFAULT_CONFIG` / `HARPER_CONFIG` / `HARPER_SET_CONFIG`
+ * compose with it at boot — so if any of those names `models`, the file alone is not authoritative
+ * for the block and hot reload stays off, preserving boot semantics unchanged. (That is also the
+ * compatibility gate: an orchestrator still injecting models through `HARPER_SET_CONFIG` gets
+ * today's restart behavior; one that writes the file instead gets live reload.)
+ *
+ * Returns whether the watch is active.
+ */
+export declare function startModelsConfigHotReload(options?: {
+    configFilePath?: string;
+    debounceMs?: number;
+    /** Test seam: invoked when a watcher snapshot is observed, before its settle timer is armed. */
+    onSnapshotObserved?: () => void;
+    /** Test seam: subscribe to this instance (caller-owned) instead of constructing or sharing. */
+    watcher?: RootConfigWatcher;
+}): boolean;
+/** Stop watching the config file. The current projection keeps serving. */
+export declare function stopModelsConfigHotReload(): void;
 export {};