@lunora/testing 1.0.0-alpha.29 → 1.0.0-alpha.290

package/dist/index.d.mts

@@ -1,17 +1,361 @@
-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';
+import { AgentMessageRow, AgentRunInput, AgentTokenDelta, AgentGenerateResult, AgentRunResult, AgentDefinition } from '@lunora/agent';
+import { SecretValueHost } from '@lunora/platform';
+import { LanguageModel } from 'ai';
+import { ArtifactsBindingLike, ArtifactsErrorCode, ArtifactsCommitMetadata, ArtifactsTreeEntry } from '@lunora/bindings/artifacts';
+import { ScheduledJob, LogFields, RegisteredAction, RegisteredMutation, RegisteredQuery, ArgsValidator, InferArgs, ActionCtx, MutationCtx, QueryCtx, TableDefinition, Schema } from '@lunora/server';
+import { NotifyDefinition } from '@lunora/notify';
+import { ChannelType, ChannelPayloadMap } from '@visulima/notification';
+import { QueueContentType } from '@lunora/queue';
+import { MockLanguageModelV4 } from 'ai/test';
+export {
+/**
+ * `@lunora/testing` — the user-facing toolkit for end-to-end testing a Lunora app.
+ *
+ * Today it surfaces the dev mail-catcher helpers from `@lunora/mail/testing`: in
+ * `lunora dev` every outbound email (sign-up verification, forgot-password, magic
+ * links) is captured into the studio's root-shard inbox instead of hitting a real
+ * provider, and these helpers read that inbox over the admin RPC so a Playwright
+ * test can drive "request reset → read the email → follow the link → set a new
+ * password" deterministically.
+ *
+ * This is the home for E2E fixtures to grow into — auth helpers and more — so
+ * tests import one package (`@lunora/testing`) rather than reaching into each
+ * sub-package's `/testing` entry.
+ */
+type InboxOptions,
+/**
+ * `@lunora/testing` — the user-facing toolkit for end-to-end testing a Lunora app.
+ *
+ * Today it surfaces the dev mail-catcher helpers from `@lunora/mail/testing`: in
+ * `lunora dev` every outbound email (sign-up verification, forgot-password, magic
+ * links) is captured into the studio's root-shard inbox instead of hitting a real
+ * provider, and these helpers read that inbox over the admin RPC so a Playwright
+ * test can drive "request reset → read the email → follow the link → set a new
+ * password" deterministically.
+ *
+ * This is the home for E2E fixtures to grow into — auth helpers and more — so
+ * tests import one package (`@lunora/testing`) rather than reaching into each
+ * sub-package's `/testing` entry.
+ */
+type WaitForMailOptions, extractLink, listCapturedMail, waitForMail } from '@lunora/mail/testing';
+/** A thread message as the in-memory runtime stores it (superset of {@link AgentMessageRow}). */
+interface HarnessMessage extends AgentMessageRow {
+  messageKey: string;
+  threadKey: string;
+}
+/** A thread record as the in-memory runtime stores it. */
+interface HarnessThread {
+  agent: string;
+  error?: string;
+  instanceId?: string;
+  key: string;
+  messageCount: number;
+  owner?: string;
+  status: string;
+  title?: string;
+  usage?: unknown;
+}
+/** One recorded function dispatch the loop made through `ctx.run`. */
+interface HarnessDispatch {
+  args: Record<string, unknown> | undefined;
+  path: string;
+}
+/** Extra function-dispatch handler layered over the built-in `agents:*` runtime double. */
+type HarnessFunction = (args?: Record<string, unknown>) => unknown;
+interface AgentHarnessOptions {
+  /**
+   * Worker `env` bindings visible to tool `execute` and a dynamic
+   * `instructions` thunk. Default `{ LUNORA_TEST: true }`.
+   */
+  env?: Record<string, unknown>;
+  /**
+   * The agent's `lunora/agents.ts` export name — used for thread attribution
+   * and to derive the child-agent export keys a sub-agent tool targets.
+   * Default `"agent"`.
+   */
+  exportName?: string;
+  /**
+   * Stub the app functions a tool's `execute` (or the agent's `memory.source`)
+   * dispatches through `ctx.run`, keyed by function path (`"weather:lookup"`).
+   * A handler layered here shadows the built-in `agents:*` runtime double for
+   * that path. An unstubbed non-`agents:*` dispatch throws, so a missing stub
+   * fails loudly rather than silently returning `undefined`.
+   */
+  functions?: Record<string, HarnessFunction>;
+  /**
+   * Scripted model decisions, one {@link AgentGenerateResult} per LLM turn —
+   * the default script for {@link AgentHarness.run}. A terminal turn has an
+   * empty `toolCalls`; a tool-calling turn lists the calls the loop then runs
+   * against the agent's own tools. Override per run via `run(..., { script })`,
+   * or replace it per run with a streamed `model` via `run(..., { model })`.
+   */
+  script?: AgentGenerateResult[];
+  /**
+   * The secret store the agent's `requestSecretTool` values live in, shared by
+   * every run of this harness. Default: an in-memory store whose clock only moves
+   * through its `advanceClock`.
+   */
+  secrets?: SecretValueHost;
+}
+/** Per-run overrides for {@link AgentHarness.run}. */
+interface AgentRunOverrides {
+  /** The workflow instance id for this run (default: an auto-incrementing `wf-N`). */
+  instanceId?: string;
+  /**
+   * The model for THIS run, replacing the scripted decisions. Each turn runs
+   * through the production seam over this model: `createStreamGenerate` (the
+   * `streamText` path, so a recorded stream from `recordedModel` is consumed
+   * part by part) with `onTokenDelta` as its live sink.
+   */
+  model?: LanguageModel;
+  /**
+   * Live token-delta sink for a `model` run — receives each text delta as the
+   * recorded stream produces it. Ignored for scripted runs.
+   */
+  onTokenDelta?: (delta: AgentTokenDelta) => void;
+  /** The model script for THIS run, replacing the harness default. */
+  script?: AgentGenerateResult[];
+}
+interface AgentHarness {
+  /**
+   * Resolve once the run `instanceId` has reached the wait named `name` (e.g.
+   * `secret:0:call_1`, for the first turn's call `call_1`), so a test can act on the run at a known point instead of
+   * after a delay.
+   */
+  awaitWait: (instanceId: string, name: string) => Promise<void>;
+  /**
+   * Decline the `requestSecretTool` call `toolCallId` on `threadKey` and wake its
+   * wait, as the owner's decline does.
+   */
+  decline: (threadKey: string, toolCallId: string) => void;
+  /**
+   * Deliver the event the run `instanceId` is waiting on. Delivered before that
+   * wait is reached, it is held for it.
+   */
+  deliver: (instanceId: string, name: string, payload: unknown) => void;
+  /**
+   * Every function dispatch the loop has made through `ctx.run`, in order —
+   * both the `agents:*` runtime calls and the tool/memory app dispatches. Use
+   * it to assert a tool called the function you expected with the args you
+   * expected.
+   */
+  readonly dispatches: ReadonlyArray<HarnessDispatch>;
+  /** Fail the run `instanceId`'s pending wait the way an elapsed host timeout does. */
+  expire: (instanceId: string, name: string) => void;
+  /**
+   * Every journal entry the runs have written, in the order they were written:
+   * each completed step's output (`{ kind: "step", name, output }`) and each
+   * delivered wait payload (`{ kind: "wait", name, type, payload }`). A test
+   * asserts a secret is absent from this, as it must be from the durable journal.
+   */
+  journalEntries: () => unknown[];
+  /** The persisted messages of a thread, ordered by `seq`. */
+  messages: (threadKey: string) => AgentMessageRow[];
+  /**
+   * Drive one durable agent run to completion against the in-memory journal +
+   * runtime double, returning the loop's {@link AgentRunResult}. Reuse the same
+   * `threadKey` across calls to continue a conversation (the persisted history
+   * carries over); each call runs under a fresh instance id, modelling a
+   * distinct workflow instance.
+   */
+  run: (params: AgentRunInput, overrides?: AgentRunOverrides) => Promise<AgentRunResult>;
+  /** The secret store the runs use (see {@link AgentHarnessOptions.secrets}). */
+  readonly secrets: SecretValueHost;
+  /**
+   * Supply `value` for the `requestSecretTool` call `toolCallId` on `threadKey` and
+   * wake its wait, as the owner's supply does. The value goes to the secret store
+   * and only the request's handle reaches the run.
+   */
+  supply: (threadKey: string, toolCallId: string, value: string) => Promise<void>;
+  /** The stored thread record (status, error, instanceId, usage, …), or `undefined` before its first run. */
+  thread: (threadKey: string) => HarnessThread | undefined;
+}
+/**
+ * A unit-test harness for a `defineAgent` tool-loop that runs WITHOUT a real
+ * model or network. It drives {@link runAgentLoop} over the agent's own
+ * `AgentGenerate` seam — the model is a script of per-turn decisions, tool calls
+ * run the agent's real `execute` functions inside an in-memory durable-step
+ * journal, and thread/message persistence goes through an in-memory `agents:*`
+ * runtime double. Mock any function a tool (or the agent's memory) dispatches
+ * through the `functions` option.
+ *
+ * ```ts
+ * const harness = agentHarness(support, {
+ *     script: [toolCallTurn("c1", "lookup", { id: "o_1" }), finalTurn("It shipped.")],
+ *     functions: { "orders:lookup": () => ({ status: "shipped" }) },
+ * });
+ * const result = await harness.run({ input: "where is my order?", threadKey: "t1" });
+ * expect(result.text).toBe("It shipped.");
+ * expect(harness.messages("t1").at(-1)?.content).toBe("It shipped.");
+ * ```
+ *
+ * The harness deliberately does NOT model the concurrency guard. A
+ * human-in-the-loop pause (an approval, or a `requestSecretTool` request) stops
+ * the run at its wait; the test resolves it with `deliver` or `expire`, and the
+ * harness does not route a decision through the owner-gated mutations. The
+ * harness is for exercising an agent's tools and turn logic, not the durable
+ * orchestration itself (that is covered inside `@lunora/agent`).
+ */
+declare const agentHarness: (agent: AgentDefinition, options: AgentHarnessOptions) => AgentHarness;
+/** A terminal (final-answer) turn — no tool calls. */
+declare const finalTurn: (text: string, extra?: Partial<AgentGenerateResult>) => AgentGenerateResult;
+/** A single-tool-call turn: the loop runs the named tool with `input`. */
+declare const toolCallTurn: (id: string, name: string, input: unknown, text?: string) => AgentGenerateResult;
+/**
+ * Shared, bundler-inlined builder for the OpenTelemetry `gen_ai.evaluation.*`
+ * attributes an AI **evaluation** verdict (a scorer's `{name, score, label?}`)
+ * contributes to a **generation span**.
+ *
+ * This is the emit-time counterpart of the cloud OTLP decoder, which reads
+ * `gen_ai.evaluation.<name>.score` (number) and optional
+ * `gen_ai.evaluation.<name>.label` (string) attribute pairs back off a generation
+ * span (`EVALUATION_PREFIX = "gen_ai.evaluation."`). The framework emits exactly
+ * that pair here so a score rides the same trace as the generation it grades.
+ *
+ * It lives in `shared/` because more than one layer needs the identical wire
+ * format with no runtime dependency edge between them: `@lunora/do` builds it into
+ * a live `ctx.trace` span's post-hoc attributes (`SpanHandle.recordEvaluation`),
+ * and `@lunora/server` mirrors the handle shape structurally. `@lunora/testing`
+ * ships a parallel test-time helper (`recordEvaluation` / `evaluationAttributes`)
+ * that targets the same `gen_ai.evaluation.*` contract for span-less eval
+ * events/metrics. Keep this file genuinely zero-dependency so inlining stays sound.
+ */
+/** The primitive an eval contributes to a span: a numeric score or a string label. */
+type EvaluationAttributeValue = number | string;
+/**
+ * Structural slice of the post-hoc span handle `ctx.trace` hands its body (see the
+ * server `SpanHandle`) — enough to attach an eval's attributes. Declared here
+ * rather than imported so `@lunora/testing` takes no dependency on `@lunora/server`
+ * or `@lunora/do`; the real handle is assignable to it.
+ */
+interface EvaluationSpanHandle {
+  setAttributes: (fields: Record<string, EvaluationAttributeValue>) => void;
+}
+/**
+ * Structural slice of `ctx.metrics` — enough to record a score as a durable
+ * series. Declared here for the same reason as {@link EvaluationSpanHandle}: no
+ * dependency on `@lunora/server`, and the real handle is assignable.
+ */
+interface EvaluationMetrics {
+  gauge: (name: string, value: number, attributes?: Record<string, unknown>) => void;
+}
+/** One eval verdict to emit. */
+interface RecordEvaluationInput {
+  /**
+   * Optional categorical label (e.g. `"pass"` / `"fail"` / a rubric bucket),
+   * emitted as the `.label` attribute. Omitted → no label attribute.
+   */
+  label?: string;
+  /**
+   * Optional `ctx.metrics` handle. Passing it ALSO records the score as a
+   * `gen_ai.evaluation.<name>.score` gauge, which is what gives an eval a
+   * durable history: span attributes live in the shard's bounded in-memory
+   * ring and vanish on hibernation, while metrics are persisted in per-minute
+   * buckets and can be charted as a trend. Additive — the attributes are
+   * emitted either way.
+   */
+  metrics?: EvaluationMetrics;
+  /**
+   * The scorer/evaluation name — becomes the key's name segment. Any character
+   * outside `[A-Za-z0-9._-]` is replaced with `_` so a scorer name carrying a
+   * colon (e.g. `"contains:shipped"`) still yields a well-formed attribute key.
+   */
+  name: string;
+  /** The numeric score (typically `[0, 1]`), emitted as the `.score` attribute. */
+  score: number;
+  /**
+   * Optional generation span to attach the attributes to — the post-hoc
+   * `SpanHandle` a `ctx.trace` body receives. Omitted → nothing is attached and
+   * the caller uses the returned bag for a standalone event/metric.
+   */
+  span?: EvaluationSpanHandle;
+}
+/**
+ * Build the `gen_ai.evaluation.NAME.*` attribute bag for one eval verdict — the
+ * `.score` (number) always, the `.label` (string) when a label is given. Exported
+ * so a caller can emit the score as a standalone event/metric without a span.
+ *
+ * Delegates to the shared `shared/evaluation-attributes.ts` builder so
+ * `@lunora/testing`'s scorers and the runtime's own `recordEvaluation` emit the
+ * identical wire format — only the thrown error type differs, wrapped here as a
+ * `LunoraError` to match this package's public error contract.
+ */
+declare const evaluationAttributes: (input: Pick<RecordEvaluationInput, "label" | "name" | "score">) => Record<string, EvaluationAttributeValue>;
+/**
+ * Emit one eval verdict as `gen_ai.evaluation.NAME.*` attributes. Attaches them to
+ * `input.span` when supplied (the post-hoc generation-span handle), and always
+ * returns the attribute bag so a span-less caller can ship it as an eval
+ * event/metric. Privacy-safe: only the name, score, and optional label are
+ * emitted — never the graded prompt or output.
+ */
+declare const recordEvaluation: (input: RecordEvaluationInput) => Record<string, EvaluationAttributeValue>;
+/** Test controls returned alongside the fake binding. */
+interface ArtifactsFake {
+  /** The fake `env.ARTIFACTS` binding. */
+  binding: ArtifactsBindingLike;
+  /** Make the next binding or repo call throw an `ArtifactsError` with `code` (e.g. `UPSTREAM_UNAVAILABLE`). */
+  failNext: (code: ArtifactsErrorCode) => void;
+  /** How many repo handles `get()` has handed out and how many were disposed — a leak shows as `opened > disposed`. */
+  readonly handles: {
+    disposed: number;
+    opened: number;
+  };
+  /** Stage a blob by object id. Returns the stored `Blob` (the exact instance `readBlob` hands back). */
+  putBlob: (repo: string, hash: string, content: Blob | string) => Blob;
+  /** Append a commit to the repo's history (newest first in `log()`), readable by `readCommit`. */
+  putCommit: (repo: string, commit: ArtifactsCommitMetadata) => void;
+  /** Stage a file at a ref, standing in for a push. Returns the stored `Blob` (the exact instance `readFile` hands back). */
+  putFile: (repo: string, file: {
+    content: Blob | string;
+    path: string;
+    ref: string;
+    type?: string;
+  }) => Blob;
+  /** Stage a tree by object id. */
+  putTree: (repo: string, hash: string, entries: ArtifactsTreeEntry[]) => void;
+  /** The repo names currently in the namespace. */
+  repoNames: () => string[];
+}
+/**
+ * Build an in-memory Artifacts binding plus seeding and inspection controls.
+ *
+ * ```ts
+ * const fake = createArtifactsFake({ namespace: "default" });
+ * const artifacts = createArtifacts({ binding: fake.binding });
+ * await artifacts.create("docs");
+ * fake.putFile("docs", { ref: "main", path: "README.md", content: "# hi" });
+ * ```
+ */
+declare const createArtifactsFake: (options?: {
+  namespace?: string;
+}) => ArtifactsFake;
+/** A {@link SecretValueHost} whose clock the test moves forward by hand. */
+interface FakeSecretValues extends SecretValueHost {
+  /** Move the store's clock forward, so a value put earlier can expire. */
+  advanceClock: (ms: number) => void;
+}
+/**
+ * In-memory {@link SecretValueHost} for harness suites. Follows the contract in
+ * `@lunora/platform` (unguessable refs, scope, one claimant, expiry refuses
+ * reads) with a clock that starts at zero, so a test controls every expiry
+ * through {@link FakeSecretValues.advanceClock}.
+ */
+declare const createFakeSecretValues: () => FakeSecretValues;
 /** 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.
-*/
+ * A single scheduled-job failure that exhausted its retry budget, captured
+ * during an `advance()` / `runPending()` sweep. Mirrors `SchedulerDO`'s
+ * dead-letter park (`recordRetry()`, `packages/scheduler/src/scheduler-do.ts:875-909`):
+ * a job that fails while it still has retries left is silently re-enqueued
+ * with backoff and is NOT recorded here. Only once a job's `attempts` exceeds
+ * `@lunora/scheduler`'s `MAX_RETRY_ATTEMPTS` does it land here — being a test
+ * harness, the fake scheduler never swallows a terminal failure, so tests can
+ * still assert on it.
+ */
 interface ScheduledJobFailure {
   /** The args the job was dispatched with. */
   args: Record<string, unknown>;
@@ -23,94 +367,168 @@ interface ScheduledJobFailure {
   id: string;
 }
 /**
-* Controls exposed on the test harness for the fake in-memory scheduler.
-* Access via `harness.scheduler`.
-*/
+ * 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 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, or re-enqueued as a retry, 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. A failure with retries
+   * left is silently re-enqueued with exponential backoff on the virtual clock
+   * — mirroring `SchedulerDO`'s default retry policy (`MAX_RETRY_ATTEMPTS`
+   * retries, `RETRY_BASE_DELAY_MS` base delay, doubling; both imported from
+   * `@lunora/scheduler`) — rather than surfaced. Advancing far enough to
+   * observe a terminal failure therefore costs the WHOLE backoff schedule
+   * (30s + 60s + 120s + 240s + 480s = 930s of virtual clock at today's
+   * defaults), not a single tick.
+   * Only once a job's retry budget is exhausted is the failure surfaced: it is
+   * recorded on {@link FakeSchedulerControls.failures} and, by default,
+   * re-thrown so a test still sees the error. A single such failure is
+   * re-thrown verbatim; multiple 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 dispatched this sweep, including ones that
+   * failed and were silently retried, and ones that failed terminally.
+   */
   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.
