@agiledigital/pingone-aic-script-tester 0.1.0

package/dist/src/harness/spec.d.ts

@@ -0,0 +1,67 @@
+import type { z } from "zod";
+import type { Case, Expect, Given, JsonObject } from "../case/types.ts";
+import type { Channels, RequestDraft, SuiteSpec, WireMap } from "./types.ts";
+/** Shared-state key prefix the tenant's config library reads before the ESV. */
+export declare const ESV_STATE_PREFIX = "esv.";
+/**
+ * Collapse the suite's `always` and one test's overrides into a single draft.
+ *
+ * Merging is per key, not per channel: a test that sets one header keeps the
+ * suite's others. Replacing the whole channel would make `always` useless the
+ * moment a test needed to add anything, which is the failure mode that drives
+ * people to copy the defaults into every test and then let them drift.
+ */
+export declare function mergeChannels(always: Channels | undefined, override: Channels | undefined): RequestDraft;
+/**
+ * A header or parameter is `string | string[]`; the wire form is always a
+ * list, because AM reports one list element per occurrence in send order
+ * (verified 2026-09-08 on both engines). A bare string is therefore a
+ * one-element list, not a separate case.
+ */
+export declare function normaliseWire(map: WireMap | undefined): Record<string, string[]>;
+/**
+ * Fold the parsed inputs and the ESV overrides into shared state.
+ *
+ * Inputs land under their own names and ESVs under `esv.<name>`, so a suite
+ * declaring an input called `esv.x` would be ambiguous; that is rejected
+ * rather than resolved by precedence, because either precedence is a
+ * defensible guess and neither is visible at the call site.
+ */
+export declare function applyInputsAndEsv(draft: RequestDraft, input: Readonly<Record<string, unknown>>): void;
+/** Parse a run's inputs against the suite's schema, or reject extras. */
+export declare function parseInputs<TSchema extends z.ZodType>(spec: Pick<SuiteSpec<TSchema>, "name" | "inputs">, raw: unknown): Record<string, unknown>;
+/**
+ * Turn a resolved draft into a `Given`.
+ *
+ * `session` compiles to `given.existingSession`, whose shape was measured
+ * 2026-09-14 on both evaluators: a String->String map, present only when the
+ * request carries a session cookie. Values are coerced here rather than in the
+ * mock, so the AIC lane — which has to put them through a mini journey's
+ * `putSessionProperty` — sends exactly what the local lane seeded.
+ */
+export declare function toGiven(draft: RequestDraft, base?: Given, realm?: string): Given;
+/** Assemble the `Case` both lanes are judged against. One definition. */
+export declare function toCase<TSchema extends z.ZodType>(spec: Pick<SuiteSpec<TSchema>, "name" | "script" | "outcomes">, 
+/**
+ * Used verbatim. The vitest adapter supplies an already-qualified
+ * "describe > test" path, so prefixing the suite name here would print it
+ * twice in every failure message.
+ */
+caseName: string, draft: RequestDraft, expect: Expect, base?: Given): Case;
+/**
+ * The same `Case`, from a `Given` that is already resolved.
+ *
+ * A step chain's later passes cannot go through `toCase`: `toGiven` layers the
+ * draft over the base, so the request's original seeds would win over what the
+ * previous pass actually left in state — the chain would silently restart from
+ * the top on every step.
+ */
+export declare function caseWithGiven<TSchema extends z.ZodType>(spec: Pick<SuiteSpec<TSchema>, "name" | "script" | "outcomes">, caseName: string, given: Given, expect: Expect): Case;
+export type { JsonObject };
+/**
+ * Who the mini journey logs in as. The principal need not exist as a managed
+ * object (measured 2026-09-14), so this is free; taking it from shared state
+ * means a suite that already sets `username` gets a session for that user
+ * without saying so twice.
+ */
+export declare function sessionPrincipal(draft: RequestDraft): string;

package/dist/src/harness/spec.js

