@lunora/testing 0.0.0 → 1.0.0-alpha.2

package/dist/index.d.mts

@@ -0,0 +1,265 @@
+import { ScheduledJob, RegisteredAction, RegisteredMutation, RegisteredQuery, ArgsValidator, InferArgs, ActionCtx, MutationCtx, QueryCtx, TableDefinition, Schema } from '@lunora/server';
+export { type InboxOptions, type WaitForMailOptions, extractLink, listCapturedMail, waitForMail } from '@lunora/mail/testing';
+/** A pending job entry in the fake scheduler queue. */
+interface FakeScheduledJob extends ScheduledJob {
+  /** The args the job was scheduled with. */
+  args: Record<string, unknown>;
+}
+/**
+* A single scheduled-job failure captured during an `advance()` / `runPending()`
+* sweep. Production's scheduler isolates per-job failures (one bad job does not
+* abort the rest), so the fake scheduler does the same — but, being a test
+* harness, it never swallows the error: every failure is recorded here so tests
+* can still assert on it.
+*/
+interface ScheduledJobFailure {
+  /** The args the job was dispatched with. */
+  args: Record<string, unknown>;
+  /** The error the job's handler threw (or that dispatch produced). */
+  error: unknown;
+  /** The function path the job targeted (e.g. `"messages:send"`). */
+  functionPath: string;
+  /** The id of the job that failed. */
+  id: string;
+}
+/**
+* Controls exposed on the test harness for the fake in-memory scheduler.
+* Access via `harness.scheduler`.
+*/
+interface FakeSchedulerControls {
+  /**
+  * Advance the virtual clock by `ms` milliseconds, executing all jobs whose
+  * `scheduledFor` timestamp is now at or before the new virtual "now". Jobs
+  * are dispatched in `scheduledFor` order (oldest first). Newly queued jobs
+  * (scheduled by an executed job during the advance) are NOT re-evaluated in
+  * the same advance call — callers should advance again if needed.
+  *
+  * Per-job failures are isolated (matching production): a job that throws does
+  * NOT prevent the remaining due jobs from running. After every due job has
+  * run, the failures are surfaced — they are recorded on
+  * {@link FakeSchedulerControls.failures} and, by default, re-thrown so a test
+  * still sees the error. A single failure is re-thrown verbatim; multiple
+  * failures are aggregated into an `AggregateError`. Pass
+  * `{ throwOnError: false }` to suppress the re-throw and inspect
+  * {@link FakeSchedulerControls.failures} (and the returned count) instead.
+  *
+  * Returns the number of jobs that were executed (including failed ones).
+  */
+  advance: (ms: number, options?: SweepOptions) => Promise<number>;
+  /**
+  * All scheduled-job failures captured so far, in execution order, across
+  * every `advance()` / `runPending()` call on this harness. Always available,
+  * even when `throwOnError: false` suppressed the re-throw. The list is a
+  * snapshot — mutating it does not affect the scheduler.
+  */
+  failures: () => ScheduledJobFailure[];
+  /**
+  * List all pending jobs (those not yet executed or cancelled) in the order
+  * they were enqueued.
+  */
+  list: () => FakeScheduledJob[];
+  /**
+  * Execute all currently pending jobs regardless of their `scheduledFor`
+  * time. Equivalent to advancing to `Infinity`. Returns the number of jobs
+  * executed (including failed ones).
+  *
+  * Failure isolation and surfacing match {@link FakeSchedulerControls.advance}:
+  * one failing job does not abort the rest, and failures are recorded on
+  * {@link FakeSchedulerControls.failures} and re-thrown unless
+  * `{ throwOnError: false }` is passed.
+  */
+  runPending: (options?: SweepOptions) => Promise<number>;
+}
+/** Options controlling how an `advance()` / `runPending()` sweep surfaces failures. */
+interface SweepOptions {
+  /**
+  * When `true` (the default), failures encountered during the sweep are
+  * re-thrown after every due job has run — a single failure verbatim, multiple
+  * as an `AggregateError`. When `false`, the sweep resolves normally and
+  * failures are observable only via {@link FakeSchedulerControls.failures}.
+  */
+  throwOnError?: boolean;
+}
+/**
+* Top-level dispatch for a scheduled job — wired by the harness. Unlike the
+* `runInternal` closure used by `ctx.run*` composition (which rides whatever
+* transaction span is already open), a scheduled job is a fresh top-level entry:
+* production dispatches it back to the Worker as its own RPC, so a scheduled
+* `mutation` runs inside its own BEGIN/COMMIT span and notifies subscription
+* listeners on success. The harness supplies a callback that reproduces those
+* semantics (mutations wrapped + notified; actions run unwrapped).
+*/
+/**
+* The schema value produced by `@lunora/server`'s `defineSchema`. Accepted
+* structurally; internally it is handed to `@lunora/do`'s `runShardMigrations` /
+* `createShardCtxDb`, whose `SchemaLike` is the same shape declared in the DO
+* package — the two are structurally compatible at runtime (only their
+* independently-declared trigger nesting drifts at the type level), so the
+* boundary cast below is sound.
+*/
+type TestSchema = Schema<Record<string, TableDefinition>>;
+/**
+* A user-supplied identity, surfaced to handlers via `ctx.auth`. `userId` is the
+* subject the handler reads from `ctx.auth.userId`; any additional fields are
+* returned verbatim from `ctx.auth.getIdentity()` (mirroring a decoded JWT).
+*/
+interface TestIdentity extends Record<string, unknown> {
+  userId?: null | string;
+}
+/**
+* An async iterable/iterator returned by {@link TestHarness.subscribe}.
+* Guarantees `return()` is always defined (unlike the optional `AsyncIterator.return`),
+* so callers can always unsubscribe without a `?.` guard.
+*/
+interface TestSubscription<R> extends AsyncIterable<R> {
+  next: () => Promise<IteratorResult<R, R>>;
+  return: () => Promise<IteratorResult<R, R>>;
+}
+/** An inline handler accepted by `query` / `mutation` / `run`, given direct context access. */
+type InlineQueryFunction<R> = (context: QueryCtx) => Promise<R> | R;
+type InlineMutationFunction<R> = (context: MutationCtx) => Promise<R> | R;
+type InlineActionFunction<R> = (context: ActionCtx) => Promise<R> | R;
+/**
+* A map from function path strings (e.g. `"messages:send"`) to their
+* registered function objects. Used by the fake scheduler to resolve
+* `ctx.scheduler.runAfter(delay, "messages:send", args)` → handler invocation.
+*
+* Only mutations and actions can be scheduled in production; queries passed
+* here will be accepted but produce a console.warn at dispatch time.
+*
+* The value type uses `any` because `RegisteredFunction` is contravariant in its
+* args type parameter — a `RegisteredMutation` with concrete args is not assignable
+* to `RegisteredMutation` with `ArgsValidator` at the type level even though at
+* runtime it is sound (the fake scheduler passes `Record&lt;string, unknown>` to
+* `handler` and ignores the return value).
+*/
+type FunctionRegistry = Record<string, RegisteredAction<any, any> | RegisteredMutation<any, any> | RegisteredQuery<any, any>>;
+/**
+* Options accepted by {@link lunoraTest}.
+*
+* All options are optional — `lunoraTest(schema)` preserves v1 behaviour with
+* clearly-throwing stubs for unsupported surfaces.
+*/
+interface LunoraTestOptions {
+  /**
+  * Injectable `fetch` implementation for action contexts. When provided,
+  * `ctx.fetch` in every `action` (and `withIdentity` views) resolves to this
+  * function rather than throwing the "not available in v1" stub.
+  *
+  * Pass `vi.fn()` or any `typeof globalThis.fetch` compatible implementation.
+  * @example
+  * ```ts
+  * const fakeFetch = vi.fn().mockResolvedValue(Response.json({ ok: true }));
+  * const t = lunoraTest(schema, { fetch: fakeFetch });
+  * ```
+  */
+  fetch?: typeof globalThis.fetch;
+  /**
+  * Function registry for the fake in-memory scheduler. Maps a
+  * `functionPath` string (the value passed as the second argument to
+  * `ctx.scheduler.runAfter` / `ctx.scheduler.runAt`) to the corresponding
+  * registered function object.
+  *
+  * Only required if your handlers schedule work. Scheduled jobs for paths
+  * NOT listed here produce a `console.warn` at dispatch time (matching prod
+  * behaviour for unknown paths).
+  * @example
+  * ```ts
+  * const t = lunoraTest(schema, {
+  *   functions: { "messages:send": sendMutation },
+  * });
+  * ```
+  */
+  functions?: FunctionRegistry;
+}
+/**
+* The in-memory test harness returned by {@link lunoraTest}. Mirrors the first
+* five methods of Convex's `convexTest`: `query` / `mutation` / `action` / `run`
+* / `withIdentity`. All five share one in-memory `node:sqlite` backend, so a
+* write from one method is visible to a read from another (including across a
+* `withIdentity` scope).
+*/
+interface TestHarness {
+  /** Run a registered `action` (or an inline `async (context) => …`) against the harness. */
+  action: {
+    <A extends ArgsValidator, R>(reference: RegisteredAction<A, R>, args: InferArgs<A>): Promise<R>;
+    <R>(inline: InlineActionFunction<R>): Promise<R>;
+  };
+  /** Close the underlying in-memory SQLite database, releasing the native handle. Idempotent; safe to call on any `withIdentity` view. */
+  close: () => void;
+  /** Run a registered `mutation` (or an inline `async (context) => …`) against the harness. */
+  mutation: {
+    <A extends ArgsValidator, R>(reference: RegisteredMutation<A, R>, args: InferArgs<A>): Promise<R>;
+    <R>(inline: InlineMutationFunction<R>): Promise<R>;
+  };
+  /** Run a registered `query` (or an inline `async (context) => …`) against the harness. */
+  query: {
+    <A extends ArgsValidator, R>(reference: RegisteredQuery<A, R>, args: InferArgs<A>): Promise<R>;
+    <R>(inline: InlineQueryFunction<R>): Promise<R>;
+  };
+  /** Direct db access at mutation-level (read + write), mirroring `convexTest`'s `run`. */
+  run: <R>(function_: InlineMutationFunction<R>) => Promise<R>;
+  /**
+  * Controls for the fake in-memory scheduler. Always present; scheduler
+  * jobs only execute when you call `advance(ms)` or `runPending()`.
+  *
+  * - `list()` — snapshot of all pending jobs (enqueue order).
+  * - `advance(ms)` — tick the virtual clock forward by `ms` ms, executing every job
+  * whose `scheduledFor` is now at or below virtual now.
+  * - `runPending()` — execute all currently pending jobs regardless of their scheduled time.
+  *
+  * Scheduled jobs run through the same `runInternal` dispatch as
+  * `ctx.runMutation`, so they share the harness SQLite database.
+  */
+  scheduler: FakeSchedulerControls;
+  /**
+  * Subscribe to a registered query (or inline query function) and receive
+  * an async iterable of snapshots. The first value is emitted immediately
+  * (the current query result). Subsequent values are emitted after each
+  * `mutation` / `run` call on this harness completes.
+  *
+  * Subscriptions are table-agnostic — any mutation triggers a re-evaluation.
+  * This matches the harness's single-writer model and keeps the implementation
+  * free of DO machinery.
+  * @example
+  * ```ts
+  * const sub = t.subscribe(list, {});
+  * const first = await sub.next(); // current result
+  * await t.mutation(send, { author: "ada", body: "hi" });
+  * const second = await sub.next(); // updated result
+  * await sub.return(); // unsubscribe
+  * ```
+  *
+  * The iterable is lazy — it never buffers more than one pending result.
+  * If you do not consume fast enough and multiple mutations fire, the next
+  * `next()` call will reflect the most-recent state (intermediate snapshots
+  * are coalesced).
+  */
+  subscribe: {
+    <A extends ArgsValidator, R>(reference: RegisteredQuery<A, R>, args: InferArgs<A>): TestSubscription<R>;
+    <R>(inline: InlineQueryFunction<R>): TestSubscription<R>;
+  };
+  /** Return a harness view that shares this harness's db but reports the given identity on `ctx.auth`. */
+  withIdentity: (identity: TestIdentity) => TestHarness;
+}
+/**
+* Spin up an in-memory Lunora function harness for `schema`.
+*
+* `lunoraTest(schema)` runs the migrations against a fresh `node:sqlite`
+* database, builds the same `ctx.db` writer the real Durable Object builds (via
+* `@lunora/do`'s `createShardCtxDb`), and returns a harness whose `query` /
+* `mutation` / `action` / `run` execute a registered function's `handler`
+* directly — no Durable Object, no `wrangler`, no network.
+*
+* **v1 surfaces now supported:**
+*
+* - `ctx.fetch` (actions): inject a custom `fetch` via `options.fetch`.
+* - `ctx.scheduler` (mutations + actions): fully functional fake with virtual clock;
+* control via `harness.scheduler.advance(ms)` / `runPending()` / `list()`.
+* - `harness.subscribe(query, args)`: async iterable that re-emits after mutations.
+*
+* **v1 stubs (still throwing):** `ctx.storage`, `ctx.vectors`, `ctx.workflows`.
+* These are clearly documented follow-ups.
+*/
+declare const lunoraTest: (schema: TestSchema, options?: LunoraTestOptions) => TestHarness;
+export { type FakeScheduledJob, type FakeSchedulerControls, type FunctionRegistry, type LunoraTestOptions, type ScheduledJobFailure, type SweepOptions, type TestHarness, type TestIdentity, type TestSubscription, lunoraTest };

