@volter/world-core 2.0.36 → 3.0.0

package/dist/src/managed-database.js

@@ -0,0 +1,283 @@
+// THE WORLD'S MANAGED DATABASE, as a pack reaches it (architecture.md, "The engine slot" and managed infrastructure): a
+// vendor whose data plane is a server in front of Postgres (Supabase's PostgREST, Storage and Auth; a Neon or a
+// PlanetScale) serves it over the World's own Postgres, whose URL the runtime hands the pack (the descriptor's
+// `managedDatabase`: `serve --database <url>`, or the colocated host's `database` option). A protocol-3 handler reaches
+// it as `ctx.engine`; a pack's own server in front of it (a PostgREST) through `managedDatabase(url)`. Its terms:
+//
+// - Nothing here reads the environment, and the tree references none of the rows it writes.
+// - Each batch is ONE transaction sent as ONE extended-protocol pipeline ending in ONE Sync: `BEGIN`, the role
+//   (`SET LOCAL ROLE`), the transaction-local settings (`set_config(…, true)`), the statements and `COMMIT`, every value a
+//   bind parameter. The PGlite host runs a connection's messages up to its Sync under one lock and lets another
+//   connection's read into a session idle inside a transaction; a batch that never sits idle inside its transaction lets
+//   nobody in, so its role and settings reach no other connection.
+// - The role, which Postgres takes only as SQL text, is quoted as an identifier; which roles a caller may take is the
+//   pack's rule (Supabase's three API roles), checked before a batch is made.
+// - A batch that fails leaves its transaction aborted (the backend skips to the Sync); it is ended with `ROLLBACK` before
+//   the connection is released, and a connection that cannot be rolled back is destroyed, never reused.
+//
+// The Postgres driver is node-postgres (`pg`), loaded the first time a database is bound and installed by the package that
+// declares a managed database (its package.json): the kernel's dependencies are zod and ws alone (architecture B1), and a
+// browser bundle imports the kernel without a database. A host may register another (`useDatabaseDriver`).
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+/** A Postgres error as the backend reported it (SQLSTATE and its fields), what a vendor's server passes through. */
+export class EngineDatabaseError extends Error {
+    code;
+    detail;
+    hint;
+    constructor(message, fields) {
+        super(message);
+        this.name = 'EngineDatabaseError';
+        this.code = fields.code ?? 'XX000';
+        this.detail = fields.detail ?? null;
+        this.hint = fields.hint ?? null;
+    }
+}
+/** The World's database cannot be reached: none is bound, or it does not answer. */
+export class EngineUnavailableError extends Error {
+    constructor(message) { super(message); this.name = 'EngineUnavailableError'; }
+}
+/** The transaction-local setting every batch a handler makes carries: the World clock at the call (ctx.occurredAt). */
+export const WORLD_CLOCK_SETTING = 'volter.world_clock';
+/** The World clock inside the database, for the schemas a vendor lays (its migrations stamp rows with Postgres's
+ *  `now()`, which reads the wall clock): `volter.now()`, the World clock the batch set or the wall clock where none is
+ *  set, and every column default in `schemas` that reads `now()` or `CURRENT_TIMESTAMP` (alone or inside an expression,
+ *  GoTrue's `timezone('utc', now())`) rewritten to read it. Run after the schemas are laid; running it again changes
+ *  nothing. A trigger or function that calls `now()` itself is the pack's to redefine. */
+export function worldClockSql(schemas) {
+    const list = schemas.map((s) => `'${s.replace(/'/g, "''")}'`).join(', ');
+    return `CREATE SCHEMA IF NOT EXISTS volter;
+CREATE OR REPLACE FUNCTION volter.now() RETURNS timestamptz LANGUAGE sql STABLE AS $fn$
+  SELECT coalesce(nullif(current_setting('${WORLD_CLOCK_SETTING}', true), '')::timestamptz, pg_catalog.now())
+$fn$;
+GRANT USAGE ON SCHEMA volter TO PUBLIC;
+GRANT EXECUTE ON FUNCTION volter.now() TO PUBLIC;
+DO $do$
+DECLARE d record; rewritten text;
+BEGIN
+  FOR d IN
+    SELECT n.nspname AS schema, c.relname AS tbl, a.attname AS col, pg_get_expr(ad.adbin, ad.adrelid) AS expr
+    FROM pg_attrdef ad
+    JOIN pg_class c ON c.oid = ad.adrelid
+    JOIN pg_namespace n ON n.oid = c.relnamespace
+    JOIN pg_attribute a ON a.attrelid = ad.adrelid AND a.attnum = ad.adnum
+    WHERE n.nspname IN (${list}) AND c.relkind IN ('r', 'p')
+      AND pg_get_expr(ad.adbin, ad.adrelid) ~* '(^|[^.[:alnum:]_])(now\\(\\)|current_timestamp)'
+  LOOP
+    rewritten := regexp_replace(d.expr, '(^|[^.[:alnum:]_])(now\\(\\)|current_timestamp)', '\\1volter.now()', 'gi');
+    EXECUTE format('ALTER TABLE %I.%I ALTER COLUMN %I SET DEFAULT %s', d.schema, d.tbl, d.col, rewritten);
+  END LOOP;
+END
+$do$;`;
+}
+/** Quote an identifier the way Postgres's quote_ident does for a name that needs it. */
+export function quoteIdent(name) {
+    return `"${name.replace(/"/g, '""')}"`;
+}
+/** pg's Submittable (the extension point pg-cursor and pg-query-stream use): the client hands it the connection once
+ *  it is its turn, it writes every statement's Parse/Bind/Describe/Execute and ONE Sync, and the client hands it each
+ *  backend message until ReadyForQuery. */
+class Pipeline {
+    statements;
+    done;
+    results = [];
+    current = null;
+    error = null;
+    settled = false;
+    constructor(statements, done) {
+        this.statements = statements;
+        this.done = done;
+    }
+    submit(connection) {
+        for (const statement of this.statements) {
+            connection.parse({ text: statement.text, types: [] });
+            connection.bind({ values: statement.values ?? [] });
+            connection.describe({ type: 'P' });
+            connection.execute({ rows: 0 });
+        }
+        connection.sync();
+    }
+    handleRowDescription(message) {
+        this.current = { fields: message.fields.map((field) => field.name), rows: [] };
+    }
+    handleDataRow(message) {
+        (this.current ??= { fields: [], rows: [] }).rows.push(message.fields);
+    }
+    handleCommandComplete(message) {
+        this.results.push({ ...(this.current ?? { fields: [], rows: [] }), command: String(message.text ?? '') });
+        this.current = null;
+    }
+    handleEmptyQuery() {
+        this.results.push({ fields: [], rows: [], command: '' });
+    }
+    handlePortalSuspended() { }
+    handleCopyInResponse(connection) { connection.sendCopyFail('COPY FROM STDIN is not served by a managed database batch'); }
+    handleCopyData() { }
+    handleError(error) {
+        // An ErrorResponse (the backend's, with a SQLSTATE) or a failed connection. pg ends the submittable's turn here:
+        // it drops it as the active query, so the ReadyForQuery the backend sends after skipping to the Sync goes to no
+        // one, and the next query this client is given (the ROLLBACK) is sent once that ReadyForQuery arrives.
+        this.error ??= error;
+        this.finish();
+    }
+    handleReadyForQuery() { this.finish(); }
+    finish() {
+        if (this.settled)
+            return;
+        this.settled = true;
+        this.done(this.error, this.results);
+    }
+}
+function asDatabaseError(error) {
+    const fields = error;
+    if (fields.severity === undefined)
+        return new EngineUnavailableError(`the World's Postgres failed: ${error.message}`);
+    return new EngineDatabaseError(error.message, fields);
+}
+let driver;
+/** A Postgres driver a host registers in place of node-postgres. */
+export function useDatabaseDriver(given) {
+    driver = given;
+}
+/** The driver: the registered one, else node-postgres, loaded on first use (a name the bundler does not resolve). */
+async function loadDriver() {
+    if (driver !== undefined)
+        return driver;
+    const name = 'pg';
+    try {
+        const mod = (await import(__rewriteRelativeImportExtension(name)));
+        driver = mod.default ?? mod;
+    }
+    catch (error) {
+        throw new EngineUnavailableError(`no Postgres driver: node-postgres (pg) is not installed beside the pack that declares a managed database (${error.message})`);
+    }
+    return driver;
+}
+const pools = new Map(); // cache: one pool per bound database URL — the connections this process holds to the World's Postgres, never state
+async function poolFor(url) {
+    let pool = pools.get(url);
+    if (pool === undefined) {
+        const { Pool } = await loadDriver();
+        // another request may have made it while the driver loaded
+        const made = pools.get(url);
+        if (made !== undefined)
+            return made;
+        // a few connections: the PGlite host serializes them anyway, and a container Postgres needs no more for a twin
+        pool = new Pool({ connectionString: url, max: 4, idleTimeoutMillis: 10_000, connectionTimeoutMillis: 10_000 });
+        // an idle connection that the database ends (a World's Postgres restarting) is dropped from the pool, not thrown
+        pool.on('error', () => { });
+        pools.set(url, pool);
+    }
+    return pool;
+}
+async function checkout(url) {
+    const pool = await poolFor(url);
+    try {
+        return await pool.connect();
+    }
+    catch (error) {
+        throw new EngineUnavailableError(`the World's Postgres is not answering: ${error.message}`);
+    }
+}
+function pipeline(client, statements) {
+    return new Promise((resolve) => {
+        client.query(new Pipeline(statements, (error, results) => resolve({ error, results })));
+    });
+}
+/** Run one transaction as one pipeline with one Sync; on failure, ROLLBACK before the connection goes back. */
+async function transaction(url, statements, lead) {
+    const client = await checkout(url);
+    let broken;
+    try {
+        const { error, results } = await pipeline(client, statements);
+        if (error !== null) {
+            if (error.severity !== undefined) {
+                try {
+                    await client.query('ROLLBACK');
+                }
+                catch (rollback) {
+                    broken = rollback;
+                }
+            }
+            else
+                broken = error;
+            throw asDatabaseError(error);
+        }
+        // the answer is the batch's own statements: not BEGIN, the role, the settings, or its end
+        return results.slice(lead, statements.length - 1);
+    }
+    finally {
+        client.release(broken);
+    }
+}
+function settingsStatement(settings) {
+    const names = Object.keys(settings);
+    if (names.length === 0)
+        return null;
+    const values = [];
+    const calls = names.map((name) => {
+        values.push(name, settings[name]);
+        return `set_config($${values.length - 1}, $${values.length}, true)`;
+    });
+    return { text: `SELECT ${calls.join(', ')}`, values };
+}
+/** The World's Postgres at `url` (the runtime's binding, never the environment); with `readOnly`, every transaction is
+ *  READ ONLY whatever the batch asks (a read-only twin or request: Postgres itself refuses a write, 25006); with `clock`,
+ *  every batch carries the World clock as `volter.world_clock`. */
+export function managedDatabase(url, options = {}) {
+    return {
+        bound: true,
+        async batch(batch) {
+            // the World clock at the call, which volter.now() and the defaults worldClockSql rewrote read
+            const set = settingsStatement({ ...(options.clock !== undefined ? { [WORLD_CLOCK_SETTING]: options.clock } : {}), ...(batch.settings ?? {}) });
+            const head = [
+                { text: batch.readOnly || options.readOnly ? 'BEGIN READ ONLY' : 'BEGIN' },
+                ...(batch.role === undefined ? [] : [{ text: `SET LOCAL ROLE ${quoteIdent(batch.role)}` }]),
+                ...(set === null ? [] : [set]),
+            ];
+            return transaction(url, [...head, ...batch.statements, { text: batch.rollback ? 'ROLLBACK' : 'COMMIT' }], head.length);
+        },
+        async script(text) {
+            const client = await checkout(url);
+            let broken;
+            try {
+                await client.query(text);
+            }
+            catch (error) {
+                if (error.severity === undefined)
+                    broken = error;
+                else {
+                    try {
+                        await client.query('ROLLBACK');
+                    }
+                    catch (rollback) {
+                        broken = rollback;
+                    }
+                }
+                throw asDatabaseError(error);
+            }
+            finally {
+                client.release(broken);
+            }
+        },
+    };
+}
+/** A handler's database when the World binds none: every use is the refusal naming what to add. */
+export function unboundDatabase(service) {
+    const refuse = () => {
+        throw new EngineUnavailableError(`This World binds no managed Postgres to the ${service} twin, so what it serves over one is refused, not served: add a postgres service to the World's managed infrastructure (architecture: managed infrastructure)`);
+    };
+    return { bound: false, batch: async () => refuse(), script: async () => refuse() };
+}
+/** Close every connection this process holds (a test's teardown; a served twin's connections end with it). */
+export async function closeManagedDatabases() {
+    const held = [...pools.values()];
+    pools.clear();
+    await Promise.all(held.map((pool) => pool.end().catch(() => { })));
+}