@@ -0,0 +1,189 @@
+import { AM_OWNED_SESSION_SET, DEFAULT_SESSION_PRINCIPAL, sessionFromPrincipal, } from "../case/session.js";
+/** Shared-state key prefix the tenant's config library reads before the ESV. */
+export const ESV_STATE_PREFIX = "esv.";
+/**
+ * Collapse the suite's `always` and one test's overrides into a single draft.
+ *
+ * Merging is per key, not per channel: a test that sets one header keeps the
+ * suite's others. Replacing the whole channel would make `always` useless the
+ * moment a test needed to add anything, which is the failure mode that drives
+ * people to copy the defaults into every test and then let them drift.
+ */
+export function mergeChannels(always, override) {
+    return {
+        state: {
+            shared: { ...(always?.state?.shared ?? {}), ...(override?.state?.shared ?? {}) },
+            transient: {
+                ...(always?.state?.transient ?? {}),
+                ...(override?.state?.transient ?? {}),
+            },
+        },
+        esv: { ...(always?.esv ?? {}), ...(override?.esv ?? {}) },
+        headers: { ...normaliseWire(always?.headers), ...normaliseWire(override?.headers) },
+        params: { ...normaliseWire(always?.params), ...normaliseWire(override?.params) },
+        session: { ...(always?.session ?? {}), ...(override?.session ?? {}) },
+        // Declared-empty and not-declared are different requests: `session: {}`
+        // asks for a logged-in session with no extra properties, which is a real
+        // case and is invisible if you only look at the merged key count.
+        sessionRequested: always?.session !== undefined || override?.session !== undefined,
+    };
+}
+/**
+ * A header or parameter is `string | string[]`; the wire form is always a
+ * list, because AM reports one list element per occurrence in send order
+ * (verified 2026-09-08 on both engines). A bare string is therefore a
+ * one-element list, not a separate case.
+ */
+export function normaliseWire(map) {
+    const out = {};
+    for (const [key, value] of Object.entries(map ?? {})) {
+        out[key] = wireValues(key, value);
+    }
+    return out;
+}
+function wireValues(key, value) {
+    if (typeof value === "string") {
+        return [value];
+    }
+    if (!Array.isArray(value) || value.some((entry) => typeof entry !== "string")) {
+        throw new Error(`rhino-local: ${key} must be a string or an array of strings`);
+    }
+    if (value.length === 0) {
+        throw new Error(`rhino-local: ${key} is an empty array — a key present with no values cannot be sent; omit the key instead`);
+    }
+    return [...value];
+}
+/**
+ * Fold the parsed inputs and the ESV overrides into shared state.
+ *
+ * Inputs land under their own names and ESVs under `esv.<name>`, so a suite
+ * declaring an input called `esv.x` would be ambiguous; that is rejected
+ * rather than resolved by precedence, because either precedence is a
+ * defensible guess and neither is visible at the call site.
+ */
+export function applyInputsAndEsv(draft, input) {
+    for (const [key, value] of Object.entries(input)) {
+        if (key.startsWith(ESV_STATE_PREFIX)) {
+            throw new Error(`rhino-local: input ${JSON.stringify(key)} collides with the ${JSON.stringify(ESV_STATE_PREFIX)} namespace reserved for ESV overrides; rename the input`);
+        }
+        draft.state.shared[key] = value;
+    }
+    for (const [name, value] of Object.entries(draft.esv)) {
+        draft.state.shared[`${ESV_STATE_PREFIX}${name}`] = value;
+    }
+}
+/** Parse a run's inputs against the suite's schema, or reject extras. */
+export function parseInputs(spec, raw) {
+    if (spec.inputs === undefined) {
+        if (raw !== undefined && Object.keys(raw).length > 0) {
+            throw new Error(`rhino-local: ${spec.name} passed inputs but declares none; add an \`inputs\` schema to the suite`);
+        }
+        return {};
+    }
+    const result = spec.inputs.safeParse(raw ?? {});
+    if (!result.success) {
+        const detail = result.error.issues
+            .map((issue) => `${issue.path.join(".") || "(root)"}: ${issue.message}`)
+            .join("; ");
+        throw new Error(`rhino-local: ${spec.name} input invalid — ${detail}`);
+    }
+    return result.data;
+}
+/**
+ * Turn a resolved draft into a `Given`.
+ *
+ * `session` compiles to `given.existingSession`, whose shape was measured
+ * 2026-09-14 on both evaluators: a String->String map, present only when the
+ * request carries a session cookie. Values are coerced here rather than in the
+ * mock, so the AIC lane — which has to put them through a mini journey's
+ * `putSessionProperty` — sends exactly what the local lane seeded.
+ */
+export function toGiven(draft, base = {}, realm = "alpha") {
+    const given = { ...base };
+    if (draft.sessionRequested) {
+        given.existingSession = {
+            ...sessionFromPrincipal(sessionPrincipal(draft), realm),
+            ...(base.existingSession ?? {}),
+            ...sessionStrings(draft.session),
+        };
+    }
+    if (Object.keys(draft.state.shared).length > 0) {
+        given.sharedState = { ...(base.sharedState ?? {}), ...draft.state.shared };
+    }
+    if (Object.keys(draft.state.transient).length > 0) {
+        given.transientState = {
+            ...(base.transientState ?? {}),
+            ...draft.state.transient,
+        };
+    }
+    if (Object.keys(draft.headers).length > 0) {
+        given.requestHeaders = { ...(base.requestHeaders ?? {}), ...draft.headers };
+    }
+    if (Object.keys(draft.params).length > 0) {
+        given.requestParameters = {
+            ...(base.requestParameters ?? {}),
+            ...draft.params,
+        };
+    }
+    return given;
+}
+/** Assemble the `Case` both lanes are judged against. One definition. */
+export function toCase(spec, 
+/**
+ * Used verbatim. The vitest adapter supplies an already-qualified
+ * "describe > test" path, so prefixing the suite name here would print it
+ * twice in every failure message.
+ */
+caseName, draft, expect, base = {}) {
+    return caseWithGiven(spec, caseName, toGiven(draft, base), expect);
+}
+/**
+ * The same `Case`, from a `Given` that is already resolved.
+ *
+ * A step chain's later passes cannot go through `toCase`: `toGiven` layers the
+ * draft over the base, so the request's original seeds would win over what the
+ * previous pass actually left in state — the chain would silently restart from
+ * the top on every step.
+ */
+export function caseWithGiven(spec, caseName, given, expect) {
+    return {
+        name: caseName,
+        script: spec.script,
+        outcomes: spec.outcomes,
+        given,
+        expect,
+    };
+}
+/**
+ * AM session properties are strings — every value in the measured 23-key
+ * session was one, `AuthLevel: "0"` included. A number or boolean is coerced
+ * (it survives the round trip unambiguously); an object or array is refused,
+ * because `putSessionProperty` would stringify it to `[object Object]` on the
+ * AIC lane while a structured mock would keep it here. That divergence is the
+ * false-pass shape this harness exists to prevent.
+ */
+function sessionStrings(session) {
+    const out = {};
+    for (const [key, value] of Object.entries(session)) {
+        if (AM_OWNED_SESSION_SET.has(key)) {
+            throw new Error(`rhino-local: session.${key} is set by AM, not by the caller — a mini journey that tries to override it fails the whole login with an unexplained 401. ${key === "UserId" || key === "Principals" || key === "UserToken" || key === "Principal" || key === "sun.am.UniversalIdentifier" ? "Set `state.username` instead; the session is minted for that principal" : "Remove it"}`);
+        }
+        if (value === null || typeof value === "object") {
+            throw new Error(`rhino-local: session.${key} must be a string — AM stores session properties as strings, so a ${value === null ? "null" : "structured value"} cannot survive the round trip`);
+        }
+        out[key] = String(value);
+    }
+    return out;
+}
+/**
+ * Who the mini journey logs in as. The principal need not exist as a managed
+ * object (measured 2026-09-14), so this is free; taking it from shared state
+ * means a suite that already sets `username` gets a session for that user
+ * without saying so twice.
+ */
+export function sessionPrincipal(draft) {
+    const username = draft.state.shared.username;
+    return typeof username === "string" && username.length > 0
+        ? username
+        : DEFAULT_SESSION_PRINCIPAL;
+}

