@harperfast/harper 5.2.0 → 5.2.2

package/resources/models/v1/index.ts

@@ -0,0 +1,72 @@
+/**
+ * `/v1/*` OpenAI-compatible gateway (#631).
+ *
+ * Registers three REST resources on the REST port:
+ *   POST /v1/embeddings          → V1Embeddings
+ *   POST /v1/chat/completions    → V1ChatCompletions
+ *   GET  /v1/models              → V1Models
+ *
+ * Off by default, and `defaultConfig.yaml` deliberately ships no `modelsGateway`
+ * block: with the key absent the root loader skips the component before resolving
+ * it, so none of this module graph is imported on an instance that does not use
+ * the gateway. Opt in by adding the block to `harperdb-config.yaml` with
+ * `enabled: true`, or via `set_configuration` (`modelsGateway_enabled`).
+ * `enabled: false` is honored too, for an instance that wants the block present
+ * but inert — that costs the import, which is why it is not the shipped default.
+ *
+ * Example (opt in). `rest` is required: these are REST-served resources and the
+ * gateway deliberately does not force REST to start (see `handleApplication`).
+ * Without it the resources register but every `/v1/*` path 404s.
+ *
+ * ```yaml
+ * rest: true
+ * modelsGateway:
+ *   enabled: true
+ * models:
+ *   generative:
+ *     default:
+ *       backend: ollama
+ *       model: llama3.2
+ * ```
+ *
+ * All three endpoints require `super_user` permission. Anonymous or
+ * insufficient-privilege requests receive a well-formed OpenAI error envelope.
+ */
+
+import type { Scope } from '../../../components/Scope.ts';
+import harperLogger from '../../../utility/logging/harper_logger.ts';
+import { getConfigObj } from '../../../config/configUtils.ts';
+import { V1Embeddings } from './embeddings.ts';
+import { V1ChatCompletions } from './chatCompletions.ts';
+import { V1Models } from './models.ts';
+
+export function handleApplication(scope: Scope): void {
+	if (!scope.options.get(['enabled'])) return;
+	// These resources are served by REST's middleware chain, so the instance must also
+	// have a `rest`/`REST` config section — the gateway deliberately does NOT force REST
+	// to start. Doing so requires reaching into REST's module state before application
+	// configs have loaded, which silently discards an app's own `rest` options (webSocket,
+	// urlPath/host, middleware ordering). Core has no supported way yet for a component to
+	// declare "I serve REST resources"; that gap is tracked separately.
+	//
+	// Warn rather than fail: an app loaded later may still declare `rest`, so absence here
+	// is not conclusive. But defaultConfig ships no `rest` section, so enabling the gateway
+	// alone yields three registered resources and a 404 on every /v1 path — worth a line in
+	// the log instead of silence.
+	const rootConfig = getConfigObj() as Record<string, unknown> | undefined;
+	if (rootConfig && !rootConfig.rest && !rootConfig.REST) {
+		harperLogger.warn(
+			'modelsGateway is enabled but no `rest` section is configured; /v1/* endpoints are only served when REST is active'
+		);
+	}
+	// Explicit protocol visibility: these are REST-only wire-protocol endpoints. Without a
+	// policy, the shared registry matches them for every protocol lookup — WS dispatch could
+	// reach V1ChatCompletions.connect() and then fail iterating its non-iterable badRequest
+	// envelope, and they would surface through MQTT/GraphQL/MCP enumeration too. `sse` stays
+	// enabled for chat only: an explicit `Accept: text/event-stream` POST is dispatched via
+	// the sse lookup (REST.ts) and is a supported streaming client shape (see connect()).
+	const restOnly = { rest: true, sse: false, ws: false, mqtt: false, graphql: false, mcp: false };
+	scope.resources.set('v1/models', V1Models, restOnly);
+	scope.resources.set('v1/embeddings', V1Embeddings, restOnly);
+	scope.resources.set('v1/chat/completions', V1ChatCompletions, { ...restOnly, sse: true });
+}

package/resources/models/v1/models.ts

