@econ-v1/app-sdk 7.0.77 → 7.0.79

package/dist/burger-build/plugin.d.ts

@@ -0,0 +1,25 @@
+import type { BunPlugin } from "bun";
+import { type BurgerModule } from "./aliases.ts";
+export interface ImportViolation {
+    specifier: string;
+    /** Absolute path of the importing file. */
+    importer: string;
+    reason: string;
+}
+export interface GateState {
+    violations: ImportViolation[];
+}
+export declare const BRIDGE_NAMESPACE = "burger-require";
+/**
+ * CommonJS `require("fs")` cannot be left external: the output would call
+ * a `__require` shim that does not exist in QuickJS. Instead it resolves to
+ * this ESM module, which the bundler links into the CommonJS wrapper.
+ */
+export declare function bridgeSource(target: BurgerModule): string;
+/**
+ * Resolves every `burger:*` and C6-aliased specifier to an external
+ * `burger:*` import, and records (and externalises, so the build can finish
+ * and report every problem at once) every other `node:*`, `bun:*`, Node
+ * built-in and native addon import.
+ */
+export declare function burgerResolvePlugin(state: GateState): BunPlugin;

package/dist/burger-build/test-prepare.d.ts

@@ -0,0 +1,68 @@
+import { type Problem } from "./gate.ts";
+export interface TestPrepareOptions {
+    /** App source directory (colocated `*.test.ts` files are tests too). */
+    src: string;
+    /** Separate test directory, when the app has one. */
+    tests?: string;
+    /** Output directory; deleted and recreated. */
+    out: string;
+}
+export interface TestPlanEntry {
+    /** Absolute path of the test file as written. */
+    source: string;
+    /** Absolute path of the prepared ES module that `node-app-burger test` runs. */
+    output: string;
+}
+/** `<out>/test-plan.json`, read by `node-app test`. */
+export interface TestPlan {
+    importMap: string;
+    tests: TestPlanEntry[];
+}
+/** `<out>/importmap.json` (Contract C8). */
+export interface ImportMap {
+    imports: Record<string, string>;
+}
+export type TestPrepareOutcome = {
+    ok: true;
+    plan: TestPlan;
+    importMap: ImportMap;
+} | {
+    ok: false;
+    report: string;
+};
+export declare function commonAncestor(dirs: readonly string[]): string;
+/** `tests/db.test.ts` → `tests/db.test.js`. */
+export declare function preparedPath(relativePath: string): string;
+/** `@econ-v1/app-sdk` → `econ-v1__app-sdk.js`. */
+export declare function dependencyFileName(specifier: string): string;
+interface Workspace {
+    root: string;
+    sources: ReadonlySet<string>;
+    jsonFiles: Set<string>;
+    dependencies: Set<string>;
+    problems: Problem[];
+}
+/**
+ * What a prepared module imports instead of `specifier` (written in
+ * `importer`). Returns undefined — with a recorded problem — when the import
+ * cannot work under Burger.
+ */
+export declare function rewriteSpecifier(ws: Workspace, importer: string, specifier: string): string | undefined;
+/**
+ * Problems for a module that statically imports a module it also replaces
+ * with `mock.module`. Bun patches the already-linked bindings, so the test
+ * passes there; Burger links static imports before any code runs, so the
+ * test would silently exercise the real module.
+ */
+export declare function staticallyImportedMocks(file: string, code: string, imports: readonly {
+    kind: string;
+    path: string;
+}[]): string[];
+/**
+ * Turn an app's sources and tests into files `node-app-burger test` can run:
+ * one transpiled ES module per source file (module boundaries preserved so
+ * `mock.module` can replace them), one pre-bundled file per bare
+ * dependency specifier, and `importmap.json` (Contract C8).
+ */
+export declare function prepareTests(options: TestPrepareOptions): Promise<TestPrepareOutcome>;
+export {};

package/dist/burger-types/aliases.d.ts

