@elysra/tungsten-runtime 0.0.0-stage → 0.1.1

package/dist/types.d.ts

@@ -0,0 +1,667 @@
+/**
+ * The contract between SDKs generated by tungsten and this runtime
+ * (planning/05 "TypeScript SDK", planning/06 "Runtime and safety").
+ *
+ * Generated code is mostly data: one `OperationDescriptor` per operation,
+ * one `ApiDescriptor` per client, and thin typed wrappers that call
+ * `ClientCore`. Everything with behaviour (validation, auth, idempotency,
+ * retries, error envelopes, previews, verification, pagination) lives in the
+ * runtime, so a fix ships as a runtime release instead of a regeneration.
+ *
+ * PHASE-2 CONTRACT: these types are shared by the runtime and the
+ * TypeScript emitter. Additive changes only (new optional fields, new
+ * union members), and only with both sides updated.
+ */
+import type { TokenStore } from "./oauth.js";
+import type { EventStream } from "./streams.js";
+export type Safety = "read_only" | "mutating" | "destructive" | "irreversible";
+export type Retryable = "never" | "after_delay" | "same_key_only" | "after_remediation";
+/** Closed set of error categories shared by every tungsten runtime. */
+export type Category = "VALIDATION_FAILED" | "MALFORMED_REQUEST" | "REQUEST_TOO_LARGE" | "AUTH_FAILED" | "NOT_FOUND" | "CONFLICT" | "PRECONDITION_FAILED" | "RATE_LIMITED" | "UPSTREAM_UNAVAILABLE" | "OUTCOME_UNKNOWN" | "TRANSPORT_FAILED" | "CONFIRMATION_REQUIRED" | "GATE_DISABLED" | "UNEXPECTED_RESPONSE";
+/** The diagnostic error envelope (planning/06). Field names are snake_case
+ * on purpose: the envelope is pasted verbatim into a model's context and is
+ * identical across the TypeScript, Python and Rust runtimes. */
+export interface Diagnostic {
+    status: "error";
+    category: Category;
+    /** Operation id, e.g. `public.replayWebhookDelivery`. */
+    operation: string;
+    http_status: number | null;
+    /** The API's error code from the response body, when present. */
+    code: string | null;
+    /** JSON path of the offending argument (`body.recipient_e164`). */
+    failed_parameter: string | null;
+    /** Redacted when the parameter is sensitive; strings cut to 200 chars. */
+    received_value: unknown;
+    expected: string | null;
+    remediation: string;
+    retryable: Retryable;
+    retry_after_ms: number | null;
+    /** What to do next, e.g. the verification operation to call. */
+    next_action: string | null;
+    request_id: string | null;
+    trace: {
+        attempts: number;
+    };
+}
+export interface ResponseMeta {
+    status: number;
+    headers: Record<string, string>;
+    requestId: string | null;
+    attempts: number;
+}
+/** The meta of a stream item: the answer of the connection the event
+ * arrived on (the last one, after a reconnect) and how often the stream
+ * reconnected up to this event. */
+export interface StreamMeta extends ResponseMeta {
+    reconnects: number;
+}
+export interface Verification {
+    checked: boolean;
+    /** True when `expect` held; false when it did not within the budget. */
+    passed: boolean;
+    /** The verification operation's last result body. */
+    observed: unknown;
+    /** True when polling for `terminal` ran out of budget. */
+    timedOut?: boolean;
+    /** Why the check could not run (verification call failed); `checked` is false. */
+    error?: Diagnostic;
+}
+/** The outcome of a call. A success response without a body (204, or any
+ * success status the spec declares without content) has `value: undefined`;
+ * generated SDKs type such operations as `void` (or `T | undefined` when the
+ * operation can also answer with a body). */
+export type Result<T> = {
+    ok: true;
+    value: T;
+    meta: ResponseMeta;
+    verification?: Verification;
+} | {
+    ok: false;
+    error: Diagnostic;
+    /** What the failed call or macro already produced, when its effect
+     * happened: the success body of a mutation whose response failed
+     * strict validation, or a macro's completed step results by their
+     * `as` names. It can hold values the API shows only once (a signing
+     * secret), so store them before acting on the error; they are never
+     * repeated in the envelope. */
+    partial?: unknown;
+};
+export type HttpMethod = "GET" | "PUT" | "POST" | "DELETE" | "OPTIONS" | "HEAD" | "PATCH" | "TRACE";
+export type ParamLocation = "path" | "query" | "header" | "cookie";
+export type ParamStyle = "simple" | "form" | "label" | "matrix" | "space_delimited" | "pipe_delimited" | "deep_object";
+export type ParamRole = "plain" | "idempotency_key" | "dry_run" | "origin" | "auth" | "constant";
+export interface ParamDescriptor {
+    /** Key in the generated method's args object. Roles `idempotency_key`,
+     * `origin`, `auth` and `constant` are not args: they come from
+     * `CallOptions.idempotencyKey` and the auth profile (`ClientOptions.auth`),
+     * and their `name` is informational. */
+    name: string;
+    /** Name on the wire. */
+    wire: string;
+    in: ParamLocation;
+    required: boolean;
+    style: ParamStyle;
+    explode: boolean;
+    role: ParamRole;
+    /** Header value of a `constant` parameter: the runtime sends it on every
+     * call (`ClientOptions.headers` and `CallOptions.headers` replace it). */
+    constant?: string;
+    sensitive?: boolean;
+}
+export type BodyEncoding = "json" | "form" | "multipart" | "bytes" | "text";
+export interface BodyDescriptor {
+    mediaType: string;
+    encoding: BodyEncoding;
+    required: boolean;
+    /** `merged`: the body is a JSON object whose fields are keys of the args
+     * object, listed in `fields` (wire names; TypeScript models keep wire
+     * names). `arg`: the whole body is `args[arg]` (bytes, text, unions,
+     * arrays, or field names that collide with a parameter). */
+    shape: {
+        kind: "merged";
+        fields: string[];
+    } | {
+        kind: "arg";
+        arg: string;
+    };
+}
+export type StatusMatch = number | "1XX" | "2XX" | "3XX" | "4XX" | "5XX" | "default";
+export interface ResponseDescriptor {
+    status: StatusMatch;
+    kind: "success" | "error" | "ambiguous";
+    /** First media type, or null for a bare status. */
+    mediaType: string | null;
+}
+export type PaginationDescriptor = {
+    style: "cursor";
+    requestParam: string;
+    /** Response field holding the next cursor; empty when only `cursorItemField` applies. */
+    responseField: string;
+    itemsField: string;
+    pageSizeParam: string | null;
+    /** Response boolean (`has_more`): iteration stops as soon as it is `false`. */
+    hasMoreField?: string;
+    /** Without a cursor in the response, the next cursor is this field of the last item. */
+    cursorItemField?: string;
+} | {
+    style: "offset";
+    offsetParam: string;
+    limitParam: string;
+    itemsField: string;
+} | {
+    style: "page";
+    pageParam: string;
+    sizeParam: string;
+    itemsField: string;
+} | {
+    style: "link_header";
+    itemsField: string;
+};
+export type IdempotencyKind = "none" | "auto" | "caller_owned" | "content_hash" | "content_identity";
+export interface RemediationEntry {
+    category?: Category;
+    text?: string;
+    retryable?: Retryable;
+    next_action?: string;
+}
+export interface VerifyDescriptor {
+    /** Operation id of the read operation to call. */
+    operation: string;
+    /** Argument mapping, keyed by the read operation's parameter wire names
+     * (or generated names); string values starting with `$response.` or
+     * `$args.` are resolved against the call, `$args` by generated or wire
+     * name. */
+    args: Record<string, unknown>;
+    /** Field path → predicate (`{in: [...]}`, `{equals: x}`, `{contains: {...}}`).
+     * `$response.` and `$args.` references in `expect` and `terminal` are
+     * resolved against the call; an unresolved one never matches. */
+    expect: Record<string, unknown>;
+    terminal: Record<string, unknown>;
+    pollIntervalMs: number | null;
+    pollBudgetMs: number | null;
+}
+export interface AgentMeta {
+    safety: Safety;
+    idempotency: {
+        policy: IdempotencyKind;
+        header: string | null;
+        format: string | null;
+        persistRequired: boolean;
+        note: string | null;
+    };
+    preview: {
+        mode: "local";
+    } | {
+        mode: "header";
+        header: string;
+        value: string;
+    } | {
+        mode: "endpoint";
+        operation: string;
+    } | {
+        mode: "none";
+    };
+    confirmation: {
+        summaryFields: string[];
+        message: string | null;
+    } | null;
+    verify: VerifyDescriptor | null;
+    /** Operation-specific remediation by API error code. */
+    remediation: Record<string, RemediationEntry>;
+    remediationNote: string | null;
+    sensitiveResponseFields: string[];
+    /** Arguments marked sensitive (`x-agent-sensitive` on request body
+     * fields), as dotted paths into the args object (`pin`, `body.pin`,
+     * `profile.recovery_phrase`; array items are not indexed). Redacted in
+     * `received_value`, previews, middleware and diagnostics. */
+    sensitiveRequestFields?: string[];
+    shownOnce: boolean;
+}
+/** Structural subset of a Zod schema (`safeParse`), so the runtime does not
+ * depend on a Zod version. */
+export interface SchemaLike<T = unknown> {
+    safeParse(value: unknown): {
+        success: true;
+        data: T;
+    } | {
+        success: false;
+        error: {
+            issues: Array<{
+                path: Array<string | number>;
+                message: string;
+                code?: string;
+            }>;
+        };
+    };
+}
+export interface OperationDescriptor {
+    /** IR operation id (`public.replayWebhookDelivery`). */
+    id: string;
+    method: HttpMethod;
+    /** Path template as in the spec (`/v1/webhooks/{endpoint_id}/rotate`);
+     * placeholders use wire names. */
+    path: string;
+    params: ParamDescriptor[];
+    body: BodyDescriptor | null;
+    responses: ResponseDescriptor[];
+    /** OR of AND-sets of auth scheme names. Empty: no auth. */
+    security: string[][];
+    pagination: PaginationDescriptor | null;
+    /** For rpc-unflattened operations: the envelope field and value to send,
+     * and the field the args are placed under. `constants` are further
+     * envelope members sent verbatim (JSON-RPC `jsonrpc: "2.0"`). */
+    rpc: {
+        field: string;
+        value: string;
+        paramsField: string;
+        constants?: Record<string, unknown>;
+    } | null;
+    /** Field path of the API error code in error bodies (`code`, `error.code`). */
+    errorCodeField: string | null;
+    status: {
+        kind: "implemented";
+    } | {
+        kind: "gated";
+        envVar: string;
+        disabledStatus: number;
+    };
+    agent: AgentMeta;
+    /** Validates the args object before any network call. */
+    request?: SchemaLike;
+    /** Validates the success body (per `ClientOptions.validateResponses`).
+     *
+     * Untagged unions (IR `UnionStrategy::Untagged`, TG0301) are emitted as
+     * `z.union([...])` with the variants in IR order, and Zod tries them in
+     * that order: the body is accepted when any variant accepts it, and the
+     * first variant that does decides which refinements applied. The
+     * result's `value` is always the decoded wire body itself, never the
+     * schema's output, so an earlier variant that overlaps a later one (or
+     * strips unknown members) cannot drop or rewrite members of the body. */
+    response?: SchemaLike;
+    /** One-line summary (compacted description); the last line of preview effects. */
+    summary?: string | null;
+    /** The operation's event stream (`ClientCore.stream`); absent when it has none. */
+    stream?: StreamDescriptor;
+}
+/** The server-sent events of an operation (IR `StreamSpec`). */
+export interface StreamDescriptor {
+    /** Validates the decoded `data` of every event (per
+     * `ClientOptions.validateResponses`); absent: events are any JSON value. */
+    event?: SchemaLike;
+    /** A `data` value that ends the stream without being an event (`[DONE]`). */
+    done?: string;
+    /** Wire name of the boolean request body field that selects the stream;
+     * `ClientCore.stream` sets it to `true`. */
+    flag?: string;
+}
+/** The `authorizationCode` flow of an OAuth2 scheme (present only when the
+ * spec declares one). `refreshUrl` falls back to `tokenUrl`. */
+export interface AuthorizationCodeDescriptor {
+    authorizationUrl: string;
+    tokenUrl: string;
+    refreshUrl: string | null;
+    scopes: string[];
+}
+export type AuthSchemeDescriptor = {
+    kind: "api_key";
+    name: string;
+    in: "header" | "query" | "cookie";
+    wire: string;
+}
+/** `prefix`: the token must start with it (tungsten.yml
+ * `auth_profiles.<name>.bearer.prefix`, e.g. `ztw_`); checked before any
+ * request is sent, and a mismatch is `AUTH_FAILED` with zero network calls. */
+ | {
+    kind: "http_bearer";
+    name: string;
+    prefix: string | null;
+} | {
+    kind: "http_basic";
+    name: string;
+} | {
+    kind: "oauth2";
+    name: string;
+    tokenUrl: string | null;
+    scopes: string[];
+    authorizationCode?: AuthorizationCodeDescriptor;
+} | {
+    kind: "composite";
+    name: string;
+    /** Spec scheme names this profile satisfies together. */
+    satisfies: string[];
+    parts: Array<{
+        kind: "cookie";
+        name: string;
+    } | {
+        kind: "header";
+        name: string;
+        equalsCookie: string | null;
+        fromConfig: string | null;
+        mutationOnly: boolean;
+    } | {
+        kind: "bearer";
+        prefix: string | null;
+    }>;
+};
+export interface ApiDescriptor {
+    /** Machine name (`zrotext`). */
+    name: string;
+    /** SDK package version. */
+    version: string;
+    tungstenVersion: string;
+    servers: string[];
+    auth: AuthSchemeDescriptor[];
+    /** Global remediation by API error code (agent.yml `errors.codes`). */
+    errorCodes: Record<string, RemediationEntry>;
+    /** Statuses that make a mutation's outcome unknown. */
+    ambiguousStatuses: number[];
+    /** Non-JSON error mapping (agent.yml `errors.non_json`); `media` is a
+     * media type or `"none"` for a bare status. */
+    nonJson: Array<{
+        status: number;
+        media: string;
+        category: Category;
+        retryable: Retryable;
+        text: string | null;
+    }>;
+    /** Runtime gate env var → explanation. */
+    gates: Record<string, string>;
+    /** Retry defaults by safety tier (agent.yml `defaults.retries`):
+     * `readOnly` for read-only operations, `mutating` for every other tier
+     * (a mutation is still retried only with an idempotency key or an
+     * identity body). `ClientOptions.retries` overrides them field by field.
+     * Absent: the runtime defaults apply to every tier. */
+    retries?: {
+        readOnly: Partial<RetryOptions>;
+        mutating: Partial<RetryOptions>;
+    };
+}
+/** Credentials per auth scheme name. A string is the secret of an
+ * `api_key`, `http_bearer` or `http_basic` (`user:password`) scheme. A
+ * composite profile takes an object keyed by cookie name or config key
+ * (for ZROtext's owner session: the two cookie values and `origin`). */
+export type AuthConfig = Record<string, string | Record<string, string>>;
+export interface IdempotencyStore {
+    get(scope: string, logicalId: string): Promise<string | undefined>;
+    put(scope: string, logicalId: string, key: string): Promise<void>;
+}
+/** What middleware sees of one attempt. Secrets are redacted: secret
+ * headers, auth query values, and in a JSON or form body the arguments
+ * marked sensitive (or named like credentials) as `<redacted>`. */
+export interface RequestContext {
+    operation: OperationDescriptor;
+    attempt: number;
+    method: HttpMethod;
+    url: string;
+    headers: Record<string, string>;
+    body: BodyInit | null;
+}
+export interface Middleware {
+    onRequest?(ctx: RequestContext): void | Promise<void>;
+    onResponse?(ctx: RequestContext, response: Response): void | Promise<void>;
+    onRetry?(ctx: RequestContext, reason: Diagnostic): void | Promise<void>;
+}
+export interface RetryOptions {
+    /** Attempts after the first, for retryable outcomes. */
+    max: number;
+    baseMs: number;
+    maxMs: number;
+    jitter: "none" | "full" | "equal";
+    honorRetryAfter: boolean;
+}
+export interface ClientOptions {
+    /** Defaults to the first server. */
+    baseUrl?: string;
+    auth?: AuthConfig;
+    /** Holds the tokens of `authorizationCode` schemes (configure such a
+     * scheme as `{flow: "authorizationCode", clientId, clientSecret?,
+     * redirectUri?}`). Default: in memory, per client. */
+    tokenStore?: TokenStore;
+    /** Defaults to `globalThis.fetch`. */
+    fetch?: typeof fetch;
+    /** Per-attempt timeout. Default 30000. */
+    timeoutMs?: number;
+    /** Overrides the API's per-tier retry defaults (`ApiDescriptor.retries`)
+     * field by field, for every tier. */
+    retries?: Partial<RetryOptions>;
+    idempotencyStore?: IdempotencyStore;
+    middleware?: Middleware[];
+    /** Default `warn`: report through `onDiagnostic`, never fail the call. */
+    validateResponses?: "off" | "warn" | "strict";
+    /** Receives warnings (response validation, deprecations). */
+    onDiagnostic?: (d: Diagnostic) => void;
+    /** Extra headers on every request. */
+    headers?: Record<string, string>;
+    /** Largest server-sent event `stream()` accepts, in UTF-8 bytes (the field
+     * lines of one event plus the line being read). A larger one ends the
+     * stream with an `UNEXPECTED_RESPONSE` failure. Default 1048576 (1 MiB). */
+    maxEventBytes?: number;
+    /** How often `stream()` reconnects a dropped stream (a lost connection, or
+     * a clean end before the `done` event the operation declares) with
+     * `Last-Event-ID` set to the last event id it delivered; events whose id
+     * was delivered are never delivered twice. Only for operations that are
+     * safe to repeat (read-only, or with replay protection) and only once
+     * an event id is known (or before the first event). 0 disables it.
+     * Default 3. */
+    maxReconnects?: number;
+    /** Longest wait before a reconnect, in milliseconds: the server's `retry`
+     * value (250 ms when it sent none) is capped at this and then reduced by
+     * up to 25 % at random. Default 30000. */
+    reconnectMaxMs?: number;
+    /** A stream that delivers no bytes (comments count) for this many
+     * milliseconds is idle: it is reconnected like a dropped one, else ends
+     * with a failure whose `code` is `STREAM_IDLE`. Default: the per-attempt
+     * `timeoutMs`, which ends the stream without a reconnect. */
+    idleTimeoutMs?: number;
+    /** Overrides the key used to sign confirmation tokens. Default: random
+     * per client instance. */
+    confirmationKey?: Uint8Array;
+    /** Operations the core can resolve by id: verification hooks, endpoint
+     * previews and macro steps. Operations passed to `call` are added too. */
+    operations?: OperationDescriptor[];
+    /** Clock in epoch milliseconds (token expiry, Retry-After dates). Default `Date.now`. */
+    now?: () => number;
+    /** Random number in [0, 1) for retry jitter. Default `Math.random`. */
+    random?: () => number;
+}
+export interface CallOptions {
+    /** Required for `caller_owned` operations with `persistRequired`. */
+    idempotencyKey?: string;
+    /** Token from `preview()`; required for `irreversible`, and for
+     * `destructive` unless `true` is given. A token authorizes one intent:
+     * the first call that sends spends it, and it is accepted again only for
+     * a retry with the same idempotency key (or the identical body of a
+     * `content_identity` operation). */
+    confirm?: string | true;
+    /** `false`: `confirm: true` does not confirm a destructive operation
+     * either, and remediation never offers it (callers that only forward
+     * preview tokens, such as an MCP server). Default `true`. */
+    allowConfirmTrue?: boolean;
+    signal?: AbortSignal;
+    timeoutMs?: number;
+    /** Optional hard response-body byte cap. Positive safe integer; checked
+     * against actual bytes while reading, including non-SSE responses. */
+    maxResponseBytes?: number;
+    /** Run the operation's verification hook after success. */
+    verify?: boolean;
+    headers?: Record<string, string>;
+}
+export interface RenderedRequest {
+    method: HttpMethod;
+    url: string;
+    /** Secrets redacted as `<redacted>`. */
+    headers: Record<string, string>;
+    body: unknown;
+}
+/** One step of a macro preview (`ClientCore.previewMacro`). */
+export interface MacroStepPreview {
+    /** 1-based position in the macro. */
+    step: number;
+    kind: MacroStep["kind"];
+    /** The step's operation id. */
+    operation: string;
+    /** The name the step's result is bound to, or null. */
+    as: string | null;
+    safety: Safety;
+    /** The request the step sends (a `poll` or `paginate` step's first
+     * request), rendered without sending anything. Arguments taken from an
+     * earlier step's result show as `<from step NAME: path>` (NAME is that
+     * step's `as` name; `<from step NAME>` for the whole result), shown as
+     * written in the URL, headers and body, and exempt from pre-flight
+     * validation. Null when the step's whole argument object comes from an
+     * earlier result, or a value from an earlier result would have to be
+     * encoded before it is known (a `bytes` or `multipart` body). */
+    request: RenderedRequest | null;
+    /** The step's own effects: its confirmation message (with the same
+     * placeholders), what a `poll` or `paginate` step repeats
+     * (`Repeats <op> every N ms until <predicate>, for at most M ms.`,
+     * `Reads up to N pages of <op>.`) and its remediation note. */
+    effects: string[];
+}
+export interface PreviewResult {
+    operation: string;
+    safety: Safety;
+    /** For a macro: the first step's request (also `steps[0].request`). */
+    request: RenderedRequest;
+    /** Side-effect summary from the manifest's confirmation message, the
+     * remediation note and the operation's summary. */
+    effects: string[];
+    /** Present for mutating operations; bound to the exact arguments. */
+    confirmation_token: string | null;
+    expires_in_ms: number | null;
+    /** For `header`/`endpoint` previews: the server's answer. */
+    server_preview?: unknown;
+    /** Macro previews only: every step's rendered request and effects, in
+     * order. `effects` above lists them all, each step's under a
+     * `Step N: <kind> <operation> (<safety>).` line. */
+    steps?: MacroStepPreview[];
+}
+export interface Page<T> {
+    items: T[];
+    /** The full page body. */
+    body: unknown;
+    /** Cursor, offset, page number or URL for the next page; null at the end. */
+    next: unknown;
+}
+/** Until-predicate for `ClientCore.poll`, same shape as `VerifyDescriptor.expect`. */
+export type Predicate = Record<string, unknown>;
+/** One macro step in the canonical form (`tungsten_ir::Macro.steps`).
+ * `args`, `budget_ms` and the macro output are expressions: strings
+ * starting with `$` reference `$input` or an earlier step's `as` name,
+ * `{expr: "<ref> in [..]" | "<ref> == x" | "<ref> != x"}` is a boolean,
+ * anything else a literal. */
+export interface MacroStep {
+    kind: "call" | "poll" | "paginate";
+    /** Operation id, resolved among the operations registered with the core. */
+    operation: string;
+    args: unknown;
+    as: string | null;
+    /** `poll` only: predicate on the step's success body. When the budget
+     * runs out before it holds, the step's `as` name is bound to `null`, so
+     * an output like `{expr: "$status == null"}` reports the timeout. */
+    until: Predicate | null;
+    interval_ms: number | null;
+    budget_ms: unknown;
+    /** `paginate` only: page limit. */
+    max_pages: number | null;
+}
+/** A compiled macro (`tungsten_ir::Macro`).
+ *
+ * Confirmation is macro-level: when the macro's tier (the strictest of its
+ * declared `safety` and its steps' tiers) is `destructive` or
+ * `irreversible`, `runMacro` requires `confirm` like an operation of that
+ * tier, with a token from `previewMacro` bound to the macro name and its
+ * exact input. That one confirmation authorizes every step of the run;
+ * steps never ask for their own tokens, since their arguments may depend on
+ * earlier steps' results. The token is spent (bound to the run's
+ * idempotency key) by the first step that passes pre-flight and sends, so
+ * a run refused before sending anything can be corrected and repeated with
+ * the same token. */
+export interface MacroDescriptor {
+    name: string;
+    summary: string;
+    safety: Safety;
+    steps: MacroStep[];
+    output: unknown;
+    /** The macro input: an operation's args (`extends`) plus added fields.
+     * An added field's JSON Schema `default` is applied when the input
+     * omits it. */
+    input: {
+        extends: string | null;
+        add: Record<string, unknown>;
+    };
+    /** Output fields carrying secrets (dotted paths); redacted in traces. */
+    sensitiveResponseFields?: string[];
+    /** The output holds values the API returns only once. */
+    shownOnce?: boolean;
+    /** Disclosure cluster (agent.yml `disclosure.clusters`). */
+    cluster?: string | null;
+}
+/** Further `ClientCore` methods beyond {@link ClientCoreApi}. */
+export interface ClientCoreExtensions {
+    /** Make operations resolvable by id (verification, endpoint previews, macros). */
+    register(...ops: OperationDescriptor[]): void;
+    /** A registered operation by id. */
+    operation(id: string): OperationDescriptor | undefined;
+    /** Run a compiled macro; returns its output or the first failing step's
+     * envelope, with the completed steps' results as `partial` (a rerun is
+     * never offered when a completed mutating step has no replay
+     * protection). A `destructive` or `irreversible` macro needs
+     * `opts.confirm` (see {@link MacroDescriptor}). */
+    runMacro<T>(macro: MacroDescriptor, input: Record<string, unknown>, opts?: CallOptions): Promise<Result<T>>;
+    /** Preview a macro without sending anything: validates and renders
+     * every step's request (arguments from earlier results as
+     * `<from step NAME: path>` placeholders, from a dry evaluation), lists
+     * every step's effects and, unless the macro is read-only, returns a
+     * confirmation token bound to the macro and this exact input. A step
+     * whose arguments fail pre-flight for reasons other than a placeholder
+     * fails the preview, naming the step. */
+    previewMacro(macro: MacroDescriptor, input: Record<string, unknown>, opts?: CallOptions): Promise<Result<PreviewResult>>;
+}
+/** One item of a stream: an event, or the failure that ends the stream
+ * (an envelope; a failure before the first event is the only item). */
+export type StreamItem<T> = {
+    ok: true;
+    /** The event's `data`, decoded from JSON (and validated). */
+    value: T;
+    /** The `event` field of the server-sent event, `message` when it has none. */
+    event: string;
+    /** The last event id the stream has set so far, or null. */
+    id: string | null;
+    /** The last `retry` value (milliseconds) the stream has set so far, or null. */
+    retry: number | null;
+    meta: StreamMeta;
+} | {
+    ok: false;
+    error: Diagnostic;
+};
+/** What `ClientCore` (implemented in `client.ts`) offers generated code. */
+export interface ClientCoreApi {
+    readonly api: ApiDescriptor;
+    /** Validate, authenticate, apply idempotency and confirmation rules, send
+     * with retries, classify the response. Never throws for API or transport
+     * errors; returns `{ok: false, error}`. */
+    call<T>(op: OperationDescriptor, args: Record<string, unknown>, opts?: CallOptions): Promise<Result<T>>;
+    /** Run the operation's preview mode. */
+    preview(op: OperationDescriptor, args: Record<string, unknown>, opts?: CallOptions): Promise<Result<PreviewResult>>;
+    /** Iterate the events of an operation's event stream (`text/event-stream`).
+     * Errors before the stream starts (validation, auth, an error status) are
+     * the only item, as for `call`, and are retried by the same rules. A
+     * started stream that drops is reconnected with `Last-Event-ID`
+     * (`ClientOptions.maxReconnects`) when the operation is safe to repeat;
+     * otherwise, or when the reconnects are used up, a connection lost or an
+     * idle timeout ends it with a final failure item (`TRANSPORT_FAILED`,
+     * `UPSTREAM_UNAVAILABLE` for a read; `OUTCOME_UNKNOWN` for a mutation;
+     * `code` `STREAM_IDLE` for `ClientOptions.idleTimeoutMs`), as does an event
+     * that is not JSON or (with `validateResponses: "strict"`) does not match
+     * the event type. The result is an async iterable with helpers
+     * (`on`, `collect`, `reduce`, `first`, `cancel`). */
+    stream<T>(op: OperationDescriptor, args: Record<string, unknown>, opts?: CallOptions): EventStream<T>;
+    /** Iterate pages; stops after the last page or the first error result. */
+    pages<T>(op: OperationDescriptor, args: Record<string, unknown>, opts?: CallOptions): AsyncIterable<Result<Page<T>>>;
+    /** Call a read operation until `until` holds or the budget runs out. */
+    poll<T>(op: OperationDescriptor, args: Record<string, unknown>, until: Predicate, intervalMs: number, budgetMs: number, opts?: CallOptions): Promise<Result<T> & {
+        timedOut?: boolean;
+    }>;
+}

package/dist/types.js

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