@relayflows/sdk 2.0.9 → 2.0.11

package/src/failure-kinds.ts

@@ -1,7 +1,20 @@
+import { PLUGIN_FAILURE_KINDS } from './plugin-manifest.js';
+import { NAMED_GATE_FAILURE_KINDS } from './named-gates.js';
 const SHARED_SPEC_FAILURE_KINDS = ['invalid_spec'] as const;
 
 /** Environment refusal kinds produced after spec validation succeeds. */
 const PREFLIGHT_ENVIRONMENT_FAILURE_KINDS = [
+  ...NAMED_GATE_FAILURE_KINDS,
+  ...PLUGIN_FAILURE_KINDS,
+  'helper_provider.mount_required',
+  'helper_provider.unsupported',
+  'helper_slack.credential_missing',
+  'helper_slack.mount_required',
+  'helper_mount_required',
+  'mcp_undeclared_server',
+  'mcp_unreachable',
+  'budget_syntax_invalid',
+  'budget_missing_price',
   'cli_missing',
   'cli_unauthenticated',
   'cli_unresolved',
@@ -9,8 +22,12 @@ const PREFLIGHT_ENVIRONMENT_FAILURE_KINDS = [
   'command_missing',
   'model_unavailable',
   'model_unknown',
+  'memory_unreachable',
   'no_executor',
   'probe_failed',
+  'scope_syntax_invalid',
+  'mount_unknown',
+  'scope_ungrantable',
 ] as const;
 
 /** Closed refusal taxonomy for public preflight (RFC covenant 2). */
@@ -63,6 +80,14 @@ export const PREFLIGHT_WARNING_KINDS = [
  * step failed. All of them are still exit 2 — refused before a journal write.
  */
 export const RUN_FAILURE_KINDS = [
+  'bucket_unconfigured',
+  'bucket_unreachable',
+  'bundle_signature_invalid',
+  'bundle_unsupported',
+  'human_influenced_run',
+  'reuse_spec_mismatch',
+  'reuse_run_not_found',
+  'reuse_journal_read_failed',
   'daemon_unreachable',
   'daemon_protocol_mismatch',
   'daemon_start_failed',
@@ -83,12 +108,25 @@ export const RUN_WARNING_KINDS = [
   'connection_file_stale',
 ] as const;
 
+/** File-level editor hints emitted by flows check, outside pure preflight. */
+export const CHECK_WARNING_KINDS = ['editor_schema_missing'] as const;
+export type CheckWarningKind = (typeof CHECK_WARNING_KINDS)[number];
+
 export type PreflightFailureKind = (typeof PREFLIGHT_FAILURE_KINDS)[number];
 export type CheckFailureKind = (typeof CHECK_FAILURE_KINDS)[number];
 export type PreflightWarningKind = (typeof PREFLIGHT_WARNING_KINDS)[number];
 export type RunFailureKind = (typeof RUN_FAILURE_KINDS)[number];
 export type RunWarningKind = (typeof RUN_WARNING_KINDS)[number];
 
+/** Optional evidence on the existing step_failed diagnostic, not a new kind. */
+export interface StepFailedDetails {
+  stepId?: string;
+  exitCode?: number;
+  /** Terminal-safe UTF-8 excerpt, at most 1,024 bytes. */
+  stderrTail?: string;
+  hint?: string;
+}
+
 const CHECK_FAILURE_KIND_SET: ReadonlySet<string> = new Set(CHECK_FAILURE_KINDS);
 const RUN_FAILURE_KIND_SET: ReadonlySet<string> = new Set(RUN_FAILURE_KINDS);
 

package/src/gate-contract.ts

@@ -1,4 +1,5 @@
 import type { StepSpec } from './spec.js';
+import { isNamedGate } from './named-gates.js';
 
 export type JournalGateCheck =
   | 'completion'
@@ -54,6 +55,12 @@ export function acceptsAnyOutput(schema: unknown): boolean {
 /** Describe the exact named checks the existing kernel applies to a step. */
 export function inspectStepGate(step: StepSpec): StepGateInspection {
   const checks: JournalGateCheck[] = [];
+  if (isNamedGate(step.verification)) {
+    checks.push('exit_code');
+    if (step.verification.type === 'references_input') checks.push('output_contains');
+    if (step.verification.type === 'word_count_bounds') checks.push('json_schema');
+    return { stepId: step.id, kind: 'data', checks, evaluator: 'kernel', preflightable: true, replayable: true };
+  }
   if (step.type === 'deterministic') checks.push('exit_code');
   if (step.verification?.type === 'output_contains') checks.push('output_contains');
   if (step.verification?.type === 'json_schema') checks.push('json_schema');

package/src/helper-preflight.ts

@@ -0,0 +1,34 @@
+import { helperProviders } from '@relayflows/surface/runtime';
+import type { PreflightResult, PreflightDiagnostic } from './preflight.js';
+
+/** Static discovery never executes the body; dynamic aliases are checked at call time. */
+export function preflightHelpers(
+  definition: { header?: { tools?: Readonly<Record<string, unknown>> }; body?: Function },
+  facts: { slackToken?: string; slackMount?: boolean; slackMock?: boolean;
+    providers?: Readonly<Record<string, { mount: boolean; mock: boolean; token?: string }>> },
+): PreflightResult {
+  const body = typeof definition.body === 'function' ? Function.prototype.toString.call(definition.body) : '';
+  const parameter = body.match(/^(?:async\s+)?(?:function(?:\s+[\w$]+)?\s*)?(?:\(\s*([\w$]+)|([\w$]+)\s*=>)/);
+  const root = (parameter?.[1] ?? parameter?.[2])?.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const diagnostics: PreflightDiagnostic[] = [];
+  for (const { provider, namespace, supported } of helperProviders) {
+    const used = definition.header?.tools?.[namespace] === true
+      || (root !== undefined && new RegExp(`(?:^|[^\\w$.])${root}\\s*(?:\\.\\s*${namespace}\\b|\\[\\s*['"]${namespace}['"]\\s*\\])`).test(body));
+    if (!used) continue;
+    const fact = facts.providers?.[provider] ?? (provider === 'slack'
+      ? { mount: facts.slackMount, mock: facts.slackMock, token: facts.slackToken }
+      : { mount: false, mock: false, token: undefined });
+    if (!supported) {
+      diagnostics.push({ severity: 'refusal', kind: 'helper_provider.unsupported',
+        message: `f.${namespace} has no upstream relayfile writeback client.` });
+    } else if (!fact.mock && !fact.mount) {
+      diagnostics.push({ severity: 'refusal',
+        kind: provider === 'slack' ? (fact.token?.trim() ? 'helper_slack.mount_required' : 'helper_slack.credential_missing') : 'helper_provider.mount_required',
+        message: `f.${namespace} requires a relayfile ${provider} mount; direct-token transport is not implemented.` });
+    } else if (provider === 'notion' && !fact.mock && /\.\s*appendBlock\b/.test(body)) {
+      diagnostics.push({ severity: 'refusal', kind: 'helper_provider.unsupported',
+        message: 'f.notion.appendBlock is mock-only: the Notion adapter has no append-block writeback route.' });
+    }
+  }
+  return { ok: diagnostics.length === 0, gates: [], resolutions: [], diagnostics };
+}

package/src/helper-storage.ts

@@ -0,0 +1,23 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { mkdir, open, readFile, rename } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+
+/** Durable receipt precedes effect.confirm, so a confirmed replay can recover it. */
+export async function atomicJson(path: string, value: unknown): Promise<void> {
+  await mkdir(dirname(path), { recursive: true });
+  const temporary = `${path}.${randomUUID()}.tmp`;
+  const file = await open(temporary, 'wx', 0o600);
+  try { await file.writeFile(JSON.stringify(value)); await file.sync(); }
+  finally { await file.close(); }
+  await rename(temporary, path);
+  const directory = await open(dirname(path), 'r');
+  try { await directory.sync(); } finally { await directory.close(); }
+}
+
+export function receiptPath(dataDir: string, runId: string, stepId: string): string {
+  return join(dataDir, 'helper-receipts', createHash('sha256').update(`${runId}:${stepId}`).digest('hex') + '.json');
+}
+
+export async function readHelperReceipt(path: string): Promise<unknown> {
+  return JSON.parse(await readFile(path, 'utf8')) as unknown;
+}

package/src/helper-writeback.ts

@@ -0,0 +1,83 @@
+import { createHash } from 'node:crypto';
+import { join } from 'node:path';
+import { writeJsonFile, readJsonFile, listJsonFiles, type WritebackResult } from '@relayfile/adapter-core/vfs-client';
+import type { RelayTransport, RelayTransportRequest } from '@relayfile/relay-helpers/transport';
+import { helperClients, helperProviders, invokeHelper, type HelperCall } from '@relayflows/surface/runtime';
+import { providerMount } from './slack-preflight.js';
+import { atomicJson } from './helper-storage.js';
+import type { SlackCall } from './slack-writeback.js';
+
+export class HelperDeliveryError extends Error {}
+
+export async function helperWriteback(call: HelperCall, dataDir: string, runId: string, stepId: string, signal: AbortSignal): Promise<unknown> {
+  const factory = helperClients[call.provider];
+  if (!factory) throw new Error(`No writeback client for ${call.provider}`);
+  const { transport } = helperTransport(call, dataDir, runId, stepId, signal);
+  try { return await invokeHelper(factory, call, transport); }
+  catch (cause) { throw new HelperDeliveryError(cause instanceof Error ? cause.message : String(cause), { cause }); }
+}
+
+/** One transport for every provider, including Slack. Only confirmed writes succeed. */
+export function helperTransport(call: HelperCall | SlackCall, dataDir: string, runId: string, stepId: string, signal: AbortSignal) {
+  const provider = helperProviders.find(p => p.provider === call.provider);
+  if (!provider) throw new Error(`Unknown helper provider ${call.provider}`);
+  const mock = process.env[provider.mockEnv] === '1';
+  const mount = providerMount(provider.provider);
+  const options = () => {
+    signal.throwIfAborted();
+    if (!mount) throw new Error(`${provider.provider} requires a relayfile mount`);
+    return { relayfileMountRoot: mount };
+  };
+  const idempotencyKey = `${runId}:${stepId}`;
+  let deliveredRef = '';
+  const transport: RelayTransport = {
+    async read<T>(request: RelayTransportRequest): Promise<T> {
+      signal.throwIfAborted();
+      if (mock) return {} as T;
+      return readJsonFile<T>(options(), call.provider, `read.${request.resource}`, request.path);
+    },
+    async list<T>(request: RelayTransportRequest): Promise<T[]> {
+      signal.throwIfAborted();
+      if (mock) return [];
+      return (await listJsonFiles<T>(options(), call.provider, `list.${request.resource}`, request.path)).map(file => file.value);
+    },
+    async write(request) {
+      signal.throwIfAborted();
+      if (request.provider !== call.provider) throw new Error('Helper transport provider mismatch');
+      if (!mock && call.provider === 'notion' && call.verb === 'appendBlock') {
+        throw new Error('Notion appendBlock has no upstream mount writeback route');
+      }
+      if (typeof request.body !== 'object' || request.body === null || Array.isArray(request.body)) {
+        throw new Error('Helper writeback requires a JSON object');
+      }
+      const body: Record<string, unknown> = { ...request.body as Record<string, unknown>, idempotencyKey };
+      // Item paths must remain canonical; only collections receive a draft filename.
+      const draft = /\.[a-z]+$/i.test(request.path) ? request.path
+        : `${request.path}/draft-${createHash('sha256').update(idempotencyKey).digest('hex')}.json`;
+      let result: WritebackResult;
+      if (mock) {
+        deliveredRef = `mock-ref-${stepId}`;
+        result = { path: deliveredRef, absolutePath: draft, deliveryStatus: 'confirmed', receipt: { externalId: `mock-${stepId}` } };
+        await atomicJson(join(dataDir, 'mock-writeback', call.provider, `${stepId}.json`), {
+          ...call, ...body,
+          ...(call.provider === 'slack' ? { channel: request.parameters.channelId,
+            ...(body.parentRef === undefined ? {} : { replyTo: body.parentRef }) } : {}),
+          runId, stepId, request: { ...request, body }, receipt: result.receipt,
+        });
+      } else {
+        try { result = await writeJsonFile(options(), call.provider, `write.${request.resource}`, draft, body); }
+        catch (cause) {
+          // Upstream created() converts pending/terminal adapter errors into values.
+          // A journal effect must fail instead of confirming an undelivered write.
+          throw new Error(`${call.provider} writeback failed: ${cause instanceof Error ? cause.message : String(cause)}`, { cause });
+        }
+        if (result.deliveryStatus !== 'confirmed' || !result.receipt) throw new Error(`${call.provider} writeback is pending; no delivery receipt`);
+        if (call.provider === 'slack' && call.verb !== 'react' && !result.receipt.externalId && !result.receipt.ts) throw new Error('Slack writeback has no delivered timestamp');
+        deliveredRef = result.path;
+      }
+      signal.throwIfAborted();
+      return result;
+    },
+  };
+  return { transport, deliveredRef: () => deliveredRef };
+}

package/src/index.ts

@@ -12,6 +12,11 @@ export type {
   DeterministicStepSpec,
   ExitCodeGate,
   FlowSpec,
+  YamlFlowSpec,
+  YamlHelperStepSpec,
+  YamlHelperParams,
+  FlowsJson,
+  McpServerConfig,
   JsonSchemaGate,
   JsonOutputSchema,
   KernelAgentStep,
@@ -28,7 +33,13 @@ export type {
   KernelVerificationSpec,
   LlmStepSpec,
   NamedAgentSpec,
+  NamedDataGate,
+  ReferencesInputGate,
+  SubprocessGate,
+  WordCountBoundsGate,
+  RegexMatchGate,
   OutputContainsGate,
+  OutputBinding,
   OutputVerificationSpec,
   PermissionsSpec,
   RecoveryMode,
@@ -42,8 +53,17 @@ export type {
   VerificationSpec,
   WorkspaceSurface,
 } from './spec.js';
+export { MODEL_PRICING } from './model-pricing.js';
+export type { HeaderBudget } from './budget.js';
+export type { StepSpend } from './protocol.js';
 export { SPEC_SCHEMA_VERSION } from './spec.js';
 
+export { CloudFlowError, type CloudConnectionOptions } from './cloud-http.js';
+export {
+  runInCloud, getCloudFlowRun, waitForCloudFlowRun,
+  type CloudFlowSource, type RunInCloudOptions, type CloudRunReceipt, type CloudRunState,
+} from './cloud-run.js';
+
 export { canonicalize, specHash } from './canonical.js';
 export {
   compileAndHash,
@@ -63,6 +83,7 @@ export {
 } from './authored-flow.js';
 export {
   preflight,
+  preflightHelpers,
   type CliResolution,
   type CliResolutionSource,
   type CliProbeResult,
@@ -199,3 +220,8 @@ export {
   type TickPayload,
   type TickSchedule,
 } from './tick-source.js';
+
+export { createFlow, type CreateFlowOptions, type CreatedFlow } from './create-flow.js';
+
+export { renderProgress, type ProgressEvent } from './progress.js';
+export { webhookTriggerSpec } from './trigger-executor.js';

package/src/input-binding.ts

@@ -0,0 +1,76 @@
+import type { OutputBinding } from './spec.js';
+
+/** Input is a closed selector map, never a template or expression language. */
+export function inputBindingErrors(steps: readonly unknown[]): string[] {
+  const errors: string[] = [];
+  const sources = new Map(steps.flatMap((step, index) =>
+    isObject(step) && typeof step.id === 'string' ? [[step.id, { step, index }] as const] : []));
+  for (const [index, step] of steps.entries()) {
+    if (!isObject(step) || step.input === undefined) continue;
+    const at = `spec.steps[${index}].input`;
+    if (!isObject(step.input)) {
+      errors.push(`${at}: expected a map of output selectors`);
+      continue;
+    }
+    for (const [name, binding] of Object.entries(step.input)) {
+      const where = `${at}.${name}`;
+      if (!name.trim() || !isBinding(binding)) {
+        errors.push(`${where}: expected { step: <id>, path?: [object keys or array indices] }`);
+        continue;
+      }
+      const source = sources.get(binding.step);
+      if (source === undefined) {
+        errors.push(`${where}: unknown source step "${binding.step}"`);
+        continue;
+      }
+      if (source.index >= index) {
+        errors.push(`${where}: source "${binding.step}" must precede this step; forward and self references are not supported`);
+      }
+      const gate = source.step.verification;
+      const schema = source.step.output ?? (isObject(gate) && gate.type === 'json_schema' ? gate.schema : undefined);
+      if (schema === undefined) {
+        errors.push(`${where}: source "${binding.step}" must declare an output schema (output or json_schema verification)`);
+      } else if (!declaresPath(schema, binding.path ?? [])) {
+        errors.push(`${where}: path ${JSON.stringify(binding.path)} is not present in source "${binding.step}"'s declared output schema`);
+      }
+    }
+  }
+  return errors;
+}
+
+export function bindingDependencies(input: unknown): string[] {
+  return isObject(input) ? Object.values(input).filter(isBinding).map(binding => binding.step) : [];
+}
+
+function isBinding(value: unknown): value is OutputBinding {
+  return isObject(value)
+    && Object.keys(value).every(key => key === 'step' || key === 'path')
+    && typeof value.step === 'string' && value.step.trim().length > 0
+    && (value.path === undefined || (Array.isArray(value.path) && value.path.every(segment =>
+      typeof segment === 'string' || (typeof segment === 'number' && Number.isSafeInteger(segment) && segment >= 0))));
+}
+
+/** Only explicit properties/items paths are portable; no schema inference. */
+function declaresPath(schema: unknown, path: readonly (string | number)[]): boolean {
+  let current = schema;
+  for (const segment of path) {
+    if (!isObject(current)) return false;
+    if (typeof segment === 'string') {
+      if (!isObject(current.properties) || !Object.hasOwn(current.properties, segment)) return false;
+      current = current.properties[segment];
+    } else if (Array.isArray(current.prefixItems) && segment < current.prefixItems.length) {
+      current = current.prefixItems[segment];
+    } else if (Array.isArray(current.items)) {
+      if (segment >= current.items.length) return false;
+      current = current.items[segment];
+    } else {
+      if (current.items === undefined) return false;
+      current = current.items;
+    }
+  }
+  return current !== undefined && current !== false;
+}
+
+function isObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}

package/src/journal-client.ts

@@ -10,6 +10,7 @@
 // loopback double in tests.
 
 import { EventEmitter } from 'node:events';
+export { walkJournal, JournalReadError, type JournalEvent, type JournalReadFailure } from './journal-reader.js';
 import { randomUUID } from 'node:crypto';
 import { createConnection, type Socket } from 'node:net';
 import type { VerbContract, EventSubmitParams } from './protocol.js';
@@ -65,7 +66,7 @@ export class JournalClient extends EventEmitter {
   private readonly connectTimeoutMs: number;
 
   constructor(
-    private readonly socketPath: string,
+    readonly socketPath: string,
     options: JournalClientOptions = {},
   ) {
     super();
@@ -73,6 +74,13 @@ export class JournalClient extends EventEmitter {
     this.connectTimeoutMs = options.connectTimeoutMs ?? 2_000;
   }
 
+  /** Independent session for an SDK helper worker; preserves the caller's registration. */
+  createPeer(): JournalClient {
+    return new JournalClient(this.socketPath, {
+      requestTimeoutMs: this.requestTimeoutMs, connectTimeoutMs: this.connectTimeoutMs,
+    });
+  }
+
   /** Open the unix socket connection. Rejects on connect failure (fail-closed). */
   connect(): Promise<void> {
     return new Promise((resolve, reject) => {
@@ -196,13 +204,13 @@ export class JournalClient extends EventEmitter {
    * the run file, and append `run.spawned`. Authoring specs must be compiled
    * with `toKernelSpec` before crossing this journal-protocol boundary.
    */
-  runStart(spec: KernelRunSpec): Promise<VerbContract['run.start']['result']> {
-    return this.request('run.start', { spec }, null);
+  runStart(spec: KernelRunSpec, reuseFromRunId?: string): Promise<VerbContract['run.start']['result']> {
+    return this.request('run.start', { spec, ...(reuseFromRunId === undefined ? {} : { reuse_from_run_id: reuseFromRunId }) }, null);
   }
 
   /** §3 memoized resume. */
-  runResume(runId: string): Promise<VerbContract['run.resume']['result']> {
-    return this.request('run.resume', { run_id: runId }, null);
+  runResume(runId: string, allowHumanInfluenced = false): Promise<VerbContract['run.resume']['result']> {
+    return this.request('run.resume', { run_id: runId, ...(allowHumanInfluenced ? { allow_human_influenced: true } : {}) }, null);
   }
 
   /** Durably request cancellation and return the terminal run fact. */
@@ -341,7 +349,11 @@ export class JournalClient extends EventEmitter {
     });
   }
 
-  /** Complete a dispatched step — also the out-of-band path. */
+  /**
+   * Complete a dispatched step — also the out-of-band path. Like runStart
+   * and runResume, this drives downstream steps before replying, so their
+   * execution bounds apply rather than the bounded protocol-request timeout.
+   */
   stepComplete(
     runId: string,
     stepId: string,
@@ -355,6 +367,7 @@ export class JournalClient extends EventEmitter {
       end_pins?: Pins;
       effects?: EffectRef[];
       trajectory_tail?: unknown;
+      human_intervention?: boolean;
     } = {},
   ): Promise<VerbContract['step.complete']['result']> {
     return this.request('step.complete', {
@@ -364,7 +377,7 @@ export class JournalClient extends EventEmitter {
       idempotency_key: idempotencyKey,
       completionReason,
       ...extra,
-    });
+    }, null);
   }
 
   /** Satisfy `wait.event`; a human response arrives here too. */

package/src/journal-offset.ts

@@ -0,0 +1,60 @@
+import { readFileSync } from 'node:fs';
+
+/** Locate a table row's cell in a SQLite snapshot for read-error diagnostics. */
+export function journalRecordOffset(path: string, rootPage: number, seq: number): string {
+  const main = readFileSync(path);
+  const encodedSize = main.readUInt16BE(16);
+  const pageSize = encodedSize === 1 ? 65536 : encodedSize;
+  const pages = new Map<number, { bytes: Buffer; offset: number; file: string }>();
+  let wal: Buffer | undefined;
+  try { wal = readFileSync(`${path}-wal`); } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error;
+  }
+  if (wal !== undefined) {
+    const frameSize = pageSize + 24;
+    let lastCommit = 0;
+    for (let frame = 32; frame + frameSize <= wal.length; frame += frameSize) {
+      // RESTART checkpoints reuse the WAL without truncating its old tail.
+      // Frames from that prior generation are not part of SQLite's view.
+      if (!wal.subarray(frame + 8, frame + 16).equals(wal.subarray(16, 24))) break;
+      if (wal.readUInt32BE(frame + 4) !== 0) lastCommit = frame;
+    }
+    for (let frame = 32; frame <= lastCommit; frame += frameSize) {
+      pages.set(wal.readUInt32BE(frame), { bytes: wal, offset: frame + 24, file: 'WAL' });
+    }
+  }
+  const visited = new Set<number>();
+  let page = rootPage;
+  while (!visited.has(page)) {
+    visited.add(page);
+    const source = pages.get(page) ?? { bytes: main, offset: (page - 1) * pageSize, file: 'journal' };
+    const header = source.offset + (page === 1 ? 100 : 0);
+    const kind = source.bytes[header];
+    if (kind !== 5 && kind !== 13) break;
+    const count = source.bytes.readUInt16BE(header + 3);
+    let next = kind === 5 ? source.bytes.readUInt32BE(header + 8) : 0;
+    for (let index = 0; index < count; index += 1) {
+      const cell = source.offset + source.bytes.readUInt16BE(header + (kind === 5 ? 12 : 8) + 2 * index);
+      const rowIdOffset = kind === 5 ? cell + 4 : varint(source.bytes, cell).next;
+      const rowId = varint(source.bytes, rowIdOffset).value;
+      if (kind === 13 && rowId === BigInt(seq)) return `${source.file} byte offset ${cell}`;
+      if (kind === 5 && BigInt(seq) <= rowId) {
+        next = source.bytes.readUInt32BE(cell);
+        break;
+      }
+    }
+    if (next === 0) break;
+    page = next;
+  }
+  throw new Error('Cannot locate journal record cell.');
+}
+
+function varint(bytes: Buffer, offset: number): { value: bigint; next: number } {
+  let value = 0n;
+  for (let index = 0; index < 9; index += 1) {
+    const byte = bytes.readUInt8(offset++);
+    value = (value << (index === 8 ? 8n : 7n)) | BigInt(index === 8 ? byte : byte & 0x7f);
+    if (byte < 0x80 || index === 8) return { value, next: offset };
+  }
+  throw new Error('Invalid SQLite varint.');
+}