@@ -0,0 +1,20 @@
+// Specifiers the burger-build bundler rewrites to burger:* (Contracts C5, C6).
+// Typing them here keeps existing `node:`/`bun:` imports compiling with the
+// exact Phase 1 subset — anything outside it is a type error.
+
+declare module "node:fs" { export * from "burger:fs"; export { default } from "burger:fs"; }
+declare module "fs" { export * from "burger:fs"; export { default } from "burger:fs"; }
+declare module "node:fs/promises" { export * from "burger:fs/promises"; export { default } from "burger:fs/promises"; }
+declare module "fs/promises" { export * from "burger:fs/promises"; export { default } from "burger:fs/promises"; }
+declare module "node:path" { export * from "burger:path"; export { default } from "burger:path"; }
+declare module "path" { export * from "burger:path"; export { default } from "burger:path"; }
+declare module "node:os" { export * from "burger:os"; export { default } from "burger:os"; }
+declare module "os" { export * from "burger:os"; export { default } from "burger:os"; }
+declare module "node:worker_threads" { export * from "burger:worker_threads"; export { default } from "burger:worker_threads"; }
+declare module "worker_threads" { export * from "burger:worker_threads"; export { default } from "burger:worker_threads"; }
+declare module "node:crypto" { export * from "burger:crypto"; export { default } from "burger:crypto"; }
+declare module "crypto" { export * from "burger:crypto"; export { default } from "burger:crypto"; }
+declare module "node:buffer" { export * from "burger:buffer"; export { default } from "burger:buffer"; }
+declare module "buffer" { export * from "burger:buffer"; export { default } from "burger:buffer"; }
+declare module "bun:sqlite" { export * from "burger:sqlite"; export { default } from "burger:sqlite"; }
+declare module "bun:test" { export * from "burger:test"; }

package/dist/burger-types/globals.d.ts

@@ -0,0 +1,66 @@
+// Globals present in every Burger runtime in Phase 1 (Contract C5).
+// Pair with `"lib": ["ES2023"]` and no DOM lib: fetch, URL, streams, etc. are
+// deliberately absent until Phase 2.
+
+interface BurgerConsole {
+  log(...data: unknown[]): void;
+  info(...data: unknown[]): void;
+  warn(...data: unknown[]): void;
+  error(...data: unknown[]): void;
+  debug(...data: unknown[]): void;
+}
+declare var console: BurgerConsole;
+
+declare function setTimeout(handler: (...args: any[]) => void, timeoutMs?: number, ...args: any[]): number;
+declare function clearTimeout(id: number | undefined): void;
+declare function setInterval(handler: (...args: any[]) => void, timeoutMs?: number, ...args: any[]): number;
+declare function clearInterval(id: number | undefined): void;
+declare function queueMicrotask(callback: () => void): void;
+
+declare class TextEncoder {
+  constructor();
+  readonly encoding: "utf-8";
+  encode(input?: string): Uint8Array;
+}
+
+declare class TextDecoder {
+  constructor(label?: "utf-8" | "utf8", options?: { fatal?: boolean; ignoreBOM?: boolean });
+  readonly encoding: "utf-8";
+  decode(input?: Uint8Array | ArrayBuffer): string;
+}
+
+declare var performance: { now(): number };
+
+interface BurgerCrypto {
+  randomUUID(): string;
+  getRandomValues<T extends Int8Array | Uint8Array | Uint8ClampedArray | Int16Array | Uint16Array | Int32Array | Uint32Array | BigInt64Array | BigUint64Array>(array: T): T;
+}
+declare var crypto: BurgerCrypto;
+
+declare var Buffer: import("burger:buffer").BufferConstructor;
+type Buffer = import("burger:buffer").Buffer;
+
+declare function structuredClone<T>(value: T): T;
+
+interface BurgerProcessMemoryUsage {
+  heapUsed: number;
+  heapTotal: number;
+  external: number;
+  rss: number;
+}
+
+interface BurgerProcess {
+  /** Per-app and mutable: writes and deletes never reach the OS environment. */
+  env: Record<string, string | undefined>;
+  readonly argv: string[];
+  readonly platform: "linux" | "darwin";
+  readonly arch: "arm64" | "x64";
+  exit(code: number): never;
+  on(event: "uncaughtException", listener: (error: unknown) => void): void;
+  on(event: "unhandledRejection", listener: (reason: unknown) => void): void;
+  on(event: string, listener: (...args: unknown[]) => void): void;
+  off(event: string, listener: (...args: any[]) => void): void;
+  nextTick(callback: (...args: any[]) => void, ...args: any[]): void;
+  memoryUsage(): BurgerProcessMemoryUsage;
+}
+declare var process: BurgerProcess;

