@xenosystem/blocks 0.4.0 → 0.5.0

package/dist/transport-B1cdciP8.d.ts

@@ -0,0 +1,787 @@
+import { XenoValue, XenoQuery, XenoColumn, XenoSchemaCatalog, XenoResultSet } from '@xenosystem/data-core';
+
+/**
+ * The `xeno.core.connectors` contract.
+ *
+ * This panel is the data family's **capability holder** and its **resolver**. Every other panel in
+ * the family declares `storage.local` and nothing else *because this one exists*. It is also the one
+ * place in the catalog where getting security wrong has consequences beyond a bad pixel.
+ *
+ * @module
+ */
+
+/**
+ * How a REST source pages — **declared, never guessed**.
+ *
+ * The four styles below are the whole of what the survey found in real connector configs, and they
+ * are genuinely incompatible: `offset` counts rows, `page` counts pages, `cursor` carries an opaque
+ * token forward, and `link-header` puts the next URL in an RFC 8288 header where no amount of body
+ * inspection will find it. Collapsing them into one "pagination" bag with three optional parameter
+ * names — which is what the previous shape did — makes every one of them a special case at the call
+ * site, and makes `page.total` a guess.
+ *
+ * `hasMore` is derived by **over-fetching one row** for every style except `cursor`/`link-header`,
+ * which say so themselves. A source that cannot report an exact total must leave `page.total`
+ * undefined; a locally-filtered REST source reporting its unfiltered total is a silent lie (§5).
+ */
+type XenoRestPaging = 
+/** One request, whatever comes back. */
+{
+    style: 'none';
+}
+/** `?limit=50&offset=100` — the row-counting style. */
+ | {
+    style: 'offset';
+    limitParam: string;
+    offsetParam: string;
+}
+/** `?per_page=50&page=3` — the page-counting style. `firstPage` is 1 for most APIs, 0 for some. */
+ | {
+    style: 'page';
+    limitParam: string;
+    pageParam: string;
+    firstPage?: number;
+}
+/**
+ * `?limit=50&cursor=abc` — the opaque-token style.
+ *
+ * `cursorPath` says where the NEXT cursor lives in the response body; without it the source can
+ * only ever return its first page, which is a silent one-page ceiling rather than an error.
+ */
+ | {
+    style: 'cursor';
+    cursorParam: string;
+    cursorPath: string;
+    limitParam?: string;
+    hasMorePath?: string;
+}
+/** RFC 8288 `Link: <…>; rel="next"`. GitHub's style, and invisible from the body. */
+ | {
+    style: 'link-header';
+    limitParam?: string;
+};
+/**
+ * Header names that may never appear in a persisted config.
+ *
+ * §6 L7 is a live bug in a shipped connector: it masks `password` on serialize and writes the mask
+ * back verbatim on load (so a round-trip *destroys* the credential), and it masks `password`
+ * **only** — leaving `headers`, where `Authorization: Bearer …` lives, in the clear. The fix is not
+ * a better mask. *A mask is not a security boundary.* The fix is to make the secret unrepresentable
+ * in the config at all: these names are refused at execution time and the value must come from
+ * `credentialRef`, which the host resolves on its own side of the transport seam.
+ */
+declare const SECRET_HEADER_NAMES: readonly string[];
+/**
+ * Reject header names that must not be persisted in a config.
+ *
+ * @param headers - Static headers from a connection config.
+ * @returns The offending names, lower-cased. Empty when the config is clean.
+ *
+ * @example
+ * ```ts
+ * secretHeaderNames({ Accept: 'application/json' })            // → []
+ * secretHeaderNames({ Authorization: 'Bearer abc' })           // → ['authorization']
+ * ```
+ */
+declare function secretHeaderNames(headers: Record<string, string> | undefined): string[];
+/**
+ * Normalize the deprecated `pagination` bag forward into a {@link XenoRestPaging}.
+ *
+ * An existing `.xapp` carrying the old shape keeps working; nothing has to be migrated on disk.
+ *
+ * @param paging - The explicit declaration, when present.
+ * @param legacy - The deprecated bag.
+ * @returns A paging declaration, defaulting to `{style: 'none'}`.
+ */
+declare function normalizePaging(paging: XenoRestPaging | undefined, legacy: {
+    limitParam?: string;
+    offsetParam?: string;
+    cursorParam?: string;
+} | undefined): XenoRestPaging;
+/** Every connection kind. */
+type XenoConnectionKind = 'inline' | 'file.csv' | 'file.json' | 'file.parquet' | 'rest' | 'graphql' | 'sql.postgres' | 'sql.mysql' | 'sql.sqlite' | 'sql.duckdb' | 'xeno.sheets' | 'xeno.post' | 'xeno.ledger';
+/**
+ * The connection config, **discriminated on `kind`**.
+ *
+ * ## Why this is a union and not a bag
+ *
+ * sheets' `DatabaseConnector` carries one flat config object for every kind, and that is precisely
+ * why its declared `graphql` kind falls into the *database* error branch: `executeQuery` switches on
+ * `rest` and lets everything else reach the SQL path, so a plain HTTP source dies with *"Database
+ * queries require main process IPC"* (§6 L13, a live bug).
+ *
+ * With a discriminated union the compiler forces every branch to be handled and forces every kind to
+ * carry only the fields it can actually use. **A missing `graphql` branch is a compile error, not a
+ * runtime message about the wrong subsystem.**
+ */
+type XenoConnectionConfig = {
+    kind: 'inline';
+    rows: unknown;
+    primaryKey?: string[];
+} | {
+    kind: 'file.csv';
+    /** An OPAQUE handle minted by the host's picker. **Never a path** — the panel cannot enumerate. */
+    fileRef: string;
+    /** Field separator. Absent means "sniff it" — see `sniffDelimiter`. */
+    delimiter?: string;
+    /** First row is a header. Default `true`. */
+    hasHeader?: boolean;
+    /** Text encoding the host decodes with. Default `'utf-8'`. */
+    encoding?: string;
+    /** Rows to skip before the header (banner lines above a CSV are common in exports). */
+    skipRows?: number;
+    /** Quote character. Default `"`. */
+    quote?: string;
+} | {
+    kind: 'file.json';
+    /** An OPAQUE handle minted by the host's picker. */
+    fileRef: string;
+    rootPath?: string;
+    /** Text encoding. Default `'utf-8'`. */
+    encoding?: string;
+    /** The file is newline-delimited JSON (one record per line) rather than one document. */
+    ndjson?: boolean;
+} | {
+    kind: 'file.parquet';
+    fileRef: string;
+} | {
+    kind: 'rest';
+    url: string;
+    method?: 'GET' | 'POST';
+    /** Header NAMES only — a value carrying a credential belongs behind `credentialRef`. */
+    headerNames?: string[];
+    /**
+     * Static headers.
+     *
+     * **Non-secret only, and enforced rather than requested:** {@link SECRET_HEADER_NAMES} are
+     * rejected at execution time, because a config bag is persisted verbatim into `.xapp` and one
+     * shipped connector already ships that exact bug (§6 L7 — it masks `password` and leaves
+     * `Authorization: Bearer …` in the clear). Anything authenticating belongs behind
+     * `credentialRef`, which the host resolves on its own side of the transport seam.
+     */
+    headers?: Record<string, string>;
+    /** Static, non-secret query parameters. */
+    params?: Record<string, string>;
+    /** JSONPath-ish root at which the row array lives. */
+    rootPath?: string;
+    /**
+     * How this source pages.
+     *
+     * @deprecated Superseded by {@link XenoRestPaging}. Still read, and normalized forward by
+     * `normalizePaging`, so an existing `.xapp` keeps working.
+     */
+    pagination?: {
+        limitParam?: string;
+        offsetParam?: string;
+        cursorParam?: string;
+    };
+    /** How this source pages, declared explicitly. */
+    paging?: XenoRestPaging;
+    /** Path to an exact total, when the source reports one (implies `exactTotal`). */
+    totalPath?: string;
+} | {
+    kind: 'graphql';
+    url: string;
+    /** The document. Host-validated when `allowRawQueries` is off. */
+    document: string;
+    variables?: Record<string, XenoValue>;
+    rootPath?: string;
+    /** Static, non-secret headers. Same enforcement as `rest`. */
+    headers?: Record<string, string>;
+    /**
+     * Variable names to bind paging into.
+     *
+     * GraphQL pages through *variables*, not query parameters, so the REST paging union does not
+     * transfer. Absent means the document handles its own paging.
+     */
+    paging?: {
+        limitVar?: string;
+        offsetVar?: string;
+        cursorVar?: string;
+        cursorPath?: string;
+    };
+    /** Path to an exact total. */
+    totalPath?: string;
+} | {
+    kind: 'sql.postgres' | 'sql.mysql';
+    host: string;
+    port?: number;
+    database: string;
+    /** Username only. The password lives behind `credentialRef` and never appears here. */
+    user?: string;
+    ssl?: boolean;
+    /** Default table/view. */
+    entity?: string;
+} | {
+    kind: 'sql.sqlite';
+    fileRef: string;
+    entity?: string;
+} | {
+    kind: 'sql.duckdb';
+    /**
+     * `'wasm'` runs DuckDB-WASM over **already-fetched buffers** — real SQL with **zero
+     * capabilities**, in-sandbox and web-exportable. `'file'` opens a database on disk and needs a
+     * host resolver.
+     */
+    mode: 'wasm' | 'file';
+    fileRef?: string;
+    /** Connection ids whose results are registered as tables for the WASM engine. */
+    sourceConnectionIds?: string[];
+    entity?: string;
+} | {
+    kind: 'xeno.sheets' | 'xeno.post' | 'xeno.ledger';
+    resourceId: string;
+};
+/** What a source can do for itself. Drives honest degradation AND `column.aggregatable`. */
+interface XenoConnectorCapabilities {
+    pushdown: {
+        filter: boolean;
+        sort: boolean;
+        group: boolean;
+        aggregate: boolean;
+        join: boolean;
+        limit: boolean;
+    };
+    /** Aggregate functions the source can compute. */
+    aggregates?: string[];
+    /** Filter operators the source understands. */
+    filterOps?: string[];
+    /** Schema introspection available. */
+    introspect: boolean;
+    /** The source pushes updates. */
+    live: boolean;
+    /** Writes accepted. */
+    writable: boolean;
+    /**
+     * The source can report an EXACT total row count.
+     *
+     * When `false` the resolver must leave `page.total` undefined and derive `hasMore` from an
+     * over-fetch — a locally-filtered REST source reporting its unfiltered total is a silent lie.
+     */
+    exactTotal: boolean;
+    /** Hard row ceiling. */
+    maxRows?: number;
+    /**
+     * Runtime facilities this kind needs.
+     *
+     * **`host.resolver` is deliberately NOT a `PanelCapability`.** It is modelled as *absence*: a kind
+     * whose `requires` cannot be satisfied in the current substrate renders `health: 'unsupported'`
+     * with `HOST_RESOLVER_REQUIRED`. No SDK change, consistent with the rejection of a
+     * `PanelHost.services.data` injection.
+     */
+    requires?: ('net.fetch' | 'fs.read' | 'host.resolver')[];
+}
+/**
+ * Connection health.
+ *
+ * `unconfigured` is a **fixable setup gap** and renders info-toned, not as an error — a platform the
+ * operator has not finished wiring is not a failure. `unsupported` means "requires a desktop host"
+ * in this sandbox.
+ */
+type XenoConnectionHealth = 'unknown' | 'ok' | 'degraded' | 'unconfigured' | 'unsupported' | 'error' | 'expired';
+/** Typed resolver errors. Never a raw 500, never an env-var name. */
+type XenoResolverErrorCode = 'AUTH_EXPIRED' | 'AUTH_REVOKED' | 'UNCONFIGURED' | 'HOST_RESOLVER_REQUIRED' | 'RATE_LIMITED' | 'TIMEOUT' | 'NETWORK'
+/** Its OWN code with its own remedy text — folding it into NETWORK loses the only actionable fix. */
+ | 'CORS_BLOCKED' | 'PARSE' | 'SCHEMA_MISMATCH' | 'ROW_LIMIT' | 'UNKNOWN';
+/** Runtime health, never persisted. */
+interface XenoConnectionStatus {
+    health: XenoConnectionHealth;
+    /** Host-authored sentence, rendered verbatim. */
+    message?: string;
+    code?: XenoResolverErrorCode;
+    /** Epoch ms of the last successful query. */
+    lastOkAt?: number;
+    /** Absolute epoch ms at which the credential expires. */
+    expiresAt?: number;
+}
+/** How often the connection re-queries. */
+interface XenoRefreshPolicy {
+    mode: 'manual' | 'interval' | 'live';
+    /** Normalized to ms. */
+    intervalMs?: number;
+}
+/**
+ * A connection. **Persisted verbatim into `.xapp`, and contains no secret.**
+ */
+interface XenoConnection {
+    id: string;
+    /** Display name. */
+    name: string;
+    /** Discriminator, mirroring `config.kind` so a caller can switch before narrowing. */
+    kind: XenoConnectionKind;
+    /** Kind-specific config. */
+    config: XenoConnectionConfig;
+    /**
+     * `'$cred:<id>[#dataKey]'` — **the only credential surface**. Three independent implementations
+     * converged on reference-by-id; nothing else about a secret ever reaches this panel.
+     */
+    credentialRef?: string;
+    /**
+     * Bumped by the host whenever the credential behind `credentialRef` changes.
+     *
+     * Part of the cache key, so a re-auth invalidates cached results without anyone remembering to.
+     */
+    credentialRefRev?: number;
+    refresh?: XenoRefreshPolicy;
+    capabilities: XenoConnectorCapabilities;
+    /** Bumped when the schema changes, so `fields` re-reads without polling. */
+    catalogRev?: number;
+    /**
+     * Column ids forming this source's primary key.
+     *
+     * 🔴 **Row identity, for every kind — not just `inline`.** A declared key is used verbatim as the
+     * row id, which is what lets a selection made in one panel mean the same record in another. The
+     * `inline` config has carried this since the beginning; every other kind resolved through the
+     * host executor and silently got a *synthesized positional* id instead, so a REST payload with a
+     * perfectly good `id` produced `src-…:0:4:d6ntwe` and every drill-down broke on the first sort.
+     *
+     * Resolution order is: this field → the executor's own `primaryKey` → conservative inference from
+     * the returned rows → a synthesized id. Declaring it is always better than being inferred.
+     */
+    primaryKey?: string[];
+    /** Free-form grouping/tagging. */
+    tags?: string[];
+}
+/**
+ * A connection plus its runtime state.
+ *
+ * `health` is **rebuilt as `unknown` on load and never persisted** — a stale "healthy" written into
+ * an `.xapp` is a lie, and the first thing a user does with a lie is trust it.
+ */
+interface XenoConnectionState {
+    connection: XenoConnection;
+    status: XenoConnectionStatus;
+    /** The last good result, kept so a failed refresh can keep serving rather than blanking. */
+    lastGoodAt?: number;
+    /** A query is in flight. */
+    busy?: boolean;
+}
+/** One field of a host-supplied credential form. */
+interface XenoCredentialField {
+    key: string;
+    label: string;
+    type: 'text' | 'password' | 'select' | 'textarea' | 'number' | 'boolean';
+    required?: boolean;
+    placeholder?: string;
+    /** Help text. */
+    description?: string;
+    options?: {
+        label: string;
+        value: string;
+    }[];
+    /** Show this field only when another field equals one of these values. */
+    showWhen?: {
+        key: string;
+        equals: (string | number | boolean)[];
+    };
+}
+/**
+ * The form descriptor a host sends when a credential is needed.
+ *
+ * **A descriptor, with no platform names** — the panel renders fields, it does not know that this is
+ * Stripe or Postgres. That is what lets one panel serve every connector without growing a registry
+ * of vendor-specific UI.
+ */
+interface XenoCredentialFormSpec {
+    /** Correlates the form with the `submit_credential` that answers it. */
+    requestId: string;
+    connectionId: string;
+    title: string;
+    /** How the credential is obtained. */
+    mode: 'form' | 'oauth-redirect' | 'oauth-loopback' | 'none';
+    fields?: XenoCredentialField[];
+    /** "Where do I get this?" */
+    docsUrl?: string;
+    /**
+     * For loopback OAuth: the EXACT redirect URI to register, rendered **verbatim**.
+     *
+     * Rendering it verbatim is what prevents the redirect-URI mismatch landmine: one implementation
+     * falls back to `localhost:3000` when three env vars are unset, another derives it from the
+     * loopback port. Showing the user the real string is the only reliable fix.
+     */
+    redirectUri?: string;
+    /** Host-authored explanation. */
+    message?: string;
+}
+/** What the panel emits when the user submits a credential form. */
+interface XenoCredentialSubmission {
+    requestId: string;
+    connectionId: string;
+    /** The entered values. Held in transient component state only, cleared immediately after. */
+    values: Record<string, string | number | boolean>;
+}
+/** The host's answer. **Never contains the values.** */
+interface XenoCredentialResult {
+    requestId: string;
+    connectionId: string;
+    credentialRef?: string;
+    credentialRefRev?: number;
+    status: XenoConnectionStatus;
+}
+/** A query arriving from a consumer panel. */
+interface XenoConnectorQueryRequest {
+    requestId: string;
+    query: XenoQuery;
+    /**
+     * Which panel asked.
+     *
+     * Correlation is per **(connectionId, requestorPanelId)**, not one global id: this panel is a
+     * fan-in, so N concurrent queries from N panels are all legitimate and a single outstanding slot
+     * would make each new one cancel the last.
+     */
+    requestorPanelId?: string;
+    connectionId?: string;
+}
+/** The split of a query into what the source runs and what the pipeline runs locally. */
+interface PushdownSplit {
+    /** Executed by the source. */
+    pushed: XenoQuery;
+    /** Executed locally through `@xenosystem/data-core`. */
+    local: XenoQuery;
+    /** Op names pushed down, for `result.stats`. */
+    pushedOps: string[];
+    /** Op names run locally, for `result.stats`. */
+    localOps: string[];
+}
+/** What a host-side executor is handed. */
+interface ConnectorExecuteInput {
+    connection: XenoConnection;
+    /** Only the pushed part. */
+    query: XenoQuery;
+    /** Row cap already clamped. */
+    limit: number;
+}
+/** What a host-side executor returns. */
+interface ConnectorExecuteOutput {
+    rows: unknown;
+    /** Set when the source knows its exact total AND declares `exactTotal`. */
+    total?: number;
+    /** More rows exist. Derived by the resolver from an over-fetch when the source cannot say. */
+    hasMore?: boolean;
+    columns?: XenoColumn[];
+    catalog?: XenoSchemaCatalog;
+    /**
+     * The primary key of the returned rows, when the executor knows it.
+     *
+     * A SQL executor reading a real catalog knows this for certain; a REST one usually does not.
+     * Supplying it outranks inference and produces `derivedFrom: 'introspect'` rather than `'sample'`.
+     */
+    primaryKey?: string[];
+    error?: {
+        code: XenoResolverErrorCode;
+        message: string;
+        retryable?: boolean;
+    };
+    scannedRows?: number;
+    executionMs?: number;
+}
+/** The panel's serialized state. */
+interface ConnectorsPanelState {
+    /** Connections, with `credentialRef` — **never a secret, never `health`**. */
+    connections: XenoConnection[];
+    /** The last query, per connection. */
+    lastQueries?: Record<string, XenoQuery>;
+    selectedId?: string;
+}
+/** What the controller exposes to its view. */
+interface ConnectorsViewState {
+    connections: XenoConnectionState[];
+    selectedId: string | null;
+    /** The credential form to render, when the host has asked for one. */
+    form: XenoCredentialFormSpec | null;
+    /** Connection ids with a query in flight. */
+    busy: string[];
+    /** The last error per connection. */
+    errors: Record<string, XenoConnectionStatus>;
+}
+/** Runtime facilities the current substrate provides. */
+interface SubstrateFacilities {
+    netFetch: boolean;
+    fsRead: boolean;
+    hostResolver: boolean;
+}
+/**
+ * Can this connection run here — and if not, why?
+ *
+ * Returns the honest degraded state rather than a stub. A kind that cannot open a TCP socket in
+ * QuickJS renders a disabled card with a reason; it never pretends to work and fails later.
+ *
+ * @param connection - The connection.
+ * @param facilities - What the substrate offers.
+ * @returns `null` when supported, else the status to display.
+ */
+declare function evaluateSupport(connection: XenoConnection, facilities: SubstrateFacilities): XenoConnectionStatus | null;
+/**
+ * The default capabilities for a kind.
+ *
+ * This is the capability matrix as code — including the one row that matters most:
+ * **`sql.duckdb` in `wasm` mode requires NOTHING.** DuckDB-WASM runs in-sandbox over
+ * already-fetched buffers, which is the honest bridge that gives real SQL to a web export and to
+ * `iframe-quickjs` with zero capabilities. The same kind in `file` mode needs a host resolver.
+ *
+ * @param config - The connection config (narrowed by kind).
+ * @returns Sensible default capabilities.
+ */
+declare function defaultCapabilitiesFor(config: XenoConnectionConfig): XenoConnectorCapabilities;
+/** A result set carrying a typed resolver error. */
+declare function errorResult(code: XenoResolverErrorCode, message: string, query?: XenoQuery, retryable?: boolean): XenoResultSet;
+
+/**
+ * The transport seams — how this panel reaches a network, a file, or a SQL engine **without ever
+ * holding a socket, a path, or a secret**.
+ *
+ * ## Why the seams look like this
+ *
+ * `XENO DATA PANELS - UNION SPEC.md` §4 rejected a `PanelHost.services.data` injection: it would
+ * make the data source invisible in the `.xapp` graph, which is precisely what a Retool competitor
+ * sells. The seam it accepted instead is `queryRequest` out / `result` in — *"query execution stays
+ * host-side; the panel never reads the network."*
+ *
+ * That leaves one question this file answers: **who owns the protocol?** If the host owned it too,
+ * every host would re-implement REST paging, JSONPath extraction, CSV quoting and the Arrow→JSON
+ * conversion, and would get them wrong in a different way each time. So the split is:
+ *
+ * - **The panel owns the protocol.** Paging, extraction, parsing, schema derivation, error
+ *   classification, over-fetch, clamping — all of it is in this package, unit-tested in Node.
+ * - **The host owns the act.** One `fetch`, one `readFile`, one SQL engine. Each is a narrow
+ *   function the host implements against whatever its substrate allows: a real `fetch` in-process,
+ *   a proxied allowlisted one under `iframe-quickjs`, none at all in a web export.
+ *
+ * ## The property that keeps the secret lock intact
+ *
+ * A request carries **`credentialRef`, never a credential**. The host resolves the reference and
+ * attaches the `Authorization` header (or the connection string, or the API key) on its side of the
+ * seam. The panel therefore *cannot* leak a token it never receives — the guarantee is structural,
+ * not a discipline someone has to remember.
+ *
+ * This is also why {@link XenoFetchResponse} is a plain object rather than a DOM `Response`: it has
+ * to survive `postMessage` to a sandbox proxy, and a `Response` does not.
+ *
+ * @module
+ */
+
+/** One outbound HTTP request. Structured-cloneable, so it can cross a sandbox boundary. */
+interface XenoFetchRequest {
+    /** Absolute URL, query string already built by the panel. */
+    url: string;
+    method: 'GET' | 'POST';
+    /**
+     * Non-secret headers only.
+     *
+     * A header carrying a credential is the host's business: it resolves {@link credentialRef} and
+     * merges the result in on its own side. One shipped connector stores `Authorization: Bearer …`
+     * in a plain config bag and serializes it in the clear (§6 L7); that is unrepresentable here.
+     */
+    headers?: Record<string, string>;
+    /** Request body, already serialized. */
+    body?: string;
+    /**
+     * The credential to apply, by reference.
+     *
+     * **The panel has no idea what this resolves to** and never sees the result.
+     */
+    credentialRef?: string;
+    /** Abort deadline in ms. The host is free to clamp it down, never up. */
+    timeoutMs?: number;
+    /** Cancellation, when the substrate supports it. */
+    signal?: AbortSignal;
+}
+/** One HTTP response, reduced to what the panel actually reads. */
+interface XenoFetchResponse {
+    status: number;
+    statusText?: string;
+    ok: boolean;
+    /** Header names **lower-cased** — HTTP header names are case-insensitive and hosts disagree. */
+    headers: Record<string, string>;
+    /** The body as text. The panel parses it; the host never guesses a content type. */
+    body: string;
+    /**
+     * The final URL after redirects, when the host can report it.
+     *
+     * Used only for relative `Link`-header resolution.
+     */
+    url?: string;
+}
+/**
+ * A failure the transport can name.
+ *
+ * A host that proxies a request **knows** whether it was blocked by CORS, timed out, or never left
+ * the machine. Handing that back as a code is what lets §6 L9 hold — `CORS_BLOCKED` keeps its own
+ * remedy text instead of being folded into a generic `NETWORK`, which is the difference between
+ * *"add this origin to your API's allow-list"* and *"something went wrong"*.
+ */
+declare class ConnectorTransportError extends Error {
+    readonly code: XenoResolverErrorCode;
+    readonly retryable: boolean;
+    constructor(code: XenoResolverErrorCode, message: string, retryable?: boolean);
+}
+/** The network seam. Supplied by the host; absent means "no network here". */
+type XenoConnectorFetch = (request: XenoFetchRequest) => Promise<XenoFetchResponse>;
+/**
+ * A file, by opaque reference.
+ *
+ * **The panel never enumerates paths and never learns one.** `fileRef` is a handle the host minted
+ * from its own picker — the same opaque-handle discipline `xeno-shell` uses for host-folder mounts,
+ * where raw paths deliberately never cross the bridge.
+ */
+interface XenoFileReadRequest {
+    fileRef: string;
+    /** Text encoding to decode with. Default `'utf-8'`. */
+    encoding?: string;
+    /** Read at most this many bytes. The panel asks; the host may return fewer, never more. */
+    maxBytes?: number;
+}
+/** What the host returns for a file read. */
+interface XenoFileReadResponse {
+    /** Decoded text. */
+    text: string;
+    /** Display name for the schema/catalog. **Never a full path.** */
+    name?: string;
+    /** Total size, when known — lets the panel say "truncated" honestly. */
+    byteLength?: number;
+    /** The host stopped early because {@link XenoFileReadRequest.maxBytes} was hit. */
+    truncated?: boolean;
+}
+/** The file seam. Supplied by the host; absent means "no disk here". */
+type XenoConnectorFileReader = (request: XenoFileReadRequest) => Promise<XenoFileReadResponse>;
+/** A table offered to the in-sandbox SQL engine. */
+interface XenoSqlTable {
+    /** The name the query will use. Validated before it reaches SQL — see `duckdb.ts`. */
+    name: string;
+    /** Plain row objects, already fetched by another connection. */
+    rows: Record<string, unknown>[];
+}
+/**
+ * The in-sandbox SQL engine seam.
+ *
+ * Deliberately **eight lines wide**, and deliberately not `@duckdb/duckdb-wasm`. Rule 8 of the
+ * package contract is that no panel takes a heavyweight runtime dependency: DuckDB-WASM is several
+ * megabytes of wasm plus a worker, and a static import would impose it on every consumer of this
+ * package including the ones that never open a SQL source — exactly the lucide mistake the catalog
+ * already paid for once.
+ *
+ * So the engine is an **optional peer resolved from the host**, like xterm in `panel-terminal`. The
+ * package ships a reference adapter on the `./duckdb` subpath; a host that already owns a DuckDB
+ * instance implements these three methods against its own and imports nothing extra.
+ */
+interface XenoSqlEngine {
+    /**
+     * Make `tables` queryable, replacing any previous registration of the same names.
+     *
+     * @param tables - The source results to expose.
+     */
+    register(tables: XenoSqlTable[]): Promise<void>;
+    /**
+     * Run a SELECT and return plain row objects.
+     *
+     * The adapter is responsible for Arrow→JSON conversion, including the `BigInt` and timestamp
+     * traps that make a naive `JSON.stringify` throw.
+     *
+     * @param sql - The statement.
+     * @returns Plain rows.
+     */
+    query(sql: string): Promise<Record<string, unknown>[]>;
+    /** Release the engine, its worker, and its registered buffers. */
+    dispose?(): Promise<void> | void;
+}
+/**
+ * Everything the executor may be given.
+ *
+ * Every field is optional, and **absence is meaningful**: a missing `fetch` is not a bug to work
+ * around, it is a substrate that has no network, and the executor renders that as a visible
+ * `unsupported` state rather than failing later at query time.
+ */
+interface ConnectorTransport {
+    /** HTTP. Enables `rest`, `graphql` and the first-party `xeno.*` kinds. */
+    fetch?: XenoConnectorFetch;
+    /** File reads. Enables `file.csv` and `file.json`. */
+    readFile?: XenoConnectorFileReader;
+    /** In-sandbox SQL. Enables `sql.duckdb` in `wasm` mode. */
+    sql?: XenoSqlEngine;
+    /** Default request deadline, ms. Default 30 000. */
+    timeoutMs?: number;
+    /** Ceiling on bytes read from a file. Default 32 MiB. */
+    maxFileBytes?: number;
+}
+/**
+ * The facilities a transport actually provides.
+ *
+ * Derived, never declared. The controller's own default is optimistic
+ * (`{netFetch: true, fsRead: true, hostResolver: true}`), which is right for a trusted host that
+ * supplies an executor but wrong as a *general* default: a connection that reports `ok` and then
+ * fails at query time is the "stub that fails later" the capability matrix exists to forbid.
+ *
+ * @param transport - The composed transport.
+ * @param hostResolver - Whether a host-side executor was supplied for `sql.*`.
+ * @returns What this substrate can honestly claim.
+ *
+ * @example
+ * ```ts
+ * const facilities = facilitiesOf({ fetch: browserFetch() }, false)
+ * // → { netFetch: true, fsRead: false, hostResolver: false }
+ * ```
+ */
+declare function facilitiesOf(transport: ConnectorTransport | undefined, hostResolver: boolean): {
+    netFetch: boolean;
+    fsRead: boolean;
+    hostResolver: boolean;
+};
+/** Options for {@link browserFetch}. */
+interface BrowserFetchOptions {
+    /**
+     * Resolve a `credentialRef` into headers to merge.
+     *
+     * Lives on the **host** side of the seam by construction: this function is composed by the host,
+     * and the panel only ever passes the reference through.
+     */
+    resolveCredential?: (ref: string) => Promise<Record<string, string>> | Record<string, string>;
+    /**
+     * Hosts this transport may talk to.
+     *
+     * `undefined` means unrestricted, which is only appropriate in-process. A sandboxed host **must**
+     * pass a per-connection allow-list — §4 of the connectors spec makes the proxied REST path
+     * "consented at grant time", and an allow-list is what consent means mechanically.
+     */
+    allowHosts?: string[];
+    /** The page origin, for the CORS heuristic. Defaults to `location.origin` when there is one. */
+    origin?: string;
+    /** Injectable `fetch`, for tests. */
+    impl?: typeof globalThis.fetch;
+}
+/**
+ * A `fetch`-backed transport for a **trusted, in-process** host.
+ *
+ * Not the sandboxed path: a sandboxed host proxies these requests through its main process and
+ * applies its own allow-list and consent. This exists so that a desktop host — `xeno-apps`, Sheets,
+ * Spectra — can wire live REST and GraphQL sources in one line.
+ *
+ * @param options - Credential resolution, allow-list, and a `fetch` override for tests.
+ * @returns A transport fetch.
+ *
+ * @example
+ * ```ts
+ * const panel = createConnectorsPanel({
+ *   transport: { fetch: browserFetch({ resolveCredential: vault.headersFor }) },
+ * })
+ * ```
+ */
+declare function browserFetch(options?: BrowserFetchOptions): XenoConnectorFetch;
+/**
+ * Turn a thrown `fetch` failure into a typed code — **honestly**.
+ *
+ * The browser deliberately refuses to tell JavaScript whether a cross-origin request was blocked by
+ * CORS: both a CORS rejection and a dead network surface as `TypeError: Failed to fetch` with no
+ * status. So this does not *claim* CORS; it claims it only when the one distinguishing fact is
+ * present — **the request was cross-origin and we know our own origin.** Same-origin failures, and
+ * any failure in an environment with no origin at all (Node, a worker without `location`), stay
+ * `NETWORK`, because asserting CORS there would be a guess dressed as a diagnosis.
+ *
+ * @param error - What `fetch` threw.
+ * @param target - The parsed request URL.
+ * @param origin - The page origin, if known.
+ * @param timeoutMs - The deadline that was in force.
+ * @returns A typed transport error.
+ */
+declare function classifyBrowserFetchFailure(error: unknown, target: URL, origin: string | undefined, timeoutMs: number): ConnectorTransportError;
+
+export { type XenoRefreshPolicy as A, type BrowserFetchOptions as B, type ConnectorExecuteInput as C, type XenoSqlTable as D, browserFetch as E, classifyBrowserFetchFailure as F, defaultCapabilitiesFor as G, errorResult as H, evaluateSupport as I, facilitiesOf as J, normalizePaging as K, secretHeaderNames as L, type PushdownSplit as P, type SubstrateFacilities as S, type XenoSqlEngine as X, type ConnectorExecuteOutput as a, type ConnectorsPanelState as b, type ConnectorsViewState as c, type XenoConnection as d, type XenoCredentialFormSpec as e, type XenoCredentialResult as f, type XenoConnectionStatus as g, type XenoConnectorQueryRequest as h, type XenoRestPaging as i, type XenoConnectorFetch as j, type XenoResolverErrorCode as k, type XenoConnectorFileReader as l, type ConnectorTransport as m, type XenoCredentialField as n, ConnectorTransportError as o, SECRET_HEADER_NAMES as p, type XenoConnectionConfig as q, type XenoConnectionHealth as r, type XenoConnectionKind as s, type XenoConnectionState as t, type XenoConnectorCapabilities as u, type XenoCredentialSubmission as v, type XenoFetchRequest as w, type XenoFetchResponse as x, type XenoFileReadRequest as y, type XenoFileReadResponse as z };