@particle-academy/fancy-connector-core 0.0.0

package/dist/index.d.ts

@@ -0,0 +1,2129 @@
+/**
+ * Posting a sequence as a CHAIN — the bug that is silent in every direction.
+ *
+ * ## What went wrong in the reference implementation
+ *
+ * A renderer split long copy into `(1/3)`, `(2/3)`, `(3/3)` and the connector
+ * posted each segment **top-level**, on two providers. Numbered like a thread,
+ * connected to nothing. Nothing threw; the send reported success; the numbering
+ * made it look deliberate, so a reader assumes the thread exists and they missed
+ * it.
+ *
+ * It was unreachable by any test, because the chaining lived inside a loop that
+ * needed a live session. So the chain builder here **takes the post function as
+ * an argument** — which is the entire reason this is a module rather than four
+ * lines inside a connector.
+ *
+ * ## The rule it encodes, which is one line and easy to reverse
+ *
+ * > **`root` is fixed at the top of the chain and never moves. `parent` advances
+ * > to whatever was just posted.**
+ *
+ * Reverse them and every message attaches to the first: a fan, not a thread —
+ * and the provider's response looks identical either way, which is why this
+ * needs a test rather than care.
+ *
+ * ## What it deliberately does NOT do
+ *
+ * No retry. Retry wraps ONE request (see `delivery.ts`); wrapping the chain
+ * would re-post every earlier segment when a later one failed, turning a partial
+ * send into a duplicated one. A partial chain is reported with what it did post,
+ * so a person can see exactly where it stopped.
+ */
+/**
+ * A reference to something already posted, as the provider identifies it.
+ *
+ * Opaque to this module: AT Protocol needs a uri **and** a cid, Mastodon needs
+ * one status id, Telegram needs a message id and a chat. A shape naming one
+ * provider's model would be wrong for the next one, so the chain carries
+ * whatever the poster returned and never reads inside it.
+ */
+type ChainRef = Record<string, string | number>;
+type ChainLinks<Ref extends ChainRef> = {
+    /** The top of the conversation. Fixed for the whole chain. */
+    root: Ref;
+    /** The message immediately above this one. Advances every step. */
+    parent: Ref;
+};
+type ChainOutcome<Ref extends ChainRef> = {
+    /** Everything that was posted, in order. */
+    posted: Ref[];
+    /** The failure that stopped it, if one did. */
+    failed?: {
+        index: number;
+        error: unknown;
+    };
+};
+/**
+ * Post `segments` as a connected chain, optionally starting inside an existing
+ * conversation.
+ *
+ * `post` is given the text and the links for this position — `undefined` for a
+ * top-level message — and returns the provider's reference to what it created.
+ *
+ * **Stops at the first failure and reports what it posted.** Continuing would
+ * produce a thread with a hole in it, and unwinding is not available: nothing
+ * here can delete a public message, and pretending otherwise would be worse than
+ * the hole.
+ */
+declare function postChain<Ref extends ChainRef>(segments: string[], answering: ChainLinks<Ref> | undefined, post: (text: string, links: ChainLinks<Ref> | undefined, index: number) => Promise<Ref>): Promise<ChainOutcome<Ref>>;
+
+/**
+ * The connector API version — what makes two release clocks safe.
+ *
+ * ## The problem this exists for
+ *
+ * The core and the connector catalogue are separate repositories, so they
+ * release on separate clocks. That is deliberate: a provider changing its API is
+ * a connector fix and must not wait on a core release. But it creates a hazard
+ * that is worse here than in an ordinary package pair, because **connectors ship
+ * as vendored source**:
+ *
+ * > A consumer copies a connector into their project. Six months later they
+ * > upgrade the core. Their copy of the connector was written against a core two
+ * > minors older, and pre-1.0 minors are allowed to break.
+ *
+ * Nothing in a version range catches that, because the vendored copy has no
+ * manifest of its own — it is just files in someone else's repository. And the
+ * failure is the quiet kind: the connector still compiles, still runs, and does
+ * something subtly different.
+ *
+ * ## The fix: a second number that moves far more slowly
+ *
+ * The core's package version tracks everything — fixes, additions, internal
+ * changes. `CONNECTOR_API_VERSION` tracks only one thing: **the surface a
+ * connector is written against.** Adding a module, fixing a classifier, or
+ * improving a message does not move it. Changing what a `Connector` must
+ * implement, renaming a field a connector declares, or altering what `render`
+ * returns does.
+ *
+ * So a core can go 0.3 → 0.9 without a single vendored connector caring, and the
+ * one release that does matter announces itself in a number a connector can
+ * check at import time rather than discover at run time.
+ *
+ * ## The support window, and why it is two rather than one
+ *
+ * The core accepts the current version **and the one before it**. One would mean
+ * every consumer has to re-vendor every connector on the same day the core ships
+ * — which nobody does, so in practice they would pin the core instead and stop
+ * getting fixes. Two gives a real window: the catalogue re-issues its connectors
+ * on the new version, consumers re-vendor when they next touch that connector,
+ * and the old shape keeps working until the version after next.
+ *
+ * More than two would be a promise we cannot keep, because it means maintaining
+ * a compatibility shim for a shape nobody has read in a year.
+ */
+/**
+ * The connector surface this core implements.
+ *
+ * **Bump this ONLY for a change a connector's own source can see**, and say in
+ * the changelog what a connector author must DO. If nothing in `connectors/`
+ * would have to change, it is not a connector API change.
+ */
+declare const CONNECTOR_API_VERSION = 1;
+/**
+ * Versions this core will run.
+ *
+ * Ordered newest first, purely so the error message reads naturally.
+ */
+declare const SUPPORTED_CONNECTOR_API: readonly number[];
+declare class ConnectorApiMismatch extends Error {
+    readonly connector: string;
+    readonly declared: number;
+    constructor(message: string, connector: string, declared: number);
+}
+/**
+ * Refuse a connector written against a surface this core does not implement.
+ *
+ * **Called at registration, not at call time.** A mismatch discovered on the
+ * first real request is a mismatch discovered in production; discovered when the
+ * catalogue is assembled, it is a build failure with a name attached.
+ *
+ * The message names the direction, because the two cases need opposite actions
+ * and are trivially confused:
+ *
+ * - **connector NEWER than the core** → upgrade the core.
+ * - **connector OLDER than the window** → re-vendor the connector.
+ *
+ * "Incompatible versions" sends someone to read source; naming which side is
+ * behind sends them to the command.
+ */
+declare function assertConnectorApi(connectorId: string, declared: number): void;
+/**
+ * Whether a core version satisfies a connector's declared minimum.
+ *
+ * Exists so a registry or a CLI can answer *before* vendoring, which is the only
+ * moment the answer is cheap. Compares the numeric prefix of each dotted
+ * segment, so a prerelease suffix does not make `0.4.0-rc.1` sort below `0.3.9`
+ * in a way nobody expected.
+ */
+declare function satisfiesMinimum(coreVersion: string, minimum: string): boolean;
+
+/**
+ * Failure classification — the one decision every retry gets wrong.
+ *
+ * ## The tension
+ *
+ * A network hiccup should not lose a call. And a retry after a request that
+ * **succeeded and whose response was lost** is a second write — the exact
+ * failure an idempotency gate exists to prevent, arriving through the door
+ * marked *reliability*.
+ *
+ * Nearly every retry helper reconciles those the same way and loses: it catches
+ * an error, waits, and tries again, because from the caller's side all failures
+ * look alike. They are not alike.
+ *
+ * | what happened | did the provider receive it? | retry? |
+ * |---|---|---|
+ * | DNS failure, connection refused, socket reset before send | **no** | always safe |
+ * | HTTP 429 / 5xx | **yes**, and it explicitly refused | safe — it says it did nothing |
+ * | timeout, aborted request, unrecognised error | **unknown** | only where the provider is idempotent |
+ * | HTTP 4xx that is not 429 | **yes**, and the answer was a real no | never |
+ *
+ * That third row is the whole design. A timeout looks exactly like a failure and
+ * may have been a success.
+ *
+ * ## Why this is a separate axis from the error CLASS
+ *
+ * The first version of this runtime carried `retryable` as a fixed boolean on
+ * each error class, and `ConnectorTransient` covered both a 5xx *and* a thrown
+ * transport. Those are opposite cases: a 5xx is the provider telling you it did
+ * nothing, and a thrown transport may be a socket that closed after the bytes
+ * went out. Marking both `retryable = true` meant an ambiguous failure on a
+ * connector with no idempotency key was retried — a silent double write, on the
+ * path whose entire job is not producing one.
+ *
+ * So the primitive is the **kind**, and retryability is a function of the kind
+ * AND what the connector declared about repeating a request. `error.retryable`
+ * survives and now answers the narrower question — *is this safe to retry
+ * whatever the connector is?* — which makes an old caller conservative rather
+ * than wrong.
+ */
+/** Why a call failed, in the only terms that decide whether to try again. */
+type FailureKind = 
+/** Never reached the provider. A second attempt cannot duplicate anything. */
+"unreachable"
+/** The provider answered, and its answer was "not now". It did nothing. */
+ | "refused-explicitly"
+/** It may or may not have been acted on. Nobody can tell. */
+ | "ambiguous"
+/** The provider answered and the answer was a real, permanent no. */
+ | "rejected";
+/**
+ * How a connector behaves when a call goes wrong, and how fast it may be used.
+ *
+ * **`idempotent` is the load-bearing field**, and it is the only thing that
+ * makes an ambiguous failure safe to retry. A connector that has not thought
+ * about it gets `false`, and an ambiguous failure is then reported for a person
+ * instead of retried into a double write.
+ */
+type DeliveryDeclaration = {
+    idempotent: boolean;
+    /**
+     * Why it is or is not — **cited, not asserted**.
+     *
+     * `idempotent: true` with no reason is the one claim whose failure is a public
+     * double write, so the reason names the mechanism (`Idempotency-Key`,
+     * `com.atproto.repo.createRecord` having none) rather than restating the flag.
+     */
+    why: string;
+    /** Smallest gap between two calls on this connector. */
+    minIntervalMs: number;
+    /**
+     * Whose number `minIntervalMs` is.
+     *
+     * A confident figure nobody can cite is worse than an honest one that is too
+     * slow, because the honest one gets revised when evidence turns up and the
+     * confident one gets quoted as a platform fact.
+     */
+    rateSource: "documented" | "self-imposed";
+    /** Where the numbers came from. See `citation.ts`. */
+    citation?: Citation;
+};
+/**
+ * Where a declared fact was read, and when.
+ *
+ * A citation with no date is an assertion wearing a URL. The date is what lets a
+ * drift check say *this was true eight months ago and nobody has looked since*,
+ * which is a different and more useful statement than *this is true*.
+ */
+type Citation = {
+    /** The provider's own documentation for this fact. */
+    url: string;
+    /** ISO date the URL was actually read by a person or a check. */
+    readOn: string;
+    /** The sentence the fact rests on, quoted. Optional but strongly wanted. */
+    quote?: string;
+};
+type Classified = {
+    kind: FailureKind;
+    detail: string;
+    /** Seconds the provider asked us to wait, when it said so. */
+    retryAfter?: number;
+};
+/**
+ * Classify a thrown transport failure.
+ *
+ * **An unrecognised error falls to `ambiguous`, never to `unreachable`.** That
+ * asymmetry is deliberate: an unknown failure treated as unreachable would be
+ * retried, and the one thing worse than a lost call is two calls nobody asked
+ * for. Guessing in the safe-looking direction is how this goes wrong.
+ */
+declare function classifyError(error: unknown): Classified;
+/**
+ * Classify an HTTP status.
+ *
+ * A status means the provider answered, so it knows what it did. 429 and 5xx are
+ * "not now"; everything else in the 4xx range is a real no, and retrying a real
+ * no just spends someone's rate limit on the same rejection.
+ *
+ * 429 is decided **before** the 4xx sweep, because it is a 4xx and is the one
+ * 4xx worth retrying — the other ordering marks every throttle permanent and
+ * turns a busy minute into a failed run.
+ */
+declare function classifyStatus(status: number, body?: string, retryAfterHeader?: string | null): Classified;
+type RetryPolicy = {
+    /** Total attempts, including the first. */
+    attempts: number;
+    /** First backoff in ms. Doubles each attempt. */
+    baseDelayMs: number;
+    /** Never wait longer than this between attempts. */
+    maxDelayMs: number;
+    /**
+     * Whether the provider makes a repeated request harmless.
+     *
+     * `false` is the correct default for any connector that has not proven
+     * otherwise, and "proven" means a test that publishes twice and compares the
+     * result — not a comment.
+     */
+    idempotent: boolean;
+};
+declare const DEFAULT_RETRY: RetryPolicy;
+/**
+ * May this failure be retried?
+ *
+ * The whole rule, in four lines, in one place. A connector that classified its
+ * own statuses would eventually decide some 4xx was worth retrying, and the
+ * reason retries are safe at all is that this decision is made once.
+ */
+declare function shouldRetry(kind: FailureKind, policy: Pick<RetryPolicy, "idempotent">): boolean;
+/**
+ * True where a retry is safe **whatever the connector is** — i.e. without
+ * needing to know whether repeating the request is harmless.
+ *
+ * This is what `ConnectorError.retryable` answers, and it is deliberately the
+ * narrow question. A caller that has an idempotency declaration should ask
+ * `shouldRetry` instead and get the extra case.
+ */
+declare function isUnconditionallyRetryable(kind: FailureKind): boolean;
+type Attempt = {
+    attempt: number;
+    kind: FailureKind;
+    detail: string;
+    /** How long we waited before the NEXT attempt. Absent on the last. */
+    waitedMs?: number;
+};
+type DeliveryOutcome<T> = {
+    ok: boolean;
+    value?: T;
+    /** Every attempt that failed, in order. Empty when the first one worked. */
+    attempts: Attempt[];
+    /** Why it stopped, when it failed. Written for a person who has to act. */
+    gaveUp?: string;
+    /** The classification of the last failure, so a host can route on it. */
+    kind?: FailureKind;
+};
+/**
+ * The message a person reads when an ambiguous failure could not be retried.
+ *
+ * Exported because a host will want to recognise it, and because the wording is
+ * load-bearing: it has to say *go and look*, not *it failed*. Those prompt
+ * different actions and only one of them is correct.
+ */
+declare const AMBIGUOUS_REFUSAL: string;
+/**
+ * Run ONE request, retrying only where retrying is provably safe.
+ *
+ * ## Retry wraps ONE request, never a sequence
+ *
+ * Wrapping a multi-post publish would re-send every earlier segment of a thread
+ * when a later one failed — turning a partial send into a duplicated one. So the
+ * unit is a single request and a chain composes above it, not below.
+ *
+ * `send` must throw on failure. An error carrying a `classified` property (see
+ * `httpFailure`) is trusted; anything else is classified here. That indirection
+ * lets each connector decide what counts as a failure for it — a Telegram
+ * `200 OK` with `{"ok": false}` is a failure and only the connector knows that —
+ * while the decision about *retrying* stays in one place for all of them.
+ *
+ * `sleep` is injectable so a test proves the real backoff schedule without
+ * waiting for it. A test that actually slept would be slow enough that somebody
+ * would eventually shorten the delays to speed it up, and then the thing under
+ * test would be the shortened version.
+ */
+declare function deliver<T>(send: (attempt: number) => Promise<T>, policy?: RetryPolicy, sleep?: (ms: number) => Promise<void>): Promise<DeliveryOutcome<T>>;
+/**
+ * Wait until this channel may be used again.
+ *
+ * In-process only, and that is the correct scope for a host running on one
+ * machine. A host that fans out across processes owns the coordination, because
+ * the package cannot see the other senders and pretending otherwise would be a
+ * limiter that reports success while doing nothing.
+ */
+declare function respectRate(channel: string, minIntervalMs: number, now?: () => number, sleep?: (ms: number) => Promise<void>): Promise<{
+    waitedMs: number;
+}>;
+/** Only for tests — the map is module-global and would leak between them. */
+declare function resetRateState(): void;
+
+/**
+ * The faker layer — every connector ships one, always.
+ *
+ * ## Why every connector, and not just the ones without a sandbox
+ *
+ * A sandbox still needs an account, a key, a network, and a provider that is
+ * up. That is four ways for someone evaluating the kit to get nothing working,
+ * before they have learned anything about the kit. A faker removes all four:
+ * vendor a node, drop it on a canvas, press run, see a shaped result.
+ *
+ * It is also what makes the golden fixtures honest. Fixtures run on both
+ * runtimes and are the publish gate; if they needed a network they would either
+ * be skipped in CI or be flaky, and a flaky gate is one people learn to
+ * re-run rather than read.
+ *
+ * ## Deterministic, not random
+ *
+ * Same inputs, same output — always. A faker that returns a fresh uuid every
+ * call cannot be asserted on, so its fixtures degrade to "it did not throw",
+ * which is the assertion that catches nothing. Values here are derived from a
+ * seed built out of the service, the operation and the request, so two runs
+ * agree and two runtimes can be compared to each other.
+ *
+ * The values are obviously fake ON PURPOSE — `fake_`-prefixed ids, `example.test`
+ * hosts, round numbers. Nobody should ever look at a faked result and wonder
+ * whether it moved real money.
+ */
+/** A faker: one function per service, switching on the operation. */
+type ConnectorFaker = (operation: string, request: FakeRequest) => unknown;
+type FakeRequest = {
+    /** The node's resolved config. */
+    config: Record<string, unknown>;
+    /** The value on the incoming wire. */
+    input?: unknown;
+    /** Deterministic helpers, seeded from service + operation + config. */
+    fake: FakeValues;
+};
+/**
+ * Deterministic value helpers handed to a faker.
+ *
+ * Small on purpose. A faker's job is to return the SHAPE the provider returns —
+ * the field names a downstream node will reference — not to simulate the
+ * provider's business logic.
+ */
+type FakeValues = {
+    /** A stable id with the provider's usual prefix: `id("ch")` → `ch_fake_1a2b3c`. */
+    id: (prefix: string) => string;
+    /** A stable integer in `[min, max]`. */
+    int: (min: number, max: number) => number;
+    /** Pick a stable element of a list. */
+    pick: <T>(options: readonly T[]) => T;
+    /** A fixed ISO-8601 instant, offset by whole seconds. Never `Date.now()`. */
+    timestamp: (offsetSeconds?: number) => string;
+    /** A stable lowercase hex string of `length` characters. */
+    hex: (length: number) => string;
+};
+/**
+ * The instant every faker counts from.
+ *
+ * A constant rather than the clock, because a fixture asserting on `createdAt`
+ * must not start failing tomorrow. Chosen to be recognisably synthetic.
+ */
+declare const FAKE_EPOCH = "2026-01-01T00:00:00.000Z";
+/** FNV-1a. Small, dependency-free, and stable across both runtimes. */
+declare function seedFrom(...parts: unknown[]): number;
+/** Build the deterministic helpers for one faked call. */
+declare function fakeValues(seed: number): FakeValues;
+/** Build the request handed to a faker, with helpers already seeded. */
+declare function fakeRequest(service: string, operation: string, config: Record<string, unknown>, input?: unknown): FakeRequest;
+
+/**
+ * Which copy of a provider a connector talks to — and who decides.
+ *
+ * Three modes, and the third is the one that makes this marketplace usable:
+ *
+ * | mode      | talks to                    | needs credentials | needs network |
+ * |-----------|-----------------------------|-------------------|---------------|
+ * | `live`    | the provider, for real      | yes               | yes           |
+ * | `sandbox` | the provider's test estate  | yes (test ones)   | yes           |
+ * | `fake`    | the node's own faker        | no                | no            |
+ *
+ * ## The environment is the DEFAULT, never the constraint
+ *
+ * A locally-hosted project defaults to sandbox. It is not *pinned* to sandbox:
+ * an author who explicitly asks for `live` on their laptop gets `live`, because
+ * the alternative — an environment that silently overrides a stated intention —
+ * produces the worst outcome available here, which is a workflow that reports
+ * success while having charged nobody. Equally, `sandbox` set explicitly stays
+ * sandbox in production, which is how you stage a connector before cutting it
+ * over.
+ *
+ * So: explicit beats the connection, the connection beats the environment.
+ *
+ * ## Why "fake" is a MODE and not a test double
+ *
+ * Every connector ships a faker (see `faker.ts`), and it is reachable the same
+ * way in a test, in a demo and on a laptop with no credentials. Making it a
+ * separate mechanism — a mock injected only under test — would mean the code
+ * path a consumer develops against is not the one that runs, and the fixtures
+ * would prove nothing about the executor.
+ */
+/** The three environments a connector node can run against. */
+type ConnectorMode = "fake" | "sandbox" | "live";
+/** What a node's `mode` config field may say. `auto` means "let the rules decide". */
+type RequestedMode = ConnectorMode | "auto";
+declare const CONNECTOR_MODES: ConnectorMode[];
+/**
+ * How a provider exposes its test estate — the four shapes that actually exist.
+ *
+ * This is data, not per-node code, because getting it wrong is the difference
+ * between hitting a test ledger and hitting a real one. Verified per provider in
+ * `.ai/plans/fancy-flow-connector-nodes.md`; a node declares which of the four
+ * it is and the core does the rest.
+ *
+ * - `credential` — same base URL, a test-scoped key selects the estate
+ *   (Stripe's `sk_test_…`). The trap: pointing a live key at it works, so the
+ *   only guard is the key itself.
+ * - `base-url` — a different host entirely (PayPal's `api-m.sandbox.paypal.com`).
+ * - `separate-account` — a distinct tenant you must create, often with its own
+ *   login host (Salesforce sandbox orgs on `test.salesforce.com`).
+ * - `none` — the provider has no test estate. `sandbox` is then not offered at
+ *   all, and the node's honest choices are `fake` and `live`.
+ */
+type SandboxKind = "credential" | "base-url" | "separate-account" | "none";
+/** The host's view of where it is running. Kept tiny so it is trivial to fake. */
+type HostEnvironment = {
+    /** True only in a real production deployment. Everything else is "local". */
+    production: boolean;
+};
+type ModeInputs = {
+    /** What the node's config asked for. `undefined` / `"auto"` means "decide". */
+    requested?: RequestedMode | null;
+    /** A mode pinned on the CONNECTION, if the host pinned one. */
+    connectionMode?: ConnectorMode | null;
+    /** Whether the provider has a test estate at all. */
+    sandbox: SandboxKind;
+    /** Whether the connection actually carries credentials for the sandbox estate. */
+    hasSandboxCredentials: boolean;
+    environment: HostEnvironment;
+};
+/**
+ * Resolve the mode a connector call runs in.
+ *
+ * Deliberately a pure function of stated facts, so both runtimes can be held to
+ * the same table of cases and a host can unit-test its own wiring without a
+ * network or a provider.
+ */
+declare function resolveConnectorMode(inputs: ModeInputs): ConnectorMode;
+/** Raised when a requested mode cannot be honoured. Never downgraded silently. */
+declare class ConnectorModeError extends Error {
+    constructor(message: string);
+}
+/** True when the mode reaches the provider over the network. */
+declare function isRemote(mode: ConnectorMode): boolean;
+
+/**
+ * A CONNECTION — credentials plus an environment choice — configured once per
+ * service and referenced by every node that uses it.
+ *
+ * ## Why this is not per-node config
+ *
+ * The obvious design is to put an API key field on each node. It is also wrong,
+ * for three reasons that only show up later:
+ *
+ * 1. **Rotation.** A key on twelve nodes is twelve edits and one you will miss.
+ * 2. **The sandbox/live switch has to live somewhere singular.** If each node
+ *    carries its own, a graph can be half in the test estate and half in the
+ *    real one, and nothing about the canvas shows it.
+ * 3. **Credentials would be in the graph.** A `WorkflowSchema` is plain JSON
+ *    that gets exported, committed, MCP'd to an agent and pasted into issues.
+ *    Nothing secret may ever be in it.
+ *
+ * So a node's config stores a **connection id** — an opaque, non-secret name
+ * like `"stripe"` or `"stripe-eu"` — and the host resolves it to credentials at
+ * run time. This is the same arrangement fancy-flow already uses for LLM clients
+ * and `fancy-git` uses for providers: the node cannot reach for a credential,
+ * the host has to hand one over.
+ *
+ * ```ts
+ * registerConnectionHost({
+ *   environment: { production: process.env.NODE_ENV === "production" },
+ *   connections: {
+ *     stripe: {
+ *       service: "stripe",
+ *       live:    { secretKey: process.env.STRIPE_SECRET_KEY },
+ *       sandbox: { secretKey: process.env.STRIPE_TEST_SECRET_KEY },
+ *     },
+ *   },
+ * });
+ * ```
+ *
+ * Note what is NOT here: no key, no token, no placeholder that looks like one.
+ * Credentials are configuration, and configuration comes from the consumer's
+ * environment.
+ */
+
+/**
+ * Credentials for one estate. Values are opaque strings the node's auth
+ * strategy understands — `secretKey`, `clientId`/`clientSecret`, `token`.
+ */
+type ConnectionCredentials = Record<string, string | undefined>;
+/** One configured connection to one service. */
+type ConnectionSpec = {
+    /** The service this connection is for — must match the node's `connector.service`. */
+    service: string;
+    /** Human label, shown in the picker. Defaults to the id. */
+    label?: string;
+    /**
+     * Pin this connection to a mode. Optional, and usually absent: leaving it
+     * unset is what lets the environment supply the default.
+     */
+    mode?: ConnectorMode;
+    live?: ConnectionCredentials;
+    sandbox?: ConnectionCredentials;
+    /**
+     * Override the base URL per mode. Only needed for a `separate-account`
+     * provider whose tenant has its own host (a Salesforce instance URL); the
+     * `base-url` providers carry theirs in the node's service descriptor.
+     */
+    baseUrl?: Partial<Record<ConnectorMode, string>>;
+};
+type ConnectionHost = {
+    environment: HostEnvironment;
+    connections: Record<string, ConnectionSpec>;
+};
+/**
+ * Install the host's connections. Returns an unregister function.
+ *
+ * One registration for the whole app, matching how a person thinks about it:
+ * you authorize Stripe once, then every node that needs Stripe already has it.
+ */
+declare function registerConnectionHost(next: ConnectionHost | null): () => void;
+declare function getConnectionHost(): ConnectionHost | null;
+/** Connection ids the host has configured for a service — feeds the picker. */
+declare function connectionsFor(service: string): Array<{
+    id: string;
+    label: string;
+}>;
+/** What a node's executor actually needs, once everything has been resolved. */
+type ResolvedConnection = {
+    id: string;
+    service: string;
+    mode: ConnectorMode;
+    /** Empty in `fake` mode — there is nothing to authenticate against. */
+    credentials: ConnectionCredentials;
+    /** Undefined in `fake` mode. */
+    baseUrl?: string;
+};
+type ResolveOptions = {
+    service: string;
+    operation: string;
+    /** The connection id from host config. Defaults to the service name. */
+    connectionId?: string | null;
+    /** The mode the caller asked for. */
+    requested?: RequestedMode | null;
+    /**
+     * Credentials handed straight in, bypassing the registry entirely.
+     *
+     * The primary path for a host that already owns credential storage and has no
+     * wish to hand a package a second copy: it passes them per call, this resolver
+     * does not consult any global, and there is nothing to initialise. The
+     * registry below remains for hosts that prefer to configure once.
+     *
+     * An EMPTY object is not the same as `null`: it means "the caller supplied
+     * credentials and there are none", which fails the `requires` check loudly
+     * rather than falling through to the registry and silently using someone
+     * else's.
+     */
+    credentials?: ConnectionCredentials | null;
+    sandbox: SandboxKind;
+    /** Base URL per mode, from the node's service descriptor. */
+    baseUrls?: Partial<Record<ConnectorMode, string>>;
+    /** Credential keys that must be present for a remote call. */
+    requires?: string[];
+};
+/**
+ * Resolve the connection and mode for one call.
+ *
+ * ## `fake` needs no host at all
+ *
+ * A freshly vendored connector runs before anything is configured, and that is
+ * deliberate: it is the difference between a marketplace someone can try and
+ * one they can only read about. So the no-host case resolves to `fake` rather
+ * than throwing — UNLESS the author explicitly asked for a remote mode, in
+ * which case the ask is honoured by failing loudly instead of quietly doing
+ * something else.
+ */
+declare function resolveConnection(options: ResolveOptions): ResolvedConnection;
+
+/**
+ * The one call path every connector uses.
+ *
+ * A connector never chooses between "call the provider" and "call the faker" —
+ * it describes the request it wants and hands it here. That is the point: the
+ * code path a consumer develops against with no credentials is the same code
+ * path that runs in production, so fixtures prove something about the connector
+ * rather than about a mock.
+ *
+ * ```ts
+ * const charge = await callConnector(STRIPE, {
+ *   operation: "charge_create",
+ *   credentials,
+ *   request: { method: "POST", path: "/v1/charges", form: { amount, currency } },
+ *   idempotencyKey,
+ *   idempotent: true,
+ * });
+ * ```
+ *
+ * ## What changed from the first version of this runtime, and why
+ *
+ * The old loop caught a thrown transport, called it transient, and retried it.
+ * A thrown transport includes a **timeout**, which may be a request the provider
+ * received and acted on — so on a connector with no idempotency key that retry
+ * is a silent double write. Retrying is now a function of the classification AND
+ * the connector's declared idempotency, and `idempotent` defaults to `false`
+ * because a connector that has not thought about it must not be assumed safe.
+ *
+ * See `delivery.ts` for the full table.
+ */
+
+/**
+ * Everything true of a SERVICE rather than of one operation.
+ *
+ * One per provider, declared once and shared by that provider's connectors. It
+ * is data — base URLs, required credential keys, how the sandbox is selected —
+ * so that facts verified against provider documentation live in exactly one
+ * reviewable place instead of being retyped into each connector.
+ */
+type ServiceDescriptor = {
+    service: string;
+    title: string;
+    sandbox: SandboxKind;
+    /**
+     * Base URL per mode. A `credential`-sandbox provider gives the same URL for
+     * both, which is itself worth writing down: it is why a live key pointed at
+     * "sandbox" quietly reaches production.
+     */
+    baseUrls: Partial<Record<ConnectorMode, string>>;
+    /** Credential keys a remote call cannot proceed without. */
+    requires: string[];
+    /**
+     * Apply the provider's auth scheme to an outgoing request.
+     *
+     * A FUNCTION rather than a declarative header name, because there is no common
+     * shape: the key can be a header (under any of a dozen names), a Basic
+     * username with a blank password, a query parameter, a body field, or a URL
+     * path segment — and several providers need more than one at once. It receives
+     * the resolved mode too, because for some providers auth and estate are the
+     * same decision expressed in the URL.
+     */
+    authorize: (credentials: ConnectionCredentials, request: PreparedRequest, mode: ConnectorMode) => void | Promise<void>;
+    /** The service's faker. Required — see `faker.ts`. */
+    faker: ConnectorFaker;
+    /** Header the provider uses for idempotency, when it has one. */
+    idempotencyHeader?: string;
+};
+type ConnectorRequest = {
+    method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+    path: string;
+    query?: Record<string, string | number | boolean | undefined>;
+    headers?: Record<string, string>;
+    /** JSON body. Mutually exclusive with `form`. */
+    json?: unknown;
+    /** `application/x-www-form-urlencoded` body — what several payment APIs want. */
+    form?: Record<string, string | number | boolean | undefined>;
+};
+type PreparedRequest = {
+    method: string;
+    url: string;
+    headers: Record<string, string>;
+    body?: string;
+};
+/** The HTTP seam. A host may swap it; nothing here assumes a browser or Node. */
+type Transport = (request: PreparedRequest) => Promise<TransportResponse>;
+type TransportResponse = {
+    status: number;
+    headers: Record<string, string>;
+    body: string;
+};
+type CallOptions = {
+    operation: string;
+    /**
+     * Credentials, passed IN.
+     *
+     * **Nothing in this package reads `process.env`.** A host stores values
+     * wherever it stores values — a gitignored file behind a whitelist, a secret
+     * manager, a Laravel config — and hands them over per call. A package that
+     * reached for the environment itself would bypass that discipline entirely,
+     * and a test in this repo asserts that it does not.
+     *
+     * Omit to resolve through a registered connection host instead; see
+     * `connection.ts`.
+     */
+    credentials?: ConnectionCredentials;
+    /** Which estate to use. Resolved from the connection host when omitted. */
+    mode?: ConnectorMode;
+    /** Connection id, for the registered-host path. */
+    connectionId?: string | null;
+    /**
+     * The caller's own config for this call.
+     *
+     * Passed to the faker so its output is deterministic, and read for
+     * `connection` and `mode` when those were not given explicitly — which is what
+     * a workflow node stores them in. Explicit arguments always win; this is a
+     * convenience for a host whose configuration IS a config object, not a second
+     * source of truth.
+     */
+    config?: Record<string, unknown>;
+    input?: unknown;
+    request: ConnectorRequest;
+    /**
+     * Value for the provider's idempotency header. Derive it from the run and the
+     * step, never a fresh uuid: the entire point is that a RETRY carries the same
+     * key. See `idempotency.ts`.
+     */
+    idempotencyKey?: string;
+    /**
+     * Whether repeating this exact request is harmless.
+     *
+     * **Defaults to `false`.** The only thing that makes an ambiguous failure
+     * retryable, so it is opt-in and has to be true because the provider makes it
+     * true — not because a retry would be convenient.
+     */
+    idempotent?: boolean;
+    /** Retry budget for retryable failures. Total attempts, including the first. */
+    attempts?: number;
+    /** Override the transport for this call. Otherwise the registered one, then `fetch`. */
+    transport?: Transport;
+    /**
+     * Called for each FAILED attempt once the call has finished, so a host can
+     * journal what actually happened. A call that worked on the third try is a
+     * different operational fact from one that worked immediately.
+     *
+     * A callback rather than a field on the result, because the result is a
+     * published shape and this is a diagnostic — see `ConnectorResult`.
+     */
+    onAttempt?: (attempt: Attempt) => void;
+};
+/**
+ * What a connector call returns, alongside the provider's own payload.
+ *
+ * The mode is REPORTED, never inferred by the caller. A call that emitted the
+ * provider's data alone would leave every downstream reader — a human, an agent,
+ * a log — unable to tell a faked result from a real one, which is the single
+ * most important fact about a connector run.
+ *
+ * **Retry history is deliberately NOT here.** It was, briefly, and the flow
+ * node marketplace's cross-runtime fixtures caught it immediately: this object
+ * is published on a node's output port and referenced by templates and agents,
+ * and PHP's `ConnectorResult::toArray()` does not carry it. Two runtimes
+ * publishing different shapes is the exact drift those fixtures exist to
+ * prevent, and a diagnostic field is a poor reason to break it. Pass
+ * `onAttempt` to observe retries.
+ */
+type ConnectorResult<T = unknown> = {
+    data: T;
+    /** Which estate this actually ran against. Always reported, never inferred. */
+    mode: ConnectorMode;
+    connection: string;
+};
+/** Install a transport. Only needed if the runtime has no global `fetch`. */
+declare function registerTransport(next: Transport | null): void;
+declare function callConnector<T = unknown>(service: ServiceDescriptor, options: CallOptions): Promise<ConnectorResult<T>>;
+
+/**
+ * API drift — being told the provider changed, rather than discovering it.
+ *
+ * ## The failure this addresses
+ *
+ * A connector's worst failure is silent. The provider changes its API and
+ * nothing says so until something breaks in production — and by then the person
+ * who wrote the connector has moved on, the reason it worked is gone, and the
+ * first symptom is usually a 400 that reads like bad input.
+ *
+ * ## What the system DOES on drift: it REPORTS. It never adapts.
+ *
+ * This is the load-bearing decision and it is deliberate.
+ *
+ * A connector that reshapes itself around a changed API is worse than one that
+ * fails loudly, for three reasons that compound:
+ *
+ * 1. **It cannot be reviewed.** The bytes that go out stop being a function of
+ *    the source someone read. A host that guarantees "what was approved is what
+ *    was sent" cannot make that guarantee about code that rewrote itself.
+ * 2. **Its behaviour depends on WHEN it ran**, because it depends on what the
+ *    spec said at that moment. Two runs of the same workflow on the same input
+ *    can differ, and nothing in the run record explains why.
+ * 3. **Adaptation is only ever a guess at intent.** A renamed field might be a
+ *    rename or might be a different field with a similar name; a removed one
+ *    might be gone or moved. Getting it wrong writes wrong data confidently.
+ *
+ * ## And it never changes RUNTIME behaviour either
+ *
+ * A drift check runs out of band — on a schedule, in CI, on demand. It does not
+ * fail a call that is working. If the spec changed and the call still succeeds,
+ * failing the run would be a self-inflicted outage caused by a document. The
+ * only thing that changes runtime behaviour is the provider actually refusing,
+ * which the error taxonomy already handles.
+ *
+ * So: **drift reports; the provider decides; a person acts.**
+ *
+ * ## Two detection strategies, because most providers publish nothing
+ *
+ * 1. **Specs**, where a provider publishes a machine-readable one at a stable
+ *    URL. Checked against the connector's declared slice — see `ApiContract`.
+ * 2. **Recorded shapes**, where it does not. A fixture of the response fields a
+ *    connector reads, compared against a live response on a schedule. Field
+ *    NAMES only; values are never recorded, because a recorded response from a
+ *    real account is a data leak wearing a test fixture's clothes.
+ *
+ * The second is the fallback and is designed anyway, because it is the majority
+ * case: of the providers surveyed for this package, the ones publishing a
+ * maintained spec are a minority, and publishing one is not the same as
+ * maintaining it — `slackapi/slack-api-specs` has not been touched since 2021.
+ */
+/**
+ * One operation a connector calls.
+ *
+ * The `path` is the TEMPLATE, matching the provider's own documentation, so it
+ * can be looked up in a spec: `/v1/charges/{charge}`, not the interpolated URL.
+ */
+type ContractOperation = {
+    /** Stable name, matching the connector's own operation id. */
+    operation: string;
+    method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+    path: string;
+    /** Request fields the connector SENDS. Drift here breaks writes. */
+    sends?: string[];
+    /** Response fields the connector READS. Drift here breaks reads, silently. */
+    reads?: string[];
+};
+/**
+ * Where a provider's machine-readable description lives.
+ *
+ * `kind` matters because "machine-readable" is not one format. AT Protocol
+ * publishes **lexicons**, not OpenAPI, and a checker that assumed OpenAPI would
+ * report every AT Protocol connector as unspecified — which is a different and
+ * much worse answer than "specified, in another format".
+ */
+type SpecSource = {
+    kind: "openapi";
+    url: string;
+    note?: string;
+} | {
+    kind: "lexicon";
+    url: string;
+    note?: string;
+} | {
+    kind: "none";
+    /**
+     * Why there is no spec, and what the fallback is. Required — "none" with
+     * no reason is indistinguishable from "nobody looked".
+     */
+    note: string;
+};
+/** Everything a connector declares about the API it was written against. */
+type ApiContract = {
+    connector: string;
+    /** Base URL the operations hang off, for a human reading the report. */
+    baseUrl?: string;
+    spec: SpecSource;
+    operations: ContractOperation[];
+    /** When a person last read the provider's documentation for this contract. */
+    reviewedOn: string;
+};
+type DriftFinding = {
+    /**
+     * `missing-operation` — the path or method is gone. A write will start failing.
+     * `missing-request-field` — something we send is no longer accepted.
+     * `missing-response-field` — something we read is gone. **Silent**: the code
+     *   keeps running and produces nothing, which is the dangerous one.
+     * `unreadable-spec` — the spec URL moved or stopped parsing. Not drift in the
+     *   API, but drift in our ability to see it, and it must not read as "clean".
+     * `stale-review` — nobody has looked at this contract in a long time.
+     */
+    kind: "missing-operation" | "missing-request-field" | "missing-response-field" | "unreadable-spec" | "stale-review";
+    operation?: string;
+    detail: string;
+};
+type DriftReport = {
+    connector: string;
+    checkedAt: string;
+    /** `unchecked` is a real outcome and never counts as clean. */
+    outcome: "clean" | "drifted" | "unchecked";
+    findings: DriftFinding[];
+    /** How the check was done, so a report can be read without the code. */
+    method: "openapi" | "lexicon" | "recorded-shape" | "none";
+};
+/**
+ * Check a contract against an OpenAPI document already fetched by the caller.
+ *
+ * The FETCH is the caller's, not this function's — so the check is a pure
+ * function of two documents and can be tested against a fixture with no network,
+ * and so a host chooses its own HTTP client, cache and proxy. A checker that
+ * fetched would also be a checker that phones out on a schedule, which is
+ * exactly the thing several hosts of this package refuse to have.
+ */
+declare function checkAgainstOpenApi(contract: ApiContract, document: unknown): DriftReport;
+/**
+ * The field NAMES a connector saw in a real response, per operation.
+ *
+ * Names only. A recorded response body from a real account is a data leak
+ * wearing a test fixture's clothes, and the thing being checked is the shape.
+ */
+type RecordedShape = {
+    connector: string;
+    recordedOn: string;
+    operations: Record<string, string[]>;
+};
+/**
+ * The field names present in a response, flattened to dotted paths.
+ *
+ * Arrays collapse to their first element's shape: a response with three items
+ * has one shape, and recording `items.0.id`, `items.1.id`, `items.2.id` would
+ * make the fixture depend on how much data the account happened to have.
+ */
+declare function shapeOf(value: unknown, prefix?: string, depth?: number): string[];
+/**
+ * Compare a live response's shape against what was recorded.
+ *
+ * **Only fields the connector READS are findings.** A provider adding fields is
+ * normal and healthy; reporting it would bury the one line that matters under
+ * every additive release, and a drift report nobody reads is worse than none
+ * because it is evidence somebody is watching.
+ */
+declare function checkAgainstRecordedShape(contract: ApiContract, operation: string, liveResponse: unknown): DriftReport;
+/** How long a contract may go unreviewed before that is itself a finding. */
+declare const REVIEW_STALE_DAYS = 180;
+/**
+ * A contract whose provider publishes nothing, checked as far as it can be.
+ *
+ * Reported as `unchecked` with the reason, never `clean`. Those are different
+ * claims and the difference is the entire value of a report.
+ */
+declare function unchecked(contract: ApiContract): DriftReport;
+
+/**
+ * The connector error taxonomy.
+ *
+ * A host that retries needs to know WHICH KIND of failure it is looking at.
+ * "Something went wrong" is not enough information to choose between retrying,
+ * pausing for a person, and stopping — so every failure is classified at the
+ * point it is known, which is inside the connector, not three frames up where
+ * the type has already been lost.
+ *
+ * | class | kind | retry? |
+ * |---|---|---|
+ * | `ConnectorConfigError` | `rejected` | never — nothing about a second attempt changes an unset key |
+ * | `ConnectorAuthError` | `rejected` | never — the credential is wrong; hammering it locks accounts |
+ * | `ConnectorRateLimited` | `refused-explicitly` | yes, after `retryAfter` |
+ * | `ConnectorTransient` | `refused-explicitly` | yes — a 5xx is the provider saying it did nothing |
+ * | `ConnectorAmbiguous` | `ambiguous` | **only** where the connector is idempotent |
+ * | `ConnectorUnreachable` | `unreachable` | yes — it never arrived |
+ * | `ConnectorRequestError` | `rejected` | never — a 4xx we caused fails the same way twice |
+ *
+ * ## What changed, and why it is a fix rather than a refactor
+ *
+ * `ConnectorTransient` used to mean *5xx OR a thrown transport*, with
+ * `retryable = true`. Those are opposite cases. A 5xx is the provider reporting
+ * that it did nothing; a thrown transport may be a socket that closed after the
+ * bytes went out. Retrying the second on a connector with no idempotency key is
+ * a silent double write — the failure this whole layer exists to prevent.
+ *
+ * So the two are separate classes now, `kind` is the primitive, and `retryable`
+ * answers the narrow question *is this safe whatever the connector is?* An older
+ * caller reading `.retryable` therefore becomes conservative rather than wrong.
+ */
+
+type ConnectorErrorContext = {
+    service: string;
+    operation: string;
+    /** HTTP status when there was one. */
+    status?: number;
+    /** The provider's own error code, when it publishes one. */
+    providerCode?: string;
+};
+/** Base for everything below, so a host can catch the family in one clause. */
+declare class ConnectorError extends Error {
+    readonly service: string;
+    readonly operation: string;
+    readonly status?: number;
+    readonly providerCode?: string;
+    /**
+     * What kind of failure this is. The primitive every retry decision reads.
+     *
+     * Defaults to `ambiguous` on the base class deliberately: an unclassified
+     * failure must not be assumed safe.
+     */
+    readonly kind: FailureKind;
+    constructor(message: string, ctx: ConnectorErrorContext);
+    /**
+     * Safe to retry **without knowing anything about the connector**.
+     *
+     * Ambiguous failures answer `false` here even though they may be retryable on
+     * an idempotent connector — ask `shouldRetry(error.kind, { idempotent })` for
+     * that. This getter is the conservative half on purpose.
+     */
+    get retryable(): boolean;
+    /** The classification, in the shape `deliver()` reads off a thrown error. */
+    get classified(): Classified;
+}
+/**
+ * A required piece of configuration is missing or unusable.
+ *
+ * The message must name the exact key the consumer has to set. "Stripe is not
+ * configured" sends someone reading source; "no `secretKey` on the `stripe`
+ * connection" sends them to the line.
+ */
+declare class ConnectorConfigError extends ConnectorError {
+    readonly kind: FailureKind;
+}
+/** The provider rejected the credential. Retrying cannot help. */
+declare class ConnectorAuthError extends ConnectorError {
+    readonly kind: FailureKind;
+}
+/** The provider asked us to slow down. It did nothing, and said so. */
+declare class ConnectorRateLimited extends ConnectorError {
+    readonly kind: FailureKind;
+    /** Seconds to wait, when the provider said. */
+    readonly retryAfter?: number;
+    constructor(message: string, ctx: ConnectorErrorContext & {
+        retryAfter?: number;
+    });
+    get classified(): Classified;
+}
+/**
+ * A 5xx. The provider answered, and its answer was "not now".
+ *
+ * Named for what it is rather than for how it feels: this is an *explicit
+ * refusal*, which is why it is always safe to repeat. A timeout feels the same
+ * to the caller and is not the same thing — see `ConnectorAmbiguous`.
+ */
+declare class ConnectorTransient extends ConnectorError {
+    readonly kind: FailureKind;
+}
+/**
+ * The request never reached the provider — DNS, refused connection, a socket
+ * closed before anything went out.
+ *
+ * Always safe to repeat, and the only transport-level failure of which that is
+ * true.
+ */
+declare class ConnectorUnreachable extends ConnectorError {
+    readonly kind: FailureKind;
+}
+/**
+ * Nobody can tell whether the provider acted on it. A timeout, an abort, an
+ * error nothing recognises.
+ *
+ * **Retryable only where the connector declared that repeating a request is
+ * harmless.** On anything else this is reported for a person, because the
+ * alternative is a duplicate that nobody will ever trace back to a bug.
+ */
+declare class ConnectorAmbiguous extends ConnectorError {
+    readonly kind: FailureKind;
+}
+/** A 4xx we caused. The same request will fail the same way. */
+declare class ConnectorRequestError extends ConnectorError {
+    readonly kind: FailureKind;
+}
+/**
+ * Classify an HTTP response into the taxonomy.
+ *
+ * 429 before the 4xx sweep, deliberately — see `classifyStatus`.
+ */
+declare function classifyHttp(status: number, ctx: ConnectorErrorContext, body: string, retryAfter?: number): ConnectorError;
+/**
+ * Turn a thrown transport failure into the right class.
+ *
+ * The default is `ConnectorAmbiguous`, not `ConnectorTransient`. That single
+ * default is the difference between "a flaky network costs us a retry" and "a
+ * flaky network costs someone a duplicate charge".
+ */
+declare function classifyThrown(cause: unknown, ctx: ConnectorErrorContext): ConnectorError;
+/**
+ * An HTTP failure carrying its classification, for connectors that decide what
+ * counts as a failure themselves.
+ *
+ * Telegram answers `200 OK` with `{"ok": false}` for a real refusal, so its
+ * connector has to raise the failure itself — and when it does, it must be
+ * classified the same way every other failure is. `httpFailure(400, …)` is how
+ * it says "this is a real no" without inventing a second vocabulary.
+ */
+declare function httpFailure(status: number, body: string, retryAfter?: string | null): Error;
+
+/**
+ * A run, a position inside it, and how many times that position has been tried.
+ *
+ * Declared STRUCTURALLY rather than imported, and that is the whole point: this
+ * package must be usable by a host that has never heard of a workflow engine.
+ * `fancy-flow`'s `RunIdentity` class satisfies this shape exactly, so a flow
+ * node passes `ctx.run` straight in with no adapter and no dependency in either
+ * direction — and a host with its own notion of "the same logical attempt"
+ * implements five members and gets the same guarantees.
+ *
+ * The identity is more than `(run, step)` for a reason: a step legitimately runs
+ * many times in one run — once per loop iteration, once per nested invocation —
+ * so the key carries the PATH that led to it. `attempt` is carried and
+ * deliberately NOT part of the key, because a retry must produce the same key.
+ */
+type RunIdentity = {
+    /** Stable for the whole run: same across retries, resumes, workers and hosts. */
+    readonly runKey: string;
+    /** 1-based attempt of THIS logical step. Never part of the key. */
+    readonly attempt: number;
+    /** ISO-8601 instant of attempt 1 of this step. */
+    readonly firstAttemptAt: string;
+    /** The identity of one execution of one step, stable across its retries. */
+    stepKey(stepId: string, occurrence?: number | null): string;
+    /** May this attempt reuse the key and still be deduplicated? */
+    isReplaySafe(windowSeconds: number | null | undefined, now?: Date | string): boolean;
+};
+/**
+ * The idempotency key a writing connector sends, and when it must refuse to.
+ *
+ * ## What the engine now provides
+ *
+ * `fancy-flow` 0.46.0 carries a **run identity** on the execution context, so a
+ * node can derive a key that is the same on every retry of one logical step and
+ * different for every other execution of the same node.
+ * `ctx.run.stepKey(ctx.node.id)` is that key. The equivalent landed in
+ * `fancy-flow-php` 0.19.0 and the Python runtime, all three pinned by
+ * `shared/flow-run-identity` in `@particle-academy/fancy-conformance`.
+ *
+ * Before that, neither engine could produce one, and both obvious substitutes
+ * were worse than sending nothing:
+ *
+ * - **the node id alone** is stable across retries and also across RUNS, so two
+ *   legitimate payments share a key and the provider silently collapses the
+ *   second into the first — a payment that never happened, reported as success;
+ * - **a fresh random value** is unique per run and also per ATTEMPT, so a retry
+ *   creates a second charge.
+ *
+ * So this used to return `null` and every writing node emitted a warning and
+ * sent no key, staying pinned to one attempt. That is no longer the case where
+ * a host supplies an identity — which durable runs do automatically.
+ *
+ * ## The part that is still a judgement call: the provider's window
+ *
+ * Providers forget idempotency keys. Stripe's window is **24 hours**. Past it,
+ * resending the key creates a second charge and sending a fresh one creates a
+ * second charge — there is no safe third option — so `idempotencyKeyFor`
+ * **throws** rather than choosing. A loud stuck run that a person reconciles
+ * beats a silent double write nobody ever sees.
+ *
+ * A first attempt is never refused, however long the run was parked: nothing
+ * was sent on an earlier attempt, so there is nothing for the provider to have
+ * forgotten. That is what lets an approval sit for a week and then charge.
+ */
+/** Stripe's window, and the default for a provider that has not said otherwise. */
+declare const DEFAULT_IDEMPOTENCY_WINDOW_SECONDS: number;
+/**
+ * Longest key the strictest provider in the catalogue accepts.
+ *
+ * Stripe caps `Idempotency-Key` at 255 characters. A deep subflow path could
+ * exceed that, and a provider rejecting the header is a 400 that looks like a
+ * bug in the request body.
+ */
+declare const MAX_IDEMPOTENCY_KEY_LENGTH = 255;
+/** Raised when a retry can no longer be made safe. Never retryable. */
+declare class ConnectorIdempotencyExpiredError extends ConnectorConfigError {
+}
+/** The run identity a host published, or `null`. Checked in order. */
+declare function runIdentityFrom(ctx: unknown): RunIdentity | null;
+/**
+ * Where a host with no engine support may still publish a run key.
+ *
+ * Kept because a consumer on an older `fancy-flow` has no `ctx.run`, and
+ * seeding `__runKey` into the run's initial inputs is the documented fallback.
+ * It gives a per-run key with no attempt information, so the window check below
+ * treats it as a first attempt — correct for a host that does not retry, and
+ * the reason the engine-supplied identity is strictly better.
+ */
+declare function runKeyFrom(ctx: unknown): string | null;
+type IdempotencyOptions = {
+    /**
+     * How long the provider remembers a key. `null` means it never forgets; `0`
+     * means it does not dedupe at all, so no retry may reuse one.
+     */
+    windowSeconds?: number | null;
+    /** Distinguishes repeated executions of one node at the same level. */
+    occurrence?: number | null;
+    /** Injectable for tests. Never a network call. */
+    now?: Date;
+    /** For the error message when a key cannot be made safe. */
+    context?: Partial<ConnectorErrorContext>;
+};
+/**
+ * The idempotency key for this execution of this node, or `null`.
+ *
+ * `null` means the host published no run identity at all — send no header
+ * rather than inventing one, and keep the node `unsafe-to-replay`.
+ *
+ * **Throws** `ConnectorIdempotencyExpiredError` when this is a RETRY and the
+ * provider's window has elapsed. That is not a defensive check; it is the only
+ * correct answer, because both alternatives write twice.
+ */
+declare function idempotencyKeyFor(ctx: unknown, nodeId: string, options?: IdempotencyOptions): string | null;
+/**
+ * The warning a node emits when it is about to write without a key.
+ *
+ * Said out loud, at the moment it matters, because the failure it precedes is
+ * invisible: the run succeeds, the retry succeeds, and there are two charges.
+ */
+declare const NO_IDEMPOTENCY_KEY_WARNING: string;
+
+/**
+ * Measuring and slicing text the way providers actually measure and slice it.
+ *
+ * ## Why a package owns this at all
+ *
+ * Two of the nastiest bugs in a connector catalogue are one-liners, and both
+ * come from reaching for the obvious JavaScript idiom:
+ *
+ * 1. **`text.length` is not a count of anything a provider limits.** It counts
+ *    UTF-16 code units. `"👍".length` is 2 and `"👨‍👩‍👧".length` is 8, so it
+ *    overcounts exactly the posts most likely to sit near a limit — and it fails
+ *    in the worse direction, because a post that passes our check and is then
+ *    refused by the server reads as the network being flaky rather than as our
+ *    bug.
+ * 2. **`indexOf` returns a character index, and rich-text formats want BYTES.**
+ *    AT Protocol facets are UTF-8 byte ranges. An implementation using character
+ *    indices is correct for ASCII and silently corrupts every post containing an
+ *    emoji or an accent — and it corrupts the *link*, so the post looks fine and
+ *    the link goes somewhere wrong.
+ *
+ * Neither is discoverable by testing with ASCII, which is what everyone tests
+ * with. So the package makes the wrong thing unreachable: a `ByteRange` is a
+ * type, not a convention, and it can only be produced by a function that
+ * encoded the string.
+ *
+ * ## The unit is declared, never assumed
+ *
+ * Providers count different things — Bluesky counts graphemes, Discord and
+ * Telegram count characters, some count bytes. `TextUnit` makes the choice
+ * explicit at the point a limit is declared, so nobody has to remember which
+ * network is which.
+ */
+/** What a provider actually counts. Declared per connector, never guessed. */
+type TextUnit = "graphemes" | "characters" | "utf8-bytes";
+/**
+ * A half-open range of UTF-8 BYTES.
+ *
+ * Named for the unit because the whole failure mode is somebody passing
+ * character offsets into a field that wants bytes. The two are equal for ASCII,
+ * which is why this survives review and fails in production.
+ */
+type ByteRange = {
+    byteStart: number;
+    byteEnd: number;
+};
+/**
+ * Count graphemes — what a person means by "characters".
+ *
+ * `Intl.Segmenter` is the correct tool and has been in Node since 16. The
+ * fallback is the spread operator, which counts code points rather than UTF-16
+ * units and so is wrong by less. Both are better than `.length`.
+ */
+declare function graphemes(text: string): number;
+/** Length of `text` in UTF-8 bytes. */
+declare function utf8Length(text: string): number;
+/**
+ * Count `text` in whichever unit a provider enforces.
+ *
+ * The one function every limit check goes through, so a connector never has to
+ * decide — and so `text.length` never appears in connector source at all.
+ */
+declare function measure(text: string, unit: TextUnit): number;
+/**
+ * The UTF-8 byte range of a substring that starts at a CHARACTER index.
+ *
+ * The bridge between the index a regex gives you and the offsets a provider
+ * wants. Takes the character index because that is what `matchAll` produces, and
+ * returns bytes because that is what goes on the wire — doing the conversion in
+ * one place is the entire point.
+ */
+declare function byteRangeOf(text: string, charIndex: number, substring: string): ByteRange;
+/**
+ * Extract the substring a byte range names.
+ *
+ * Exists so a test can prove a range points where it claims to, which is the
+ * only way to catch an off-by-one that ASCII hides. A range that lands
+ * mid-character yields the replacement character rather than throwing, because
+ * the useful failure here is a visibly wrong string in an assertion, not an
+ * exception three frames away.
+ */
+declare function sliceByteRange(text: string, range: ByteRange): string;
+/**
+ * Bare URLs in `text`, with their UTF-8 byte ranges.
+ *
+ * Trailing punctuation is excluded: a link at the end of a sentence would
+ * otherwise swallow the full stop and 404. Closing brackets go too, for the same
+ * reason and because a URL in parentheses is common in prose.
+ *
+ * This is the generic half of a "link facet" — a connector maps the ranges into
+ * whatever its provider's rich-text shape is. The package owns the offsets
+ * because the offsets are what people get wrong; it does not own the provider's
+ * schema, because that is the provider's.
+ */
+declare function linkRanges(text: string): Array<ByteRange & {
+    url: string;
+}>;
+
+/**
+ * Rendering — what a provider would ACTUALLY receive.
+ *
+ * ## Why a connector package owns this, and why it is dangerous
+ *
+ * One piece of content often has to reach several providers whose limits are
+ * incompatible. Without adaptation the same text is wasteful on one and refused
+ * by another. With naive adaptation, the bytes that reach the public are not the
+ * bytes anyone approved — and every guarantee a host makes about approval
+ * becomes a lie the moment adaptation exists.
+ *
+ * So rendering happens **before** whatever gate the host applies: the person
+ * approving sees exactly what each provider will receive and approves *that*.
+ * Nothing is invented after the decision.
+ *
+ * ## Which forces three properties
+ *
+ * 1. **Pure.** Rules in, payload out. No clock, no randomness, no network. If
+ *    the preview and the send could disagree, the approval means nothing.
+ *    Anything variable — an instance's configured limit — is resolved by the
+ *    CALLER and passed in as a rule, so it becomes part of what was approved.
+ * 2. **Versioned.** Any change to how text is split, counted or faceted bumps
+ *    `RENDERER_VERSION`, and the version is **inside** the payload hash rather
+ *    than beside it, so it cannot be checked separately and forgotten.
+ * 3. **Honest about loss.** Anything that could not be fitted is reported as a
+ *    problem, never quietly applied. A truncated URL is worse than a refused
+ *    post, because it looks deliberate and goes somewhere wrong.
+ *
+ * ## And one rule about where length lives
+ *
+ * **No length rule outside this module.** A validator and a renderer that both
+ * judge length will disagree, and then the validator refuses content the
+ * renderer had already solved. `validate()` on a connector checks things the
+ * renderer cannot — media, alt text, a required field — and leaves length here.
+ */
+
+/**
+ * Bump on ANY change to how text is split, counted, or faceted.
+ *
+ * A payload approved under `1` refuses to send once this reads `2`, because the
+ * payload the approver saw is no longer the payload that would go out. That is
+ * the correct outcome and the reason the field exists.
+ */
+declare const RENDERER_VERSION = "render@1";
+type Segment = {
+    /** The text of this message, exactly as it would be sent. */
+    text: string;
+    /** How many of the provider's unit this segment uses. */
+    count: number;
+    /** Link ranges, in UTF-8 bytes, **relative to this segment**. */
+    links?: Array<ByteRange & {
+        url: string;
+    }>;
+};
+type RenderedPayload = {
+    /** One entry per message. More than one means a thread. */
+    segments: Segment[];
+    /** What the provider counts, so a preview can label the number. */
+    unit: TextUnit;
+    /**
+     * What the provider allows, or **null where it imposes no limit**.
+     *
+     * Null rather than a very large number: `Number.MAX_SAFE_INTEGER` is
+     * arithmetically fine and reads, on a person's screen, as
+     * `157 / 9007199254740991` — a number pretending to be a fact. "No limit" and
+     * "a limit so large it cannot be hit" are different statements.
+     */
+    limit: number | null;
+    /** Why this could not be rendered, when it could not. Never silently repaired. */
+    problems: string[];
+    rendererVersion: string;
+};
+/**
+ * The rules a provider imposes on a message, as DATA.
+ *
+ * Declarative on purpose. Across the providers this was extracted from, the
+ * differences that mattered were all values — the limit, the unit, whether a
+ * thread mechanism exists, whether links carry byte offsets. A provider whose
+ * rendering genuinely needs code supplies its own `render` on the connector and
+ * ignores this; the point of the rule set is that most do not have to.
+ */
+type RenderRules = {
+    /** The provider's limit per message, or null where it has none. */
+    limit: number | null;
+    unit: TextUnit;
+    /**
+     * Whether this provider can carry a sequence of connected messages.
+     *
+     * False means over-length content is REFUSED rather than split — splitting
+     * would invent a structure the provider does not have, and a numbered sequence
+     * of unconnected messages is worse than a refusal because it looks deliberate.
+     */
+    thread: boolean;
+    /** Include UTF-8 link ranges per segment, for providers with rich-text spans. */
+    links?: boolean;
+    /** Human name, used in refusal messages. */
+    label: string;
+    /**
+     * Suffix added to each part of a thread, given the 1-based index and total.
+     *
+     * Defaults to ` (i/n)`. Its cost is measured and subtracted from the limit
+     * BEFORE splitting, because a suffix discovered afterwards is a bug that only
+     * appears on long threads.
+     */
+    numbering?: (index: number, total: number) => string;
+};
+/**
+ * Split text into parts that each fit the limit.
+ *
+ * **Sentence boundaries first, then words, and never mid-grapheme.** A thread
+ * that splits mid-argument is worse than one that splits a little unevenly, so
+ * this prefers a natural break even when it wastes room.
+ *
+ * A single token that cannot fit at all is reported as a problem rather than
+ * hard-cut — see the module note about truncated URLs.
+ */
+declare function splitToFit(text: string, limit: number, unit: TextUnit): {
+    parts: string[];
+    problems: string[];
+};
+/**
+ * Render text against a provider's rule set.
+ *
+ * The one entry point. A connector that needs nothing bespoke declares rules and
+ * calls this; the shared behaviour — numbering cost, per-segment link offsets,
+ * refusal where there is no thread mechanism — is then identical everywhere,
+ * which is what makes a catalogue feel like one thing.
+ */
+declare function render(text: string, rules: RenderRules): RenderedPayload;
+/**
+ * A stable fingerprint of what would actually be sent.
+ *
+ * This is what an approval covers. A host recomputes it at dispatch and refuses
+ * on mismatch: if the rendering changed for ANY reason — edited text, a changed
+ * limit, a new renderer version — the hashes differ, because the approver
+ * approved a payload rather than an intention.
+ *
+ * Async because it uses WebCrypto, which is the only hash available on every
+ * runtime the suite supports. A host that wants it synchronously should hold the
+ * value rather than recompute it.
+ */
+declare function payloadHash(payload: RenderedPayload): Promise<string>;
+/**
+ * Refuse empty content, centrally.
+ *
+ * The sha of the empty string is a valid sha, so an empty payload passes every
+ * byte-verification a host can write. Refusing it in one place is what stops
+ * every one of those checks from being hollow.
+ */
+declare function isEmptyPayload(payload: RenderedPayload): boolean;
+
+/**
+ * The seam — two objects, deliberately separate.
+ *
+ * They answer different questions and change on different clocks:
+ *
+ * - **`ProviderAdapter`** — *how does an operator stand this up, and does it
+ *   work?* Credential shapes, setup steps with the trap in each one named,
+ *   scopes, a read-only verify. It changes when the provider changes its
+ *   onboarding, which is rarely and disruptively.
+ * - **`Connector`** — *what does calling this actually involve?* Capabilities,
+ *   delivery behaviour, validation, rendering, the call itself, measurement. It
+ *   changes when the API changes, which is often and quietly.
+ *
+ * Folding them together produces an object that has to be edited for both, and
+ * a diff that cannot tell you which happened.
+ *
+ * ## What this package does NOT own, and never will
+ *
+ * Everything on this list belongs to the HOST, because each is enforced in one
+ * place and every connector inherits it from the dispatch path rather than
+ * implementing it:
+ *
+ * - **approval** — whether this may go out at all;
+ * - **liveness** — `call(..., { dryRun })` takes the flag; a connector must
+ *   never resolve its own. A host may require two independent yeses, or ten;
+ *   that is its business and the package cannot help it get that wrong;
+ * - **the approved-bytes comparison** — the host re-renders and refuses on
+ *   mismatch. The package makes that possible by keeping `render` pure and
+ *   versioned, and does not perform it;
+ * - **consent** for anything reaching a list of people;
+ * - **any journal** — decisions, dispatches, runs;
+ * - **credential storage.** Credentials are ARGUMENTS. Nothing in this package
+ *   reads `process.env`, and a test asserts that it does not.
+ *
+ * A packager that owned any of those would be unusable by a host that takes them
+ * seriously — which is the only kind of host worth building for.
+ */
+
+/**
+ * One credential a provider needs.
+ *
+ * **`secret` is chosen per field, never inferred from the type.** A Discord
+ * webhook URL is a URL and is entirely a secret — it carries its token in the
+ * path — and the reference implementation very nearly stored it as
+ * configuration because it looked like a URL.
+ */
+type CredentialField = {
+    /** Stable key. The host maps it to wherever it keeps values. */
+    key: string;
+    label: string;
+    /** What it is, where it comes from, and what it does NOT prove. */
+    help: string;
+    /**
+     * `provider` — one value for the whole installation (an OAuth app serves
+     * every account). `account` — one value per connected account.
+     *
+     * The distinction exists because getting it wrong means either asking for the
+     * same app secret five times or letting one account's token reach another's.
+     */
+    scope: "provider" | "account";
+    secret: boolean;
+    required: boolean;
+    /** A hint for an empty field. NEVER a real value. */
+    placeholder?: string;
+};
+type SetupStep = {
+    title: string;
+    /** The step, and the trap in it. A step with no trap named is usually wrong. */
+    detail: string;
+    url?: string;
+};
+/**
+ * The result of a read-only credential check.
+ *
+ * **`proves` is not decoration.** Telegram's `getMe` validates the token and
+ * says nothing about whether the bot was added to the target chat — which is the
+ * step everyone actually gets stuck on. A green tick that means more than it
+ * should is worse than no tick, so a verify states its own scope.
+ */
+type VerifyResult = {
+    ok: boolean;
+    /** What was learned — ideally the account's real name, so the id can be checked. */
+    detail: string;
+    /** Exactly what this proves, and what it does not. */
+    proves?: string;
+};
+/**
+ * How an operator stands a provider up.
+ *
+ * Every provider worth listing is declared, **including the ones that cannot
+ * work yet**: a provider missing from a catalogue reads as unsupported, while a
+ * provider listed as `implemented: false` tells you exactly what it would take.
+ */
+type ProviderAdapter = {
+    id: string;
+    label: string;
+    /** True when this can actually be used today. A real state, not a placeholder. */
+    implemented: boolean;
+    /** One line on what it is for, shown before anyone opens the setup. */
+    summary: string;
+    fields: CredentialField[];
+    setup: SetupStep[];
+    /** Exactly what to ask for, and no more. */
+    scopes: string[];
+    /**
+     * How long credentials last, where the provider publishes a figure.
+     *
+     * Undefined means the provider states no lifetime — which a surface should
+     * report as "no published expiry" rather than inventing one, and still note
+     * that anything can be revoked. "No known expiry" is not "cannot stop working".
+     */
+    credentialLifetimeDays?: number;
+    /** How the provider exposes a test estate, in the four shapes that exist. */
+    sandbox: SandboxKind;
+    /**
+     * A read-only call proving the credential works AND reaches the right account.
+     *
+     * Deliberately a read. A verify that wrote something would be a send, and
+     * sends are gated.
+     */
+    verify?(credentials: Record<string, string>): Promise<VerifyResult>;
+};
+type Problem = {
+    severity: "block" | "warn";
+    message: string;
+};
+/**
+ * The result of one call.
+ *
+ * `ref` is how the provider identifies what was done — the handle every later
+ * question is joined on. **A 2xx with no ref is a failure**, and the connector
+ * says so rather than reporting a success nobody can point at.
+ */
+type CallResult = {
+    ok: boolean;
+    ref: string | null;
+    /** True when nothing actually left the building. */
+    dryRun: boolean;
+    detail: string;
+    /** Which estate this ran against. Always reported, never inferred. */
+    mode?: ConnectorMode;
+};
+/**
+ * What a connector can report, in its own words — **declared, not inferred**.
+ *
+ * Inferring the shape from whatever a pull last returned gives an empty shape
+ * when nothing has been pulled, and then *"this reports nothing"* and *"nobody
+ * has asked yet"* are the same blank, needing opposite actions.
+ *
+ * `canonical` is what the metric IS across providers, where an honest equivalent
+ * exists. A like and a favourite are the same act; a repost and a boost are the
+ * same act; a quote often has no equivalent, and `null` says so — which is more
+ * useful than a mapping somebody invented to make a table line up.
+ */
+type MetricDescriptor = {
+    /** The key the connector's own mapping actually returns. */
+    key: string;
+    /** What the provider itself calls it. */
+    label: string;
+    canonical: "like" | "share" | "reply" | "quote" | "view" | null;
+    means: string;
+};
+type MetricSample = {
+    ref: string;
+    at: string;
+    /** Only what the provider actually reported. **Absent stays absent.** */
+    metrics: Record<string, number>;
+};
+/**
+ * What a connector can do.
+ *
+ * **A capability flag must not outrun the code**, and this is checkable rather
+ * than a rule people remember: `assertCapabilitiesHonest` in `metrics.ts` fails
+ * when `metrics: true` has no declared shape. In the reference implementation
+ * two connectors claimed metrics while returning `[]` for weeks — so a pull did
+ * not skip them, it asked, got nothing, and reported nothing, which on a
+ * dashboard is indistinguishable from *"we asked and nobody engaged"*.
+ */
+type Capabilities = {
+    call: boolean;
+    metrics: boolean;
+    feedback: boolean;
+};
+/**
+ * One capability of one provider.
+ *
+ * `Target` is the host's own content shape — the package has no opinion about
+ * it, and a field named for one host's content model has no business in a shared
+ * contract.
+ */
+type Connector<Target = unknown> = {
+    id: string;
+    label: string;
+    /** Which `ProviderAdapter` stands this up. */
+    provider: string;
+    /**
+     * The connector API version this was written against.
+     *
+     * Required, and checked at registration by `assertConnectorApi`. The core and
+     * the catalogue release on separate clocks, and a connector is VENDORED — a
+     * copy in someone else's repository, with no manifest of its own to carry a
+     * version range. This number is the only thing that can say "this copy was
+     * written for a core you no longer have", and it says it at build time rather
+     * than in production. See `compat.ts`.
+     */
+    connectorApi: number;
+    capabilities: Capabilities;
+    /**
+     * How this behaves when a call goes wrong, and how fast it may be used.
+     * Cited, not asserted — see `DeliveryDeclaration`.
+     */
+    delivery: DeliveryDeclaration;
+    /** Declared metric shape. **Absent, not empty**, where there are none. */
+    metricShape?: MetricDescriptor[];
+    /**
+     * Rendering rules, where this connector renders text.
+     *
+     * Data rather than code for the common case. A provider whose rendering
+     * genuinely needs code supplies `render` instead.
+     */
+    renderRules?: RenderRules;
+    /**
+     * Everything the renderer cannot judge — media, alt text, a required field.
+     * **Never length**: see the note at the top of `render.ts`.
+     */
+    validate(target: Target): Problem[];
+    /** Pure and versioned. Overrides `renderRules` when both are present. */
+    render?(target: Target, rules?: Record<string, number>): RenderedPayload;
+    /**
+     * Do the thing.
+     *
+     * `credentials` are passed IN. `dryRun` is decided by the HOST. Neither is
+     * negotiable, and both are asserted by tests in this package.
+     */
+    call(target: Target, options: {
+        dryRun: boolean;
+        credentials: Record<string, string>;
+        mode?: ConnectorMode;
+    }): Promise<CallResult>;
+    fetchMetrics?(refs: string[], credentials: Record<string, string>): Promise<MetricSample[]>;
+    /**
+     * Feedback on things we did, for refs the host already holds.
+     *
+     * **Optional, and absent is a real answer** rather than a gap to be filled. A
+     * connector with no feedback mechanism must not pretend by returning an empty
+     * array — "nobody replied" and "this cannot tell you" are different, and only
+     * one of them is news.
+     */
+    fetchFeedback?(refs: string[], credentials: Record<string, string>): Promise<Array<{
+        id: string;
+        inReplyTo: string;
+        author: string;
+        text: string;
+        at: string;
+        url: string | null;
+        /** What answering this would need. Opaque to the host. */
+        context: Record<string, string>;
+    }>>;
+};
+/**
+ * A catalogue of connectors and the providers that stand them up.
+ *
+ * A plain lookup rather than a registry with lifecycle: the host owns which
+ * connectors it installed, and a package-level global would be one more thing
+ * that can be half-initialised.
+ */
+type Catalogue<Target = unknown> = {
+    providers: Record<string, ProviderAdapter>;
+    connectors: Record<string, Connector<Target>>;
+};
+
+/**
+ * Making a declared metric shape checkable against the code that produces it.
+ *
+ * ## The bug this exists to catch, which shipped for weeks
+ *
+ * Two connectors in the reference implementation declared
+ * `capabilities.metrics: true` while their metric fetch returned `[]`. A pull
+ * therefore did not skip them — it asked, got nothing, and reported nothing,
+ * which on a dashboard is indistinguishable from *"we asked and nobody
+ * engaged"*. A capability flag had quietly turned an unimplemented feature into
+ * a reported zero, on the one surface whose entire job is not making claims it
+ * cannot stand behind.
+ *
+ * A declared shape and the code that produces the numbers are the classic pair
+ * that agrees on the day it is written and drifts silently after. So the mapping
+ * is extracted as a **pure function per connector**, and these helpers feed it a
+ * synthetic response and compare the keys it returns against the keys declared.
+ * **No credentials, no network.**
+ *
+ * ## And the rule underneath all of it
+ *
+ * **Absent stays absent.** A count the provider did not send is omitted, never
+ * reported as zero. A zero says "nothing happened"; an absence says "we don't
+ * know". A measurement surface that confuses those is worthless, and the
+ * confusion is one `?? 0` away.
+ */
+
+type ShapeMismatch = {
+    connector: string;
+    /** Keys the mapping produced that nothing declared. */
+    undeclared: string[];
+    /** Keys declared that the mapping never produces. */
+    unproduced: string[];
+};
+/**
+ * Compare a declared shape against what a mapping actually returns.
+ *
+ * `produced` is the output of the connector's pure response→metrics function
+ * given a synthetic response with EVERY field populated. Anything the mapping
+ * can emit therefore appears, and anything it cannot is caught as a declaration
+ * nobody can honour.
+ */
+declare function compareShape(connectorId: string, declared: MetricDescriptor[] | undefined, produced: Record<string, number>): ShapeMismatch | null;
+/**
+ * Every way a capability flag can outrun the code, as findings.
+ *
+ * Returns strings rather than throwing so a host can report all of them at once.
+ * A check that stops at the first problem trains people to fix one thing and
+ * re-run, which is how a list of six becomes six rounds.
+ */
+declare function capabilityProblems(connector: Connector<never>): string[];
+/**
+ * Drop keys whose value the provider did not actually send.
+ *
+ * The one function a connector's mapping should build on, so *absent stays
+ * absent* is a property of the code rather than a habit. `0` survives; `null`,
+ * `undefined` and non-numbers do not.
+ */
+declare function reported(values: Record<string, unknown>): Record<string, number>;
+
+/**
+ * Dry-verify — proving the transport with a credential that cannot work.
+ *
+ * ## The discipline, and why it beats a fake server
+ *
+ * A connector written from documentation can be wrong in three ways that look
+ * identical until a real credential arrives:
+ *
+ * 1. the URL is wrong,
+ * 2. the request shape is wrong,
+ * 3. the error handling never runs.
+ *
+ * **All three are invisible to a test with a fake server**, because a fake
+ * server agrees with whatever the code does. That is the single most important
+ * thing this module encodes: a green unit suite against a mock proves the code
+ * is consistent with itself.
+ *
+ * So a probe calls the REAL API with a deliberately invalid credential and
+ * requires an **auth-shaped refusal**. That proves the host resolved, the path
+ * exists, the method was accepted, and a failure was recognised as a failure.
+ *
+ * ## What counts as a pass, precisely
+ *
+ * An auth-shaped refusal is `401`, `403`, or a `404` on a provider that answers
+ * 404 for an unknown credential-in-the-path (a Discord webhook does exactly
+ * this). The provider declares which, because guessing here would let a genuine
+ * "this endpoint moved" 404 read as success — the one outcome a probe exists to
+ * catch.
+ *
+ * ## Offline is SKIPPED, never failed
+ *
+ * A check that goes red on a train gets ignored, and then it is worth nothing
+ * when it goes red for real. Unreachable is reported as skipped with the reason,
+ * and the assertions that need no network still run.
+ *
+ * ## And nothing is ever sent
+ *
+ * Every probe is a READ. A probe that wrote something would be a send, and sends
+ * are the host's to gate.
+ */
+
+type ProbeOutcome = "pass" | "fail" | "skip";
+type ProbeResult = {
+    connector: string;
+    outcome: ProbeOutcome;
+    /** What happened, in the provider's own words where possible. */
+    detail: string;
+    status?: number;
+    kind?: FailureKind;
+};
+type ProbeSpec = {
+    /** Which connector this probes. */
+    connector: string;
+    /**
+     * The read-only request, fully formed, carrying a credential that cannot be
+     * valid. Built by the connector so the probe exercises the connector's own URL
+     * and auth placement rather than a second copy of them.
+     */
+    request: () => Promise<{
+        status: number;
+        body: string;
+    }>;
+    /**
+     * Statuses that count as an auth-shaped refusal for THIS provider.
+     *
+     * Declared rather than assumed. Discord answers `404` for an unknown webhook
+     * id, and on a provider that does not, a 404 means the endpoint moved — the
+     * exact drift a probe is for.
+     */
+    authStatuses: number[];
+    /** Why those statuses, for whoever reads a failure at 3am. */
+    why: string;
+};
+/**
+ * Run one probe.
+ *
+ * Never throws. A probe that threw would take the suite down with it, and the
+ * suite's whole value is that it runs everywhere including on a laptop with no
+ * network.
+ */
+declare function probe(spec: ProbeSpec): Promise<ProbeResult>;
+type ProbeReport = {
+    results: ProbeResult[];
+    passed: number;
+    failed: number;
+    skipped: number;
+    /** True when nothing failed. Skips do not fail a report. */
+    ok: boolean;
+};
+/** Run a set of probes and summarise. Sequential: probes hit real providers. */
+declare function runProbes(specs: ProbeSpec[]): Promise<ProbeReport>;
+
+/**
+ * Verifying an inbound provider webhook.
+ *
+ * An unverified webhook endpoint is a public, unauthenticated way to start a
+ * workflow in someone's account — which is to say, a way for a stranger to make
+ * your app refund an order or post to your Slack. So verification is part of the
+ * connector pattern rather than an exercise for the host: a trigger node that
+ * cannot verify its deliveries must say so, and a host must not be able to mount
+ * one by accident.
+ *
+ * ## The three things every provider's scheme actually needs
+ *
+ * Providers differ in header names and in what exactly gets signed, and almost
+ * nothing else:
+ *
+ * 1. **The RAW body.** Signatures are computed over bytes. Re-serialising parsed
+ *    JSON changes key order and whitespace and produces a signature mismatch
+ *    that looks like a wrong secret. The host must pass the body it received.
+ * 2. **A constant-time comparison.** `===` on a signature leaks, through timing,
+ *    which prefix was right. That is a real forgery path, not a theoretical one.
+ * 3. **A timestamp tolerance.** Without it a valid signature is valid forever,
+ *    so anyone who ever saw one delivery can replay it whenever they like.
+ *
+ * WebCrypto rather than `node:crypto`, so the same file runs on Node, Bun, Deno
+ * and an edge runtime. Node 22 is the suite's floor and has it globally.
+ */
+type WebhookVerification = {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+};
+type HmacScheme = {
+    /** Hash to use. */
+    algorithm: "SHA-256" | "SHA-1" | "SHA-512";
+    /**
+     * Build the exact string that gets signed. Providers differ here more than
+     * anywhere else — Stripe signs `${timestamp}.${body}`, Slack signs
+     * `v0:${timestamp}:${body}`, GitHub signs the body alone.
+     */
+    payload: (raw: string, timestamp?: string) => string;
+    /** Seconds a delivery stays acceptable. */
+    tolerance?: number;
+    /** Encoding of the signature the provider sends. */
+    encoding?: "hex" | "base64";
+};
+/**
+ * Verify an HMAC-signed delivery.
+ *
+ * Returns a RESULT rather than throwing, and the failure carries a reason: a
+ * host wants to log which check failed (stale? wrong secret? no header?) while
+ * still answering the provider with an opaque 400.
+ */
+declare function verifyHmac(options: {
+    raw: string;
+    signature: string | undefined;
+    secret: string | undefined;
+    scheme: HmacScheme;
+    timestamp?: string;
+    /** Seconds since the epoch. Injected so tests are not clock-dependent. */
+    now?: number;
+}): Promise<WebhookVerification>;
+/** HMAC of `payload` under `secret`, hex or base64 encoded. */
+declare function hmac(secret: string, payload: string, algorithm: HmacScheme["algorithm"], encoding?: "hex" | "base64"): Promise<string>;
+/**
+ * Compare two strings without leaking where they diverge.
+ *
+ * The length check first is deliberate and safe: a signature's length is fixed
+ * by its algorithm and is not a secret, so revealing a mismatch there tells an
+ * attacker nothing they could not compute.
+ */
+declare function constantTimeEquals(a: string, b: string): boolean;
+/**
+ * Pull one header case-insensitively.
+ *
+ * Header case is not preserved consistently across proxies, frameworks and
+ * runtimes; a connector that read `req.headers["Stripe-Signature"]` would work
+ * behind one server and reject every delivery behind another.
+ */
+declare function header(headers: Record<string, string | string[] | undefined>, name: string): string | undefined;
+
+/**
+ * How a connector trigger learns that something happened.
+ *
+ * **Not every provider pushes, and assuming webhooks is the single most common
+ * way a connector catalogue ends up lying.** Google Drive and Microsoft Graph
+ * want a *subscription* you must renew before it expires. Salesforce wants a
+ * Pub/Sub or CometD stream. S3 wants an event notification routed to
+ * infrastructure the consumer provisions. Reddit wants you to poll. Each of
+ * those is a different obligation on the host, and a node that declared
+ * "webhook" for all of them would install cleanly and then never fire.
+ *
+ * So a trigger declares its delivery mechanism, and the host can refuse to mount
+ * one it has no machinery for — at author time, not at 3am.
+ */
+
+/**
+ * The delivery mechanisms that actually exist in the wild.
+ *
+ * - `webhook` — the provider POSTs to a URL you own. Verify the signature.
+ * - `subscription` — a webhook that EXPIRES. Someone has to renew it, forever,
+ *   and if nobody does the workflow stops firing without an error anywhere.
+ *   Distinct from `webhook` precisely because that ongoing duty is invisible.
+ * - `poll` — you ask, on a schedule, and track a cursor.
+ * - `pubsub` — the provider publishes to a broker (Google Pub/Sub, Salesforce
+ *   Pub/Sub API, SNS/SQS) that the consumer must provision.
+ * - `stream` — a long-lived connection the host maintains (websocket, gRPC,
+ *   SSE, CometD).
+ */
+type DeliveryMechanism = "webhook" | "subscription" | "poll" | "pubsub" | "stream";
+type TriggerDescriptor = {
+    service: string;
+    operation: string;
+    delivery: DeliveryMechanism;
+    /**
+     * What the host has to do before this fires, in one sentence, aimed at the
+     * person who has to do it. Surfaced by the editor and by the MCP, because a
+     * trigger whose setup is undocumented is a trigger that silently never fires.
+     */
+    setup: string;
+    /** For `subscription`: how long the provider keeps it alive, in seconds. */
+    subscriptionTtl?: number;
+    /** For `webhook` / `subscription`: how a delivery is authenticated. */
+    verification?: WebhookVerificationSpec;
+    /** For `poll`: the provider's smallest sane interval, in seconds. */
+    minPollSeconds?: number;
+    /** A faked sample event, so the node is runnable before any of the above. */
+    faker: ConnectorFaker;
+};
+type WebhookVerificationSpec = {
+    /** Header carrying the signature. */
+    signatureHeader: string;
+    /** Header carrying the timestamp, when the scheme signs one. */
+    timestampHeader?: string;
+    scheme: HmacScheme;
+    /**
+     * Some schemes pack the timestamp INTO the signature header
+     * (Stripe: `t=…,v1=…`). Given the raw header value, return the parts.
+     */
+    parse?: (raw: string) => {
+        signature?: string;
+        timestamp?: string;
+    };
+};
+type InboundDelivery = {
+    /** The body EXACTLY as received. Not re-serialised. See `webhook.ts`. */
+    raw: string;
+    headers: Record<string, string | string[] | undefined>;
+};
+/**
+ * Verify an inbound delivery against a trigger's declared scheme.
+ *
+ * A trigger with no `verification` REFUSES rather than accepts. That asymmetry
+ * is the whole safety property: an unverifiable endpoint is a stranger's button
+ * for starting workflows in your account, and defaulting to "allow" would make
+ * every misconfiguration into an open door that looks shut.
+ */
+declare function verifyDelivery(trigger: TriggerDescriptor, delivery: InboundDelivery, secret: string | undefined, now?: number): Promise<WebhookVerification>;
+/**
+ * The event a trigger node publishes when it runs.
+ *
+ * Three sources, in order, and the third is why a connector trigger is usable
+ * on day one:
+ *
+ * 1. A verified delivery the host injected on the `in` port.
+ * 2. Nothing injected, but the connection is remote — that is a host wiring
+ *    error, and it fails loudly rather than emitting a plausible blank.
+ * 3. `fake` mode — the trigger emits its own sample event, so an author can
+ *    press Run, see the real field names, and wire the downstream nodes against
+ *    them before the provider has ever been contacted.
+ */
+declare function triggerEvent(trigger: TriggerDescriptor, connection: ResolvedConnection, injected: unknown, config: Record<string, unknown>): unknown;
+
+export { AMBIGUOUS_REFUSAL, type ApiContract, type Attempt, type ByteRange, CONNECTOR_API_VERSION, CONNECTOR_MODES, type CallOptions, type CallResult, type Capabilities, type Catalogue, type ChainLinks, type ChainOutcome, type ChainRef, type Citation, type Classified, type ConnectionCredentials, type ConnectionHost, type ConnectionSpec, type Connector, ConnectorAmbiguous, ConnectorApiMismatch, ConnectorAuthError, ConnectorConfigError, ConnectorError, type ConnectorErrorContext, type ConnectorFaker, ConnectorIdempotencyExpiredError, type ConnectorMode, ConnectorModeError, ConnectorRateLimited, type ConnectorRequest, ConnectorRequestError, type ConnectorResult, ConnectorTransient, ConnectorUnreachable, type ContractOperation, type CredentialField, DEFAULT_IDEMPOTENCY_WINDOW_SECONDS, DEFAULT_RETRY, type DeliveryDeclaration, type DeliveryMechanism, type DeliveryOutcome, type DriftFinding, type DriftReport, FAKE_EPOCH, type FailureKind, type FakeRequest, type FakeValues, type HmacScheme, type HostEnvironment, type IdempotencyOptions, type InboundDelivery, MAX_IDEMPOTENCY_KEY_LENGTH, type MetricDescriptor, type MetricSample, type ModeInputs, NO_IDEMPOTENCY_KEY_WARNING, type PreparedRequest, type ProbeOutcome, type ProbeReport, type ProbeResult, type ProbeSpec, type Problem, type ProviderAdapter, RENDERER_VERSION, REVIEW_STALE_DAYS, type RecordedShape, type RenderRules, type RenderedPayload, type RequestedMode, type ResolveOptions, type ResolvedConnection, type RetryPolicy, type RunIdentity, SUPPORTED_CONNECTOR_API, type SandboxKind, type Segment, type ServiceDescriptor, type SetupStep, type ShapeMismatch, type SpecSource, type TextUnit, type Transport, type TransportResponse, type TriggerDescriptor, type VerifyResult, type WebhookVerification, type WebhookVerificationSpec, assertConnectorApi, byteRangeOf, callConnector, capabilityProblems, checkAgainstOpenApi, checkAgainstRecordedShape, classifyError, classifyHttp, classifyStatus, classifyThrown, compareShape, connectionsFor, constantTimeEquals, deliver, fakeRequest, fakeValues, getConnectionHost, graphemes, header, hmac, httpFailure, idempotencyKeyFor, isEmptyPayload, isRemote, isUnconditionallyRetryable, linkRanges, measure, payloadHash, postChain, probe, registerConnectionHost, registerTransport, render, reported, resetRateState, resolveConnection, resolveConnectorMode, respectRate, runIdentityFrom, runKeyFrom, runProbes, satisfiesMinimum, seedFrom, shapeOf, shouldRetry, sliceByteRange, splitToFit, triggerEvent, unchecked, utf8Length, verifyDelivery, verifyHmac };