package/dist/src/multipart.d.ts

@@ -0,0 +1,11 @@
+/** One part: its field name (possibly empty), its filename when it is a file, its media type as sent, its bytes. */
+export type MultipartPart = {
+    name: string;
+    filename: string | null;
+    type: string | null;
+    body: Uint8Array;
+};
+/** The boundary a `multipart/form-data` content type names, or null (not multipart, or no boundary). */
+export declare function multipartBoundary(contentType: string | null | undefined): string | null;
+/** The parts of a body delimited by `boundary`, in order; a malformed tail ends the reading. */
+export declare function multipartParts(bytes: Uint8Array, boundary: string): MultipartPart[];

package/dist/src/multipart.js

@@ -0,0 +1,51 @@
+// A multipart/form-data body's parts, read from its bytes (RFC 7578): the one reading every pack's uploads go through.
+// A runtime's own form parser is not used: Bun's drops a part whose field name is empty, which a browser's or
+// supabase-js's Blob upload sends. Dependency-free and side-effect free (a browser bundle imports it).
+/** The boundary a `multipart/form-data` content type names, or null (not multipart, or no boundary). */
+export function multipartBoundary(contentType) {
+    if (!contentType || !/^multipart\/form-data/i.test(contentType))
+        return null;
+    const hit = /boundary=(?:"([^"]+)"|([^;\s]+))/i.exec(contentType);
+    return hit ? (hit[1] ?? hit[2]) : null;
+}
+function indexOf(haystack, needle, from) {
+    outer: for (let i = from; i <= haystack.length - needle.length; i += 1) {
+        for (let j = 0; j < needle.length; j += 1)
+            if (haystack[i + j] !== needle[j])
+                continue outer;
+        return i;
+    }
+    return -1;
+}
+/** The parts of a body delimited by `boundary`, in order; a malformed tail ends the reading. */
+export function multipartParts(bytes, boundary) {
+    const encoder = new TextEncoder();
+    const decoder = new TextDecoder();
+    const delimiter = encoder.encode(`--${boundary}`);
+    const blank = encoder.encode('\r\n\r\n');
+    const parts = [];
+    let at = indexOf(bytes, delimiter, 0);
+    while (at >= 0) {
+        const start = at + delimiter.length;
+        // `--` after the delimiter closes the body
+        if (bytes[start] === 0x2d && bytes[start + 1] === 0x2d)
+            break;
+        const headerEnd = indexOf(bytes, blank, start);
+        if (headerEnd < 0)
+            break;
+        const next = indexOf(bytes, delimiter, headerEnd + 4);
+        if (next < 0)
+            break;
+        const head = decoder.decode(bytes.subarray(start, headerEnd));
+        const disposition = /content-disposition:[^\r\n]*/i.exec(head)?.[0] ?? '';
+        parts.push({
+            name: /\bname="([^"]*)"/i.exec(disposition)?.[1] ?? '',
+            filename: /\bfilename="([^"]*)"/i.exec(disposition)?.[1] ?? null,
+            type: /content-type:\s*([^\r\n]+)/i.exec(head)?.[1]?.trim() ?? null,
+            // the CRLF before the next delimiter is the delimiter's, not the part's
+            body: bytes.slice(headerEnd + 4, next - 2),
+        });
+        at = next;
+    }
+    return parts;
+}

