prelude

Add two numbers; preserves integer when both operands are integers.

Subtract two numbers; preserves integer when both operands are integers.

Multiply two numbers; preserves integer when both operands are integers.

Floor-modulo two numbers; preserves integer when both operands are integers. A zero divisor panics (guard with a comparison first).

Divide two numbers; always yields a number. A zero divisor panics (guard with a comparison first) — division never yields Infinity / NaN.

Negate a number; preserves integer.

Whether two values are equal.

Whether two values are not equal.

Whether the left number is less than the right.

Whether the left number is less than or equal to the right.

Whether the left number is greater than the right.

Whether the left number is greater than or equal to the right.

Logical conjunction.

Logical disjunction.

Logical negation.

Concatenate two strings.

Signal a typed error the caller may recover from. The payload is a domain-specific error data (e.g. json.parse_error); a handler at that payload type catches it — use handler { request throw(error: my_error) -> never { break fallback } } — and an unhandled throw fails the run with the payload. -> never means a throw cannot be resumed: a handler recovers by breaking out of the handle (or rethrows).

The element at index (0-based), or null when the index is out of bounds.

The number of elements.

A copy of the array with value appended.

The left array followed by the right.

The elements from start (inclusive) to end (exclusive), 0-based, clamped to the bounds.

Whether value occurs among the elements (structural equality, like ==).

The index of the first element equal to value (structural equality), or null when none is.

The arrays' elements concatenated in order — one level of nesting removed. With for's mapping this is also the filter idiom: map each element to [x] or [], then flatten.

The elements in reverse order.

The integers from start (inclusive) to end (exclusive), in order — for's counted-loop source. Empty when end <= start.

The empty array.

No secret env entry is set under key. Thrown by get_secret — catch it to fall back in-program (use handler { request throw(error: env.missing_secret) -> never { ... } }).

Read a secret env entry by key, returning its value as a private string (the value is tainted secret and cannot flow to a user-facing boundary). A missing key throws missing_secret (carrying the key), so a program can fall back for optional config; uncaught, the throw fails the run.

Read every non-secret env entry as a record of bare (public) strings, keyed by the env key.

The file a handle names is gone — it was freed, or the id never named a blob in this project (a model hallucinating a $katari_ref). One error covers both: a slim handle cannot tell which, and a program that catches this reacts the same way (re-fetch, skip). Thrown by every reader below; catch it to recover.

The content passed to from_base64 is not valid base64 (bad alphabet, length, or padding). Thrown by from_base64 — catch it to fall back when a model or upstream API hands back a corrupt base64 payload.

The file's bytes, base64-encoded — the inline shape multimodal model APIs take. The whole content materialises as one string, so mind the size (a large file makes a large request body). Throws gone if the handle no longer names a live blob (freed, or a made-up id).

The file's recorded MIME type (e.g. "image/png"), read from the project's file catalog; "" when none was recorded. Throws gone if the handle no longer names a live blob.

The file's size in bytes, read from the project's file catalog (no content download). Throws gone if the handle no longer names a live blob.

Make a file from a base64 string — the engine's blob producer, for lifting a model's / API's embedded base64 (a gemini inline_data image) OFF the value plane and INTO a real blob handle, so the heavy bytes travel runtime-side like any other file. The new file is owned by the current run and reclaimed with it (or explicitly, via free). Two calls with the SAME bytes are DIFFERENT files (a file is a resource, not a literal). Throws malformed_base64 if content is not valid base64.