package/dist/src/harness/step.d.ts

@@ -0,0 +1,80 @@
+import type { CallbackEffect, Expect, Given, JsonValue, RecordedEffects } from "../case/types.ts";
+import type { IdmHandle } from "./types.ts";
+/**
+ * One submitted callback value — what the client types into the callback the
+ * script sent. `type` names the callback it answers; the harness matches
+ * replies to emitted callbacks by type, in order.
+ */
+export interface CallbackReply {
+    type: string;
+    value: JsonValue;
+}
+export interface StepContext<TInput> {
+    input: TInput;
+    /** 1-based position in the chain. */
+    step: number;
+    /** What this pass emitted, in order. */
+    callbacks: CallbackEffect[];
+    effects: RecordedEffects;
+}
+/** Everything an intermediate pass can assert, minus the outcome it cannot have. */
+export type StepExpect = Omit<Expect, "outcome">;
+export interface StepSpec<TInput> {
+    /**
+     * What this pass must do before it suspends. `outcome` is not offered: a
+     * pass that decided an outcome did not suspend, and the chain has nothing
+     * to reply to.
+     */
+    expect?: StepExpect;
+    /**
+     * What the client submits back. A function receives what the pass emitted,
+     * which is how a reply depends on the choices the script offered.
+     */
+    reply: CallbackReply[] | ((ctx: StepContext<TInput>) => CallbackReply[]);
+    /**
+     * Asserted on each lane after this pass and before the reply is submitted —
+     * the point of the chain is to check the world between two halves of a
+     * journey, not only at the end. AIC cannot dump intermediate node state
+     * without adding a script-visible callback, so `effects.evidence` marks
+     * those channels unobserved there. Fail by throwing.
+     */
+    check?: (idm: IdmHandle, ctx: StepContext<TInput>) => void | Promise<void>;
+}
+/**
+ * Seed the next pass from the pass that just suspended.
+ *
+ * MEASURED 2026-09-14 against a live tenant, one scripted decision node that
+ * put a value in each bucket, sent a NameCallback, and read them back on the
+ * resumed pass (`docs/api/09-journeys.md` → "What survives a callback round
+ * trip"):
+ *
+ * - **shared state survives.** `nodeState.get` returned it and `nodeState.keys()`
+ *   still listed it.
+ * - **transient state does NOT.** It came back `null`, identical to a key
+ *   nobody ever set (the control), and it was absent from `keys()`. It is
+ *   dropped — not promoted into secure state, which is the plausible guess a
+ *   hand-rolled mock makes and the one that turns a broken script green.
+ * - **`resumedFromSuspend` stays false.** It belongs to `action.suspend()`, so
+ *   a callback round trip must not set it; seeding `true` here would put the
+ *   local lane in a state the AIC lane cannot even reach (the AIC lane refuses
+ *   `given.resumedFromSuspend` for exactly that reason).
+ *
+ * Secure state is carried as the previous pass left it. No next-gen script can
+ * write it — there is no `putSecure` — so this is local-lane bookkeeping for a
+ * seed the case supplied, not a claim about AM. The AIC lane skips any case
+ * that declares `given.secureState`.
+ */
+export declare function carryGiven(previous: Given, effects: RecordedEffects, submitted: readonly CallbackEffect[]): Given;
+/**
+ * Merge replies into the callbacks a pass emitted, producing what the client
+ * submits.
+ *
+ * An emitted callback with no reply is submitted **without a value**, so a
+ * script that reads it fails naming the type rather than receiving whatever
+ * the callback happened to carry outbound. That asymmetry is deliberate: AM
+ * fills an unanswered input with a per-type default (an unanswered
+ * HiddenValueCallback comes back holding its own `id`, measured 2026-09-14),
+ * and inventing those defaults for every callback type would be a mock the
+ * tenant does not match.
+ */
+export declare function submittedCallbacks(emitted: readonly CallbackEffect[], replies: readonly CallbackReply[], label: string): CallbackEffect[];