-  */
+   * All scheduled-job failures that exhausted their retry budget, in
+   * execution order, across every `advance()` / `runPending()` call on this
+   * harness. A failure with retries remaining is NOT recorded here — see
+   * {@link ScheduledJobFailure}. 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 all pending jobs (those not yet executed or cancelled) in the order
+   * they were enqueued. A job currently waiting out its retry backoff is
+   * still pending (visible here with its `attempts` count incremented and
+   * `scheduledFor` pushed out) until its budget is exhausted.
+   */
   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.
-  */
+   * Execute all currently pending jobs regardless of their `scheduledFor`
+   * time. Equivalent to advancing to `Infinity`. Returns the number of jobs
+   * dispatched this sweep (including failed ones, retried or terminal).
+   *
+   * Failure isolation, retry, and surfacing match
+   * {@link FakeSchedulerControls.advance}: one failing job does not abort the
+   * rest, a failure under the retry budget is silently re-enqueued rather
+   * than surfaced, and only a terminal failure is 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}.
-  */
+   * 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;
 }
+/** What a handler attached to the dispatch's span (`ctx.span`) during a harness run. */
+interface RecordedWideEvent {
+  /**
+   * Attributes accumulated across the run, merged in call order. Values are
+   * recorded AS PASSED (not coerced the way the real pipeline normalizes them),
+   * so a test asserts on what the handler meant rather than on the wire form.
+   */
+  attributes: LogFields;
+  /** Span events recorded via `ctx.span.addEvent` / `recordException`, in order. */
+  events: {
+    attributes?: LogFields;
+    name: string;
+  }[];
+  /** Links recorded via `ctx.span.addLink`, in order. */
+  links: {
+    spanId: string;
+    traceId: string;
+  }[];
+}
+/** The channels `ctx.notify` can deliver on. */
+type NotifyChannel = Extract<ChannelType, "chat" | "inapp" | "push" | "webhook">;
+/**
+ * One delivery a handler made through `ctx.notify` / `ctx.push`. For push,
+ * `payload.to` is the device target: the FCM token, or for Web Push the
+ * JSON-stringified subscription (keys included).
+ */
+type SentNotification = { [C in NotifyChannel]: {
+  channel: C;
+  payload: ChannelPayloadMap[C];
+}; }[NotifyChannel];
+/** Inspect what handlers delivered through `ctx.notify` / `ctx.push`. */
+interface FakeNotifyControls {
+  /** Forget every recorded delivery (registered subscriptions are kept). */
+  clear: () => void;
+  /** Recorded deliveries in send order, optionally only those on `channel`. Throws when `options.notify` was not passed. */
+  sent: (channel?: NotifyChannel) => SentNotification[];
+}
+/** One message a handler enqueued through `ctx.queues.<name>`, as the consumer decodes it. */
+interface SentQueueMessage {
+  body: unknown;
+  contentType?: QueueContentType;
+  delaySeconds?: number;
+  /** The `lunora/queues.ts` export name the message was sent through. */
+  queue: string;
+}
 /**
-* 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).
-*/
+ * Inspect what handlers enqueued. Production sends are not transactional — a
+ * mutation that throws after `ctx.queues.x.send(...)` has still sent it — so the
+ * record keeps those too. Nothing is consumed: a test asserts on the messages and
+ * drives the consumer itself if it wants to.
+ */
+interface FakeQueueControls {
+  /** Forget every recorded message. */
+  clear: () => void;
+  /** Recorded messages in send order, optionally only those sent to `queue`; an undeclared `queue` throws. */
+  sent: (queue?: string) => SentQueueMessage[];
+}
+/** One message a handler published through `ctx.topics.<name>`, as a subscriber decodes it. */
+interface PublishedTopicMessage {
+  body: unknown;
+  contentType?: QueueContentType;
+  delaySeconds?: number;
+  /** The `lunora/queues.ts` topic export name the message was published to. */
+  topic: string;
+}
 /**
-* 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.
-*/
+ * Inspect what handlers published. Like queue sends, a publish is not
+ * transactional, so one made by a mutation that then threw stays recorded.
+ */
+interface FakeTopicControls {
+  /** Forget every recorded message. */
+  clear: () => void;
+  /** Recorded messages in publish order, optionally only those published to `topic`; an undeclared `topic` throws. */
+  published: (topic?: string) => PublishedTopicMessage[];
+}
+/** The schema value produced by `@lunora/server`'s `defineSchema`. */
 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).