package/dist/burger-types/index.d.ts

@@ -0,0 +1,3 @@
+/// <reference path="./modules.d.ts" />
+/// <reference path="./aliases.d.ts" />
+/// <reference path="./globals.d.ts" />

package/dist/burger-types/modules.d.ts

@@ -0,0 +1,436 @@
+// burger:* module declarations — Contract C4 (burger:host) and C6 (Phase 1 modules).
+// Anything not declared here is not provided by Burger Phase 1.
+// Modules provided under a Node or Bun name also have a `default` export: an
+// object containing all their named exports (C6).
+
+declare module "burger:host" {
+  /** Per-app identity and paths, fixed at runtime creation. */
+  export const appId: string;
+  export const dataDir: string;
+  export const logDir: string;
+  export const entryPoint: string;
+  export const config: unknown;
+
+  export interface HostChannel {
+    /** Serialise `frame` with serde_json, append "\n", write. Throws TypeError if not JSON-serialisable. */
+    send(frame: object): void;
+    /** Register the frame handler. Replaces any previous handler. */
+    onFrame(handler: (frame: any) => void): void;
+    /** Called once when the connection closes; `error` is set when it closed abnormally. */
+    onClose(handler: (error?: Error) => void): void;
+    close(): void;
+  }
+
+  /** Open the app channel. Calling it twice returns the same channel. */
+  export function connect(): HostChannel;
+
+  /** QuickJS runtime memory for THIS app, in KiB. */
+  export function memoryUsage(): {
+    heap_used_kb: number;
+    heap_total_kb: number;
+    external_kb: number;
+    heap_capacity_kb: number;
+  };
+
+  /** Stop this app. Never returns. */
+  export function exit(code: number): never;
+}
+
+declare module "burger:fs" {
+  export type PathLike = string;
+  export type Utf8Encoding = "utf8" | "utf-8";
+
+  export interface Stats {
+    isFile(): boolean;
+    isDirectory(): boolean;
+    readonly size: number;
+    readonly mtimeMs: number;
+  }
+
+  export function existsSync(path: PathLike): boolean;
+  export function readFileSync(path: PathLike): Uint8Array;
+  export function readFileSync(path: PathLike, encoding: Utf8Encoding | { encoding: Utf8Encoding }): string;
+  export function writeFileSync(path: PathLike, data: string | Uint8Array): void;
+  export function appendFileSync(path: PathLike, data: string | Uint8Array): void;
+  export function mkdirSync(path: PathLike, options?: { recursive?: boolean }): void;
+  export function readdirSync(path: PathLike): string[];
+  export function statSync(path: PathLike): Stats;
+  export function rmSync(path: PathLike, options?: { recursive?: boolean; force?: boolean }): void;
+  export function renameSync(oldPath: PathLike, newPath: PathLike): void;
+  export function chmodSync(path: PathLike, mode: number): void;
+  export function unlinkSync(path: PathLike): void;
+  /** Create a unique directory whose name starts with `prefix`; returns its path. */
+  export function mkdtempSync(prefix: string): string;
+
+  export interface FsPromises {
+    exists(path: PathLike): Promise<boolean>;
+    readFile(path: PathLike): Promise<Uint8Array>;
+    readFile(path: PathLike, encoding: Utf8Encoding | { encoding: Utf8Encoding }): Promise<string>;
+    writeFile(path: PathLike, data: string | Uint8Array): Promise<void>;
+    appendFile(path: PathLike, data: string | Uint8Array): Promise<void>;
+    mkdir(path: PathLike, options?: { recursive?: boolean }): Promise<void>;
+    readdir(path: PathLike): Promise<string[]>;
+    stat(path: PathLike): Promise<Stats>;
+    rm(path: PathLike, options?: { recursive?: boolean; force?: boolean }): Promise<void>;
+    rename(oldPath: PathLike, newPath: PathLike): Promise<void>;
+    chmod(path: PathLike, mode: number): Promise<void>;
+    unlink(path: PathLike): Promise<void>;
+    mkdtemp(prefix: string): Promise<string>;
+  }
+
+  export const promises: FsPromises;
+
+  const fs: {
+    existsSync: typeof existsSync;
+    readFileSync: typeof readFileSync;
+    writeFileSync: typeof writeFileSync;
+    appendFileSync: typeof appendFileSync;
+    mkdirSync: typeof mkdirSync;
+    readdirSync: typeof readdirSync;
+    statSync: typeof statSync;
+    rmSync: typeof rmSync;
+    renameSync: typeof renameSync;
+    chmodSync: typeof chmodSync;
+    unlinkSync: typeof unlinkSync;
+    mkdtempSync: typeof mkdtempSync;
+    promises: FsPromises;
+  };
+  export default fs;
+}
+
+declare module "burger:fs/promises" {
+  import type { FsPromises } from "burger:fs";
+  export const exists: FsPromises["exists"];
+  export const readFile: FsPromises["readFile"];
+  export const writeFile: FsPromises["writeFile"];
+  export const appendFile: FsPromises["appendFile"];
+  export const mkdir: FsPromises["mkdir"];
+  export const readdir: FsPromises["readdir"];
+  export const stat: FsPromises["stat"];
+  export const rm: FsPromises["rm"];
+  export const rename: FsPromises["rename"];
+  export const chmod: FsPromises["chmod"];
+  export const unlink: FsPromises["unlink"];
+  export const mkdtemp: FsPromises["mkdtemp"];
+  const fsPromises: FsPromises;
+  export default fsPromises;
+}
+
+declare module "burger:path" {
+  export interface ParsedPath {
+    root: string;
+    dir: string;
+    base: string;
+    ext: string;
+    name: string;
+  }
+  export interface PathModule {
+    join(...paths: string[]): string;
+    resolve(...paths: string[]): string;
+    dirname(path: string): string;
+    basename(path: string, suffix?: string): string;
+    extname(path: string): string;
+    relative(from: string, to: string): string;
+    normalize(path: string): string;
+    isAbsolute(path: string): boolean;
+    readonly sep: "/";
+    readonly delimiter: ":";
+    parse(path: string): ParsedPath;
+    format(pathObject: Partial<ParsedPath>): string;
+  }
+  export const join: PathModule["join"];
+  export const resolve: PathModule["resolve"];
+  export const dirname: PathModule["dirname"];
+  export const basename: PathModule["basename"];
+  export const extname: PathModule["extname"];
+  export const relative: PathModule["relative"];
+  export const normalize: PathModule["normalize"];
+  export const isAbsolute: PathModule["isAbsolute"];
+  export const sep: PathModule["sep"];
+  export const delimiter: PathModule["delimiter"];
+  export const parse: PathModule["parse"];
+  export const format: PathModule["format"];
+  const path: PathModule;
+  export default path;
+}
+
+declare module "burger:os" {
+  export interface CpuInfo {
+    model: string;
+    speed: number;
+  }
+  export interface OsModule {
+    platform(): "linux" | "darwin";
+    arch(): "arm64" | "x64";
+    cpus(): CpuInfo[];
+    totalmem(): number;
+    freemem(): number;
+    hostname(): string;
+    tmpdir(): string;
+    homedir(): string;
+    readonly EOL: string;
+  }
+  export const platform: OsModule["platform"];
+  export const arch: OsModule["arch"];
+  export const cpus: OsModule["cpus"];
+  export const totalmem: OsModule["totalmem"];
+  export const freemem: OsModule["freemem"];
+  export const hostname: OsModule["hostname"];
+  export const tmpdir: OsModule["tmpdir"];
+  export const homedir: OsModule["homedir"];
+  export const EOL: OsModule["EOL"];
+  const os: OsModule;
+  export default os;
+}
+
+declare module "burger:worker_threads" {
+  export const isMainThread: true;
+  export const workerData: undefined;
+  export const parentPort: null;
+  export const threadId: 0;
+  const workerThreads: {
+    isMainThread: true;
+    workerData: undefined;
+    parentPort: null;
+    threadId: 0;
+  };
+  export default workerThreads;
+}
+
+declare module "burger:crypto" {
+  export type HashAlgorithm = "sha256" | "sha512" | "sha1";
+  export type DigestEncoding = "hex" | "base64";
+  export interface Hash {
+    update(data: string | Uint8Array): Hash;
+    digest(): Uint8Array;
+    digest(encoding: DigestEncoding): string;
+  }
+  export type Hmac = Hash;
+  export function randomUUID(): string;
+  export function randomBytes(size: number): Uint8Array;
+  export function createHash(algorithm: HashAlgorithm): Hash;
+  export function createHmac(algorithm: HashAlgorithm, key: string | Uint8Array): Hmac;
+  export function timingSafeEqual(a: Uint8Array, b: Uint8Array): boolean;
+  const crypto: {
+    randomUUID: typeof randomUUID;
+    randomBytes: typeof randomBytes;
+    createHash: typeof createHash;
+    createHmac: typeof createHmac;
+    timingSafeEqual: typeof timingSafeEqual;
+  };
+  export default crypto;
+}
+
+declare module "burger:buffer" {
+  export type BufferEncoding = "utf8" | "utf-8" | "hex" | "base64" | "base64url";
+
+  /** C5 subset of Node's Buffer. Instances are `Uint8Array`s. */
+  export interface Buffer extends Uint8Array<ArrayBuffer> {
+    toString(encoding?: BufferEncoding): string;
+    equals(other: Uint8Array): boolean;
+    subarray(start?: number, end?: number): Buffer;
+    slice(start?: number, end?: number): Buffer;
+  }
+
+  export interface BufferConstructor {
+    readonly prototype: Buffer;
+    from(value: string, encoding?: BufferEncoding): Buffer;
+    from(value: Uint8Array | ArrayBuffer | readonly number[]): Buffer;
+    alloc(size: number): Buffer;
+    concat(list: readonly Uint8Array[]): Buffer;
+    isBuffer(value: unknown): value is Buffer;
+    byteLength(value: string): number;
+  }
+
+  export const Buffer: BufferConstructor;
+  const buffer: { Buffer: BufferConstructor };
+  export default buffer;
+}
+
+declare module "burger:sqlite" {
+  export type SQLValue = null | number | bigint | string | Uint8Array;
+  export type SQLBinding = SQLValue | boolean | undefined;
+  export type SQLParams =
+    | SQLBinding[]
+    | [SQLBinding[]]
+    | [Record<string, SQLBinding>];
+
+  export interface Changes {
+    changes: number;
+    lastInsertRowid: number | bigint;
+  }
+
+  export interface Statement<Row = unknown> {
+    all(...params: SQLParams): Row[];
+    get(...params: SQLParams): Row | null;
+    run(...params: SQLParams): Changes;
+    values(...params: SQLParams): SQLValue[][];
+  }
+
+  export interface DatabaseOptions {
+    create?: boolean;
+    readonly?: boolean;
+  }
+
+  export class Database {
+    constructor(filename?: string, options?: DatabaseOptions);
+    query<Row = unknown>(sql: string): Statement<Row>;
+    prepare<Row = unknown>(sql: string): Statement<Row>;
+    exec(sql: string, ...params: SQLParams): Changes;
+    run(sql: string, ...params: SQLParams): Changes;
+    transaction<Args extends unknown[], Result>(fn: (...args: Args) => Result): (...args: Args) => Result;
+    close(): void;
+  }
+
+  /** Default export is the Database class itself, which also carries `.Database` (C6). */
+  const sqlite: typeof Database & { Database: typeof Database };
+  export default sqlite;
+}
+
+declare module "burger:test" {
+  export type TestBody = () => void | Promise<unknown>;
+  /** A per-test timeout in milliseconds, or `{ timeout }` (as bun:test accepts). */
+  export type TestOptions = number | { timeout?: number };
+
+  /**
+   * `test.each(table)(title, fn)`: one test per row. A row that is an array is
+   * spread into `fn`'s arguments; `title` takes `%s %d %i %f %j %o %p %#`.
+   */
+  export interface EachFunction {
+    <Row extends readonly unknown[]>(table: readonly Row[]): (
+      title: string,
+      fn: (...args: Row) => void | Promise<unknown>,
+      options?: TestOptions,
+    ) => void;
+    <Row>(table: readonly Row[]): (title: string, fn: (arg: Row) => void | Promise<unknown>, options?: TestOptions) => void;
+  }
+
+  export interface DescribeEachFunction {
+    <Row extends readonly unknown[]>(table: readonly Row[]): (title: string, fn: (...args: Row) => void) => void;
+    <Row>(table: readonly Row[]): (title: string, fn: (arg: Row) => void) => void;
+  }
+
+  export interface TestFunction {
+    (name: string, fn: TestBody, options?: TestOptions): void;
+    skip(name: string, fn?: TestBody, options?: TestOptions): void;
+    only(name: string, fn: TestBody, options?: TestOptions): void;
+    todo(name: string, fn?: TestBody): void;
+    each: EachFunction;
+  }
+
+  export interface DescribeFunction {
+    (name: string, fn: () => void): void;
+    skip(name: string, fn: () => void): void;
+    only(name: string, fn: () => void): void;
+    todo(name: string, fn?: () => void): void;
+    each: DescribeEachFunction;
+  }
+
+  export const describe: DescribeFunction;
+  export const test: TestFunction;
+  export const it: TestFunction;
+
+  export function beforeEach(fn: TestBody): void;
+  export function afterEach(fn: TestBody): void;
+  export function beforeAll(fn: TestBody): void;
+  export function afterAll(fn: TestBody): void;
+  export function setDefaultTimeout(ms: number): void;
+
+  export interface Matchers<R> {
+    toBe(expected: unknown): R;
+    toContain(expected: unknown): R;
+    toEqual(expected: unknown): R;
+    toStrictEqual(expected: unknown): R;
+    toHaveLength(length: number): R;
+    toBeDefined(): R;
+    toBeUndefined(): R;
+    toBeNull(): R;
+    toBeTruthy(): R;
+    toBeFalsy(): R;
+    toHaveProperty(keyPath: string | string[], value?: unknown): R;
+    toMatchObject(expected: object): R;
+    toMatch(expected: string | RegExp): R;
+    toBeGreaterThan(expected: number | bigint): R;
+    toBeGreaterThanOrEqual(expected: number | bigint): R;
+    toBeLessThan(expected: number | bigint): R;
+    toBeLessThanOrEqual(expected: number | bigint): R;
+    /** `|expected - actual| < 10^-digits / 2`; `digits` defaults to 2. */
+    toBeCloseTo(expected: number, digits?: number): R;
+    toStartWith(prefix: string): R;
+    toThrow(expected?: string | RegExp | Error | AsymmetricMatcher | (new (...args: any[]) => Error)): R;
+    toBeInstanceOf(expected: abstract new (...args: any[]) => unknown): R;
+    toContainEqual(expected: unknown): R;
+    /** The subject is a `mock()` function. */
+    toHaveBeenCalled(): R;
+    toHaveBeenCalledTimes(count: number): R;
+    toHaveBeenCalledWith(...args: unknown[]): R;
+  }
+
+  export interface Expect extends Matchers<void> {
+    readonly not: Matchers<void>;
+    readonly resolves: Matchers<Promise<void>> & { readonly not: Matchers<Promise<void>> };
+    readonly rejects: Matchers<Promise<void>> & { readonly not: Matchers<Promise<void>> };
+  }
+
+  /** Placeholder accepted wherever an expected value is (`toEqual`, `toContainEqual`, `toHaveBeenCalledWith`, …). */
+  export interface AsymmetricMatcher {
+    asymmetricMatch(other: unknown): boolean;
+  }
+
+  export interface ExpectFunction {
+    (actual: unknown): Expect;
+    /** Matches any value created by `constructor` (or of that primitive type for `Number`, `String`, …). */
+    any(constructor: abstract new (...args: any[]) => unknown): AsymmetricMatcher;
+    /** Matches anything but `null` and `undefined`. */
+    anything(): AsymmetricMatcher;
+    /** Matches any object that has at least `sample`'s properties with equal values. */
+    objectContaining(sample: object): AsymmetricMatcher;
+    /** Matches any array that contains an element equal to each of `items`. */
+    arrayContaining(items: readonly unknown[]): AsymmetricMatcher;
+    stringContaining(text: string): AsymmetricMatcher;
+    stringMatching(pattern: string | RegExp): AsymmetricMatcher;
+  }
+
+  export const expect: ExpectFunction;
+
+  export type AnyFunction = (...args: any[]) => any;
+
+  export type MockResult<T> = { readonly type: "return"; readonly value: T } | { readonly type: "throw"; readonly value: unknown };
+
+  export interface MockState<F extends AnyFunction> {
+    readonly calls: Parameters<F>[];
+    readonly results: MockResult<ReturnType<F>>[];
+    /** `this` of each call. */
+    readonly instances: unknown[];
+  }
+
+  export interface Mock<F extends AnyFunction> {
+    (...args: Parameters<F>): ReturnType<F>;
+    readonly mock: MockState<F>;
+    mockImplementation(fn: F): Mock<F>;
+    mockImplementationOnce(fn: F): Mock<F>;
+    mockReturnValue(value: ReturnType<F>): Mock<F>;
+    mockReturnValueOnce(value: ReturnType<F>): Mock<F>;
+    mockResolvedValue(value: Awaited<ReturnType<F>>): Mock<F>;
+    mockResolvedValueOnce(value: Awaited<ReturnType<F>>): Mock<F>;
+    mockRejectedValue(error: unknown): Mock<F>;
+    mockRejectedValueOnce(error: unknown): Mock<F>;
+    /** Forget recorded calls, results and instances; keep the implementation. */
+    mockClear(): Mock<F>;
+    /** `mockClear()`, and drop every implementation (calls then return `undefined`). */
+    mockReset(): Mock<F>;
+  }
+
+  export interface MockFactory {
+    <F extends AnyFunction = AnyFunction>(fn?: F): Mock<F>;
+    /**
+     * Replace the module `specifier` (resolved as an import from the calling
+     * file) with `factory()`'s result. Factories are synchronous (C8). Call it
+     * before the module is loaded, then load it with `await import()`: static
+     * imports are linked before any test code runs.
+     */
+    module(specifier: string, factory: () => Record<string, unknown>): void;
+  }
+
+  export const mock: MockFactory;
+}

