@harperfast/harper 5.0.30 → 5.1.0-beta.2

package/resources/models/types.ts

@@ -0,0 +1,296 @@
+/**
+ * Public type surface for the model-access API (`scope.models`).
+ *
+ * Phase 1 foundation of #510. Other phases (ollama, openai, gateway, @embed,
+ * anthropic, bedrock) consume these types; changes here cascade.
+ *
+ * Reference: planning artifact `tmp/harper-510-phase-1-detail.md` (canonical shapes).
+ */
+
+export interface Models {
+	embed(input: string | string[], opts?: EmbedOpts): Promise<Float32Array[]>;
+	generate(input: GenerateInput, opts?: GenerateOpts): Promise<GenerateResult>;
+	generateStream(input: GenerateInput, opts?: GenerateOpts): AsyncIterable<GenerateChunk>;
+}
+
+export interface ModelBackend {
+	readonly name: string;
+	capabilities(): ModelCapabilities;
+	embed?(input: string | string[], opts: BackendOpts<EmbedOpts>): Promise<ModelCallResult<Float32Array[]>>;
+	generate?(input: GenerateInput, opts: BackendOpts<GenerateOpts>): Promise<ModelCallResult<GenerateResult>>;
+	generateStream?(input: GenerateInput, opts: BackendOpts<GenerateOpts>): AsyncIterable<GenerateChunk>;
+}
+
+export interface ModelCapabilities {
+	embed: boolean;
+	generate: boolean;
+	stream: boolean;
+	tools: boolean;
+	adapters: boolean;
+}
+
+export type EmbedOpts = {
+	model?: string;
+	/** For models that distinguish document-vs-query embeddings (e.g. nomic-embed-text); ignored otherwise. */
+	inputType?: 'document' | 'query';
+	signal?: AbortSignal;
+};
+
+export type GenerateOpts = {
+	model?: string;
+	adapter?: string;
+	temperature?: number;
+	maxTokens?: number;
+	responseFormat?: 'text' | 'json' | { schema: object };
+	/**
+	 * How to handle tool calls the model emits. `'return'` (default) hands tool-call
+	 * requests back to the caller; `'auto'` resolves them in-process to completion.
+	 * The tool definitions themselves live on `GenerateInput`'s object variant
+	 * (alongside `messages` and `system`) — they're content, not strategy.
+	 */
+	toolMode?: 'return' | 'auto';
+	/**
+	 * `toolMode: 'auto'` only. Hard cap on backend → tool → backend iterations
+	 * before the loop emits `BudgetExceededError({kind: 'iterations'})`. Default 10.
+	 */
+	maxToolIterations?: number;
+	/**
+	 * `toolMode: 'auto'` only. Cumulative prompt+completion token cap across all
+	 * iterations. Trips `BudgetExceededError({kind: 'tokens'})` when exceeded.
+	 *
+	 * Best-effort: enforcement depends on the backend reporting `usage`. Against a
+	 * backend that returns no usage the cap is unmeasurable — the loop warns once and
+	 * continues (it does NOT silently pretend the cap is in force); `maxToolIterations`
+	 * remains the hard bound. Not yet supported on `generateStream` (throws 501).
+	 */
+	maxToolTokens?: number;
+	/**
+	 * `toolMode: 'auto'` only. Cumulative cost cap across all iterations. The v1
+	 * cost-per-call function returns 0 (no rate card yet) so this trips only when
+	 * a test or follow-up wires a non-zero function — the seam is in place.
+	 *
+	 * Same best-effort caveat as `maxToolTokens`: cost is derived from backend usage,
+	 * so a backend reporting no usage makes the cap unmeasurable (warn-once, continue).
+	 * Not yet supported on `generateStream` (throws 501).
+	 */
+	maxCostUsd?: number;
+	/**
+	 * `toolMode: 'auto'` only. When a single backend round emits multiple tool calls,
+	 * `'parallel'` (default) runs handlers concurrently via `Promise.all`; `'serial'`
+	 * runs them in order. Each handler is its own dispatch — no shared transaction.
+	 */
+	toolParallelism?: 'parallel' | 'serial';
+	/**
+	 * `toolMode: 'auto'` only. Per-tool-result byte cap (JSON-stringified) before
+	 * truncation. The model sees only the truncated form; the trace records the
+	 * original size. Default 65_536.
+	 */
+	toolResultMaxBytes?: number;
+	/**
+	 * `toolMode: 'auto'` only. How to validate tool-call arguments against the
+	 * tool's `parameters` JSON Schema. v1 implements `'none'` (default); `'strict'`
+	 * and `'lenient'` are reserved on the type surface but throw `501` at the loop
+	 * entry until a JSON Schema validator is wired (Harper today uses Joi for
+	 * internal validation and passes JSON Schema through to backends; adopting
+	 * Ajv is a separate decision).
+	 */
+	toolArgValidation?: 'strict' | 'lenient' | 'none';
+	/**
+	 * `toolMode: 'auto'` only. When a tool handler throws, `'recover'` (default)
+	 * appends the error as a tool result so the model can react; `'abort'` returns
+	 * the error to the caller with the full trace attached.
+	 */
+	toolErrorMode?: 'recover' | 'abort';
+	/**
+	 * `toolMode: 'auto'` only. When true, the resolved `GenerateResult.trace` is
+	 * populated with per-iteration entries. On error paths the trace is always
+	 * returned (via `BudgetExceededError.partialTrace`) regardless of this flag.
+	 */
+	includeToolTrace?: boolean;
+	/**
+	 * `toolMode: 'auto'` only. Caller-supplied dispatch table keyed by tool name.
+	 * The model emits a tool call → loop looks up the handler here. v1 contract;
+	 * the registry seam (#615) replaces this with a `scope.resources` lookup.
+	 *
+	 * Lookup is own-property + callable only (a model-emitted name matching an Object
+	 * prototype member never resolves a built-in). Missing-handler behavior splits on
+	 * whether the name was declared in `tools`: a DECLARED name with no handler is a
+	 * caller config bug (hard `ClientError(400)`); an UNDECLARED name is treated as a
+	 * model hallucination and routed through `toolErrorMode` (recover feeds an
+	 * "unknown tool" error back to the model; abort stops the loop).
+	 */
+	toolHandlers?: Record<string, ToolHandler>;
+	/**
+	 * `toolMode: 'auto'` only. Optional hook called as turns flow through the loop
+	 * (user → assistant → tool → assistant → ...). Structural shape — not coupled
+	 * to #511's `ConversationResource` so callers can plug in their own store.
+	 */
+	conversation?: ConversationAppender;
+	/** Accepted in Phase 1; activates with #511 (ConversationResource). */
+	conversationId?: string;
+	signal?: AbortSignal;
+};
+
+/**
+ * Generation input. Tools and system prompt live here (with `messages`) because
+ * they are model-facing content. Caller must use the object form to supply tools:
+ * `{ messages, tools, system }`.
+ */
+export type GenerateInput = string | Message[] | { messages: Message[]; tools?: ToolDef[]; system?: string };
+
+/** Options handed to a backend: caller-supplied opts plus runtime accounting context. */
+export type BackendOpts<TOpts> = TOpts & { accounting: AccountingContext };
+
+export interface AccountingContext {
+	/** Free-form tenant identifier (v1). Pending canonical model from #510 comment thread. */
+	tenantId?: string;
+	/** Resource path (e.g. matched route) of the calling Resource, if any. */
+	app?: string;
+}
+
+/**
+ * Backend call result.
+ *
+ * `pending` is reserved for future long-running operations (Bedrock batch, fabric LROs);
+ * no Phase 1 backend emits it. The public `Models` facade unwraps `completed` and
+ * matches #510's `Promise<Float32Array[]>` / `Promise<GenerateResult>` signatures,
+ * throwing if a backend returns `pending` until the LRO surface is added.
+ */
+export type ModelCallResult<T> =
+	| { status: 'completed'; output: T; usage?: TokenUsage }
+	| { status: 'pending'; operationId: string; resumeAfter?: number };
+
+export interface TokenUsage {
+	promptTokens?: number;
+	completionTokens?: number;
+	embeddingTokens?: number;
+	gpuMs?: number;
+	latencyMs?: number;
+}
+
+export interface Message {
+	role: 'system' | 'user' | 'assistant' | 'tool';
+	content: string;
+	/** When `role === 'assistant'`: tool calls the model requested. */
+	toolCalls?: ToolCall[];
+	/** When `role === 'tool'`: id of the tool call this message responds to. */
+	toolCallId?: string;
+}
+
+export interface ToolDef {
+	name: string;
+	description: string;
+	/** JSON Schema for the tool's input. */
+	parameters: object;
+}
+
+export interface ToolCall {
+	id: string;
+	name: string;
+	/** Parsed tool input. Backends that deliver stringified JSON (OpenAI) normalize before yielding. */
+	arguments: object;
+}
+
+export interface GenerateResult {
+	content: string;
+	toolCalls?: ToolCall[];
+	/** Why generation stopped. Backend-agnostic; backends map their native reasons. */
+	finishReason: 'stop' | 'length' | 'tool_calls' | 'content_filter';
+	/**
+	 * Token / cost usage for this call. Pass-through from the backend's
+	 * `ModelCallResult.usage` so callers (and the `toolMode: 'auto'` loop) can
+	 * cap cumulative budgets without re-querying analytics.
+	 *
+	 * Backends MUST NOT set this field on the `output` they return — the framework
+	 * (`Models.generate`) injects it from `ModelCallResult.usage`, which is the
+	 * authoritative source. A backend that sets both gets the framework's value;
+	 * easy to miss but unambiguous: usage lives at the call-result layer.
+	 */
+	usage?: TokenUsage;
+	/**
+	 * `toolMode: 'auto'` only, and only when `includeToolTrace: true` (or when an
+	 * error path attaches `partialTrace` via `BudgetExceededError`). One entry per
+	 * tool invocation, in the order it ran.
+	 */
+	trace?: ToolTraceEntry[];
+}
+
+/**
+ * Per-tool-invocation record emitted by the `toolMode: 'auto'` loop. Entries land
+ * on `GenerateResult.trace` (success path, when `includeToolTrace`) or on
+ * `BudgetExceededError.partialTrace` (any error path). Always in invocation order.
+ */
+export interface ToolTraceEntry {
+	/** 1-based iteration index — which backend round this tool call belongs to. */
+	iteration: number;
+	toolCallId: string;
+	toolName: string;
+	arguments: object;
+	/** JSON-stringified result, possibly truncated. Absent on handler error. */
+	result?: string;
+	/** True when `result` was clipped to `toolResultMaxBytes`. */
+	truncated?: boolean;
+	/** Pre-truncation byte length of the JSON-stringified result. */
+	totalBytes?: number;
+	/** Wall-clock duration of the handler call. */
+	durationMs: number;
+	/** Set when the handler threw. The loop's `toolErrorMode` decides recovery. */
+	error?: { name: string; message: string };
+}
+
+/**
+ * Context handed to a `ToolHandler`. v1: caller-supplied dispatch table. The
+ * `signal` is the composed iteration-level signal (caller signal ∪ budget-trip
+ * cancellation), so a long-running handler stops promptly when the loop trips a cap.
+ */
+export interface ToolHandlerContext {
+	signal?: AbortSignal;
+	accounting: AccountingContext;
+}
+
+/**
+ * Caller-supplied tool implementation. Return value is JSON-serialized into a
+ * `tool`-role message and fed back to the model on the next iteration. Throws are
+ * caught by the loop and routed by `toolErrorMode` (`'recover'` | `'abort'`).
+ *
+ * The `args` type parameter lets typed apps assign concrete handler signatures
+ * (`const search: ToolHandler<{query: string}> = ...`) without contravariance
+ * complaints under `strictFunctionTypes`. Defaults to `any` so the unparameterized
+ * `ToolHandler` stays assignable from arbitrary handlers in untyped callers.
+ */
+export type ToolHandler<T = any> = (args: T, ctx: ToolHandlerContext) => unknown | Promise<unknown>;
+
+/**
+ * Optional hook the loop calls as conversation turns flow. Structural so the
+ * built-in `ConversationResource` (#511) AND ad-hoc stores can satisfy it.
+ *
+ * **Contract:**
+ * - The loop appends ONLY new turns it produces (assistant + tool turns from each
+ *   round). It does NOT echo the caller's input back — the caller owns turn 0.
+ * - `append` is `await`ed inline between loop steps, giving the appender ordering
+ *   + back-pressure. Slow appenders pause the loop.
+ * - Appenders SHOULD NOT throw. A throw propagates as the loop's terminal error
+ *   (bypassing `BudgetExceededError` / `ToolHandlerError` shapes) and discards any
+ *   in-progress trace. If your appender CAN fail recoverably, catch internally and
+ *   log; only surface unrecoverable persistence failures.
+ */
+export interface ConversationAppender {
+	append(turn: ConversationTurn): Promise<void>;
+}
+
+export type ConversationTurn =
+	| { role: 'user'; content: string }
+	| { role: 'assistant'; content: string; toolCalls?: ToolCall[] }
+	| { role: 'tool'; toolCallId: string; content: string };
+
+export interface GenerateChunk {
+	/** Incremental text appended since the previous chunk. */
+	deltaContent?: string;
+	/**
+	 * Tool-call deltas accumulating across chunks. A streaming backend may deliver
+	 * the same tool-call id multiple times with partial fields as it builds up.
+	 */
+	deltaToolCalls?: Partial<ToolCall>[];
+	/** Set on the final chunk. */
+	finishReason?: GenerateResult['finishReason'];
+}