package/dist/index.d.ts

@@ -0,0 +1,265 @@
+import { ScheduledJob, RegisteredAction, RegisteredMutation, RegisteredQuery, ArgsValidator, InferArgs, ActionCtx, MutationCtx, QueryCtx, TableDefinition, Schema } from '@lunora/server';
+export { type InboxOptions, type WaitForMailOptions, extractLink, listCapturedMail, waitForMail } from '@lunora/mail/testing';
+/** A pending job entry in the fake scheduler queue. */
+interface FakeScheduledJob extends ScheduledJob {
+  /** The args the job was scheduled with. */
+  args: Record<string, unknown>;
+}
+/**
+* A single scheduled-job failure captured during an `advance()` / `runPending()`
+* sweep. Production's scheduler isolates per-job failures (one bad job does not
+* abort the rest), so the fake scheduler does the same — but, being a test
+* harness, it never swallows the error: every failure is recorded here so tests
+* can still assert on it.
+*/
+interface ScheduledJobFailure {
+  /** The args the job was dispatched with. */
+  args: Record<string, unknown>;
+  /** The error the job's handler threw (or that dispatch produced). */
+  error: unknown;
+  /** The function path the job targeted (e.g. `"messages:send"`). */
+  functionPath: string;
+  /** The id of the job that failed. */
+  id: string;
+}
+/**
+* Controls exposed on the test harness for the fake in-memory scheduler.
+* Access via `harness.scheduler`.
+*/
+interface FakeSchedulerControls {
+  /**
+  * Advance the virtual clock by `ms` milliseconds, executing all jobs whose
+  * `scheduledFor` timestamp is now at or before the new virtual "now". Jobs
+  * are dispatched in `scheduledFor` order (oldest first). Newly queued jobs
+  * (scheduled by an executed job during the advance) are NOT re-evaluated in
+  * the same advance call — callers should advance again if needed.
+  *
+  * Per-job failures are isolated (matching production): a job that throws does
+  * NOT prevent the remaining due jobs from running. After every due job has
+  * run, the failures are surfaced — they are recorded on
+  * {@link FakeSchedulerControls.failures} and, by default, re-thrown so a test
+  * still sees the error. A single failure is re-thrown verbatim; multiple
+  * failures are aggregated into an `AggregateError`. Pass
+  * `{ throwOnError: false }` to suppress the re-throw and inspect
+  * {@link FakeSchedulerControls.failures} (and the returned count) instead.
+  *
+  * Returns the number of jobs that were executed (including failed ones).
+  */
+  advance: (ms: number, options?: SweepOptions) => Promise<number>;
+  /**
+  * All scheduled-job failures captured so far, in execution order, across
+  * every `advance()` / `runPending()` call on this harness. Always available,
+  * even when `throwOnError: false` suppressed the re-throw. The list is a
+  * snapshot — mutating it does not affect the scheduler.
+  */
+  failures: () => ScheduledJobFailure[];
+  /**
+  * List all pending jobs (those not yet executed or cancelled) in the order
+  * they were enqueued.
+  */
+  list: () => FakeScheduledJob[];
+  /**
+  * Execute all currently pending jobs regardless of their `scheduledFor`
+  * time. Equivalent to advancing to `Infinity`. Returns the number of jobs
+  * executed (including failed ones).
+  *
+  * Failure isolation and surfacing match {@link FakeSchedulerControls.advance}:
+  * one failing job does not abort the rest, and failures are recorded on
+  * {@link FakeSchedulerControls.failures} and re-thrown unless
+  * `{ throwOnError: false }` is passed.
+  */
+  runPending: (options?: SweepOptions) => Promise<number>;
+}
+/** Options controlling how an `advance()` / `runPending()` sweep surfaces failures. */
+interface SweepOptions {
+  /**
+  * When `true` (the default), failures encountered during the sweep are
+  * re-thrown after every due job has run — a single failure verbatim, multiple
+  * as an `AggregateError`. When `false`, the sweep resolves normally and
+  * failures are observable only via {@link FakeSchedulerControls.failures}.
+  */
+  throwOnError?: boolean;
+}
+/**
+* Top-level dispatch for a scheduled job — wired by the harness. Unlike the
+* `runInternal` closure used by `ctx.run*` composition (which rides whatever
+* transaction span is already open), a scheduled job is a fresh top-level entry:
+* production dispatches it back to the Worker as its own RPC, so a scheduled
+* `mutation` runs inside its own BEGIN/COMMIT span and notifies subscription
+* listeners on success. The harness supplies a callback that reproduces those
+* semantics (mutations wrapped + notified; actions run unwrapped).
+*/
+/**
+* The schema value produced by `@lunora/server`'s `defineSchema`. Accepted
+* structurally; internally it is handed to `@lunora/do`'s `runShardMigrations` /
+* `createShardCtxDb`, whose `SchemaLike` is the same shape declared in the DO
+* package — the two are structurally compatible at runtime (only their
+* independently-declared trigger nesting drifts at the type level), so the
+* boundary cast below is sound.
+*/
+type TestSchema = Schema<Record<string, TableDefinition>>;
+/**
+* A user-supplied identity, surfaced to handlers via `ctx.auth`. `userId` is the
+* subject the handler reads from `ctx.auth.userId`; any additional fields are
+* returned verbatim from `ctx.auth.getIdentity()` (mirroring a decoded JWT).
+*/
+interface TestIdentity extends Record<string, unknown> {
+  userId?: null | string;
+}
+/**
+* An async iterable/iterator returned by {@link TestHarness.subscribe}.
+* Guarantees `return()` is always defined (unlike the optional `AsyncIterator.return`),
+* so callers can always unsubscribe without a `?.` guard.
+*/
+interface TestSubscription<R> extends AsyncIterable<R> {
+  next: () => Promise<IteratorResult<R, R>>;
+  return: () => Promise<IteratorResult<R, R>>;
+}
+/** An inline handler accepted by `query` / `mutation` / `run`, given direct context access. */
+type InlineQueryFunction<R> = (context: QueryCtx) => Promise<R> | R;
+type InlineMutationFunction<R> = (context: MutationCtx) => Promise<R> | R;
+type InlineActionFunction<R> = (context: ActionCtx) => Promise<R> | R;
+/**
+* A map from function path strings (e.g. `"messages:send"`) to their
+* registered function objects. Used by the fake scheduler to resolve
+* `ctx.scheduler.runAfter(delay, "messages:send", args)` → handler invocation.
+*
+* Only mutations and actions can be scheduled in production; queries passed
+* here will be accepted but produce a console.warn at dispatch time.
+*
+* The value type uses `any` because `RegisteredFunction` is contravariant in its
+* args type parameter — a `RegisteredMutation` with concrete args is not assignable
+* to `RegisteredMutation` with `ArgsValidator` at the type level even though at
+* runtime it is sound (the fake scheduler passes `Record&lt;string, unknown>` to
+* `handler` and ignores the return value).
+*/
+type FunctionRegistry = Record<string, RegisteredAction<any, any> | RegisteredMutation<any, any> | RegisteredQuery<any, any>>;
+/**
+* Options accepted by {@link lunoraTest}.
+*
+* All options are optional — `lunoraTest(schema)` preserves v1 behaviour with
+* clearly-throwing stubs for unsupported surfaces.
+*/
+interface LunoraTestOptions {
+  /**
+  * Injectable `fetch` implementation for action contexts. When provided,
+  * `ctx.fetch` in every `action` (and `withIdentity` views) resolves to this
+  * function rather than throwing the "not available in v1" stub.
+  *
+  * Pass `vi.fn()` or any `typeof globalThis.fetch` compatible implementation.
+  * @example
+  * ```ts
+  * const fakeFetch = vi.fn().mockResolvedValue(Response.json({ ok: true }));
+  * const t = lunoraTest(schema, { fetch: fakeFetch });
+  * ```
+  */
+  fetch?: typeof globalThis.fetch;
+  /**
+  * Function registry for the fake in-memory scheduler. Maps a
+  * `functionPath` string (the value passed as the second argument to
+  * `ctx.scheduler.runAfter` / `ctx.scheduler.runAt`) to the corresponding
+  * registered function object.
+  *
+  * Only required if your handlers schedule work. Scheduled jobs for paths
+  * NOT listed here produce a `console.warn` at dispatch time (matching prod
+  * behaviour for unknown paths).
+  * @example
+  * ```ts
+  * const t = lunoraTest(schema, {
+  *   functions: { "messages:send": sendMutation },
+  * });
+  * ```
+  */
+  functions?: FunctionRegistry;
+}
+/**
+* The in-memory test harness returned by {@link lunoraTest}. Mirrors the first
+* five methods of Convex's `convexTest`: `query` / `mutation` / `action` / `run`
+* / `withIdentity`. All five share one in-memory `node:sqlite` backend, so a
+* write from one method is visible to a read from another (including across a
+* `withIdentity` scope).
+*/
+interface TestHarness {
+  /** Run a registered `action` (or an inline `async (context) => …`) against the harness. */
+  action: {
+    <A extends ArgsValidator, R>(reference: RegisteredAction<A, R>, args: InferArgs<A>): Promise<R>;
+    <R>(inline: InlineActionFunction<R>): Promise<R>;
+  };
+  /** Close the underlying in-memory SQLite database, releasing the native handle. Idempotent; safe to call on any `withIdentity` view. */
+  close: () => void;
+  /** Run a registered `mutation` (or an inline `async (context) => …`) against the harness. */
+  mutation: {
+    <A extends ArgsValidator, R>(reference: RegisteredMutation<A, R>, args: InferArgs<A>): Promise<R>;
+    <R>(inline: InlineMutationFunction<R>): Promise<R>;
+  };
+  /** Run a registered `query` (or an inline `async (context) => …`) against the harness. */
+  query: {
+    <A extends ArgsValidator, R>(reference: RegisteredQuery<A, R>, args: InferArgs<A>): Promise<R>;
+    <R>(inline: InlineQueryFunction<R>): Promise<R>;
+  };
+  /** Direct db access at mutation-level (read + write), mirroring `convexTest`'s `run`. */
+  run: <R>(function_: InlineMutationFunction<R>) => Promise<R>;
+  /**
+  * Controls for the fake in-memory scheduler. Always present; scheduler
+  * jobs only execute when you call `advance(ms)` or `runPending()`.
+  *
+  * - `list()` — snapshot of all pending jobs (enqueue order).
+  * - `advance(ms)` — tick the virtual clock forward by `ms` ms, executing every job
+  * whose `scheduledFor` is now at or below virtual now.
+  * - `runPending()` — execute all currently pending jobs regardless of their scheduled time.
+  *
+  * Scheduled jobs run through the same `runInternal` dispatch as
+  * `ctx.runMutation`, so they share the harness SQLite database.
+  */
+  scheduler: FakeSchedulerControls;
+  /**
+  * Subscribe to a registered query (or inline query function) and receive
+  * an async iterable of snapshots. The first value is emitted immediately
+  * (the current query result). Subsequent values are emitted after each
+  * `mutation` / `run` call on this harness completes.
+  *
+  * Subscriptions are table-agnostic — any mutation triggers a re-evaluation.
+  * This matches the harness's single-writer model and keeps the implementation
+  * free of DO machinery.
+  * @example
+  * ```ts
+  * const sub = t.subscribe(list, {});
+  * const first = await sub.next(); // current result
+  * await t.mutation(send, { author: "ada", body: "hi" });
+  * const second = await sub.next(); // updated result
+  * await sub.return(); // unsubscribe
+  * ```
+  *
+  * The iterable is lazy — it never buffers more than one pending result.
+  * If you do not consume fast enough and multiple mutations fire, the next
+  * `next()` call will reflect the most-recent state (intermediate snapshots
+  * are coalesced).
+  */
+  subscribe: {
+    <A extends ArgsValidator, R>(reference: RegisteredQuery<A, R>, args: InferArgs<A>): TestSubscription<R>;
+    <R>(inline: InlineQueryFunction<R>): TestSubscription<R>;
+  };
+  /** Return a harness view that shares this harness's db but reports the given identity on `ctx.auth`. */
+  withIdentity: (identity: TestIdentity) => TestHarness;
+}
+/**
+* Spin up an in-memory Lunora function harness for `schema`.
+*
+* `lunoraTest(schema)` runs the migrations against a fresh `node:sqlite`
+* database, builds the same `ctx.db` writer the real Durable Object builds (via
+* `@lunora/do`'s `createShardCtxDb`), and returns a harness whose `query` /
+* `mutation` / `action` / `run` execute a registered function's `handler`
+* directly — no Durable Object, no `wrangler`, no network.
+*
+* **v1 surfaces now supported:**
+*
+* - `ctx.fetch` (actions): inject a custom `fetch` via `options.fetch`.
+* - `ctx.scheduler` (mutations + actions): fully functional fake with virtual clock;
+* control via `harness.scheduler.advance(ms)` / `runPending()` / `list()`.
+* - `harness.subscribe(query, args)`: async iterable that re-emits after mutations.
+*
+* **v1 stubs (still throwing):** `ctx.storage`, `ctx.vectors`, `ctx.workflows`.
+* These are clearly documented follow-ups.
+*/
+declare const lunoraTest: (schema: TestSchema, options?: LunoraTestOptions) => TestHarness;
+export { type FakeScheduledJob, type FakeSchedulerControls, type FunctionRegistry, type LunoraTestOptions, type ScheduledJobFailure, type SweepOptions, type TestHarness, type TestIdentity, type TestSubscription, lunoraTest };

package/dist/index.mjs

@@ -0,0 +1,2 @@
+export { lunoraTest } from './packem_shared/lunoraTest-BUg4Ebv8.mjs';
+export { extractLink, listCapturedMail, waitForMail } from '@lunora/mail/testing';