package/dist/src/harness/step.js

@@ -0,0 +1,97 @@
+/**
+ * Seed the next pass from the pass that just suspended.
+ *
+ * MEASURED 2026-09-14 against a live tenant, one scripted decision node that
+ * put a value in each bucket, sent a NameCallback, and read them back on the
+ * resumed pass (`docs/api/09-journeys.md` → "What survives a callback round
+ * trip"):
+ *
+ * - **shared state survives.** `nodeState.get` returned it and `nodeState.keys()`
+ *   still listed it.
+ * - **transient state does NOT.** It came back `null`, identical to a key
+ *   nobody ever set (the control), and it was absent from `keys()`. It is
+ *   dropped — not promoted into secure state, which is the plausible guess a
+ *   hand-rolled mock makes and the one that turns a broken script green.
+ * - **`resumedFromSuspend` stays false.** It belongs to `action.suspend()`, so
+ *   a callback round trip must not set it; seeding `true` here would put the
+ *   local lane in a state the AIC lane cannot even reach (the AIC lane refuses
+ *   `given.resumedFromSuspend` for exactly that reason).
+ *
+ * Secure state is carried as the previous pass left it. No next-gen script can
+ * write it — there is no `putSecure` — so this is local-lane bookkeeping for a
+ * seed the case supplied, not a claim about AM. The AIC lane skips any case
+ * that declares `given.secureState`.
+ */
+export function carryGiven(previous, effects, submitted) {
+    const next = { ...previous };
+    next.sharedState = clone(effects.sharedState.final);
+    // Not `{}`: absent and empty differ elsewhere in `Given`, and "the tenant
+    // dropped it" is absence.
+    delete next.transientState;
+    if (Object.keys(effects.secureState.final).length > 0) {
+        next.secureState = clone(effects.secureState.final);
+    }
+    else {
+        delete next.secureState;
+    }
+    next.callbacks = submitted.map((callback) => ({ ...callback }));
+    if (effects.managedStore !== undefined) {
+        // Records the earlier pass created have to be visible to the later one,
+        // or a chain can never test a journey that writes and then reads back.
+        next.managed = clone(effects.managedStore);
+    }
+    return next;
+}
+/**
+ * Merge replies into the callbacks a pass emitted, producing what the client
+ * submits.
+ *
+ * An emitted callback with no reply is submitted **without a value**, so a
+ * script that reads it fails naming the type rather than receiving whatever
+ * the callback happened to carry outbound. That asymmetry is deliberate: AM
+ * fills an unanswered input with a per-type default (an unanswered
+ * HiddenValueCallback comes back holding its own `id`, measured 2026-09-14),
+ * and inventing those defaults for every callback type would be a mock the
+ * tenant does not match.
+ */
+export function submittedCallbacks(emitted, replies, label) {
+    const pending = new Map();
+    for (const reply of replies) {
+        const queue = pending.get(reply.type);
+        if (queue === undefined) {
+            pending.set(reply.type, [reply.value]);
+        }
+        else {
+            queue.push(reply.value);
+        }
+    }
+    const out = [];
+    for (const callback of emitted) {
+        const queue = pending.get(callback.type);
+        const { value: _outbound, ...rest } = callback;
+        if (queue === undefined || queue.length === 0) {
+            out.push({ ...rest });
+            continue;
+        }
+        out.push({ ...rest, value: queue.shift() });
+    }
+    const leftover = [...pending.entries()].filter(([, queue]) => queue.length > 0);
+    if (leftover.length > 0) {
+        const emittedCounts = countByType(emitted);
+        const detail = leftover
+            .map(([type, queue]) => `${queue.length} unused ${type} ${queue.length === 1 ? "reply" : "replies"} (the pass emitted ${emittedCounts.get(type) ?? 0})`)
+            .join("; ");
+        throw new Error(`rhino-local: ${label} replied to callbacks the pass did not send — ${detail}. A reply nobody asked for would seed the next pass with a value the tenant could never deliver`);
+    }
+    return out;
+}
+function countByType(callbacks) {
+    const counts = new Map();
+    for (const callback of callbacks) {
+        counts.set(callback.type, (counts.get(callback.type) ?? 0) + 1);
+    }
+    return counts;
+}
+function clone(value) {
+    return JSON.parse(JSON.stringify(value));
+}