package/dist/src/observe.d.ts

@@ -1,9 +1,12 @@
 import { type SubjectFields } from './hash.js';
+/** `adopts`: the local id of a subject a deploy settled with no vendor id, which this observation is (refresh's
+ *  adoption, architecture "Refresh"): the observation lands as that subject's alias, and the local one stands. */
 export type ObservedResource = {
     type: string;
     id: string;
     fields: SubjectFields;
     deleted?: boolean;
+    adopts?: string;
 };
 export type ObserveReport = {
     observed: number;
@@ -18,7 +21,7 @@ export type Observation = {
     resource: ObservedResource;
 } | {
     resources: ObservedResource[];
-    complete?: string[];
+    complete?: Completed[];
 });
 /** Run `fn` with every `observeResource` inside it COLLECTED instead of folded; the caller folds the
  *  batch (`observeResources`) once `fn` returns. The kernel's refresh does this around an adapter. */
@@ -26,11 +29,18 @@ export declare function collectObservations<T>(fn: () => Promise<T>): Promise<{
     value: T;
     observations: Observation[];
 }>;
+/** A type a batch listed in full: all of it, or (a type under a parent) the subjects whose `field` names one of the
+ *  parents listed `within`. */
+export type Completed = string | {
+    type: string;
+    field: string;
+    within: string[];
+};
 /** Fold a collected batch: one `observeResources` per service, `complete` applied to each. */
 export declare function foldObservations(observations: Observation[], opts?: {
     root?: string;
     at?: string;
-    complete?: string[];
+    complete?: Completed[];
     batch?: string;
 }): ObserveReport;
 /** One observed resource: collected when a refresh scope is open, else folded onto the root's log now. */