@@ -0,0 +1,53 @@
+/**
+ * `GET /v1/models` — OpenAI-compatible model list endpoint (#631).
+ *
+ * Enumerates all registered embedding and generative backends from the
+ * process-wide `backendRegistry`. The response mirrors the OpenAI shape:
+ * `{ object: 'list', data: [{ id, object: 'model', created, owned_by }] }`.
+ *
+ * `logicalName` (not `backend.name`) is the `id` — it's what callers pass as
+ * `model` in subsequent requests.
+ */
+
+import { Resource } from '../../Resource.ts';
+import { listBackends } from '../backendRegistry.ts';
+import { authorizeV1Request, type OpenAIErrorResponse } from './errors.ts';
+
+export interface OAIModelEntry {
+	id: string;
+	object: 'model';
+	created: number;
+	owned_by: string;
+}
+
+export interface OAIModelList {
+	object: 'list';
+	data: OAIModelEntry[];
+}
+
+// @ts-ignore — Resource base class is not typed for static dispatch; pattern mirrors login.ts
+export class V1Models extends Resource {
+	// Reserve this fixed route: a later app registration at the same path becomes a
+	// loud conflict (ErrorResource) instead of silently replacing the gateway and its
+	// super_user gate. See Resources.set.
+	static reservedPath = true;
+
+	static get(_target: unknown, request: unknown): OAIModelList | OpenAIErrorResponse {
+		const authError = authorizeV1Request(request as any);
+		if (authError) return authError;
+
+		const created = Math.floor(Date.now() / 1000);
+		// OpenAI model ids are unique; a logical name registered for both generative and
+		// embedding (e.g. `default` in each section) is one model id to callers.
+		const ids = new Set<string>();
+		const data: OAIModelEntry[] = [];
+		for (const kind of ['generative', 'embedding'] as const) {
+			for (const { logicalName } of listBackends(kind)) {
+				if (ids.has(logicalName)) continue;
+				ids.add(logicalName);
+				data.push({ id: logicalName, object: 'model', created, owned_by: 'harper' });
+			}
+		}
+		return { object: 'list', data };
+	}
+}

package/resources/models/v1/translation.ts