package/dist/src/harness/types.d.ts

@@ -0,0 +1,100 @@
+import type { z } from "zod";
+import type { Expect, Given, JsonObject, JsonValue } from "../case/types.ts";
+/** A header or parameter value. An array is sent as repeated occurrences. */
+export type WireValue = string | readonly string[];
+export type WireMap = Readonly<Record<string, WireValue>>;
+export interface StateChannels {
+    shared?: JsonObject;
+    transient?: JsonObject;
+}
+/**
+ * Everything a run can carry into the script, in one shape. The same five
+ * channels are declarable on the suite (`always`), overridable per test, and
+ * reachable from `beforeRun` — so there is one place to look, whichever
+ * surface you are reading.
+ */
+export interface Channels {
+    state?: StateChannels;
+    /**
+     * ESV overrides. NOT the `systemEnv` binding — these compile to shared
+     * state under `esv.<name>`, which the tenant's config library consults
+     * before falling back to the real ESV. Seed the real binding with
+     * `given.esv` instead; both mechanisms exist and mean different things.
+     */
+    esv?: Readonly<Record<string, string>>;
+    /** Sent on the authenticate request. No script can assign these bindings. */
+    headers?: WireMap;
+    /** Sent on the authenticate request. */
+    params?: WireMap;
+    /**
+     * `existingSession` — session properties the script sees, as a flat string
+     * map. Declaring it at all (`session: {}` included) asks for a logged-in
+     * session; the AIC lane pays for it with an extra round trip, because a
+     * session only exists once a journey has run to completion, so the lane
+     * runs a two-line mini journey and forwards its cookie to the subject.
+     *
+     * Custom properties only. The ones AM sets itself — `UserId`, `AuthLevel`
+     * and the rest — are refused, because `putSessionProperty` cannot override
+     * them and trying fails the whole login with an unexplained 401. The five
+     * AM derives from the principal come from `state.username` instead.
+     *
+     * Nothing about the subject tree changes, and the principal need not exist
+     * as a managed object (both measured 2026-09-14).
+     */
+    session?: JsonObject;
+}
+/** The mutable draft `beforeRun` is handed. */
+export interface RequestDraft {
+    state: {
+        shared: JsonObject;
+        transient: JsonObject;
+    };
+    esv: Record<string, string>;
+    headers: Record<string, string[]>;
+    params: Record<string, string[]>;
+    session: JsonObject;
+    /** Whether either level asked for a session at all. See mergeChannels. */
+    sessionRequested: boolean;
+}
+/** A managed record the harness creates and is therefore responsible for. */
+export interface FixtureSpec {
+    type: string;
+    record: JsonObject;
+}
+export interface BeforeRunContext<TInput> {
+    input: TInput;
+    request: RequestDraft;
+    fixtures: FixtureCreator;
+}
+export interface FixtureCreator {
+    create(type: string, record: JsonObject | JsonObject[]): Promise<void>;
+}
+/**
+ * What checks and cleanup receive on both lanes. The surface is shared, but
+ * record shape is not projected: AIC reads retain tenant-materialized fields.
+ */
+export interface IdmHandle {
+    read(resource: string): Promise<JsonObject | null>;
+    query(type: string, filter: Readonly<Record<string, JsonValue>>): Promise<JsonObject[]>;
+    delete(resource: string): Promise<void>;
+}
+export interface CleanupContext<TInput> {
+    input: TInput;
+}
+export interface SuiteSpec<TSchema extends z.ZodType> {
+    name: string;
+    /** Author source, already loaded. */
+    script: string;
+    /** The outcome vocabulary. Required here — a lease has to declare it. */
+    outcomes: readonly string[];
+    inputs?: TSchema;
+    always?: Channels;
+    fixtures?: Readonly<Record<string, FixtureSpec>>;
+    beforeRun?: (ctx: BeforeRunContext<z.output<TSchema>>) => void | Promise<void>;
+    cleanup?: (idm: IdmHandle, ctx: CleanupContext<z.output<TSchema>>) => Promise<void>;
+}
+/** Per-test overrides, merged over the suite's `always`. */
+export interface RunOverrides extends Channels {
+    expect: Expect;
+}
+export type { Expect, Given, JsonObject, JsonValue };