@@ -39,11 +49,11 @@ export declare function observeResource(service: string, resource: ObservedResou
     at?: string;
 }): ObserveReport;
 /** The fold: diff each resource against upstream state, append what changed to the root's log. `complete`
- *  names the types this batch listed in full — a subject of such a type the batch does not hold is
- *  tombstoned. Entry ids are content-addressed, so the same observation folds once. */
+ *  names the types this batch listed in full (or in full under the parents it names) — a subject of such a type the
+ *  batch does not hold is tombstoned. Entry ids are content-addressed, so the same observation folds once. */
 export declare function observeResources(service: string, resources: ObservedResource[], opts?: {
     root?: string;
     at?: string;
-    complete?: string[];
+    complete?: Completed[];
     batch?: string;
 }): ObserveReport;

package/dist/src/observe.js

@@ -7,16 +7,17 @@
 // unchanged resource appends nothing; a listing the adapter declares complete tombstones what it
 // no longer holds. A refresh runs inside a scope that collects the adapter's observations and folds
 // them as one batch; an ingest observes directly, one resource at a time.
-import { withAncestryLock } from "./ancestry.js";
+import { withHistoryLock } from "./ancestry.js";
 import { AsyncLocalStorage } from 'node:async_hooks';
 import { appendParentEntry, readParentTreeMap } from "./log.js";
 import { hashFieldValue } from "./hash.js";
 import { worldNow } from "./world-clock.js";