package/resources/openApi.ts

@@ -1,20 +1,9 @@
 import { packageJson } from '../utility/packageUtils.js';
 import { Resources } from './Resources.ts';
 import { Resource } from './Resource.ts';
+import { DATA_TYPES } from './jsonSchemaTypes.ts';
 
 const OPENAPI_VERSION = '3.0.3';
-// Maps graphql primitive types to open api types
-const DATA_TYPES = {
-	Int: 'integer',
-	Float: 'number',
-	Long: 'integer',
-	ID: 'string',
-	String: 'string',
-	Boolean: 'boolean',
-	Date: 'string',
-	Bytes: 'string',
-	BigInt: 'integer',
-};
 
 const SCHEMA_COMP_REF = '#/components/schemas/';
 const DESCRIPTION_200 = 'successful operation';
@@ -62,37 +51,70 @@ export function generateJsonApi(resources: Resources, serverHttpURL: string) {
 			api.components.schemas[def.type] = {};
 			const defProps: Record<string, unknown> = {};
 			const defRequired: string[] = [];
-			for (const prop of def.properties) {
+			// Iterate the Array form of the type's attributes. After the graphql parser
+			// alignment, top-level typeDefs from `resources.allTypes` carry both
+			// `.attributes` (Array, internal) and `.properties` (Record, canonical) —
+			// we want the Array here. For nested sub-attribute defs (passed via
+			// `prop` recursion below), `.properties` remains the Array form attached
+			// by `Object.defineProperty` in graphql.ts. Coalesce so both call sites work.
+			const subAttributes = def.attributes ?? def.properties;
+			if (!subAttributes) {
+				return;
+			}
+			for (const prop of subAttributes) {
+				// @hidden: suppress the property from the emitted OpenAPI document.
+				if (prop.hidden) continue;
+				let entry: any;
 				if (DATA_TYPES[prop.type]) {
-					defProps[prop.name] = new Type(DATA_TYPES[prop.type], prop.type);
+					entry = new Type(DATA_TYPES[prop.type], prop.type);
 				} else if (prop.properties) {
-					defProps[prop.name] = new Ref(prop.type);
+					entry = new Ref(prop.type);
 					includeDefinitionInSchema(prop);
-				} else if (prop.elements?.properties) {
-					defProps[prop.name] = new ArrayRef(prop.elements.type);
-					includeDefinitionInSchema(prop.elements);
+				} else if (prop.type === 'array' && prop.elements) {
+					// Sub-attribute array. Primitive element types (e.g. [String], [Int]) go to a
+					// Type-typed items entry; complex-typed elements recurse like the top-level path.
+					if (prop.elements.properties) {
+						entry = new ArrayRef(prop.elements.type);
+						includeDefinitionInSchema(prop.elements);
+					} else if (DATA_TYPES[prop.elements.type]) {
+						entry = { type: 'array', items: new Type(DATA_TYPES[prop.elements.type], prop.elements.type) };
+					} else {
+						// Unknown / `Any` element — emit a loose array shape rather than dropping.
+						entry = { type: 'array', items: { format: prop.elements.type } };
+					}
+				}
+				if (entry) {
+					if (prop.description) entry.description = prop.description;
+					defProps[prop.name] = entry;
 				}
 				if (prop.nullable === false) {
 					defRequired.push(prop.name);
 				}
 			}
 			// ... down here we actually define the value for the new type.
-			api.components.schemas[def.type] = new ResourceSchema(defProps, !def.sealed, defRequired);
+			api.components.schemas[def.type] = new ResourceSchema(defProps, !def.sealed, defRequired, def.description);
 		}
 	};
 
 	for (const [, resource] of resources) {
 		// skip invalid and error resources
 		if (!resource.path || resource.Resource.isError) continue;
+		// @hidden type-level: drop the Resource from the OpenAPI document entirely.
+		// Data remains queryable through Harper's other interfaces under RBAC.
+		if (resource.Resource.hidden === true) continue;
 
 		const { path } = resource;
 		const strippedPath = path.split('/').pop(); // strip any namespace from path
 		let { attributes, sealed } = resource.Resource;
 		const { prototype, primaryKey = 'id' } = resource.Resource;
+		// Class-level description from @table docstring or programmatic `static description`.
+		// Used as both the schema-level `description` (in components.schemas) and as a prefix
+		// on each path-level operation description.
+		const tableDoc: string | undefined = resource.Resource.description;
 		if (!attributes && resources.allTypes.has(resource.path)) {
 			const possibleType = resources.allTypes.get(resource.path);
 			sealed = possibleType.sealed;
-			attributes = possibleType.properties;
+			attributes = possibleType.attributes ?? possibleType.properties;
 		}
 		if (!primaryKey) continue;
 		const props = {};
@@ -100,7 +122,10 @@ export function generateJsonApi(resources: Resources, serverHttpURL: string) {
 		const resourceRequired: string[] = [];
 
 		if (attributes) {
-			for (const { type, name, elements, relationship, definition, nullable } of attributes) {
+			for (const attr of attributes) {
+				const { type, name, elements, relationship, definition, nullable, description, hidden } = attr;
+				// @hidden field-level: suppress the attribute from props, query params, and required.
+				if (hidden) continue;
 				const def = definition ?? elements?.definition;
 				if (def) {
 					includeDefinitionInSchema(def);
@@ -134,6 +159,10 @@ export function generateJsonApi(resources: Resources, serverHttpURL: string) {
 						props[name] = new Type(DATA_TYPES[type], type);
 					}
 				}
+				// Attach per-property description so it surfaces in Swagger UI / Redoc.
+				if (description && props[name] && typeof props[name] === 'object' && !('$ref' in props[name])) {
+					(props[name] as { description?: string }).description = description;
+				}
 				queryParamsArray.push(new Parameter(name, 'query', props[name]));
 			}
 		}
@@ -144,7 +173,7 @@ export function generateJsonApi(resources: Resources, serverHttpURL: string) {
 		primaryKeyParam.description = 'primary key of record';
 		const propertyParamPath = new Parameter('property', 'path', { enum: propsArray });
 		propertyParamPath.required = true;
-		api.components.schemas[strippedPath] = new ResourceSchema(props, !sealed, resourceRequired);
+		api.components.schemas[strippedPath] = new ResourceSchema(props, !sealed, resourceRequired, tableDoc);
 
 		const hasPost = prototype.post !== Resource.prototype.post || prototype.update;
 		const hasPut = typeof prototype.put === 'function';
@@ -152,6 +181,10 @@ export function generateJsonApi(resources: Resources, serverHttpURL: string) {
 		const hasDelete = typeof prototype.delete === 'function';
 		const hasPatch = typeof prototype.patch === 'function';
 
+		// Prepend the class-level docstring to each verb's path-level description when present.
+		// Otherwise the existing hardcoded sentence stands alone.
+		const withDoc = (sentence: string) => (tableDoc ? `${tableDoc} ${sentence}` : sentence);
+
 		const url = `/${path}/`;
 		if (!api.paths[url]) {
 			api.paths[url] = {};
@@ -176,7 +209,7 @@ export function generateJsonApi(resources: Resources, serverHttpURL: string) {
 						}
 					),
 				},
-				'create a new record auto-assigning a primary key'
+				withDoc('create a new record auto-assigning a primary key')
 			);
 		}
 
@@ -192,7 +225,7 @@ export function generateJsonApi(resources: Resources, serverHttpURL: string) {
 				queryParamsArray,
 				security,
 				{ '200': new Response200({ type: 'array', items: { $ref: SCHEMA_COMP_REF + strippedPath } }) },
-				'search for records by the specified property name and value pairs'
+				withDoc('search for records by the specified property name and value pairs')
 			);
 		}
 
@@ -200,7 +233,7 @@ export function generateJsonApi(resources: Resources, serverHttpURL: string) {
 			api.paths[url].delete = new Delete(
 				queryParamsArray,
 				security,
-				'delete all the records that match the provided query',
+				withDoc('delete all the records that match the provided query'),
 				{
 					'204': new Response204(),
 				}
@@ -225,7 +258,7 @@ export function generateJsonApi(resources: Resources, serverHttpURL: string) {
 				[primaryKeyParam],
 				security,
 				{ '200': new Response200({ $ref: SCHEMA_COMP_REF + strippedPath }) },
-				'retrieve a record by its primary key'
+				withDoc('retrieve a record by its primary key')
 			);
 		}
 
@@ -235,7 +268,7 @@ export function generateJsonApi(resources: Resources, serverHttpURL: string) {
 				security,
 				strippedPath,
 				{ '200': new Response200({ $ref: SCHEMA_COMP_REF + strippedPath }) },
-				"create or update the record with the URL path that maps to the record's primary key"
+				withDoc("create or update the record with the URL path that maps to the record's primary key")
 			);
 		}
 
@@ -245,7 +278,7 @@ export function generateJsonApi(resources: Resources, serverHttpURL: string) {
 				security,
 				strippedPath,
 				{ '200': new Response200({ $ref: SCHEMA_COMP_REF + strippedPath }) },
-				"patch the record with the URL path that maps to the record's primary key"
+				withDoc("patch the record with the URL path that maps to the record's primary key")
 			);
 		}
 