Release a file the current run owns, freeing its bytes now rather than at run teardown — for a large, short-lived intermediate (a decoded image already handed to a model). Idempotent and silent: freeing an already-gone file, or one the run does NOT own (a user-uploaded file, whose lifetime is the file API's), is a no-op — so a retried block that frees the same handle twice behaves identically each attempt. A later read of a freed handle throws gone.

An HTTP request never completed: DNS failure, refused connection, timeout, or a mid-flight runtime restart. Thrown by fetch. (A response that did arrive is never an error — branch on its status.)

A text body: the content string, sent verbatim (Content-Type is the caller's to set). The content may be a secret (an OAuth refresh_token in a form-encoded body).

A raw-bytes body: the file content's bytes, sent as-is — the shape an upload API (an S3 PUT) takes. The Content-Type defaults to the file's recorded content type; set a Content-Type header to override it.

A multipart/form-data body (RFC 7578): the parts, each a named form field — text or file. The transport generates the boundary and sets the Content-Type, so do not set a Content-Type header for it.

A JSON body from a value value tree (records / arrays / scalars / files, mixed): serialised to a JSON document where every file leaf — and only a file leaf — becomes the base64 of its bytes, in place. This is the REST convention (a GitHub content upload, an AI provider's inline image), NOT an HTTP standard. To transmit a file's HANDLE instead of its bytes (almost never what an API wants), stringify it yourself first (e.g. embed json.stringify(value = a_file) as a string). Everything but a file goes on the wire as the tree you built. The tree may carry secrets (its type is private-capable), revealed only to the destination.

A text form field: the field named name with the text content (which may be a secret).

A file form field: the field named name carrying the file content, advertised with filename. Its per-part Content-Type is the file's recorded content type.

Perform an HTTP request to url with method (e.g. "GET" / "POST"), the given headers and body. The body is one of http.text / http.binary / http.multipart / http.json (a file in any of them is read from the blob store at the send boundary, never materialised earlier). Each header value AND a private body surface (a text's content, a json's tree) may be a secret, submitted to url's server, while url and method stay public. Returns the response status code, its headers (names lowercased; repeated headers joined with ", ") and its body text. A request that never completes throws fetch_error (catchable with use handler { request throw(error: http.fetch_error) -> never { ... } }).

Perform an HTTP request to url with method, the given headers and body — EXACTLY fetch's request — but capture the RESPONSE body as a downloaded file rather than as text. The bytes land in the blob store and the reply carries only the slim file HANDLE; the raw bytes (and their base64) never touch the value plane, the durable call record, or the trace. This is the receive-side twin of a binary REQUEST body, and it exists for the same reason: to keep a payload's bytes OFF the value plane. A plain fetch of a megabyte image would read it into the response body STRING, dragging that text (and its base64, once re-encoded) through every value, event, and trace it flows into — whereas fetch_file streams it straight to a blob and hands back a handle. Reach for it to download a file by URL: an image, a PDF, a CSV export, a release artifact. It is NOT for a base64 field buried inside a JSON reply (a data-URI in an API's JSON document) — fetch_file only ever captures the WHOLE response body; decode an embedded base64 string with files.from_base64 after an ordinary fetch. The downloaded file's recorded content type is the response's Content-Type (falling back to application/octet-stream when the server sent none). Returns the response status code (branch on it exactly like fetch — a non-2xx reply's body is still captured to a file, so a caller inspects status before trusting the download), its headers (names lowercased; repeated headers joined with ", "), and the downloaded file. A request that never completes throws fetch_error, exactly like fetch.

A JSON API responded with a non-2xx status. Thrown by post_json (the raw fetch never treats an arrived response as an error — this wrapper takes the opinionated JSON-API stance).

POST body — a JSON value tree — to url as application/json with the given headers, and return the reply PARSED into its document value. This is the canonical one-call shape of a JSON API integration: build the body as an ordinary record / array / scalar tree, post it, and read the reply as a value — no manual json.stringify / json.parse around the call. body AND each header value may be a secret (an auth token — an "Authorization" of "Bearer <key>" for OpenAI, an "x-goog-api-key" for Gemini — or a refresh_token in the body of an OAuth exchange): both are submitted only to url's server, which stays public. A file placed anywhere in body rides as base64 (the http.json slot contract). The Content-Type defaults to application/json unless a header overrides it. A non-2xx status throws status_error (its body text attached); a transport failure throws fetch_error; a 2xx body that is not JSON throws json.parse_error (a JSON API that broke its promise) — an empty 2xx body is null. To send already-serialized text, or to keep the raw reply text, call fetch directly.

A JSON document failed to parse: the text is not JSON. Thrown by parse / parse_as.

A value does not conform to the requested type's schema. Thrown by validate / parse_as; message names the offending path.

Parse JSON text into the value it denotes — a record / array / string / integer / number / boolean / null, or a file where the text carries a $katari_ref handle. Traverse a document with shape filters (case record(r)) and the readers below, or pin its shape with parse_as[T]. A number without a fractional part parses as integer. Malformed text throws parse_error.

Check value against T's schema and return it unchanged, or throw validation_error naming the offending path. A pure check — it never rewrites the value. Instantiate T explicitly (it appears only in the result, so it cannot be inferred).

Parse JSON text directly as a T — parse then validate[T], the typed text boundary. Instantiate T explicitly (it appears only in the result, so it cannot be inferred). Malformed text throws parse_error; a value that does not conform to T's schema throws validation_error naming the offending path.

Render ANY value as its (compact) JSON text — TOTAL and CANONICAL (one value, one text). A document value (record / array / string / integer / number / boolean / null) round-trips verbatim, so stringify(parse(s)) is s up to whitespace; a file becomes its $katari_ref handle object, a data value nests its fields under $katari_value ({ $katari_constructor: name, $katari_value: { ...fields } }), and an agent / closure / tool its handle object. stringify is the READ CHANNEL for showing an AI a handle / data value (an error render, a handle embed, a tool result rendered back to a model). A secret operand taints the whole result (the monotonic information-flow rule).

The record target holds (its entries), or the empty record if target is not a record.

The array target holds (its elements), or the empty array if target is not an array.

The child at object key key (null if target is not a record or has no such key).

The element at array index index (null if target is not an array or index is out of range).

The string target holds (the empty string if it is not a string).

The absolute value; preserves integer.

The smaller of the two; preserves integer when both operands are integers.

The larger of the two; preserves integer when both operands are integers.

The largest integer not above the value. A non-finite value cannot occur (division never yields one).

The smallest integer not below the value.

The nearest integer (half away from zero, the grade-school rule — not banker's rounding).

The MCP server rejected a listing or a tool call, or the transport failed (the server-reported or transport message). Also raised as the scope backstop: a tool called after its provide returned reports its closed scope this way. Catch it to control retry — a retried call reconnects.

The server rejected the headers key material. Retrying with the same material does not help: a human must fix the key the program supplies. Never raised on the oauth path — an unusable oauth credential pauses the run on an authorization escalation instead of failing it. Distinct from server_error so a program can catch the two differently.

Header-based access: values ride on every request to the server (each value may be a secret, such as a bearer key). Anonymous access is headers(values = record.empty()).

A named OAuth credential, stored server-side. The runtime injects and refreshes its tokens itself; the name is not a secret. While the name has no usable credential, any use pauses the run on a prelude.oauth.authorize escalation — answering it (the runtime-hosted browser flow) establishes the credential and resumes the run.

The built-in scope capability for the dynamic provide path: a nullary phantom marker, carried in a tool's effect row, never performable, never handleable. provide mints it for its continuation's row and discharges it from its own, so a tool tagged scope cannot outlive the provide that introduced it. A generated katari mcp pull binding declares its own module-local marker instead; distinct nullary markers never merge and never widen, so there is no covariance to reason about.

Plug an MCP server's tools into a program for the extent of continuation, as a scoped provider — the use mcp.provide(url = ..., auth = ...) form. The runtime lists the server (a missing or dead oauth credential pauses on an authorization escalation and retries once answered; rejected headers material throws auth_error; a rejected listing throws server_error), hands continuation a toolbox[Scope] of one runtime-minted agent per tool (each carrying the server signature — for reflection.get_metadata and call-site validation — and the descriptor it was listed with), and settles with the continuation's result. Scope rides the continuation's row (that is what a tool call raises) and is DISCHARGED from provide's own row, so a tool cannot escape the block: the scope closes when continuation returns (or the run is cancelled), and a stray later call is rejected as a typed server_error. Scope is the marker the tools are gated by — the built-in mcp.scope for the dynamic path, or a generated binding's module-local marker; pass it explicitly as the first [...] argument (mcp.provide[mcp.scope](...)), and the toolbox binder's annotation must agree. Discharging Scope is provide's alone (only it opens the connection), so a live tool context cannot be forged. url is a plain routing value: the runtime connects and caches under the {url, auth} descriptor. DECLARE ONE MARKER PER LOGICAL CONNECTION. When you call provide directly you choose Scope yourself: share ONE marker across two connections and their scopes MERGE at the type level (the two servers' tools become mutually substitutable in a row that carries the marker) — the same widening the old dynamic-URL toolbox[string] had, no worse. It is only a TYPE distinction: routing and the live-provide backstop are always enforced by each tool value's own {url, auth} descriptor, so a call never reaches the wrong server — at worst a tool whose provide has closed fails with a typed server_error. A katari mcp pull binding needs no such discipline: its module namespace mints a distinct marker (github.connection) per connection automatically, so pulled servers never share a scope.

Call one tool on an MCP server directly — the static counterpart of provide, with no listing and no minted agent value. The seam the binding modules katari mcp pull generates are built on: tool is the server-declared tool name, arguments its arguments object as a plain value tree (records / arrays / scalars, and a file becomes base64 in place — the same slot contract as http.json). The result is read as a value and checked against T inside the runtime: a $katari_ref handle object becomes a REAL file value, records / arrays / scalars land as themselves, a plain-text reply reads only into a string-shaped T, and a mismatch throws validation_error. Instantiate T with unknown to keep the reply as a raw document value (the codegen's choice when no outputSchema maps); a $katari_ref in it is still a real file — the wire-to-value conversion is unconditional, never schema-directed. T appears only in the result, so it is never inferable — instantiate it explicitly; the Scope marker is a phantom the row never infers, so a caller writes both to [...], mcp.call[Scope, T](url = ..., ...) — a generated binding passes its own module-local marker. Nothing validates arguments before the server does (unlike a minted tool) — a rejected call throws server_error. Scope-gated the same way as a minted tool (Scope on its row): a generated binding calls this only inside a provide scope over the same marker and descriptor, and the runtime rejects a call with no live scope for that descriptor as a typed server_error.

Publish tools as a live MCP server for the extent of subscriber. The runtime mints a fresh, unguessable capability URL and serves the record's agents as MCP tools there — each record key is the published tool name, each agent's declared signature the tool's advertised schema. The URL is the key: possession grants access, nobody without it can call in. subscriber receives the URL, hands it to whoever should connect (an AI session, a teammate's MCP client), and stays alive while calls should be served; when it returns the URL deactivates and its result becomes serve's result. Cancelling the run cancels subscriber and deactivates the URL the same way. The subscriber's effects flow to the caller's handlers unchanged; the served agents are self-contained (their effects are handled, or are at most io and this module's throws), so any agent fits once its own effects are handled. A served tool that throws or panics with no handler of its own cancels the whole endpoint (its failure proxies up and fails the run unless caught above subscriber) — wrap a tool's body in a handler for per-request resilience.

The OAuth token could not be resolved for a TRANSIENT reason — a network error, or the token endpoint failing (5xx) while refreshing. Thrown by token. Catch it to control retry — a retried call re-resolves. (A credential that needs a human to (re)authorize is never a throw: the run pauses on an authorization escalation instead.)

Resolve a usable OAuth bearer token for the stored credential name, as a private string (the token is tainted secret and may flow only to a submission sink — an http Authorization header — never to a user-facing boundary). The runtime holds the token material and refreshes it on demand, so no token ever enters the program. When name has no usable token (never authorized, or refresh-dead), the run PAUSES on a prelude.oauth.authorize escalation and resumes once the credential is established (the runtime-hosted browser flow, or a proactive login) — it does not fail. A transient resolution failure throws server_error (catchable with use handler { request throw(error: oauth.server_error) -> never { ... } }); uncaught, it fails the run.

Read the value under key, or null when the key is absent.

A copy of the record with value under key (replacing an existing entry).

A copy of the record without key (unchanged when the key is absent).

Every key, in sorted order.

Whether key is present.

The number of entries.

Every entry as a [key, value] pair, in sorted key order — the record's for-iterable view.

Every value, in sorted key order — the value-side counterpart of keys.

The two records' entries in one record; on a shared key the right value wins (the override direction of layered configuration, e.g. default headers extended per call).

The empty record.

The public metadata of one callable: its (qualified) name, its @"..." description, and the JSON Schemas of its input, output and requests — each schema a plain document value, ready to embed in an AI tool list. A local (closure) callable has an empty name.

Derive agent_metadata from a callable value (a top-level agent, a data constructor, a request, an external, a local closure, or a runtime-minted tool such as an MCP server's). A generic callable instantiated with [T] yields schemas specialised to the instantiation; a runtime-minted tool yields the name / description / input schema its provider declared.

A dynamic dispatch failed before the target ran: the target is not a callable, or args does not conform to its input schema (message names the offending path). Thrown by call_agent.

Invoke a callable VALUE with a runtime-built argument record — dynamic dispatch for a target an AI picked out of a tool list. args is validated against the target's input schema at the delegation boundary; a mismatch throws call_error at this call site (catch it to let the model retry). The target's effects flow through unchanged.

The built-in nursery scope: a nullary phantom marker, carried in a fiber's effect row and every operation's row, never performable, never handleable. provide mints it for its continuation and discharges it from its own row, so a fiber cannot outlive its nursery. Declare your own marker per nursery when nesting, so two regions' scopes never merge.

Open a nursery for the extent of continuation, as a scoped provider — the use region.provide[region.scope, E](...) form. It hands continuation a nursery[Scope, E] handle whose fibers may raise at most the effects E, and settles with the continuation's result. Scope rides the continuation's row (that is what a fork / join / cancel / watch raises) and is DISCHARGED from provide's own row, so no fiber outlives the block: the nursery closes when continuation returns (its still-running fibers are cancelled). Pin Scope and the ceiling E as the first two type arguments (region.provide[region.scope, my_effects]); R and the residual outer row are inferred from the continuation. Discharging Scope is provide's alone (only it opens the nursery), so a live join context cannot be forged. NEST UNDER DISTINCT MARKERS: share one marker across two nurseries and their scopes MERGE (fibers become mutually joinable), so declare a module-local effect per nursery when nesting.