@oxy-hq/sdk 2.12.0 → 2.16.0

package/dist/testing.d.mts

@@ -0,0 +1,656 @@
+
+import { _ as OxyOrgAssignment, f as OxyFunctionRow, l as OxyFunctionContext, p as OxyFunctionUser, v as OxyOrgPlace } from "./function-context-BNpL5bFb.mjs";
+//#region src/testing/gates.d.ts
+/** The loose shape a JSON import of `oxy-app.json` satisfies. */
+interface ManifestLike {
+  slug?: string;
+  functions?: Record<string, Record<string, unknown> | undefined>;
+}
+/** `FunctionCapabilities` for one function, plus its write allowlist. */
+interface FunctionGates {
+  functionName: string;
+  slug: string;
+  /** `app_<slug>` with `-` → `_`, or `null` when the slug cannot back a writer. */
+  writerSchema: string | null;
+  secretsWrite: boolean;
+  emailSend: boolean;
+  orgRead: boolean;
+  storageRead: boolean;
+  storageWrite: boolean;
+  oltp: boolean;
+  airhouse: boolean;
+  /** `destinations`: the databases `ctx.warehouse` writes and `ctx.tx` may name. */
+  destinations: string[];
+  /** `customerWarehouseWrites`: database → the non-blank reason, blank ones dropped. */
+  customerWarehouseWrites: Record<string, string>;
+  /** `fetch.maxResponseBytes`, when the entry raises the ceiling. */
+  fetchMaxBytes: number | null;
+}
+/**
+ * `app_writer_name` + `WriterRef::schema_name`: the schema an app's slug
+ * derives, or `null` when it derives none.
+ *
+ * Both halves matter. `app_writer_name` refuses a slug containing `_` outright
+ * — `my_app` would otherwise alias the hyphenated sibling `my-app` onto one
+ * schema and role — and then runs the derived name through `validate_name`,
+ * which is what rejects a leading digit, an over-long name, and any character
+ * outside `[a-z0-9_]`. Skipping that second half handed back a schema for slugs
+ * the host answers `None` for, which is the difference between a green test and
+ * a closed `ctx.oltp` in production.
+ */
+declare function writerSchema(slug: string): string | null;
+/** Read the gates for `functionName` from `manifest`, or throw naming what is missing. */
+declare function readGates(manifest: ManifestLike, functionName: string): FunctionGates;
+//#endregion
+//#region src/testing/host-contract.d.ts
+/**
+ * The host's words, gates, op names and rules, as `@oxy-hq/sdk/testing`
+ * enforces them on an app's unit tests.
+ *
+ * ONE SOURCE OF TRUTH, AND IT IS NOT THIS FILE. Every string below is quoted
+ * from the host's source — `host.rs`, `host/destinations.rs`,
+ * `host/airhouse_ops.rs`, `upsert_support.rs`, `tx.rs`, `runtime.rs` under
+ * `crates/app/src/server/api/custom_apps_functions/`, and the connector's
+ * `transaction.rs` / `postgres_tx/convert.rs` — never paraphrased.
+ * `{placeholder}`s stand for what the host formats in (`{database}`,
+ * `{dialect}`, …) and use the host's own names.
+ *
+ * HELD TO THE HOST BY A RUST TEST. `sdk_testing_drift.rs`, beside `host.rs`,
+ * `include_str!`s this file and fails when a `refusal:` here is no longer a
+ * sentence its `source:` file contains, when `HOST_OPS` differs from the
+ * host's closed list, when `GATES` stops naming exactly the fields of
+ * `FunctionCapabilities`, when `ABSENT_GLOBALS` differs from `oxyc`'s lint
+ * list, or when `FETCH_RULES` differs from `is_safe_outbound`. One direction
+ * only: this file is checked against the host, the host is never checked
+ * against this file (`internal-docs/sdk-testing-context.md` §7, answer 9).
+ *
+ * THE RUST TEST READS TEXT, NOT TYPESCRIPT: after stripping comments it takes
+ * the block from `export const HOST_OPS` to `] as const;`, every object whose
+ * key line ends `: {` and carries `source:` and `refusal:` lines, the
+ * `hostField:` / `ops:` lines of `GATES`, the `name:` / `member:` lines of
+ * `ABSENT_GLOBALS`, and every quoted string in `FETCH_RULES`. Keep those keys
+ * spelled as they are, each `refusal:` a single string literal, and none of
+ * them behind a comment that is not a full-line one.
+ *
+ * NO `contractVersion` (§7, answer 10): a reworded refusal reaches an app on
+ * its next SDK bump, which is the right moment to see it; a version field
+ * with no consumer is a mechanism nobody reads.
+ */
+/**
+ * Every name the host pages an op under — `HOST_OPS` in `host_call_attrs.rs`,
+ * "pinned by unit tests to `host_op_name` and `runtime::host_call_span`". The
+ * `HostOp` type is this list, so `"warehouse.inserts"` does not compile.
+ */
+declare const HOST_OPS: readonly ["query", "query_stream", "fetch", "semantic.query", "airway.run", "warehouse.insert", "warehouse.exec", "warehouse.upsert", "warehouse.query", "tx.begin", "tx.begin_oltp", "tx.query", "tx.exec", "tx.commit", "tx.rollback", "oltp.query", "oltp.exec", "airhouse.query", "airhouse.exec", "airhouse.append", "storage.getUploadUrl", "storage.getDownloadUrl", "storage.put", "storage.get", "storage.head", "storage.list", "storage.delete", "storage.copy", "secrets.set", "email.send", "org.people", "org.places", "org.assignments"];
+/** One of the host's closed list of op names. */
+type HostOp = (typeof HOST_OPS)[number];
+/**
+ * The surface `reply_json` prefixes a refusal with (`runtime.rs`): a thrown
+ * `HostError`'s message is `"<surface>: <host message>"`. Every `tx.*` verb —
+ * `begin_oltp` included — answers under `ctx.tx`, because one op carries all
+ * six.
+ */
+declare const SURFACES: {
+  readonly query: "ctx.query";
+  readonly queryStream: "ctx.queryStream";
+  readonly fetch: "ctx.fetch";
+  readonly warehouse: "ctx.warehouse";
+  readonly tx: "ctx.tx";
+  readonly oltp: "ctx.oltp";
+  readonly airhouse: "ctx.airhouse";
+  readonly secretsSet: "ctx.secrets.set";
+  readonly emailSend: "ctx.email.send";
+  readonly storage: "ctx.storage";
+  readonly orgPeople: "ctx.org.people";
+  readonly orgPlaces: "ctx.org.places";
+  readonly orgAssignments: "ctx.org.assignments";
+  readonly semanticQuery: "ctx.semantic.query";
+  readonly airwayRun: "ctx.airway.run";
+};
+/** One refusal the host writes: the file it is quoted from and its template. */
+interface RefusalTemplate {
+  readonly source: string;
+  readonly refusal: string;
+}
+/**
+ * Every refusal the context throws, quoted from the host. The context renders
+ * a template by substituting its `{placeholder}`s and prefixing the surface.
+ */
+declare const REFUSALS: {
+  readonly secretsWrite: {
+    readonly source: "host.rs";
+    readonly refusal: "ctx.secrets.set: this function has not declared the `secrets.write` capability (add it to oxy-app.json to permit writes)";
+  };
+  readonly emailSend: {
+    readonly source: "host.rs";
+    readonly refusal: 'EmailCapabilityMissing: this function has not declared the `email.send` capability (add "email": { "send": true } to its oxy-app.json entry)';
+  };
+  readonly orgPeople: {
+    readonly source: "host.rs";
+    readonly refusal: 'OrgCapabilityMissing: this function has not declared the `org.read` capability (add "org": { "read": true } to its oxy-app.json entry)';
+  };
+  readonly orgMember: {
+    readonly source: "host.rs";
+    readonly refusal: 'OrgCapabilityMissing: this function has not declared the `org.read` capability (add "org": { "read": true } to its oxy-app.json entry) — ctx.org.{member}';
+  };
+  readonly storageWrite: {
+    readonly source: "host.rs";
+    readonly refusal: 'StorageCapabilityMissing: this function has not declared the `storage.write` capability (add "storage": { "write": true } to its oxy-app.json entry)';
+  };
+  readonly storageRead: {
+    readonly source: "host.rs";
+    readonly refusal: 'StorageCapabilityMissing: this function has not declared the `storage.read` capability (add "storage": { "read": true } to its oxy-app.json entry)';
+  };
+  readonly oltp: {
+    readonly source: "host.rs";
+    readonly refusal: 'OltpCapabilityMissing: this function has not declared the `oltp` capability (add "oltp": { "enabled": true } to its oxy-app.json entry). The schema it writes is derived from the app\'s own slug — the manifest only enables access.';
+  };
+  readonly airhouse: {
+    readonly source: "host/airhouse_ops.rs";
+    readonly refusal: 'AirhouseCapabilityMissing: this function has not declared the `airhouse` capability (add "airhouse": { "enabled": true } to its oxy-app.json entry). The schema it writes is derived from the app\'s own slug — the manifest only enables access.';
+  };
+  readonly destinationNotDeclared: {
+    readonly source: "host.rs";
+    readonly refusal: "database '{database}' is not in this function's `destinations` allowlist (declare it in oxy-app.json to permit writes)";
+  };
+  readonly databaseNotConfigured: {
+    readonly source: "host.rs";
+    readonly refusal: "database '{database}' is not configured for this project";
+  };
+  readonly managedOltpWrite: {
+    readonly source: "host/destinations.rs";
+    readonly refusal: "database '{database}' is the org's OLTP store, which this surface reaches as the read-only analyst — write this app's own records with ctx.oltp";
+  };
+  readonly customerWarehouseWrite: {
+    readonly source: "host/destinations.rs";
+    readonly refusal: 'database \'{database}\' is a customer warehouse, and customer warehouses are read-only to apps. Facts this app records belong in Airhouse (ctx.airhouse); records it edits belong in ctx.oltp. If this write has to stay, say why on the function in oxy-app.json: "customerWarehouseWrites": { "{database}": "<reason>" }';
+  };
+  readonly customerWarehouseTransaction: {
+    readonly source: "host/destinations.rs";
+    readonly refusal: ". A ctx.tx transaction counts as a write even when it only reads — read with ctx.warehouse.query instead";
+  };
+  readonly upsertUnsupported: {
+    readonly source: "upsert_support.rs";
+    readonly refusal: "warehouse.upsert is not supported on {dialect}: it compiles to `INSERT … ON CONFLICT … DO UPDATE`, which only Postgres and DuckDB parse. Use warehouse.insert, or warehouse.exec with this warehouse's own upsert statement.";
+  };
+  readonly transactionOpen: {
+    readonly source: "host.rs";
+    readonly refusal: "could not open a transaction on '{database}': {e}";
+  };
+  readonly transactionUnsupported: {
+    readonly source: "transaction.rs";
+    readonly refusal: "{backend} does not support multi-statement transactions — ctx.tx() requires a Postgres-backed database (`type: postgres`). Use ctx.warehouse.{insert,exec,upsert} for single-statement writes.";
+  };
+  readonly transactionsOpen: {
+    readonly source: "tx.rs";
+    readonly refusal: "this invocation already has {MAX_OPEN} transactions open. Commit or roll one back before opening another.";
+  };
+  readonly transactionFinished: {
+    readonly source: "runtime.rs";
+    readonly refusal: "{label}: this transaction is already finished — {what} was called after the callback returned";
+  };
+  readonly transactionFnNotFunction: {
+    readonly source: "runtime.rs";
+    readonly refusal: "{signature}: fn must be a function";
+  };
+  readonly btoaBytes: {
+    readonly source: "runtime.rs";
+    readonly refusal: "btoa: expected a string. For bytes use bytesToBase64() from @oxy-hq/sdk";
+  };
+  readonly atobPadding: {
+    readonly source: "runtime.rs";
+    readonly refusal: "atob: '=' may only appear as trailing padding";
+  };
+  readonly atobLength: {
+    readonly source: "runtime.rs";
+    readonly refusal: "atob: invalid base64 length";
+  };
+  readonly fetchInvalidUrl: {
+    readonly source: "host.rs";
+    readonly refusal: "invalid url: {e}";
+  };
+  readonly fetchBlocked: {
+    readonly source: "host.rs";
+    readonly refusal: "fetch to '{url}' blocked by SSRF allowlist";
+  };
+  readonly fetchInvalidHeaderName: {
+    readonly source: "host.rs";
+    readonly refusal: "InvalidFetchHeader: `{k}` is not a header name";
+  };
+  readonly fetchInvalidHeaderValue: {
+    readonly source: "host.rs";
+    readonly refusal: "InvalidFetchHeader: the value of `{k}` is not a header value";
+  };
+  readonly fetchTooLarge: {
+    readonly source: "host.rs";
+    readonly refusal: "response too large ({len} bytes > {max_bytes} cap)";
+  };
+  readonly slugCannotBackASchema: {
+    readonly source: "host.rs";
+    readonly refusal: string;
+  };
+  readonly oltpParamsNotArray: {
+    readonly source: "host.rs";
+    readonly refusal: "`params` must be an array of values. Pass positional arguments for $1, $2, … — e.g. [name, partySize].";
+  };
+  readonly noDefaultDatabase: {
+    readonly source: "host.rs";
+    readonly refusal: "this project has no databases configured";
+  };
+  readonly oltpUnsupportedColumn: {
+    readonly source: "postgres_tx/convert.rs";
+    readonly refusal: "result column `{name}` has Postgres type `{ty}`, which cannot be returned directly. Cast it to text in the SELECT list and parse it in your function — cast the whole expression, not the output name (`avg(qty)::text`, `amount::text`). Note `avg`/`sum` over any numeric type, and a bare decimal literal, are all `numeric`. (Supported as-is: bool, int2/4/8, float4/8, text/varchar/char/name, json/jsonb, uuid, timestamptz/timestamp, date, time.)";
+  };
+};
+/** One capability gate: the `FunctionCapabilities` field and the ops it refuses. */
+interface Gate {
+  /** The `FunctionCapabilities` field in `host.rs`. */
+  readonly hostField: string;
+  /** The capability as the manifest and the refusal name it: `storage.write`. */
+  readonly manifest: string;
+  /** The host ops refused while the manifest lacks it. */
+  readonly ops: readonly HostOp[];
+}
+/**
+ * Every gate in `FunctionCapabilities`, in the struct's order. `storage_read`
+ * and `storage_write` list `check_storage_capability`'s arms (`copy` needs
+ * both); `customer_warehouse_writes` is decided per database by
+ * `destination_write_policy`, after the `destinations` allowlist.
+ * `storage_retention` and `fetch_max_bytes` are fields of the struct and
+ * deliberately absent: they shape an allowed call, they never refuse one.
+ */
+declare const GATES: readonly [{
+  readonly hostField: "secrets_write";
+  readonly manifest: "secrets.write";
+  readonly ops: readonly ["secrets.set"];
+}, {
+  readonly hostField: "email_send";
+  readonly manifest: "email.send";
+  readonly ops: readonly ["email.send"];
+}, {
+  readonly hostField: "org_read";
+  readonly manifest: "org.read";
+  readonly ops: readonly ["org.people", "org.places", "org.assignments"];
+}, {
+  readonly hostField: "storage_read";
+  readonly manifest: "storage.read";
+  readonly ops: readonly ["storage.getDownloadUrl", "storage.get", "storage.head", "storage.list", "storage.copy"];
+}, {
+  readonly hostField: "storage_write";
+  readonly manifest: "storage.write";
+  readonly ops: readonly ["storage.getUploadUrl", "storage.put", "storage.delete", "storage.copy"];
+}, {
+  readonly hostField: "oltp";
+  readonly manifest: "oltp.enabled";
+  readonly ops: readonly ["oltp.query", "oltp.exec", "tx.begin_oltp"];
+}, {
+  readonly hostField: "airhouse";
+  readonly manifest: "airhouse.enabled";
+  readonly ops: readonly ["airhouse.query", "airhouse.exec", "airhouse.append"];
+}, {
+  readonly hostField: "customer_warehouse_writes";
+  readonly manifest: "customerWarehouseWrites";
+  readonly ops: readonly ["warehouse.insert", "warehouse.exec", "warehouse.upsert", "tx.begin"];
+}];
+/**
+ * The globals the isolate does not define, as `oxyc`'s `isolate-global` lint
+ * names them (`ABSENT_GLOBALS` in `sdk/cli/src/publish/function-lint.ts`).
+ * `member` narrows an entry to `<name>.<member>`; an empty `member` is the
+ * whole of `process.*`. The isolate's bootstrap defines `Response`, `btoa`,
+ * `atob`, `console` and `__buildCtx` and nothing else (`runtime.rs`), so it has
+ * no `crypto` global at all; the lint singles out `subtle` because that is what
+ * an author reaches for, and `run()` removes the whole global as production
+ * does.
+ */
+declare const ABSENT_GLOBALS: readonly [{
+  readonly name: "Buffer";
+}, {
+  readonly name: "TextEncoder";
+}, {
+  readonly name: "TextDecoder";
+}, {
+  readonly name: "Blob";
+}, {
+  readonly name: "File";
+}, {
+  readonly name: "FormData";
+}, {
+  readonly name: "crypto";
+  readonly member: "subtle";
+}, {
+  readonly name: "process";
+  readonly member: "";
+}];
+/**
+ * `is_safe_outbound` in `host.rs`, the first-layer check every `ctx.fetch`
+ * URL meets before anything is sent: the scheme, the host names refused by
+ * name, and the suffixes an internal name ends with. The IP rules (loopback,
+ * unspecified, private, link-local, broadcast, documentation, v4-mapped and
+ * embedded v6) are code, in `fetch-rules.ts`. What no unit test can reproduce
+ * is the second layer — a public name that RESOLVES to a private address is
+ * caught at connect time by `PublicOnlyDnsResolver` — so the context does not
+ * pretend to.
+ */
+declare const FETCH_RULES: {
+  readonly scheme: "https";
+  readonly literalHosts: readonly ["localhost", "ip6-localhost", "ip6-loopback"];
+  readonly internalSuffixes: readonly [".internal", ".local", ".localdomain", ".svc", ".cluster.local"];
+};
+/** `FETCH_MAX_BYTES` in `host.rs`: the default `ctx.fetch` response ceiling. */
+declare const FETCH_MAX_BYTES: number;
+/** `MAX_OPEN` in `tx.rs`: transactions one invocation may hold open at once. */
+declare const MAX_OPEN_TRANSACTIONS = 4;
+/**
+ * How each dialect names itself in a refusal — `SqlDialect::as_str` in the
+ * connector crate, which `upsert_support::check` and `transaction::unsupported`
+ * format in. Only Postgres, DuckDB and SQLite parse `ON CONFLICT`
+ * (`parses_on_conflict`), and only the Postgres connector opens a transaction.
+ */
+declare const DIALECTS: {
+  readonly clickhouse: {
+    readonly name: "ClickHouse";
+    readonly parsesOnConflict: false;
+    readonly opensTransactions: false;
+  };
+  readonly postgres: {
+    readonly name: "PostgreSQL";
+    readonly parsesOnConflict: true;
+    readonly opensTransactions: true;
+  };
+  readonly duckdb: {
+    readonly name: "DuckDB";
+    readonly parsesOnConflict: true;
+    readonly opensTransactions: false;
+  };
+};
+type Dialect = keyof typeof DIALECTS;
+//#endregion
+//#region src/testing/zoo.d.ts
+type ZooEngine = "clickhouse" | "postgres" | "duckdb";
+/** Which plane read the value: `ctx.warehouse` / `ctx.query`, or `ctx.oltp` / `ctx.tx`. */
+type ZooPlane = "warehouse" | "oltp";
+interface ZooCase {
+  key: string;
+  native_type: string;
+  class: string;
+  value_sql: string;
+  expect: {
+    warehouse: unknown;
+    oltp?: unknown;
+  };
+}
+interface ShapeZoo {
+  version: number;
+  engines: Record<ZooEngine, {
+    cases: ZooCase[];
+  }>;
+}
+/** Where a row value came from — the honesty flag on every read. */
+type RowSource = "zoo" | "typed" | "author";
+/** A value a read would REFUSE rather than return: `expect.oltp.$error`. */
+declare class ZooRefusal {
+  readonly column: string;
+  readonly nativeType: string;
+  readonly detail: string;
+  constructor(column: string, nativeType: string, detail: string);
+  /** The host's full sentence for it, from the contract. */
+  message(): string;
+}
+declare const ZOO: ShapeZoo;
+/** The zoo table's name, from the fixture's digest — the canary's `zooTableName`. */
+declare function zooTableName(sha256Hex?: string): string;
+/** `c001`, `c002`, … — the zoo column for case `index`. */
+declare function zooColumn(index: number): string;
+/** What a read of case `c` on `plane` returns — or refuses. */
+declare function expectation(c: ZooCase, plane: ZooPlane, column: string): unknown | ZooRefusal;
+/** Every case of `engine` for `nativeType`, as written in the zoo. */
+declare function casesFor(engine: ZooEngine, nativeType: string): ZooCase[];
+/** The native types the zoo pins for `engine`, for a declaration error to list. */
+declare function knownTypes(engine: ZooEngine): string[];
+/**
+ * Render one SQL-side value of a typed column through the zoo.
+ *
+ * - The value IS a case's `value_sql` for this type → that case's expectation
+ *   (`source: "zoo"`).
+ * - `NULL` → `null`.
+ * - Otherwise the `plain` case's SHAPE decides: a number-shaped type parses the
+ *   literal, except that an integer outside `i64` becomes its exact digits as a
+ *   string where the zoo pins that (`precision_gt_18` expecting a string) — the
+ *   host reads an overflowing column as `u64` rendered to text; a string-shaped
+ *   type unquotes; a boolean-shaped type reads `true`/`false`/`1`/`0`; a JSON
+ *   shape parses (`source: "typed"`).
+ */
+declare function renderValue(engine: ZooEngine, nativeType: string, valueSql: string, plane: ZooPlane, column: string): {
+  value: unknown | ZooRefusal;
+  source: RowSource;
+};
+//#endregion
+//#region src/testing/stores.d.ts
+/** A read's rows, and the weakest source among them. */
+interface ReadResult {
+  rows: OxyFunctionRow[];
+  source: RowSource | null;
+}
+/**
+ * One SQL-evaluating store: a warehouse database, the OLTP schema or the
+ * Airhouse schema. `engine` picks which zoo cases render typed columns;
+ * `plane` picks which expectation a case yields.
+ */
+declare class TableStore {
+  readonly engine: ZooEngine;
+  readonly plane: ZooPlane;
+  /** For a schema-qualified name to resolve to a bare one: the schema, or `null`. */
+  readonly schema: string | null;
+  private readonly tables;
+  constructor(engine: ZooEngine, plane: ZooPlane,
+  /** For a schema-qualified name to resolve to a bare one: the schema, or `null`. */
+  schema?: string | null);
+  /** The zoo table for this engine: column `cNNN` is case NNN's expectation. */
+  zoo(): this;
+  /**
+   * Declare a typed table: `{ id: "UInt64", amount: "Decimal(18, 4)" }`. A
+   * type the zoo has no case for is an error here, not a guess at read time.
+   */
+  table(name: string, columns: Record<string, string>): TypedTable;
+  /** Seed rows as JS values, unrendered — every read of them is `source: "author"`. */
+  raw(name: string, rows: OxyFunctionRow[]): this;
+  /** Every row of `name` as a function would read it; a `$error` cell is its refusal text. */
+  rows(name: string): OxyFunctionRow[];
+  /** The names of every table declared, seeded or created. */
+  tableNames(): string[];
+  /** Whether `name` exists. */
+  has(name: string): boolean;
+  /** Evaluate `sql` as a read: rows, or a throw. */
+  query(sql: string, params?: readonly unknown[]): ReadResult;
+  /** Evaluate `sql` as a statement: rows affected, or a throw. */
+  exec(sql: string, params?: readonly unknown[]): number;
+  /** Append JS rows to `name` (`ctx.warehouse.insert`, `ctx.airhouse.append`): unrendered. */
+  append(name: string, rows: OxyFunctionRow[]): number;
+  /** Snapshot every table, for `ctx.tx` rollback. */
+  snapshot(): () => void;
+  private key;
+  private lookup;
+  private require;
+  private create;
+  private insert;
+  private matching;
+  private select;
+  private remove;
+  private update;
+}
+/** A declared typed table: insert SQL-side values, rendered through the zoo. */
+declare class TypedTable {
+  private readonly store;
+  readonly name: string;
+  constructor(store: TableStore, name: string);
+  /** Insert rows of SQL-side values (`{ id: "42", at: "'2024-03-10 12:34:56'" }`). */
+  insert(rows: Record<string, string>[]): this;
+}
+/** One object in the app's storage silo, body as base64. */
+interface StoredObject {
+  key: string;
+  body: string;
+  contentType: string | null;
+  size: number;
+  lastModified: string;
+}
+/** What `ctx.fetch` should answer for a URL: a result, or a function of the call. */
+type FetchAnswer = {
+  status?: number;
+  body?: string;
+  encoding?: "utf8" | "base64";
+} | ((url: string, init: RequestInit & {
+  encoding?: "utf8" | "base64";
+}) => {
+  status?: number;
+  body?: string;
+  encoding?: "utf8" | "base64";
+});
+/** The `ctx.fetch` side: answers by URL, and what was received. */
+declare class FetchStore {
+  readonly received: {
+    url: string;
+    init: RequestInit & {
+      encoding?: "utf8" | "base64";
+    };
+  }[];
+  private readonly answers;
+  /** Answer every URL equal to `match` (or matching the RegExp) with `answer`. */
+  on(match: string | RegExp, answer: FetchAnswer): this;
+  answerFor(url: string): FetchAnswer | undefined;
+}
+//#endregion
+//#region src/testing/context.d.ts
+/** One database the project configures, as the context needs to know it. */
+interface TestDatabase {
+  dialect: Dialect;
+  /**
+   * `destination_kind`'s mapping (`host/destinations.rs`): `airhouse` /
+   * `airhouse_managed` may be written; `postgres_managed` is the org's OLTP
+   * store, refused; anything else is a customer warehouse, read-only without a
+   * `customerWarehouseWrites` reason. An unknown kind fails closed the same way.
+   */
+  kind: "airhouse" | "airhouse_managed" | "postgres_managed" | "customer";
+}
+interface TestContextOptions {
+  /** The `functions.<name>` entry whose capabilities gate the context. */
+  function: string;
+  /** The project's databases by name; `ctx.query` reaches `defaultDatabase` or the first. */
+  databases?: Record<string, TestDatabase>;
+  defaultDatabase?: string;
+  /** `ctx.env`. */
+  env?: Record<string, string>;
+  /** `ctx.user`, over a default org member. */
+  user?: Partial<OxyFunctionUser>;
+}
+/** One host op the function made, as the context recorded it. */
+interface HostCall {
+  op: HostOp;
+  /** The op's payload as `__buildCtx` packs it: `{ database, table, rows }`, `{ sql, params }`, … */
+  args: Record<string, unknown>;
+  /** `refused`: a `HostError` the context threw; `threw`: any other error, an override's included. */
+  outcome: "ok" | "refused" | "threw";
+  /** The full error message — `"<surface>: <host message>"` for a refusal. */
+  message?: string;
+  /** What the host op replied, on `ok`. */
+  result?: unknown;
+  /** For a read answered from a store: the weakest source among its rows. */
+  source?: RowSource;
+}
+/** The host op behind a ctx member: answers with what the host would reply. */
+type HostOpImpl = (args: Record<string, unknown>) => Promise<unknown> | unknown;
+type Person = {
+  id: string;
+  name: string;
+  role: string | null;
+  kind: "member" | "frontline";
+};
+/** The stores, for a test to seed and inspect. */
+interface TestState {
+  warehouse(database: string): TableStore;
+  readonly oltp: TableStore;
+  readonly airhouse: TableStore;
+  readonly storage: Map<string, StoredObject>;
+  readonly secrets: Map<string, string>;
+  readonly emails: Record<string, unknown>[];
+  readonly fetch: FetchStore;
+  readonly org: {
+    people: Person[];
+    places: OxyOrgPlace[];
+    assignments: OxyOrgAssignment[];
+  };
+  readonly semantic: {
+    on(answer: (spec: Record<string, unknown>) => unknown): void;
+  };
+  readonly airway: {
+    runs: {
+      pipelineRef: string;
+      variables: unknown;
+    }[];
+  };
+}
+interface TestContext {
+  ctx: OxyFunctionContext;
+  /** Every host op made, in order. */
+  readonly calls: readonly HostCall[];
+  /** The de-duplicated first-call order of op names. */
+  ops(): HostOp[];
+  callsTo(op: HostOp): HostCall[];
+  /** Replace one host op for this context; still recorded. */
+  override(op: HostOp, impl: HostOpImpl): void;
+  /** Evaluate `fn` with the isolate's absent globals absent (`run.ts`). */
+  run<T>(fn: () => Promise<T> | T): Promise<T>;
+  readonly state: TestState;
+  readonly gates: FunctionGates;
+}
+declare function createTestContext(manifest: ManifestLike, options: TestContextOptions): TestContext;
+//#endregion
+//#region src/testing/fetch-rules.d.ts
+/** The host's verdict on a URL: allowed, or refused before sending. */
+declare function isSafeOutbound(url: URL): boolean;
+//#endregion
+//#region src/testing/host-error.d.ts
+/** The `name` the runtime gives every refusal it unwraps. */
+declare const HOST_ERROR_NAME = "HostError";
+/**
+ * Render a refusal template: every `{placeholder}` replaced by `vars[name]`.
+ * A placeholder the caller did not supply is a bug in the context, not in the
+ * app under test, so it throws rather than leaking `{database}` into a message
+ * a test might then match on.
+ */
+declare function render(template: RefusalTemplate, vars?: Record<string, string | number>): string;
+/**
+ * The error a function sees when the host refuses: `name` `"HostError"`,
+ * message `"<surface>: <message>"`.
+ */
+declare function hostError(surface: string, message: string): Error;
+/** `hostError` over a rendered template. */
+declare function refuse(surface: string, template: RefusalTemplate, vars?: Record<string, string | number>): Error;
+/** Whether `err` is a refusal the context (or the runtime) threw. */
+declare function isHostError(err: unknown): err is Error;
+/**
+ * An error in the context's OWN words — never the host's. Thrown where the
+ * context cannot model what the host would do (an unrecognised statement, an
+ * unregistered `fetch` answer) and says so, rather than answering something
+ * production would not. Its `name` is `"TestContextError"` so a test can never
+ * mistake it for a refusal.
+ */
+declare function contextError(message: string): Error;
+//#endregion
+//#region src/testing/run.d.ts
+/** `globalThis.btoa` as the isolate defines it: strings only, Latin1 only. */
+declare function isolateBtoa(input: unknown): string;
+/** `globalThis.atob` as the isolate defines it: WHATWG forgiving-base64. */
+declare function isolateAtob(input: unknown): string;
+/**
+ * Evaluate `fn` with every `ABSENT_GLOBALS` entry removed from `globalThis` and
+ * `btoa` / `atob` replaced by the isolate's, restoring all of them afterwards
+ * — whether `fn` resolves or throws.
+ */
+declare function runWithoutIsolateGlobals<T>(fn: () => Promise<T> | T): Promise<T>;
+//#endregion
+//#region src/testing/shape-zoo-sha256.d.ts
+declare const ZOO_SHA256 = "04f75f9054a46e521d8787d65f5d214440d041860971c77e66edc7bfbaf8d16a";
+//#endregion
+export { ABSENT_GLOBALS, DIALECTS, type Dialect, FETCH_MAX_BYTES, FETCH_RULES, type FetchAnswer, FetchStore, type FunctionGates, GATES, type Gate, HOST_ERROR_NAME, HOST_OPS, type HostCall, type HostOp, type HostOpImpl, MAX_OPEN_TRANSACTIONS, type ManifestLike, REFUSALS, type ReadResult, type RefusalTemplate, type RowSource, SURFACES, type ShapeZoo, type StoredObject, TableStore, type TestContext, type TestContextOptions, type TestDatabase, type TestState, TypedTable, ZOO, ZOO_SHA256, type ZooCase, type ZooEngine, type ZooPlane, ZooRefusal, casesFor, contextError, createTestContext, expectation, hostError, isHostError, isSafeOutbound, isolateAtob, isolateBtoa, knownTypes, readGates, refuse, render, renderValue, runWithoutIsolateGlobals, writerSchema, zooColumn, zooTableName };
+//# sourceMappingURL=testing.d.mts.map

package/dist/testing.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"testing.d.mts","names":[],"sources":["../src/testing/gates.ts","../src/testing/host-contract.ts","../src/testing/zoo.ts","../src/testing/stores.ts","../src/testing/context.ts","../src/testing/fetch-rules.ts","../src/testing/host-error.ts","../src/testing/run.ts","../src/testing/shape-zoo-sha256.ts"],"mappings":"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"}