@@ -0,0 +1,362 @@
+/**
+ * OpenAI ↔ Harper internal shape mappers for the `/v1/*` gateway (#631).
+ *
+ * All functions are pure (no I/O, no side-effects) so they can be unit-tested
+ * in isolation without a running Harper instance.
+ */
+
+import { randomUUID } from 'node:crypto';
+import type {
+	EmbedOpts,
+	GenerateInput,
+	GenerateOpts,
+	GenerateResult,
+	Message,
+	ToolCall,
+	ToolDef,
+	TokenUsage,
+} from '../types.ts';
+
+// ---------------------------------------------------------------------------
+// OpenAI wire shapes — inlined to avoid a runtime dependency on the SDK
+// ---------------------------------------------------------------------------
+
+export interface OAIMessageIn {
+	role: string;
+	/** May be null for assistant messages that only contain tool_calls. */
+	content: string | null;
+	tool_calls?: Array<{
+		id: string;
+		type: string;
+		function: { name: string; arguments: string };
+	}>;
+	/** Present on role === 'tool' messages. */
+	tool_call_id?: string;
+}
+
+export interface OAIToolIn {
+	type: 'function';
+	function: {
+		name: string;
+		description?: string;
+		parameters?: object;
+	};
+}
+
+export interface OAIChatRequest {
+	model?: string;
+	messages: OAIMessageIn[];
+	tools?: OAIToolIn[];
+	/** Subset recognised: 'none' | 'auto' | 'required' | {type:'function', function:{name}}. */
+	tool_choice?: unknown;
+	temperature?: number;
+	/** OpenAI v1 field; superseded by max_completion_tokens in v1+. */
+	max_tokens?: number;
+	/** Preferred alias; takes precedence over max_tokens when both present. */
+	max_completion_tokens?: number;
+	response_format?: { type: string; json_schema?: unknown };
+	stream?: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// OpenAI request → Harper internal
+// ---------------------------------------------------------------------------
+
+/**
+ * Map an OpenAI `messages` array to Harper `Message[]`.
+ * Normalises `tool_calls[].function.arguments` from JSON strings to parsed
+ * objects (Harper's internal contract); maps `tool_call_id` to `toolCallId`.
+ */
+export function translateMessages(oaiMessages: OAIMessageIn[]): Message[] {
+	return oaiMessages.map((m): Message => {
+		// Content parts are flattened to the text Harper's Message.content expects; shapes
+		// that cannot be flattened are rejected up front by validateChatRequest.
+		const content = Array.isArray(m.content)
+			? (m.content as Array<{ text: string }>).map((part) => part.text).join('')
+			: (m.content ?? '');
+		const base: Message = {
+			// `developer` is OpenAI's successor to `system` (the API itself treats the two
+			// identically, converting `system` to `developer` on models that use the newer
+			// hierarchy). Harper's internal Message union carries the channel as `system`,
+			// which every provider adapter maps to its system-instruction slot — so the
+			// instruction's priority is preserved rather than degraded to `user`. Roles
+			// outside the union are rejected up front by validateChatRequest, so the cast
+			// below is over a vetted set.
+			role: m.role === 'developer' ? 'system' : (m.role as Message['role']),
+			content,
+		};
+		if (m.tool_calls?.length) {
+			base.toolCalls = m.tool_calls.map((tc): ToolCall => {
+				let args: object;
+				try {
+					args = JSON.parse(tc.function.arguments);
+				} catch {
+					// Preserve unparseable argument strings under a sentinel key rather
+					// than dropping them — backend can decide what to do.
+					args = { _raw: tc.function.arguments };
+				}
+				return { id: tc.id, name: tc.function.name, arguments: args };
+			});
+		}
+		if (m.tool_call_id) base.toolCallId = m.tool_call_id;
+		return base;
+	});
+}
+
+/** Map OpenAI `tools[]` to Harper `ToolDef[]`. */
+export function translateTools(oaiTools: OAIToolIn[]): ToolDef[] {
+	return oaiTools.map((t): ToolDef => ({
+		name: t.function.name,
+		description: t.function.description ?? '',
+		parameters: t.function.parameters ?? {},
+	}));
+}
+
+/**
+ * Build Harper `GenerateInput` from translated messages and tool definitions.
+ * Uses the object form `{ messages, tools }` when tools are present, so that
+ * tool definitions travel alongside messages per Harper's type contract.
+ */
+export function toGenerateInput(messages: Message[], tools: ToolDef[] | undefined): GenerateInput {
+	if (tools?.length) return { messages, tools };
+	return messages;
+}
+
+/** `tool_choice` values the internal contract can faithfully represent. */
+function isRepresentableToolChoice(choice: unknown): boolean {
+	return choice === undefined || choice === null || choice === 'auto' || choice === 'none';
+}
+
+/**
+ * Validate the OpenAI wire shapes this gateway maps, returning a client-facing
+ * message for a 400 or `null` when the request is well-formed.
+ *
+ * Kept separate from the mappers so malformed nested input (`messages: [null]`,
+ * `tool_calls: [{}]`, `tools: [{}]`) becomes an OpenAI-shaped 400 instead of a
+ * TypeError escaping the handler as an RFC 9457 500.
+ */
+export function validateChatRequest(body: OAIChatRequest): string | null {
+	const req = body as any;
+	// Top-level fields that control routing and framing first: a non-string `model`
+	// would silently invoke the configured default model (potentially expensive), and a
+	// truthy non-boolean `stream` ("false") would return SSE the client didn't ask for.
+	if (req.model !== undefined && typeof req.model !== 'string') return "'model' must be a string";
+	if (req.stream !== undefined && typeof req.stream !== 'boolean') return "'stream' must be a boolean";
+	if (req.temperature !== undefined) {
+		if (typeof req.temperature !== 'number' || !Number.isFinite(req.temperature)) {
+			return "'temperature' must be a finite number";
+		}
+		if (req.temperature < 0 || req.temperature > 2) return "'temperature' must be between 0 and 2";
+	}
+	for (const field of ['max_tokens', 'max_completion_tokens']) {
+		const value = req[field];
+		if (value === undefined) continue;
+		if (typeof value !== 'number' || !Number.isInteger(value) || value < 1) {
+			return `'${field}' must be a positive integer`;
+		}
+	}
+	if (!Array.isArray(req.messages) || req.messages.length === 0) return "'messages' must be a non-empty array";
+	for (let i = 0; i < req.messages.length; i++) {
+		const m = req.messages[i];
+		if (!m || typeof m !== 'object' || Array.isArray(m)) return `'messages[${i}]' must be an object`;
+		if (typeof m.role !== 'string') return `'messages[${i}].role' must be a string`;
+		// Closed set: translateMessages casts into Harper's Message union, so an
+		// unknown role must be a loud 400 here — previously it was cast through and
+		// provider adapters degraded it to 'user', silently changing its priority.
+		// 'developer' is accepted and carried as 'system' (see translateMessages);
+		// the deprecated 'function' role is deliberately not supported.
+		if (!['system', 'developer', 'user', 'assistant', 'tool'].includes(m.role)) {
+			return `'messages[${i}].role' must be one of 'system', 'developer', 'user', 'assistant', 'tool'`;
+		}
+		// OpenAI allows content parts: [{ type: 'text', text: '...' }, ...]. Harper's
+		// Message.content is a string, so those are flattened in translateMessages; reject
+		// shapes we cannot flatten rather than passing a non-string downstream.
+		if (m.content !== undefined && m.content !== null && typeof m.content !== 'string') {
+			if (!Array.isArray(m.content)) return `'messages[${i}].content' must be a string, array of parts, or null`;
+			for (let p = 0; p < m.content.length; p++) {
+				const part = m.content[p];
+				if (!part || typeof part !== 'object') return `'messages[${i}].content[${p}]' must be an object`;
+				if (part.type !== 'text' || typeof part.text !== 'string') {
+					return `'messages[${i}].content[${p}]' must be a text part ({ type: 'text', text: string }); other part types are not supported yet`;
+				}
+			}
+		}
+		if (m.tool_calls !== undefined) {
+			if (!Array.isArray(m.tool_calls)) return `'messages[${i}].tool_calls' must be an array`;
+			for (let j = 0; j < m.tool_calls.length; j++) {
+				const tc = m.tool_calls[j];
+				const at = `'messages[${i}].tool_calls[${j}]`;
+				if (!tc || typeof tc !== 'object') return `${at}' must be an object`;
+				if (!tc.function || typeof tc.function !== 'object') return `${at}.function' is required`;
+				if (typeof tc.function.name !== 'string') return `${at}.function.name' must be a string`;
+				if (typeof tc.function.arguments !== 'string') return `${at}.function.arguments' must be a JSON string`;
+			}
+		}
+	}
+	if (req.tools !== undefined) {
+		if (!Array.isArray(req.tools)) return "'tools' must be an array";
+		for (let i = 0; i < req.tools.length; i++) {
+			const t = req.tools[i];
+			if (!t || typeof t !== 'object') return `'tools[${i}]' must be an object`;
+			if (!t.function || typeof t.function !== 'object') return `'tools[${i}].function' is required`;
+			if (typeof t.function.name !== 'string') return `'tools[${i}].function.name' must be a string`;
+		}
+	}
+	if (!isRepresentableToolChoice(req.tool_choice)) {
+		// Better a clear 400 than silently downgrading 'required'/named selection to 'auto'.
+		return "'tool_choice' supports 'auto' and 'none'; 'required' and named function selection are not supported yet";
+	}
+	if (req.response_format !== undefined) {
+		const rf = req.response_format;
+		if (!rf || typeof rf !== 'object' || Array.isArray(rf)) return "'response_format' must be an object";
+		if (rf.type === 'json_schema') {
+			const wrapper = rf.json_schema;
+			if (!wrapper || typeof wrapper !== 'object') {
+				return "'response_format.json_schema' is required when type is 'json_schema'";
+			}
+			if (!wrapper.schema || typeof wrapper.schema !== 'object') {
+				return "'response_format.json_schema.schema' must be a JSON Schema object";
+			}
+		}
+	}
+	return null;
+}
+
+/**
+ * Map an OpenAI chat-completion request body to `GenerateOpts`.
+ *
+ * `tool_choice` is honored by the caller, not here: `'none'` omits tools from the
+ * generate input entirely, and unrepresentable choices are rejected up front by
+ * `validateChatRequest`. Full in-process tool-call orchestration is #612 (out of
+ * scope for #631), so tool calls are always returned to the caller to invoke.
+ *
+ * Assumes `validateChatRequest` has already passed.
+ */
+export function toGenerateOpts(body: OAIChatRequest): GenerateOpts {
+	const opts: GenerateOpts = { toolMode: 'return' };
+	if (typeof body.model === 'string') opts.model = body.model;
+	if (typeof body.temperature === 'number') opts.temperature = body.temperature;
+	const maxTokens = body.max_completion_tokens ?? body.max_tokens;
+	if (typeof maxTokens === 'number') opts.maxTokens = maxTokens;
+	if (body.response_format) {
+		const rf = body.response_format;
+		if (rf.type === 'json_object') {
+			opts.responseFormat = 'json';
+		} else if (rf.type === 'json_schema') {
+			// The wire value is a wrapper ({ name, strict, schema }); Harper's contract wants
+			// the JSON Schema itself. Passing the wrapper makes the backend wrap it again and
+			// send metadata where the provider expects the schema.
+			opts.responseFormat = { schema: (rf.json_schema as { schema: object }).schema };
+		} else {
+			opts.responseFormat = 'text';
+		}
+	}
+	return opts;
+}
+
+/** Map an OpenAI embeddings request body to `EmbedOpts`. */
+export function toEmbedOpts(body: { model?: string }): EmbedOpts {
+	const opts: EmbedOpts = {};
+	if (typeof body.model === 'string') opts.model = body.model;
+	return opts;
+}
+
+// ---------------------------------------------------------------------------
+// Harper internal → OpenAI response shapes
+// ---------------------------------------------------------------------------
+
+interface OAIToolCallOut {
+	id: string;
+	type: 'function';
+	function: { name: string; arguments: string };
+}
+
+interface OAIAssistantMessage {
+	role: 'assistant';
+	/** null when the message contains only tool_calls. */
+	content: string | null;
+	tool_calls?: OAIToolCallOut[];
+}
+
+export interface OAIChatCompletion {
+	id: string;
+	object: 'chat.completion';
+	created: number;
+	model: string;
+	choices: Array<{
+		index: number;
+		message: OAIAssistantMessage;
+		finish_reason: string;
+	}>;
+	usage: {
+		prompt_tokens: number;
+		completion_tokens: number;
+		total_tokens: number;
+	};
+}
+
+function toOAIToolCalls(toolCalls: ToolCall[]): OAIToolCallOut[] {
+	return toolCalls.map((tc) => ({
+		id: tc.id,
+		type: 'function',
+		// Guard against backends that return arguments as a pre-serialised JSON string;
+		// passing a string through JSON.stringify would double-encode it.
+		function: {
+			name: tc.name,
+			arguments: typeof tc.arguments === 'string' ? tc.arguments : JSON.stringify(tc.arguments),
+		},
+	}));
+}
+
+/** Map a Harper `GenerateResult` to an OpenAI `chat.completion` response object. */
+export function toChatCompletion(result: GenerateResult, model: string, id?: string): OAIChatCompletion {
+	const completionId = id ?? `chatcmpl-${randomUUID().replaceAll('-', '')}`;
+	const hasTools = !!result.toolCalls?.length;
+	const message: OAIAssistantMessage = {
+		role: 'assistant',
+		// OpenAI sets content to null when there are tool calls and no text content.
+		content: result.content || (hasTools ? null : ''),
+	};
+	if (hasTools) message.tool_calls = toOAIToolCalls(result.toolCalls!);
+	const usage = result.usage ?? {};
+	return {
+		id: completionId,
+		object: 'chat.completion',
+		created: Math.floor(Date.now() / 1000),
+		model,
+		choices: [{ index: 0, message, finish_reason: result.finishReason }],
+		usage: {
+			prompt_tokens: usage.promptTokens ?? 0,
+			completion_tokens: usage.completionTokens ?? 0,
+			total_tokens: (usage.promptTokens ?? 0) + (usage.completionTokens ?? 0),
+		},
+	};
+}
+
+export interface OAIEmbedResponse {
+	object: 'list';
+	data: Array<{ embedding: number[]; index: number; object: 'embedding' }>;
+	model: string;
+	usage: { prompt_tokens: number; total_tokens: number };
+}
+
+/** Map `Float32Array[]` from `models.embed()` to an OpenAI embeddings response. */
+export function toEmbedResponse(vecs: Float32Array[], model: string, usage?: TokenUsage): OAIEmbedResponse {
+	return {
+		object: 'list',
+		data: vecs.map((vec, index) => ({
+			embedding: Array.from(vec),
+			index,
+			object: 'embedding',
+		})),
+		model,
+		// Embeddings have no completion side, so OpenAI reports the same count in both
+		// fields. Harper backends spell it `embeddingTokens` (with `promptTokens` as a
+		// fallback for backends that report it that way); mapping must be symmetric —
+		// a backend supplying only embeddingTokens must not leave prompt_tokens at 0.
+		usage: {
+			prompt_tokens: usage?.embeddingTokens ?? usage?.promptTokens ?? 0,
+			total_tokens: usage?.embeddingTokens ?? usage?.promptTokens ?? 0,
+		},
+	};
+}

package/resources/roles.ts

@@ -13,21 +13,80 @@ const USERS_NOT_DBS: readonly string[] = RESERVED_DATABASE_NAMES;
  * This is the component for handling role declarations in the Harper system. This will read roles.yaml for role
  * definitions and ensure that they are created in the system database.
  */
-export function handleApplication(scope: import('../components/Scope.ts').Scope) {
-	scope.handleEntry(async (entry) => {
-		if (entry.eventType === 'unlink') return;
-		return handleFile((entry as any).contents);
+export function handleApplication(
+	scope: import('../components/Scope.ts').Scope,
+	ensureRoleFn: (role: any) => Promise<unknown> = ensureRole
+) {
+	const rolesByFile = new Map<string, Set<string>>();
+	const contentsByFile = new Map<string, Buffer>();
+	let pending = Promise.resolve();
+	const enqueue = (operation: () => Promise<void>) => {
+		const queued = pending.then(operation);
+		pending = queued.catch(() => {});
+		return queued;
+	};
+	const entryHandler = scope.handleEntry((entry) =>
+		enqueue(async () => {
+			if (entry.entryType !== 'file') return;
+			const previousRoles = rolesByFile.get(entry.absolutePath) ?? new Set<string>();
+			if (entry.eventType === 'unlink') {
+				rolesByFile.delete(entry.absolutePath);
+				contentsByFile.delete(entry.absolutePath);
+				warnForStaleRoles(scope, previousRoles, rolesByFile);
+				return;
+			}
+			contentsByFile.set(entry.absolutePath, entry.contents);
+			const currentRoles = await handleFile(entry.contents, ensureRoleFn);
+			rolesByFile.set(entry.absolutePath, currentRoles);
+			warnForStaleRoles(
+				scope,
+				new Set([...previousRoles].filter((roleName) => !currentRoles.has(roleName))),
+				rolesByFile
+			);
+		})
+	);
+	if (!entryHandler) return;
+	scope.on('deploy:end', () => {
+		void entryHandler.ready
+			.then(() =>
+				enqueue(async () => {
+					for (const contents of contentsByFile.values()) {
+						try {
+							await handleFile(contents, ensureRoleFn);
+						} catch (error) {
+							scope.logger.error?.('Could not reconcile a roles file after deploy:', error);
+						}
+					}
+				})
+			)
+			.catch((error) => scope.logger.error?.('Could not reconcile roles after deploy:', error));
 	});
 }
 
+function warnForStaleRoles(
+	scope: import('../components/Scope.ts').Scope,
+	removedRoles: Set<string>,
+	rolesByFile: Map<string, Set<string>>
+): void {
+	const stillDeclared = new Set<string>();
+	for (const roleNames of rolesByFile.values()) for (const roleName of roleNames) stillDeclared.add(roleName);
+	const staleRoles = [...removedRoles].filter((roleName) => !stillDeclared.has(roleName));
+	if (staleRoles.length === 0) return;
+	scope.logger.warn(
+		`Role definitions removed for ${staleRoles.join(', ')}; existing roles and grants remain active until explicitly altered or deleted`
+	);
+}
+
 /**
  * This function will handle the roles.yaml file content that has been read, and ensure that the roles are translated to
  * the right shape and created in the system database.
  * @param rolesContent
  */
-async function handleFile(rolesContent) {
+async function handleFile(rolesContent, ensureRoleFn: (role: any) => Promise<unknown>) {
 	let rolesToDefine = parseDocument(rolesContent.toString(), { simpleKeys: true } as any).toJSON();
+	const roleNames = new Set<string>();
 	for (let roleName in rolesToDefine) {
+		roleNames.add(roleName);
 		let role = rolesToDefine[roleName];
 		if (!role.permission) {
 			// we allow the permission object to be collapsed into the root object for convenience
@@ -78,8 +137,9 @@ async function handleFile(rolesContent) {
 			}
 		}
 		role.role = role.id = roleName;
-		await ensureRole(role);
+		await ensureRoleFn(role);
 	}
+	return roleNames;
 }
 async function ensureRole(role) {
 	const roleTable = getDatabases().system.hdb_role;
@@ -87,10 +147,10 @@ async function ensureRole(role) {
 	for await (let existingRole of roleTable.search([{ attribute: 'role', value: role.role }] as any)) {
 		// use the existing role id so we can update in place. Legacy roles may have a UUID for the id instead of the role name
 		const { __createdtime__, __updatedtime__, ...existingRoleData } = existingRole;
+		role.id = existingRole.id;
 		if (isEqual(existingRoleData, role)) {
 			return;
 		}
-		role.id = existingRole.id;
 		return alterRole(role);
 	}
 	return addRole(role);

package/resources/search.ts

@@ -147,7 +147,8 @@ export function executeConditions(
 			table,
 			request.allowFullScan,
 			filtered,
-			context
+			context,
+			request.limit !== undefined ? (request.offset || 0) + request.limit : undefined
 		);
 	}
 	function mapConditionsToFilters(conditions, intersection, estimatedIncomingCount) {
@@ -247,7 +248,11 @@ export function searchByIndex(
 	Table: any,
 	allowFullScan?: boolean,
 	filtered?: any,
-	context?: any
+	context?: any,
+	// How many rows the query will ultimately consume (offset + limit), when it is bounded. An
+	// approximate index returns a fixed-size candidate list, so without this a query asking for more
+	// rows than that list holds silently gets a short result set. Only custom indexes read it.
+	minResults?: number
 ): AsyncIterable<Id | { key: Id; value: any }> {
 	let attribute_name = searchCondition[0] ?? searchCondition.attribute;
 	let value = searchCondition[1] ?? searchCondition.value;
@@ -505,7 +510,7 @@ export function searchByIndex(
 			// exploring until it has enough MATCHING results, rather than post-filtering an under-filled
 			// candidate set. Only indexes that opt in (filteredSearch) receive it; others post-filter as before.
 			const recordFilter = index.customIndex.filteredSearch ? searchCondition.recordFilter : undefined;
-			const loaded = index.customIndex.search(searchCondition, context, recordFilter).map((entry) => {
+			const loaded = index.customIndex.search(searchCondition, context, recordFilter, minResults).map((entry) => {
 				// if the custom index returns an entry with metadata, merge it with the loaded entry
 				if (typeof entry === 'object' && entry) {
 					const { key, ...otherProps } = entry;