package/dist/index.d.ts

@@ -30,7 +30,11 @@
  * ```
  */
 import { Database } from "bun:sqlite";
-export { initAppTelemetry, telemetryActive, incrementCounter } from "./otel.js";
+import type { AppMemorySample, NodeAppCtx } from "./platform/types.js";
+export type { AppMemorySample } from "./platform/types.js";
+export declare const initAppTelemetry: (appName: string) => Promise<void>;
+export declare const telemetryActive: () => boolean;
+export declare const incrementCounter: (name: string, value?: number, attributes?: Record<string, string | number | boolean>) => void;
 /**
  * Open an app-owned SQLite database with a bounded page cache.
  *
@@ -40,17 +44,12 @@ export { initAppTelemetry, telemetryActive, incrementCounter } from "./otel.js";
 export declare function openDatabase(path: string, options?: {
     cacheSizeKb?: number;
 }): Database;
-interface NodeAppCtx {
-    socket: string | undefined;
-    logDir: string | undefined;
-    dataDir: string | undefined;
-}
 /** @internal exported for unit tests; not part of the public SDK surface. */
-export declare function _resolveCtx(): NodeAppCtx;
+export declare const _resolveCtx: () => NodeAppCtx;
 /** @internal test-only export */
-export declare function _testRunNodeAppPath(): string | undefined;
+export declare const _testRunNodeAppPath: () => string | undefined;
 /** @internal test-only export; also the production exit pathway. */
-export declare function _testExitWorker(code: number, mainThread: boolean, exit?: (code: number) => never): void;
+export declare const _testExitWorker: (code: number, mainThread: boolean, exit?: (code: number) => never) => void;
 export interface AppMetadata {
     name: string;
     version: string;
@@ -192,15 +191,9 @@ export declare function _testLeaseState(): {
     timerArmed: boolean;
     draining: boolean;
 };
-export interface AppMemorySample {
-    heap_used_kb: number;
-    heap_total_kb: number;
-    external_kb?: number;
-    heap_capacity_kb?: number;
-}
-/** @internal Exact isolate sample used by the IPC timer and unit tests. */
-export declare function _sampleMemory(): AppMemorySample;
-export declare function _captureHeapSnapshotTo(path: string, generate?: () => ArrayBuffer, write?: (path: string, bytes: ArrayBuffer) => Promise<number>): Promise<{
+/** @internal Exact runtime heap sample used by the IPC timer and unit tests. */
+export declare const _sampleMemory: () => AppMemorySample;
+export declare const _captureHeapSnapshotTo: (path: string, generate?: () => ArrayBuffer, write?: (path: string, bytes: ArrayBuffer) => Promise<number>) => Promise<{
     size_bytes: number;
 }>;
 export declare function _handleHeapSnapshotRequest(request: HeapSnapshotRequest, send: (message: HeapSnapshotResponse) => void, capture?: (path: string) => Promise<{