@harperfast/harper 5.1.20 → 5.2.0-alpha.5

package/resources/indexes/HierarchicalNavigableSmallWorld.ts

@@ -115,6 +115,10 @@ function bisectInsert(arr: Candidate[], distance: number): number {
 const ENTRY_POINT = Symbol.for('entryPoint');
 const KEY_PREFIX = Symbol.for('key');
 const MAX_LEVEL = 10; // should give good high-level skip list performance up to trillions of nodes
+// Visit budget for the post-delete connectivity probe (repairSeveredNeighbors, #1712). Severed
+// islands are small (bounded by the deleted node's neighborhood), so a probe that visits this many
+// nodes without reaching the entry point is treated as connected-but-far and repaired conservatively.
+const PROBE_VISIT_LIMIT = 256;
 type Connection = {
 	id: number;
 	distance: number;
@@ -142,7 +146,12 @@ export class HierarchicalNavigableSmallWorld {
 	// Index options that only affect search, not the stored graph — changing them must not trigger a
 	// reindex (databases.ts persists the new value but skips rebuilding). efConstructionSearch is the
 	// search-time candidate-list size; the build uses efConstruction/M/distance, which are structural.
-	static searchOnlyOptions = ['efConstructionSearch'];
+	// filterExpansion is the visit-budget multiplier for predicate-aware (filtered) traversal.
+	static searchOnlyOptions = ['efConstructionSearch', 'filterExpansion'];
+	// Signals to search.ts that this index accepts a per-record predicate in search() and applies it
+	// during traversal (predicate-aware / ACORN-style filtering), so companion conditions and RBAC can
+	// be pushed down instead of post-filtering an under-filled candidate set (#1241).
+	filteredSearch = true;
 	indexStore: any;
 	M: number = 16; // max number of connections per layer
 	efConstruction: number = 100; // size of dynamic candidate list
@@ -152,6 +161,17 @@ export class HierarchicalNavigableSmallWorld {
 	// a value of 1 is extremely aggressive.
 	optimizeRouting = 0.5;
 	nodesVisitedCount = 0;
+	// Visit-budget multiplier for predicate-aware traversal (#1241). When a filter is selective enough
+	// that layer-0 results never fill `ef`, the "closest candidate worse than worst result" stop rule
+	// never triggers, so maxVisits = ef * filterExpansion caps how many nodes an under-filled filtered
+	// search visits before returning what it has (approximate, like all ANN). It does NOT bound a filter
+	// that fills `ef` — that terminates naturally. Default 24 (not the 8 the design sketch assumed):
+	// this HNSW visits a large fraction of the graph per query, so filling `ef` at selectivity `s` needs
+	// ~ef/s visits; a multiplier of 24 fills down to ~4% selectivity before the budget bites, keeping
+	// recall at or above post-filtering across the range the query planner routes to traversal. Raising
+	// it is nearly free for condition-derived filters (they fill and self-terminate); it mainly trades
+	// latency for recall on selective *function* predicates. Per-query override via the search options.
+	filterExpansion = 24;
 
 	idIncrementer: BigInt64Array | undefined;
 	distance: (a: number[], b: number[]) => number;
@@ -188,6 +208,7 @@ export class HierarchicalNavigableSmallWorld {
 			if (options.efConstructionSearch !== undefined) this.efConstructionSearch = options.efConstructionSearch;
 			if (options.mL !== undefined) this.mL = options.mL;
 			if (options.optimizeRouting !== undefined) this.optimizeRouting = options.optimizeRouting;
+			if (options.filterExpansion !== undefined) this.filterExpansion = options.filterExpansion;
 		}
 	}
 	index(primaryKey: Id, vector: number[], existingVector?: number[], options: any = {}) {
@@ -497,6 +518,10 @@ export class HierarchicalNavigableSmallWorld {
 			this.indexStore.remove(safeKey, options);
 		}
 		const needsReindexing = new Map();
+		// On DELETE, track every neighbor that loses an edge: the empty-list check below only
+		// catches fully-orphaned nodes, but a cluster can stay internally connected while losing
+		// its only bridges to the entry point — see repairSeveredNeighbors (#1712).
+		const edgeLosingNeighborIds = vector ? undefined : new Set<number>();
 		// remove connections to this node that are no longer valid
 		if (oldNode.level !== undefined) {
 			for (let l = 0; l <= oldNode.level; l++) {
@@ -505,6 +530,7 @@ export class HierarchicalNavigableSmallWorld {
 					// get and copy the neighbor node so we can modify it
 					const neighborNode = updateNode(neighborId, this.safeGetSync(neighborId, options));
 					if (!neighborNode) continue;
+					edgeLosingNeighborIds?.add(neighborId);
 					// On an UPDATE (vector != null), only remove the reverse edge at
 					// the exact level l where the old connection existed. Sweeping 0..l would destroy reverse
 					// edges at lower levels that were just re-added by addConnection or preserved by the
@@ -580,9 +606,92 @@ export class HierarchicalNavigableSmallWorld {
 			}
 			this.index(key, orphanVector, orphanVector, options);
 		}
+		if (edgeLosingNeighborIds?.size) this.repairSeveredNeighbors(edgeLosingNeighborIds, options);
 		this.checkSymmetry(nodeId, this.safeGetSync(nodeId, options), options);
 	}
 
+	/**
+	 * After a delete, a neighbor that lost an edge can be severed from the entry point even with
+	 * non-empty connection lists: a locally-connected cluster whose only bridges ran through the
+	 * deleted node becomes a disconnected island, unreachable by search at any ef (#1712). The
+	 * empty-list orphan check in index() can't see this, so probe each edge-losing neighbor's
+	 * connectivity and reindex the ones that are cut off.
+	 *
+	 * The probe is a level-prioritized best-first traversal (hubs first, since the entry point is
+	 * a high-level node), treating edges as undirected — the same assumption validateConnectivity
+	 * makes. Note the direction difference: the probe walks source→entry-point over stored
+	 * (outgoing) edges while search walks entry-point→outward, so an asymmetric edge could make
+	 * the probe claim connectivity that search doesn't have. Edges are bidirectional by
+	 * construction (checkSymmetry logs violations), and reverse-reachability from the entry point
+	 * would be O(N) per delete, so this is a deliberate residual. In a connected component the
+	 * probe reaches the known-connected set within a few hops; in an island it exhausts the
+	 * island quickly. If it exceeds PROBE_VISIT_LIMIT without an answer (pathologically distant
+	 * entry point — or an island larger than the budget), reinsert just the probe source: a
+	 * wasted reinsert in the connected case, and in the oversized-island case a partial repair
+	 * (the source relinks to the live graph, the rest of the island stays severed — reindexing
+	 * replaces the source's edges rather than bridging through them, and reindexing all 256+
+	 * probed nodes on what is usually just a distant entry point would be far too expensive).
+	 */
+	private repairSeveredNeighbors(neighborIds: Set<number>, options: any) {
+		const entryPointId = this.indexStore.getSync(ENTRY_POINT, options);
+		if (entryPointId === undefined) return;
+		const knownConnected = new Set<number>([entryPointId]);
+		for (const sourceId of neighborIds) {
+			if (knownConnected.has(sourceId)) continue;
+			const sourceNode = this.safeGetSync(sourceId, options);
+			if (!sourceNode || sourceNode.level === undefined) continue; // already removed or stale reference
+			const visited = new Map<number, Node>([[sourceId, sourceNode]]);
+			const frontier = new MinHeap();
+			frontier.push({ id: sourceId, distance: -sourceNode.level, node: sourceNode });
+			let verdict: 'connected' | 'island' | 'inconclusive' = 'island';
+			probe: for (;;) {
+				const current = frontier.pop();
+				if (!current) break; // exhausted the reachable set without touching the connected component
+				for (let l = 0; l <= current.node.level; l++) {
+					for (const { id: neighborId } of current.node[l] || []) {
+						if (neighborId === undefined) continue;
+						if (knownConnected.has(neighborId)) {
+							verdict = 'connected';
+							break probe;
+						}
+						if (visited.has(neighborId)) continue;
+						const node = this.safeGetSync(neighborId, options);
+						if (!node || node.level === undefined) continue; // stale reference
+						visited.set(neighborId, node);
+						frontier.push({ id: neighborId, distance: -node.level, node });
+					}
+				}
+				if (visited.size > PROBE_VISIT_LIMIT) {
+					verdict = 'inconclusive';
+					break;
+				}
+			}
+			if (verdict === 'connected') {
+				// every visited node connects to the source, which reaches the connected component
+				for (const id of visited.keys()) knownConnected.add(id);
+			} else {
+				// island: reinsert every member so the whole cluster relinks to the live graph;
+				// inconclusive: reinsert only the source (partial repair — see docstring)
+				if (verdict === 'inconclusive') {
+					logger.warn?.('connectivity probe exceeded visit budget after a delete, reinserting only', sourceId);
+				}
+				const toReindex = verdict === 'island' ? visited.values() : [sourceNode];
+				logger.debug?.('reindexing nodes severed from the entry point by a delete', sourceId);
+				for (const node of toReindex) {
+					const nodeVector =
+						node.scale !== undefined ? dequantizeInt8(node.vector as Int8Array, node.scale) : (node.vector as number[]);
+					this.index(node.primaryKey, nodeVector, nodeVector, options);
+				}
+				if (verdict === 'island') {
+					// the whole reindexed island is now relinked; skip re-probing its members
+					for (const id of visited.keys()) knownConnected.add(id);
+				} else {
+					knownConnected.add(sourceId);
+				}
+			}
+		}
+	}
+
 	private safeGetSync(key: any, options?: any): any {
 		try {
 			let node = this.indexStore.getSync(key, options);
@@ -643,7 +752,13 @@ export class HierarchicalNavigableSmallWorld {
 		ef: number,
 		level: number,
 		options: { transaction?: any } = {},
-		distanceFunction = this.distance
+		distanceFunction = this.distance,
+		// Predicate-aware traversal (#1241, layer 0 only). `filter` decides result admission by primary
+		// key; non-matching nodes still route (they stay in the candidate/visited sets) so the graph
+		// remains navigable under selective filters (ACORN). `filterState` carries the visit budget and
+		// per-query counters. Both are undefined for routing layers and for unfiltered searches.
+		filter?: (primaryKey: Id) => boolean,
+		filterState?: FilterState
 	): SearchResults {
 		// Pre-compute query magnitude for cosine; use cached invMag on stored nodes to skip sqrt per neighbor.
 		// Asymmetric distance: the query stays full-precision float; a stored neighbor may be int8
@@ -697,13 +812,62 @@ export class HierarchicalNavigableSmallWorld {
 
 		const candidates = new MinHeap();
 		candidates.push(initialCandidate);
-		const results = [initialCandidate] as SearchResults;
 
+		if (!filter) {
+			// Unfiltered path (unchanged): results are seeded with the entry point and every visited
+			// node is admitted; the stop rule is "closest remaining candidate worse than worst result".
+			const results = [initialCandidate] as SearchResults;
+			while (candidates.size > 0) {
+				const current = candidates.pop()!;
+				const furthestDistance = results[results.length - 1].distance;
+
+				if (current.distance > furthestDistance) break;
+
+				for (const { id: neighborId } of current.node[level] || []) {
+					if (visited.has(neighborId) || neighborId === undefined) continue;
+					visited.add(neighborId);
+
+					const neighbor = this.safeGetSync(neighborId, options);
+					if (!neighbor) continue;
+					this.nodesVisitedCount++;
+					const distance = computeDistance(neighbor.vector, neighbor.invMag, neighbor.scale);
+
+					if (distance < furthestDistance || results.length < ef) {
+						const candidate: Candidate = { id: neighborId, distance, node: neighbor };
+						candidates.push(candidate);
+						results.splice(bisectInsert(results, distance), 0, candidate);
+						if (results.length > ef) results.pop();
+					}
+				}
+			}
+			results.visited = visited.size;
+			return results;
+		}
+
+		// Predicate-aware path (#1241). `results` holds only nodes the filter admits, but every visited
+		// node still routes: it enters the candidate heap and can be expanded, preserving connectivity
+		// through non-matching regions. Because matches accrue slower than visits, the distance stop rule
+		// only applies once `ef` matches are in hand; until then we keep expanding.
+		//
+		// maxVisits = ef * filterExpansion is a hard ceiling on layer-0 node visits. It has to be
+		// generous enough NOT to truncate a non-selective filter before it fills `ef` (filling at
+		// selectivity `s` costs ~ef/s visits) — that is why the default filterExpansion is larger than a
+		// standard-HNSW rule of thumb, since this index visits a large fraction of the graph per query.
+		// It matters as a genuine bound in two cases: a selective filter that can never fill `ef` (where
+		// the alternative is crawling the whole graph — the same regime the planner diverts to the exact
+		// brute-force path for condition filters, leaving function predicates the real beneficiary), and
+		// a filter that fills `ef` with distant matches (a loose worst-match bound would otherwise let
+		// the distance rule explore almost everything).
+		// search() always supplies filterState alongside filter; default one for any direct caller that doesn't.
+		if (!filterState) filterState = { maxVisits: Infinity, nodesVisited: 0, filterEvaluations: 0 };
+		const results = [] as unknown as SearchResults;
+		if (this.admit(filter, filterState, entryPoint.primaryKey)) results.push(initialCandidate);
+		let budgetExhausted = false;
 		while (candidates.size > 0) {
 			const current = candidates.pop()!;
-			const furthestDistance = results[results.length - 1].distance;
-
-			if (current.distance > furthestDistance) break;
+			// Once we have ef matches, the worst of them bounds useful exploration; before that, keep going.
+			const furthestDistance = results.length >= ef ? results[results.length - 1].distance : Infinity;
+			if (results.length >= ef && current.distance > furthestDistance) break;
 
 			for (const { id: neighborId } of current.node[level] || []) {
 				if (visited.has(neighborId) || neighborId === undefined) continue;
@@ -712,20 +876,41 @@ export class HierarchicalNavigableSmallWorld {
 				const neighbor = this.safeGetSync(neighborId, options);
 				if (!neighbor) continue;
 				this.nodesVisitedCount++;
+				filterState.nodesVisited++;
 				const distance = computeDistance(neighbor.vector, neighbor.invMag, neighbor.scale);
 
+				// Route through any node that could still improve the result set (under-filled or nearer
+				// than the current worst match) — filtering does not prune the graph, only admission.
 				if (distance < furthestDistance || results.length < ef) {
 					const candidate: Candidate = { id: neighborId, distance, node: neighbor };
 					candidates.push(candidate);
-					results.splice(bisectInsert(results, distance), 0, candidate);
-					if (results.length > ef) results.pop();
+					if (this.admit(filter, filterState, neighbor.primaryKey)) {
+						results.splice(bisectInsert(results, distance), 0, candidate);
+						if (results.length > ef) results.pop();
+					}
+				}
+				if (filterState.nodesVisited >= filterState.maxVisits) {
+					budgetExhausted = true;
+					break;
 				}
 			}
+			if (budgetExhausted) break;
 		}
 		results.visited = visited.size;
 		return results;
 	}
 
+	/**
+	 * Evaluate the traversal predicate for one node, counting the evaluation for `explain`. Kept as a
+	 * tiny helper so both the entry-point seed and the neighbor loop share the counting path. The filter
+	 * itself memoizes verdicts per query (a node can be reached from multiple neighbors), so this stays
+	 * cheap even when the predicate loads a record.
+	 */
+	private admit(filter: (primaryKey: Id) => boolean, filterState: FilterState | undefined, primaryKey: Id): boolean {
+		if (filterState) filterState.filterEvaluations++;
+		return filter(primaryKey);
+	}
+
 	/**
 	 * This the main entry from Harper's query functionality, where we actually search for an ordered list of nearest
 	 * neighbors, using the provided sort/order definition object and performing the multi-layer skip-list search.
@@ -745,6 +930,7 @@ export class HierarchicalNavigableSmallWorld {
 			distance,
 			comparator,
 			ef,
+			filterExpansion,
 		}: {
 			target: number[];
 			value: number;
@@ -752,8 +938,14 @@ export class HierarchicalNavigableSmallWorld {
 			distance: string;
 			comparator: string;
 			ef?: number;
+			filterExpansion?: number;
 		},
-		context: any
+		context: any,
+		// Predicate-aware traversal (#1241). When provided, only nodes for which `filter(primaryKey)`
+		// returns true are admitted to the result list at layer 0; routing is unaffected. Composed by
+		// search.ts from companion AND conditions, a caller-supplied `vectorFilter`, and record-level
+		// RBAC. Must be synchronous and side-effect free. JS-API only (never from a REST query string).
+		filter?: (primaryKey: Id) => boolean
 	) {
 		let limit: number | undefined; // only set for threshold comparators; 0 is a valid threshold (e.g. dotProduct)
 		let limitInclusive = false; // true for `le`, false for `lt`
@@ -793,14 +985,34 @@ export class HierarchicalNavigableSmallWorld {
 				: (this.indexStore.getStats?.()?.entryCount ?? 0);
 			effectiveEf = autoScaleEf(nodeCount);
 		}
+		// Predicate-aware traversal budget (#1241): matches accrue slower than visits under a selective
+		// filter, so bound layer-0 work at ef * filterExpansion nodes. Only built when a filter is active.
+		const filterState: FilterState | undefined = filter
+			? {
+					maxVisits: effectiveEf * (filterExpansion && filterExpansion > 0 ? filterExpansion : this.filterExpansion),
+					nodesVisited: 0,
+					filterEvaluations: 0,
+				}
+			: undefined;
 		let entryPoint = this.getEntryPoint(options);
-		if (!entryPoint) return [];
+		if (!entryPoint) return withStats([], filterState);
 		let entryPointId = entryPoint.id;
 		let results: Candidate[] = [];
-		// For each level from top to bottom
+		// For each level from top to bottom. The filter applies only at layer 0 (result admission);
+		// upper layers route unfiltered so non-matching hubs still guide the descent.
 		for (let l = entryPoint.level; l >= 0; l--) {
 			// Search for closest neighbors at current level
-			results = this.searchLayer(target, entryPointId, entryPoint, effectiveEf, l, options, distanceFunction);
+			results = this.searchLayer(
+				target,
+				entryPointId,
+				entryPoint,
+				effectiveEf,
+				l,
+				options,
+				distanceFunction,
+				l === 0 ? filter : undefined,
+				l === 0 ? filterState : undefined
+			);
 
 			if (results.length > 0) {
 				const neighbor = results[0]; // closest neighbor becomes new entry point
@@ -812,11 +1024,14 @@ export class HierarchicalNavigableSmallWorld {
 			results = results.filter((candidate) =>
 				limitInclusive ? candidate.distance <= limit : candidate.distance < limit
 			);
-		return results.map((candidate) => ({
-			// we return the result as an entry so we can provide distance as metadata
-			key: candidate.node.primaryKey, // return value
-			distance: candidate.distance,
-		}));
+		return withStats(
+			results.map((candidate) => ({
+				// we return the result as an entry so we can provide distance as metadata
+				key: candidate.node.primaryKey, // return value
+				distance: candidate.distance,
+			})),
+			filterState
+		);
 	}
 	/**
 	 * Exact distance between a query and a record's FULL-precision vector, mirroring search()'s metric
@@ -1052,3 +1267,22 @@ type Candidate = {
 	node: Node;
 };
 type SearchResults = Candidate[] & { visited: number };
+// Per-query state for predicate-aware traversal (#1241): the visit budget plus counters surfaced for
+// tuning (nodesVisited / filterEvaluations). One instance per search(), threaded to the layer-0 searchLayer.
+type FilterState = {
+	maxVisits: number;
+	nodesVisited: number;
+	filterEvaluations: number;
+};
+/**
+ * Attach filtered-traversal counters to the returned entries array so callers (search.ts / explain) can
+ * report how much of the graph a filtered query touched. No-op for unfiltered searches. Non-enumerable so
+ * the stats don't leak into iteration/serialization of the result entries.
+ */
+function withStats<T extends any[]>(entries: T, filterState: FilterState | undefined): T {
+	if (filterState) {
+		Object.defineProperty(entries, 'nodesVisited', { value: filterState.nodesVisited, enumerable: false });
+		Object.defineProperty(entries, 'filterEvaluations', { value: filterState.filterEvaluations, enumerable: false });
+	}
+	return entries;
+}

package/resources/jsResource.ts

@@ -1,5 +1,6 @@
 import { Scope } from '../components/Scope.ts';
 import { dirname } from 'path';
+import { signalResourcesRegistered } from '../utility/signalling.ts';
 
 function isResource(value: any) {
 	return (
@@ -96,6 +97,11 @@ export async function handleApplication(scope: Scope) {
 				scope.logger.debug?.(`Registered root resource: ${path}`);
 			}
 			recurseForResources(scope, resourceModule, root);
+			// A JS resource that extends an exported @table is the one carrying author opt-ins
+			// (`static mcpTools`/`mcpPrompts`), and it registers here — after the schema-derived
+			// table class and after the MCP component's boot scan. Signal so listing surfaces
+			// (MCP application tools) rebuild against the now-settled registry (#1448).
+			signalResourcesRegistered();
 		} catch (error) {
 			// Rethrow with more context
 			throw new ResourceLoadError(entryEvent.absolutePath, error);

package/resources/loadEnv.ts

@@ -1,6 +1,8 @@
 import { parse } from 'dotenv';
 import logger from '../utility/logging/harper_logger.ts';
 import { Scope } from '../components/Scope.ts';
+import { isEncryptedEnvValue } from '../utility/envFile.ts';
+import { deferEncryptedEnvValue, getSecretDecryptor } from './secretDecryptor.ts';
 import { CONFIG_SHAPING_ENV_VARS } from '../config/componentEnvPrepass.ts';
 
 export function handleApplication(scope: Scope) {
@@ -11,7 +13,36 @@ export function handleApplication(scope: Scope) {
 			return;
 		}
 		logger.debug(`Loading env file: ${entry.absolutePath}`);
-		for (const [key, value] of Object.entries(parse(entry.contents))) {
+		for (const [key, rawValue] of Object.entries(parse(entry.contents))) {
+			let value = rawValue;
+			// Encrypted (`enc:v1:`) values are decrypted via the Pro env-secrets component if it has
+			// registered a decryptor; otherwise the secret stays opaque and is skipped (so the app
+			// fails loudly on a missing var rather than receiving ciphertext as the value).
+			if (isEncryptedEnvValue(rawValue)) {
+				const decryptor = getSecretDecryptor();
+				// Logged at error level (not warn) so an undecryptable secret is never silent — but
+				// skipped rather than fatal, so the node still boots and the bad value can be fixed via
+				// set_env_value, and a non-Pro node isn't crashed by a replicated encrypted value. The
+				// entry is also queued so a decryptor that registers later (custody can come up after
+				// component `.env` loading) replays it into process.env; until then the app sees a
+				// missing var (and should fail on it) rather than receiving ciphertext.
+				if (!decryptor) {
+					logger.error(
+						`Environment variable ${key} from ${entry.absolutePath} is encrypted but no env-secret decryptor is registered yet (the Harper Pro env-secrets component is required); deferring`
+					);
+					deferEncryptedEnvValue({ key, rawValue, sourcePath: entry.absolutePath, override });
+					continue;
+				}
+				try {
+					value = decryptor(rawValue);
+				} catch (error) {
+					logger.error(
+						`Failed to decrypt environment variable ${key} from ${entry.absolutePath}: ${(error as Error).message}; skipping`
+					);
+					continue;
+				}
+			}
+
 			if (CONFIG_SHAPING_ENV_VARS.includes(key)) {
 				// covers components deployed after boot too — the boot-time pre-pass only sees
 				// components present when the config is composed (#1513)
@@ -20,8 +51,8 @@ export function handleApplication(scope: Scope) {
 				);
 				// Enforce at the injection point: the trio must never reach process.env
 				// from a component .env — anything downstream that (re)composes config
-				// from process.env would otherwise silently honor it, re-inverting the
-				// top-down config relationship.
+				// from process.env (e.g. #1618/#1726's OptionsWatcher) would otherwise
+				// silently honor it, re-inverting the top-down config relationship.
 				continue;
 			}
 			if (process.env[key] !== undefined) {

package/resources/login.ts

@@ -12,9 +12,9 @@ class Login extends Resource {
 		// TODO: Return a login page
 	}
 	static async post(_id, body, request) {
-		const { username, password } = body;
+		const { username, password, token } = body;
 		return {
-			data: await request.login(username, password),
+			data: await request.login(username, password, token),
 		};
 	}
 }

package/resources/models/Models.ts

@@ -112,7 +112,7 @@ export class Models implements ModelsContract {
 			signal?.throwIfAborted();
 			const attemptStart = performance.now();
 			try {
-				const backendOpts: BackendOpts<EmbedOpts> = { ...opts, signal, accounting };
+				const backendOpts = toBackendOpts(opts, signal, accounting);
 				const result = await backend.embed!(input, backendOpts);
 				// Throw on `pending` BEFORE recording success — otherwise we'd write a
 				// success row followed by a failure row from the catch (duplicate).
@@ -166,7 +166,7 @@ export class Models implements ModelsContract {
 			signal?.throwIfAborted();
 			const attemptStart = performance.now();
 			try {
-				const backendOpts: BackendOpts<GenerateOpts> = { ...opts, signal, accounting };
+				const backendOpts = toBackendOpts(opts, signal, accounting);
 				const result = await backend.generate!(input, backendOpts);
 				if (result.status !== 'completed') throw new ModelPendingNotSupportedError(backend.name);
 				this.#record(backend, 'generate', opts.model, accounting, opts, result, attemptStart);
@@ -210,7 +210,7 @@ export class Models implements ModelsContract {
 		}
 		// First candidate only — mid-stream fallback would mean replaying already-yielded chunks.
 		const backend = resolved.candidates[0];
-		const backendOpts: BackendOpts<GenerateOpts> = { ...opts, signal, accounting };
+		const backendOpts = toBackendOpts(opts, signal, accounting);
 		return this.#wrapStream(backend, input, backendOpts, opts, accounting, startedAt);
 	}
 
@@ -352,6 +352,22 @@ type Resolution = { candidates: ModelBackend[] } | { error: Error; backend: Mode
  * against a backend that actually supports the call (the default router never returns
  * empty for a satisfying primary; it only drops on name or capability miss).
  */
+/**
+ * Builds the options passed to a backend call. `opts.model` is the LOGICAL name — it selects
+ * the configured entry via resolveCandidates and must not reach the backend, where it would
+ * override the entry's configured wire model id (#1593: `@embed(model: "default")` sent the
+ * literal string "default" to the provider). Backends always use their own configured model.
+ */
+function toBackendOpts<TOpts extends { model?: string; signal?: AbortSignal }>(
+	opts: TOpts,
+	signal: AbortSignal | undefined,
+	accounting: AccountingContext
+): BackendOpts<TOpts> {
+	const backendOpts = { ...opts, signal, accounting };
+	delete backendOpts.model;
+	return backendOpts;
+}
+
 function resolveCandidates(kind: ResolveKind, model: string | undefined, requires: Capability[]): Resolution {
 	const logicalName = model ?? 'default';
 	const candidates = getRouter().route({ kind, logicalName, requires });

package/resources/models/embedHook.ts

@@ -118,9 +118,20 @@ export function buildEmbedBefore(
 				try {
 					vector = await embedder(record);
 				} catch (err) {
-					// Backend errors can carry URLs / key tails; log raw, rethrow sanitized.
+					// Backend errors can carry URLs / key tails; log raw, rethrow sanitized. Include
+					// only safe identifiers (error class name, upstream HTTP status) so the failure is
+					// diagnosable without hunting through server logs (#1593). upstreamStatus is the
+					// provider's status — NOT ServerError's statusCode, which is Harper's own response
+					// status and would misleadingly read 500 here.
 					getLogger().error?.(`Embedder for attribute "${attr.name}" failed:`, err);
-					throw new Error(`Failed to compute embedding for attribute "${attr.name}"`);
+					const status = (err as any)?.upstreamStatus;
+					const errName = (err as any)?.name;
+					const detail =
+						(errName && errName !== 'Error' ? ` [${errName}]` : '') +
+						(typeof status === 'number' ? ` (backend HTTP ${status})` : '');
+					throw new Error(
+						`Failed to compute embedding for attribute "${attr.name}"${detail} — see server log for details`
+					);
 				}
 				record[attr.name] = normalizeVector(vector);
 			})