+import { worldPaths } from "./storage.js";
 // ONE sink per process, whichever copy of the kernel a pack resolved: a pack installed beside a
 // world carries its own `@volter/world-core`, and its observations must reach the scope the runtime
 // opened. A module-level instance would be one per copy; a process-global symbol is one per process.
 const SINK = Symbol.for('volter.observe.sink');
-// created on first use, never at import: a mirror's CLIENT bundle (target browser) carries this module
+// created on first use, never at import: a browser bundle carrying the kernel carries this module
 // through the pack's shared helpers, and a browser has no AsyncLocalStorage — constructing one at load
 // would kill the whole client ("not a constructor") for a scope the browser never opens
 const sink = () => (globalThis[SINK] ??= new AsyncLocalStorage());
@@ -75,8 +76,8 @@ function stable(value) {
     return `{${Object.keys(o).sort().map((k) => `${JSON.stringify(k)}:${stable(o[k])}`).join(',')}}`;
 }
 /** The fold: diff each resource against upstream state, append what changed to the root's log. `complete`
- *  names the types this batch listed in full — a subject of such a type the batch does not hold is
- *  tombstoned. Entry ids are content-addressed, so the same observation folds once. */
+ *  names the types this batch listed in full (or in full under the parents it names) — a subject of such a type the
+ *  batch does not hold is tombstoned. Entry ids are content-addressed, so the same observation folds once. */
 export function observeResources(service, resources, opts = {}) {
     const collecting = typeof AsyncLocalStorage === 'function' ? sink().getStore() : undefined;
     if (collecting) {
@@ -86,17 +87,17 @@ export function observeResources(service, resources, opts = {}) {
     return foldResources(service, resources, opts);
 }
 function foldResources(service, resources, opts) {
-    return withAncestryLock(() => {
+    return withHistoryLock(worldPaths(service, opts.root).dir, () => {
         const at = opts.at ?? worldNow();
         // one look is one batch: every entry it appends carries the same id, and no position may split it
         const batch = opts.batch ?? `obs:${service}:${at}`;
         const tree = readParentTreeMap(service, opts.root);
         const report = { observed: resources.length, appended: 0, unchanged: 0, removed: 0 };
         const seen = new Set();
-        const append = (subject, fields) => {
+        const append = (subject, fields, aliasOf) => {
             const entry = {
-                id: `observed:${service}:${subject.type}:${subject.id}:${hashFieldValue({ subject, fields, at })}`,
-                service, op: 'set', operation: 'observed', subject, occurredAt: at, actor: { kind: 'system', id: 'vendor' }, fields, batch,
+                id: `observed:${service}:${subject.type}:${subject.id}:${hashFieldValue({ subject, fields, at, ...(aliasOf ? { aliasOf } : {}) })}`,
+                service, op: 'set', operation: 'observed', subject, occurredAt: at, actor: { kind: 'system', id: 'vendor' }, fields, batch, ...(aliasOf ? { aliasOf } : {}),
             };
             const { appended } = appendParentEntry(entry, opts.root);
             const key = `${subject.type}:${subject.id}`;
@@ -110,6 +111,15 @@ function foldResources(service, resources, opts) {
         for (const r of resources) {
             const key = `${r.type}:${r.id}`;
             seen.add(key);
+            // an adoption: the vendor's subject is the local one a deploy made with no id, aliased to it
+            if (r.adopts !== undefined && !tree.has(key)) {
+                seen.add(`${r.type}:${r.adopts}`);
+                if (append({ type: r.type, id: r.id }, r.fields, r.adopts))
+                    report.appended += 1;
+                else
+                    report.unchanged += 1;
+                continue;
+            }
             const existing = tree.get(key);
             if (r.deleted) {
                 if (existing && existing.fields.deleted !== true) {
@@ -135,10 +145,14 @@ function foldResources(service, resources, opts) {
             else
                 report.unchanged += 1;
         }
-        for (const type of opts.complete ?? []) {
+        for (const c of opts.complete ?? []) {
+            const type = typeof c === 'string' ? c : c.type;
+            const within = typeof c === 'string' ? undefined : new Set(c.within);
             for (const s of tree.values()) {
                 if (s.type !== type || seen.has(`${s.type}:${s.id}`) || s.fields.deleted === true)
                     continue;
+                if (within && typeof c !== 'string' && !within.has(String(s.fields[c.field])))
+                    continue;
                 if (append({ type: s.type, id: s.id }, { deleted: true }))
                     report.removed += 1;
             }

package/dist/src/openai-wire.d.ts

@@ -0,0 +1,108 @@
+import type { PackScenario } from './pack-fetch.js';
+import type { ScenarioDecision } from './scenario.js';
+type Row = Record<string, unknown>;
+/** A turn: the text, or tool calls, the reasoning when there is some, and why it finished. */
+export type WireTurn = {
+    text?: string | null;
+    toolCalls?: Array<{
+        name: string;
+        arguments: Row;
+    }>;
+    reasoning?: string | null;
+    finishReason?: string;
+};
+/** Tokens, estimated at about four characters a token: a twin's count, not a tokenizer's. */
+export declare const estimateTokens: (text: string) => number;
+/** A message's content as text: a string, or its text parts joined. */
+export declare const chatText: (content: unknown) => string;
+/** The last user message's text. */
+export declare function chatLastUserText(messages: Row[]): string;
+/** The tool results the last message carries (a `tool` message), by its name or call id. */
+export declare const chatToolResults: (messages: Row[]) => string[];
+/** The labeled stub for a chat request: with tools offered (`tool_choice` not `none`) and the last message not a tool's
+ *  result, it calls the tool the choice names, else the first, with arguments its schema admits; with a JSON response
+ *  format, it answers a value the schema admits; otherwise it echoes the last user message. `label` names the twin. */
+export declare function chatStubTurn(body: Row, label: string): WireTurn;
+export type ChatShape = {
+    id: string;
+    model: string;
+    created: number;
+    turn: WireTurn;
+    messages: Row[];
+    /** the request's max_tokens / max_completion_tokens: a longer text is cut there and finishes `length` */
+    maxTokens?: number;
+    /** each tool call's id */
+    callId: (i: number) => string;
+    /** fields a vendor adds at the top of the answer and of each chunk (OpenRouter's `provider`) */
+    extra?: Row;
+    /** top-level fields on interim stream chunks instead of extra; terminal chunks retain extra */
+    interimExtra?: Row;
+    /** fields a vendor adds to the usage (OpenRouter's `cost`) */
+    usageExtra?: Row;
+    /** the vendor also answers the provider's own finish reason (`native_finish_reason`) */
+    nativeFinish?: boolean;
+    /** the name the reasoning takes in a message (`reasoning`, or `reasoning_content`) */
+    reasoningField?: string;
+};
+/** A chat completion's body (`object: chat.completion`), one choice. */
+export declare function chatCompletion(s: ChatShape): Row;
+/** A chat completion streamed: its chunks (`object: chat.completion.chunk`) as Server-Sent Events, the text in two
+ *  deltas, the last chunk carrying the finish reason and the usage, then `data: [DONE]`. `comment` is a keep-alive a
+ *  vendor sends first (OpenRouter's `: OPENROUTER PROCESSING`). */
+export declare function chatCompletionSSE(s: ChatShape & {
+    comment?: string;
+}): string;
+/** A V4 call's options as the chat completions request they mean: its prompt as messages, its tools, tool choice,
+ *  response format and output limit; so the chat stub and the wire's scenario read it. */
+export declare function aiSdkChatBody(call: Row, model: string): Row;
+/** A V4 generate result: the turn's content (reasoning, text, tool calls with their input as JSON text), its finish
+ *  reason (unified, and the raw one) and its usage; `extra` is what the server adds (the gateway's provider metadata). */
+export declare function languageModelResult(s: ChatShape): Row;
+/** A V4 stream: its parts as Server-Sent Events (stream-start, response-metadata, the reasoning, the text in two deltas,
+ *  each tool call's input then the call, and the finish), with no `[DONE]`: the SDK reads every event as a part. */
+export declare function languageModelSSE(s: ChatShape): string;
+/** A Responses request's input as items: a string is one user message. */
+export declare const responsesItems: (input: unknown) => Row[];
+/** The last user message's text in a Responses input. */
+export declare function responsesLastUserText(input: unknown): string;
+/** The function-call outputs the input ends with. */
+export declare const responsesToolResults: (input: unknown) => string[];
+/** The labeled stub for a Responses request: a function tool is called (unless the input already carries its output or
+ *  `tool_choice` is `none`), a JSON schema format answers a value it admits, otherwise the last user text is echoed. */
+export declare function responsesStubTurn(body: Row, label: string): WireTurn;
+export type ResponsesShape = {
+    id: string;
+    model: string;
+    createdAt: number;
+    turn: WireTurn;
+    body: Row;
+    /** ids for the output items: the message, the reasoning, each function call and its call id */
+    itemId: (kind: 'msg' | 'rs' | 'fc' | 'call', i: number) => string;
+    extra?: Row;
+};
+/** A Responses object (`object: response`, `status: completed`): its output items (the reasoning when there is some,
+ *  the message with its output text, or function calls) and its usage. */
+export declare function responsesAnswer(s: ResponsesShape): Row;
+/** A Responses object streamed: the events the wire sends (`response.created`, `response.in_progress`, each output
+ *  item's added, its text deltas and done, `response.completed`), each `event:` and `data:` with its sequence number. */
+export declare function responsesSSE(s: ResponsesShape): string;
+export type WireRequest = {
+    model: string;
+    text: string;
+    lastUser: string;
+    tools: string[];
+    results: string[];
+    toolsForbidden?: boolean;
+};
+/** Whether a request forbids every tool call: OpenAI's `tool_choice: 'none'`, Anthropic's `{ type: 'none' }`. */
+export declare const forbidsTools: (choice: unknown) => boolean;
+/** The turn a scenario's decision scripts (`respond`: text, toolCalls, reasoning, finishReason), or undefined. */
+export declare function scenarioTurn(decision: ScenarioDecision | undefined): WireTurn | undefined;
+/** A request as the scenario reads it: its model, its text, its last user text, the tools it offers and the tool
+ *  results it ends with, from a chat completion's messages or a Responses input. */
+export declare function wireRequest(body: Row): WireRequest;
+/** The scenario of a vendor on this wire: its operations, and its error body for a scripted fault. `readers` reads an
+ *  operation whose request is another wire's (a gateway's Anthropic Messages surface: anthropicWire's
+ *  `messagesWireRequest`), so one scenario scripts every surface's turns alike. */
+export declare function scenario(vendor: string, operations: string[], faultBody: (status: number, message: string | undefined) => unknown, readers?: Record<string, (body: Row) => WireRequest>): PackScenario<WireRequest>;
+export {};