-*/
+ * 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.
-*/
+ * 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>>;
@@ -120,88 +538,187 @@ 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).
-*/
+ * 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<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.
-*/
+ * Options accepted by {@link lunoraTest}.
+ *
+ * All options are optional — `lunoraTest(schema)` preserves v1 behaviour with
+ * clearly-throwing stubs for unsupported surfaces.
+ */
 interface LunoraTestOptions {
   /**
-  * Injectable `ctx.env` for every context (query / mutation / action). When
-  * provided, handlers that read `ctx.env.SOME_KEY` (the validated `defineEnv`
-  * surface) see this object. Left unset it stays `undefined` — matching the
-  * optional `ctx.env?` field, so graceful `ctx.env?.KEY` access still yields
-  * `undefined` rather than throwing. Not a throwing stub for exactly that
-  * reason: `env` is designed to be legitimately absent.
-  * @example
-  * ```ts
-  * const t = lunoraTest(schema, { env: { STRIPE_KEY: "sk_test_…" } });
-  * ```
-  */
+   * Enforce the secure-by-default RLS guard on the writer registered
+   * procedures dispatch through (`query`/`mutation`/`action`, via
+   * `reference.handler`) — the same `enforceRls: true` production's generated
+   * `buildCtx` always passes. Under a `.rls("required")` schema, a procedure
+   * that touches a known, non-`.public()` table without `.use(rls(...))` in
+   * its chain rejects with `RlsRequiredError`, exactly as it would on first
+   * dispatch in production. Defaults to `true` so a green suite means the
+   * deploy is RLS-safe; the harness's other surfaces — `t.run` and any
+   * `@lunora/seed` helper built on it — stay on the trusted, UNGUARDED writer
+   * regardless of this flag (mirroring production's admin/migration system
+   * paths).
+   *
+   * Set to `false` to opt back into the pre-guard permissive behaviour (every
+   * `lunoraTest` release before this option existed): every procedure's
+   * `ctx.db` goes unguarded even under a `.rls("required")` schema. This
+   * forfeits the "a passing suite means the deploy is safe" guarantee — a
+   * procedure that forgot `.use(rls(...))` will pass in tests and throw
+   * `RlsRequiredError` on its first production request. No effect when the
+   * schema does not declare `.rls("required")` (the guard is a no-op there
+   * either way).
+   * @default true
+   * @example
+   * ```ts
+   * // Restores the old permissive behavior for a suite not yet migrated.
+   * const t = lunoraTest(schema, { enforceRls: false });
+   * ```
+   */
+  enforceRls?: boolean;
+  /**
+   * Injectable `ctx.env` for every context (query / mutation / action). When
+   * provided, handlers that read `ctx.env.SOME_KEY` (the validated `defineEnv`
+   * surface) see this object. Left unset it stays `undefined` — matching the
+   * optional `ctx.env?` field, so graceful `ctx.env?.KEY` access still yields
+   * `undefined` rather than throwing. Not a throwing stub for exactly that
+   * reason: `env` is designed to be legitimately absent.
+   * @example
+   * ```ts
+   * const t = lunoraTest(schema, { env: { STRIPE_KEY: "sk_test_…" } });
+   * ```
+   */
   env?: Record<string, unknown>;
   /**
-  * 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 });
-  * ```
-  */
+   * 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(async () => 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 },
-  * });
-  * ```
-  */
+   * 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;
   /**
-  * Fixed value for `ctx.now` (epoch ms) in every context. Production captures
-  * `Date.now()` once per execution; in tests a fixed `now` makes time-dependent
-  * handlers deterministic. Defaults to the wall clock at harness creation.
-  * @example
-  * ```ts
-  * const t = lunoraTest(schema, { now: 1_700_000_000_000 });
-  * ```
-  */
+   * The app's `lunora/notify.ts` default export. Enables `ctx.notify` and its
+   * `ctx.push` alias on every context, built by `@lunora/notify`'s own
+   * `createNotify` — so register / list / unregister / broadcast behave as in
+   * production, and channels are wired exactly when production wires them
+   * (each factory is called with `options.env`; a push target for a transport
+   * that resolved to nothing fails). Differences: deliveries are recorded and
+   * report accepted instead of reaching a service (no send-time DNS re-check,
+   * retry or circuit breaker), and subscriptions live in an in-memory store —
+   * the definition's `store` is never called. Assert on deliveries with
+   * `harness.notify.sent()`. Left unset, touching `ctx.notify` / `ctx.push` —
+   * or calling `harness.notify.sent()` — throws, naming this option.
+   * @example
+   * ```ts
+   * import notify from "../lunora/notify";
+   *
+   * const t = lunoraTest(schema, { notify });
+   * await t.action(alertOwner, { orderId });
+   * expect(t.notify.sent("push")).toHaveLength(1);
+   * ```
+   */
+  notify?: NotifyDefinition;
+  /**
+   * Fixed value for `ctx.now` (epoch ms) in every context. Production captures
+   * `Date.now()` once per execution; in tests a fixed `now` makes time-dependent
+   * handlers deterministic. Defaults to the wall clock at harness creation.
+   * @example
+   * ```ts
+   * const t = lunoraTest(schema, { now: 1_700_000_000_000 });
+   * ```
+   */
   now?: number;
+  /**
+   * The export names of the queues in `lunora/queues.ts` (the keys of
+   * `ctx.queues`). Each gets a recording producer on mutation and action
+   * contexts, behind `@lunora/queue`'s own validation (batch cap, delay
+   * ceiling), so a send the platform would refuse rejects here too. A name not
+   * listed rejects on use, as an undeclared queue does in production. Assert
+   * on sends with `harness.queues.sent(name)`. Left unset, touching
+   * `ctx.queues` — or calling `harness.queues.sent()` — throws, naming this
+   * option.
+   * @example
+   * ```ts
+   * const t = lunoraTest(schema, { queues: ["jobs"] });
+   * await t.mutation(enqueueJob, { id: "a" });
+   * expect(t.queues.sent("jobs")).toEqual([{ body: { id: "a" }, queue: "jobs" }]);
+   * ```
+   */
+  queues?: ReadonlyArray<string>;
+  /**
+   * Fakes for `ctx.services` (the `lunora.config` `services` an app calls),
+   * keyed like `ctx.services`. Set on action contexts only — queries and
+   * mutations have no `ctx.services` at runtime either. A key with no fake
+   * throws on use, naming the option to add it to.
+   * @example
+   * ```ts
+   * const t = lunoraTest(schema, {
+   *   services: { documentParser: { fetch: vi.fn(async () => Response.json({ text: "…" })) } },
+   * });
+   * ```
+   */
+  services?: Record<string, object>;
+  /**
+   * The export names of the topics in `lunora/queues.ts` (the keys of
+   * `ctx.topics`). Each gets a recording publisher on mutation and action
+   * contexts, built by `@lunora/queue`'s own `createTopicContext` — so the
+   * batch cap, delay ceiling and reserved-key check reject as in production,
+   * and a name not listed rejects on use. Bodies are recorded and size-checked
+   * as `queues` records them, once per message however many subscriptions the
+   * app declares; no subscription handler runs. Assert with
+   * `harness.topics.published(name)`. Left unset, touching `ctx.topics` — or
+   * calling `harness.topics.published()` — throws, naming this option.
+   * @example
+   * ```ts
+   * const t = lunoraTest(schema, { topics: ["signups"] });
+   * await t.mutation(signUp, { email: "a@example.test" });
+   * expect(t.topics.published("signups")).toHaveLength(1);
+   * ```
+   */
+  topics?: ReadonlyArray<string>;
 }
 /**
-* 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).
-*/
+ * 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: {
@@ -215,76 +732,325 @@ interface TestHarness {
     <A extends ArgsValidator, R>(reference: RegisteredMutation<A, R>, args: InferArgs<A>): Promise<R>;
     <R>(inline: InlineMutationFunction<R>): Promise<R>;
   };
+  /**
+   * What handlers delivered through `ctx.notify` / `ctx.push` (enabled by
+   * `options.notify`): `sent(channel?)` in send order, `clear()` to reset.
+   * Both throw when the option was not passed. Shared with any `withIdentity` view.
+   */
+  notify: FakeNotifyControls;
   /** 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`. */
