@lunora/testing 1.0.0-alpha.9 → 1.0.0-alpha.90

package/dist/index.d.mts

@@ -1,17 +1,174 @@
-import { ScheduledJob, RegisteredAction, RegisteredMutation, RegisteredQuery, ArgsValidator, InferArgs, ActionCtx, MutationCtx, QueryCtx, TableDefinition, Schema } from '@lunora/server';
+import { AgentMessageRow, AgentRunInput, AgentGenerateResult, AgentRunResult, AgentDefinition } from '@lunora/agent';
+import { ScheduledJob, RegisteredAction, RegisteredMutation, RegisteredQuery, ArgsValidator, InferArgs, ActionCtx, MutationCtx, QueryCtx, LogFields, TableDefinition, Schema } from '@lunora/server';
 export { type InboxOptions, 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 `AGENT_*` bindings 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;
+/** The primitive an eval attaches 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;
+}
+/** 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;
+  /**
+   * 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.
+ */
+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 captured during an `advance()` / `runPending()`
+ * sweep. Production's scheduler isolates per-job failures (one bad job does not
+ * abort the rest), so the fake scheduler does the same — but, being a test
+ * harness, it never swallows the error: every failure is recorded here so tests
+ * can still assert on it.
+ */
 interface ScheduledJobFailure {
   /** The args the job was dispatched with. */
   args: Record<string, unknown>;
@@ -23,94 +180,85 @@ 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 during the advance) are NOT re-evaluated in
+   * the same advance call — callers should advance again if needed.
+   *
+   * Per-job failures are isolated (matching production): a job that throws does
+   * NOT prevent the remaining due jobs from running. After every due job has
+   * run, the failures are surfaced — they are recorded on
+   * {@link FakeSchedulerControls.failures} and, by default, re-thrown so a test
+   * still sees the error. A single failure is re-thrown verbatim; multiple
+   * failures are aggregated into an `AggregateError`. Pass
+   * `{ throwOnError: false }` to suppress the re-throw and inspect
+   * {@link FakeSchedulerControls.failures} (and the returned count) instead.
+   *
+   * Returns the number of jobs that were executed (including failed ones).
+   */
   advance: (ms: number, options?: SweepOptions) => Promise<number>;
   /**
-  * All scheduled-job failures captured so far, in execution order, across
-  * every `advance()` / `runPending()` call on this harness. Always available,
-  * even when `throwOnError: false` suppressed the re-throw. The list is a
-  * snapshot — mutating it does not affect the scheduler.
-  */
+   * All scheduled-job failures captured so far, in execution order, across
+   * every `advance()` / `runPending()` call on this harness. Always available,
+   * even when `throwOnError: false` suppressed the re-throw. The list is a
+   * snapshot — mutating it does not affect the scheduler.
+   */
   failures: () => ScheduledJobFailure[];
   /**
-  * List all pending jobs (those not yet executed or cancelled) in the order
-  * they were enqueued.
-  */
+   * List all pending jobs (those not yet executed or cancelled) in the order
+   * they were enqueued.
+   */
   list: () => FakeScheduledJob[];
   /**
-  * Execute all currently pending jobs regardless of their `scheduledFor`
-  * time. Equivalent to advancing to `Infinity`. Returns the number of jobs
-  * executed (including failed ones).
-  *
-  * Failure isolation and surfacing match {@link FakeSchedulerControls.advance}:
-  * one failing job does not abort the rest, and failures are recorded on
-  * {@link FakeSchedulerControls.failures} and re-thrown unless
-  * `{ throwOnError: false }` is passed.
-  */
+   * Execute all currently pending jobs regardless of their `scheduledFor`
+   * time. Equivalent to advancing to `Infinity`. Returns the number of jobs
+   * executed (including failed ones).
+   *
+   * Failure isolation and surfacing match {@link FakeSchedulerControls.advance}:
+   * one failing job does not abort the rest, and failures are recorded on
+   * {@link FakeSchedulerControls.failures} and re-thrown unless
+   * `{ throwOnError: false }` is passed.
+   */
   runPending: (options?: SweepOptions) => Promise<number>;
 }
 /** Options controlling how an `advance()` / `runPending()` sweep surfaces failures. */
 interface SweepOptions {
   /**
-  * When `true` (the default), failures encountered during the sweep are
-  * re-thrown after every due job has run — a single failure verbatim, multiple
-  * as an `AggregateError`. When `false`, the sweep resolves normally and
-  * failures are observable only via {@link FakeSchedulerControls.failures}.
-  */
+   * When `true` (the default), failures encountered during the sweep are
+   * re-thrown after every due job has run — a single failure verbatim, multiple
+   * as an `AggregateError`. When `false`, the sweep resolves normally and
+   * failures are observable only via {@link FakeSchedulerControls.failures}.
+   */
   throwOnError?: boolean;
 }
 /**
-* Top-level dispatch for a scheduled job — wired by the harness. Unlike the
-* `runInternal` closure used by `ctx.run*` composition (which rides whatever
-* transaction span is already open), a scheduled job is a fresh top-level entry:
-* production dispatches it back to the Worker as its own RPC, so a scheduled
-* `mutation` runs inside its own BEGIN/COMMIT span and notifies subscription
-* listeners on success. The harness supplies a callback that reproduces those
-* semantics (mutations wrapped + notified; actions run unwrapped).
-*/
-/**
-* The schema value produced by `@lunora/server`'s `defineSchema`. Accepted
-* structurally; internally it is handed to `@lunora/do`'s `runShardMigrations` /
-* `createShardCtxDb`, whose `SchemaLike` is the same shape declared in the DO
-* package — the two are structurally compatible at runtime (only their
-* independently-declared trigger nesting drifts at the type level), so the
-* boundary cast below is sound.
-*/
+ * 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 +268,117 @@ 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&lt;string, unknown>` to
+ * `handler` and ignores the return value).
+ */
 type FunctionRegistry = Record<string, RegisteredAction<any, any> | RegisteredMutation<any, any> | RegisteredQuery<any, any>>;
 /**
-* Options accepted by {@link lunoraTest}.
-*
-* All options are optional — `lunoraTest(schema)` preserves v1 behaviour with
-* clearly-throwing stubs for unsupported surfaces.
-*/
+ * 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().mockResolvedValue(Response.json({ ok: true }));
+   * const t = lunoraTest(schema, { fetch: fakeFetch });
+   * ```
+   */
   fetch?: typeof globalThis.fetch;
   /**
-  * Function registry for the fake in-memory scheduler. Maps a
-  * `functionPath` string (the value passed as the second argument to
-  * `ctx.scheduler.runAfter` / `ctx.scheduler.runAt`) to the corresponding
-  * registered function object.
-  *
-  * Only required if your handlers schedule work. Scheduled jobs for paths
-  * NOT listed here produce a `console.warn` at dispatch time (matching prod
-  * behaviour for unknown paths).
-  * @example
-  * ```ts
-  * const t = lunoraTest(schema, {
-  *   functions: { "messages:send": sendMutation },
-  * });
-  * ```
-  */
+   * 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;
 }
 /**
-* 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 +397,189 @@ 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;
 }
+/** 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;
+  }[];
+}
 /**
-* 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()`.
+ * - `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;
+}
+/** 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&lt;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<string> | string, scorers: ReadonlyArray<Scorer>) => Promise<EvalResult>;
+export { type AgentHarness, type AgentHarnessOptions, type AgentRunOverrides, type EvalCase, type EvalItemResult, type EvalResult, type EvaluationAttributeValue, type EvaluationSpanHandle, type FakeScheduledJob, type FakeSchedulerControls, type FunctionRegistry, type HarnessDispatch, type HarnessMessage, type HarnessThread, type LunoraTestOptions, type RecordEvaluationInput, type ScheduledJobFailure, type ScoreResult, type Scorer, type ScorerSample, type SweepOptions, type TestHarness, type TestIdentity, type TestSubscription, agentHarness, containsScorer, evaluate, evaluationAttributes, exactMatchScorer, finalTurn, keywordScorer, llmScorer, lunoraTest, recordEvaluation, regexScorer, scoreSample, toolCallTurn };