@@ -253,7 +286,7 @@ export function generateJsonApi(resources: Resources, serverHttpURL: string) {
 			api.paths[urlById].delete = new Delete(
 				[primaryKeyParam],
 				security,
-				'delete a record with the given primary key',
+				withDoc('delete a record with the given primary key'),
 				{
 					'204': new Response204(),
 				}
@@ -273,7 +306,7 @@ export function generateJsonApi(resources: Resources, serverHttpURL: string) {
 					'200': new Response200({ enum: propsArray }),
 				},
 
-				'used to retrieve the specified property of the specified record'
+				withDoc('used to retrieve the specified property of the specified record')
 			);
 		}
 	}
@@ -377,11 +410,12 @@ function Delete(parameters, security, description, responses) {
 	this.responses = responses;
 }
 
-function ResourceSchema(properties, additionalProperties?: boolean, required?: string[]) {
+function ResourceSchema(properties, additionalProperties?: boolean, required?: string[], description?: string) {
 	this.type = 'object';
 	this.properties = properties;
 	this.additionalProperties = additionalProperties;
 	this.required = required;
+	if (description) this.description = description;
 }
 
 function Type(type, format) {

package/resources/replayLogs.ts

@@ -29,11 +29,14 @@ export function replayLogs(rootStore: RocksDatabase, tables: any): Promise<void>
 		try {
 			purgedLogs = purgeAgedLogs(rootStore);
 		} catch (error) {
-			logger.warn(`Failed to purge aged transaction logs before replay in ${rootStore.databaseName} database`, error);
+			logger.warn(
+				`Failed to purge aged transaction logs before replay in ${(rootStore as any).databaseName} database`,
+				error
+			);
 		}
 		if (purgedLogs.length > 0) {
 			logger.info(
-				`Purged ${purgedLogs.length} aged transaction-log file(s) before replay in ${rootStore.databaseName} database`
+				`Purged ${purgedLogs.length} aged transaction-log file(s) before replay in ${(rootStore as any).databaseName} database`
 			);
 		}
 		const tableById = new Map<number, typeof Resource>();
@@ -46,8 +49,8 @@ export function replayLogs(rootStore: RocksDatabase, tables: any): Promise<void>
 		let lastTimestamp = 0;
 		let writes = 0;
 		let skipped = 0;
-		const txnLog: RocksTransactionLogStore = rootStore.auditStore;
-		for (const auditRecord of txnLog.getRange({ startFromLastFlushed: true, readUncommitted: true })) {
+		const txnLog: RocksTransactionLogStore = (rootStore as any).auditStore;
+		for (const auditRecord of txnLog.getRange({ startFromLastFlushed: true, readUncommitted: true }) as any) {
 			const {
 				type,
 				tableId,
@@ -67,11 +70,17 @@ export function replayLogs(rootStore: RocksDatabase, tables: any): Promise<void>
 				}
 				const Table = tableById.get(tableId);
 				if (!Table) continue;
-				const context: Context = { nodeId, alreadyLogged: true, version, expiresAt, user: { name: username } };
-				const { primaryStore } = Table;
+				const context: Context = {
+					nodeId,
+					alreadyLogged: true,
+					version,
+					expiresAt,
+					user: { username },
+				} as any;
+				const { primaryStore } = Table as any;
 				const target = new RequestTarget();
 				target.id = null;
-				const tableInstance = Table.getResource(target, context, {});
+				const tableInstance: any = Table.getResource(target, context, {});
 				// TODO: If this throws an error due to being unable to access structures, we need to iterate through
 				// other transaction logs to get the latest structure. Ultimately we may have to skip records
 				if (!warnedReplayHappening) {
@@ -177,9 +186,11 @@ export function replayLogs(rootStore: RocksDatabase, tables: any): Promise<void>
 		} catch (error) {
 			logger.error('Error committing replay transaction', error);
 		}
-		if (writes > 0) logger.warn(`Replayed ${writes} records in ${rootStore.databaseName} database`);
+		if (writes > 0) logger.warn(`Replayed ${writes} records in ${(rootStore as any).databaseName} database`);
 		if (skipped > 0)
-			logger.warn(`Skipped ${skipped} unrecoverable audit entries in ${rootStore.databaseName} database during replay`);
+			logger.warn(
+				`Skipped ${skipped} unrecoverable audit entries in ${(rootStore as any).databaseName} database during replay`
+			);
 		// we never actually release the lock because we only want to ever run one time
 		// rootStore.unlock('replayLogs');
 	});

package/resources/replayLogsGuards.ts

@@ -40,3 +40,48 @@ export function classifyAuditEntryForReplay(
 	if ((action & RECORD_BEARING_FLAGS) !== 0 && !hasRecord) return 'missing-record';
 	return null;
 }
+
+/**
+ * Wraps a transaction-log query iterator so a corrupt/torn frame ends that log's iteration
+ * cleanly instead of escaping as an uncaughtException. rocksdb-js throws a bounded RangeError
+ * when an entry's framing is broken; framing loss means the next entry can't be located, so the
+ * frame marks end-of-log (entries before it were already yielded) and startup replay /
+ * replication broadcast continue. `onCorruptFrame` fires once, latched — kept a callback (not a
+ * direct log) so this module stays out of the Harper module graph and is unit-testable.
+ */
+export function endIteratorOnCorruptFrame<T>(
+	iterator: Iterator<T>,
+	onCorruptFrame: (error: RangeError) => void
+): IterableIterator<T> {
+	let stopped = false;
+	return {
+		[Symbol.iterator]() {
+			return this;
+		},
+		next(): IteratorResult<T> {
+			if (stopped) return { done: true, value: undefined };
+			try {
+				return iterator.next();
+			} catch (error) {
+				// Key on the class, not the message: the framing RangeError's wording is
+				// version-dependent (1.4.2 added hex offsets). Anything else re-throws.
+				if (!(error instanceof RangeError)) throw error;
+				stopped = true;
+				onCorruptFrame(error);
+				return { done: true, value: undefined };
+			}
+		},
+		// Forward early termination (for-of break/return/throw) so the source's cleanup runs;
+		// mark stopped first. Current rocksdb-js implements neither — hence the protocol defaults.
+		return(value?: any): IteratorResult<T> {
+			stopped = true;
+			if (typeof iterator.return === 'function') return iterator.return(value);
+			return { done: true, value };
+		},
+		throw(error?: any): IteratorResult<T> {
+			stopped = true;
+			if (typeof iterator.throw === 'function') return iterator.throw(error);
+			throw error;
+		},
+	};
+}