@lunora/testing 1.0.0-alpha.22 → 1.0.0-alpha.220

package/dist/index.d.mts

@@ -1,17 +1,248 @@
-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, AgentGenerateResult, AgentRunResult, AgentDefinition } from '@lunora/agent';
+import { ScheduledJob, LogFields, RegisteredAction, RegisteredMutation, RegisteredQuery, ArgsValidator, InferArgs, ActionCtx, MutationCtx, QueryCtx, TableDefinition, Schema } from '@lunora/server';
+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 })`.
+   */
+  script: AgentGenerateResult[];
+}
+/** 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 script for THIS run, replacing the harness default. */
+  script?: AgentGenerateResult[];
+}
+interface AgentHarness {
+  /**
+   * 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>;
+  /** 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 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 or a
+ * human-in-the-loop approval pause — it 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>;
 /** 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 +254,119 @@ 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;
+  }[];
+}
 /**
-* 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.
-*/
+ * 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).
-*/
+ * 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,75 +376,130 @@ 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 `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 });
-  * ```
-  */
+   * 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(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 });
-  * ```
-  */
+   * 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;
+  /**
+   * 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 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: {
@@ -207,69 +518,251 @@ interface TestHarness {
     <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`. */
+  /**
+   * 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 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.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.
+ * - `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 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 EvalCase, type EvalItemResult, type EvalResult, type EvaluationAttributeValue, type EvaluationMetrics, type EvaluationSpanHandle, type FakeScheduledJob, type FakeSchedulerControls, type FunctionRegistry, type HarnessDispatch, type HarnessMessage, type HarnessThread, type LunoraTestOptions, type ProducedOutput, type RecordEvaluationInput, type RetrievalScorerOptions, type ScheduledJobFailure, type ScoreResult, type Scorer, type ScorerSample, type SweepOptions, type TestHarness, type TestIdentity, type TestSubscription, agentHarness, containsScorer, evaluate, evaluationAttributes, exactMatchScorer, finalTurn, groundednessScorer, keywordScorer, llmScorer, lunoraTest, mrrScorer, ndcgAtK, precisionAtK, recallAtK, recordEvaluation, regexScorer, scoreSample, toolCallTurn };