package/dist/src/harness/types.js

@@ -0,0 +1 @@
+export {};

package/dist/src/harness/vitest.d.ts

@@ -0,0 +1,52 @@
+import type { z } from "zod";
+import type { AicIo } from "../aic/tenant.ts";
+import type { TenantProvider } from "../aic/provider.ts";
+import { Lease, type LeaseOptions, type Suite } from "./lease.ts";
+export interface UseLeaseAicOptions {
+    id: string;
+    realm?: string;
+    tenant?: string;
+    project?: string;
+    /** Where the tenant and its bearer come from; see `resolveTenantProvider`. */
+    provider?: TenantProvider;
+    unsupported?: "fail" | "skip";
+}
+export interface UseLeaseOptions extends Partial<Omit<LeaseOptions, "runner" | "lane" | "realm">> {
+    spawnTimeoutMs?: number;
+    aic?: UseLeaseAicOptions;
+    /** Injected fake seam for adapter tests; production uses the default AIC I/O. */
+    aicIo?: AicIo;
+    /** Injected filesystem seam for adapter tests. */
+    aicStateDir?: string;
+}
+/** The env var that opts a run into the tenant lane. */
+export declare const AIC_LANE_ENV = "AIC_SCRIPT_TESTER_AIC";
+/**
+ * Spread into `useLease` options to run both lanes when `AIC_SCRIPT_TESTER_AIC=1`.
+ *
+ * Off by default, deliberately. The tenant lane needs an unlocked agent and
+ * network, which CI has neither of, and a checkout without them should still
+ * be able to run the whole suite offline — so opting in is a per-invocation
+ * decision, not a property of the file:
+ *
+ *     npm test                      # local lane only, as before
+ *     AIC_SCRIPT_TESTER_AIC=1 npm test    # both lanes, against the sandbox
+ *
+ * `id` must be unique per file: it seeds the deterministic resource ids, and
+ * one AIC lease per file is enforced.
+ */
+export declare function aicWhenEnabled(id: string, realm?: string): {
+    aic?: UseLeaseAicOptions;
+};
+/**
+ * Take a lease for one test file, and register its own lifecycle.
+ *
+ * The hooks are registered here rather than left to the author because
+ * forgetting teardown is the one mistake that leaks tenant state, and it
+ * leaks silently — the suite still passes. Owning the hooks makes the leak
+ * impossible to cause by omission. The same applies to failure records: the
+ * author must not have to remember to write the transaction id down.
+ */
+export declare function useLease<TSchema extends z.ZodType>(suite: Suite<TSchema>, options?: UseLeaseOptions): Lease<TSchema>;
+export declare function claimAicLeaseForFile(file: string, id: string): void;
+export declare function releaseAicLeaseForFile(file: string, id?: string): void;