+  /**
+   * What handlers enqueued through `ctx.queues` (declared by `options.queues`):
+   * `sent(name?)` in send order, `clear()` to reset. Sends are not
+   * transactional in production, so one made by a mutation that then threw is
+   * recorded too. Both throw when the option was not passed. Shared with any
+   * `withIdentity` view.
+   */
+  queues: FakeQueueControls;
+  /**
+   * Direct db access at mutation-level (read + write), mirroring `convexTest`'s
+   * `run`. This is the harness's trusted escape hatch: `ctx.db` here is always
+   * the UNGUARDED writer, regardless of `options.enforceRls` or the schema's
+   * RLS mode — seeding/asserting against a protected table never trips the
+   * secure-by-default guard. A `ctx.runMutation`/`ctx.runQuery` call from
+   * inside the body still dispatches the target as a real registered
+   * procedure, so it is guarded exactly as `t.mutation`/`t.query` would guard
+   * it.
+   */
   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.
-  */
+   * 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 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>;
   };
+  /**
+   * What handlers published through `ctx.topics` (declared by `options.topics`):
+   * `published(name?)` in publish order, `clear()` to reset. Like queue sends,
+   * publishes are not transactional. Both throw when the option was not passed.
+   * Shared with any `withIdentity` view.
+   */
+  topics: FakeTopicControls;
+  /**
+   * What handlers attached to `ctx.span` — the **wide event** — during this
+   * harness's runs, so a test can assert the instrumentation itself:
+   *
+   * ```ts
+   * await t.mutation(checkout, { items: 3 });
+   * expect(t.wideEvent().attributes["cart.items"]).toBe(3);
+   * ```
+   *
+   * Accumulates across calls on this view (it is not reset per run), mirroring
+   * the harness's single shared database. Shared with any `withIdentity` view.
+   */
+  wideEvent: () => RecordedWideEvent;
   /** 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.env` (all contexts): inject the validated env via `options.env`; unset it
-* stays `undefined`, matching the optional `ctx.env?` field.
-* - `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.
-*/
+ * 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/shard-engine`'s `createShardCtxDb`, with the same `enforceRls: true`
+ * production's generated `buildCtx` passes), and returns a harness whose
+ * `query` / `mutation` / `action` execute a registered function's `handler`
+ * directly — no Durable Object, no `wrangler`, no network. Under a
+ * `.rls("required")` schema a procedure missing `.use(rls(...))` therefore
+ * rejects here exactly as it would on its first production dispatch — see
+ * `LunoraTestOptions.enforceRls` to opt out, and `run`'s doc for the trusted
+ * escape hatch (always unguarded).
+ *
+ * **v1 surfaces now supported:**
+ *
+ * - `ctx.env` (all contexts): inject the validated env via `options.env`; unset it
+ * stays `undefined`, matching the optional `ctx.env?` field.
+ * - `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()`. As in
+ * production it is transactional inside a mutation: a job scheduled by a mutation
+ * that then throws never becomes pending.
+ * - `ctx.queues` (mutations + actions): recording producers for `options.queues`;
+ * inspect via `harness.queues.sent(name)`.
+ * - `ctx.topics` (mutations + actions): recording publishers for `options.topics`;
+ * inspect via `harness.topics.published(name)`.
+ * - `ctx.notify` / `ctx.push` (all contexts): built from `options.notify` with
+ * recorded deliveries and in-memory subscriptions; inspect via `harness.notify.sent()`.
+ * - `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 };
+/** One provider stream part as a model's `doStream` emits it (`text-delta`, `tool-call`, `finish`, …). */
+type ModelStreamResult = Awaited<ReturnType<InstanceType<typeof MockLanguageModelV4>["doStream"]>>;
+type RecordedStreamPart = ModelStreamResult["stream"] extends ReadableStream<infer Part> ? Part : never;
+/**
+ * A pause point in a recorded turn. The stream emits `after` parts, then stops
+ * until {@link StreamGate.release} is called — a test observes or cancels the
+ * run while it is mid-stream without sleeping.
+ */
+interface StreamGate {
+  /** Resolves once the stream has reached the gate and is waiting on {@link StreamGate.release}. */
+  readonly reached: Promise<void>;
+  /** Let the paused stream continue. Idempotent. */
+  release: () => void;
+  /** Called by the recorded stream when it reaches the gate; the stream resumes after `release`. */
+  wait: () => Promise<void>;
+}
+/** One recorded model call: the stream parts it emits, plus optional pause and failure points. */
+interface RecordedTurn {
+  /** Fail the stream with `cause` once `after` parts have been emitted (a mid-stream provider error). */
+  error?: {
+    after: number;
+    cause: unknown;
+  };
+  /** The provider stream parts for one model call, in emission order. */
+  parts: ReadonlyArray<RecordedStreamPart>;
+  /** Pause after `after` parts until `gate` is released. */
+  pause?: {
+    after: number;
+    gate: StreamGate;
+  };
+}
+/** Create a {@link StreamGate} to pause a recorded turn on. */
+declare const createStreamGate: () => StreamGate;
+/**
+ * A language model that replays recorded stream parts, one {@link RecordedTurn}
+ * per model call, in order. Pass it as an agent's `model` (or to
+ * `agentHarness(...).run(..., { model })`) to drive the production streaming
+ * seam against a recorded stream. Each call pops the next turn; a call past the
+ * last recorded turn fails the stream loudly rather than inventing an answer.
+ * `doStreamCalls` records the call options each turn was requested with.
+ */
+declare const recordedModel: (turns: ReadonlyArray<RecordedTurn>) => MockLanguageModelV4;
+/** One sample handed to a {@link Scorer}. */
+interface ScorerSample {
+  /** The reference/gold answer, when the scorer compares against one. */
+  expected?: string;
+  /** The prompt/input that produced the output (for LLM-judge context). */
+  input?: string;
+  /** Arbitrary per-sample metadata carried through. */
+  metadata?: Record<string, unknown>;
+  /** The model/agent output under test. */
+  output: string;
+}
+/** A scorer's verdict: a `[0, 1]` score and an optional human-readable reason. */
+interface ScoreResult {
+  reason?: string;
+  score: number;
+}
+/** A named scorer — returns a `[0, 1]` score (or a {@link ScoreResult}) for a sample. */
+interface Scorer {
+  name: string;
+  score: (sample: ScorerSample) => Promise<ScoreResult | number> | ScoreResult | number;
+}
+/**
+ * What a `produce` runner may return: the output text alone, or the text plus
+ * metadata describing what the run actually did.
+ *
+ * The metadata form exists for scorers that judge more than the final string —
+ * a retrieval scorer needs the ranked ids the run retrieved, which only the run
+ * can know. It is merged OVER the case's own metadata before scoring.
+ */
+interface ProducedOutput {
+  /** Merged over the case's `metadata`, then handed to every scorer. */
+  metadata?: Record<string, unknown>;
+  /** The output text under test. */
+  output: string;
+}
+/** One dataset case: an input and its optional gold answer/metadata. */
+interface EvalCase {
+  expected?: string;
+  input: string;
+  metadata?: Record<string, unknown>;
+}
+/** The per-case eval result: the produced output plus each scorer's verdict and the mean. */
+interface EvalItemResult {
+  average: number;
+  input: string;
+  output: string;
+  scores: Record<string, ScoreResult>;
+}
+/** The whole eval run: per-case results plus the mean of their averages. */
+interface EvalResult {
+  average: number;
+  items: EvalItemResult[];
+}
+/** Score 1 if the output contains `needle` (case-insensitive unless `caseSensitive`). */
+declare const containsScorer: (needle: string, options?: {
+  caseSensitive?: boolean;
+}) => Scorer;
+/** Score 1 when `pattern` matches the output. */
+declare const regexScorer: (pattern: RegExp, name?: string) => Scorer;
+/** Score 1 when the trimmed output exactly equals the trimmed `expected`. */
+declare const exactMatchScorer: () => Scorer;
+/** Score the fraction of `keywords` (case-insensitive) present in the output. */
+declare const keywordScorer: (keywords: ReadonlyArray<string>) => Scorer;
+/**
+ * An LLM-as-judge scorer. `judge` is INJECTED — a `(prompt) => Promise<string>`
+ * you wire to your model (e.g. via `ctx.ai` / `generateText`), so this module
+ * stays model-agnostic and the judge is mockable in tests. It returns the model's
+ * numeric verdict (`[0, 1]`) plus its reason.
+ */
+declare const llmScorer: (options: {
+  criteria: string;
+  judge: (prompt: string) => Promise<string>;
+  name?: string;
+}) => Scorer;
+/** Run every scorer over one sample (concurrently) → each verdict keyed by name + their mean. */
+declare const scoreSample: (sample: ScorerSample, scorers: ReadonlyArray<Scorer>) => Promise<{
+  average: number;
+  scores: Record<string, ScoreResult>;
+}>;
+/**
+ * Run a dataset through `produce` (e.g. an `agentHarness.run` wrapper returning
+ * the output text) and score each output with `scorers`. Cases run concurrently;
+ * give each its own thread/key inside `produce` if the producer is stateful.
+ * Returns per-case results plus the mean of their averages.
+ */
+declare const evaluate: (cases: ReadonlyArray<EvalCase>, produce: (input: string) => Promise<ProducedOutput | string> | ProducedOutput | string, scorers: ReadonlyArray<Scorer>) => Promise<EvalResult>;
+/** Where a retrieval scorer reads its two id lists from. */
+interface RetrievalScorerOptions {
+  /** Metadata key holding the gold relevant ids. Default `"relevant"`. */
+  relevantKey?: string;
+  /** Metadata key holding the run's ranked retrieved ids. Default `"retrieved"`. */
+  retrievedKey?: string;
+}
+/**
+ * Recall@k scorer — what fraction of the gold passages made it into the top
+ * `k`.
+ *
+ * This is the ceiling on everything downstream: a passage retrieval never
+ * returned is one no reranker can promote and no prompt can cite. Omit `k` to
+ * score the whole retrieved list.
+ */
+declare const recallAtK: (k?: number, options?: RetrievalScorerOptions) => Scorer;
+/**
+ * Precision@k scorer — what fraction of the top `k` retrieved passages are
+ * gold.
+ *
+ * This is the counterweight to recall: padding `topK` raises recall for free
+ * while burying the answer in noise the model has to read past, and pay for.
+ * Omit `k` to score the whole retrieved list.
+ */
+declare const precisionAtK: (k?: number, options?: RetrievalScorerOptions) => Scorer;
+/**
+ * Mean Reciprocal Rank scorer — `1 / rank` of the first gold passage: 1 if it
+ * is first, 0.5 if second, 0 if absent.
+ *
+ * This is the metric that notices ordering, which recall cannot. A gold passage
+ * at rank 20 counts the same as rank 1 for recall@20, but only one of those
+ * survives a context-window trim or a model that skims the top of its prompt.
+ */
+declare const mrrScorer: (options?: RetrievalScorerOptions) => Scorer;
+/**
+ * Normalized Discounted Cumulative Gain scorer — relevance discounted
+ * logarithmically by rank, divided by the best achievable arrangement.
+ *
+ * This is the one to gate on when comparing retrieval strategies. Unlike recall
+ * it is sensitive to order, and unlike MRR it credits every gold passage rather
+ * than only the first — so it is the metric that can actually say whether a
+ * reranker or a hybrid leg helped.
+ *
+ * Relevance is binary: an id is gold or it is not, which is what a gold-id set
+ * expresses. Graded relevance would need per-id weights.
+ */
+declare const ndcgAtK: (k?: number, options?: RetrievalScorerOptions) => Scorer;
+/**
+ * Groundedness scorer — does the answer assert only what the retrieved context
+ * supports?
+ *
+ * This is the generation-side counterpart to the metrics above: perfect
+ * retrieval still fails if the model answers from its own weights. It scores
+ * the output against the context via an injected `judge`, the same shape
+ * `llmScorer` takes, so this stays model-agnostic and mockable.
+ *
+ * Reads the context from `metadata.context` by default — the `context` string
+ * `retrieve()` already returns. Fails closed: no context means nothing could
+ * have grounded the answer.
+ */
+declare const groundednessScorer: (options: {
+  contextKey?: string;
+  judge: (prompt: string) => Promise<string>;
+  name?: string;
+}) => Scorer;
+export { type AgentHarness, type AgentHarnessOptions, type AgentRunOverrides, type ArtifactsFake, type EvalCase, type EvalItemResult, type EvalResult, type EvaluationAttributeValue, type EvaluationMetrics, type EvaluationSpanHandle, type FakeNotifyControls, type FakeQueueControls, type FakeScheduledJob, type FakeSchedulerControls, type FakeSecretValues, type FakeTopicControls, type FunctionRegistry, type HarnessDispatch, type HarnessMessage, type HarnessThread, type LunoraTestOptions, type NotifyChannel, type ProducedOutput, type PublishedTopicMessage, type RecordEvaluationInput, type RecordedStreamPart, type RecordedTurn, type RetrievalScorerOptions, type ScheduledJobFailure, type ScoreResult, type Scorer, type ScorerSample, type SentNotification, type SentQueueMessage, type StreamGate, type SweepOptions, type TestHarness, type TestIdentity, type TestSubscription, agentHarness, containsScorer, createArtifactsFake, createFakeSecretValues, createStreamGate, evaluate, evaluationAttributes, exactMatchScorer, finalTurn, groundednessScorer, keywordScorer, llmScorer, lunoraTest, mrrScorer, ndcgAtK, precisionAtK, recallAtK, recordEvaluation, recordedModel, regexScorer, scoreSample, toolCallTurn };