import { StandardSchemaV1 } from '@standard-schema/spec';
import * as pino from 'pino';
import * as nodemailer from 'nodemailer';
import * as imapflow from 'imapflow';
import { TracerProvider } from '@opentelemetry/api';

/**
 * Accepted audience values for `jwt()` and `jwks()`.
 * Pass `"*"` to skip audience validation explicitly (opts out of cross-audience
 * replay protection; use only when the IdP does not emit `aud`).
 */
type JwtAudience = string | string[] | "*";
/**
 * Per-claim overrides for mapping a verified JWT payload to a {@link Principal}.
 * Each callback receives the decoded payload and returns the value to surface.
 *
 * Use when the IdP places identity claims under non-standard names
 * (e.g. Azure AD uses `oid` instead of `sub`, Keycloak nests roles under
 * `realm_access.roles`).
 */
interface ClaimMappers {
    /** Map to `Principal.subject`. Default: `payload.sub` then `client_id` then `azp`. */
    subject?: (payload: Record<string, unknown>) => string;
    /** Map to `Principal.clientId`. Default: `payload.client_id` then `azp`. */
    clientId?: (payload: Record<string, unknown>) => string;
    /**
     * Map to `Principal.scopes`. Default: space-split `payload.scope`.
     *
     * Supplying this replaces the default parse entirely, including its
     * undefined results: scopes grant authority, so a top-level `scope`
     * claim is never reinstated behind a mapper that decided against it.
     */
    scopes?: (payload: Record<string, unknown>) => string[] | undefined;
    /**
     * Map to `Principal.roles`. Default: `payload.roles` when it is an array
     * of strings (RFC 9068 section 2.2.3.1, semantics from SCIM). Override for
     * IdPs that nest roles elsewhere, e.g. Keycloak
     * (`realm_access.roles`) or WorkOS (`role`, a single string).
     *
     * Supplying this replaces the default parse entirely, including its
     * undefined results: roles grant authority, so a top-level `roles` claim
     * is never reinstated behind a mapper that decided against it.
     */
    roles?: (payload: Record<string, unknown>) => string[] | undefined;
    /**
     * Map to `Principal.actor` (the delegation chain). Default: the RFC 8693
     * `act` claim, which REQUIRES a `sub` on every entry.
     *
     * Supplying this replaces the default parse entirely, which is the
     * supported way to accept an actor identified by a non-standard claim
     * (for example `client_id` on a client-credentials actor). Without a
     * mapper, a present-but-unparseable `act` claim rejects the token: the
     * parser must not silently drop an actor, because that would promote a
     * delegated token to a direct call and pass an `actor: 'none'` route.
     */
    actor?: (payload: Record<string, unknown>) => Principal | undefined;
    /**
     * Map to `Principal.mayAct`. Default: the RFC 8693 `may_act` claim (an
     * object, or an array of objects, each requiring `sub`).
     *
     * Supplying this replaces the default parse entirely. Without a mapper, a
     * present-but-unparseable `may_act` claim rejects the token: `may_act` is
     * a restriction, and an absent `mayAct` means "unrestricted", so dropping
     * a malformed one would invert the claim's meaning.
     */
    mayAct?: (payload: Record<string, unknown>) => ActorMatcher[] | undefined;
}
/**
 * What kind of entity a principal's subject is. Wire claim: `sub_profile`
 * (aligned with draft-mcguinness-oauth-actor-profile). Orthogonal to
 * `Principal.kind`, which records HOW the principal was authenticated; a
 * human and an agent can both arrive via `kind: "jwks"`.
 *
 * An absent profile means unclassified; policy should treat unclassified
 * principals restrictively rather than assuming `"user"`.
 */
type PrincipalProfile = "user" | "service" | "ai_agent" | (string & {});
/**
 * Matches an actor (or a permitted future actor) by identity. All provided
 * fields must match (AND). Actor identity is canonically the
 * `(issuer, subject)` pair: per RFC 7519 section 4.1.2 a `sub` is only
 * locally unique within its issuer, so matching on `subject` alone is
 * ambiguous the moment two issuers exist, and a same-named agent from
 * another issuer would match. Omitting `issuer` works but is intended only
 * for single-issuer deployments; set it wherever more than one issuer can
 * mint actors.
 *
 * A matcher with no fields set (`{}`) matches ANY actor, as does one whose
 * only field is an empty `roles` array. That is deliberate (it is the
 * degenerate case of "all constraints satisfied"), but it means a matcher
 * built from partially-populated config is permissive rather than
 * restrictive; validate config before turning it into a matcher.
 */
interface ActorMatcher {
    /** Actor subject(s) to accept. An array is an OR across values. */
    subject?: string | string[];
    /** Issuer the actor's subject is scoped to. */
    issuer?: string;
    /** Entity profile(s) to accept. An array is an OR across values. */
    profile?: PrincipalProfile | PrincipalProfile[];
    /** Roles that must ALL be present on the actor's own `roles`. */
    roles?: string[];
}
/**
 * Authenticated principal resolved from an incoming request.
 *
 * The `kind` field records how the principal was authenticated (useful for
 * logs and analytics). All variants share the same flat shape -- callers
 * never need to type-narrow on `kind` to access identity fields.
 */
interface Principal {
    /**
     * How the principal was authenticated. Core verifiers use the known
     * values; ecosystem verifiers may use their own kind strings. The
     * `(string & {})` arm keeps autocomplete on the known set while
     * accepting any value.
     */
    kind: "jwt" | "jwks" | "oauth" | "custom" | (string & {});
    /** HTTP authentication scheme. `"bearer"` for token-based flows; may be another value for custom auth schemes. */
    scheme: "bearer" | string;
    /** Stable identity for the authenticated entity (JWT `sub`, user id, etc.). */
    subject: string;
    /** OAuth client ID (distinct from subject). */
    clientId?: string;
    /** Token issuer (JWT `iss`). */
    issuer?: string;
    /** Intended audiences (JWT `aud`). */
    audience?: string[];
    /** Email address from the `email` claim. */
    email?: string;
    /** Display name from the `name` claim. */
    name?: string;
    /** OAuth 2.0 / JWT scopes. */
    scopes?: string[];
    /** Roles from the `roles` claim. */
    roles?: string[];
    /**
     * Expiry as Unix epoch seconds (JWT `exp`).
     * Required by the MCP SDK bearer middleware when using the OAuth flow.
     */
    expiresAt?: number;
    /** Full decoded JWT payload (when available). */
    claims?: Record<string, unknown>;
    /**
     * Raw OIDC userinfo response (when available). Populated only when
     * `mcpPlugin({ userinfo: ... })` runs in URL or auto-discovery mode and the
     * userinfo endpoint returns a non-empty JSON body. Distinct from `claims`,
     * which always carries the verified JWT payload.
     *
     * Function-mode enrichment is free to merge into this field directly if
     * the user wants the raw upstream response surfaced; the framework does
     * not populate it automatically for the function variant.
     */
    userinfoClaims?: Record<string, unknown>;
    /**
     * What kind of entity the subject is. Wire claim: `sub_profile`. Absent
     * means unclassified; treat restrictively. See {@link PrincipalProfile}.
     */
    subjectProfile?: PrincipalProfile;
    /**
     * Current actor when this identity is being exercised by a delegate.
     * `subject` remains the party the action is taken ON BEHALF OF; `actor`
     * is the party PERFORMING it. Wire claim: `act` (RFC 8693 section 4.1).
     *
     * Nests to express a delegation chain: the outermost entry is the current
     * actor and the ONLY access-control input; nested entries are prior
     * actors, informational for audit only (RFC 8693 section 4.1 makes this a
     * MUST for token consumers). `authorize({ actor })` therefore matches the
     * outermost actor exclusively.
     *
     * Set only by `delegate()` (or parsed from a verified token's `act`
     * claim); there is no API that attaches an actor to an existing
     * principal, so authenticity always covers the whole chain.
     */
    actor?: Principal;
    /**
     * Parties permitted to become this principal's actor. Wire claim:
     * `may_act` (RFC 8693 section 4.4). RFC 8693 defines it as input to the
     * authorization server at token-exchange time; Routecraft additionally
     * enforces the same semantics in-process at the `delegate()` boundary,
     * which throws RC5037 when the requested actor matches no entry. Absent
     * means no in-process restriction (route-level `authorize({ actor })`
     * still applies).
     */
    mayAct?: ActorMatcher[];
    /**
     * Identifier of the consent record (delegation grant) this principal was
     * minted under, when the delegating caller supplied one. Opaque to the
     * framework; carried for audit and revocation correlation.
     */
    grantId?: string;
}
/**
 * Principal variant that guarantees a known token expiry. Used anywhere a
 * bearer-token lifecycle contract must be expressed at the type level
 * (most notably the OAuth flow: the MCP SDK's bearer middleware requires
 * `expiresAt`).
 */
type OAuthPrincipal = Principal & {
    expiresAt: number;
};
/**
 * Verifies a bearer token and resolves the authenticated principal.
 * Throw to reject access; return a {@link Principal} to allow it.
 * May be synchronous or asynchronous.
 */
type TokenVerifier = (token: string) => Principal | Promise<Principal>;
/**
 * OAuth-flavoured {@link TokenVerifier}. Guarantees the returned principal
 * carries a known `expiresAt`, which the MCP SDK's bearer middleware
 * requires. Any verifier composed into `oauth({ verify })` must satisfy
 * this shape.
 */
type OAuthTokenVerifier = (token: string) => OAuthPrincipal | Promise<OAuthPrincipal>;
/**
 * Validator-based auth: a bearer token verified on every request.
 * Returned by `jwt()` and `jwks()` helpers; also accepted as a plain object
 * with a custom `validator` function.
 *
 * @example
 * ```ts
 * import { jwt } from "@routecraft/routecraft";
 * auth: jwt({ secret: process.env.JWT_SECRET! })
 *
 * // Custom validator -- throw to reject
 * auth: {
 *   validator: async (token) => {
 *     const user = await lookupApiKey(token);
 *     if (!user) throw new Error("unknown token");
 *     return { kind: "custom", scheme: "bearer", subject: user.id };
 *   }
 * }
 *
 * // A single shared secret. Compare it in constant time: `===` returns as
 * // soon as two bytes differ, and that timing is measurable.
 * import { timingSafeStringEqual } from "@routecraft/routecraft";
 * auth: {
 *   validator: (token) => {
 *     if (!timingSafeStringEqual(process.env.OPS_SECRET!, token)) {
 *       throw new Error("unknown token");
 *     }
 *     return { kind: "custom", scheme: "bearer", subject: "ops" };
 *   }
 * }
 * ```
 */
interface ValidatorAuthOptions {
    /** Verifier called with the raw bearer token on every request. Throw to reject. */
    validator: TokenVerifier;
}
/**
 * OAuth-flavoured {@link ValidatorAuthOptions}. The `validator` is guaranteed
 * to resolve an {@link OAuthPrincipal} (with `expiresAt`). Returned by
 * `jwt()` and `jwks()` because both helpers require `exp` on verified tokens.
 *
 * Structurally a subtype of `ValidatorAuthOptions`, so the same value is
 * also usable in non-OAuth contexts.
 */
interface OAuthValidatorAuthOptions {
    /** Verifier called with the raw bearer token on every request. Throw to reject. */
    validator: OAuthTokenVerifier;
    /**
     * Expected token issuer(s), surfaced from the underlying helper (`jwt()` /
     * `jwks()`). Read by `mcpPlugin({ userinfo: true })` to locate the OIDC
     * Discovery document. Optional because custom validators may not declare an
     * issuer; if absent, OIDC auto-discovery cannot be used and the caller must
     * pass an explicit userinfo URL or function.
     */
    issuer?: string | string[];
    /**
     * Clock skew the underlying helper allowed when it checked `exp`, surfaced
     * so a downstream expiry check can apply the same tolerance. Without it a
     * consumer re-checking `expiresAt` would refuse the very token `jwt()` /
     * `jwks()` just accepted within skew.
     */
    clockToleranceSec?: number;
}
declare module "@routecraft/routecraft" {
    interface RoutecraftHeaders {
        /**
         * Authenticated principal resolved from the request, when available.
         *
         * One header carries the entire structured `Principal` rather than ten
         * flat string keys (subject, issuer, audience, ...). The `ex.principal`
         * getter is sugar over reading this header. See
         * `.standards/exchange-state-model.md` for the rationale (cross-cutting
         * concerns get one header key, never a special field).
         */
        "routecraft.auth.principal"?: Principal;
    }
}

/**
 * Supported HMAC algorithms for JWT signature verification.
 * Maps JWT `alg` header values to Node.js `crypto.createHmac` digest names.
 */
declare const HMAC_ALGORITHMS: {
    readonly HS256: "sha256";
    readonly HS384: "sha384";
    readonly HS512: "sha512";
};
/**
 * Supported RSA algorithms for JWT signature verification.
 * Maps JWT `alg` header values to Node.js `crypto.createVerify` algorithm names.
 */
declare const RSA_ALGORITHMS: {
    readonly RS256: "RSA-SHA256";
    readonly RS384: "RSA-SHA384";
    readonly RS512: "RSA-SHA512";
};
type HmacAlgorithm = keyof typeof HMAC_ALGORITHMS;
type RsaAlgorithm = keyof typeof RSA_ALGORITHMS;
/**
 * HMAC (symmetric) JWT options.
 * Uses a shared secret to sign and verify tokens.
 */
interface JwtHmacOptions {
    /** Shared secret used to verify HMAC signatures. */
    secret: string;
    /**
     * HMAC algorithm to accept. Default: `"HS256"`.
     * The helper rejects tokens whose `alg` header does not match.
     */
    algorithm?: HmacAlgorithm;
    /**
     * Clock skew tolerance in seconds for `exp` and `nbf` checks.
     * Default: `0` (no tolerance).
     */
    clockToleranceSec?: number;
    /**
     * Expected `iss` claim. Tokens whose `iss` does not match are rejected.
     * Required to prevent cross-issuer token replay.
     */
    issuer: string | string[];
    /**
     * Expected `aud` claim. Pass `"*"` to explicitly skip audience validation
     * (cross-audience token replay becomes possible -- use only when the IdP
     * does not emit `aud`, e.g. Clerk with no API audience configured).
     * Required to prevent cross-audience token replay.
     */
    audience: JwtAudience;
    /** Optional per-claim overrides for non-standard IdPs. */
    claims?: ClaimMappers;
}
/**
 * RSA (asymmetric) JWT options.
 * Uses a public key to verify signatures.
 */
interface JwtRsaOptions {
    /** PEM-encoded public key or certificate used to verify RSA signatures. */
    publicKey: string;
    /**
     * RSA algorithm to accept. Default: `"RS256"`.
     * The helper rejects tokens whose `alg` header does not match.
     */
    algorithm?: RsaAlgorithm;
    /**
     * Clock skew tolerance in seconds for `exp` and `nbf` checks.
     * Default: `0` (no tolerance).
     */
    clockToleranceSec?: number;
    /**
     * Expected `iss` claim. Tokens whose `iss` does not match are rejected.
     * Required to prevent cross-issuer token replay.
     */
    issuer: string | string[];
    /**
     * Expected `aud` claim. Pass `"*"` to explicitly skip audience validation
     * (cross-audience token replay becomes possible -- use only when the IdP
     * does not emit `aud`, e.g. Clerk with no API audience configured).
     * Required to prevent cross-audience token replay.
     */
    audience: JwtAudience;
    /** Optional per-claim overrides for non-standard IdPs. */
    claims?: ClaimMappers;
}
/**
 * Options for the built-in static-key JWT auth helper.
 * Supports HMAC (symmetric) and RSA (asymmetric) signing.
 *
 * Discriminated by key: pass `secret` for HMAC, `publicKey` for RSA.
 */
type JwtAuthOptions = JwtHmacOptions | JwtRsaOptions;
/**
 * Built-in static-key JWT authentication helper.
 * Verifies HMAC or RSA signed JWTs using only `node:crypto` (no external
 * dependencies).
 *
 * Returns an {@link OAuthValidatorAuthOptions} that can be passed directly to
 * `mcpPlugin({ auth: jwt({ ... }) })` or `oauth({ verify: jwt({ ... }) })`.
 * Because the return type guarantees an {@link OAuthPrincipal}, it is also
 * structurally assignable wherever a plain `ValidatorAuthOptions` is accepted.
 *
 * On success the validator returns an {@link OAuthPrincipal} (`kind: "jwt"`)
 * populated from standard JWT claims (`sub`, `iss`, `aud`, `exp`, `scope`,
 * etc.) with the full decoded payload available in `claims`.
 *
 * Security: `issuer` is required to bind tokens to the expected IdP and prevent
 * cross-issuer replay. `audience` is required (or explicitly set to `"*"` to
 * opt out) to bind tokens to this resource and prevent cross-audience replay.
 * Tokens without an `exp` claim are always rejected.
 *
 * @example
 * ```ts
 * import { mcpPlugin, jwt } from "@routecraft/ai";
 *
 * // HMAC (symmetric): shared secret
 * mcpPlugin({
 *   transport: "http",
 *   auth: jwt({
 *     secret: process.env.JWT_SECRET!,
 *     issuer: "https://idp.example.com",
 *     audience: "https://mcp.example.com",
 *   }),
 * });
 *
 * // RSA (asymmetric): public key only
 * mcpPlugin({
 *   transport: "http",
 *   auth: jwt({
 *     algorithm: "RS256",
 *     publicKey: process.env.JWT_PUBLIC_KEY!,
 *     issuer: "https://idp.example.com",
 *     audience: "https://mcp.example.com",
 *   }),
 * });
 * ```
 */
declare function jwt(options: JwtAuthOptions): OAuthValidatorAuthOptions;

/**
 * Options for the JWKS-backed JWT auth helper.
 */
interface JwksOptions {
    /**
     * JWKS endpoint URL used to fetch the IdP's signing keys.
     * Keys are cached and rotated by `jose`'s `createRemoteJWKSet`.
     */
    jwksUrl: string | URL;
    /**
     * Expected `iss` claim. Tokens whose issuer does not match are rejected,
     * preventing cross-issuer replay.
     */
    issuer: string | string[];
    /**
     * Expected `aud` claim. Pass `"*"` to explicitly skip audience validation
     * (cross-audience token replay becomes possible -- use only when the IdP
     * does not emit `aud`, e.g. Clerk with no API audience configured).
     * Required to prevent cross-audience token replay.
     */
    audience: JwtAudience;
    /**
     * Accepted JWS algorithms. Defaults to the asymmetric `RS*`/`PS*`/`ES*`/`EdDSA`
     * family. Restrict further if the IdP only uses a single algorithm; expand
     * only if the IdP uses something outside the defaults.
     */
    algorithms?: string[];
    /**
     * Clock skew tolerance in seconds applied to `exp` and `nbf` validation.
     * Passed through to `jose`'s `jwtVerify`. Default: no tolerance.
     */
    clockToleranceSec?: number;
    /** Optional per-claim overrides for non-standard IdPs. */
    claims?: ClaimMappers;
}
/**
 * JWKS-backed JWT authentication helper.
 * Verifies bearer JWTs against a remote JWKS endpoint using `jose`.
 * Keys are cached and rotated automatically. Tokens without an `exp` claim
 * are always rejected (enforced via `jose`'s `requiredClaims`).
 *
 * Returns an {@link OAuthValidatorAuthOptions} that can be passed directly to
 * `mcpPlugin({ auth: jwks({ ... }) })` or `oauth({ verify: jwks({ ... }) })`.
 * Because the return type guarantees an {@link OAuthPrincipal}, it is also
 * structurally assignable wherever a plain `ValidatorAuthOptions` is accepted.
 *
 * On success the validator returns an {@link OAuthPrincipal} (`kind: "jwks"`)
 * populated from standard JWT claims (`sub`, `iss`, `aud`, `exp`, `scope`,
 * etc.) with the full decoded payload available in `claims`.
 *
 * Requires the optional peer dependency `jose`:
 * ```sh
 * bun add jose
 * ```
 *
 * @example
 * ```ts
 * import { mcpPlugin, jwks } from "@routecraft/ai";
 *
 * // Standalone: just verify bearer JWTs (no OAuth proxy flow)
 * mcpPlugin({
 *   transport: "http",
 *   auth: jwks({
 *     jwksUrl: "https://idp.example.com/.well-known/jwks.json",
 *     issuer: "https://idp.example.com",
 *     audience: "https://mcp.example.com",
 *   }),
 * });
 * ```
 */
declare function jwks(options: JwksOptions): OAuthValidatorAuthOptions;

/**
 * Well-known error categories used by core codes. Ecosystem packages may
 * use their own category strings; the `(string & {})` arm keeps
 * autocomplete on the known set while accepting any value.
 */
type KnownErrorCategory = "Definition" | "DSL" | "Lifecycle" | "Adapter" | "Runtime";
type RCMeta = {
    category: KnownErrorCategory | (string & {});
    message: string;
    suggestion?: string;
    docs: string;
    /**
     * Whether this error should be retried by the retry wrapper.
     * - `true`: Transient error, retry may succeed (e.g., network issues)
     * - `false`: Permanent error, retry will not help (e.g., validation, config)
     */
    retryable: boolean;
};
/**
 * Open error-code registry. Core declares its own `RC####` codes here;
 * ecosystem packages add namespaced codes via declaration merging plus a
 * runtime {@link registerErrorCodes} call:
 *
 * ```typescript
 * declare module "@routecraft/routecraft" {
 *   interface ErrorCodeRegistry {
 *     AI1001: RCMeta;
 *   }
 * }
 * registerErrorCodes("AI", { AI1001: { ... } }, "@routecraft/ai");
 * ```
 *
 * The `RC` namespace is reserved for core. Each namespace is claimable by
 * exactly one owner package, which makes cross-package code collisions a
 * detectable package-identity conflict instead of a silent numbering
 * accident (TypeScript merges identical `X: RCMeta` declarations without
 * complaint, so the compiler alone cannot catch them).
 */
interface ErrorCodeRegistry {
    RC1001: RCMeta;
    RC1002: RCMeta;
    RC1003: RCMeta;
    RC1004: RCMeta;
    RC2001: RCMeta;
    RC2002: RCMeta;
    RC3001: RCMeta;
    RC3002: RCMeta;
    RC5001: RCMeta;
    RC5002: RCMeta;
    RC5003: RCMeta;
    RC5004: RCMeta;
    RC5010: RCMeta;
    RC5011: RCMeta;
    RC5012: RCMeta;
    RC5013: RCMeta;
    RC5014: RCMeta;
    RC5015: RCMeta;
    RC5016: RCMeta;
    RC5017: RCMeta;
    RC5018: RCMeta;
    RC5019: RCMeta;
    RC5020: RCMeta;
    RC5021: RCMeta;
    RC5022: RCMeta;
    RC5023: RCMeta;
    RC5024: RCMeta;
    RC5025: RCMeta;
    RC5026: RCMeta;
    RC5028: RCMeta;
    RC5029: RCMeta;
    RC5030: RCMeta;
    RC5031: RCMeta;
    RC5032: RCMeta;
    RC5033: RCMeta;
    RC5034: RCMeta;
    RC5035: RCMeta;
    RC5036: RCMeta;
    RC5037: RCMeta;
    RC5038: RCMeta;
    RC5039: RCMeta;
    RC5040: RCMeta;
    RC5041: RCMeta;
    RC5042: RCMeta;
    RC5043: RCMeta;
    RC5044: RCMeta;
    RC5045: RCMeta;
    RC5046: RCMeta;
    RC5047: RCMeta;
    RC5048: RCMeta;
    RC5049: RCMeta;
    RC5050: RCMeta;
    RC5051: RCMeta;
    RC5052: RCMeta;
    RC5053: RCMeta;
    RC5054: RCMeta;
    RC5055: RCMeta;
    RC5056: RCMeta;
    RC5057: RCMeta;
    RC5058: RCMeta;
    RC5059: RCMeta;
    RC5060: RCMeta;
    RC5061: RCMeta;
    RC5062: RCMeta;
    RC5063: RCMeta;
    RC5064: RCMeta;
    RC5065: RCMeta;
    RC5066: RCMeta;
    RC9901: RCMeta;
}
/** All known error codes: core `RC####` plus registered ecosystem namespaces. */
type RCCode = keyof ErrorCodeRegistry;
/**
 * Core codes only: the `RC####` keys declared in this file. Ecosystem keys
 * merged into {@link ErrorCodeRegistry} are excluded so the `RC` const
 * below stays exhaustively checked against what core actually defines.
 */
type CoreErrorCode = keyof ErrorCodeRegistry & `RC${number}`;
declare const RC: {
    [K in CoreErrorCode]: RCMeta;
};
declare class RoutecraftError extends Error {
    readonly rc: RCCode;
    readonly meta: RCMeta;
    /**
     * Whether this error should be retried by the retry wrapper.
     */
    readonly retryable: boolean;
    constructor(rc: RCCode, meta: RCMeta, cause?: unknown);
    toString(): string;
    /**
     * Used by pino and other serializers so log output includes rc, message, suggestion, docs, causeMessage, causeStack as searchable fields.
     */
    toJSON(): Record<string, unknown>;
    static parse(cause: unknown): {
        message: string;
        error: Error;
    };
}
/**
 * Formats Standard Schema validation issues into a human-readable string.
 * Each issue becomes "path: message" (or just "message" when there is no path).
 *
 * @param issues - The raw issues value from a Standard Schema validation result
 * @returns A formatted string describing what failed
 *
 * @example
 * ```
 * formatSchemaIssues([{ message: "Required", path: ["name"] }])
 * // => '"name": Required'
 * ```
 */
declare function formatSchemaIssues(issues: unknown): string;
/**
 * Creates a RoutecraftError with the given code and optional cause/overrides.
 *
 * @param rc - Error code from the RC registry (e.g. "RC5001", "RC1002")
 * @param cause - Optional underlying error (stored as cause, message can be overridden)
 * @param overrides - Optional overrides for message, suggestion, docs, or
 *   retryable (e.g. an adapter that knows a specific occurrence of a
 *   normally-permanent code is transient, or vice versa)
 * @returns A RoutecraftError instance (branded, with retryable from RC meta)
 *
 * @example
 * ```typescript
 * throw rcError("RC5002", new Error("Invalid payload"), { message: "Validation failed" });
 * ```
 */
declare function rcError(rc: RCCode, cause?: unknown, overrides?: Partial<Pick<RCMeta, "message" | "suggestion" | "docs" | "retryable">>): RoutecraftError;
/**
 * Register ecosystem error codes under a claimed namespace.
 *
 * Call once at module load time (typically from a side-effect import next
 * to the matching `declare module` augmentation of {@link ErrorCodeRegistry}).
 * Each namespace is claimable by exactly one owner package; a second claim
 * throws RC1003 naming both packages so consumers know which two packages
 * collide (they cannot fix the collision themselves). Re-registration by
 * the same owner is idempotent and replaces the previous codes, so module
 * re-evaluation (test runners, HMR) is safe.
 *
 * @param namespace - Unique uppercase prefix, e.g. "AI" (`RC` is reserved for core)
 * @param codes - Map of `${namespace}${4 digits}` codes to their metadata
 * @param owner - Owning package name, used in collision diagnostics
 *
 * @example
 * ```typescript
 * registerErrorCodes(
 *   "AI",
 *   { AI1001: { category: "Adapter", message: "...", docs: "...", retryable: false } },
 *   "@routecraft/ai",
 * );
 * ```
 */
declare function registerErrorCodes(namespace: string, codes: Record<string, RCMeta>, owner: string): void;

/**
 * How long a deferral stays resumable: milliseconds, or a duration
 * string with a unit suffix (`"500ms"`, `"30s"`, `"15m"`, `"72h"`, `"7d"`).
 *
 * The string form exists because the realistic values here are human ones:
 * an approval window is three days, not 259_200_000.
 */
type Duration = number | `${number}${DurationUnit}`;
/** Unit suffixes accepted by {@link parseDuration}. */
type DurationUnit = "ms" | "s" | "m" | "h" | "d";
/**
 * Resolve a {@link Duration} to milliseconds.
 *
 * The single duration guard for the whole framework: every authored time
 * option parses here, so the accepted grammar cannot drift between the
 * surfaces that use it.
 *
 * @param value - Milliseconds, or a duration string
 * @param field - Option name quoted in the error message
 * @param min - Smallest accepted duration. `1` (the default) for a
 *   deadline, where zero means "already expired" and is always a mistake;
 *   `0` for a wait, where zero legitimately means "do not wait".
 * @returns The duration in milliseconds
 * @throws RC5003 when the value is not a duration an `expiresAt` `Date`
 *   can represent: at least `min` milliseconds, and not past the end of
 *   the representable time range
 */
declare function parseDuration(value: Duration, field: string, min?: 0 | 1): number;

/**
 * Cron expression with autocomplete for nicknames and common patterns.
 * Accepts any valid cron string (5-field or 6-field) as well.
 */
type CronExpression = "@yearly" | "@annually" | "@monthly" | "@weekly" | "@daily" | "@midnight" | "@hourly" | "* * * * *" | "*/5 * * * *" | "*/15 * * * *" | "*/30 * * * *" | "0 * * * *" | "0 0 * * *" | "0 0 * * 0" | "0 0 1 * *" | "0 0 1 1 *" | (string & {});
/**
 * Configuration options for the cron source adapter.
 */
interface CronOptions {
    /**
     * IANA timezone for the cron schedule (e.g., "America/New_York")
     * @default undefined (system timezone)
     */
    timezone?: string;
    /**
     * Maximum number of times the cron job will fire before stopping.
     * Delegated to croner's `maxRuns` option.
     * @default Infinity
     */
    maxFires?: number;
    /**
     * Upper bound on a random delay added to each trigger, to prevent
     * synchronized spikes in distributed deployments. Each delay is drawn
     * uniformly from `[0, maxJitter)`.
     * Recommended: "1s" to "30s" for production workloads.
     * Can be set globally via `ADAPTER_CRON_OPTIONS` in the context store.
     * @default 0
     */
    maxJitter?: Duration;
    /**
     * Human-readable name for the cron job, used in headers for observability
     * @default undefined
     */
    name?: string;
    /**
     * If true, prevents the job from running if the previous execution
     * (including any jitter delay) is still in progress. Delegated to
     * croner's `protect` option.
     * @default true
     */
    protect?: boolean;
    /**
     * Date or ISO 8601 string at which the cron job should start running.
     * Ticks before this date are skipped.
     * @default undefined (starts immediately)
     */
    startAt?: Date | string;
    /**
     * Date or ISO 8601 string at which the cron job should stop running.
     * The job is permanently stopped once this date is reached.
     * @default undefined (runs indefinitely)
     */
    stopAt?: Date | string;
}
/**
 * Header keys the cron source sets on every emitted exchange. Keys live
 * under the reserved `routecraft.cron.*` namespace; the value types are
 * merged into `RoutecraftHeaders` below.
 */
declare const CronHeaders: {
    /** The cron expression that triggered this exchange */
    readonly EXPRESSION: "routecraft.cron.expression";
    /** The timestamp when the cron job fired, in ISO 8601 format */
    readonly FIRED_TIME: "routecraft.cron.firedTime";
    /** The next timestamp when the cron job will fire, in ISO 8601 format */
    readonly NEXT_RUN: "routecraft.cron.nextRun";
    /** The number of times the cron job has fired */
    readonly COUNTER: "routecraft.cron.counter";
    /** The IANA timezone for the cron schedule */
    readonly TIMEZONE: "routecraft.cron.timezone";
    /** The human-readable name for the cron job */
    readonly NAME: "routecraft.cron.name";
};
declare module "@routecraft/routecraft" {
    interface RoutecraftHeaders {
        /** The cron expression that triggered this exchange */
        [CronHeaders.EXPRESSION]?: string;
        /** The timestamp when the cron job fired, in ISO 8601 format */
        [CronHeaders.FIRED_TIME]?: string;
        /** The next timestamp when the cron job will fire, in ISO 8601 format */
        [CronHeaders.NEXT_RUN]?: string;
        /** The number of times the cron job has fired */
        [CronHeaders.COUNTER]?: number;
        /** The IANA timezone for the cron schedule */
        [CronHeaders.TIMEZONE]?: string;
        /** The human-readable name for the cron job */
        [CronHeaders.NAME]?: string;
    }
}

/**
 * What an {@link EnablementPredicate} answers with.
 *
 * `true` enables the route. A string disables it and IS the reason, so ops
 * can report why without the author declaring the reason a second time
 * (which is the declaration that goes stale). `false` disables it with a
 * generic reason, for a predicate that has nothing useful to add.
 */
type EnablementVerdict = boolean | string;
/**
 * Decides whether a route runs.
 *
 * Evaluated once as the context starts, and again on the cadence the route
 * declared via {@link EnablementOptions.refresh}. It is per-route lifecycle,
 * not per-exchange filtering: it never sees an exchange and never runs on
 * the hot path.
 *
 * A predicate that throws leaves the route disabled with the error message
 * as its reason and never fails the boot. A capability whose credentials are
 * missing is a configuration state, and a configuration state must not take
 * the process down.
 */
type EnablementPredicate = () => EnablementVerdict | Promise<EnablementVerdict>;
/**
 * How often a route's predicate is re-evaluated.
 *
 * A {@link Duration} is a fixed interval; a cron expression is a schedule.
 * They are told apart by shape rather than by a mode flag: every cron
 * expression contains a space or starts with `@`, and no `Duration` does.
 */
type RefreshCadence = Duration | CronExpression | typeof MANUAL_REFRESH;
/**
 * Explicit opt-out from any refresh cadence: the predicate is evaluated once
 * as the route starts and never again until something asks.
 *
 * Omitting `refresh` means the same thing, so this exists for the case where
 * the cadence is COMPUTED: `refresh: pollCadence ?? "manual"` says what it
 * means, where the alternative is assembling the options object
 * conditionally. It also restores the sentinel precedent `deferral`
 * already sets with `defaultTtl: "never"` and `retention: "never"`.
 */
declare const MANUAL_REFRESH = "manual";
/**
 * `drainGrace` value meaning "wait as long as it takes": the disable never
 * forces, and in-flight exchanges always reach a terminal outcome.
 *
 * The route stops intaking immediately either way, so this trades a bounded
 * transition for a guaranteed one. Choose it when the work is more expensive
 * to lose than the transition is to wait for, and only when the pipeline is
 * known to terminate; a step that can hang holds the disable open forever.
 */
declare const NEVER_FORCE = "never";
/** Options for the second argument of `.enabled()`. */
interface EnablementOptions {
    /**
     * Re-evaluate the predicate on this cadence.
     *
     * Omitted (the default) is MANUAL: the predicate runs once as the route
     * starts and never again until something explicitly asks. That keeps the
     * common case, an environment variable that cannot change without a
     * restart, free of any recurring cost, and it stops a predicate that
     * reaches the network from becoming an invisible repeating one.
     *
     * Pass `"manual"` to say so explicitly, which is what a computed cadence
     * wants: `refresh: pollCadence ?? "manual"`.
     */
    refresh?: RefreshCadence;
    /**
     * How long in-flight exchanges may keep running after the route stops
     * intaking, before execution is abandoned.
     *
     * Defaults to the context's `shutdown.timeout`, because a disable is a
     * per-route shutdown and one knob for both is what an operator expects to
     * find. Set it per route when the author knows what this pipeline's
     * in-flight work actually costs: a route whose steps take a minute needs
     * longer than the 30 second default, and a route of fast steps can be
     * taken out of service far quicker.
     *
     * `"never"` ({@link NEVER_FORCE}) waits indefinitely, so every in-flight
     * exchange reaches a terminal outcome and nothing is abandoned. See
     * {@link NEVER_FORCE} for when that is the right trade.
     */
    drainGrace?: Duration | typeof NEVER_FORCE;
}
/**
 * A route's enablement declaration, as stored on its definition.
 *
 * @internal The shape is internal; declare it with `.enabled()`.
 */
interface RouteEnablement {
    readonly predicate: EnablementPredicate;
    readonly refresh?: RefreshCadence;
    readonly drainGrace?: Duration | typeof NEVER_FORCE;
}
/**
 * Where a route stands: enabled, or disabled with the reason ops reports.
 *
 * A discriminated union rather than a `{ enabled, reason? }` pair so a
 * reader cannot consult `reason` on an enabled route, and so the disabled
 * arm can never be constructed without one.
 */
type EnablementState = {
    readonly enabled: true;
} | {
    readonly enabled: false;
    readonly reason: string;
};

/**
 * Type registries for compile-time safety via declaration merging.
 *
 * Users populate these empty interfaces in their project to enable
 * strict autocomplete and red-line errors for misconfigured endpoints,
 * providers, and event names. When a registry is empty, the corresponding
 * adapter falls back to accepting any string (no breaking change).
 *
 * @example
 * ```typescript
 * // In your project's types file:
 * declare module '@routecraft/routecraft' {
 *   interface DirectEndpointRegistry {
 *     'payments': PaymentData;
 *     'orders': OrderData;
 *   }
 * }
 *
 * // Now direct('payments', { ... }) autocompletes and
 * // direct('nonexistent', { ... }) shows a red line.
 * ```
 */
/**
 * Registry for direct adapter endpoints.
 *
 * Keys are endpoint strings (e.g. 'payments'), values are the body type
 * for that endpoint. Populate via declaration merging to constrain
 * `direct()`, `ForwardFn`, and related APIs.
 */
interface DirectEndpointRegistry {
}
/**
 * Resolves a registry to its string keys when populated,
 * or falls back to `string` when the registry is empty.
 *
 * @template Registry - The registry interface to resolve
 */
type ResolveKey<Registry> = keyof Registry extends never ? string : Extract<keyof Registry, string>;
/**
 * Resolves the body type for a registry endpoint.
 * When the registry is populated and the key exists, returns the mapped value type.
 * Falls back to `Fallback` (default `unknown`) when the registry is empty or key is unregistered.
 *
 * @template Registry - The registry interface to look up
 * @template K - The endpoint key to resolve
 * @template Fallback - Fallback type when key is not found (default `unknown`)
 */
type ResolveBody<Registry, K extends string, Fallback = unknown> = keyof Registry extends never ? Fallback : K extends keyof Registry ? Registry[K] : Fallback;
/**
 * Resolved direct endpoint type.
 * Constrained to registered endpoints when `DirectEndpointRegistry` is populated,
 * falls back to `string` when empty.
 */
type RegisteredDirectEndpoint = ResolveKey<DirectEndpointRegistry>;

/**
 * A log file the logger was asked for and could not open. Read by the CLI,
 * which owns the setting and refuses to run with its logs diverted.
 *
 * @internal
 */
interface LogFileDiversion {
    /** The file as it was named. */
    path: string;
    /** Where the name came from. */
    source: "LOG_FILE" | "CRAFT_LOG_FILE" | "craft.log";
    /** Why it could not be opened for appending. */
    reason: string;
}
/**
 * The log file the logger could not open, if it was asked for one.
 *
 * The logger never fails over its destination: an embedding application
 * cannot be stopped by its logger, so a file that cannot be opened diverts
 * the logs to a file of the same name in the temporary directory, then to
 * standard error. A host that owns the setting reads this to refuse instead.
 *
 * @internal
 */
declare function logFileDiversion(): LogFileDiversion | undefined;
/**
 * Framework-level pino logger instance. Configured via craft.log.{cjs,js} or environment variables.
 */
declare const logger: pino.Logger<string, boolean>;

/**
 * Metadata the engine passes to a source adapter at subscribe time.
 *
 * Carries the route's id and optional discovery bundle so adapters that
 * maintain registries (direct, mcp) can mirror route-level metadata into
 * their own registry entries without re-declaring it in adapter options.
 */
interface SourceMeta {
    /** ID of the route this source is subscribed to. */
    routeId: string;
    /** Route-level discovery bundle, when set via the builder. */
    discovery?: RouteDiscovery;
    /**
     * The route declares a route-entry `.authorize()`, so it cannot run
     * without a verified principal. Identity-capable transports (the http
     * dispatcher) use this to pull credential verification even on a mount
     * with no wall; transports without a credential channel ignore it and
     * the authorize step rejects at route entry as before.
     */
    requiresPrincipal?: boolean;
    /**
     * The route's consumer may hold a message before the pipeline runs, as
     * `.batch()` does, so `emit()` returning does not mean work has started or
     * that the route counts it as in flight.
     *
     * A source that acknowledges a delivery on its own authority needs to know
     * this: it would otherwise report success for a message the route can still
     * discard at shutdown. Sources that simply await `emit()` can ignore it.
     */
    bufferedConsumer?: boolean;
}
/**
 * Everything a source adapter needs from the engine, handed to
 * {@link CallableSource} as a single object. Adding a capability to this
 * interface is additive; the source contract never changes shape again.
 *
 * Sources that authenticate at their boundary (e.g. the MCP server with
 * `auth:` configured) forward the resolved identity by writing the
 * structured `Principal` into `headers["routecraft.auth.principal"]`
 * on the emitted message: state lives on `headers`, full stop.
 *
 * @template T - Body type of messages produced by this source (after parse)
 */
interface Subscription<T = unknown> {
    /** The owning context (store access, logger, events). */
    context: CraftContext;
    /** Fires when the route stops; sources must stop producing and return. */
    signal: AbortSignal;
    /** Route id and discovery bundle for registry-maintaining sources. */
    meta: SourceMeta;
    /**
     * Signal readiness: the source is wired and able to produce. Routes
     * emit `route:started` once every source has called this (emitting a
     * first message also marks readiness as a fallback).
     */
    ready(): void;
    /**
     * Signal that this finite source has finished producing. Aborts the
     * source's controller so a single-source route completes; on a
     * multi-ingress route only this source's child controller aborts.
     * Pass a reason to record an abnormal completion as the abort reason;
     * to surface a fatal source error to the engine, reject from
     * `subscribe` instead (the route aborts with that error). Idempotent:
     * calling it again (or after the signal already aborted) is a no-op.
     */
    complete(reason?: unknown): void;
    /**
     * Hand one message to the route. Resolves with the processed exchange
     * (or rejects with the pipeline error, which sources typically catch
     * and log so one bad message does not kill the source).
     *
     * The {@link Message} envelope carries the payload plus the optional
     * `parse` / `parseFailureMode` used by the synthetic parse step: when
     * `parse` is set, `message` is the RAW value (e.g. a JSON line string)
     * and the parsed result becomes the exchange body. See
     * `adapters/shared/parse.ts` for the `OnParseError` semantics.
     */
    emit(msg: Message<T>): Promise<Exchange>;
}
/**
 * Function form of a source: subscribes to data and emits messages until
 * the subscription's signal aborts. Use with `.from(callableSource)` or
 * adapters that implement {@link Source}.
 *
 * ```ts
 * .from(async (sub) => {
 *   while (!sub.signal.aborted) {
 *     const item = await poll();
 *     await sub.emit({ message: item, headers: { "x-origin": "poll" } });
 *   }
 * })
 * ```
 *
 * @template T - Body type of messages produced by this source (after parse)
 */
type CallableSource<T = unknown> = (sub: Subscription<T>) => Promise<void> | void;
/**
 * Source adapter: produces messages for a route. Used with `.from(source)`.
 *
 * @template T - Body type of messages produced
 */
interface Source<T = unknown> extends Adapter {
    subscribe: CallableSource<T>;
}
/**
 * Generator form of a source: an (async) generator function receiving the
 * {@link Subscription} and yielding message bodies. Each yielded value is
 * emitted sequentially (`await sub.emit(...)` per item, so the pipeline
 * applies natural backpressure); when the generator returns, the source
 * completes like any finite source. Use `sub.emit({ message, headers })`
 * directly inside the generator when a message needs headers.
 *
 * ```ts
 * .from(async function* (sub) {
 *   while (!sub.signal.aborted) {
 *     yield await poll();
 *   }
 * })
 * ```
 *
 * @template T - Body type of messages produced by this source
 */
type GeneratorSource<T = unknown> = (sub: Subscription<T>) => AsyncGenerator<T, void, unknown> | Generator<T, void, unknown>;
/**
 * Anything `.from()` accepts and normalizes into a {@link Source}:
 * a Source adapter, a callable source, an (async) generator function,
 * or a bare (async) iterable of message bodies.
 *
 * @template T - Body type of messages produced
 */
type SourceLike<T = unknown> = Source<T> | CallableSource<T> | GeneratorSource<T> | AsyncIterable<T> | Iterable<T>;
/** A non-empty list of sources, the type a helper returns so `.from(...helper())` compiles. */
type SourceList = [SourceLike<unknown>, ...SourceLike<unknown>[]];

/**
 * Symbol used by registerDsl to access the builder's internal addStep method.
 * Defined in a separate module to avoid circular imports between builder.ts
 * and dsl.ts.
 *
 * @internal
 */
declare const PUSH_STEP: unique symbol;
/**
 * Symbol used by sub-pipeline builders (the shared PathBuilder for choice and
 * multicast paths) to hand their compiled step array back to their parent Step
 * without exposing a public `.steps()` API. Keeps the "no headless builder"
 * constraint on RouteBuilder intact.
 *
 * @internal
 */
declare const COLLECT_STEPS: unique symbol;
/**
 * Symbol a step implements to expose the sub-pipelines it carries (choice
 * branches, multicast paths, dispatch targets) to framework-level walks of
 * a route's step tree, without widening the public `Step` contract or
 * making those step arrays writable from outside.
 *
 * The one walk today is the defer-site resolver, which has to know both
 * that a sub-pipeline exists and whether it rejoins the main flow.
 *
 * @internal
 */
declare const NESTED_STEPS: unique symbol;
/**
 * Symbol a step implements to expose the step instance that hosts a
 * re-entrant defer site: the `.to()` / `.enrich()` step whose adapter
 * carries the defer-capable brand. Step-scope wrappers forward it to
 * their inner step (like {@link NESTED_STEPS}), so the defer-site walk
 * can store the site on the instance whose `execute` converts the defer
 * signal, however deeply the step is wrapped.
 *
 * @internal
 */
declare const DEFER_HOST: unique symbol;

/**
 * Where a `.defer()` sits in a route, and what runs when it is resumed.
 *
 * Resolved once at `craft().build()` time and stored on the route
 * definition, for one reason: execution two happens in a different process,
 * so the continuation cannot be a closure captured at defer time. It has
 * to be re-derivable from the route definition alone, and a site is exactly
 * that derivation.
 */
interface DeferSite {
    /**
     * Stable address of the deferring step within the route.
     *
     * The index of the step in a pre-order walk of the route's step tree, not
     * an index into `definition.steps`: a defer inside a `.choice()` branch
     * is a real position that a flat index cannot name. Two processes running
     * the same route source derive the same numbers, which is all the address
     * has to guarantee. The record's `position` field carries it, and
     * `position + 1` onward is {@link DeferSite.continuation}, except for a
     * re-entrant site, whose continuation starts at `position` itself.
     */
    readonly position: number;
    /**
     * The steps that run on resume, flattened in execution order.
     *
     * For a defer on the main flow this is simply the steps after it. For a
     * defer inside a `.choice()` branch it is the rest of that branch
     * followed by the steps after the choice, which is the same sequence the
     * executor would have run had the exchange never deferred (a matched branch
     * rejoins the main flow).
     *
     * For a re-entrant site the continuation additionally INCLUDES the
     * deferring step itself at its head, because the step must re-run to
     * finish the work it deferred in the middle of. That head is therefore also
     * covered by the continuation hash: editing a defer-capable step's own
     * definition (an inline agent's options, say) invalidates its deferred
     * exchanges, which is correct because that definition is what resumes.
     */
    readonly continuation: ReadonlyArray<Step<Adapter>>;
    /**
     * Resume re-enters the deferring step itself rather than the step after
     * it. Set on sites assigned to defer-capable `.to()` / `.enrich()`
     * steps; absent on static `.defer()` sites.
     *
     * Two consequences at revival, both deliberate: the payload is NOT
     * validated against a live schema (the schema the step raised at defer
     * time lives in its own code and cannot be read back off the route, so
     * `RC5049` never fires for a re-entrant site and the step is the
     * validator), and the stored schema descriptor is compared against
     * itself, so a changed schema cannot be detected. Both are the same
     * residue class as "the hash covers step definitions, never the behaviour
     * of what the tail calls".
     */
    readonly reentrant?: boolean;
}
/**
 * Mark an adapter as able to raise a durable deferral from inside its own
 * execution (by throwing a `DeferSignal` from `fetch` / `send`). The
 * defer-site walk assigns `.to()` / `.enrich()` steps carrying a marked
 * adapter a re-entrant {@link DeferSite}.
 *
 * Core owns the brand; a consumer package (the agent tier is the shipped
 * case) marks its adapter with this helper and never mints its own symbol.
 */
declare function markDeferCapable(adapter: Adapter): void;
/**
 * A `.to()` / `.enrich()` step that can host a re-entrant defer site.
 * The walk stores its verdict on the hosting instance, because that
 * instance's `execute` is where the defer signal is converted (before any
 * step-scope wrapper can observe the throw and, say, retry the step).
 *
 * @internal
 */
interface DeferCapableStep extends Step<Adapter> {
    /** Assigned by {@link resolveDeferSites} when the step sits on the primary flow. */
    deferSite?: DeferSite;
    /**
     * Why no site was assigned, when the step sits somewhere a durable deferral
     * cannot be revived from (inside a `.split()` fan-out, or a
     * `.multicast()` path / `.dispatch()` target). Deferability of a
     * capable step is dynamic, so the refusal cannot fail the build the way a
     * static `.defer()` does; it fails the first actual deferral instead,
     * with this message, as `RC5051`.
     */
    deferRefusal?: string;
    /** Identity through wrappers: the instance the walk stores the site on. */
    [DEFER_HOST](): DeferCapableStep | undefined;
}
/**
 * What a `defer` outcome hands the executor.
 *
 * The step resolves the pieces (its schema, its expiry, its site) and the
 * executor owns the effects (serialize, hash, store, emit), which keeps
 * every scheduling decision in one place, as with every other outcome kind.
 *
 * It lives here rather than beside the operation because `types.ts` names
 * it on the `StepOutcome` union, and `types.ts` is the dependency root: it
 * does not import from `operations/`.
 *
 * @internal
 */
interface DeferRequest {
    /**
     * Live schema the eventual resume payload is validated against, when the site
     * declared one. Absent defers with no ingress validation, which is the
     * click-yes case: the route's own continuation is then the only reader of
     * whatever arrives.
     */
    readonly schema?: StandardSchemaV1;
    /** Resolved TTL in milliseconds, when one was declared. */
    readonly expiresInMs?: number;
    /**
     * Whatever the deferring step attached at deferral. Persisted verbatim and
     * handed to the resume route's `authorize` hook; never interpreted here.
     */
    readonly meta?: unknown;
    /**
     * Identity of the call this deferral belongs to, when the deferring step
     * mints one credential per call. Persisted as the record's `callBinding`
     * and carried as the token's `sub` claim.
     */
    readonly callBinding?: string;
    /** Where this defer sits, and what runs on resume. */
    readonly site: DeferSite;
    /**
     * Closure state owned by the deferring step, persisted in the record's
     * `stepState` slot and handed back to a re-entrant step at revival. The
     * store never interprets it; the plain-JSON rule (`RC5042`) applies.
     */
    readonly stepState?: unknown;
}
/**
 * A step that can defer the exchange. Implemented by the `.defer()` step;
 * declared here so the walk can recognise one without importing the
 * operation (which imports this module back).
 *
 * @internal
 */
interface DeferrableStep extends Step<Adapter> {
    readonly operation: OperationType.DEFER;
    /**
     * The live resume-payload schema, when the site declared one. Read back
     * off the step at resume time to validate the submitted payload, because a
     * Standard Schema cannot be persisted with the record.
     */
    readonly schema?: StandardSchemaV1;
    /** Assigned by {@link resolveDeferSites}. Absent means the step is not reachable from a built route. */
    site?: DeferSite;
}
/**
 * One nested sub-pipeline of a step, as reported through
 * {@link NESTED_STEPS}.
 *
 * `rejoins` is the load-bearing field. A `.choice()` branch flows back into
 * the main pipeline when it matches, so a defer inside one has a
 * well-defined continuation that spans the branch tail and the main tail. A
 * `.multicast()` path or a `.dispatch()` target runs as an isolated nested
 * pipeline whose exchange is not the route's primary flow, so there is no
 * such continuation and a defer inside one is refused.
 */
interface NestedSteps {
    readonly steps: ReadonlyArray<Step<Adapter>>;
    readonly rejoins: boolean;
    /**
     * The predicate that selects this sub-pipeline, when one does (a
     * `.choice()` branch). It decides which branch shapes the body, so a
     * fingerprint of the pipeline has to see it.
     */
    readonly predicate?: (exchange: Exchange) => boolean;
}
/**
 * Whether a built route can raise a durable deferral: statically (a
 * declared `.defer()`) or at runtime (a defer-capable step that MAY
 * defer). The predicate transports key on to advertise a `Deferred`
 * acknowledgment arm, owned here next to the fields it reads so a new way
 * for a route to defer updates every consumer in one edit.
 */
declare function routeCanDefer(definition: RouteDefinition): boolean;

/**
 * Abstract base for "dual-mode wrapper" operations: a single concept
 * (`.error()`, `.retry()`, `.timeout()`, `.cache()`, ...) that
 * applies at either route scope (when staged before `.from()`) or step
 * scope (when chained after `.from()`). The route-scope path is wired
 * by the builder via existing fields on `RouteDefinition`. The
 * step-scope path is wired by wrapping the *immediately next* step in a
 * concrete `WrapperStep` subclass.
 *
 * Subclasses implement {@link WrapperStep.runInner}: run the inner step
 * and return its {@link StepOutcome} (usually unchanged), substitute a
 * recovery outcome on failure, or rethrow (signals an unrecoverable
 * error for the pipeline executor to handle).
 *
 * The template `execute()` handles the boilerplate: emitting the
 * inner step's `route:step:started` / `route:step:completed` events with the inner
 * label (so the wrapper is observationally invisible) around the
 * subclass's `runInner`, and passing the inner's outcome through to the
 * executor, which owns all scheduling.
 *
 * The `WrapperStep` class is exposed for forward-compat as wrapper
 * authors land additional operations (retry, cache, timeout, circuit
 * breaker, etc.).
 */
declare abstract class WrapperStep<T extends Adapter = Adapter> implements Step<T> {
    protected readonly inner: Step<T>;
    /**
     * Operation kind delegated from the inner step so observers see the
     * wrapped operation's identity, not a generic "wrapper".
     */
    readonly operation: Step<T>["operation"];
    /** Adapter delegated from the inner step. */
    readonly adapter: T;
    /** Display label delegated from the inner step. */
    readonly label?: string;
    /**
     * The wrapper emits its own `route:step:started` / `route:step:completed` events
     * with the inner step's label, so the executor must not emit a generic
     * pair around the wrapper.
     */
    readonly skipStepEvents = true;
    /**
     * Forward the inner step's sub-pipelines so a wrapper is transparent to
     * framework-level walks of the route's step tree.
     *
     * Without this a wrapped nesting step hides everything inside it: a
     * `.error(h).choice(when(p, (b) => b.defer(...)))` route resolved zero
     * defer sites, which silently disabled the build-time refusals AND the
     * startup check, and then failed at runtime, after the approver had
     * already been notified, with a diagnostic telling the user to build the
     * route through `craft()` (which they had).
     *
     * @internal
     */
    [NESTED_STEPS](): ReadonlyArray<NestedSteps>;
    /**
     * Forward the defer-host protocol to the inner step, for the same
     * reason nested steps are forwarded: the defer-site walk sees the
     * wrapper (which delegates the inner adapter, so the capability brand is
     * visible), but the site must land on the instance whose `execute`
     * converts the defer signal, which is the innermost `.to()` /
     * `.enrich()` step.
     *
     * @internal
     */
    [DEFER_HOST](): DeferCapableStep | undefined;
    constructor(inner: Step<T>);
    /**
     * The step this wrapper folds around, for build-time walks that must see
     * through a stack of wrappers (e.g. assigning a step-scope cache its site).
     *
     * @internal
     */
    get wrapped(): Step<T>;
    /**
     * The options this wrapper was built with, as reported by
     * {@link describeOptions}, for build-time walks that fingerprint a
     * wrapper stack.
     *
     * @internal
     */
    get fingerprintOptions(): unknown;
    /**
     * Report the options that define this wrapper, so a `.cache()` whose
     * cached computation includes it (a step-scope cache stacked above it,
     * or a route-scope cache over the pipeline) can fold them into its
     * default key.
     * Without them, editing a wrapper between a cache and its step (an
     * `.error()` handler's recovery value, a `.retry()` predicate deciding
     * which failures are recovered) would leave the key unchanged and an
     * external provider would keep replaying what the old wrapper produced.
     *
     * Return the configuration, not runtime state: callables as themselves
     * (their source text is hashed), plain data as plain data, and never a
     * controller, bucket or other live object (those hash as `[opaque]` and
     * add nothing). Return `null` when the wrapper takes no options. The
     * value goes through the same projection as an adapter's options in
     * `deferral/hash.ts`, so the same carriers and depth bound apply.
     *
     * Abstract so a new wrapper cannot silently opt out of the cache key.
     */
    protected abstract describeOptions(): unknown;
    /**
     * Run the inner step with whatever extra behaviour the subclass adds
     * and return the outcome the pipeline should act on. Return the
     * inner's outcome unchanged when it succeeded; return a substitute
     * outcome (e.g. `continue` with a recovered exchange) when the
     * wrapper handled a failure. Throw to signal the wrapper could not
     * recover; the executor will then fall through to the route-level
     * error handler (or fail the exchange when none is set).
     *
     * There is no scheduling to intercept: the inner step never sees the
     * work queue, so a failed inner step has, by construction, scheduled
     * nothing. The pre-outcome engine required subclasses to capture and
     * replay inner queue pushes (and clear them on recovery); that whole
     * protocol is gone.
     *
     * @param exchange Live exchange to feed to the inner step.
     * @param ctx Executor capability passthrough for the inner step.
     * @returns Outcome the executor schedules.
     */
    protected abstract runInner(exchange: Exchange, ctx: StepContext): Promise<StepOutcome>;
    /**
     * Template method called by the pipeline executor. Emits the inner
     * step's lifecycle events with the inner label, delegates to
     * {@link runInner}, and returns the outcome for the executor to
     * schedule. Wrapper-specific failure events are emitted by the
     * subclass before it rethrows.
     */
    execute(exchange: Exchange, ctx: StepContext): Promise<StepOutcome>;
}

/**
 * Options for the `.retry()` wrapper (step scope and route scope).
 */
interface RetryOptions {
    /**
     * Maximum total attempts, including the first one. `3` means the
     * original execution plus up to two re-attempts. Must be at least 1.
     * Default: `3`.
     */
    maxAttempts?: number;
    /**
     * Base wait between attempts. Default: `1000`.
     */
    backoff?: Duration;
    /**
     * Growth multiplier applied to `backoff` each attempt: the wait
     * before attempt `n` is `backoff * factor^(n - 1)`. `1` (the default)
     * is fixed backoff; `2` doubles each time (`100, 200, 400, ...`); any
     * value `>= 1` is allowed for gentler or steeper curves. Replaces the
     * old `exponential` boolean (`exponential: true` is now `factor: 2`).
     */
    factor?: number;
    /**
     * Upper bound (ms) on a single wait, so an exponential `factor` cannot
     * grow the backoff without limit at higher `maxAttempts`. The computed
     * wait is clamped to this BEFORE jitter is applied. Default: the
     * platform timer ceiling (`2_147_483_647`), i.e. effectively unbounded.
     */
    maxBackoff?: Duration;
    /**
     * Randomise each wait to avoid synchronized retry storms across many
     * exchanges hitting the same downstream:
     * - `"none"` (default): use the computed wait exactly.
     * - `"full"`: pick uniformly in `[0, computed]` (AWS "full jitter").
     * - a number in `[0, 1]`: subtract up to that fraction, i.e. pick in
     *   `[computed * (1 - jitter), computed]` (`0.2` keeps 80-100% of the
     *   wait). `"full"` is `1`; `"none"` is `0`.
     *
     * Jitter only ever reduces a wait, so it never exceeds `maxBackoff`.
     */
    jitter?: "none" | "full" | number;
    /**
     * Decide whether a failed attempt is re-attempted. Default: skip
     * `RoutecraftError`s with `retryable: false` (validation, auth,
     * config errors fail the same way every time); everything else,
     * including unknown third-party errors, is retried.
     */
    retryOn?: (error: Error) => boolean;
}
/**
 * {@link RetryOptions} with every field populated. This is the shape
 * stored on `RouteDefinition.retry` for route-scope `.retry()` (and is
 * therefore part of the public definition surface); internally it is
 * shared between the step-scope wrapper and the route-scope segment
 * step in the pipeline executor.
 */
interface ResolvedRetryOptions {
    maxAttempts: number;
    backoffMs: number;
    /** Growth multiplier per attempt; `1` is fixed backoff. */
    factor: number;
    /** Hard cap on a single computed wait (before jitter). */
    maxBackoffMs: number;
    /** Jitter fraction in `[0, 1]`: `0` none, `1` full. */
    jitter: number;
    retryOn: (error: Error) => boolean;
}
/**
 * Step-scope `.retry()` wrapper. Re-attempts the wrapped step on
 * failure with configurable backoff. Each attempt receives the same
 * (frozen) exchange, so a re-attempt always starts from the input that
 * failed, not from partial output.
 *
 * The attempt counter is loop-local state inside one execution; it is
 * NOT written to exchange headers (headers carry persistent exchange
 * state, see `.standards/exchange-state-model.md`). Observers track
 * attempts via the `route:retry:attempt` events instead.
 *
 * Emits the pre-declared scope-aware lifecycle events:
 * - `route:retry:started` when the guarded execution begins.
 * - `route:retry:attempt` before each backoff wait + re-attempt.
 * - `route:retry:stopped` on final success or failure.
 */
declare class RetryWrapperStep<T extends Adapter = Adapter> extends WrapperStep<T> {
    #private;
    constructor(inner: Step<T>, options?: RetryOptions);
    protected describeOptions(): unknown;
    protected runInner(exchange: Exchange, ctx: StepContext): Promise<StepOutcome>;
}

/**
 * Route-scope `.timeout()` config. This is the shape stored on
 * `RouteDefinition.timeout` (and is therefore part of the public
 * definition surface); the builder stages it pre-`.from()` and the
 * pipeline executor's timeout segment consumes it.
 */
interface ResolvedTimeoutOptions {
    /** Deadline in milliseconds for each run of the bounded segment. */
    timeoutMs: number;
}
/**
 * Step-scope `.timeout()` wrapper. Bounds the wrapped step with a
 * deadline: when the step settles in time its outcome passes through
 * unchanged; when the deadline fires first the wrapper throws `RC5011`
 * (Request timeout, `retryable: true`) so an outer `.retry()` wrapper
 * re-attempts it by default and `.error()` handlers can branch on the
 * code.
 *
 * The wrapped step's promise is not cancelled on expiry (promises
 * cannot be cancelled): its eventual settlement is discarded. What the
 * step DOES get is an `AbortSignal` on its `StepContext` that fires
 * when the deadline expires, with the `RC5011` error as the abort
 * reason. A step that forwards `ctx.signal` into cancellation-aware IO
 * (`fetch`, DB drivers) therefore aborts its abandoned work instead of
 * running it to completion in the background. The signal is linked to
 * any enclosing signal (a route-scope timeout's abandon signal, an
 * outer step-scope timeout), so whichever deadline fires first aborts
 * the innermost work.
 *
 * Emits scope-aware lifecycle events:
 * - `route:timeout:started` when the guarded execution begins.
 * - `route:timeout:stopped` when the step settles within the deadline.
 * - `route:timeout:expired` when the deadline fires (then throws).
 */
declare class TimeoutWrapperStep<T extends Adapter = Adapter> extends WrapperStep<T> {
    #private;
    constructor(inner: Step<T>, duration: Duration);
    protected describeOptions(): unknown;
    protected runInner(exchange: Exchange, ctx: StepContext): Promise<StepOutcome>;
}

/**
 * Base for a stateful operation that holds one piece of state PER ROUTE.
 *
 * A single step (or controller) instance is built once per `RouteDefinition`,
 * but that definition can be registered into multiple contexts, producing
 * several live `Route` instances. Keying the state by `Route` in a WeakMap
 * gives each Route its OWN state, so the contexts cannot cross-contaminate
 * each other (cross-sample, cross-suppress, cross-trip, cross-rate-limit).
 * A single `#routeless` fallback covers the route-less case (a step run in
 * isolation, e.g. a unit test) so behaviour stays bounded there too.
 *
 * Subclasses provide {@link createState}; the per-route lookup and lazy
 * creation live here once rather than being re-implemented per operation.
 *
 * @internal
 */
declare abstract class RouteScopedController<S> {
    #private;
    /**
     * Build a fresh state instance. Called at most once per Route (and once
     * for the route-less fallback), on first use.
     */
    protected abstract createState(): S;
    /**
     * Resolve the state for `route`, creating it on first use; or the shared
     * route-less instance when no Route is attached.
     */
    stateFor(route: Route | undefined): S;
}

/**
 * The three states of a circuit breaker.
 *
 * - `closed`: calls flow through; failures within the sliding window are
 *   counted, and the breaker trips to `open` once they reach the
 *   threshold.
 * - `open`: calls fast-fail (fallback or `RC5025`) without running the
 *   protected work, until `cooldown` has elapsed.
 * - `half-open`: a bounded number of probe calls are allowed through to
 *   test whether the downstream has recovered; one success closes the
 *   breaker, one failure re-opens it.
 */
type CircuitBreakerState = "closed" | "open" | "half-open";
/**
 * Options for the `.circuitBreaker()` operation (step scope and route
 * scope). A breaker tracks failures over a sliding window and short-circuits
 * execution when the target is known to be failing, so a flaky downstream
 * does not turn into a pile of slow, doomed calls.
 */
interface CircuitBreakerOptions {
    /**
     * Number of failures within `window` that trips the breaker from
     * `closed` to `open`. Must be a finite integer >= 1.
     */
    failureThreshold: number;
    /**
     * Sliding window over which failures are counted. Failures older than
     * this no longer count toward the threshold. Default `60_000`.
     */
    window?: Duration;
    /**
     * How long the breaker stays `open` before allowing a probe
     * (transition to `half-open`). Default `30_000`.
     */
    cooldown?: Duration;
    /**
     * Maximum concurrent probe calls allowed in the `half-open` state.
     * Default `1`. Values above 1 are best-effort: the first probe to
     * succeed closes the breaker, so concurrent probes resolving after it
     * are accounted against the now-closed breaker.
     */
    halfOpenMax?: number;
    /**
     * Produce the value to use when the breaker rejects a call (open, or
     * half-open at capacity). When set, the rejected exchange's body becomes
     * the result of `fallback` and the pipeline continues; when omitted, the
     * breaker throws `RC5025` so a `.error()` handler (or the default error
     * path) can react.
     *
     * The second argument is `forward`, the same direct-route caller the
     * `.error()` handler receives: `forward(endpoint, payload)` sends to a
     * direct route and resolves with that route's result, so a fallback can
     * be dynamic (serve from a cache route, a secondary provider, etc.)
     * rather than a static value. May be async.
     *
     * @example Static fallback
     * ```ts
     * .circuitBreaker({ failureThreshold: 5, fallback: () => ({ degraded: true }) })
     * ```
     * @example Dynamic fallback via a direct route
     * ```ts
     * .circuitBreaker({
     *   failureThreshold: 5,
     *   fallback: (exchange, forward) => forward("recs-fallback", exchange.body),
     * })
     * ```
     */
    fallback?: (exchange: Exchange, forward: ForwardFn) => unknown | Promise<unknown>;
    /**
     * Decide whether a failed call counts toward the failure threshold.
     * Default: count everything except `RoutecraftError`s flagged
     * `retryable: false` (auth `RC5012`, validation `RC5002`, etc.), which
     * are deterministic and not evidence the downstream is unhealthy. This
     * mirrors `.retry()`'s `retryOn` default.
     */
    isFailure?: (error: Error) => boolean;
    /**
     * Optional label carried on this breaker's `route:circuitBreaker:*`
     * events, so stacked or sibling breakers can be told apart in logs and
     * metrics. Has no effect on behaviour. Observe transitions by
     * subscribing to those events (`route:circuitBreaker:opened` /
     * `:halfOpen` / `:closed` / `:rejected`); the breaker exposes no
     * notification callback, consistent with the other operations.
     */
    label?: string;
}
/**
 * {@link CircuitBreakerOptions} with every behavioural field populated.
 * This is the shape stored behind {@link CircuitBreakerController} and is
 * shared by the step-scope wrapper and the route-scope segment.
 *
 * @internal
 */
interface ResolvedCircuitBreakerOptions {
    failureThreshold: number;
    windowMs: number;
    cooldownMs: number;
    halfOpenMax: number;
    fallback?: (exchange: Exchange, forward: ForwardFn) => unknown | Promise<unknown>;
    isFailure: (error: Error) => boolean;
    label?: string;
}
/**
 * Decision returned by {@link CircuitBreakerMachine.acquire}. `probe` is
 * true when the admitted call is a half-open probe, so the matching
 * record call knows to release the probe slot and apply half-open
 * transition semantics.
 *
 * @internal
 */
type CircuitBreakerDecision = {
    admitted: true;
    probe: boolean;
} | {
    admitted: false;
    state: "open" | "half-open";
    retryAfterMs: number;
};
/**
 * Lifecycle hooks the breaker reports transitions to, so the step-scope
 * wrapper and the route-scope segment emit the same
 * `route:circuitBreaker:*` events with their own `scope` / `stepLabel`
 * bindings.
 *
 * @internal
 */
interface CircuitBreakerHooks {
    /** Closed/half-open -> open (the breaker tripped). */
    onOpened(failureCount: number): void;
    /** Open -> half-open (cooldown elapsed; a probe is being admitted). */
    onHalfOpen(): void;
    /** Half-open -> closed (a probe succeeded; the breaker recovered). */
    onClosed(): void;
    /** A call was rejected because the breaker is open or half-open at capacity. */
    onRejected(state: "open" | "half-open", retryAfterMs: number): void;
}
/**
 * The per-route state machine. Holds the sliding window of failure
 * timestamps (a ring buffer, pruned on access, not a flat counter so the
 * window genuinely slides), the current state, the open timestamp, and
 * the in-flight half-open probe count. One instance per Route (see
 * {@link CircuitBreakerController}), never one per exchange.
 *
 * @internal
 */
declare class CircuitBreakerMachine {
    #private;
    constructor(options: ResolvedCircuitBreakerOptions);
    /** Current breaker state (exposed for diagnostics and tests). */
    get state(): CircuitBreakerState;
    /**
     * Decide whether the calling exchange may proceed. May transition
     * open -> half-open when the cooldown has elapsed. Emits `halfOpen` /
     * `rejected` via `hooks`.
     */
    acquire(now: number, hooks: CircuitBreakerHooks): CircuitBreakerDecision;
    /** Record a successful call. A successful probe closes the breaker. */
    recordSuccess(probe: boolean, hooks: CircuitBreakerHooks): void;
    /**
     * Record a failed call. `counts` is false for deterministic errors that
     * should not trip the breaker (the probe slot is still released so it
     * does not leak, but no state transition is applied).
     */
    recordFailure(now: number, probe: boolean, counts: boolean, hooks: CircuitBreakerHooks): void;
}
/**
 * Owns the circuit-breaker state for one `.circuitBreaker()` across every
 * Route the enclosing step (or segment) runs in. Keyed by Route in a
 * WeakMap, so a single definition registered into multiple contexts gives
 * each Route its OWN breaker rather than one shared circuit (which would
 * let the contexts trip each other). Mirrors {@link ThrottleController}.
 *
 * @internal
 */
declare class CircuitBreakerController extends RouteScopedController<CircuitBreakerMachine> {
    #private;
    constructor(options: ResolvedCircuitBreakerOptions);
    /** The resolved options (fallback, threshold, cooldown, label, ...). */
    get options(): ResolvedCircuitBreakerOptions;
    /** Optional gate label, surfaced on the `route:circuitBreaker:*` events. */
    get label(): string | undefined;
    protected createState(): CircuitBreakerMachine;
    acquire(route: Route | undefined, hooks: CircuitBreakerHooks): CircuitBreakerDecision;
    recordSuccess(route: Route | undefined, probe: boolean, hooks: CircuitBreakerHooks): void;
    recordFailure(route: Route | undefined, error: Error, probe: boolean, hooks: CircuitBreakerHooks): void;
}
/**
 * Step-scope `.circuitBreaker()` wrapper. Protects the immediately-next
 * step: counts its failures over a sliding window, trips after the
 * threshold, then fast-fails subsequent calls (fallback or `RC5025`)
 * until the cooldown elapses and a probe is allowed through. The breaker
 * state lives on a {@link CircuitBreakerController} keyed by Route, so
 * every exchange on a given Route shares one breaker while distinct
 * Routes (even from the same definition) stay isolated. This is the
 * deliberate per-ROUTE shared-state exception to the `WrapperStep` rule
 * (see `.standards/resilience-wrappers.md` section 8).
 *
 * Emits the `route:circuitBreaker:opened` / `:halfOpen` / `:closed` /
 * `:rejected` family with `scope: "step"`.
 */
declare class CircuitBreakerWrapperStep<T extends Adapter = Adapter> extends WrapperStep<T> {
    #private;
    constructor(inner: Step<T>, options: CircuitBreakerOptions);
    protected describeOptions(): unknown;
    protected runInner(exchange: Exchange, ctx: StepContext): Promise<StepOutcome>;
}

/**
 * A counting semaphore: bounds how many holders may run at once, queueing
 * the rest FIFO. The shared concurrency primitive behind `.concurrency()`
 * (the bulkhead wrapper) and, in future, bounded `.split()` fan-out.
 *
 * Synchronous-first, like {@link TokenBucket}: under the single-threaded
 * event loop a batch of concurrent exchanges each take a distinct slot (or
 * a distinct queue position) in the same tick, so admission order is
 * deterministic FIFO and the cap is never exceeded.
 *
 * State is in-memory and lives PER ROUTE (one `Semaphore` per Route, held
 * by a controller's WeakMap), never per exchange. A handed-out release
 * function is idempotent: calling it twice frees exactly one slot.
 *
 * @internal
 */
declare class Semaphore {
    #private;
    constructor(max: number);
    /** Configured maximum simultaneous holders. */
    get max(): number;
    /** Slots currently held (admitted but not yet released). */
    get inUse(): number;
    /** Exchanges currently queued, waiting for a slot to free. */
    get waiting(): number;
    /**
     * Take a slot only if one is free right now. Returns a release function
     * on success, or `undefined` when all slots are in use (the caller fails
     * fast rather than waiting). Used by reject mode.
     */
    tryAcquire(): (() => void) | undefined;
    /**
     * Acquire a slot, waiting FIFO until one frees when all are in use.
     * Resolves with a release function. Rejects with {@link SleepAbortedError}
     * the moment `signal` aborts (route shutdown), so a stopping route does
     * not strand an exchange in the wait queue. Used by queue mode.
     */
    acquire(signal?: AbortSignal): Promise<() => void>;
}

/**
 * Options for the `.concurrency()` wrapper (step scope and route scope).
 *
 * A bulkhead: it bounds how many exchanges run the wrapped work AT ONCE,
 * as opposed to `.throttle()`, which bounds how many run PER TIME WINDOW.
 * The two compose but are not substitutes: a 10/sec throttle still allows
 * unbounded simultaneous in-flight exchanges if each is slow; a
 * concurrency of 5 caps simultaneity regardless of rate (protect a
 * connection pool, a memory-bound step, or a downstream with a hard
 * concurrency cap).
 */
interface ConcurrencyOptions {
    /** Maximum simultaneous in-flight exchanges. Must be a finite integer >= 1. */
    max: number;
    /**
     * Behaviour when all slots are busy:
     * - `"queue"` (default): the exchange waits FIFO for a slot, applying
     *   backpressure rather than dropping it. The wait is cancellable, so on
     *   route shutdown a waiting exchange is admitted rather than stranded.
     * - `"reject"`: fail fast with `RC5026` (no slot, no wait) so the caller
     *   sheds load instead of building an unbounded in-memory backlog.
     */
    mode?: "queue" | "reject";
    /**
     * Queue mode only: cap the wait line. When `max` slots are busy AND
     * `maxQueue` exchanges are already waiting, the next one fails fast with
     * `RC5026` instead of joining the queue. The middle ground between "wait
     * forever" (omit it) and "reject as soon as busy" (`mode: "reject"`).
     * Must be a finite integer >= 1; passing it in `reject` mode is rejected
     * at build time (use `mode: "reject"`, which is `maxQueue: 0`). Default:
     * unbounded.
     */
    maxQueue?: number;
    /**
     * Partition the limit: each distinct key gets its own independent slot
     * pool, so you can cap concurrency per user / tenant / connection pool.
     * Omit for a single pool shared across the whole route. The selector runs
     * once per exchange and MUST return a string; coalesce missing values
     * (e.g. `?? "anonymous"`). A selector that throws fails the exchange.
     *
     * @example Per authenticated principal
     * ```ts
     * .concurrency({ max: 3, key: (ex) => ex.principal?.subject ?? "anonymous" })
     * ```
     */
    key?: (exchange: Exchange) => string;
    /**
     * Maximum number of distinct keys to track concurrently when `key` is
     * set. Per-key semaphores live in an LRU, so memory stays bounded even
     * with an unbounded key space. Default `10_000`. Ignored when `key` is
     * not set.
     */
    maxKeys?: number;
    /**
     * Optional label carried on this bulkhead's `route:concurrency:*` events,
     * so stacked or sibling limiters can be told apart in logs and metrics.
     * Has no effect on behaviour.
     */
    label?: string;
}
/**
 * {@link ConcurrencyOptions} with every behavioural field populated. Shared
 * by the step-scope wrapper and the route-scope segment.
 *
 * @internal
 */
interface ResolvedConcurrencyOptions {
    max: number;
    mode: "queue" | "reject";
    /** Wait-queue bound; `Number.POSITIVE_INFINITY` when unbounded. */
    maxQueue: number;
    key?: (exchange: Exchange) => string;
    maxKeys: number;
    label?: string;
}
/**
 * Per-route bulkhead state for one `.concurrency()`. Holds a single shared
 * {@link Semaphore} when unkeyed, or an LRU of per-key semaphores when a
 * `key` selector is configured. One instance per Route (see
 * {@link ConcurrencyController}), never one per exchange.
 *
 * @internal
 */
declare class ConcurrencyLimiter {
    #private;
    constructor(options: ResolvedConcurrencyOptions);
    /**
     * Resolve the {@link Semaphore} for `exchange` (the shared one, or the
     * per-key one, creating it on first use), plus the partition key it
     * belongs to (absent when unkeyed).
     */
    semaphoreFor(exchange: Exchange): {
        semaphore: Semaphore;
        key?: string;
    };
}
/**
 * Lifecycle hooks the bulkhead reports to, so the step-scope wrapper and
 * the route-scope segment emit the same `route:concurrency:*` events with
 * their own `scope` / `stepLabel` bindings.
 *
 * @internal
 */
interface ConcurrencyHooks {
    /** Route abort signal; cancels the queue wait on shutdown. */
    signal?: AbortSignal;
    /** All slots were busy; the exchange joins the wait queue at `queueDepth`. */
    onQueued(queueDepth: number, key?: string): void;
    /**
     * A slot was acquired. `waited` is true when the exchange had to queue
     * first; `inUse` is the slot count after admission.
     */
    onAcquired(waited: boolean, inUse: number, key?: string): void;
    /** The held slot was released; `heldMs` is how long the work held it. */
    onReleased(heldMs: number, key?: string): void;
    /**
     * The exchange was failed fast (`RC5026`): `reason` is `"busy"` (reject
     * mode, all slots busy) or `"queue-full"` (queue mode, wait line at
     * `maxQueue`).
     */
    onRejected(reason: "busy" | "queue-full", key?: string): void;
}
/**
 * Owns the bulkhead state for one `.concurrency()` across every Route the
 * enclosing step (or segment) runs in. Keyed by Route in a WeakMap, so a
 * single definition registered into multiple contexts gives each Route its
 * OWN slot pool rather than one shared bulkhead (which would let the
 * contexts steal each other's slots). Mirrors {@link ThrottleController}.
 *
 * @internal
 */
declare class ConcurrencyController extends RouteScopedController<ConcurrencyLimiter> {
    #private;
    constructor(options: ResolvedConcurrencyOptions);
    /** Optional limiter label, surfaced on the `route:concurrency:*` events. */
    get label(): string | undefined;
    protected createState(): ConcurrencyLimiter;
    /**
     * Acquire a slot for `exchange`. In `queue` mode (default) the caller
     * waits FIFO when the pool is full (bounded by `maxQueue`); the wait is
     * cancellable, so on route shutdown the exchange is admitted rather than
     * stranded. In `reject` mode a busy pool fails fast with `RC5026` without
     * waiting. Returns the (idempotent) release function plus the partition
     * key it was charged against (absent when unkeyed).
     *
     * `opts.mustWait` overrides BOTH modes for a caller that cannot absorb a
     * refusal, and deliberately ignores `maxQueue` as well: rejecting is the
     * outcome the flag exists to prevent, so a bounded wait line would
     * reintroduce it under a different name. The limit itself still holds,
     * because the semaphore is the route's own and is shared with every other
     * caller. Read `maxQueue` as bounding the exchanges that CAN be shed.
     *
     * Two gaps that flag does not close, both worth knowing before sizing
     * `max`: the wait is unbounded in TIME as well as in depth, so a saturated
     * pool holds each waiter (and whatever answered it) until a slot frees or
     * the route stops; and a `key` selector that throws still raises `RC5003`
     * from below, because the partition has to be resolved before the mode is
     * consulted.
     */
    acquire(exchange: Exchange, route: Route | undefined, hooks: ConcurrencyHooks, opts?: {
        mustWait?: boolean;
    }): Promise<{
        release: () => void;
        key?: string;
    }>;
}
/**
 * Step-scope `.concurrency()` wrapper. Bounds the wrapped step to `max`
 * simultaneous in-flight exchanges, queueing (backpressure) or fast-failing
 * (`RC5026`) the rest per `mode`.
 *
 * The slot pool lives on a {@link ConcurrencyController} keyed by Route, so
 * every exchange on a given Route shares one bulkhead while distinct Routes
 * (even from the same definition) stay isolated. This is the deliberate
 * per-ROUTE shared-state exception to the `WrapperStep` rule (see
 * `.standards/resilience-wrappers.md` section 8).
 *
 * Emits the `route:concurrency:queued` / `:acquired` / `:released` /
 * `:rejected` family with `scope: "step"`.
 */
declare class ConcurrencyWrapperStep<T extends Adapter = Adapter> extends WrapperStep<T> {
    #private;
    constructor(inner: Step<T>, options: ConcurrencyOptions);
    protected describeOptions(): unknown;
    protected runInner(exchange: Exchange, ctx: StepContext): Promise<StepOutcome>;
}

/**
 * How a source adapter handles a parse failure on an individual item.
 *
 * Source adapters that translate raw bytes into a structured body (json,
 * html, csv, jsonl, mail) accept this option to control what happens when
 * the parse step throws.
 *
 * All three modes are observable via the events bus, mirroring the
 * filter / validate operation patterns:
 *
 * | Mode    | Lifecycle events fired                       |
 * |---------|----------------------------------------------|
 * | `fail`  | `route:exchange:started` -> `route:exchange:failed` (or `route:error:caught` if `.error()` recovers) |
 * | `abort` | `route:exchange:started` -> `route:exchange:failed`, then `context:error` and the source dies |
 * | `drop`  | `route:exchange:started` -> `route:exchange:dropped` (`reason: "parse-failed"`) |
 *
 * adopt the contract.
 */
type OnParseError = 
/**
 * Default. The exchange fails: the route's `.error()` handler is invoked
 * with an `RC5016` error, or `route:exchange:failed` is emitted when no handler
 * is set. Streaming adapters continue to the next item.
 *
 * Use when you want parse failures to be observable per item and the rest
 * of the source to keep flowing.
 */
"fail"
/**
 * The source aborts on the first parse failure. The bad item still emits
 * `route:exchange:started` -> `route:exchange:failed` for per-item observability;
 * then the source's subscribe promise rejects and `context:error` fires.
 *
 * Use when partial-data is unacceptable and a malformed item should stop
 * the import (atomic-load semantics).
 */
 | "abort"
/**
 * The parse failure is dropped from the pipeline. The synthetic parse
 * step emits `route:exchange:started` -> `route:exchange:dropped` with
 * `reason: "parse-failed"` (matching `filter` / `validate` drop
 * semantics). Streaming adapters continue to the next item; no
 * `route:exchange:failed` and no `.error()` handler invocation.
 *
 * Use when malformed items are expected (scraping, lossy upstreams) and
 * you want them counted in `route:exchange:dropped` metrics rather than
 * surfaced as route errors.
 */
 | "drop";
/**
 * Default `OnParseError` value applied when a parsing adapter does not set
 * one explicitly.
 */
declare const DEFAULT_ON_PARSE_ERROR: OnParseError;

/**
 * Pluggable backend for the `.cache()` operation. Implementations decide
 * where cached values live (in-memory, Redis, file-backed, multi-tier,
 * etc.) and how eviction works. The contract is async-by-default so
 * remote backends fit without breaking the call signature.
 *
 * A reference implementation backed by `lru-cache` ships as
 * {@link MemoryCacheProvider}. Custom providers can be supplied
 * per-operation via `cache({ provider })`; a future change will allow a
 * global default to be set on `CraftConfig` (tracked in #112).
 *
 * Stampede protection (deduping concurrent computations for the same
 * key) is the provider's responsibility via {@link getOrCompute} so the
 * dedupe strategy can match the backend. In-memory providers track an
 * in-flight Promise per key; distributed providers like Redis can use a
 * lock key or rely on the underlying store's atomicity.
 */
interface CacheProvider {
    /**
     * Fetch a value by key. Returns `undefined` when there is no entry
     * for the key (cache miss) or when the entry has expired. Treat
     * `undefined` as "miss"; do not store `undefined` as a cached value.
     *
     * `null` is a valid cached value and is distinct from a miss: a
     * cached `null` returns `null`, not `undefined`.
     *
     * @param key The cache key.
     */
    get(key: string): Promise<unknown>;
    /**
     * Store a value under `key`. When `ttl` is provided, the entry
     * expires after `ttl` milliseconds; otherwise the provider's default
     * expiry applies (which may be "never").
     *
     * `undefined` is not a storable value (it is the miss sentinel);
     * implementations must reject it. `null` is storable.
     *
     * @param key The cache key.
     * @param value The value to cache. Must not be `undefined`.
     * @param ttl Optional time to live in milliseconds.
     */
    set(key: string, value: unknown, ttl?: number): Promise<void>;
    /** Remove an entry by key. No-op if the key is absent. */
    delete(key: string): Promise<void>;
    /** Check existence without producing a "hit" side effect. */
    has(key: string): Promise<boolean>;
    /**
     * Atomic "get-or-compute" with stampede protection. On a hit, returns
     * the cached value. On a miss, runs `loader()` exactly once across
     * concurrent callers with the same key and caches the result before
     * resolving. If `loader` throws, the error propagates and nothing is
     * cached.
     *
     * Wrappers and adapters should prefer this over manual
     * `get` / `set` round-trips so the dedupe strategy stays with the
     * provider.
     *
     * If `loader` resolves to `undefined`, treat it as a non-value:
     * return it to the caller but do NOT store it (consistent with `get`
     * returning `undefined` for a miss). Do not throw in this case, even
     * though `set` rejects `undefined`. `null` is a value and is cached.
     *
     * @param key The cache key.
     * @param loader Producer for the cached value on a miss.
     * @param ttl Optional time to live for the produced value.
     */
    getOrCompute<T>(key: string, loader: () => Promise<T>, ttl?: number): Promise<T>;
}
/**
 * Construction options for {@link MemoryCacheProvider}.
 */
interface MemoryCacheProviderOptions {
    /**
     * Maximum number of entries to keep. When the cache is full, the
     * least-recently-used entry is evicted to make room. Defaults to
     * 1000.
     */
    max?: number;
    /**
     * Default time to live in milliseconds, applied when a `set` call
     * omits `ttl`. Defaults to no expiry (entries live until evicted by
     * the LRU policy or explicitly deleted).
     */
    ttl?: number;
}
/**
 * Default in-process cache provider. Backed by `lru-cache` for
 * size-bounded LRU eviction with optional TTL, plus an in-flight
 * Promise map for stampede protection.
 *
 * Two instances are independent stores; the framework does not share
 * state across `MemoryCacheProvider` instances. The module-level
 * `defaultMemoryCacheProvider` is shared by every `.cache()` call that
 * does not supply its own provider.
 *
 * Thread-safe within the JS event loop: `getOrCompute` reads, registers
 * an in-flight Promise, and resolves it atomically with respect to
 * other JS turns on the same key. Across workers / processes the cache
 * is local to the host.
 */
declare class MemoryCacheProvider implements CacheProvider {
    #private;
    constructor(options?: MemoryCacheProviderOptions);
    get(key: string): Promise<unknown>;
    set(key: string, value: unknown, ttl?: number): Promise<void>;
    delete(key: string): Promise<void>;
    has(key: string): Promise<boolean>;
    getOrCompute<T>(key: string, loader: () => Promise<T>, ttl?: number): Promise<T>;
    /**
     * Drop all entries. Mainly for tests and explicit invalidation.
     *
     * Not part of the {@link CacheProvider} interface: clearing semantics
     * vary by backend (a Redis `FLUSHDB` is destructive and shared), so
     * this helper is specific to the in-memory provider. Construct a fresh
     * provider for test isolation rather than relying on `clear()` against
     * an arbitrary `CacheProvider`.
     */
    clear(): void;
    /**
     * Number of live entries (excludes in-flight loaders).
     *
     * Not part of the {@link CacheProvider} interface; specific to the
     * in-memory provider and intended for tests and diagnostics.
     */
    get size(): number;
}

/**
 * Options for `.cache()`, at route scope (before `.from()`) and step scope
 * (after `.from()`).
 *
 * @template Current Body type entering the cached route or step.
 */
interface CacheOptions<Current = unknown> {
    /**
     * Derive the cache key from the exchange. The returned string is the
     * identity used by the provider's `get` / `set`.
     *
     * When omitted, the key is a SHA-256 over the route id (plus, at step
     * scope, the cache's site, and at route scope, a fingerprint of the
     * cached pipeline: see `CacheKeyScope`), the principal's
     * `issuer` and `subject` plus those of every `actor` hop when the
     * exchange carries one, and a SHA-256 of `JSON.stringify(body)`. Two routes, two cached steps, or two
     * callers therefore never share an entry by accident. The route id is
     * part of the key, so give the route an `.id()`: an unnamed route gets
     * a fresh id on every start, and its entries in an external provider
     * stop matching after a restart.
     *
     * The default needs a body. An exchange whose body is `undefined` (a
     * bodiless `http()` GET, whose input lives in the
     * `routecraft.http.params` / `routecraft.http.query` headers) fails
     * with `RC5029`, as does a body `JSON.stringify` cannot represent
     * (a top-level function or symbol, a circular reference, a `BigInt`).
     * Nested functions and symbols are silently dropped by `JSON.stringify`,
     * so bodies differing only there share a key. Supply `key` for those. A
     * `null` body is keyable.
     *
     * A custom `key` is used VERBATIM: nothing is added to it. Every route
     * and step on the same provider shares entries for equal keys, and so
     * does every caller, so put the route (`ex.headers[HeadersKeys.ROUTE_ID]`)
     * and the caller's identity (`ex.principal?.issuer` and `subject`) in
     * the key, and drop the principal only when every caller sees the same
     * answer. On a route that admits delegation, add the current actor
     * (`ex.principal?.actor?.issuer` and `subject`) as well, or two delegates
     * acting for the same subject share entries.
     *
     * Performance: the default hashes a JSON serialisation of the body on
     * every exchange. For hot paths or large bodies (file contents, large
     * payloads), supply a `key` that returns a stable identifier already
     * to hand (an id field, a content hash in a header, a tuple of the
     * relevant fields) to avoid re-serialising and re-hashing.
     */
    key?: (exchange: Exchange<Current>) => string;
    /**
     * Time to live. After expiry, the next execution with the same key
     * recomputes the value. When omitted, the provider's default applies
     * (the bundled in-memory provider keeps entries until LRU eviction).
     */
    ttl?: Duration;
    /**
     * Cache backend. Defaults to a process-wide in-memory provider. Pass
     * a custom provider (Redis, multi-tier, file-backed, etc.) by
     * constructing an implementation of {@link CacheProvider} and
     * handing it in here.
     */
    provider?: CacheProvider;
}
/**
 * Where a cache sits, which the default key namespaces its entries by.
 *
 * `site` is the JSON of `[index, stackIndex, below, fingerprint]`: the
 * step's pre-order index in the route's step tree, the cache's index in
 * that step's full wrapper stack, `[kind, optionsFingerprint]` for each
 * wrapper between the cache and the innermost step, and a fingerprint of
 * the innermost step's definition (operation, label, adapter id and
 * options, callable source). It derives from the route definition alone,
 * so every process running the same route source computes the same site
 * and shares entries in an external provider. Moving a step, reordering
 * its wrappers, or changing its definition or the options of a wrapper
 * below the cache (an `.error()` handler, a `.retry()` policy) changes the
 * site, so those edits cause misses rather than replays of entries the old
 * definition produced.
 *
 * Wrappers above the cache contribute their count (through `stackIndex`)
 * but not their options: they run outside the cached computation and none
 * rewrites the exchange it passes inward, so they cannot change what is
 * stored for a key. The fingerprints do not cover what a callable closes
 * over or config read at run time; put those in an explicit key when they
 * change the output.
 *
 * At route scope there is no site; `pipeline` is the
 * {@link pipelineFingerprint} of every step a hit skips, nested branches
 * and wrapper options included, so editing any of them misses rather than
 * replaying what the old pipeline produced. The route's `.input()` and
 * `.output()` schemas stay out: input validation runs before the cache
 * check (its result is the body the key hashes) and output validation runs
 * after the pipeline on a hit as on a miss, so neither shapes a stored
 * entry.
 *
 * @internal
 */
type CacheKeyScope = {
    readonly kind: "route";
    readonly routeId: string;
    readonly pipeline: string;
} | {
    readonly kind: "step";
    readonly routeId: string;
    readonly site: string;
};
/**
 * Internal resolved shape of {@link CacheOptions}: every field is
 * populated, with defaults filled in. Shared between the step-scope
 * wrapper and the route-scope filter steps.
 *
 * @internal
 */
interface ResolvedCacheOptions<Current = unknown> {
    key: (exchange: Exchange<Current>, scope: CacheKeyScope) => string;
    /** No custom `key` was supplied, so `key` is {@link defaultCacheKey}. */
    usesDefaultKey: boolean;
    ttl: number | undefined;
    provider: CacheProvider;
}
/**
 * Step-scope `.cache()` wrapper. On a cache hit, replaces
 * `exchange.body` with the cached value and skips the wrapped step. On
 * a miss, runs the wrapped step, caches its produced body, and lets
 * the pipeline continue normally. Errors from the wrapped step are
 * NOT cached and propagate to outer wrappers / route-level handlers; an
 * error reply the step returns without throwing is cached (see
 * `StepBuilderBase.cache`).
 *
 * The default key is namespaced by route id and by this wrapper's site
 * ({@link CacheKeyScope}), assigned by {@link assignCacheSites} when the
 * route is built. A wrapper
 * that never went through `RouteBuilder.build()` (constructed by hand)
 * gets a random site on first use, so it never shares entries with
 * another cache, at the cost of not sharing them across restarts either.
 *
 * Concurrent exchanges with the same derived key share a single
 * computation via the provider's `getOrCompute`, so a slow underlying
 * operation runs at most once per key per TTL window.
 *
 * Emits cache lifecycle events on the route's event bus:
 * - `route:cache:hit` when a cached value is reused.
 * - `route:cache:miss` when the wrapped step runs.
 * - `route:cache:stored` when a fresh value is written.
 * - `route:cache:failed` when key derivation or the provider throws.
 *
 * Known limitation: concurrent exchanges that share a single
 * `getOrCompute` computation (stampede dedupe) currently report
 * `route:cache:hit` for the waiters rather than a distinct "deduped" signal,
 * which can inflate hit-rate metrics. Tracked separately; needs a
 * provider-interface change to report whether the current call ran the
 * loader.
 *
 * Ordering note: a step-scope `.error()` placed INSIDE the cache
 * (`.cache().error(h).to(d)`) feeds the handler's recovery value into
 * the cache, so a fallback becomes the permanent cached answer for that
 * key. Put `.error()` OUTSIDE the cache (`.error(h).cache().to(d)`)
 * unless caching recovery results is intended.
 *
 * Route scope (`.cache()` before `.from()`) does not use this class; it
 * runs as the `cacheCheck` / `cacheStore` filter steps.
 */
declare class CacheWrapperStep<T extends Adapter = Adapter> extends WrapperStep<T> {
    #private;
    constructor(inner: Step<T>, options?: CacheOptions);
    protected describeOptions(): unknown;
    /**
     * Whether this cache derives its key with {@link defaultCacheKey}, which
     * depends on the route id.
     *
     * @internal
     */
    get usesDefaultKey(): boolean;
    /**
     * Record this wrapper's position in its route. Called by
     * {@link assignCacheSites}; see {@link CacheKeyScope}.
     *
     * @internal
     */
    assignSite(site: string): void;
    protected runInner(exchange: Exchange, ctx: StepContext): Promise<StepOutcome>;
}

/**
 * Time window a `.throttle()` rate is measured over.
 *
 * Longer quota windows (week / month) are intentionally absent: this is
 * an IN-MEMORY limiter, so its state resets on process restart and is
 * not shared across instances. That is fine for second-to-day smoothing
 * but unsafe for a durable "N per month" quota, which needs persistent,
 * shared storage (a separate feature).
 */
type ThrottleTimeUnit = "second" | "minute" | "hour" | "day";
/**
 * Options for the `.throttle()` wrapper (step scope and route scope).
 */
interface ThrottleOptions {
    /** Allowed requests per `per` window. Must be a finite number > 0. */
    rate: number;
    /**
     * Time window the `rate` is measured over. Default `"second"`.
     *
     * A unit word (`"minute"`) reads best for the common case; a
     * {@link Duration} covers windows a unit word cannot name, such as
     * `"90s"`. Note that a BARE NUMBER is milliseconds, as everywhere else a
     * `Duration` is accepted: `per: 60` is 60ms, not a minute. Write
     * `per: "60s"` (or `per: "minute"`) for that.
     */
    per?: ThrottleTimeUnit | Duration;
    /**
     * Behaviour when an exchange exceeds the rate:
     * - `"delay"` (default): pace it, waiting until a token frees. Smooths
     *   bursty traffic into a steady rate; never drops an exchange.
     * - `"reject"`: throw `RC5013` immediately so the caller fails fast
     *   (e.g. a source returns 429) instead of being buffered. Avoids the
     *   unbounded in-flight growth that delay can accumulate under a fast
     *   source. A rejected exchange does NOT consume a token.
     */
    mode?: "delay" | "reject";
    /**
     * Burst allowance: the most calls admitted back-to-back after an idle
     * window before pacing kicks in (the token bucket's capacity). Default
     * is `rate` (one window's worth). Set it lower for stricter pacing, or
     * higher to tolerate spikes. Decoupled from `per`, so `{ rate: 600,
     * per: "minute" }` does not silently allow a 600-wide burst unless you
     * ask for it.
     */
    burst?: number;
    /**
     * Partition the limit: each distinct key gets its own independent
     * bucket, so you can rate-limit per user, per IP, per tenant, etc.
     * Omit for a single bucket shared across the whole route (a global
     * limit). The selector runs once per exchange and MUST return a
     * string; coalesce missing values (e.g. `?? "anonymous"`). A selector
     * that throws fails the exchange (it is user code, like a transform),
     * so guard it rather than relying on the never-drops contract.
     *
     * @example Per authenticated principal
     * ```ts
     * .throttle({ rate: 10, key: (ex) => ex.principal?.subject ?? "anonymous" })
     * ```
     */
    key?: (exchange: Exchange) => string;
    /**
     * Maximum number of distinct keys to track concurrently when `key` is
     * set. The per-key buckets live in an LRU, so memory stays bounded
     * even with an unbounded key space (the least-recently-used key's
     * bucket is evicted and resets when it next appears). Default
     * `10_000`. Ignored when `key` is not set.
     */
    maxKeys?: number;
    /**
     * Optional label carried on this throttle's `route:throttle:*` events,
     * so stacked gates (e.g. a global limit plus a per-IP limit) can be
     * told apart in logs and metrics. Has no effect on behaviour.
     */
    label?: string;
}
/**
 * {@link ThrottleOptions} normalised to what the limiter needs. Staged
 * on the builder's pending options for route-scope `.throttle()`.
 *
 * @internal
 */
interface ResolvedThrottleOptions {
    /** Token bucket capacity (burst allowance). */
    capacity: number;
    /** Tokens replenished per millisecond (`rate / windowMs`). */
    refillPerMs: number;
    /** On-limit behaviour. */
    mode: "delay" | "reject";
    /** Per-exchange partition selector; absent means a single shared bucket. */
    key?: (exchange: Exchange) => string;
    /** LRU cap on distinct keys (only meaningful when `key` is set). */
    maxKeys: number;
    /** Optional label for `route:throttle:*` events. */
    label?: string;
}
/**
 * Step-scope `.throttle()` wrapper. Rate-limits the wrapped step to a
 * fixed number of calls per time window, pacing exchanges that exceed
 * the rate (backpressure) rather than dropping them.
 *
 * The limiter state lives on a {@link ThrottleController} held on the
 * wrapper instance. The builder constructs one wrapper instance per
 * route at build time, but the controller keys its buckets by Route, so
 * every exchange on a given Route shares one limiter while distinct
 * Routes (even built from the same definition) stay isolated. This is
 * the deliberate exception to the `WrapperStep` rule against storing
 * state on `this`: that rule bars PER-EXECUTION state; a rate limiter is
 * PER-ROUTE state and sharing it is the entire point. See
 * `.standards/resilience-wrappers.md` section 8.
 *
 * Emits scope-aware lifecycle events:
 * - `route:throttle:delayed` when an exchange must wait for a token.
 * - `route:throttle:passed` when an exchange is admitted (with `waited`).
 */
declare class ThrottleWrapperStep<T extends Adapter = Adapter> extends WrapperStep<T> {
    #private;
    constructor(inner: Step<T>, options: ThrottleOptions);
    protected describeOptions(): unknown;
    protected runInner(exchange: Exchange, ctx: StepContext): Promise<StepOutcome>;
}

/**
 * What a detached run reports back. `error` is present exactly when
 * `failed` is true and the failure reached the run's boundary, which is
 * what a resume needs to cache as the deferral's continuation result.
 *
 * @internal
 */
interface DetachedResult {
    failed: boolean;
    dropped: boolean;
    /**
     * The run deferred at a `.defer()`. Distinct from every other outcome:
     * the exchange is neither finished nor failed, and its terminal body is
     * the `Deferred` acknowledgment rather than the route's output. A caller
     * that treats it as a completion publishes both a false receipt and the
     * next deferral's resume token.
     */
    deferred: boolean;
    exchange: Exchange;
    error?: unknown;
}

/**
 * Function that forwards a payload to another route via the direct adapter and returns its result.
 *
 * @param endpoint - The target route's direct endpoint
 * @param payload - The data to send
 * @returns The result of the target route's pipeline
 */
type ForwardFn = (endpoint: RegisteredDirectEndpoint, payload: unknown) => Promise<unknown>;
/**
 * Error handler invoked when a step in the route pipeline throws an unhandled error.
 *
 * The pipeline does not resume after this handler runs. The handler's return value
 * becomes the route's final exchange body. Use `forward` to delegate to another route.
 *
 * Instead of a recovery body the handler may return a branded `Recovery`
 * directive built with the `recovery` helpers (see `recovery.ts`):
 * `recovery.drop(reason?)` discards the exchange (emits
 * `route:exchange:dropped`, no `route:exchange:completed`), and
 * `recovery.rethrow()` propagates the original error exactly as if the
 * handler had thrown it. Plain (unbranded) return values are unaffected.
 *
 * @param error - The thrown error
 * @param exchange - The exchange at the point of failure
 * @param forward - Sends a payload to another route via the direct adapter
 * @returns Static fallback value, result of forward(), or a `Recovery` directive
 */
type ErrorHandler = (error: unknown, exchange: Exchange, forward: ForwardFn) => unknown | Promise<unknown>;
/**
 * Per-direction schema bundle for discoverable-capability routes. Mirrors the
 * Standard Schema shape used by adapters; the engine enforces `input` before
 * pipeline steps run and `output` before the primary destination fires.
 */
interface RouteSchemas {
    /** Standard Schema for the body. */
    body?: StandardSchemaV1;
    /** Standard Schema for the headers. */
    headers?: StandardSchemaV1;
}
/**
 * Well-known tag values surfaced as autocomplete suggestions while still
 * accepting any user-defined string. Use these consistently to enable
 * downstream filtering (e.g. an agent that only whitelists `"read-only"`
 * tools).
 */
type KnownTag = "read-only" | "destructive" | "idempotent" | "open-world";
/**
 * Tag value: one of the framework's well-known tags or any user string.
 * The `& {}` keeps autocomplete on `KnownTag` while accepting arbitrary
 * strings.
 */
type Tag = KnownTag | (string & {});
/**
 * Route-level discovery bundle. Adapters that maintain registries (direct,
 * mcp) mirror these fields into their registry entries; the engine uses
 * `input` / `output` for framework-enforced validation regardless of adapter.
 *
 * Set via the `.title()`, `.description()`, `.input()`, `.output()`,
 * and `.tag()` builder methods. All fields are optional.
 */
interface RouteDiscovery {
    /** Human-readable display title for discovery consumers (agents, docs). */
    title?: string;
    /** Human-readable description of what this route does. */
    description?: string;
    /** Input schemas runtime-enforced before pipeline steps run. */
    input?: RouteSchemas;
    /** Output schemas runtime-enforced before the primary destination. */
    output?: RouteSchemas;
    /**
     * Tags surfaced on `ToolsCatalog` entries for the builder form of
     * `tools((catalog) => ...)` in `@routecraft/ai`, and on resolved
     * tool entries for downstream inspection. Empty/missing means no
     * tags.
     */
    tags?: Tag[];
}
/**
 * Configuration for a route: source, steps, and consumer.
 *
 * Describes how data flows from a source through processing steps to destinations.
 * The builder preserves body type `T`; at runtime the runnable Route uses `Exchange`
 * and handlers/events receive `Exchange<unknown>` unless you narrow or use `Route<T>`.
 *
 * @template T - Body type produced by the source (flowing through the chain until type-erased at runtime)
 *
 * @example
 * ```typescript
 * const def: RouteDefinition<string> = {
 *   id: 'my-route',
 *   sources: [simple('hello')],
 *   steps: [...],
 *   consumer: { type: SimpleConsumer, options: undefined }
 * };
 * ```
 */
type RouteDefinition<T = unknown> = {
    /** Unique identifier for the route */
    readonly id: string;
    /**
     * The sources that feed data into the route. A route may expose multiple
     * ingresses (e.g. `direct` for internal callers, `mcp` for agents, `http`
     * for integrations) that all drive the same downstream pipeline. The route
     * stays a single logical entity: one id, one set of lifecycle events, and
     * (where the registries derive a public name from the route id) one name
     * across ingresses. Every entry must be non-empty; the builder normalizes a
     * single `.from(x)` to `[x]`.
     */
    readonly sources: readonly Source<T>[];
    /** Processing steps that transform, filter, or direct the data */
    readonly steps: Step<Adapter>[];
    /** Consumer configuration that determines how data is processed */
    readonly consumer: {
        /** The type of consumer to use */
        type: ConsumerType<Consumer>;
        /** Options for the consumer */
        options: unknown;
    };
    /**
     * Optional error handler invoked when a step throws an unhandled error.
     * If defined, the handler's return value becomes the final exchange body.
     * If not defined, the error is logged and emitted via the error event (current behavior).
     */
    readonly errorHandler?: ErrorHandler;
    /**
     * Framework-managed filters that run BEFORE the source-attached
     * parse step (and therefore before everything else). Today: the
     * `.authorize()` ValidateSteps in declaration order. This is chain
     * position #2 in `.standards/pre-from-filter-chain.md`.
     *
     * @internal
     */
    readonly preParseFilters: Step<Adapter>[];
    /**
     * Framework-managed filters that run AFTER the source-attached parse
     * step but BEFORE the user pipeline. Today: the route-scope
     * `cache-check` filter (chain position #9). The future
     * `circuitBreaker` (#6) slots in once it lands. Route-scope
     * `throttle` (#5), `retry` (#7), and `timeout` (#8) instead sit
     * OUTSIDE this array (it is wrapped by the retry / timeout segments),
     * so they ride on their own definition fields below.
     *
     * @internal
     */
    readonly postParseFilters: Step<Adapter>[];
    /**
     * Framework-managed filters that run AFTER the user pipeline.
     * Today: the route-scope `cache-store` filter (chain position #10)
     * when `.cache()` is configured. Reached only on miss-success; the
     * cache-check filter pushes `steps: []` on a hit to short-circuit.
     *
     * @internal
     */
    readonly postFromFilters: Step<Adapter>[];
    /**
     * Optional route-level discovery bundle: title, description, and input /
     * output schemas. Populated via `.title()`, `.description()`, `.input()`,
     * and `.output()` on the route builder. The engine enforces `input` and
     * `output` schemas; discovery-aware adapters (direct, mcp) mirror the
     * metadata into their registries.
     */
    readonly discovery?: RouteDiscovery;
    /**
     * The route's enablement predicate and refresh cadence, from `.enabled()`.
     *
     * Route metadata rather than a filter: it decides whether this route runs
     * at all, per route and per lifecycle, so it never enters the pre-from
     * filter chain and never sees an exchange. Absent means always enabled,
     * which is every route that does not declare one.
     */
    readonly enablement?: RouteEnablement;
    /**
     * True when the route declares a route-entry `.authorize()`. Mirrored to
     * sources via {@link SourceMeta.requiresPrincipal} so identity-capable
     * transports enforce credential verification before dispatching into the
     * route, even on an unwalled mount.
     */
    readonly requiresPrincipal?: boolean;
    /**
     * Route-scope `.retry()` config (pre-from filter chain position #7).
     * Unlike the cache filters, retry is not a flat step in
     * `postParseFilters`: it scopes over the whole chain tail (timeout,
     * cache-check, user pipeline, cache-store) and re-runs it on
     * failure, so the pipeline executor wraps the tail in a retry
     * segment step when this is set. See
     * `.standards/pre-from-filter-chain.md`.
     */
    readonly retry?: ResolvedRetryOptions;
    /**
     * Route-scope `.timeout()` config (pre-from filter chain position
     * #8). Bounds each run of the chain tail below it with a deadline;
     * placed inside `retry` so every attempt gets its own deadline. Like
     * `retry`, realized as a segment step wrapped around the tail by the
     * pipeline executor rather than a flat `postParseFilters` entry.
     */
    readonly timeout?: ResolvedTimeoutOptions;
    /**
     * Route-scope `.throttle()` admission gates (pre-from filter chain
     * position #5), in declaration order. Each is a one-shot gate (a flat
     * step, not a segment like retry / timeout); the exchange must be
     * admitted by ALL of them, so stacking `.throttle()` calls AND-combines
     * independent limits (e.g. a global ceiling plus a per-principal rate).
     * The pipeline executor places them OUTSIDE the retry (#7) / timeout
     * (#8) segments (throttle #5 is above them in the chain) and runs them
     * once per exchange; a retried attempt re-runs only the tail below and
     * never re-acquires a token.
     *
     * @internal
     */
    readonly throttle?: Step<Adapter>[];
    /**
     * Route-scope `.circuitBreaker()` controller (pre-from filter chain
     * position #6). Unlike retry / timeout (config objects re-built into a
     * segment per run), the breaker holds persistent per-Route state (the
     * failure window and the open/half-open machine), so the builder stores
     * the live {@link CircuitBreakerController} here once at `.from()` time
     * and the pipeline executor wraps the chain tail in a breaker segment
     * around it. Sits OUTSIDE the retry (#7) / timeout (#8) segments and
     * INSIDE the throttle (#5) gate: when open it fast-fails before retry /
     * timeout run, so one tripped breaker call is recorded per fully
     * exhausted attempt, not per retry. See
     * `.standards/pre-from-filter-chain.md`.
     *
     * @internal
     */
    readonly circuitBreaker?: CircuitBreakerController;
    /**
     * Route-scope `.concurrency()` bulkhead controllers (one per
     * `.concurrency()` call; they nest). Like the circuit breaker they hold
     * persistent per-Route state (the slot pool / semaphores), so the builder
     * stores the live {@link ConcurrencyController}s here once at `.from()`
     * time and the pipeline executor wraps the chain tail in a bulkhead
     * segment per controller. Sits at the INNERMOST resilience position,
     * INSIDE the retry (#7) / timeout (#8) segments, so a slot is acquired
     * per attempt and released between retry backoffs (never held while a
     * retry sleeps). See `.standards/pre-from-filter-chain.md`.
     *
     * @internal
     */
    readonly concurrency?: ConcurrencyController[];
    /**
     * Every `.defer()` the route can reach, resolved once at build time and
     * in pre-order. Each step carries the {@link DeferSite} naming its
     * address and its continuation, which is what a resume addresses: the
     * continuation cannot be a closure captured at defer time, because
     * execution two happens in a different process.
     *
     * Absent (rather than empty) on a route that never defers, so the
     * common case costs nothing and `context.start()` can tell "no defers"
     * from "defers, needs a runtime" without walking anything.
     *
     * @internal
     */
    deferSteps?: DeferrableStep[];
    /**
     * Every defer-capable `.to()` / `.enrich()` step the route carries on
     * its primary flow, each holding the re-entrant {@link DeferSite} the
     * walk assigned it. Separate from {@link RouteDefinition.deferSteps}
     * deliberately: a capable step only MAY defer at runtime, so it does not
     * make the route require a deferral runtime at startup (`RC5052` stays
     * keyed to static sites; a runtime deferral without the runtime fails as an
     * ordinary step error naming the config line), and it does not trip the
     * route-scope cache refusal, whose "silently never caches" reasoning
     * assumes every run defers.
     *
     * @internal
     */
    reentrantDeferSteps?: DeferCapableStep[];
    /**
     * The route can reach a `.resume()`. Recorded alongside
     * {@link RouteDefinition.deferSteps} because a resume ingress needs the
     * deferral runtime too (it verifies tokens and reads the store), and a
     * resume-only route carries no defer sites to infer that from.
     *
     * @internal
     */
    usesResume?: boolean;
    /**
     * The route has no `.id()` and a `.cache()` using the default key, which
     * is namespaced by the route id. The generated id changes on every start,
     * so the route warns once it is registered. Set by `RouteBuilder.build()`.
     *
     * @internal
     */
    volatileCacheKey?: boolean;
    /**
     * Fingerprint of the user pipeline a route-scope `.cache()` skips on a
     * hit, folded into its default key (see `CacheKeyScope`). Set by
     * `RouteBuilder.build()` on a route with a route-scope cache.
     *
     * @internal
     */
    cachePipeline?: string;
};
/**
 * Represents a runnable route that processes data.
 *
 * Routes handle the flow of data from a source through processing steps
 * and can be started and stopped. Use Route<T> when you know the route's
 * body type (e.g. from a typed definition); at runtime, handlers and
 * events receive Exchange (body: unknown) unless narrowed.
 *
 * @template T The body type of the route's exchange when known (default unknown)
 */
interface Route<T = unknown> {
    /** The context this route belongs to */
    readonly context: CraftContext;
    /** The route's configuration */
    readonly definition: RouteDefinition<T>;
    /**
     * Fires when in-flight work on this route is being abandoned. NOT fired
     * when the route merely stops accepting new work, which is what graceful
     * shutdown's first stage does.
     */
    readonly signal: AbortSignal;
    /**
     * Fires when the route stops accepting new work, which is the moment
     * graceful shutdown begins. Work already in flight keeps running.
     *
     * A wrapper that is WAITING observes this: a `.delay()` wait, a
     * `.throttle()` pacing gap, a bulkhead queue slot, a `.retry()` backoff.
     * The wait is cut short once shutdown begins and the exchange still
     * reaches a terminal outcome, where sitting the timer out burns the
     * shutdown deadline and ends in an abandonment that reports nothing.
     * {@link Route.signal} is for abandonment itself, never for shortening a
     * wait.
     */
    readonly intakeSignal: AbortSignal;
    /**
     * Abandon in-flight execution on this route. The forced stage of shutdown
     * and an explicit `stop()`; never the graceful drain.
     * @internal
     */
    abortExecution(reason?: unknown): void;
    /**
     * How much work is still in flight. Read when a forced shutdown reports
     * what it is abandoning, which is the only forensic record that stage
     * leaves.
     * @internal
     */
    readonly inFlightCount: number;
    /** Logger for this route (pino child logger) */
    logger: ReturnType<typeof logger.child>;
    /**
     * Start processing: subscribe to every source and begin delivering messages through the steps.
     * @returns Promise that resolves when all sources have been subscribed and the consumers are ready
     */
    start(): Promise<void>;
    /**
     * Stop the route: abort all source subscriptions and clear the internal queues.
     */
    stop(): void;
    /**
     * Re-arm a stopped route so {@link Route.start} can run again, under the
     * fresh controller the context now holds for it.
     *
     * Only enablement calls this. Both abort controllers latch, and the queues
     * and consumers behind them belong to the run that just ended, so a route
     * brought back from `disabled` needs new ones or it would refuse to start
     * against its own aborted signal. Route IDENTITY is deliberately preserved:
     * ops tracks by route id, the capability registry keys by endpoint, and
     * listeners hold this instance, so re-enabling must not hand out a
     * different object.
     *
     * @param controller - The intake controller the context has registered
     *   for this route, so the two never disagree about which one a shutdown
     *   aborts.
     * @internal
     */
    resetForRestart(controller: AbortController): void;
    /**
     * Wait until all in-flight message handlers and tracked tasks (e.g. tap) have completed.
     * Does not stop the route; use stop() to abort the sources.
     */
    drain(): Promise<void>;
    /**
     * Track a background task (e.g. tap) for this route.
     * @param promise The promise to track
     * @internal
     */
    trackTask(promise: Promise<unknown>): void;
    /**
     * Register a callback run at the START of every `drain()` (which shutdown
     * also calls), before the in-flight wait loop. Lets a step holding an
     * exchange outside the queue (debounce) flush it into in-flight work so
     * drain releases it promptly instead of waiting out a timer. Callbacks
     * must be idempotent: `drain()` can be called more than once.
     *
     * @internal
     */
    onDrain(callback: () => void): void;
    /**
     * Run `steps` against a revived exchange as a first-class run of this
     * route: its own `route:exchange:started` / `:completed` pair, the route-scope
     * `.error()` handler, and `.output()` validation before completion.
     *
     * The entry point for execution two. The steps handed in are the deferred
     * exchange's continuation, so the route resumes partway down its pipeline
     * without re-running what already ran, and without re-running the
     * pre-from filter chain (authorize, parse, input, throttle, cache), all
     * of which belong to execution one.
     *
     * @param exchange - The rehydrated exchange, already bound to this route
     * @param steps - The continuation, in execution order
     * @internal
     */
    runContinuation(exchange: Exchange, steps: ReadonlyArray<Step<Adapter>>): Promise<DetachedResult>;
    /**
     * Push an error into this route's error channel for an exchange that is
     * not currently running in it.
     *
     * The resume path uses it so a revival failure (an expired deferral, a
     * continuation that changed under a deferred exchange) reaches the
     * DEFERRED route's `.error()` handler rather than only the ingress
     * route's. That is the difference between a route that can notify the
     * approver and re-ask, and an approver left at a dead link.
     *
     * @param exchange - The exchange the failure concerns
     * @param error - The failure to route
     * @param operation - Step label reported on the error events
     * @internal
     */
    enterErrorChannel(exchange: Exchange, error: unknown, operation: string): Promise<void>;
    /**
     * Build a forward function the route uses to delegate from an
     * error / fallback handler to another route via the direct adapter.
     * Exposed so step-scope `WrapperStep` subclasses can hand the same
     * callable to a user-supplied handler as the route-level pipeline
     * does.
     *
     * @param caller The exchange the forward is issued from. Its headers
     *   travel with the forwarded call, so the target sees the same
     *   principal and correlation id as the caller. Required rather than
     *   optional so a new call site cannot silently forward anonymously.
     * @internal
     */
    getForward(caller: Exchange): ForwardFn;
}
/**
 * Default implementation of the Route interface.
 *
 * Manages message flow from the source through the defined steps and the
 * internal processing queue to the consumer. Handles start, stop, drain, and
 * background task tracking (e.g. for tap).
 */
declare class DefaultRoute implements Route {
    readonly context: CraftContext;
    readonly definition: RouteDefinition;
    /**
     * Stops INTAKE: sources subscribe against this, and aborting it means
     * "produce nothing further". It does NOT cancel work already in flight,
     * which is what makes graceful shutdown's first stage a drain rather than
     * a cancellation.
     */
    private abortController;
    /**
     * Abandons EXECUTION: surfaced as {@link DefaultRoute.signal} and threaded
     * into steps, wrappers and agent dispatch. Aborted only when work is
     * genuinely being given up on: a forced shutdown, an explicit `stop()`, or
     * a route that failed to start.
     *
     * Separate from intake because one controller carrying both meanings made
     * the documented two-stage shutdown a lie: the first signal, which
     * promises to stop accepting work and drain, cancelled every in-flight
     * exchange as well.
     */
    private executionController;
    /** Logger for this route (pino child logger) */
    readonly logger: ReturnType<typeof logger.child>;
    /** Internal queues, one per source, for passing messages to the consumers */
    private messageChannels;
    /** Processes messages from the message channels, one consumer per source */
    private consumers;
    /** All in-flight work (handler and task promises) for drain */
    private inFlight;
    /** Callbacks run at the start of drain() to flush deferred holds (debounce). */
    private drainCallbacks;
    /**
     * Create a new route instance.
     *
     * @param context The context this route belongs to
     * @param definition The route's configuration
     * @param abortController Optional controller for aborting the route
     */
    constructor(context: CraftContext, definition: RouteDefinition, abortController?: AbortController);
    /**
     * Emit `route:stopping` / `route:stopped` when the intake controller
     * aborts, however that abort arrives (shutdown, `stop()`, a finite source
     * completing). Re-armed on every restart because the listener belongs to
     * the controller, and a restart installs a new one.
     */
    private watchIntakeAbort;
    /** @inheritDoc */
    get intakeSignal(): AbortSignal;
    /** @inheritDoc */
    get inFlightCount(): number;
    /**
     * The EXECUTION signal: fires when in-flight work is being abandoned, not
     * when the route merely stops accepting new work. Steps, resilience
     * wrappers and agent dispatch observe this.
     */
    get signal(): AbortSignal;
    /**
     * Abandon in-flight execution on this route.
     *
     * Graceful shutdown never calls this: stage one aborts intake and waits.
     * It is the forced stage, an explicit `stop()`, and a route that failed to
     * start.
     *
     * @param reason - Recorded as the abort reason for anything observing it.
     * @internal
     */
    abortExecution(reason?: unknown): void;
    /**
     * Create a new exchange object from a message and optional headers.
     *
     * Sources that authenticate at their boundary set the structured
     * `Principal` on `headers["routecraft.auth.principal"]` before calling
     * the consumer handler; that value flows through this method as a
     * normal header and surfaces on the exchange via the `ex.principal`
     * getter.
     *
     * This is the single route-ingress boundary: both the consumer handler
     * and `buildForward` funnel through it, and a `direct()` source hands the
     * target its caller's headers verbatim. Engine-owned identity is
     * therefore re-established here rather than inherited:
     *
     * - `routecraft.id` is minted fresh. Ingress is always a new exchange,
     *   and an inherited id collides in every store keyed by it (telemetry
     *   spans and rows, deferral ids). The correlation id is what links a
     *   hop, not the exchange id.
     * - `routecraft.split_hierarchy` is dropped. A split group only joins
     *   within the executor run that created it, so an inherited hierarchy is
     *   unjoinable, and `.aggregate()` would resolve its trailing group id
     *   against the context-wide split-parent store and delete the caller's
     *   still-in-flight entry.
     * - `routecraft.route` and `routecraft.operation` are stamped for the
     *   receiving route.
     *
     * Everything else, principal and correlation id included, is inherited by
     * reference. See `.standards/security.md` section 3.
     *
     * @param message The message data
     * @param headers Optional headers to include
     * @returns A new Exchange object
     * @private
     */
    private buildExchange;
    private cachedExecutorDeps?;
    private cachedValidationDeps?;
    /**
     * Assemble the deps object for the pipeline executor. Memoized: every
     * field is stable for the lifetime of the route, and this is called on
     * the per-exchange hot path.
     */
    private executorDeps;
    /** Assemble the deps object for the pipeline validation helpers (memoized, see {@link executorDeps}). */
    private validationDeps;
    /**
     * Track a background task (e.g. tap) for this route.
     * @internal
     */
    trackTask(promise: Promise<unknown>): void;
    /**
     * Register a flush callback run at the start of drain(). See {@link Route.onDrain}.
     * @internal
     */
    onDrain(callback: () => void): void;
    /**
     * Start processing data on this route.
     *
     * This method:
     * 1. Registers each per-source consumer to process messages
     * 2. Subscribes to every source to receive data
     *
     * @returns A promise that resolves when the route has started
     * @throws {RoutecraftError} If the route has been aborted
     */
    start(): Promise<void>;
    /**
     * Create an AbortController that aborts when the route's controller aborts,
     * but whose own abort does not propagate back to the route. Used to give
     * each ingress of a multi-source route an independent lifetime so a finite
     * source completing does not tear down its sibling ingresses.
     */
    private linkedChildController;
    /**
     * Build the handler registered on every per-source consumer. The handler is
     * shared across all of a route's ingresses so they drive one pipeline; it
     * stashes the source-supplied parser and the route's `.input()` validator
     * on exchange internals so `runPipeline` runs both INSIDE the pre-from
     * filter chain (positions #3 / #4). A parse or validation failure is
     * therefore a normal step failure, routable through the route-scope
     * `.error()` handler (chain position #1) for every source shape; see
     * #187 (parse) and #447 (the input fold).
     */
    private buildConsumerHandler;
    /**
     * Stop processing data on this route.
     *
     * This method:
     * 1. Unsubscribes from the internal processing queue
     * 2. Aborts the route's controller
     */
    stop(): void;
    /**
     * One (channel, consumer) pair per source, so each ingress gets its own
     * delivery queue and, for batch routes, its own batch window. All
     * consumers drive the same shared step pipeline via the handler registered
     * in start(), so the route stays a single logical entity regardless of how
     * many ingresses it exposes.
     *
     * Shared by the constructor and the restart so a consumer that gains a
     * construction dependency cannot get it in one path and silently miss it
     * in the other.
     */
    private buildChannelsAndConsumers;
    /** @inheritDoc */
    resetForRestart(controller: AbortController): void;
    /**
     * Process an exchange through the route's steps.
     * Resolves with the result immediately; then waits for background tasks (e.g. tap) before cleanup.
     *
     * @param exchange The initial exchange to process
     * @returns A promise that resolves when processing is complete
     * @private
     */
    private handler;
    /**
     * Run a revived exchange through its continuation. See
     * {@link Route.runContinuation}.
     *
     * Tracked as in-flight work so `drain()` (and therefore shutdown) waits
     * for execution two, which arrives out of band and would otherwise be
     * invisible to the route that owns it.
     *
     * @internal
     */
    runContinuation(exchange: Exchange, steps: ReadonlyArray<Step<Adapter>>): Promise<DetachedResult>;
    /**
     * Push an error into this route's error channel. See
     * {@link Route.enterErrorChannel}.
     *
     * Implemented as a one-step pipeline whose step throws, rather than by
     * calling the handler directly, so a revival failure produces exactly the
     * events a step failure produces (`route:step:error`,
     * `route:error-handler:invoked` / `:recovered` / `:failed`, or the
     * default `route:error` + `context:error` + `route:exchange:failed`
     * path). A second, hand-rolled error path would drift from that one.
     *
     * @internal
     */
    enterErrorChannel(exchange: Exchange, error: unknown, operation: string): Promise<void>;
    /**
     * Build a forward function that sends a payload to another route via the direct adapter.
     *
     * Exposed (`@internal`) so step-scope `WrapperStep` subclasses can hand
     * the same forward callable to a user-supplied error / fallback handler
     * as the route-level pipeline does. Resolve via
     * `getExchangeRoute(exchange).getForward(exchange)`.
     *
     * @returns A forward function
     */
    getForward(caller: Exchange): ForwardFn;
    /**
     * Build a forward function that sends a payload to another route via the direct adapter.
     *
     * The forwarded exchange inherits the calling exchange's headers, which is
     * what carries the caller's principal and correlation id across the hop. A
     * `direct()` destination gets this for free because it hands the target its
     * live exchange; forward builds a fresh envelope, so it has to pass the
     * headers explicitly or the target sees an anonymous, separately-traced
     * call.
     *
     * @param caller The exchange the forward is issued from
     * @returns A forward function
     * @private
     */
    private buildForward;
    /**
     * Wait for all in-flight work (handlers and tasks) to complete.
     * Loops until no new work is added (drains consumer queue).
     */
    drain(): Promise<void>;
    /**
     * Run the registered drain-flush callbacks (see {@link Route.onDrain}).
     * Callbacks are idempotent by contract, so calling this repeatedly (once
     * up front and once per drain settle round) is safe.
     */
    private runDrainCallbacks;
    /**
     * Check if the route has been aborted, and throw an error if it has.
     *
     * @throws {RoutecraftError} If the route has been aborted
     * @private
     */
    private assertNotAborted;
}

/**
 * A discoverable capability registered in a context: an endpoint plus the
 * route's discovery bundle (`.title()` / `.description()` / `.input()` /
 * `.output()` / `.tag()`).
 *
 * Returned by {@link CraftContext.capabilities}; dispatch into a
 * capability with `CraftClient.sendDirect(endpoint, body)`.
 */
interface Capability extends RouteDiscovery {
    /** Raw endpoint / route id, exactly as passed to `.id(...)` / `direct(...)`. */
    endpoint: string;
    /**
     * The remote this capability was imported from (`defineConfig({ remotes })`),
     * absent for a capability a local route registered. Read by the ops
     * listing to name the origin and by the agent tool policy so a rule can
     * keep an agent local-only.
     */
    remote?: string;
}
/**
 * Core-owned store key for the capability registry, keyed by RAW endpoint.
 *
 * Ownership is deliberately inverted from "core reads an adapter's
 * registry": adapters that expose discoverable endpoints WRITE into this
 * registry via {@link registerCapability}, and `context.capabilities()`
 * reads it without knowing which adapter populated it. That keeps the
 * core context free of adapter knowledge and lets future discoverable
 * adapters surface in `capabilities()` without core changes.
 *
 * `Symbol.for` so duplicate copies of the package (CLI vs user module)
 * share one registry.
 *
 * @internal The registry shape is internal; read via
 *   `context.capabilities()` and write via {@link registerCapability}.
 */
declare const CAPABILITY_REGISTRY: unique symbol;
/**
 * Register (or update) a discoverable capability on the context. Called
 * by adapters when a discoverable endpoint subscribes; the direct source
 * is the built-in writer, and ecosystem adapters exposing their own
 * discoverable endpoints use the same call.
 *
 * Keyed by the RAW endpoint id; any transport-level key encoding stays
 * inside the adapter that needs it.
 *
 * @returns A disposer that removes THIS registration when the endpoint is
 *   still held by it, and does nothing once something else has taken the
 *   name. An unconditional delete would be wrong on the one path that
 *   matters: a local route stopping hands its endpoint to the remote route
 *   it shadowed, `route:stopped` reaches the remotes plugin before the
 *   direct source's own abort listener, and a blind delete would then
 *   erase the replacement that already owns the name.
 */
declare function registerCapability(context: CraftContext, capability: Capability): () => void;
/**
 * Core-owned store key for endpoints declared internal, keyed by RAW
 * endpoint. Same ownership inversion as {@link CAPABILITY_REGISTRY}:
 * adapters write, consumers read without knowing which adapter wrote.
 *
 * A `direct({ internal: true })` source registers here INSTEAD of the
 * capability registry: its in-process endpoint works unchanged, while the
 * two external doors (ops dispatch, agent `directTool` resolution) find
 * no capability. This map is what lets their refusals say "declared
 * internal" instead of the wrong advice "add `.from(direct())`" for a
 * route that has one.
 *
 * A map rather than a set of names, because a marker has to be removable
 * by the registration that wrote it and by nothing else. The value is an
 * identity token: a stale disposer from a route that has already stopped
 * compares its own token against what the map holds and finds a stranger
 * there, so it leaves the live marker alone.
 *
 * @internal The map shape is internal; write via
 *   {@link registerInternalEndpoint} and read via {@link isInternalEndpoint}.
 */
declare const INTERNAL_ENDPOINT_REGISTRY: unique symbol;
declare module "@routecraft/routecraft" {
    interface StoreRegistry {
        [CAPABILITY_REGISTRY]: Map<string, Capability>;
    }
}
declare module "@routecraft/routecraft" {
    interface StoreRegistry {
        [INTERNAL_ENDPOINT_REGISTRY]: Map<string, symbol>;
    }
}
/**
 * Record that an endpoint declared itself internal: composable in-process,
 * deliberately absent from the capability registry. Called by adapters at
 * subscribe, alongside where they would otherwise register a capability.
 *
 * @returns A disposer with the same ownership rule as
 *   {@link registerCapability}'s: it clears the marker only while this
 *   registration still holds it.
 */
declare function registerInternalEndpoint(context: CraftContext, endpoint: string): () => void;
/**
 * Whether an endpoint declared itself internal. Read by the external doors
 * (ops dispatch, agent tool resolution) to refuse by name rather than with
 * advice that does not apply.
 */
declare function isInternalEndpoint(context: CraftContext, endpoint: string): boolean;

/**
 * Store key under which test-time adapter overrides are registered.
 *
 * Intended for use by `@routecraft/testing`'s `testContext().override(...)`
 * API. Production code should not write to this key.
 * @internal
 */
declare const RC_ADAPTER_OVERRIDES: unique symbol;
/**
 * Recorded call to an overridden destination adapter (send / enrich).
 * @internal
 */
interface AdapterSendCall {
    /** Args that were passed to the adapter's factory at route definition time. */
    args: unknown[];
    /** Snapshot of the exchange as seen by the adapter at the moment of the call. */
    exchange: {
        id: string;
        body: unknown;
        headers: ExchangeHeaders;
    };
    /** Result the mock returned (undefined for void-returning sends). */
    result: unknown;
}
/**
 * Recorded call to an overridden source adapter (subscribe).
 * @internal
 */
interface AdapterSourceCall {
    /** Args that were passed to the factory at route definition time. */
    args: unknown[];
    /** Number of messages yielded by this subscription. */
    yielded: number;
}
/**
 * Brand marking a source fixture that carries explicit headers alongside its
 * body. Lets a source-role mock reproduce the body/headers split that real
 * envelope-carrying sources (http, mail) perform, so a route that reads
 * `routecraft.<adapter>.*` headers can be exercised through `mockAdapter`.
 *
 * Use the `sourceMessage()` helper from `@routecraft/testing` to construct
 * these rather than building the branded object by hand.
 * @internal
 */
declare const SOURCE_FIXTURE: unique symbol;
/**
 * A source fixture pairing a message body with the headers a real source would
 * have attached. Recognised by {@link wrapSourceWithOverride}.
 * @internal
 */
interface SourceFixture<M = unknown> {
    readonly [SOURCE_FIXTURE]: true;
    /** The body the source would deliver on the exchange. */
    readonly body: M;
    /** Headers the source would attach (e.g. `routecraft.mail.*`). */
    readonly headers?: ExchangeHeaders;
}
/**
 * Type guard for {@link SourceFixture}. A plain message is delivered as the
 * body with no headers; a branded fixture is unwrapped into `(body, headers)`.
 * @internal
 */
declare function isSourceFixture(value: unknown): value is SourceFixture;
/**
 * A source-role fixture: either a plain message (delivered as the body with no
 * headers) or a {@link SourceFixture} carrying body + headers.
 * @internal
 */
type SourceMessage<M = unknown> = M | SourceFixture<M>;
/**
 * Handler shape for a source-role mock. May be a plain array of fixtures,
 * an async iterable, or a callable that returns either (receiving the
 * construction args so it can vary by call site). Each fixture may be a plain
 * message or a {@link SourceFixture} (via `sourceMessage()`) to also attach
 * headers.
 * @internal
 */
type SourceOverrideBehavior<M = unknown> = readonly SourceMessage<M>[] | AsyncIterable<SourceMessage<M>> | Iterable<SourceMessage<M>> | ((args: unknown[]) => readonly SourceMessage<M>[] | Iterable<SourceMessage<M>> | AsyncIterable<SourceMessage<M>>);
/**
 * Handler shape for a destination-role mock. Receives the exchange (as
 * seen by the adapter) and a meta object containing the factory args used
 * at the call site. Returning a value replaces `exchange.body` upstream.
 * @internal
 */
type SendOverrideHandler = (exchange: Exchange, meta: {
    args: unknown[];
}) => unknown | Promise<unknown>;
/**
 * An override registered on a test context. `target` may be either the
 * factory function that produced the adapter (matched via the factory-tag
 * set by `tagAdapter`) or the adapter's constructor class (matched by
 * `adapter.constructor === target`). Both routes coexist so any adapter
 * can be mocked without opt-in, while tagged factories keep nicer DX.
 * @internal
 */
interface AdapterOverride {
    /** Factory function or adapter class to match against the adapter instance. */
    target: unknown;
    /** Optional source-role behaviour (used when adapter has `subscribe`). */
    source?: SourceOverrideBehavior;
    /** Optional destination-role behaviour (used when adapter has `send`). */
    send?: SendOverrideHandler;
    /** Recorded calls, populated at execution time. */
    calls: {
        source: AdapterSourceCall[];
        send: AdapterSendCall[];
    };
}

/**
 * The minimal synchronous SQLite surface the framework's storage
 * subsystems need, declared once for every consumer.
 *
 * Declared here rather than imported so neither `bun-types` nor
 * `@types/better-sqlite3` reaches the published type surface. `bun:sqlite`
 * and `better-sqlite3` both satisfy this shape, which is what lets one
 * store implementation sit on either driver.
 *
 * A consumer needing more than this extends {@link SqliteDatabase} with
 * the members it actually uses, rather than re-deriving what the two
 * drivers have in common.
 */
interface SqliteStatement {
    run(...params: unknown[]): unknown;
    all(...params: unknown[]): unknown[];
    get(...params: unknown[]): unknown;
}
interface SqliteDatabase {
    exec(sql: string): void;
    prepare(sql: string): SqliteStatement;
    close(): void;
}
/**
 * Constructor shape shared by both drivers. The options argument is
 * optional because `bun:sqlite` and `better-sqlite3` accept one and the
 * deferral store passes none; typing it here keeps callers that do pass
 * options from re-declaring the whole constructor.
 */
type SqliteDatabaseConstructor = new (filename: string, options?: {
    readonly?: boolean;
}) => SqliteDatabase;

/**
 * Which driver backs a resolved connection. Surfaced so the store factory
 * can log what a deployment actually got, and so tests can assert the split
 * rather than infer it.
 */
type SqliteDriverName = "bun:sqlite" | "better-sqlite3";
interface ResolvedSqliteDriver {
    readonly name: SqliteDriverName;
    readonly Database: SqliteDatabaseConstructor;
}
/**
 * Resolve a synchronous SQLite driver for the current runtime.
 *
 * `bun:sqlite` under Bun, `better-sqlite3` as an optional peer under Node,
 * and an in-memory fallback with a loud warning when neither is available.
 * The default is durable wherever the runtime allows, because surviving a
 * restart is the feature's whole promise.
 *
 * ## Why not `node:sqlite`
 *
 * It is ruled out by the engines floor rather than by its API:
 *
 * | Runtime | `bun:sqlite` | `node:sqlite` | `better-sqlite3` |
 * | --- | --- | --- | --- |
 * | Bun >= 1.1 (our floor) | built in | n/a | installable |
 * | Node 22.0 - 22.4 (our floor) | n/a | does not exist | installable |
 * | Node 22.5+ | n/a | behind `--experimental-sqlite` | installable |
 * | Node 24+ | n/a | unflagged | installable |
 *
 * Core's floor is Node 22.0, so across the supported range `node:sqlite`
 * either does not exist or needs a CLI flag the framework cannot set on the
 * user's behalf. That inverts the naive preference order for the Node arm
 * and leaves `better-sqlite3` as the only Node option that works on the
 * whole range.
 *
 * ## Graduation condition for `node:sqlite`
 *
 * `node:sqlite` becomes the preferred Node driver, ahead of
 * `better-sqlite3`, once `@routecraft/routecraft`'s `engines.node` floor
 * moves past the first Node major where it runs unflagged (Node 24). At
 * that point it is a built-in with no install step and no native rebuild,
 * which beats an optional peer on every axis; `better-sqlite3` stays
 * supported as a fallback for anyone below the new floor. Revisit this
 * function and nothing else: the store talks to {@link SqliteDatabase},
 * not to a driver.
 *
 * @param consumer - Names the subsystem asking, so an absent peer names
 *   what wanted it ("deferral store (sqlite)", "telemetry (sqlite)")
 *   rather than reporting a generic sqlite failure. Used ONLY to build the
 *   default loaders: a caller that supplies its own `loaders` owns the
 *   naming inside them, and this argument then has no effect.
 * @param loaders - Injection point for tests, which need to simulate a
 *   runtime that lacks a driver without leaving the runtime they run on.
 * @returns The resolved driver for this runtime.
 * @throws RC5017 when running under Node and `better-sqlite3` is absent.
 *   Whether that is fatal is the store factory's call, not this
 *   function's: an unconfigured context falls back to memory with a
 *   warning, while a context that named a store path fails to start,
 *   because silently degrading a deployment that asked for durability is
 *   worse than refusing to run.
 */
declare function resolveSqliteDriver(consumer: string, loaders?: SqliteDriverLoaders): Promise<ResolvedSqliteDriver>;
/**
 * Driver loaders. Injectable so a store in another package, or a test
 * exercising the absent-peer arm, supplies its own resolution rather than
 * the runtime's.
 */
interface SqliteDriverLoaders {
    bun(): Promise<SqliteDatabaseConstructor>;
    node(): Promise<SqliteDatabaseConstructor>;
}

/**
 * Environment variable read for the resume-token signing secret when the
 * context does not configure one explicitly.
 */
declare const DEFERRAL_SECRET_ENV = "ROUTECRAFT_DEFERRAL_SECRET";
/**
 * A signed capability naming one deferral.
 *
 * The token proves that whoever holds it was handed it by this deployment.
 * It does NOT prove the holder may resume: authorizing the resuming
 * principal is the resume ingress route's job (`.resume({ authorize })`,
 * sender verification, a per-recipient link), which is where an
 * authenticated principal is available. Nor does the token enforce single use on its own; the store's
 * compare-and-swap does that, so a replayed token finds the deferral
 * already resumed and gets the cached continuation result instead of a second
 * execution.
 */
interface ResumeTokenPayload {
    /** Deferral this token resumes. */
    readonly id: string;
    /** Mint time, epoch milliseconds. Carried for audit, not enforced. */
    readonly iat: number;
    /**
     * The call this credential belongs to, when the deferring step can raise
     * more than one at a time.
     *
     * A deferral id names a RECORD; on the agent surface a single record is
     * reached through whichever tool call won a parallel batch, and every
     * handler in that batch is handed a credential before the winner is
     * known. Binding the credential to its own call is what stops the loser's
     * recipient from resuming the winner's deferral: revive compares this claim
     * against the record's own `stepState.deferredToolCallId` and refuses a
     * mismatch before touching the record.
     *
     * Absent for a static `.defer()`, which has exactly one logical call.
     * Both mismatched arms fail closed: a token without this claim cannot
     * resume a record that has a bound call, and a token carrying it cannot
     * resume a record that has none.
     */
    readonly sub?: string;
}
/**
 * Mints and verifies resume tokens for one context.
 *
 * HMAC-SHA256 over a compact JSON payload, encoded base64url so a token
 * survives a URL, an email body, and a chat message without escaping.
 */
declare class ResumeTokenSigner {
    #private;
    /**
     * How the secret was obtained. Surfaced so the context can log it once at
     * startup: an operator seeing `ephemeral` in production has a
     * misconfiguration, and that is worth being able to spot.
     */
    readonly source: SigningSecretSource;
    constructor(secret: string | Buffer, source: SigningSecretSource);
    /**
     * Mint a token for a deferral id.
     *
     * Callable BEFORE the deferring step runs, which is what lets a
     * notification step earlier in the pipeline put a working resume link in
     * the message it sends. Nothing about the deferred exchange is needed to
     * sign: the deferral id is derivable from the exchange (see
     * {@link deferralIdFor}), and the token carries no claims of its own.
     *
     * @param id - The deferral id this token will resume.
     * @param now - Mint timestamp, injectable for deterministic tests.
     * @param sub - The call this credential belongs to, when the deferring
     *   step can raise several at once. See {@link ResumeTokenPayload.sub}.
     */
    mint(id: string, now?: Date, sub?: string): string;
    /**
     * Verify a token and return what it names.
     *
     * @param token - The token as presented by the resume ingress.
     * @returns The verified payload.
     * @throws RC5041 when the token is malformed, carries an unknown format
     *   version, or fails signature verification. The three are deliberately
     *   one error: telling a caller which of them failed tells an attacker
     *   how far a forgery got.
     */
    verify(token: string): ResumeTokenPayload;
}
/** Where a context's signing secret came from. */
type SigningSecretSource = "config" | "env" | "ephemeral";

/**
 * Whether a deferred exchange is still waiting or has settled.
 *
 * Two values, because the five that came before were answers to three
 * different questions. What the work is waiting FOR is
 * {@link Deferral.waitingFor}; how it settled is {@link Deferral.outcome};
 * whether a delivery claim is outstanding is {@link Deferral.claimedAt}. A
 * reader asks one of those and reads the field that answers it, instead of
 * inferring all three from which of five values a record landed on.
 *
 * A deferral is resumable while it is `waiting` AND unclaimed. The claim is
 * a second axis rather than a third state: whoever holds it owns telling the
 * route, and a claim whose holder died is released by
 * {@link DeferralStore.releaseClaims} once its lease elapses, so the next
 * sweep redelivers. Every transition goes through the store's
 * compare-and-swap methods so exactly one caller wins a race between a
 * resume, a sweep, and a cancellation.
 */
type DeferralState = "waiting" | "settled";
/**
 * What a deferral is waiting for.
 *
 * One value today: `.defer()` waits for somebody to call `.resume()`. It is
 * a stored field rather than an implied constant so a management surface can
 * group by it, and so the kinds #737 and #738 add (asking a person, handing
 * work outside the process) widen this union instead of introducing a second
 * vocabulary beside it.
 *
 * Kept on a settled record too, because it says what the work WAS waiting
 * for. That is what makes "expired while waiting for a resume" readable off
 * one record rather than reconstructed from two.
 */
type DeferralWaitingFor = "resume";
/**
 * Keyset cursor for {@link DeferralStore.findExpired}.
 *
 * Pages advance strictly past `(expiresAt, id)`, so a record the caller
 * visited and could not retire is never re-read by the same pass, whatever
 * its state. That is what makes an arbitrarily long unretirable prefix
 * unable to starve the records behind it.
 */
interface ExpiredScanCursor {
    readonly expiresAt: Date;
    readonly id: string;
}
/**
 * Keyset cursor for {@link DeferralStore.list}.
 *
 * A deferral id is `{exchangeId}#{sequence}` and an exchange id is a uuid,
 * so id order says nothing about time. The listing is ordered by
 * `(deferredAt, id)` instead, which is the order an operator reads it in:
 * what has been waiting longest is what they are looking for.
 */
interface DeferralListCursor {
    readonly deferredAt: Date;
    readonly id: string;
}
/**
 * What {@link DeferralStore.list} is being asked for.
 *
 * `state` defaults to `waiting` at the caller rather than here, because a
 * store implementation must not have to know which half of the collection
 * a management surface considers interesting.
 */
interface DeferralListQuery {
    /** Only deferrals in this state. Both states when absent. */
    readonly state?: DeferralState;
    /** Only deferrals belonging to this route. */
    readonly routeId?: string;
    /** Bound on one page. A non-positive or non-integer value throws. */
    readonly limit: number;
    /** Resume strictly past this position in `(deferredAt, id)` order. */
    readonly after?: DeferralListCursor;
}
/**
 * One deferral as a management surface presents it.
 *
 * A projection rather than the record, and deliberately so: the record
 * carries the serialized exchange, the step state and the resume-payload
 * schema, none of which a listing may show and none of which it should
 * pull into memory a page at a time to then drop. What a reader needs is
 * what it is waiting for, how long it has waited, and whether anything
 * already holds it.
 */
interface DeferralSummary {
    readonly id: string;
    readonly routeId: string;
    readonly state: DeferralState;
    /** What the work is waiting for, or was waiting for when it settled. */
    readonly waitingFor: DeferralWaitingFor;
    /**
     * Whether a delivery claim is outstanding, rather than when it was
     * taken. A reader asks whether anything already owns telling the route,
     * and the timestamp is an implementation detail of the lease.
     */
    readonly claimed: boolean;
    readonly deferredAt: Date;
    /** When the sweeper will expire it. Absent means no deadline. */
    readonly expiresAt?: Date;
    /** How it settled. Absent while it is waiting. */
    readonly outcome?: DeferralOutcome;
}
/**
 * Project a stored record onto what a management surface may see.
 *
 * Named once and shared by both backends so a field can never reach the
 * listing from one store and not the other, and so the exchange has one
 * place it is dropped rather than one per backend.
 */
declare function summariseDeferral(deferral: Deferral): DeferralSummary;
/**
 * The persisted form of a deferred exchange: exactly the two stored slots of
 * `Exchange` (`body` and `headers`), per
 * `.standards/exchange-state-model.md`. Derivations (`id`, `principal`,
 * `logger`) are rebuilt by constructing a `DefaultExchange` around these
 * two on the resuming process, so there is nothing else to persist.
 *
 * Both slots are plain JSON data. `serializeExchange` refuses anything else
 * with `RC5042` rather than writing a value the store cannot round-trip.
 */
interface SerializedExchange {
    readonly body: unknown;
    readonly headers: Readonly<Record<string, unknown>>;
}
/**
 * How the resume-payload schema is carried on a stored deferral.
 *
 * A Standard Schema is a live object with a validate function, so it cannot
 * be persisted. What is persisted is a reference: the `(routeId, position)`
 * pair on the record identifies the deferring step, whose live `schema` is
 * read back off the route at resume time, and `hash` is folded into
 * `continuationHash` so a schema that changed under a deferred exchange fails
 * the compatibility check rather than validating against the wrong
 * contract.
 *
 * `jsonSchema` is populated opportunistically from the non-standard
 * `~standard.jsonSchema` extension that Zod, ArkType and the AI SDK bridge
 * expose. It is descriptive only: it tells a caller and an operator what a
 * a valid resume payload looks like. Validation always runs against the live schema.
 *
 * A site that declares NO schema still gets a descriptor, carrying
 * {@link DeferralSchema.absent}. That sentinel is deliberately distinct
 * from the degraded fallback below: without it, editing a site from a
 * declared-but-unrenderable schema to no schema at all would leave the
 * digest unmoved, so a recipient told there was a contract would have their
 * payload accepted unvalidated with no re-ask.
 */
interface DeferralSchema {
    /** Stable hash of the resume-payload schema, or the absent sentinel. */
    readonly hash: string;
    /** Set when the site declared no schema at all. */
    readonly absent?: boolean;
    /** JSON Schema rendering when the schema exposes one. Never used to validate. */
    readonly jsonSchema?: unknown;
    /**
     * Set when the schema advertised a `~standard.jsonSchema` extension that
     * then produced nothing, so {@link DeferralSchema.hash} identifies only
     * the vendor rather than the contract.
     *
     * The consequence is worth stating where it is read: the step tail is
     * still hashed, but a widened or narrowed schema of that kind cannot
     * move the digest, so a resume will not catch it. Zod throws for
     * unrepresentable types (a `Date`, a `bigint`, any `.transform()`), which
     * makes this reachable with an ordinary approval schema.
     */
    readonly degraded?: boolean;
}
/**
 * Audit record of who resumed a deferral.
 *
 * A subset of `Principal` rather than the principal itself: the store is a
 * persistence surface, and a full principal carries claims, scopes and a
 * delegation chain that would be resurrected as data with no verification
 * behind it. What is recorded is enough to answer "who authorized this",
 * which is what the receipt is for.
 */
interface PrincipalRef {
    readonly subject: string;
    readonly issuer?: string;
    readonly clientId?: string;
    /** The outermost actor's subject when a delegate resumed on someone's behalf. */
    readonly actorSubject?: string;
}
/**
 * How a deferral settled.
 *
 * Present exactly when {@link Deferral.state} is `settled` and absent
 * exactly while it is `waiting`. Nothing in the type system enforces that
 * pairing; the store's transitions do, because every one of them writes
 * `state` and `outcome` in the same compare-and-swap.
 */
interface DeferralOutcome {
    /** Which way it ended. */
    readonly kind: "resumed" | "expired" | "denied";
    /**
     * When the record left the waiting state. This is the retention clock:
     * {@link DeferralStore.purgeSettled} measures from here, so a record that
     * waits for months and settles today is kept for the full retention
     * window from today.
     */
    readonly at: Date;
    /** Why a `denied` deferral was denied (cancellation, operator action). */
    readonly reason?: string;
    /** Who resumed it. Only ever set on a `resumed` outcome. */
    readonly by?: PrincipalRef;
}
/**
 * The cached result of execution two, written once the resumed exchange
 * settles. A duplicate resume returns this instead of running the
 * continuation a second time.
 */
interface SerializedOutcome {
    /**
     * How execution two ended. `deferred` is the two-stage-approval case:
     * the continuation reached ANOTHER `.defer()` and deferred again, so the
     * work is neither finished nor failed. It is recorded distinctly because
     * calling it `completed` would tell a receipt, a dashboard, and every
     * duplicate resume that the work finished while it is still waiting on
     * the next resume.
     */
    readonly status: "completed" | "failed" | "dropped" | "deferred";
    /** Terminal body on a completed run. Plain JSON data, same rule as {@link SerializedExchange}. */
    readonly body?: unknown;
    /** Error code and message on a failed run. The stack is deliberately not persisted. */
    readonly error?: {
        readonly rc?: string;
        readonly message: string;
    };
    /** Drop reason on a dropped run. */
    readonly reason?: string;
    readonly at: Date;
}
/**
 * A deferred exchange plus everything needed to revive it.
 *
 * The record is deliberately free of anything agent-shaped. A deferring
 * step that needs to carry closure state of its own puts it in
 * {@link Deferral.stepState}, which the store never interprets; that one
 * opaque slot is what lets the agent tier (#258) share this store instead
 * of growing a second one.
 */
interface Deferral {
    /** Deferral identity. Distinct from the deferred exchange's own id. */
    readonly id: string;
    /** Route the deferred exchange belongs to. Resume re-enters this route. */
    readonly routeId: string;
    /** Index of the deferring step. Execution two resumes at `position + 1`. */
    readonly position: number;
    /**
     * Hash over steps `position + 1` to the end of the pipeline, plus the
     * resume-payload schema descriptor.
     *
     * {@link Deferral.meta} is deliberately NOT folded in. It lives only on
     * the record, so it has no live copy to drift from: a defer site that
     * snapshots its policy there is protected by where the value lives rather
     * than by a tamper check.
     *
     * Covers step DEFINITIONS only: what a `direct()` route the tail forwards
     * to actually does, which version an adapter is on, and how an external
     * system behaves can all change without moving this hash. See
     * {@link continuationHash}.
     */
    readonly continuationHash: string;
    readonly exchange: SerializedExchange;
    readonly schema: DeferralSchema;
    /**
     * Whatever the deferring step attached at deferral, persisted verbatim and
     * handed back to the resume route's `authorize` hook.
     *
     * The framework never reads it. Who may resume a deferred run is the
     * application's policy, and this is where the deferral carries whatever that
     * policy needs: a channel name, the roles the defer site required, an amount,
     * a snapshot of the policy in force at deferral time. Subject to the same
     * plain-JSON rule as the exchange (`RC5042`).
     *
     * On the agent surface it is supplied by a tool handler, which means the
     * MODEL influenced it. Treat it as data the defer site chose, not as a fact
     * the framework vouches for.
     */
    readonly meta?: unknown;
    /**
     * Which call this record belongs to, when the deferring step mints one
     * credential per call.
     *
     * A batch of parallel tool calls shares one record (one deferral) while each
     * handler sends its own recipient a link. Only the call that actually won
     * the deferral may be resumed, so its identity is recorded here and every
     * credential carries the same value as its `sub` claim. A losing sibling's
     * recipient then takes `RC5055` rather than resuming a deferral that was never
     * theirs.
     *
     * Absent for an ordinary `.defer()`, where there is nothing to
     * disambiguate.
     */
    readonly callBinding?: string;
    /**
     * Opaque state owned by the deferring step. Absent for an ordinary step;
     * an agent step puts its messages thread and outstanding tool-call id
     * here. The store persists it verbatim and never reads into it, so it is
     * subject to the same JSON-data rule as the exchange.
     */
    readonly stepState?: unknown;
    /**
     * Binds an approval to the operation it authorized rather than to a
     * deferral id, so a receipt reads "this principal authorized this exact
     * operation". See {@link actionFingerprint}.
     */
    readonly actionFingerprint: string;
    readonly deferredAt: Date;
    /** When the sweeper will expire this deferral. Absent means no TTL. */
    readonly expiresAt?: Date;
    /**
     * When the outstanding delivery claim was taken, which is BEFORE the
     * notification: it is a claim timestamp, not proof of delivery. Set only
     * on a `waiting` record, cleared when a stale claim is released, and kept
     * on a settled one as the record of who got there first.
     *
     * Load-bearing rather than informational: a claimed record is not
     * resumable, because the claim holder owns the outcome. That is the
     * compare every transition out of `waiting` makes.
     */
    readonly claimedAt?: Date;
    readonly state: DeferralState;
    readonly waitingFor: DeferralWaitingFor;
    /** How it settled. Absent while {@link Deferral.state} is `waiting`. */
    readonly outcome?: DeferralOutcome;
    /** Cached result of execution two, for idempotent re-resume. */
    readonly continuation?: SerializedOutcome;
}
/**
 * A deferral as it is handed to {@link DeferralStore.create}.
 *
 * A record is born `waiting`, so the fields only a transition can produce
 * are not part of the input. Taking a full {@link Deferral} would let a
 * caller insert a record that is already settled, and every compare-and-swap
 * in the contract then refuses to move it: the exchange is deferred
 * permanently, with no error to notice.
 */
type NewDeferral = Omit<Deferral, DeferralTransitionField> & {
    readonly [K in DeferralTransitionField]?: never;
};
/**
 * The fields only a `mark*` transition may write.
 */
type DeferralTransitionField = "state" | "outcome" | "continuation" | "claimedAt";
/**
 * Details recorded when a resume wins the compare-and-swap.
 */
interface DeferralResumption {
    readonly at: Date;
    readonly by?: PrincipalRef;
}
/**
 * Result of a compare-and-swap on a deferral.
 *
 * `won` is the load-bearing field: it reports whether THIS caller performed
 * the transition. A resume arriving at the same moment the sweeper expires
 * the deferral produces exactly one `won: true`, and the loser reads
 * `deferral.outcome` to find out what happened instead.
 *
 * `deferral` is the record as it stands after the attempt, so a loser
 * does not need a second read to react. It is `undefined` only when the id
 * is unknown.
 */
interface DeferralCasResult {
    readonly won: boolean;
    readonly deferral: Deferral | undefined;
}
/**
 * What the startup scan reports at info level.
 */
interface PendingDeferralSummary {
    /** Deferrals still waiting. */
    readonly count: number;
    /** `deferredAt` of the oldest of them, absent when there are none. */
    readonly oldest?: Date;
}
/**
 * Whether a deferral can still be resumed: waiting, with no delivery claim
 * outstanding.
 *
 * The two-field condition every transition out of waiting compares against,
 * named once so the stores, the revival path and the sweeper cannot drift on
 * it. A claimed record is deliberately excluded even though it is still
 * waiting: the claim holder owns the outcome, and letting a resume in behind
 * it would produce two notifications for one event.
 */
declare function resumable(deferral: Deferral): boolean;
/**
 * Whether a delivery claim is outstanding on a waiting deferral, which is
 * what {@link DeferralStore.markExpired} and
 * {@link DeferralStore.markDenied} settle.
 */
declare function claimed(deferral: Deferral): deferral is Deferral & {
    readonly claimedAt: Date;
};
/**
 * Persistence contract for deferred exchanges.
 *
 * Two backends ship: {@link MemoryDeferralStore} for tests and ephemeral
 * use, and {@link SqliteDeferralStore} as the durable default wherever
 * the runtime allows. Postgres and redis are out of scope; the contract is
 * shaped so they can be added without touching call sites, which is why
 * every method is async and why the state transitions are compare-and-swap
 * rather than read-then-write.
 *
 * Implementations must treat the three `mark*` methods as atomic with
 * respect to each other. Single-node coordination is all that is required
 * today, but a read-then-write implementation cannot be made safe later
 * without a rewrite, and the atomic form costs nothing now.
 */
interface DeferralStore {
    /**
     * Persist a newly deferred exchange. Throws if `record.id` already exists:
     * a deferral id is minted per defer and a collision means a bug, not
     * a retry. The stored record is `waiting` and unclaimed; only the
     * transitions below move it.
     */
    create(record: NewDeferral): Promise<void>;
    /** Load a deferral by id. `undefined` when the id is unknown. */
    get(id: string): Promise<Deferral | undefined>;
    /**
     * Settle an unclaimed waiting deferral as `resumed`, recording who resumed
     * it and when. Exactly one concurrent caller wins.
     */
    markResumed(id: string, resumption: DeferralResumption): Promise<DeferralCasResult>;
    /**
     * Claim an unclaimed waiting deferral for delivery, recording when the
     * claim was taken. The record stays `waiting`, which is the point: a claim
     * is not an outcome. Winning it is the right to notify the route, and the
     * caller delivers the re-ask and then settles with
     * {@link DeferralStore.markExpired} or {@link DeferralStore.markDenied}. A
     * holder that dies mid-delivery is healed by
     * {@link DeferralStore.releaseClaims} rather than leaving the record
     * stuck.
     *
     * A released EXPIRY claim is overdue, so the next sweep redelivers it. A
     * released DENIAL claim is not, so its redelivery waits for the next
     * replay of the token, or for the deadline, whichever comes first; the
     * proactive nag is lost only for a record that has no deadline and is
     * never replayed, which is the pre-lease behaviour for every crash.
     */
    claimExpiry(id: string, at: Date): Promise<DeferralCasResult>;
    /**
     * Settle a claimed deferral as `expired`, stamping
     * {@link DeferralOutcome.at} at the write. `expiresAt` still says when the
     * deferral came due and `claimedAt` when its delivery was claimed; the
     * outcome's own timestamp is when the record actually stopped waiting,
     * which is what retention measures from.
     */
    markExpired(id: string): Promise<DeferralCasResult>;
    /**
     * Settle a claimed deferral as `denied`, stamping
     * {@link DeferralOutcome.at} at the write.
     * The claim-first shape applies to denial for the same reason as expiry:
     * a crash between the transition and the notification must heal by
     * redelivery, not strand the approver. Cancellation (#552) will claim
     * first too.
     */
    markDenied(id: string, reason?: string): Promise<DeferralCasResult>;
    /**
     * Release every delivery claim taken at or before `before` by clearing
     * {@link Deferral.claimedAt}, and report how many were released. The
     * records were and remain `waiting`; what changes is that they are
     * resumable and sweepable again.
     *
     * This is the healing half of the claim: a released record is past its
     * deadline, so the next ordinary sweep pass redelivers it. A crash after
     * delivery but before finalize therefore costs one duplicate escalation
     * after the lease elapses, which is the accepted at-least-once trade;
     * a crash before delivery costs nothing but the lease's delay.
     */
    releaseClaims(before: Date): Promise<number>;
    /**
     * Compare-and-swap the opaque {@link Deferral.stepState} slot of a
     * record that is STILL waiting and unclaimed, leaving every other field
     * alone.
     *
     * The one write that edits a waiting record in place rather than settling
     * it. Compaction is the motivating caller: an agent's deferred thread grows
     * past what the model will accept, and shrinking it has to happen while
     * the exchange stays deferred, because a resume that lands on an
     * unshrinkable thread has nowhere to go.
     *
     * Two races are closed by the same compare. `expected` is the
     * `stepStateFingerprint` of the state the caller read and rewrote, so two
     * compactions of the same record produce one winner and one `won: false`
     * holding the state that landed, instead of the second silently
     * discarding the first. And the swap only matches an unclaimed waiting
     * row, so a resume or a sweep that got there first wins outright: the compaction is
     * refused rather than rewriting the thread of a run that is already
     * executing its continuation.
     *
     * The store still never reads INTO the slot. Whether the replacement is a
     * usable thread is the owning tier's question, and `@routecraft/ai`
     * answers it before calling this.
     *
     * @param id - Deferral whose step state is being replaced
     * @param expected - Fingerprint of the step state the caller based its
     *   replacement on, from `stepStateFingerprint`
     * @param stepState - The replacement. Subject to the same plain-JSON rule
     *   as every other free-form slot (`RC5042`). `undefined` clears the slot
     *   on every backend.
     */
    replaceStepState(id: string, expected: string, stepState: unknown): Promise<DeferralCasResult>;
    /**
     * Cache the result of execution two so a duplicate resume can reply
     * without re-running the continuation. Silently ignores an unknown id: the
     * cache is a convenience, and losing the race to a sweep must not turn
     * into a second failure on the way out.
     *
     * Unconditional by design: only the caller that won `markResumed` ever
     * writes a continuation, so there is no competing writer for this row and
     * a compare would defend nothing.
     */
    recordContinuation(id: string, continuation: SerializedOutcome): Promise<void>;
    /**
     * Deferrals still waiting and unclaimed whose `expiresAt` is at or
     * before `now`, ordered by `(expiresAt ASC, id ASC)` and starting
     * strictly after `after` when one is given. `limit` bounds one page so a
     * backlog accumulated while the process was down does not produce an
     * unbounded batch.
     *
     * The ordering is a strict total order within a backend, which is what
     * makes the cursor sound; it is not guaranteed byte-identical across
     * backends for non-ASCII ids, so a cursor must only ever be replayed
     * against the store that produced it.
     *
     * A non-positive or non-integer `limit`, or a malformed `after`, is a
     * caller error and throws rather than being interpreted.
     */
    findExpired(now: Date, limit: number, after?: ExpiredScanCursor): Promise<Deferral[]>;
    /** Count and oldest `deferredAt` across deferrals still waiting. */
    pending(): Promise<PendingDeferralSummary>;
    /**
     * One page of deferrals as a management surface presents them, ordered
     * `(deferredAt ASC, id ASC)` and starting strictly after
     * {@link DeferralListQuery.after} when one is given.
     *
     * Ordered by time rather than by id because a deferral id is
     * `{exchangeId}#{sequence}` over a uuid, so id order is arbitrary and a
     * listing in it answers no question anyone asks. Oldest first is the
     * question: what has been waiting longest.
     *
     * A projection rather than the records, so the serialized exchange, the
     * step state and the resume-payload schema never enter the read path at
     * all. The listing must not show them, and a store that returned whole
     * records would page a hundred thousand exchange bodies through memory
     * on the way to dropping them.
     *
     * The ordering is a strict total order within a backend, and as with
     * {@link DeferralStore.findExpired} it is not guaranteed byte-identical
     * across backends for non-ASCII ids, so a cursor is only ever replayed
     * against the store that produced it.
     *
     * A non-positive or non-integer `limit` is a caller error and throws
     * rather than being interpreted.
     */
    list(query: DeferralListQuery): Promise<DeferralSummary[]>;
    /**
     * Records settled as `resumed` whose continuation never landed, oldest
     * first.
     *
     * This is crash residue. A resume wins the compare-and-swap out of
     * `waiting` BEFORE running the continuation and caches the result after,
     * so a record in this state means the process died between the two.
     * The approval is spent, the work half ran, and nothing will ever revisit
     * it: it is invisible to {@link DeferralStore.findExpired}, which only
     * looks at waiting records.
     *
     * Re-running a
     * continuation whose side effects may have half happened needs a lease on
     * the resumed outcome and idempotent continuations, which is the
     * admission-and-idempotency work tracked separately. What this method is
     * for is the boot summary after an outage, which is the first moment
     * anyone could learn such a record exists.
     *
     * The asymmetry with the delivery claim is deliberate: expiry
     * NOTIFICATIONS heal by redelivery because re-sending a nag is safe,
     * while this residue is a half-run CONTINUATION and is only ever
     * reported.
     *
     * @param limit - Cap on records returned. Omit for all of them.
     */
    resumedWithoutContinuation(limit?: number): Promise<Deferral[]>;
    /**
     * Delete settled deferrals whose {@link DeferralOutcome.at} is before
     * `before`, and report how many went.
     *
     * A settled record holds a full serialized exchange body plus its cached
     * continuation, and nothing else ever removes one. Without a
     * retention path a long-running process accumulates every exchange that
     * ever deferred: on disk under sqlite, and on the heap under the
     * in-memory backend, which is also the automatic fallback for a Node
     * install without a driver. Waiting records are never touched, whatever
     * their age; expiring them is the sweeper's job and goes through
     * {@link DeferralStore.markExpired}.
     *
     * The cutoff is the outcome's timestamp, not `deferredAt`: retention
     * promises how long a SETTLED record is kept, and measuring from the
     * deferral would purge a record that waited 89 days and settled on day 89
     * one day after it settled.
     */
    purgeSettled(before: Date): Promise<number>;
    /** Release backend resources. Idempotent. */
    close(): Promise<void>;
}

/**
 * Environment variable naming where deferred exchanges are persisted. Either
 * a file path or the literal `memory`. Overridden by an explicit
 * `deferral: { store }`.
 */
declare const DEFERRAL_STORE_ENV = "ROUTECRAFT_DEFERRAL_STORE";

declare module "@routecraft/routecraft" {
    interface CraftConfig {
        /**
         * Durable defer and resume. Set it when any route can reach a
         * `.defer()`; leaving it unset is fine for a context that never
         * defers.
         */
        deferral?: DeferralConfig;
    }
}
/**
 * Where deferred exchanges live.
 *
 * - A path (or `{ path }`) opens the sqlite backend at that location. This
 *   is the value a container deployment sets to a mounted volume, which is
 *   the whole point of it being configurable.
 * - `"memory"` opts into the in-process backend explicitly, accepting that
 *   deferred exchanges die with the process.
 * - A {@link DeferralStore} instance plugs in a backend of your own
 *   (postgres, redis) without waiting for core to ship one.
 */
type DeferralStoreConfig = string | {
    path: string;
} | "memory" | DeferralStore;
/**
 * Deferral configuration on `defineConfig`.
 */
interface DeferralConfig {
    /**
     * Where deferred exchanges are persisted. Defaults to the sqlite backend at
     * {@link DEFAULT_DEFERRAL_DB_PATH}, or to whatever
     * {@link DEFERRAL_STORE_ENV} names.
     */
    store?: DeferralStoreConfig;
    /**
     * HMAC secret for signing resume tokens.
     *
     * Prefer the {@link DEFERRAL_SECRET_ENV} environment variable: a secret
     * in a config file is a secret in version control. This field exists for
     * deployments that pull secrets from a manager at boot and hand them to
     * `defineConfig` in code.
     */
    secret?: string;
    /**
     * How long a deferral stays resumable when `.defer()` names no `ttl`.
     *
     * Defaults to {@link DEFAULT_DEFERRAL_TTL}. Set `"never"` to opt a
     * context out of default expiry entirely, which means an unresumed
     * deferral is kept until something else retires it.
     */
    defaultTtl?: Duration | "never";
    /**
     * How often the sweeper looks for overdue deferrals.
     *
     * Defaults to {@link DEFAULT_SWEEP_INTERVAL}. TTLs are measured in hours,
     * so sub-minute precision buys nothing; the knob exists for tests and for
     * deployments that want expiry noticed sooner.
     */
    sweepInterval?: Duration;
    /**
     * How long an expiry-delivery claim is honoured before the sweeper
     * releases it for redelivery.
     *
     * Defaults to {@link DEFAULT_EXPIRY_LEASE}. Only a crash mid-delivery
     * ever spends this; keep it comfortably longer than the slowest `.error()`
     * handler, because a lease shorter than a slow handler would make one
     * healthy process double-deliver by itself.
     */
    expiryLease?: Duration;
    /**
     * How long settled deferrals (resumed, expired, denied) are kept before
     * the sweeper purges them.
     *
     * Defaults to {@link DEFAULT_DEFERRAL_RETENTION}. Set `"never"` to keep
     * everything, which is the audit-trail configuration; the store then
     * grows with every exchange that ever deferred.
     */
    retention?: Duration | "never";
}
/**
 * The resolved per-context deferral runtime: one store, one signer.
 */
interface DeferralRuntime {
    readonly store: DeferralStore;
    readonly signer: ResumeTokenSigner;
    /**
     * What the store resolved to, for the startup log line. `custom` is a
     * store the caller supplied; reporting it as `sqlite` would mislead
     * exactly the operators who configured a backend deliberately, on the one
     * field that answers "is this deployment durable, and against what".
     */
    readonly backend: "sqlite" | "memory" | "custom";
    /**
     * False when the caller supplied the store, in which case they own its
     * lifecycle and the plugin must not close it on teardown. A user-supplied
     * backend typically wraps a pool shared with the rest of the application,
     * or is reused across two contexts in one process (which is how a
     * restart-durability test is written).
     */
    readonly ownsStore: boolean;
    /**
     * Milliseconds a deferral stays resumable when `.defer()` names no
     * `ttl`. Undefined when the context opted out with `defaultTtl: "never"`,
     * which is the only way to defer something with no deadline at all.
     */
    readonly defaultTtlMs?: number;
    /**
     * Milliseconds between sweeps. Resolved here rather than in the plugin's
     * `start()` hook so a malformed duration fails while the context is still
     * being built, which is the rule the rest of this config already follows.
     */
    readonly sweepIntervalMs: number;
    /** Milliseconds an expiry-delivery claim is honoured before redelivery. */
    readonly expiryLeaseMs: number;
    /** Milliseconds settled records are kept. Undefined means keep forever. */
    readonly retentionMs?: number;
}
/**
 * Plugin form of {@link createDeferralRuntime}, wired to the `deferral`
 * config key. Resolves the runtime during `initPlugins()` so a missing
 * signing secret fails at startup, and closes the store during teardown,
 * but only a store it opened itself.
 */
declare function deferralPlugin(config?: DeferralConfig): CraftPlugin;

/**
 * Context-store key holding the resolved deferral runtime.
 *
 * Exported so the executor, the resume path, and the sweeper reach one
 * resolved store and one signer per context rather than each building their
 * own.
 *
 * It lives in this leaf module rather than next to
 * {@link createDeferralRuntime} because `exchange.ts` reads the key to
 * build the `ex.deferral` affordance, and importing `config.ts` from
 * there would pull the store backends (and, through them, the context) into
 * a runtime cycle rooted at the exchange. The type-only import above is
 * erased, so this module has no runtime dependencies at all.
 */
declare const DEFERRAL_RUNTIME: "routecraft.deferral.runtime";
declare module "@routecraft/routecraft" {
    interface StoreRegistry {
        [DEFERRAL_RUNTIME]: DeferralRuntime;
    }
}

/**
 * Store key for runner-provided argv tokens.
 *
 * Set by `craft run` (or any runner) before `context.start()` so that
 * adapters can read the remaining CLI arguments without coupling to a
 * specific runner package.
 */
declare const RUNNER_ARGV: unique symbol;
/**
 * Base store registry that can be extended by adapters
 *
 * @example
 * ```typescript
 * // Extend the store registry with channel adapter types
 * declare module "@routecraft/routecraft" {
 *   interface StoreRegistry {
 *     "routecraft.adapter.channel.store": Map<string, import("./adapters/channel.ts").MessageChannel>;
 *     "routecraft.adapter.channel.config": Partial<ChannelAdapterOptions>;
 *   }
 * }
 * ```
 */
interface StoreRegistry {
    [key: `${string}.${string}.${string}`]: unknown;
    [RUNNER_ARGV]: string[];
    [RC_ADAPTER_OVERRIDES]: AdapterOverride[];
}
/**
 * Options with merged configuration support.
 * This type is used for adapters that support both direct options and
 * options that can be merged with context configuration.
 */
type MergedOptions<T> = {
    /** Direct options for configuration */
    options: Partial<T>;
    /**
     * Function to merge options with context configuration
     * @param context The CraftContext instance
     * @returns Merged options
     */
    mergedOptions(context: CraftContext): T;
};
/**
 * A plugin configures the context and may own work for as long as it runs.
 *
 * Three phases, each answering a different question:
 *
 * - `apply(ctx)` wires the context, before routes are registered
 *   (`initPlugins()`). Nothing is running yet.
 * - `start(ctx)` begins work, after every route has started. Optional.
 * - `teardown(ctx)` releases whatever the other two acquired, when the
 *   context stops and routes have drained. Optional.
 *
 * The split matters for anything with a lifetime. A plugin that opens a
 * handle does it in `apply()`; a plugin that starts a timer or drives routes
 * does it in `start()`, because at `apply()` time there are no routes to
 * drive. Either way `teardown()` is what releases it.
 *
 * Plugins needing neither can omit both; use `ctx.registerTeardown()` from
 * `apply()` for one-off cleanup callbacks.
 */
interface CraftPlugin {
    /**
     * Stable identifier for the plugin, surfaced as `pluginId` on
     * `plugin:*` event payloads and in logs. Falls back to the plugin's
     * constructor name (or `plugin-<index>`) when omitted.
     */
    name?: string;
    /**
     * RESERVED. Names of plugins this plugin depends on. Not enforced yet:
     * declaring it today has no effect, but the key is reserved so a
     * future dependency-ordered initialisation can use it without a
     * breaking change.
     */
    dependsOn?: string[];
    /** Keep the context running after all routes complete until `stop()` is called. */
    keepsAlive?: boolean;
    apply(ctx: CraftContext): void | Promise<void>;
    /**
     * Called once per context start, after every route has been started, in
     * plugin registration order. Awaited. Optional.
     *
     * This is where a plugin owning a background task belongs, because
     * `apply()` runs at build time when no route is running yet. A plugin
     * that starts something here MUST stop it in {@link CraftPlugin.teardown}:
     * a live interval keeps the process alive with no visible cause.
     *
     * A throw fails `context.start()`. The context then shuts down (routes
     * aborted and drained, every plugin torn down in reverse order) and the
     * original error is rethrown unchanged, so a plugin that fails to start
     * cannot leave a half-running context behind.
     */
    start?(ctx: CraftContext): void | Promise<void>;
    /**
     * Called when the context stops, after routes have drained, and when a
     * build or a start failed partway. Optional.
     *
     * The second argument says which of those happened, so a plugin never has
     * to infer it from its own state. Ignore it and the hook behaves exactly
     * as it did when teardown only ran on a fully started context; read it
     * when releasing depends on how far the context got.
     */
    teardown?(ctx: CraftContext, info: TeardownInfo): void | Promise<void>;
}
/**
 * What the context managed to do before this teardown, handed to every
 * {@link CraftPlugin.teardown}.
 *
 * The distinction exists because teardown now runs on three different
 * shapes of context: one that started and is stopping, one whose build
 * failed with only some plugins applied, and one whose start failed with
 * only some plugins started. A plugin that closes what `apply()` opened
 * needs none of this; a plugin that stops what `start()` began must not be
 * told to stop something it never began.
 */
interface TeardownInfo {
    /**
     * This is not a fully started context. Either it never started (a build
     * that failed partway, or an embedder that built and then stopped without
     * ever calling `start()`) or a `start()` hook threw. Routes may not be
     * registered and later plugins may never have applied, so state a plugin
     * would expect a running context to hold may be missing.
     */
    partial: boolean;
    /**
     * THIS plugin's own `start()` hook ran to completion. Always false for a
     * plugin with no `start()` hook, and false during a build-failure unwind,
     * where nothing started.
     */
    started: boolean;
}
/**
 * Configuration options for creating a CraftContext.
 *
 * Declared as an `interface` so ecosystem packages can extend it via
 * declaration merging. Pair an augmentation with `registerConfigApplier`
 * to promote an ecosystem capability to a first-class config key.
 *
 * @example
 * ```typescript
 * declare module "@routecraft/routecraft" {
 *   interface CraftConfig {
 *     myCapability?: MyCapabilityOptions;
 *   }
 * }
 * ```
 */
interface CraftConfig {
    /**
     * Service / application name for this context. Emitted on every log line as
     * `service.name` (the OpenTelemetry semantic convention), so log aggregators
     * that map OTel resource attributes (e.g. BetterStack `resources.service.name`)
     * can identify the originating app. When omitted, no `service.name` field is
     * added to logs.
     */
    name?: string;
    /** Initial values for the context store */
    store?: Map<keyof StoreRegistry, StoreRegistry[keyof StoreRegistry]>;
    /** Event handlers to register on context creation */
    on?: Partial<Record<EventName, EventHandler<EventName> | EventHandler<EventName>[]>>;
    /** One-time event handlers to register on context creation (fire once, then auto-unsubscribe) */
    once?: Partial<Record<EventName, EventHandler<EventName> | EventHandler<EventName>[]>>;
    /** Plugins to run before routes are registered (call initPlugins() then registerRoutes) */
    plugins?: CraftPlugin[];
    /** How long a graceful shutdown may drain before it is forced. */
    shutdown?: ShutdownConfig;
}
/**
 * Bounds on {@link CraftContext.stop}.
 *
 * Shutdown behaviour is a property of the app, not of one invocation, which
 * is why this is config rather than a CLI flag: the same bound applies to a
 * signal, to `craft start --once`, and to an embedder calling `stop()`.
 */
interface ShutdownConfig {
    /**
     * How long stage one may drain in-flight exchanges before stage two is
     * forced. Defaults to {@link DEFAULT_SHUTDOWN_TIMEOUT_MS}.
     *
     * Set it BELOW the platform's own kill timer (Kubernetes
     * `terminationGracePeriodSeconds` and friends) so the process's policy
     * decides the outcome rather than the platform's: past that timer the
     * platform sends SIGKILL and whatever stage two was meant to do is lost.
     */
    timeout?: Duration;
}
/**
 * How long a graceful shutdown drains before it is forced. Thirty seconds
 * because it sits under the common platform defaults (Kubernetes ships 30s
 * itself, and operators who raise it raise this with it) while being long
 * enough that ordinary in-flight work finishes inside it.
 */
declare const DEFAULT_SHUTDOWN_TIMEOUT_MS = 30000;
/**
 * What a completed {@link CraftContext.stop} reports.
 *
 * Returned because it is an answer the caller acts on: `shutdownHandler`
 * maps it to an exit code, and `craft start --once` reports a forced stop as
 * a failure. The same pair also rides on `context:stopped`, because counting
 * forced shutdowns is observability and an exit code is not something an
 * in-process subscriber can read.
 */
interface ShutdownOutcome {
    /**
     * Stage one did not finish inside the deadline, so in-flight execution was
     * abandoned. The process should exit non-zero.
     */
    forced: boolean;
    /**
     * Route ids that still had work in flight when the deadline hit. Empty on
     * a clean stop, so the shape does not change between the two arms.
     */
    pending: string[];
}
/**
 * The main context for running and managing routes.
 *
 * CraftContext is the central runtime environment that:
 * - Manages the lifecycle of routes
 * - Provides a storage system for adapters
 * - Handles startup and shutdown of the application
 *
 * @example
 * ```typescript
 * // Create a context with routes and event handlers
 * const context = new CraftContext({
 *   on: {
 *     'context:starting': async () => {
 *       console.log('Starting application');
 *     },
 *     'context:stopping': async () => {
 *       console.log('Shutting down application');
 *     }
 *   }
 * });
 *
 * // Register routes
 * context.registerRoutes(myRoute1, myRoute2);
 *
 * // Start processing routes
 * await context.start();
 *
 * // Later, stop all routes
 * await context.stop();
 * ```
 */
declare class CraftContext {
    /** Unique identifier for this context instance */
    readonly contextId: string;
    /** Service / application name, surfaced on logs as `service.name`. */
    readonly name?: string;
    /** Routes registered with this context */
    private routes;
    /** Abort controllers for each route */
    private controllers;
    /**
     * Owns every route's `.enabled()` state, its refresh cadence, and the
     * transitions between them. Built eagerly (it is a few maps) so the
     * capability filter and ops can read it whether or not any route
     * declares a predicate.
     */
    private readonly enablement;
    /** Storage for adapter configuration and state */
    private store;
    /** Logger for this context (pino child logger) */
    readonly logger: ReturnType<typeof logger.child>;
    /** Event bus backing on/once/emit (see event-bus.ts) */
    private readonly events;
    /** Plugins from config, run by initPlugins() before routes are registered */
    private readonly plugins;
    /** Guards initPlugins() so start() can call it idempotently */
    private pluginsInitialized;
    /**
     * Indices of plugins whose `apply()` returned. Teardown walks this rather
     * than the whole plugin list: a build that failed at plugin 3 must not
     * tear down plugin 4, which never ran.
     */
    private readonly appliedPlugins;
    /** Indices of plugins whose `start()` hook returned. */
    private readonly startedPlugins;
    /** Latched once `start()` has fully completed, for {@link TeardownInfo.partial}. */
    private startCompleted;
    /** How long stage one of shutdown may drain; see {@link ShutdownConfig}. */
    private readonly shutdownTimeoutMs;
    /** Teardown callbacks registered by plugins; run during stop() before context:stopped */
    private readonly teardownCallbacks;
    /** Cached shutdown promise so concurrent stop() callers all await the same teardown */
    private shutdownPromise;
    /** Backing gate for {@link CraftContext.whenStarted}. */
    private startedGate;
    /** The in-flight start, so concurrent `start()` calls join one boot. */
    private startInFlight;
    /**
     * The plugin lifecycle hook currently awaiting, so a `stop()` that lands
     * mid-boot can let it finish before teardown runs.
     *
     * Scoped to `apply()` and `start()` alone, never `run()`: for an
     * indefinite route `run()` resolves only once the context stops, so
     * waiting on it would deadlock the shutdown this ordering exists to serve.
     */
    private pluginHookInFlight;
    /** Latched by `stop()`. A stopped context refuses to start again. */
    private hasStopped;
    /**
     * Create a new CraftContext instance.
     *
     * @param config Optional configuration for the context
     */
    constructor(config?: CraftConfig);
    /**
     * Generate a plugin identifier from the plugin's constructor name or index.
     * @param plugin The plugin instance
     * @param index The plugin's index in the plugins array
     * @returns A string identifier for the plugin
     */
    private getPluginId;
    /**
     * Run plugins from config. Called by the builder's `build()` (and by
     * `start()` as an idempotent fallback) before routes are registered so
     * plugins can set up state or dynamically add routes.
     *
     * Fails fast: on first plugin error, logs, emits `error`, and rethrows.
     *
     * @throws Rethrows if any plugin's `apply(ctx)` throws
     * @internal Public for the builder and tests; not part of the supported
     *   embedding surface. The context initialises plugins itself.
     */
    initPlugins(): Promise<void>;
    /**
     * Resolves once the context is fully started: every route has emitted
     * `route:started` AND every plugin `start()` hook has resolved.
     *
     * `context.start()` cannot answer this, because it does not resolve until
     * the routes complete, and an http or cron route completes at shutdown.
     * Waiting on `route:started` alone answers only two thirds of the
     * lifecycle, which is why anything needing a started context (a test
     * harness, a readiness probe) waits here instead.
     *
     * A hook that performs bounded startup work is awaited by this, on
     * purpose: the deferral sweeper's downtime scan has RUN by the time
     * this resolves, so overdue expiries reach their routes before new
     * traffic does. Rejects with the error that refused the start, which is a
     * plugin `start()` hook or the context's own config. A single route that
     * fails to come up is NOT observable here: `start()` keeps the remaining
     * routes running by design, so a probe that must know a specific route is
     * serving watches `route:started` for it.
     *
     * A context starts once (`start()` after `stop()` refuses with RC1004),
     * so this settles exactly once and keeps reporting that outcome.
     */
    whenStarted(): Promise<void>;
    /**
     * The gate behind {@link CraftContext.whenStarted}, created on first
     * use by either side.
     *
     * Lazy because most contexts never ask, and shared because `start()` has
     * to settle the same promise a caller may already be holding.
     *
     * @internal
     */
    private ensureStartedGate;
    /**
     * Resolve once every route has signalled readiness, or stopped trying.
     *
     * `Promise.allSettled` over the route starts cannot answer this: each
     * mapped function runs only as far as its first `await`, so it returns
     * when every route has ENTERED `start()`, not when its sources are
     * listening. A plugin whose `start()` hook talks to a route would race
     * the source's subscribe, and a readiness probe would report a context
     * ready before its HTTP port was bound.
     *
     * A route that fails or completes counts as settled rather than ready.
     * One failing route does not fail the context (`start()` keeps the others
     * running by design), so readiness cannot report it either: what this
     * waits for is that no route is still coming up, not that all of them did.
     *
     * The wait is bounded because readiness is not something every source
     * signals. Everything `.from()` normalizes signals it (the iterable path
     * from its loop, a bare callable on invocation), but a hand-written
     * `Source` adapter that never calls `ready()` and never emits would
     * otherwise hold the whole context down forever. The bound is a guard
     * against that, not a deadline anything healthy approaches.
     *
     * @internal
     */
    private awaitRoutesStarted;
    /**
     * Log one line saying whether the boot came up, after the readiness gate
     * settles.
     *
     * `whenStarted()` deliberately cannot report a single route failing to
     * bind, because partial availability is the design: one route failing
     * does not fail the context. That leaves an operator watching a boot with
     * no single answer to "did everything come up", visible only to whoever
     * subscribed to `route:started` at the right moment. This is that answer,
     * and nothing more: no new events, no semantics change.
     */
    private logBootSummary;
    /**
     * Run every plugin's optional `start()`, in registration order.
     *
     * Separate from {@link CraftContext.initPlugins} because the two phases
     * answer different questions. `apply()` wires the context and runs at
     * build time; `start()` begins work and needs the routes running. The
     * deferral sweeper is the first consumer: it re-enters a route's error
     * channel when a deferred exchange expires, which is not something that can
     * be done against a route that has not started.
     *
     * A throw propagates to `context.start()`, which shuts the context down
     * before rethrowing it unchanged. Unwinding a partially started context
     * is deliberately the existing shutdown path rather than a second
     * mechanism, so a plugin's stop logic has one home; a failed build
     * unwinds through the same walk via {@link CraftContext.unwindFailedBuild},
     * so which phase failed does not change where cleanup lives.
     */
    private startPlugins;
    /**
     * Run one plugin lifecycle hook, publishing it as the in-flight hook for
     * as long as it runs.
     *
     * The published promise covers the hook and the bookkeeping that records
     * it, so a shutdown waiting on it sees a plugin either fully applied or
     * fully absent, never half-recorded.
     *
     * @param hook The hook call together with the state it updates on success
     */
    private runLifecycleHook;
    /**
     * Wait for a plugin lifecycle hook still in flight before teardown runs.
     *
     * Waiting rather than interrupting, and unbounded, for the reason plugin
     * teardown is unbounded: a hook cut off partway keeps whatever it acquired
     * after its last await point, and no teardown can release what the plugin
     * had not yet handed over. Interrupting instead would oblige every plugin
     * author to write `start()` so it tolerates teardown-before-completion, a
     * contract paid for by every correct plugin to contain a defective one.
     * A hook that never settles is that defective plugin, not a shutdown
     * policy question.
     *
     * The hook's own rejection belongs to whoever invoked it, which is why
     * only its settling is observed here.
     */
    private settlePluginHook;
    /**
     * Refuse to start when a route can reach a `.defer()` and nothing
     * configured where deferred exchanges go.
     *
     * Deliberately not auto-provisioned. The deferral runtime decides
     * whether this deployment survives a restart and whether resume tokens
     * outlive the process, and defaulting it silently would hand a route that
     * promises durability an in-memory store nobody chose. Failing at startup
     * costs one config line; failing on the first large payout costs the
     * payout.
     *
     * Routes that never touch deferral carry neither marker, so a context
     * without the feature pays nothing here.
     *
     * @throws RC5052 when a deferrable route has no deferral runtime
     */
    private assertDeferralConfigured;
    /**
     * Register a teardown callback to run when the context stops. Plugins use this
     * to release resources (e.g. caches, native handles) after routes have drained.
     * Callbacks run in REVERSE registration order (LIFO, mirroring plugin
     * teardown) before `context:stopped` is emitted, so resources unwind in
     * the opposite order they were acquired.
     *
     * @param fn - Callback (sync or async) to run during stop()
     */
    registerTeardown(fn: () => void | Promise<void>): void;
    /**
     * Subscribe to lifecycle and system events.
     *
     * Takes an exact event name, or `"*"` for every event. Patterns such as
     * `route:*` are refused with RC2001: event names are a fixed set and the
     * route id lives in the payload, so scope to one route with
     * `forRoute(routeId, handler)`. The `event()` source still accepts patterns.
     *
     * @param event - Exact event name (e.g. `route:started`) or `"*"`
     * @param handler - Callback receiving `{ ts, contextId, details }`
     * @returns Unsubscribe function (call to remove the handler)
     *
     * @example
     * ```typescript
     * // Subscribe to specific event
     * const unsubscribe = ctx.on('route:started', ({ details }) => {
     *   console.log('Route started:', details.route.definition.id);
     * });
     *
     * // One route's failed exchanges
     * ctx.on('route:exchange:failed', forRoute('orders', ({ details }) => {
     *   console.log('Order failed:', details.error);
     * }));
     *
     * // Every event
     * ctx.on('*', ({ details }) => {
     *   console.log('Event:', details);
     * });
     *
     * // later: unsubscribe();
     * ```
     */
    on<K extends EventName>(event: K, handler: EventHandler<K>): () => void;
    on(event: "*", handler: EventHandler<EventName>): () => void;
    /**
     * Subscribe to an event for a single occurrence. The handler is automatically
     * removed after the first time the event is emitted.
     *
     * Accepts the same names as `on()`: an exact event name, or `"*"`.
     *
     * @param event - Exact event name or `"*"`
     * @param handler - Callback receiving `{ ts, contextId, details }`
     * @returns Unsubscribe function (call to remove the handler before it fires)
     *
     * @example
     * ```typescript
     * // Wait for context to start
     * ctx.once('context:started', () => {
     *   console.log('Context started!');
     * });
     *
     * // Wait for the first route to start
     * ctx.once('route:started', ({ details }) => {
     *   console.log('First route started:', details.routeId);
     * });
     * ```
     */
    once<K extends EventName>(event: K, handler: EventHandler<K>): () => void;
    once(event: "*", handler: EventHandler<EventName>): () => void;
    /**
     * Emit an event to registered handlers.
     *
     * @param event - Event name
     * @param details - Event-specific payload (merged into `EventPayload.details`)
     * @internal Public for use by routes/adapters; prefer subscribing via on()
     */
    emit<K extends EventName>(event: K, details: EventPayload<K>["details"]): void;
    /**
     * Register routes with this context.
     *
     * @param definitions Route definitions to register
     * @throws {RoutecraftError} If there are duplicate route IDs or invalid route definitions
     *
     * @example
     * ```typescript
     * // Register a single route
     * context.registerRoutes(myRoute);
     *
     * // Register multiple routes
     * context.registerRoutes(route1, route2, route3);
     * ```
     */
    registerRoutes(...definitions: RouteDefinition[]): void;
    /**
     * Get all routes registered with this context.
     *
     * @returns A copy of the route list. Mutating the returned array does
     *   not affect the context; routes are managed via `registerRoutes()`.
     */
    getRoutes(): Route[];
    /**
     * List the discoverable capabilities registered in this context: every
     * direct endpoint together with its route's discovery metadata. Agents
     * and embedding code use this instead of reaching into the (internal)
     * direct registry; dispatch into a capability with
     * `CraftClient.sendDirect(capability.endpoint, body)`.
     *
     * @returns A fresh array of capability snapshots. Endpoints are the raw
     *   ids as passed to `.id(...)`; mutating the result does not affect
     *   the registry.
     */
    capabilities(): Capability[];
    /**
     * Get a value from the context store.
     *
     * @template K Store key type
     * @param key The store key to retrieve
     * @returns The stored value or undefined if not found
     *
     * @example
     * ```typescript
     * // Get channel store
     * const channelStore = context.getStore('routecraft.adapter.channel.store');
     * ```
     */
    getStore<K extends keyof StoreRegistry>(key: K): StoreRegistry[K] | undefined;
    /**
     * Set a value in the context store.
     *
     * @template K Store key type
     * @param key The store key
     * @param value The value to store
     *
     * @example
     * ```typescript
     * // Set channel store
     * context.setStore('routecraft.adapter.channel.store', new Map());
     * ```
     */
    setStore<K extends keyof StoreRegistry>(key: K, value: StoreRegistry[K]): void;
    /**
     * Find a route by its ID.
     *
     * @param id The route ID to find
     * @returns The matching route or undefined if not found
     */
    getRouteById(id: string): Route | undefined;
    /**
     * Start all routes registered with this context.
     *
     * Emits `context:starting` and `context:started`, then starts all routes in parallel.
     * If all routes complete (e.g. finite sources), the context automatically stops.
     * If any route fails to start, the error is logged, emitted as `error`, and rethrown.
     *
     * **Context Lifecycle Events:**
     * - `context:starting` - Context initialization begins
     * - `context:started` - Context initialized (routes may not be started yet)
     * - `context:stopping` - Context shutdown begins
     * - `context:stopped` - Context shutdown complete
     *
     * **Note:** `context:started` fires after context initialization but BEFORE
     * individual routes start. To track route readiness, subscribe to
     * `route:started` or `route:stopping` events instead.
     * To filter by specific route, inspect details.route.definition.id in the handler.
     *
     * @returns A promise that resolves when all routes have started (or when context stops)
     * @throws If any route fails to start
     *
     * @example
     * ```typescript
     * try {
     *   await context.start();
     *   console.log('All routes started successfully');
     * } catch (error) {
     *   console.error('Failed to start routes:', error);
     * }
     * ```
     */
    start(): Promise<void>;
    private run;
    /**
     * Wait for all in-flight route handlers (and their background tasks) to complete.
     * Does not stop sources; use stop() for full shutdown.
     *
     * @returns A promise that resolves when all routes have drained
     */
    drain(): Promise<void>;
    /**
     * Stop all routes and shut down the context.
     *
     * This will:
     * 1. Abort all route controllers (stops sources)
     * 2. Drain all routes (wait for in-flight handlers and their background tasks)
     *
     * @returns A promise that resolves when all shutdown operations complete
     *
     * @example
     * ```typescript
     * // Handle shutdown signals
     * process.on('SIGINT', async () => {
     *   console.log('Shutting down...');
     *   await context.stop();
     *   process.exit(0);
     * });
     * ```
     */
    stop(): Promise<ShutdownOutcome>;
    /**
     * Tear down every plugin that applied, in reverse application order, then
     * the registered teardown callbacks.
     *
     * One walk serves all three exits: an ordinary shutdown, a start that
     * failed partway, and a build that failed partway. They differ only in
     * what {@link TeardownInfo} reports, which is why they are not three
     * mechanisms.
     *
     * Only APPLIED plugins are torn down. A build that failed at plugin 3
     * leaves plugin 4 never having run, and calling its teardown would ask it
     * to release something it never acquired.
     *
     * Failure-tolerant throughout: a throwing teardown is logged and the
     * remaining teardowns still run, because the caller's original error is
     * what the operator needs and one plugin's cleanup must not strand
     * another's.
     *
     * @param partial - The context never finished starting.
     */
    private teardownPlugins;
    /**
     * Release everything a failed `build()` acquired, then let the caller
     * rethrow the original error.
     *
     * `build()` never returns a context when it fails, so the caller has no
     * handle to run teardown against: whatever an `apply()` opened (a database
     * handle, a socket, an interval) is unreachable and stays open. Under a
     * supervisor that retries boot, one handle leaks per attempt, and with
     * SQLite the held handle also keeps the file locked, so a transient boot
     * failure becomes a permanent one whose error names lock contention rather
     * than the real cause.
     *
     * @internal Called by `ContextBuilder.build()` on the failure path.
     */
    unwindFailedBuild(): Promise<void>;
    private performShutdown;
    /**
     * Wait for ONE route to drain, bounded by the route's own grace or, when
     * it declared none, by the same `shutdown.timeout` the whole-context
     * shutdown uses.
     *
     * Enablement's disable transition is the caller: taking a route out of
     * service is a per-route shutdown, so it defaults to the same
     * operator-facing knob rather than a second timeout nobody knows to look
     * for. A route that declared `.enabled({ drainGrace })` overrides it,
     * because the author is the one who knows what this pipeline's in-flight
     * work costs.
     *
     * @param graceMs - Milliseconds to allow; `undefined` for the context
     *   default; `null` to wait indefinitely and never force.
     * @returns True when the route drained; false when the deadline elapsed
     *   first and the caller must force it.
     */
    private drainRouteWithin;
    /**
     * Re-arm a disabled route under a fresh controller and start it.
     *
     * The controller is minted HERE rather than inside the route so this map
     * and the route never disagree about which controller a shutdown aborts:
     * a route holding one controller while `controllers` held the previous,
     * latched one would make `stop()` a silent no-op for that route.
     */
    private restartRoute;
    /**
     * Re-evaluate enablement predicates on demand and apply any transitions.
     *
     * The internal control surface behind the operator loop the deferred
     * `/ops` re-evaluate endpoint will expose: set the secret, ask for a
     * re-check, and a route whose predicate now passes starts without a
     * process restart. The endpoint is wiring on top of this, not a redesign
     * of it.
     *
     * @param routeId - Re-evaluate only this route. Omitted re-evaluates
     *   every route that declared a predicate.
     * @returns Each re-evaluated route's resulting state, by route id.
     */
    reevaluateEnablement(routeId?: string): Promise<ReadonlyMap<string, EnablementState>>;
    /**
     * Whether a route is currently serving, as far as `.enabled()` is
     * concerned. True for a route that never declared a predicate.
     */
    isRouteEnabled(routeId: string): boolean;
    /**
     * Every route currently disabled by its predicate, mapped to the reason.
     *
     * Read by the ops surface, which reports a disabled route distinctly from
     * a failed one: a deliberate configuration state is not an open circuit
     * and must not degrade the aggregate.
     */
    disabledRoutes(): ReadonlyMap<string, string>;
    /**
     * Resolve when `drain` settles, or reject with {@link SHUTDOWN_DEADLINE}
     * once the configured bound elapses.
     */
    private raceShutdownDeadline;
    /**
     * Abandon in-flight execution on every route, and report what was still
     * running.
     *
     * The log line names route ids and their pending counts rather than a
     * total, because it is the only forensic record a forced shutdown leaves:
     * an operator reading it afterwards needs to know WHICH capability was
     * still working, not merely that something was.
     *
     * What this accepts losing: in-flight exchanges are abandoned mid-step and
     * emit no terminal event. What it does NOT do is settle or deny anything on
     * the way down, so a deferred exchange survives a forced shutdown exactly
     * as it survives a graceful one.
     *
     * It does NOT reach the deferral sweeper. The sweeper stops cooperatively
     * from `context:stopping`, which fires at the start of EVERY shutdown, and
     * plugin teardown then awaits its in-flight sweep unbounded, outside this
     * deadline. Records it had claimed heal via their lease either way.
     */
    private forceStageTwo;
}

/**
 * Deferral state carried on the exchange.
 *
 * Per `.standards/exchange-state-model.md`, everything that must survive a
 * deferral lives in `headers`; `ex.deferral` is a derivation over these keys
 * plus the context's signer, in the same shape as `ex.principal` and
 * `ex.logger`. Nothing here is a second per-exchange bag.
 */
declare const DeferralHeaders: {
    /**
     * How many times this exchange has already deferred. Distinguishes
     * successive deferrals of one exchange (a route that defers, resumes,
     * and defers again for a second approval), which is what keeps their
     * deferral ids distinct.
     */
    readonly SEQUENCE: "routecraft.deferral.sequence";
    /**
     * Id of the exchange a snapshot was taken of, set when the framework
     * clones an exchange (`.tap()`, `.multicast()`). A clone gets a fresh
     * `routecraft.id` by design, so without this a token minted inside a
     * `.tap()` notification would name a deferral that never exists. The
     * canonical "notify before deferring" step is exactly such a tap, so the affordance follows this key back to the exchange that will
     * actually defers.
     */
    readonly OWNER: "routecraft.deferral.owner";
    /** The validated resume payload, written by the resume path before the continuation runs. */
    readonly RESULT: "routecraft.deferral.result";
    /** Who resumed it, recorded for audit. */
    readonly RESUMED_BY: "routecraft.deferral.resumedBy";
    /** When the resume was accepted. */
    readonly RESUMED_AT: "routecraft.deferral.resumedAt";
};
declare module "@routecraft/routecraft" {
    interface RoutecraftHeaders {
        "routecraft.deferral.sequence"?: number;
        "routecraft.deferral.owner"?: string;
        "routecraft.deferral.result"?: unknown;
        "routecraft.deferral.resumedBy"?: PrincipalRef;
        "routecraft.deferral.resumedAt"?: Date;
    }
}
/**
 * The `ex.deferral` affordance.
 *
 * Readable at any point in a pipeline, which is the whole point: `id` and
 * `token` are derived from the exchange rather than minted by the defer
 * step, so a notification step that runs BEFORE the `.defer()` can put a
 * working resume link in the message it sends (n8n's `$execution.resumeUrl`
 * has the same property).
 *
 * `result`, `resumedBy` and `resumedAt` are the other half: they are absent
 * on execution one and populated by the resume path before the continuation
 * runs. `result` is typed `unknown` here and narrowed by the builder, which
 * threads the `schema` option's output type into every step after the
 * `.defer()`, the way `.input()` types the body.
 *
 * @template R - The resume payload type, threaded in by `.defer({ schema })`
 */
interface DeferralAffordance<R = unknown> {
    /** Id of the deferral this exchange would defer as (or deferred as). */
    readonly id: string;
    /** How many times this exchange has already deferred. Zero before the first defer. */
    readonly sequence: number;
    /**
     * Signed, single-use resume token for {@link DeferralAffordance.id}.
     *
     * @throws RC5052 when the context has no deferral runtime configured.
     */
    readonly token: string;
    /**
     * A resume token bound to one specific call on this record.
     *
     * Only a step that can raise several calls against one deferral needs this:
     * the agent tier's parallel tool batch is the shipped case, where every
     * handler sees the same deferral id (it names the deferral, not the call)
     * and each sends its own recipient a link. Binding the credential to the
     * call means the handler that then LOSES the deferral cannot have its
     * recipient resume the winner's deferral; they take `RC5055` instead.
     *
     * The binding is checked against what the record actually deferred with, so
     * minting one here without the deferral recording the same value refuses
     * every resume. Plain `.defer()` sites use {@link
     * DeferralAffordance.token}.
     *
     * @throws RC5052 when the context has no deferral runtime configured.
     */
    readonly tokenFor: (callBinding: string) => string;
    /** The validated resume payload. Present only after a resume. */
    readonly result: R;
    /** Who resumed it. Present only after a resume, and only when the ingress route had a principal. */
    readonly resumedBy: PrincipalRef | undefined;
    /** When the resume was accepted. Present only after a resume. */
    readonly resumedAt: Date | undefined;
}

/**
 * Types of operations that can be performed on an exchange.
 * These values are used in exchange headers to track the current operation.
 */
declare enum OperationType {
    /** The exchange was created from a source */
    FROM = "from",
    /**
     * Synthetic step inserted by the runtime when a source adapter attaches a
     * `parse` function to the queued message. Builds a derived exchange via
     * `DefaultExchange.rewrap(exchange, { body: await parse(exchange.body) })`
     * before any user steps so parse failures flow through the route's normal
     * error handling instead of aborting the source. See #187.
     */
    PARSE = "parse",
    /** The exchange was processed by a processor */
    PROCESS = "process",
    /** The exchange was sent to a destination */
    TO = "to",
    /** The exchange was split into multiple exchanges */
    SPLIT = "split",
    /** The exchange was aggregated from multiple exchanges */
    AGGREGATE = "aggregate",
    /** Modify the body of the exchange */
    TRANSFORM = "transform",
    /** Tap an exchange without modifying it */
    TAP = "tap",
    /** Filter an exchange based on a condition and reject the message if the condition is not met */
    FILTER = "filter",
    /** Validate the exchange against a schema and reject the message if the schema is not met */
    VALIDATE = "validate",
    /** Enrich the exchange with data from another exchange */
    ENRICH = "enrich",
    /** Set or override a header on the exchange */
    HEADER = "header",
    /** Conditionally route the exchange through one of several branches */
    CHOICE = "choice",
    /** Fan the exchange out to multiple independent paths in parallel */
    MULTICAST = "multicast",
    /** Run exactly one of several targets, chosen by load-balancing strategy */
    DISPATCH = "dispatch",
    /** Rate limit an operation, pacing exchanges that exceed the rate */
    THROTTLE = "throttle",
    /** Fast-fail an operation while a downstream is known to be failing */
    CIRCUIT_BREAKER = "circuit-breaker",
    /** Bound how many exchanges run an operation simultaneously (bulkhead) */
    CONCURRENCY = "concurrency",
    /** Pass every Nth exchange (or the first per time window), dropping the rest */
    SAMPLE = "sample",
    /** Drop exchanges whose derived key has already been seen */
    DEDUPE = "dedupe",
    /** Hold a burst of exchanges and release only the last after a quiet period */
    DEBOUNCE = "debounce",
    /** Short-circuit the pipeline: drop the exchange without further steps */
    HALT = "halt",
    /** Defer the exchange durably and exit the pipeline, to be resumed later at the next step */
    DEFER = "defer",
    /** Revive a deferred exchange addressed by a signed resume token */
    RESUME = "resume"
}
/**
 * Framework-owned header keys present on every exchange.
 *
 * The whole `routecraft.*` header namespace is RESERVED: the framework and
 * its adapters own every key under it. Adapter-specific keys live in
 * per-adapter key objects next to their adapters (e.g. `MailHeaders.UID`,
 * `CronHeaders.EXPRESSION`); each adapter merges its keys into
 * {@link RoutecraftHeaders} via declaration merging so they stay typed on
 * `exchange.headers`. User-defined headers must use their own namespace
 * (e.g. `x-...` or `myapp.*`).
 */
declare const HeadersKeys: {
    /** Unique identifier for this exchange. Stored in headers so it survives halt/continue alongside body. */
    readonly ID: "routecraft.id";
    /** The operation type (from, process, to) */
    readonly OPERATION: "routecraft.operation";
    /** The route id */
    readonly ROUTE_ID: "routecraft.route";
    /** The correlation id */
    readonly CORRELATION_ID: "routecraft.correlation_id";
    /** The hierarchy of split groups this exchange belongs to */
    readonly SPLIT_HIERARCHY: "routecraft.split_hierarchy";
    /**
     * Authenticated principal resolved from the request, when available.
     * Carries the structured `Principal` object; the `ex.principal` getter
     * is sugar over `ex.headers[HeadersKeys.AUTH_PRINCIPAL]`.
     */
    readonly AUTH_PRINCIPAL: "routecraft.auth.principal";
};
/**
 * Typed map of well-known headers on an exchange. The core interface
 * declares only the framework-owned keys; adapters and ecosystem packages
 * merge their own `routecraft.<adapter>.*` keys in via declaration merging,
 * next to the adapter that owns them:
 *
 * ```ts
 * declare module "@routecraft/routecraft" {
 *   interface RoutecraftHeaders {
 *     "routecraft.myadapter.thing"?: string;
 *   }
 * }
 * ```
 *
 * The `routecraft.*` namespace is reserved for the framework and adapters;
 * see {@link HeadersKeys}.
 */
interface RoutecraftHeaders {
    /**
     * Unique identifier for this exchange.
     *
     * Stored in headers (not as a separate field) so it travels with the
     * exchange's serializable state. This is the single source of truth for
     * exchange identity; the `ex.id` getter reads from this key.
     */
    "routecraft.id": string;
    /** The current operation being performed (OperationType or DSL label) */
    "routecraft.operation": OperationType | string;
    /** The ID of the route processing this exchange */
    "routecraft.route": string;
    /** Unique identifier for correlating related exchanges */
    "routecraft.correlation_id": string;
    /** Hierarchy path for split operations */
    "routecraft.split_hierarchy"?: readonly string[];
}
/**
 * Allowed types for a single header value at the **bag** level.
 *
 * `unknown` lets cross-cutting concerns (auth principal, future tracing
 * spans, tenancy contexts) live in `headers` as a single typed slot rather
 * than being spread across many flat keys. Per-key types are narrowed by
 * {@link RoutecraftHeaders} (which adapters extend via declaration
 * merging); this bag-level type is just the catch-all for unregistered
 * keys.
 *
 * For API surfaces that accept a static header value (e.g. `.header("k",
 * v)`), prefer {@link HeaderLiteral} which excludes function types so user
 * lambdas get correct inference in the value-or-function overload.
 *
 * Array values declared on registered keys are typed `readonly string[]` so
 * they cannot be mutated via `push` / `splice` / index assignment through
 * the (already `Readonly<>`) `ExchangeHeaders` map. The contract is
 * type-level; the constructor freezes array values defensively so a caller
 * who casts away the readonly cannot mutate a shared reference.
 */
type HeaderValue = unknown;
/**
 * Allowed types for a header value when supplied as a literal at an API
 * boundary that also accepts a callback (e.g. `.header("k", v)` /
 * `.header("k", ex => ...)`). Excludes function types so the callback arm
 * of the union infers parameters correctly.
 *
 * Includes the original primitive types for source-compat plus
 * `Readonly<Record<string, unknown>>` so structured values (Principal,
 * future Span, etc.) can be assigned directly when they aren't mediated by
 * a callback.
 */
type HeaderLiteral = string | number | boolean | null | undefined | readonly string[] | Readonly<Record<string, unknown>>;
/**
 * Complete set of headers for an exchange. Read-only by contract: produce
 * derived headers via spread (`{ ...exchange.headers, key: value }`) and the
 * framework re-wraps the resulting exchange when the operation hands it back.
 *
 * Includes standard Routecraft headers, adapter-declared headers (merged
 * into {@link RoutecraftHeaders}), and custom headers.
 */
type ExchangeHeaders = Readonly<Partial<RoutecraftHeaders> & Record<string, HeaderValue>>;
/**
 * Represents a message being processed through a route.
 *
 * An exchange has two kinds of state:
 *
 * 1. **Stored fields** (`body`, `headers`) carry the data and metadata that
 *    must survive halt/continue. Persistence serializes exactly these two
 *    slots; rehydration constructs a new instance around them.
 * 2. **Derived accessors** (`id`, `principal`, `logger`) read from
 *    `headers` (or runtime services) and look like properties at the call
 *    site. They are not stored separately. `id` reads
 *    `headers["routecraft.id"]`; `principal` reads
 *    `headers["routecraft.auth.principal"]`; `logger` builds a child logger
 *    lazily from the framework's logger and the exchange's id.
 *
 * Cross-cutting concerns (auth, tracing, tenancy) all live as keys in
 * `headers` rather than as top-level fields. This keeps the serialization
 * surface small and avoids a "special field" precedent for every new
 * concern.
 *
 * Exchanges are immutable. Operations that change body or headers must
 * produce a new exchange (typically via spread) and return it; the
 * framework re-wraps the result via {@link DefaultExchange.rewrap} so it
 * preserves internal bindings (context, route). Body is not deep-frozen so
 * adapter authors can attach arbitrary user payloads, but the framework
 * will not mutate it and authors should treat it the same way.
 *
 * @template T The type of data in the body
 */
type Exchange<T = unknown> = {
    /**
     * Unique identifier for this exchange.
     *
     * Reads from `headers["routecraft.id"]`. Stable across `rewrap`s so
     * pipeline steps see the same id throughout a route.
     */
    readonly id: string;
    /** Headers containing metadata, including cross-cutting concerns like the authenticated principal. */
    readonly headers: ExchangeHeaders;
    /** The data being processed */
    readonly body: T;
    /**
     * Authenticated principal for this exchange, when one has been resolved.
     *
     * Sugar over `headers["routecraft.auth.principal"]`. Set automatically by
     * source adapters that perform authentication (e.g. the MCP server when
     * `auth:` is configured) by writing the principal into headers. Routes
     * may also assign a custom principal in `.process()` by spreading new
     * headers with this key.
     *
     * Propagates naturally because it lives in `headers`: any operation that
     * spreads `prev.headers` keeps the principal sticky-set automatically,
     * with no special-case plumbing.
     */
    readonly principal?: Principal | undefined;
    /**
     * Logger for this exchange (pino child logger).
     *
     * Built lazily from the framework's base logger and the exchange's id /
     * route / correlation. Not stored as serializable state; rehydrated
     * exchanges build a fresh child logger on first access.
     */
    readonly logger: ReturnType<typeof logger.child>;
    /**
     * Durable-deferral view of this exchange: the id and signed token it
     * would defer as, and (after a resume) the payload that revived it.
     *
     * Sugar over the `routecraft.deferral.*` headers plus the context's
     * token signer, in the same shape as `principal` and `logger`. Readable
     * before the `.defer()` runs, which is what lets a notification step
     * earlier in the pipeline send a working resume link.
     *
     * `result` is `unknown` here; `.defer({ schema })` narrows it to the
     * schema's output type for every step after the defer.
     */
    readonly deferral: DeferralAffordance;
};
/**
 * Get the CraftContext for an exchange, if it has internals.
 * Reads from symbol-keyed storage first (cross-instance safe), then WeakMap.
 *
 * @param exchange The exchange
 * @returns The context or undefined
 * @internal
 */
declare function getExchangeContext(exchange: Exchange): CraftContext | undefined;
/**
 * Get the route for an exchange, if it has internals.
 * Reads from symbol-keyed storage first (cross-instance safe), then WeakMap.
 *
 * @param exchange The exchange
 * @returns The route or undefined
 * @internal
 */
declare function getExchangeRoute(exchange: Exchange): Route | undefined;
/**
 * The step state a resume attached for the re-entrant step about to re-run,
 * or `undefined` when this execution is not resuming that step.
 *
 * A defer-capable adapter (see {@link markDeferCapable}) calls this at
 * the top of its execution to decide between a fresh run and a resumed one.
 * Reading does NOT consume the state: the executor clears it when the step
 * settles, so a step-scope or route-scope `.retry()` re-running a failed
 * resume attempt still sees it, while a later defer-capable step in the
 * same continuation (or a fresh deferral by the same step) starts clean.
 */
declare function peekResumeStepState(exchange: Exchange): unknown;
/**
 * Returns true if the route's `.output({ body })` validation accepted this
 * exchange's body against `schema` specifically.
 *
 * A request/reply source adapter that enforces the same schema at its own
 * protocol boundary reads this to avoid validating twice. The second run is
 * not merely redundant: validation replaces the body with the schema's
 * output value, so a schema that transforms (`z.string().transform(...)`,
 * `.pipe()`) rejects the very value it just produced.
 *
 * The schema is compared by identity, so an exchange validated against some
 * other contract does not count as validated against this one.
 *
 * @param exchange - The exchange to test, or any rewrap of it
 * @param schema - The schema the caller is about to enforce
 * @returns Whether the route already validated this body against that schema
 */
declare function wasOutputValidated(exchange: Exchange, schema: StandardSchemaV1): boolean;
/**
 * Returns true if the exchange (or any rewrap of it sharing the same
 * internals) has been marked as dropped.
 *
 * A request/reply source adapter reads this to tell "the route declined
 * this request" apart from "the route produced this result": a dropped
 * exchange resolves with the body it came in with, so an adapter that does
 * not check hands the caller its own request back as if it were an answer.
 * `CraftClient.sendDirect` and the route-scope `forward` both raise RC5031
 * on it; an adapter outside core translates it into whatever its protocol
 * uses to decline.
 *
 * @param exchange - The exchange to test, or any rewrap of it
 * @returns Whether the exchange was dropped rather than completed
 */
declare function isDropped(exchange: Exchange): boolean;
/**
 * Internal options accepted by {@link DefaultExchange}'s constructor.
 * The constructor freezes whatever it produces; callers can supply either a
 * `Readonly<...>` headers object (e.g. from another exchange) or a plain
 * literal.
 *
 * `id` and `principal` are NOT options here: they live inside `headers`
 * (`headers["routecraft.id"]` and `headers["routecraft.auth.principal"]`).
 * Callers that want to control them set the corresponding header keys when
 * building `headers`.
 *
 * @internal
 */
type DefaultExchangeOptions<T> = {
    body?: T;
    headers?: ExchangeHeaders;
};
/**
 * Default implementation of the Exchange interface.
 *
 * The implementation stores exactly two fields, `body` and `headers`.
 * Everything else surfaced on the public `Exchange<T>` API (`id`,
 * `principal`, `logger`) is exposed through getters that derive from
 * `headers` plus runtime services. This keeps the serialization surface
 * for halt/continue narrow (just `{ body, headers }`) and removes the
 * "special field" precedent for cross-cutting concerns.
 *
 * Instances are immutable: the constructor freezes the wrapper and headers
 * (and any non-primitive header values, defensively). Body is left
 * unfrozen so user payloads of any shape can flow through; the framework
 * does not mutate it.
 *
 * @template T The type of data in the body
 *
 * @example
 * ```typescript
 * // Create a simple exchange with a string body
 * const exchange = new DefaultExchange<string>(context, {
 *   body: "Hello, World!"
 * });
 *
 * // Access exchange properties
 * console.log(exchange.id);        // Unique UUID (read from headers["routecraft.id"])
 * console.log(exchange.body);      // "Hello, World!"
 * console.log(exchange.headers);   // Headers object with standard fields
 * ```
 */
declare class DefaultExchange<T = unknown> implements Exchange<T> {
    #private;
    /** Headers containing metadata, including the exchange id and (when set) the authenticated principal. */
    readonly headers: ExchangeHeaders;
    /** The data being processed */
    readonly body: T;
    /**
     * Create a new exchange.
     *
     * @param context The CraftContext this exchange belongs to
     * @param options Optional configuration for the exchange. Set the exchange
     *   id by including `headers["routecraft.id"]`; set the principal by
     *   including `headers["routecraft.auth.principal"]`. Both default to
     *   sensible runtime values when omitted (id: `randomUUID()`).
     */
    constructor(context: CraftContext, options?: DefaultExchangeOptions<T>);
    /**
     * Unique identifier for this exchange. Reads from
     * `headers["routecraft.id"]` so the id travels with the serializable
     * state and survives halt/continue.
     */
    get id(): string;
    /**
     * Authenticated principal, when one has been resolved. Sugar over
     * `headers["routecraft.auth.principal"]`.
     */
    get principal(): Principal | undefined;
    /**
     * Pino child logger scoped to this exchange. Built lazily from the
     * framework's base logger; rebuilt on a rehydrated exchange because the
     * logger is not part of the serializable state.
     */
    get logger(): ReturnType<typeof logger.child>;
    /**
     * Durable-deferral view of this exchange. See {@link Exchange.deferral}.
     *
     * Built per access rather than cached: the view derives from `headers`,
     * which a resume rewrites, so a cached one would go stale exactly when it
     * matters. It is a small object of getters, and the expensive part
     * (minting a token) only runs if the caller reads `token`.
     */
    get deferral(): DeferralAffordance;
    /**
     * Construct a new {@link DefaultExchange} that combines internals from a
     * previous exchange (context, route binding, parse hooks) with field
     * overrides from a partial. Used by the engine to normalise plain
     * objects user code returns from `.process()` (or any `with*`-style
     * spread) back into proper instances without losing the framework's
     * back-channel state.
     *
     * - `headers` defaults to `prev.headers`. Identity (`routecraft.id`) is
     *   forced to `prev.id` so it survives a caller-supplied headers object
     *   that came from a different exchange. Cross-cutting concerns
     *   (`routecraft.auth.principal`, future tracing/tenancy keys) flow
     *   through naturally because they live in the same headers bag.
     * - `body` defaults to `prev.body`.
     *
     * Identity-changing operations (split, aggregate restoring a parent)
     * construct a new `DefaultExchange` directly with fresh headers rather
     * than calling `rewrap`.
     *
     * @internal
     */
    static rewrap<T>(prev: Exchange, partial?: {
        readonly body?: T;
        readonly headers?: ExchangeHeaders;
    }): DefaultExchange<T>;
}

/**
 * Compile a path pattern into a matcher closure.
 *
 * Supports literal segments and `:param` segments. Pattern and pathname are
 * tokenised on `/`; an empty leading token (from the leading `/`) and any
 * empty trailing token (from a trailing `/`) are dropped so `"/orders"`,
 * `"/orders/"`, and the pathname `"/orders/"` all behave the same way.
 *
 * URL-decoding happens once per matched segment so handlers receive the
 * decoded value (`"hello world"`, not `"hello%20world"`).
 *
 * URLPattern would do all of this, but it is not a global in Node 22. Doing
 * it by hand keeps the http source dependency-free; richer patterns
 * (constraints, wildcards) can move to URLPattern when the minimum Node
 * version catches up.
 */
interface PathMatcher {
    /** Try to match a concrete pathname. Returns the resolved params on success, null on miss. */
    match(pathname: string): Readonly<Record<string, string>> | null;
    /** Original pattern, e.g. `/orders/:id`. */
    readonly pattern: string;
    /** Names of `:param` segments in the pattern, in declaration order. */
    readonly paramNames: readonly string[];
}

declare const SCHEMES: readonly ["hmac-sha256-hex", "hmac-sha1-hex", "stripe-timestamped", "standard-webhooks"];
/**
 * Signature schemes supported by the built-in webhook verifier.
 *
 * - `"hmac-sha256-hex"`: hex-encoded HMAC-SHA256 of the raw body. GitHub's
 *   `X-Hub-Signature-256` uses this with `prefix: "sha256="`.
 * - `"hmac-sha1-hex"`: hex-encoded HMAC-SHA1 of the raw body. Legacy GitHub
 *   `X-Hub-Signature` uses this with `prefix: "sha1="`. Prefer sha256 when
 *   the provider offers both.
 * - `"stripe-timestamped"`: Stripe's `Stripe-Signature` format
 *   (`t=<unix>,v1=<hex>`). The signed payload is `<t>.<raw body>` and the
 *   timestamp must be within `toleranceSec` of the server clock, which
 *   bounds replay of captured deliveries.
 * - `"standard-webhooks"`: the [Standard Webhooks](https://www.standardwebhooks.com/)
 *   format, sent by Resend, Bird and Svix among others. Reads the three
 *   headers the specification fixes (`webhook-id`, `webhook-timestamp`,
 *   `webhook-signature`), signs `<id>.<timestamp>.<raw body>` with the
 *   base64-decoded secret, and admits when any space-separated `v1,` entry
 *   matches. Covers the symmetric half of the specification only:
 *   asymmetric `v1a` (ed25519) entries are skipped like any other
 *   non-`v1` version.
 */
type HttpWebhookSignatureScheme = (typeof SCHEMES)[number];
/** Fields every scheme takes. */
interface HttpWebhookSignatureOptionsBase {
    /** Shared secret the provider signs with. */
    secret: string;
    /**
     * Literal prefix stripped from the header value before comparison, e.g.
     * `"sha256="` for GitHub. A header value that does not start with the
     * prefix is an invalid signature. Ignored by `"stripe-timestamped"` and
     * `"standard-webhooks"`, which have their own field formats.
     */
    prefix?: string;
    /**
     * Maximum allowed clock skew, in seconds, between the signature's
     * embedded timestamp and the server clock. Used by
     * `"stripe-timestamped"` and `"standard-webhooks"`. Defaults to 300.
     */
    toleranceSec?: number;
}
/**
 * The three schemes that read one configured header. `header` is required:
 * nothing in these formats fixes a header name, so there is no default that
 * would be right more often than it is wrong.
 */
interface HttpWebhookSignatureHeaderOptions extends HttpWebhookSignatureOptionsBase {
    /** Request header carrying the signature (e.g. `"x-hub-signature-256"`). Case-insensitive. */
    header: string;
    /** Signature scheme. See {@link HttpWebhookSignatureScheme}. */
    scheme: Exclude<HttpWebhookSignatureScheme, "standard-webhooks">;
}
/**
 * Standard Webhooks. The specification fixes all three header names, so a
 * route configures a secret and nothing else. There is deliberately no
 * per-header override: the id and timestamp names are read from the
 * specification, so renaming only the signature header would build a route
 * that constructs cleanly and then rejects every live delivery.
 */
interface HttpStandardWebhooksSignatureOptions extends HttpWebhookSignatureOptionsBase {
    scheme: "standard-webhooks";
    /**
     * Never set. Declared so the refusal survives a config object that is not
     * an object literal, where excess-property checking does not apply.
     */
    header?: never;
}
/**
 * Declarative webhook-signature verification for `http({...})` sources.
 * When configured, the plugin verifies the raw request bytes against the
 * signature header and rejects 401 before any route step runs, so HMAC
 * comparison never has to be hand-rolled in a `.filter()`.
 *
 * For providers whose scheme is not covered here, opt in to
 * `http({ rawBody: true })` instead and verify in a route step against
 * `routecraft.http.rawBody`.
 */
type HttpWebhookSignatureOptions = HttpWebhookSignatureHeaderOptions | HttpStandardWebhooksSignatureOptions;

/**
 * One entry in an http mount's route registry. Created when a
 * `from(http({...}))` source subscribes and removed on abort. The mount's
 * dispatcher matches incoming requests against this registry.
 *
 * The route's `handler` is the runtime-provided callback that turns a message
 * into a fully-processed {@link Exchange}. The source's job is just to call
 * it (and to convert the result back into the wire format).
 */
interface HttpRouteEntry {
    readonly routeId: string;
    readonly method: HttpMethod;
    /** Matcher over the FULL request path (mount prefix already joined in). */
    readonly matcher: PathMatcher;
    /**
     * The route declares a route-entry `.authorize()`. On a walled mount this
     * is redundant (the wall already ran); on a public mount it forces the
     * dispatcher to pull credential verification for this route.
     */
    readonly requiresPrincipal: boolean;
    /** Whether the route opted in to `routecraft.http.rawBody` on the exchange. */
    readonly rawBody: boolean;
    /** Webhook-signature gate; requests failing verification 401 before the route runs. */
    readonly signature: HttpWebhookSignatureOptions | undefined;
    /**
     * Decides when the caller is answered and with what. Undefined leaves the
     * dispatcher's own path, which awaits the pipeline and serialises it.
     */
    readonly respond: HttpResponder | undefined;
    /** Route-level discovery bundle, used by /openapi.json. */
    readonly discovery: RouteDiscovery | undefined;
    /** Provided by the source on subscribe; the dispatcher calls it once it has a parsed body. */
    readonly handler: (body: unknown, headers: ExchangeHeaders) => Promise<Exchange>;
}
/**
 * Per-mount route registry. The http plugin instantiates one per configured
 * mount; source adapters resolve their mount by name and push/pop entries.
 */
type HttpRouteRegistry = Map<string, HttpRouteEntry>;
/**
 * What the http source needs to know about one configured mount: where its
 * routes register and which path prefix route patterns are joined onto.
 */
interface HttpMountRuntime {
    /** Mount path prefix; `"/"` for the catch-all. */
    readonly path: string;
    readonly registry: HttpRouteRegistry;
}
/**
 * Symbol key sharing the mount table between the http plugin (which creates
 * and owns it) and the http source (which resolves a mount by name and
 * inserts / removes route entries). `Symbol.for` so the key is shared across
 * any duplicate package copies in a workspace (matches the convention used
 * by every other plugin in `.standards/adapter-architecture.md`).
 */
declare const HTTP_MOUNTS: unique symbol;
/**
 * Symbol key used by the http source to assert the plugin has been
 * registered. Set to `true` in `httpPlugin.apply(ctx)`. The source throws
 * `RC5003` when it is missing so misconfiguration fails at subscribe time.
 */
declare const HTTP_PLUGIN_REGISTERED: unique symbol;
declare module "@routecraft/routecraft" {
    interface StoreRegistry {
        [HTTP_MOUNTS]: ReadonlyMap<string, HttpMountRuntime>;
        [HTTP_PLUGIN_REGISTERED]: boolean;
    }
}

/**
 * `info` block of an OpenAPI 3.1 document. Mirrors the OpenAPI Info Object
 * shape (`title`, `version`, optional `description`, `contact`, `license`).
 *
 * Defaults are auto-detected from the host project's `package.json` at
 * plugin apply time:
 *
 * - `title`   -> `package.json` `name` (literal, including any `@scope/`).
 * - `version` -> `package.json` `version`.
 *
 * Description / contact / license are **not** auto-pulled even when
 * present in `package.json`: those fields commonly carry internal
 * context (TODO notes, author emails, license boilerplate) that should
 * not leak into a publicly served document by default. Set them
 * explicitly to publish them.
 *
 * Auto-detection deliberately yields nothing when the nearest
 * `package.json` is a workspace container (a `workspaces` field, or a
 * `pnpm-workspace.yaml` beside it): a monorepo root's private, often
 * stale identity must not be advertised on a publicly served document.
 * See `findPackageInfo` for the full resolution rules.
 *
 * Any explicit field passed by the caller wins over the auto-detected
 * default; no usable `package.json` falls back to the hardcoded
 * "Routecraft HTTP API" / "0.0.0".
 */
interface HttpOpenApiInfo {
    title?: string;
    version?: string;
    description?: string;
    contact?: {
        name?: string;
        url?: string;
        email?: string;
    };
    license?: {
        name: string;
        identifier?: string;
        url?: string;
    };
}

/** HTTP request methods supported by both the destination and the source. */
type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "HEAD" | "OPTIONS";
/** Query string values accepted by the destination's `query` option. */
type QueryParams = Record<string, string | number | boolean>;
/**
 * What the client does when the server answers with a 3xx. Mirrors the
 * platform `RequestInit.redirect` values, and nothing more: the option
 * reports what happened and hands control back to the route.
 *
 * - `"follow"` (the default): the runtime follows the chain and the result
 *   describes the final response.
 * - `"manual"`: the 3xx itself is returned, `Location` readable in
 *   {@link HttpResult.headers}, so a route that validated the URL it asked
 *   for can re-run that rule on the next hop instead of having the adapter
 *   walk somewhere the route never approved. Such a 3xx does not trip
 *   `throwOnHttpError`, because it is the outcome the route asked for;
 *   every other non-2xx still does, `304` included, since a cache answer is
 *   not a hop.
 * - `"error"`: the request fails rather than following.
 */
type HttpRedirectMode = "follow" | "manual" | "error";
/**
 * What the client accepts as a request body.
 *
 * Deliberately not `unknown`: a union containing `unknown` collapses to
 * `unknown`, which took the contextual parameter type off the callback form of
 * {@link HttpClientOptions.body} and made every call site annotate its own
 * exchange by hand. Anything a `fetch` body can be is here, plus the plain
 * values the client serialises to JSON for you.
 *
 * `object` is deliberately broad. Narrowing it to `Record<string, unknown>`
 * would make a callback's return type checked, but it also refuses an
 * interface-typed body, which is the ordinary case: an `interface` has no
 * implicit index signature where an otherwise identical `type` alias does, so
 * the two spellings of the same shape would stop behaving alike. It refuses
 * arrays, class instances and Maps too, all of which the client serialises
 * correctly, and
 * `object & { call?: never }` refuses a plain object literal because the
 * intersection triggers excess-property checking. So the value arm admits
 * functions and a callback's return goes unchecked; the contextual parameter
 * type it exists for still works.
 *
 * `undefined` is a member rather than only the property being optional,
 * because the callback form has to be able to decide per exchange that there
 * is no body to send (`body: (ex) => ex.body.attachment ?? undefined`). The
 * client sends none for it, as it always has.
 */
type HttpRequestPayload = string | number | boolean | null | undefined | object | Uint8Array | ArrayBuffer | URLSearchParams | FormData;
/**
 * How the client hands the response body to the route.
 *
 * - `"text"` (the default): decoded as UTF-8, then parsed as JSON when the
 *   response says it is JSON. What every route got before this option existed.
 * - `"bytes"`: the body is a `Uint8Array` of exactly what arrived, with no
 *   decoding and no JSON parsing. Required for anything that is not text,
 *   because UTF-8 decoding is lossy in one direction: an invalid sequence
 *   becomes U+FFFD and the original bytes cannot be recovered.
 *
 * Chosen explicitly rather than sniffed from the content type, which would
 * silently change the body type of an existing route that happens to receive
 * `application/octet-stream` and reads it as a string today.
 */
type HttpResponseBodyMode = "text" | "bytes";
interface HttpClientOptions<T = unknown> {
    method?: HttpMethod;
    url: string | ((exchange: Exchange<T>) => string);
    headers?: Record<string, string> | ((exchange: Exchange<T>) => Record<string, string>);
    query?: QueryParams | ((exchange: Exchange<T>) => QueryParams);
    body?: HttpRequestPayload | ((exchange: Exchange<T>) => HttpRequestPayload);
    /** Abandon the request after this long. No deadline when unset. */
    timeout?: Duration;
    throwOnHttpError?: boolean;
    /**
     * Maximum response body size in bytes. Defaults to 10 MB, the same name
     * and the same number as the http plugin's inbound cap, so one concept
     * means one thing on both sides of the framework.
     *
     * A declared `Content-Length` above the cap is refused before a byte is
     * read; otherwise the body streams and is abandoned the moment the count
     * crosses the ceiling, which bounds what an oversized response can cost
     * the process rather than only what it hands the route. Exceeding it
     * fails the exchange with `RC5061`: a truncated body would hand the
     * route half a document and let it parse as though it were whole.
     *
     * `Infinity` is the named way to opt out entirely. Zero and negatives are
     * refused rather than read as "no limit", so an options object built
     * programmatically cannot arrive at unbounded by accident.
     */
    maxBodySize?: number;
    /**
     * What to do with a 3xx response. Defaults to `"follow"`, the platform
     * default and the behaviour of every existing route. See
     * {@link HttpRedirectMode}.
     */
    redirect?: HttpRedirectMode;
    /**
     * How to hand the response body to the route. Defaults to `"text"`, which
     * is what every route did before this option existed.
     *
     * Use `"bytes"` for anything that is not text. The default decodes the
     * response as UTF-8, and that is lossy in one direction: a JPEG's leading
     * `ff d8 ff e0` is not valid UTF-8, so each byte becomes U+FFFD and
     * re-encodes as three bytes. The corruption is silent and asymmetric,
     * which is what makes it dangerous: an Ogg page header is ASCII, so a
     * voice note survives while an image beside it does not.
     *
     * `maxBodySize` and `timeout` apply unchanged; the cap counts bytes as
     * they arrive on both modes.
     *
     * @see {@link HttpResponseBodyMode}
     */
    responseBody?: HttpResponseBodyMode;
}
type HttpResult<T = string | unknown> = {
    status: number;
    headers: Record<string, string>;
    body: T;
    url: string;
};
/**
 * API-key auth options accepted by the http plugin. Mirrors the validator
 * shape used by `jwt()` / `jwks()` so the plugin's `auth` slot remains a
 * single uniform surface.
 *
 * `keys` is the static-allowlist shortcut: any caller presenting one of the
 * listed keys is admitted with a synthetic `Principal { kind: "custom",
 * scheme: "apiKey", subject: "<key fingerprint>" }`. Use `verify` instead
 * when a key needs to resolve to a per-user identity (database lookup).
 *
 * @experimental
 */
interface ApiKeyAuthOptions {
    /** Discriminator: this is API-key auth, not bearer. */
    readonly kind: "apiKey";
    /** Where to look for the key. Defaults to `"header"`. */
    in?: "header" | "query";
    /**
     * Header (or query) parameter name. Defaults to `"x-api-key"` for header
     * lookups and `"api_key"` for query lookups.
     */
    name?: string;
    /** Static allowlist of accepted keys. Mutually exclusive with `verify`. */
    keys?: readonly string[];
    /**
     * Scopes granted to a caller admitted by the static `keys` allowlist.
     *
     * Every listed key carries the same scopes, because a flat allowlist has
     * no place to hang per-key authority; when different callers need
     * different scopes, `verify` returns a principal per key and this field
     * is not the tool. Without it a static key mints a principal carrying no
     * scopes at all, which any scope check refuses.
     *
     * Refused alongside `verify` with `RC5003` rather than ignored: a verifier
     * returns the principal itself, so the scopes belong on what it returns and
     * a second place to declare them could only disagree with it.
     */
    scopes?: readonly string[];
    /**
     * Custom verifier. Receives the raw key and returns a {@link Principal}
     * (admit) or `null` (reject). Throwing is also a rejection.
     */
    verify?: (key: string) => Principal | null | Promise<Principal | null>;
}
/**
 * Reserved future shape so adding OAuth 2.1 as a follow-up is non-breaking.
 * Today it serves only as a sentinel in the discriminated union.
 *
 * @internal
 */
interface OAuthAuthOptionsReserved {
    readonly kind: "oauth";
}
/**
 * Auth strategy accepted at the plugin level. Three shapes:
 *
 * - {@link ValidatorAuthOptions} / {@link OAuthValidatorAuthOptions}:
 *   anything that exposes a `validator(token) -> Principal` -- typically the
 *   result of `jwt(...)` or `jwks(...)`. Activated by the presence of
 *   `Authorization: Bearer <token>`.
 * - {@link ApiKeyAuthOptions}: header or query API key. Discriminated by
 *   `kind: "apiKey"`.
 * - {@link OAuthAuthOptionsReserved}: placeholder for the upcoming OAuth
 *   2.1 server flow (`kind: "oauth"`). Not implementable in v1.
 */
type HttpAuth = ValidatorAuthOptions | OAuthValidatorAuthOptions | ApiKeyAuthOptions | OAuthAuthOptionsReserved;
/** Event toggles for the http plugin. */
interface HttpPluginEventOptions {
    /**
     * Emit `plugin:http:request:completed` after every response. Built-in
     * endpoints (`/health`, `/ready`, `/openapi.json`) never produce this
     * event regardless of the flag. Defaults to `true`.
     */
    perRequest?: boolean;
}
/**
 * Configuration for `defineConfig({ http: {...} })`. Materialised into a
 * plugin via the registered config applier; users rarely import this type
 * directly.
 *
 * @experimental
 */
interface HttpPluginOptions {
    /**
     * Single-mount shorthand: named entry from `CraftConfig.servers` for the
     * implicit `default` mount at `"/"`. Defaults to `"default"`. Mutually
     * exclusive with `mounts`, where each mount names its own server; the top
     * level of this options object is the mount definition when there is only
     * one, exactly as mcp and ops options are theirs.
     */
    server?: string;
    /**
     * Single-mount shorthand: auth for the implicit `default` mount at `"/"`.
     * Mutually exclusive with `mounts`. The mount is the wall: with a
     * validator in scope every route on it requires a valid credential; the
     * only route-level escalation is `.authorize()`. Omit (with a
     * server-level `servers.<name>.auth`) to inherit the server validator,
     * or pass `false` for a surface with no wall.
     */
    auth?: HttpAuth | false;
    /**
     * Named path-scoped surfaces, each a complete self-description: path,
     * server, auth. Mutually exclusive with the top-level `server` and `auth`
     * shorthand.
     *
     * ```ts
     * http: {
     *   mounts: {
     *     api:     { path: "/api" },           // servers.default, inherits its wall
     *     admin:   { path: "/admin", server: "internal" },
     *     default: { path: "/", auth: false }, // public catch-all
     *   },
     * }
     * ```
     *
     * Routes select a mount with `http({ mount: "api", path: "/orders" })`;
     * an omitted `mount` resolves only to a mount literally named `default`.
     */
    mounts?: Record<string, HttpMountDefinition>;
    /**
     * Maximum request body size in bytes. Requests exceeding this cap return
     * 413 Payload Too Large. Defaults to 10 MB, the same number as the
     * `http()` client's response cap.
     *
     * Must be a positive integer. Unlike the client option of the same name,
     * `Infinity` is refused: an inbound request comes from a stranger and is
     * buffered whole before it can be measured, so an unbounded cap here
     * means one request can exhaust the process, which is what this option
     * exists to prevent.
     */
    maxBodySize?: number;
    /** Event emission toggles. */
    events?: HttpPluginEventOptions;
    /**
     * Built-in endpoint configuration. See {@link HttpBuiltinsOptions}.
     * Built-ins serve from the mount named `default` when its path is `"/"`;
     * with no such mount they are disabled.
     */
    builtins?: HttpBuiltinsOptions;
}
/**
 * One path-scoped surface under {@link HttpPluginOptions.mounts}. Each mount
 * describes itself completely: which listener it sits on and which validator
 * applies. There is no plugin-level default to override.
 *
 * The mount decides authentication for every route on it:
 * - `auth` unset inherits the server validator (`servers.<name>.auth`) as
 *   a wall when one is configured, else the mount is open.
 * - `auth` set is the mount's own wall, replacing the server's validator.
 * - `auth: false` removes the wall: requests are served without credentials
 *   being demanded, and the inherited validator stays reachable, so a route
 *   that declares `.authorize()` still pulls verification through it.
 *   Identity demands can only tighten a public mount, never the reverse.
 */
interface HttpMountDefinition {
    /** Path prefix this mount owns. `"/"` is the catch-all fallback. */
    path: string;
    /** Named entry from `CraftConfig.servers`. Defaults to `"default"`. */
    server?: string;
    auth?: HttpAuth | false;
}
/**
 * Configuration for the built-in endpoints (`/health`, `/ready`,
 * `/openapi.json`). Each entry takes the {@link HttpBuiltinOptions}
 * shape; openapi additionally accepts an `info` block to populate the
 * OpenAPI document's `info` object. The meaning of `requireAuth` varies
 * per endpoint as documented on {@link HttpBuiltinOptions}.
 *
 * @experimental
 */
interface HttpBuiltinsOptions {
    health?: HttpBuiltinOptions;
    ready?: HttpBuiltinOptions;
    openapi?: HttpOpenApiBuiltinOptions;
}
/**
 * Configuration for `/openapi.json` specifically. Extends the uniform
 * {@link HttpBuiltinOptions} shape with `info`, the OpenAPI `info` block
 * (`title`, `version`, `description`, `contact`, `license`). When omitted,
 * `title` and `version` auto-detect from the host project's `package.json`;
 * see {@link HttpOpenApiInfo} for the security rationale on which fields
 * are auto-pulled and which are opt-in.
 *
 * @experimental
 */
interface HttpOpenApiBuiltinOptions extends HttpBuiltinOptions {
    info?: HttpOpenApiInfo;
}
/**
 * Uniform config shape for every built-in endpoint. Inspired by Spring
 * Boot Actuator's `management.endpoint.<name>.enabled` plus
 * `management.endpoint.health.show-details`, but compressed to a single
 * boolean for the auth gate.
 *
 * What `requireAuth` controls, per endpoint:
 *
 * | Endpoint | `requireAuth: false` | `requireAuth: true` |
 * | --- | --- | --- |
 * | `/health` | n/a (response is `{ status: "ok" }`, nothing to gate) | n/a |
 * | `/ready` | always `{ status: "ready", routes }` | anon: `{ status: "ready" }`; authed: `{ status: "ready", routes }`. Always 200 (k8s probes keep working). |
 * | `/openapi.json` | doc to anyone | 401 to anon; doc to authed |
 *
 * Defaults differ per endpoint based on security best practice:
 *
 * - `health`:  `{ enabled: true }` (k8s liveness must be open; `requireAuth` is a no-op)
 * - `ready`:   `{ enabled: true, requireAuth: true }` (gates the `routes` count)
 * - `openapi`: `{ enabled: true, requireAuth: false }` (matches the
 *   Stripe / GitHub / Twilio / OpenAI convention of publishing the
 *   schema publicly)
 *
 * `requireAuth` has no effect when no global `auth` is configured: there
 * is nothing to authenticate against, so the response collapses to the
 * `requireAuth: false` shape.
 *
 * @experimental
 */
interface HttpBuiltinOptions {
    /** Whether the endpoint is reachable. Default: `true`. When `false` the path returns 404. */
    enabled?: boolean;
    /** Whether seeing the endpoint's full response requires authentication. See the table above for per-endpoint behaviour. */
    requireAuth?: boolean;
}
/**
 * Back-compat alias. Older code wrote `CraftConfig["http"]: HttpConfig`
 * where `HttpConfig` was a placeholder `Record<string, unknown>`. The
 * placeholder is gone; `HttpConfig` now resolves to the real plugin
 * options shape so the slot continues to type-check.
 */
type HttpConfig = HttpPluginOptions;
/**
 * What a {@link HttpResponder} returns to send an answer of its own, described
 * rather than constructed. The dispatcher serialises it exactly as it serialises a
 * pipeline result, so one place owns the wire format.
 *
 * A `body` of `undefined` sends no body at all, which is what a bare
 * acknowledgement wants: `{ status: 202 }`.
 */
interface HttpResponseDescriptor {
    /** Status code to send. Required: a responder exists to choose it. */
    status: number;
    /** Extra response headers, lower-cased before they are applied. */
    headers?: Readonly<Record<string, string>>;
    /**
     * Response body. Serialised by the same rules as a pipeline result
     * (string, `Uint8Array`, `ArrayBuffer`, else JSON). Omit for an empty body.
     * Streaming is not available here; a route that streams has no responder.
     */
    body?: unknown;
}
/**
 * What the request looked like by the time every gate had passed. The same
 * values the route receives, never the `Request` itself: its body has already
 * been read to parse and to verify the signature, so it cannot be read again.
 */
interface HttpRespondRequest {
    /** Parsed request body, by the same content-type rules the route sees. */
    body: HttpRequestBody;
    /**
     * Raw request headers, lower-cased and unfiltered, so `authorization`
     * arrives verbatim wherever the caller sent one. A responder that logs or
     * echoes this map leaks the bearer; read `principal` for identity instead.
     */
    headers: Readonly<Record<string, string>>;
    /** Resolved path parameters. */
    params: Readonly<Record<string, string>>;
    /** Request method. */
    method: HttpMethod;
    /** Matched route pattern. */
    path: string;
    /** The admitted principal, where the mount or the route demanded one. */
    principal?: Principal;
}
/** Everything a {@link HttpResponder} is given. */
interface HttpRespondContext {
    /** The request, as the route sees it. */
    request: HttpRespondRequest;
    /**
     * The pipeline, already running. Awaiting it answers with the finished
     * exchange in hand, which is what the framework does when no responder is
     * configured. Returning without touching it answers now and leaves the
     * pipeline running detached.
     *
     * Rejections are already claimed by the framework, so ignoring this
     * promise is safe: a failure reaches the route's `.error()` handler and the
     * error events either way. Await it only to read the result.
     */
    finished: Promise<Exchange>;
}
/**
 * Decides when the caller is answered, and with what.
 *
 * Called once per request, after every gate has passed (method and path
 * match, body limit, body parse, signature verification, and the mount's
 * credential check where it has one) and after the pipeline has been
 * started. Rejections are unaffected: a bad signature is still a 401 and the
 * responder never runs.
 *
 * The response is sent when the function returns, so the function decides
 * whether the caller waits:
 *
 * A descriptor is sent as soon as it is returned. Returning `undefined`
 * defers to the pipeline instead: the dispatcher waits for `finished` and
 * answers with its result, exactly as when the option is absent. So one
 * responder can decide per request.
 *
 * ```ts
 * // Acknowledge a webhook, then process. `finished` is never touched.
 * respond: () => ({ status: 202 })
 *
 * // Answer with something derived from the finished pipeline.
 * respond: async ({ finished }) => ({ status: 200, body: (await finished).body })
 *
 * // Answer a status ping at once; let a real delivery take the normal path.
 * respond: ({ request }) =>
 *   isPing(request.body) ? { status: 202 } : undefined
 * ```
 *
 * Omitting the option entirely keeps the framework's own behaviour, which is
 * to await the pipeline and serialise its result. That path also carries
 * streaming and the deferral acknowledgement; a responder carries neither,
 * so a route that streams does not configure one.
 */
type HttpResponder = (ctx: HttpRespondContext) => HttpResponseDescriptor | undefined | Promise<HttpResponseDescriptor | undefined>;
/** Server-side options accepted by `http({...})` when used with `.from(...)`. */
interface HttpServerOptions {
    /**
     * Path pattern with `:param` segments. Examples: `"/orders"`,
     * `"/orders/:id"`, `"/tenants/:tenant/users/:user"`. Trailing slashes
     * are normalised away.
     */
    path: string;
    /** HTTP method to accept. Defaults to `"GET"`. */
    method?: HttpMethod;
    /**
     * Named mount under `http.mounts` this route belongs to. The mount, not
     * the route, decides authentication: a mount with an effective validator
     * is a wall (every route 401s without a valid token), a mount with
     * `auth: false` is public. The one route-level escalation is
     * `.authorize()`, which forces credential verification even on a public
     * mount; there is no route-level way to weaken a mount's posture.
     *
     * `path` is relative to the mount's prefix (a route `"/orders/:id"` on a
     * mount at `"/api"` serves `/api/orders/:id`).
     *
     * When omitted, the route resolves only to a mount literally named
     * `"default"`; if the plugin declares mounts and none is named
     * `default`, omitting `mount` fails loudly at subscribe rather than
     * silently landing a route on the wrong surface.
     */
    mount?: string;
    /**
     * Attach the exact wire bytes of the request body to the exchange as
     * `routecraft.http.rawBody` (a `Uint8Array`). Needed to verify webhook
     * signatures manually: providers sign the raw bytes, and re-serialising
     * the parsed body is not byte-faithful. Defaults to `false`.
     *
     * Opt-in because of retention and exposure, not cost: the bytes already
     * exist in memory during parsing, but attaching them pins a buffer of up
     * to `maxBodySize` for the exchange lifetime and surfaces raw payload
     * bytes to anything that logs or serialises the exchange headers.
     */
    rawBody?: boolean;
    /**
     * Declarative webhook-signature verification. When set, the plugin
     * verifies the raw request bytes against the configured header before
     * any route step runs; a missing, invalid, or expired signature returns
     * 401 and emits `auth:rejected` with `scheme: "signature"`. Independent
     * of the mount's bearer wall; place webhook routes whose only credential
     * is the signature itself on a public mount (`auth: false`).
     *
     * Only valid on body-bearing methods; configuring it on `GET`, `HEAD`,
     * `DELETE`, or `OPTIONS` throws RC5003 at construction. For providers
     * whose scheme is not built in, use `rawBody: true` and verify in a
     * route step instead. See {@link HttpWebhookSignatureOptions}.
     */
    signature?: HttpWebhookSignatureOptions;
    /**
     * Decide when the caller is answered, and with what. Omit it and the
     * framework awaits the pipeline and serialises its result, which is what
     * every route did before this option existed.
     *
     * The webhook form is the reason it exists:
     *
     * ```ts
     * respond: () => ({ status: 202 })
     * ```
     *
     * That answers `202` the moment the gates pass and leaves the pipeline
     * running detached. Bird, Stripe and Svix all treat a slow response as a
     * failed delivery and redeliver, and the Standard Webhooks specification
     * says to acknowledge before processing, so a webhook whose work takes tens
     * of seconds cannot answer with its result.
     *
     * What a responder costs, all of it load-bearing:
     *
     * - **A refusal only reaches the sender if it happens before the answer.**
     *   `.authorize()` runs inside the pipeline, so on a responder that answers
     *   early a denial stops the work without the caller being able to tell it
     *   from acceptance. A route that must be able to refuse its caller does
     *   not answer early.
     * - **A detached failure has nowhere to go but the error channel.** It
     *   reaches the route's `.error()` handler and the ordinary error events
     *   (`route:error`, `context:error`, `route:exchange:failed`), and nothing
     *   else, because the response has already gone. Give such a route an
     *   `.error()` handler.
     * - **Answering early removes the backpressure the caller's wait provided.**
     *   `.throttle()` and `.concurrency()` before `.from()` still apply, but
     *   their defaults (`mode: "queue"` with no `maxQueue`, `mode: "delay"`)
     *   cap how many run at once while the wait line grows without limit, and
     *   every queued exchange pins its parsed body. Under the redelivery burst
     *   this exists for, that is unbounded heap. Bound admission instead, with
     *   `.concurrency({ maxQueue })` or `mode: "reject"`.
     * - **A responder cannot stream and cannot carry a deferral.** Both live
     *   on the framework's own path, so a route that streams omits the option.
     *   An exchange body that turns out to be a stream is cancelled once the
     *   pipeline finishes, since nothing will read it and it may hold a socket
     *   or a file descriptor.
     * - **`/openapi.json` advertises only the rejection codes** for a route with
     *   a responder, because the document cannot know what a function returns.
     *   A route wanting documented success codes omits the option.
     * - **Two combinations are refused outright** (`RC5003`, at subscribe): a
     *   responder alongside `.batch()`, because a buffered message is not
     *   in-flight work and an answer would outlive the delivery; and, at
     *   request time, a responder once shutdown has begun, which answers `503`
     *   with `retry-after` so the sender redelivers to the next instance.
     *   Both refuse a responder that would have awaited the pipeline too, since
     *   nothing can tell the two apart before calling it.
     *
     * A detached run is still the route's in-flight work, so a graceful
     * shutdown waits for it within the context's drain deadline.
     *
     * @see {@link HttpResponder}
     */
    respond?: HttpResponder;
}
/**
 * Inbound HTTP message produced by the http source. Reaches the route
 * handler as the `body`. The parsed shape depends on `Content-Type`:
 *
 * - `application/json` -> parsed object.
 * - `text/*` -> string.
 * - `application/x-www-form-urlencoded` -> object built from URLSearchParams.
 * - `multipart/form-data` -> `FormData` (with `File` entries for uploads).
 * - other / no body -> `Uint8Array` (possibly empty).
 *
 * The route is free to swap the body in a `.transform(...)` step; the
 * dispatcher only reads the post-pipeline body for the response.
 *
 * Typed as `unknown` on purpose: the concrete runtime shape is only known
 * from the request's `Content-Type` (parsed object for JSON, `string` for
 * text, plain object for url-encoded form, `FormData` for multipart, or
 * `Uint8Array` for anything else). Route steps narrow it, typically via an
 * `.input()` schema. A union including `unknown` would collapse to `unknown`
 * anyway, so the alias states the honest contract and keeps the per-type
 * mapping in this doc comment.
 */
type HttpRequestBody = unknown;
/**
 * Hint shape for influencing the response. Populated by writing the matching
 * headers on the exchange somewhere in the pipeline; the dispatcher reads
 * them when building the response object.
 */
interface HttpResponseHint {
    status?: number;
    contentType?: string;
    headers?: Readonly<Record<string, string>>;
}
declare module "@routecraft/routecraft" {
    interface RoutecraftHeaders {
        /** Request method as received from the client. */
        "routecraft.http.method"?: HttpMethod;
        /** Matched route pattern (e.g. `/orders/:id`). */
        "routecraft.http.path"?: string;
        /** Raw URL the client sent (path + query). */
        "routecraft.http.url"?: string;
        /** Resolved path parameters keyed by name. */
        "routecraft.http.params"?: Readonly<Record<string, string>>;
        /** Query string parameters as a flat object. Repeated keys keep the last value. */
        "routecraft.http.query"?: Readonly<Record<string, string>>;
        /**
         * Raw request headers as a flat lower-cased map. This is the open-ended,
         * pass-through wire-header remainder (mirrors `routecraft.mail.rawHeaders`);
         * the parsed request envelope (method, path, query, params) is promoted to
         * its own keys above.
         */
        "routecraft.http.rawHeaders"?: Readonly<Record<string, string>>;
        /**
         * Exact wire bytes of the request body. Only present when the route
         * opted in via `http({ rawBody: true })`; empty-body requests carry an
         * empty array. Use for manual webhook-signature verification or any
         * consumer that needs byte-faithful input.
         */
        "routecraft.http.rawBody"?: Uint8Array;
        /** Override the response status code. */
        "routecraft.http.response.status"?: number;
        /** Override the response Content-Type. */
        "routecraft.http.response.contentType"?: string;
        /** Extra response headers merged into the final Response. */
        "routecraft.http.response.headers"?: Readonly<Record<string, string>>;
    }
}

/**
 * What execution one returns when a route defers.
 *
 * A durable defer cannot hold a caller: the resume payload arrives in
 * hours or days and the process will be restarted first. So the run that
 * reaches a `.defer()` terminates there and replies immediately with this value
 * instead of the route's declared output. The real output flows to the
 * route's destinations on execution two.
 *
 * Every source renders it in its own terms (`202` plus this body on
 * `http()`, the value itself on `direct()`, a log line on `cron()` /
 * `simple()` / file sources, an ack on queue sources), which is why a route
 * with a reachable durable defer has output type `Output | Deferred`.
 *
 * The value is deliberately transport-shaped and JSON-safe: it crosses the
 * wire to whoever called the route.
 */
interface Deferred {
    readonly status: "deferred";
    /** The deferred exchange's deferral id. */
    readonly deferralId: string;
    /** Signed, single-use token that resumes it. */
    readonly token: string;
    /**
     * JSON Schema rendering of what a valid resume payload looks like, when the
     * deferring step declared a schema and it exposes one (Zod, ArkType and
     * the AI SDK bridge do through the non-standard `~standard.jsonSchema`
     * extension). Absent otherwise, and absent whenever the site declared no
     * schema at all; validation always runs against the live schema at
     * resume, so nothing depends on this being present.
     */
    readonly schema?: unknown;
    /** When the deferral expires, ISO-8601. Absent when `.defer()` declared no `ttl`. */
    readonly expiresAt?: string;
}
/**
 * Whether a value is the framework's own {@link Deferred} acknowledgment.
 *
 * Transports call this on a route's terminal body to decide how to render
 * it. It is a brand check rather than a shape check on purpose: a route
 * whose real output happens to have `status: "deferred"` must not be
 * mistaken for a deferred exchange.
 */
declare function isDeferred(value: unknown): value is Deferred;
/**
 * JSON Schema for the {@link Deferred} acknowledgment, draft 2020-12.
 *
 * The shape a transport publishes when it advertises that a tool or route
 * may defer: the MCP server derives `oneOf: [Output, Deferred]` for a
 * deferrable tool's `outputSchema` from this rendering. Closed for
 * additional properties so the advertised contract is exactly the value
 * {@link createDeferred} mints.
 */
declare const DEFERRED_JSON_SCHEMA: {
    readonly type: "object";
    readonly description: "The run deferred at a durable deferral. The resume payload is delivered out of band with the resume token, and the real result is produced when the run continues.";
    readonly properties: {
        readonly status: {
            readonly const: "deferred";
        };
        readonly deferralId: {
            readonly type: "string";
        };
        readonly token: {
            readonly type: "string";
        };
        readonly schema: {
            readonly description: "JSON Schema of what a valid resume payload looks like, when the deferring step declared a schema that renders one.";
        };
        readonly expiresAt: {
            readonly type: "string";
            readonly format: "date-time";
        };
    };
    readonly required: readonly ["status", "deferralId", "token"];
    readonly additionalProperties: false;
};
/**
 * Standard Schema for the {@link Deferred} acknowledgment.
 *
 * Exists so surfaces that reason in schema arms (the MCP server's
 * advertised-output arms are the shipped consumer) can carry the
 * acknowledgment as an ordinary `StandardSchemaV1` next to a route's own
 * `.output()` schema. Validation accepts the framework's own acknowledgment
 * by brand first, so a genuine `Deferred` value always passes whatever a
 * structural check would say, and falls back to the structural check for
 * values that crossed a process boundary and lost the brand.
 */
declare const deferredSchema: StandardSchemaV1<unknown, Deferred>;

/**
 * Public types for the ops plugin's health surface.
 *
 * The status vocabulary and the report shape are the external contract an
 * uptime monitor and an orchestrator match against, so both are add-only:
 * fields may be added, never removed or repurposed.
 */

/**
 * The four-member health vocabulary.
 *
 * - `up`: serving normally.
 * - `degraded`: serving with reduced capability. A circuit breaker is holding
 *   calls off, or the route was deliberately taken offline. Never pages.
 * - `down`: cannot serve at all. For a route this means its source gave up
 *   producing; nothing it exists to serve is being served.
 * - `inactive`: deliberately out of the picture. A finished one-shot route, a
 *   route stopped cleanly, or an indicator muted for maintenance. Excluded
 *   from aggregation entirely.
 *
 * New signals map into these rather than extending them; their richer state
 * belongs in the per-component `details` map.
 */
type HealthStatus = "up" | "degraded" | "down" | "inactive";
/**
 * How widely a failure is felt, which decides whether readiness may carry it.
 *
 * - `instance`: this process or replica specifically. Peers may be fine, so
 *   taking this instance out of the load balancer's pool can genuinely help.
 * - `deployment`: every replica alike. Derotating one sends traffic to a peer
 *   that fails identically, so readiness must ignore it and only the
 *   operational signal may carry it.
 */
type FailureDomain = "instance" | "deployment";
/**
 * Which components a report covers.
 *
 * - `readiness`: instance-domain components only, because the only thing
 *   acting on this view does is move traffic between replicas, which helps
 *   only when the peers are in a better position.
 * - `all`: every component, whatever its domain. The operational view, read by
 *   humans and monitors, which never influences routing.
 */
type HealthView = "readiness" | "all";
/**
 * Where the app is in its own serving life, independent of whether any
 * dependency is healthy. This is the substance of readiness: during a deploy
 * a new container must not receive traffic until its routes are subscribed,
 * and during shutdown it must stop receiving before the process exits.
 */
type ContextState = "starting" | "started" | "stopping" | "stopped";
/**
 * Where a route is in its life, independent of whether that is healthy.
 *
 * Routecraft routes are not all long-running: a one-shot source runs, does its
 * work, and closes. Without this distinction such a route would either look
 * permanently `up` (a lie) or trip readiness when it finished (a false page).
 *
 * - `running`: started, still live.
 * - `completed`: stopped after doing work successfully. A finished one-shot.
 * - `stopped`: stopped cleanly without ever succeeding (shutdown, or a source
 *   that had nothing to do).
 * - `offline`: taken out of service by an operator. Reports `degraded`,
 *   never pages.
 * - `disabled`: held back by its own `.enabled()` predicate, with the reason
 *   in `details.reason`. Reports `inactive`, so it is listed and excluded
 *   from aggregation: a capability whose credentials were never supplied is
 *   a configuration state the operator chose, and paging on it would make
 *   every deliberately-dormant route an incident. Distinct from `offline`,
 *   which is a running deployment having capability taken away from it, and
 *   from `failed`, which is a route that should be running and is not.
 * - `failed`: not running when it should be. Its source gave up producing.
 */
type RouteLifecycle = "running" | "completed" | "stopped" | "offline" | "disabled" | "failed";
/** A circuit breaker's position, mirroring routecraft's breaker events. */
type CircuitState = "open" | "half-open";
/**
 * A component's status transition, as carried by `plugin:ops:health:changed`.
 *
 * Emitted as a component changes rather than derived by re-reading the whole
 * report, so an operator alerts on the transition instead of polling for it.
 */
interface HealthChange {
    component: "context" | "route" | "indicator";
    /** The component's name; the reserved id `context` for the serving lifecycle. */
    name: string;
    from: HealthStatus;
    to: HealthStatus;
}
/**
 * A value allowed in a component's `details` map.
 *
 * Structural facts only: enums, numbers, booleans. Never an error message.
 * Health answers whether a component can serve; what went wrong and why is
 * carried by logs and telemetry, which are not readable by everyone who can
 * reach this endpoint.
 */
type HealthDetailValue = string | number | boolean;
/** Component-owned diagnostic context. Structural facts only. */
type HealthDetails = Record<string, HealthDetailValue>;
/** What a component reports. */
interface Health {
    status: HealthStatus;
    details?: HealthDetails;
}
/** A component as it appears in a report. */
interface HealthComponent extends Health {
    /**
     * How widely this component's failure is felt. Only `instance` components
     * appear in the readiness view.
     */
    domain: FailureDomain;
    /** Milliseconds since this component last reported. Indicators only. */
    ageMs?: number;
}
/**
 * A report body. This shape is the external contract, so it is add-only:
 * fields may be added, never removed or repurposed.
 *
 * There is deliberately no separate `ready` flag. It would be exactly
 * `status !== "down"` on whichever view produced the report, and a derivable
 * field named `ready` on the operational aggregate invites the one mistake
 * this design exists to prevent: routing traffic on the deployment-wide
 * signal. Read `status`, and read it from `/health/ready` when the answer
 * decides where traffic goes.
 */
interface HealthReport {
    /**
     * Which components this report covers. Carried on the body so a consumer
     * holding a report can tell the operational aggregate from the routing
     * signal, rather than having to remember which path produced it.
     */
    view: HealthView;
    status: HealthStatus;
    /** The app's own serving lifecycle. Always present, always instance-domain. */
    context: HealthComponent;
    routes: Record<string, HealthComponent>;
    indicators: Record<string, HealthComponent>;
}
/** The liveness body. Deliberately carries no component state. */
interface LivenessReport {
    status: "up";
    uptime: number;
}
/**
 * Exposure of the per-component `details` maps.
 *
 * - `always`: serve details to every caller.
 * - `when-authenticated`: serve details only to a caller the mount's
 *   effective validator admits (the ops mount's own `auth`, else the
 *   server's). Written explicitly with no validator in scope it fails the
 *   boot: the operator asked for a gate and there is nothing to gate with.
 *   As the unwritten default with no validator it collapses to `never`,
 *   with a startup warning naming the ways out: a missing diagnostic is
 *   visible and self-correcting, a leak is silent, and indicator details are
 *   arbitrary app-supplied objects.
 * - `never`: never serve details.
 *
 * The gate withholds per-component diagnostics and nothing else. It does not
 * hide topology: component names are the keys of the always-served status
 * maps, and the per-component paths answer 404 for an unknown id in every
 * mode. An app that must not disclose its route inventory puts the ops
 * listener somewhere the public cannot reach it.
 */
type HealthDetailsExposure = "always" | "when-authenticated" | "never";
/** Health endpoint configuration. */
interface OpsHealthOptions {
    /** Exposure of per-component `details`. Defaults to `when-authenticated`. */
    details?: HealthDetailsExposure;
}
/** Options for {@link opsPlugin}. */
interface OpsPluginOptions {
    /**
     * Named server (`defineConfig({ servers })`) to mount the health paths on.
     * Defaults to `"default"`.
     *
     * A dedicated ops port is a second named server the surface points at, which
     * is how an internal-only surface is expressed. Bind that server somewhere
     * the probes can reach: a Kubernetes `httpGet` probe comes from the kubelet
     * against the pod IP and a reverse-proxy check comes from the proxy, so
     * neither reaches `127.0.0.1`. Only a Docker `HEALTHCHECK`, which runs
     * inside the container, does. Keep the port private at the network layer
     * rather than by binding loopback.
     */
    server?: string;
    /**
     * Validator for the details gate: `health.details: "when-authenticated"`
     * admits callers through this, falling back to the server's validator when
     * unset. It is not a wall. The health surface answers every probe without
     * a credential whatever this says, because an orchestrator's probe carries
     * none and a health endpoint that answers it 401 is a health endpoint that
     * restarts the pod. `health.details: "always"` is the way to serve
     * details to every caller.
     *
     * The management tiers under `/ops` identify their caller through this
     * same validator, and each tier's own {@link OpsTier} value decides what
     * that identity must carry.
     *
     * `false` follows the server plugin's meaning unchanged: the mount
     * declares no wall, while the inherited validator stays reachable for
     * anything that pulls identity rather than demanding it. So the details
     * gate still admits an authenticated caller, and a scope-gated tier,
     * which does demand it, is refused at boot as a contradiction rather than
     * quietly enforced through a validator the mount opted out of.
     */
    auth?: HttpAuth | false;
    /** Health endpoint configuration. */
    health?: OpsHealthOptions;
    /**
     * The management API's exposure, one field per tier. Every tier is
     * disabled unless named here, so an app that configures nothing serves
     * health and answers 404 on every `/ops` path.
     *
     * See {@link OpsTier} for what each value means. A scope string needs a
     * wall to enforce it, so one written where this mount declares none
     * (no `auth` here and none on its server, or an explicit `auth: false`)
     * fails the boot rather than admitting everyone.
     */
    tiers?: OpsTiers;
    /** Indicators to register. See `defineIndicator`. */
    indicators?: readonly Indicator[];
}
/** The `ops` config key. */
type OpsConfig = OpsPluginOptions;
/** How an indicator is declared. */
interface IndicatorDefinition {
    /** Unique name. Becomes the key in the report and the path segment. */
    name: string;
    /**
     * No report within this window makes the indicator `down` (stale).
     *
     * Optional. With it, the indicator is expected on a cadence, which is right
     * for a probe route. Without it the indicator is only as fresh as its last
     * push, which is the correct reading for one fed from a business route that
     * may legitimately be idle for hours.
     */
    maxAge?: Duration;
    /**
     * How widely this dependency's failure is felt. Defaults to `deployment`,
     * which is right for anything reached over the network with shared
     * credentials: every replica would fail the same way, so it must page
     * without ever moving traffic.
     */
    domain?: FailureDomain;
    /**
     * Bind this indicator to a route's exchange outcomes: a completed exchange
     * reports up, a failed exchange reports down, and no exchange within
     * `maxAge` goes stale. The route needs no health code at all.
     *
     * For probe routes only, where the exchange is the health check by
     * construction. Binding a business route would make every expected refusal
     * (a caller without the scope, a validation error, a business rule saying
     * no) report the dependency down, which is the escalation this design
     * exists to prevent.
     */
    route?: string;
}
/**
 * A registered indicator: both the declaration and the push handle.
 *
 * Inert until an ops plugin binds it to a context. Ledgers are keyed by
 * context rather than held in a closure slot, so one module-scope handle
 * serves any number of live contexts.
 */
interface Indicator {
    readonly name: string;
    readonly definition: Readonly<IndicatorDefinition>;
    /**
     * Report this dependency healthy.
     *
     * Anything passed in `details` is published on the health endpoint, which
     * may admit unauthenticated callers. Pass structural facts, never an error
     * message: `err.message` from a connection or auth failure routinely carries
     * hosts, usernames, and provider text. Log the error where it happened.
     */
    up(details?: HealthDetails): void;
    /**
     * Report this dependency unhealthy.
     *
     * The same rule as {@link Indicator.up}: `details` reaches the endpoint, so
     * it carries structural facts and never an error message.
     */
    down(details?: HealthDetails): void;
    /** Mark the indicator inactive: it reports `inactive` and never pages until it reports again. */
    inactive(): void;
}
/**
 * One management tier's admission rule.
 *
 * - `false` (and unset): the tier is disabled and its paths answer 404.
 * - `true`: the tier is open and needs no credential of its own.
 * - a scope string: the caller's principal must carry that scope.
 *
 * The mount's `auth` (its own, or the named server's, per the server
 * plugin's inheritance) decides WHO the caller is; this value decides what
 * that identity must carry. The two are deliberately separate: the same
 * validator serves every tier, and only the requirement differs.
 *
 * Disabled answers 404 rather than 403 so an unconfigured instance
 * discloses nothing about what it could expose, and so the rule is the one
 * an ingress proxy would enforce in front of it.
 */
type OpsTier = boolean | string;
/**
 * The management tiers, individually exposed. Unset is `false`, so an app
 * that configures nothing answers 404 on every management path.
 *
 * `operations` (taking a route offline, resetting a breaker) is named in
 * the design and deliberately not delivered yet; it slots in here without
 * reshaping anything.
 */
interface OpsTiers {
    /** `GET /ops/routes` and `GET /ops/routes/{id}`. */
    introspection?: OpsTier;
    /** `POST /ops/routes/{id}/exchanges`. */
    dispatch?: OpsTier;
    /**
     * `GET /ops/events`, the context event bus tailed as Server-Sent Events.
     *
     * Its own tier rather than a corner of introspection: the route listing
     * describes an app's shape, while the tail carries what it is doing right
     * now, exchange failures and auth decisions included. An operator who
     * wants one is not thereby asking for the other.
     */
    events?: OpsTier;
}
/**
 * The scope name this project documents for the introspection tier.
 *
 * A convention, not a default: every tier defaults to `false`, and the value
 * an operator writes is any string their tokens carry.
 */
declare const OPS_SCOPE_INTROSPECTION = "ops:introspection";
/** The scope name this project documents for the dispatch tier. */
declare const OPS_SCOPE_DISPATCH = "ops:dispatch";
/** The scope name this project documents for the events tier. */
declare const OPS_SCOPE_EVENTS = "ops:events";
/**
 * A read-only resource another package contributes to the management API,
 * served under the introspection tier at `GET /ops/{name}` and
 * `GET /ops/{name}/{segment...}`.
 *
 * The ops plugin lives in core and knows routes, exchanges and events.
 * What an ecosystem package keeps alongside them (an agent's sessions) is
 * listable through the same door and the same tier without core learning
 * what it is: the contributor answers the two reads, and the mount owns
 * admission, method handling and the wire.
 *
 * Read-only by contract. A resource that needs to act on something is the
 * operations tier's business and slots in there when it ships.
 *
 * A throw from either read is answered as a 500 carrying the error's code
 * and never its message; `RC5059` (a malformed limit or cursor) is the one
 * the caller owns and is answered as a 400 with the message.
 *
 * @template TItem - What the collection lists and the item view describes;
 *   plain JSON, since it goes on the wire as the mount serialises it
 */
interface OpsResource<TItem = unknown> {
    /**
     * The path segment under `/ops`. `routes` and `events` are the mount's
     * own and refused.
     */
    readonly name: string;
    /**
     * The collection, filtered by the request's query parameters. The
     * contributor pages, with `parsePageQuery()`, `takePage()` and
     * `decodeCursor()` from core: a present `nextCursor` means there is
     * more, exactly as for the route collection, and a resource whose whole
     * collection fits one page returns it without one.
     */
    list(query: Readonly<Record<string, string>>): Promise<OpsPage<TItem>>;
    /**
     * One item, addressed by the decoded path segments after the resource
     * name. `undefined` answers 404.
     */
    describe(segments: readonly string[]): Promise<TItem | undefined>;
}
/**
 * A collection response. Never a bare array, from the first release: a
 * present `nextCursor` means there is more, and a correct client follows
 * it even against a collection that does not produce one today.
 */
interface OpsPage<T> {
    items: T[];
    /** Opaque keyset cursor. Absent on the last page. */
    nextCursor?: string;
}
/**
 * One deferral as `GET /ops/deferrals` renders it.
 *
 * Distinct from the store's own `DeferralSummary`, and only in its
 * timestamps: a store answers in `Date`, and the wire has no such thing.
 * Left as `Date` on this type, `JSON.stringify` would still send strings
 * and every consumer of the client would be typed for a value it never
 * receives. Every closed vocabulary keeps its union, so a consumer can
 * switch exhaustively and a renamed state fails their build rather than
 * silently taking the other branch.
 *
 * What is absent is as deliberate as what is here. Never the resume
 * token, which is the credential; never the stored exchange, which is the
 * caller's data and can be anything; never the step state or the
 * resume-payload schema. A listing answers what is waiting, on what, and
 * for how long.
 */
interface OpsDeferralSummary {
    /** Deferral id, distinct from the deferred exchange's own id. */
    id: string;
    /** The route the deferred exchange belongs to, and re-enters on resume. */
    routeId: string;
    state: DeferralState;
    /** What the work is waiting for, or was waiting for when it settled. */
    waitingFor: DeferralWaitingFor;
    /**
     * Whether a delivery claim is outstanding. A claimed deferral is still
     * waiting, and is not resumable while the claim holds: whoever took it
     * owns telling the route.
     */
    claimed: boolean;
    /** ISO 8601. */
    deferredAt: string;
    /** ISO 8601. Absent means no deadline. */
    expiresAt?: string;
    /** How it settled. Absent while it is waiting. */
    outcome?: {
        kind: DeferralOutcome["kind"];
        /** ISO 8601. When it stopped waiting, which is what retention measures from. */
        at: string;
        reason?: string;
        /** Who resumed it. Only ever set on a `resumed` outcome. */
        by?: {
            subject: string;
            issuer?: string;
            clientId?: string;
        };
    };
}
/**
 * JSON Schema renderings of a route's declared schemas, when the schema
 * library exposes the non-standard `~standard.jsonSchema` extension. A
 * library without it yields nothing here; the live schema is what
 * validation runs against either way, so nothing depends on these.
 */
interface OpsRouteSchemas {
    body?: unknown;
    headers?: unknown;
}
/**
 * A route as the management API presents it.
 *
 * `dispatchable` is observed rather than inferred: a `direct()` ingress
 * registers the route in the capability registry when it subscribes, and
 * that registration is the door `POST .../exchanges` goes through. A cron-,
 * mail- or http-sourced route has no such door and says so here rather than
 * failing at dispatch time.
 *
 * `enabled` is reported separately because `dispatchable` alone cannot carry
 * both meanings. A route held back by its `.enabled()` predicate never
 * subscribes, so it is not in the capability registry either, and without
 * this field it would be indistinguishable from a cron-sourced route that
 * simply has no dispatch door. One is a configuration state an operator can
 * change; the other is the shape of the route.
 */
interface OpsRouteSummary {
    id: string;
    dispatchable: boolean;
    /**
     * False only while the route's `.enabled()` predicate is holding it back.
     * True for every route that declares no predicate, so an existing consumer
     * reading this field sees the state it already assumed.
     */
    enabled: boolean;
    /** Source kinds, in declaration order (`direct`, `cron`, `mail`, ...). */
    sources: string[];
    /** The route declares a route-entry `.authorize()`. */
    requiresPrincipal: boolean;
    title?: string;
    description?: string;
    tags?: string[];
    /**
     * The remote this route was imported from, for a route another instance
     * exposes and `defineConfig({ remotes })` made dispatchable here. Absent
     * for a route this instance defines. Additive: an existing consumer that
     * never reads it sees the listing it always saw.
     */
    remote?: string;
}
/** One route in full. Adds the schema renderings to the summary. */
interface OpsRouteDetail extends OpsRouteSummary {
    input?: OpsRouteSchemas;
    output?: OpsRouteSchemas;
}
/** Documented filters on `GET /ops/routes`. */
interface OpsRouteFilter {
    /** Only routes that do (or do not) have a dispatch door. */
    dispatchable?: boolean;
    /** Exact route id match, not a prefix. */
    id?: string;
    /** Routes carrying a source of this kind. */
    source?: string;
}
/** A page request against the route collection. */
interface OpsRouteQuery extends OpsRouteFilter {
    limit?: number;
    after?: string;
}
/**
 * One item from the event tail.
 *
 * `dropped` and `heartbeat` are the tail's own signals rather than bus
 * events: a slow reader must learn that it missed something instead of
 * silently seeing a gap, and an idle app must still put a byte on the wire
 * often enough that an intermediary does not reap the connection.
 */
type OpsEventTailItem = {
    kind: "event";
    /** The bus event's name, which rides the SSE `event` field. */
    name: string;
    /**
     * The frame's payload, already rendered to JSON.
     *
     * Rendered when the event is emitted rather than when the reader takes
     * it, for two reasons. A bus payload may carry `exchange.body`, which
     * the framework deliberately leaves mutable, so a reference held until
     * the reader catches up could report a value that never existed at the
     * moment it was emitted. And holding a few hundred payloads by
     * reference pins whatever they reach, which on a route moving large
     * bodies is all of it. Rendering unpins that; the tail's byte budget
     * is what bounds what remains.
     */
    data: string;
} | {
    kind: "dropped";
    count: number;
} | {
    kind: "heartbeat";
};
/**
 * What a dispatch produced.
 *
 * A deferral is an outcome, not an error: a route that reaches a durable
 * `.defer()` replies with the acknowledgment every other surface returns,
 * and the operator at the terminal is often exactly who the deferral waits for.
 * A drop is separate from a failure because they need different answers: a
 * drop means a filter said no, a failure means something broke.
 */
type OpsDispatchOutcome = {
    outcome: "completed";
    body: unknown;
} | {
    outcome: "deferred";
    deferral: Deferred;
} | {
    outcome: "dropped";
    message: string;
};

/**
 * Base interface for all adapters (sources, destinations, transformers, filters, etc.).
 * Adapters can expose an optional `adapterId` string for logging (e.g. "routecraft.adapter.log").
 */
interface Adapter {
    /**
     * Dotted identifier used for log and trace labels, by convention
     * "<vendor>.adapter.<name>" (e.g. "routecraft.adapter.mail"). The last
     * segment is shown in step events and logs. Optional so inline adapter
     * objects (e.g. `{ aggregate: fn }`) stay ergonomic; framework-shipped
     * adapters always set it.
     */
    adapterId?: string;
    /**
     * Observability hook for the FETCH slot: given the value the fetch
     * produced, return details to attach to the step's completion event
     * (`details.metadata`). Fires for `.enrich()` and for a fetch-only adapter
     * in `.to()`.
     *
     * Derive the result from the arguments, never from state written during the
     * call: one adapter instance serves every exchange on a route, so a field
     * set by one call is routinely read back by another.
     *
     * @param result - Value the fetch resolved to
     * @param exchange - Exchange the call ran against
     */
    getMetadata?(result: unknown, exchange?: Exchange<unknown>): StepOutcomeMetadata;
    /**
     * Observability hook for the SEND slot: given the receipt headers the send
     * recorded through {@link SendContext} (or `undefined` when it recorded
     * none), return details to attach to the step's completion event. Fires for
     * a send-resolved `.to()`.
     *
     * Named separately from {@link Adapter.getMetadata} so an adapter filling
     * both slots never has to sniff which contract it was handed. The same
     * no-instance-state rule applies.
     *
     * @param receipts - Receipt headers collected during the send
     * @param exchange - Exchange the call ran against
     */
    getSendMetadata?(receipts: unknown, exchange?: Exchange<unknown>): StepOutcomeMetadata;
}
interface Step<T extends Adapter> {
    operation: OperationType;
    adapter: T;
    /**
     * Display name shown in traces, logs, and step events instead of the
     * raw OperationType. Set automatically by registerDsl for sugar methods
     * (e.g., "log" instead of "tap", "schema" instead of "validate").
     * When absent, the operation field is used.
     */
    label?: string;
    /**
     * When true, runPipeline will not emit generic route:step:started/route:step:completed
     * events for this step. The step is responsible for emitting its own
     * lifecycle events with the correct exchange identity.
     */
    skipStepEvents?: boolean;
    /**
     * Execute this step and report what happened. The executor owns all
     * scheduling: steps no longer see the work queue or the remaining
     * pipeline, they describe an outcome and the engine routes it.
     *
     * The exchange is typed as Exchange at runtime (body is unknown);
     * the builder chain preserves body types for the next step, but custom
     * steps receive an untyped exchange. Narrow or assert body type if needed.
     */
    execute(exchange: Exchange, ctx: StepContext): Promise<StepOutcome>;
}
/**
 * Observability metadata a step may attach to its outcome (e.g. LLM token
 * usage, HTTP status codes). The executor copies it into the
 * `route:step:completed` event payload. Guidelines: small values only
 * (IDs, names, counts, codes), no large bodies. Outcome-scoped on purpose:
 * `Step` instances are shared across exchanges, so per-execution data must
 * never live on the step itself.
 */
type StepOutcomeMetadata = Record<string, unknown>;
/**
 * What a step did with its exchange. Returned from {@link Step.execute};
 * the pipeline executor translates outcomes into scheduling:
 *
 * - `continue`: run the remaining steps against `exchange` (the common case;
 *   `exchange` is usually a rewrapped derivation of the input).
 * - `complete`: skip the remaining steps and complete the exchange
 *   successfully (route-scope cache hit).
 * - `drop`: halt the exchange. The step has already called `markDropped`
 *   and emitted its drop events (filter reject, choice unmatched,
 *   parse-drop); the executor schedules nothing.
 * - `branch`: run `steps` and then the remaining steps against `exchange`
 *   (choice routes into the matched branch).
 * - `fanOut`: schedule each child exchange independently through the
 *   remaining steps (split).
 * - `defer`: deferral `exchange` durably and exit the pipeline, to be resumed
 *   later at the next step. Produced by `.defer()`. The executor
 *   serializes the exchange, writes the deferral, emits
 *   `route:exchange:deferred`, and schedules nothing further for it;
 *   `request` carries what it needs to do that (the `expect` schema, the
 *   TTL, and where the defer sits in the route). Only the framework's own
 *   defer step can produce a coherent `request`, so a custom step
 *   returning this kind without one is rejected with `RC5032` rather than
 *   silently dropping the exchange.
 *
 * The union is OPEN across minor releases: new kinds may be added as the
 * engine grows (the executor exhaustively handles every kind it ships
 * with). Code that consumes outcomes (custom wrappers, tests) should pass
 * unrecognised kinds through rather than throwing on them.
 */
type StepOutcome = {
    kind: "continue";
    exchange: Exchange;
    metadata?: StepOutcomeMetadata;
} | {
    kind: "complete";
    exchange: Exchange;
    metadata?: StepOutcomeMetadata;
} | {
    kind: "drop";
    metadata?: StepOutcomeMetadata;
} | {
    kind: "branch";
    exchange: Exchange;
    steps: Step<Adapter>[];
} | {
    kind: "fanOut";
    exchanges: Exchange[];
} | {
    kind: "defer";
    exchange: Exchange;
    request: DeferRequest;
};
/**
 * The abort surface of a step execution, handed to function-form steps
 * (`.process()`, `.transform()`, `.to()`, `.enrich()`) as their trailing
 * argument. {@link StepContext} extends it, so adapter authors
 * implementing {@link Step.execute} read the same field from `ctx`.
 *
 * `signal` fires when an enclosing `.timeout()` deadline expires (step
 * scope or route scope): promises cannot be cancelled, so the framework
 * discards the losing run's outcome, and this signal is how the run
 * itself finds out. Forward it into cancellation-aware IO (`fetch`, DB
 * drivers) so abandoned work actually stops instead of running to
 * completion in the background:
 *
 * ```ts
 * .timeout(3000)
 * .process(async (ex, { signal }) => {
 *   const res = await fetch(url, { signal });
 *   return { ...ex, body: await res.json() };
 * })
 * ```
 *
 * The signal's abort reason is the `RC5011` timeout error. It is absent
 * when no timeout wraps the step. Route shutdown does NOT fire it:
 * graceful drain lets in-flight exchanges complete (sources observe
 * shutdown via their own `Subscription.signal`).
 */
interface StepSignalContext {
    /** Fires when an enclosing `.timeout()` deadline expires. */
    readonly signal?: AbortSignal;
}
/**
 * Narrow executor capability handed to {@link Step.execute}.
 *
 * `takePending` atomically removes and returns pending sibling exchanges
 * matching the predicate; it exists for join-style steps (aggregate) that
 * consume their split siblings. The queue itself is never exposed, so
 * steps cannot reorder, duplicate, or corrupt scheduling.
 *
 * Extends {@link StepSignalContext}: `signal` fires when an enclosing
 * `.timeout()` deadline expires, so steps doing cancellation-aware IO
 * can abort abandoned work.
 */
interface StepContext extends StepSignalContext {
    takePending(predicate: (exchange: Exchange) => boolean): Exchange[];
    /**
     * Run each provided sub-pipeline against its own exchange, all in
     * parallel, resolving once every path has settled (`Promise.allSettled`
     * semantics: one path throwing does not reject the call). Each path runs
     * as an isolated nested pipeline whose failure fires that exchange's
     * default error events (the caller's route-scope `.error()` handler does
     * NOT run for a path) but does not affect the caller or sibling paths.
     * The queue itself stays private, so a fan-out step (e.g. `multicast`)
     * cannot reorder or corrupt the parent's scheduling.
     */
    runPaths(runs: ReadonlyArray<{
        steps: Step<Adapter>[];
        exchange: Exchange;
    }>): Promise<void>;
    /**
     * Run ONE sub-pipeline against its own exchange as an isolated nested run,
     * resolving with the run's outcome. Like a single {@link runPaths} entry,
     * but the result is reported back rather than swallowed, so a caller (e.g.
     * `dispatch`'s `failover` strategy) can decide what to do next based on
     * whether the run failed or was deliberately dropped. A failing path still
     * fires that exchange's default error events (the caller's route-scope
     * `.error()` handler does NOT run for it) and never rejects this call.
     */
    runPath(run: {
        steps: Step<Adapter>[];
        exchange: Exchange;
    }): Promise<{
        failed: boolean;
        dropped: boolean;
        error?: unknown;
        /**
         * True when an outer abort signal (a route-scope timeout abandoning the
         * attempt) truncated the run before or while it was scheduling steps.
         * An aborted run is neither a success nor a target failure; callers
         * (dispatch failover) must not treat it as a handled exchange.
         */
        aborted?: boolean;
    }>;
    /**
     * Capture the downstream continuation for the currently-executing step:
     * returns a runner that, when later invoked with an exchange, runs it
     * through the steps that FOLLOW this one as a detached, route-tracked
     * pipeline (with its own `route:exchange:started` / `:completed` lifecycle).
     *
     * Snapshot it synchronously inside `execute`; the runner stays valid after
     * `execute` resolves. Used by `debounce` to release a held exchange after
     * its quiet window closes without re-running the steps before it. Because
     * the released exchange is the route's PRIMARY flow (not a side-effect
     * clone), the detached run honors the route-scope `.error()` handler and
     * enforces the route's `.output()` schemas before completing, and it
     * inherits no abort signal from the capturing attempt.
     */
    captureDownstream(): (exchange: Exchange) => Promise<{
        failed: boolean;
        dropped: boolean;
    }>;
}
/**
 * Construction dependencies handed to a {@link Consumer} by the route
 * runtime, one bag per (source, consumer) pair.
 *
 * `options` is deliberately `unknown` here: route definitions store
 * heterogeneous consumer configurations, so the typed options surface
 * lives on the builder method that stages the consumer (e.g.
 * `.batch(...)`). Each consumer narrows and defaults its own options in
 * its constructor; it owns the interpretation of that value.
 */
type ConsumerDeps = {
    context: CraftContext;
    definition: RouteDefinition;
    channel: ProcessingQueue<Message>;
    options: unknown;
};
/**
 * Constructable consumer class. The single deps-bag parameter (rather
 * than positional arguments) keeps every consumer class assignable to
 * `ConsumerType<Consumer>` without casts, so route definitions can store
 * any consumer implementation uniformly.
 */
type ConsumerType<T extends Consumer = Consumer> = (new (deps: ConsumerDeps) => T) & {
    /**
     * The consumer may hold a message before the pipeline runs, the way
     * `.batch()` fills a buffer. A held message is not the route's in-flight
     * work, so a graceful shutdown can drain past it, and a transport that
     * answers its caller before the pipeline finishes cannot promise the
     * delivery will run. Declared by the consumer rather than inferred from
     * its class, so a new consumer states its own answer instead of an
     * unrelated file guessing.
     */
    readonly buffers?: boolean;
};
/**
 * Internal envelope flowing from a source adapter to its consumer through the
 * route's processing queue.
 *
 * @property message - Raw payload as the adapter handed it to `handler(...)`.
 *   When `parse` is set this is typically the unparsed bytes/string; when
 *   `parse` is unset this is the already-parsed value used directly as the
 *   exchange body.
 * @property headers - Optional exchange headers attached by the adapter.
 * @property parse - Optional parser the runtime invokes as a synthetic first
 *   step before any user-defined steps run. When provided, the runtime
 *   builds a derived exchange via
 *   `DefaultExchange.rewrap(exchange, { body: await parse(exchange.body) })`
 *   inside the same try/catch that handles step errors, so a parse
 *   failure flows through the route's `errorHandler` and
 *   `route:exchange:failed` event path. See `adapters/shared/parse.ts` for
 *   the `OnParseError` semantics. If `parse` resolves to `undefined`
 *   the body is explicitly set to `undefined` (the rewrap respects an
 *   explicit `body: undefined`), not left as the previous value.
 * @property parseFailureMode - Decides how the synthetic parse step handles
 *   a thrown parse error. `"fail"` (default) and `"abort"` throw `RC5016`
 *   so `route:exchange:failed` fires; `"drop"` instead emits `route:exchange:dropped`
 *   with `reason: "parse-failed"`. Adapters set this from their
 *   `onParseError` option; the source loop additionally rethrows for
 *   `"abort"` so the source dies. See #187.
 *
 * parse-error-handling work in #187. Their shape may evolve.
 */
type Message<T = unknown> = {
    /**
     * The payload. When `parse` is set this is the RAW pre-parse value
     * (e.g. a JSON line string), typed as `T` only after the synthetic
     * parse step runs; adapters narrow at the call site.
     */
    message: T;
    headers?: ExchangeHeaders;
    parse?: (raw: unknown) => unknown | Promise<unknown>;
    parseFailureMode?: OnParseError;
};
interface Consumer<O = unknown> {
    context: CraftContext;
    channel: ProcessingQueue<Message>;
    definition: RouteDefinition;
    options: O;
    /**
     * Register the route handler. The handler receives the same
     * {@link Message} envelope that sources enqueue, so a pass-through
     * consumer forwards it untouched while merging consumers (e.g. batch)
     * synthesize new envelopes. At runtime the envelope's `message` and the
     * returned exchange's body are untyped (unknown); the builder chain is
     * typed, so narrow or assert in the handler if you need body fields.
     *
     * When the envelope carries a `parse` function the route captures it on
     * the exchange internals so `runPipeline` can apply it as a synthetic
     * first pipeline step. Consumers that merge multiple messages parse
     * items eagerly during enqueue and hand over a `parse`-less envelope.
     */
    register(handler: (envelope: Message) => Promise<Exchange>): void;
}
/**
 * Internal queue API for route source→consumer flow. Sources enqueue messages; the consumer handler is set by the route and receives messages. Used by DefaultRoute.
 *
 * @template T - Message type (typically Message with message + headers)
 */
interface ProcessingQueue<T = unknown> {
    enqueue(message: T): Promise<Exchange>;
    setHandler(handler: (message: T) => Promise<Exchange>): Promise<void> | void;
    clear(): Promise<void> | void;
}
/** Exchange snapshot attached to terminal exchange events. */
type ExchangeSnapshot = {
    id: string;
    headers: Record<string, unknown>;
    body: unknown;
};
/** Shared identity fields on per-exchange events. */
type ExchangeScoped = {
    routeId: string;
    exchangeId: string;
    correlationId: string;
};
/**
 * What every tool-call event carries.
 *
 * `session` names the conversation the call was made in, when the agent
 * was dispatched with one. A session's boundary turn runs on the exchange
 * that deferred, which may be an earlier caller's, so the exchange identity
 * alone cannot say which conversation a call belongs to; the session can.
 */
type ToolCallScoped = ExchangeScoped & {
    toolCallId: string;
    toolName: string;
    session?: string;
};
/**
 * Every event the framework emits, mapped to its detail payload.
 *
 * Event names are a FIXED, finite set: identity (route id, plugin id,
 * step label) lives in the payload, not the name. Subscribe with exact
 * names and filter on payload fields (see {@link forRoute}), or use the
 * single catch-all `"*"` to observe everything (telemetry-style taps).
 *
 * Declared as an interface so ecosystem packages can add their own events
 * via declaration merging, mirroring `ErrorCodeRegistry` / `StoreRegistry`:
 *
 * ```typescript
 * declare module "@routecraft/routecraft" {
 *   interface EventDetailsMap {
 *     "myext:thing:happened": { routeId: string; thing: string };
 *   }
 * }
 * ```
 */
interface EventDetailsMap {
    "context:starting": Record<string, never>;
    "context:started": Record<string, never>;
    "context:stopping": {
        reason?: unknown;
    };
    /**
     * Shutdown finished. `forced` is true when stage one did not drain inside
     * `shutdown.timeout` and in-flight execution was abandoned, with
     * `pending` naming the routes that still had work. A clean stop carries
     * `forced: false` and an empty `pending`, so the shape is stable and a
     * subscriber can count forced shutdowns without reading exit codes.
     */
    "context:stopped": {
        forced: boolean;
        pending: string[];
    };
    "context:error": {
        error: unknown;
        route?: Route;
        exchange?: Exchange<unknown>;
    };
    "auth:success": {
        subject: string;
        scheme: string;
        source: string;
    };
    "auth:rejected": {
        reason: string;
        scheme: string;
        source: string;
    };
    "route:registered": {
        routeId: string;
        route: Route;
    };
    /**
     * A route's enablement predicate was evaluated and the verdict CHANGED
     * (or was reached for the first time). Not emitted when a refresh
     * re-confirms what the route was already doing, so a five-minute cadence
     * on a stable predicate is silent rather than a heartbeat.
     *
     * `reason` is present only when `enabled` is false, and is what ops
     * reports next to the route.
     */
    "route:enablement:changed": {
        routeId: string;
        route: Route;
        enabled: boolean;
        reason?: string;
    };
    "route:starting": {
        routeId: string;
        route: Route;
    };
    "route:started": {
        routeId: string;
        route: Route;
    };
    "route:stopping": {
        routeId: string;
        route: Route;
        reason?: unknown;
        exchange?: Exchange<unknown>;
    };
    "route:stopped": {
        routeId: string;
        route: Route;
        exchange?: Exchange<unknown>;
    };
    /**
     * A source subscription rejected: the source gave up producing (e.g. a
     * connection-backed source exhausted its reconnect attempts) and the route
     * is about to stop. Distinct from `route:stopping`, which also fires for
     * orderly shutdowns; subscribe to this one to alarm on a dead channel.
     */
    "route:source:failed": {
        routeId: string;
        route: Route;
        /** `adapterId` of the failed source, when the adapter declares one. */
        adapter?: string;
        error: unknown;
    };
    "route:error": {
        routeId: string;
        error: unknown;
        route?: Route;
        exchange?: Exchange<unknown>;
    };
    "route:error:caught": {
        routeId: string;
        error: unknown;
        route?: Route;
        exchange?: Exchange<unknown>;
    };
    "route:exchange:started": ExchangeScoped;
    "route:exchange:completed": ExchangeScoped & {
        duration: number;
        exchange?: ExchangeSnapshot;
    };
    "route:exchange:failed": ExchangeScoped & {
        duration: number;
        error: unknown;
        exchange?: ExchangeSnapshot;
    };
    "route:exchange:dropped": ExchangeScoped & {
        reason: string;
        exchange?: ExchangeSnapshot;
    };
    "route:exchange:restored": ExchangeScoped & {
        source: string;
    };
    /**
     * The exchange deferred at a `.defer()` and execution one ended. This is
     * that run's terminal event, in place of `:completed`: the body the
     * source receives is the `Deferred` acknowledgment, and the route's real
     * output flows on execution two.
     */
    "route:exchange:deferred": ExchangeScoped & {
        deferralId: string;
        /** Address of the deferring step; the continuation is what follows it. */
        position: number;
        /** When the deferral stops being resumable, when a `ttl` was declared. */
        expiresAt?: Date;
    };
    /**
     * A deferred exchange was revived and its continuation is about to run.
     * Execution two's `:started` follows immediately, and that run gets its
     * own `:completed` / `:failed` / `:dropped`.
     */
    "route:exchange:resumed": ExchangeScoped & {
        deferralId: string;
        position: number;
        /** Who resumed it, when the resume ingress had an authenticated principal. */
        resumedBy?: PrincipalRef;
    };
    /**
     * A deferral stopped being resumable because its `ttl` elapsed. Fires
     * when a late resume discovers it, and (once the sweeper lands) when the
     * sweeper reaches it first. The deferred route's error channel receives
     * `RC5047` alongside, which is where a re-ask belongs.
     */
    "route:exchange:expired": ExchangeScoped & {
        deferralId: string;
        expiresAt: Date;
    };
    "route:step:started": ExchangeScoped & {
        operation: OperationType | string;
        adapter?: string;
    };
    "route:step:completed": ExchangeScoped & {
        operation: OperationType | string;
        adapter?: string;
        duration: number;
        metadata?: Record<string, unknown>;
    };
    "route:step:failed": ExchangeScoped & {
        operation: OperationType | string;
        adapter?: string;
        duration: number;
        error: string;
    };
    /** A step threw; `operation` is the step label (was `route:<id>:step:<label>:error`). */
    "route:step:error": {
        routeId: string;
        error: unknown;
        route?: Route;
        exchange?: Exchange<unknown>;
        operation: string;
    };
    "route:batch:started": {
        routeId: string;
        batchSize: number;
        batchId: string;
    };
    "route:batch:flushed": {
        routeId: string;
        batchSize: number;
        batchId: string;
        waitTime: number;
        reason: "size" | "time";
    };
    "route:batch:stopped": {
        routeId: string;
        batchId: string;
    };
    "route:retry:started": ExchangeScoped & {
        /** Label of the wrapped step, or `"route"` when `scope === "route"`. */
        stepLabel: string;
        scope: "route" | "step";
        maxAttempts: number;
    };
    /** A failed attempt will be re-attempted after `backoffMs`. */
    "route:retry:attempt": ExchangeScoped & {
        stepLabel: string;
        scope: "route" | "step";
        attemptNumber: number;
        maxAttempts: number;
        /** Actual wait before the next attempt (factor growth + jitter applied). */
        backoffMs: number;
        lastError?: unknown;
    };
    "route:retry:stopped": ExchangeScoped & {
        stepLabel: string;
        scope: "route" | "step";
        attemptNumber: number;
        success: boolean;
        /**
         * Present when `success` is false: the raw error that caused the
         * final failure (non-retryable error, exhausted attempts, or the
         * last failure when shutdown interrupted the backoff).
         */
        error?: unknown;
    };
    "route:delay:started": ExchangeScoped & {
        stepLabel: string;
        scope: "step";
        delayMs: number;
    };
    "route:delay:stopped": ExchangeScoped & {
        stepLabel: string;
        scope: "step";
        delayMs: number;
        elapsed: number;
        /** True when route shutdown cut the wait short (the step still ran). */
        cancelled: boolean;
    };
    "route:timeout:started": ExchangeScoped & {
        /** Label of the wrapped step, or `"route"` when `scope === "route"`. */
        stepLabel: string;
        scope: "route" | "step";
        timeoutMs: number;
    };
    /** The deadline fired before the guarded execution settled; RC5011 follows. */
    "route:timeout:expired": ExchangeScoped & {
        stepLabel: string;
        scope: "route" | "step";
        timeoutMs: number;
        elapsed: number;
    };
    /** The guarded execution settled within the deadline. */
    "route:timeout:stopped": ExchangeScoped & {
        stepLabel: string;
        scope: "route" | "step";
        timeoutMs: number;
        elapsed: number;
    };
    /** No token was free; the exchange will wait `waitMs` before admission (delay mode). */
    "route:throttle:delayed": ExchangeScoped & {
        /** Label of the wrapped step, or `"route"` when `scope === "route"`. */
        stepLabel: string;
        scope: "route" | "step";
        /** Pacing wait applied before this exchange is admitted. */
        waitMs: number;
        /** Partition key the exchange was charged against, when `key` is set. */
        key?: string;
        /** Gate label, when `.throttle({ label })` is set. */
        label?: string;
    };
    /** The exchange was admitted through the rate limiter. */
    "route:throttle:passed": ExchangeScoped & {
        stepLabel: string;
        scope: "route" | "step";
        /** True when the exchange had to wait for a token before admission. */
        waited: boolean;
        /** Total time spent in the throttle gate (0 on the fast path). */
        elapsed: number;
        /** Partition key the exchange was charged against, when `key` is set. */
        key?: string;
        /** Gate label, when `.throttle({ label })` is set. */
        label?: string;
    };
    /** The exchange exceeded the rate and was rejected (reject mode); `RC5013` follows. */
    "route:throttle:rejected": ExchangeScoped & {
        stepLabel: string;
        scope: "route" | "step";
        /** Time until a token would free, for a Retry-After style hint. */
        retryAfterMs: number;
        /** Partition key the exchange was charged against, when `key` is set. */
        key?: string;
        /** Gate label, when `.throttle({ label })` is set. */
        label?: string;
    };
    /** The breaker tripped to open: failures reached the threshold (from closed) or a probe failed (from half-open). */
    "route:circuitBreaker:opened": ExchangeScoped & {
        /** Label of the wrapped step, or `"route"` when `scope === "route"`. */
        stepLabel: string;
        scope: "route" | "step";
        /** Counted failures in the window at the moment the breaker tripped. */
        failureCount: number;
        /** Configured failure threshold. */
        threshold: number;
        /** Cooldown before the breaker will admit a probe (half-open). */
        cooldownMs: number;
        /** Breaker label, when `.circuitBreaker({ label })` is set. */
        label?: string;
    };
    /** Cooldown elapsed; the breaker admitted a probe call to test recovery. */
    "route:circuitBreaker:halfOpen": ExchangeScoped & {
        stepLabel: string;
        scope: "route" | "step";
        label?: string;
    };
    /** A probe succeeded; the breaker recovered to closed. */
    "route:circuitBreaker:closed": ExchangeScoped & {
        stepLabel: string;
        scope: "route" | "step";
        label?: string;
    };
    /** A call was rejected because the breaker is open (or half-open at capacity); a `fallback` ran or `RC5025` followed. */
    "route:circuitBreaker:rejected": ExchangeScoped & {
        stepLabel: string;
        scope: "route" | "step";
        /** Breaker state at rejection time. */
        state: "open" | "half-open";
        /** Time until the breaker would admit a probe, for a Retry-After style hint (0 when half-open at capacity). */
        retryAfterMs: number;
        label?: string;
    };
    /** All slots were busy; the exchange joined the wait queue (queue mode). */
    "route:concurrency:queued": ExchangeScoped & {
        /** Label of the wrapped step, or `"route"` when `scope === "route"`. */
        stepLabel: string;
        scope: "route" | "step";
        /** The exchange's position in the wait queue (1 = next to be admitted). */
        queueDepth: number;
        /** Partition key the exchange was charged against, when `key` is set. */
        key?: string;
        /** Limiter label, when `.concurrency({ label })` is set. */
        label?: string;
    };
    /** A slot was acquired and the wrapped work began. */
    "route:concurrency:acquired": ExchangeScoped & {
        stepLabel: string;
        scope: "route" | "step";
        /** True when the exchange had to queue before a slot freed. */
        waited: boolean;
        /** Slots in use (including this one) at admission time. */
        inUse: number;
        key?: string;
        label?: string;
    };
    /** The held slot was released (work settled: success, drop, or failure). */
    "route:concurrency:released": ExchangeScoped & {
        stepLabel: string;
        scope: "route" | "step";
        /** How long the work held the slot, in milliseconds. */
        heldMs: number;
        key?: string;
        label?: string;
    };
    /** The exchange was failed fast with `RC5026`; `RC5026` follows. */
    "route:concurrency:rejected": ExchangeScoped & {
        stepLabel: string;
        scope: "route" | "step";
        /** `"busy"`: reject mode, all slots in use. `"queue-full"`: queue mode, wait line at `maxQueue`. */
        reason: "busy" | "queue-full";
        key?: string;
        label?: string;
    };
    "route:error-handler:invoked": ExchangeScoped & {
        originalError: unknown;
        failedOperation: string;
        /**
         * `"route"` for the route-level (`.error()` before `.from()`)
         * catch-all handler; `"step"` for a wrapper-scope handler
         * attached to a single step (`.error()` after `.from()`).
         */
        scope?: "route" | "step";
        /** Step label when `scope === "step"`. */
        stepLabel?: string;
    };
    "route:error-handler:recovered": ExchangeScoped & {
        originalError: unknown;
        failedOperation: string;
        recoveryStrategy: string;
        scope?: "route" | "step";
        stepLabel?: string;
    };
    "route:error-handler:failed": ExchangeScoped & {
        originalError: unknown;
        failedOperation: string;
        recoveryStrategy?: string;
        scope?: "route" | "step";
        stepLabel?: string;
    };
    "route:cache:hit": ExchangeScoped & {
        /** Label of the wrapped step, or `"route"` when `scope === "route"`. */
        stepLabel: string;
        scope: "route" | "step";
        key: string;
    };
    "route:cache:miss": ExchangeScoped & {
        stepLabel: string;
        scope: "route" | "step";
        key: string;
        /** True when the wrapped step dropped the exchange (filter/halt). */
        dropped?: boolean;
    };
    "route:cache:stored": ExchangeScoped & {
        stepLabel: string;
        scope: "route" | "step";
        key: string;
        /** TTL in ms when one was configured. */
        ttl?: number;
    };
    "route:cache:failed": ExchangeScoped & {
        stepLabel: string;
        scope: "route" | "step";
        /**
         * Where the failure occurred: `"key"` = key derivation threw,
         * `"get"` = provider read threw, `"inner"` = the wrapped step threw,
         * `"set"` = the provider write threw after the wrapped step succeeded.
         */
        phase: "key" | "get" | "inner" | "set";
        key?: string;
        error: string;
    };
    "route:operation:choice:matched": ExchangeScoped & {
        branchIndex: number;
        branchLabel: "when" | "otherwise";
    };
    "route:operation:choice:unmatched": ExchangeScoped;
    /** Fan-out started: the exchange is about to be cloned to each path. */
    "route:operation:multicast:started": ExchangeScoped & {
        /** Number of paths the exchange is fanned out to. */
        pathCount: number;
    };
    /** Fan-out finished: every path has settled and the original continues. */
    "route:operation:multicast:stopped": ExchangeScoped & {
        pathCount: number;
    };
    /** A target was selected to run. For `failover`, fired once per attempt. */
    "route:operation:dispatch:selected": ExchangeScoped & {
        /**
         * The strategy that made the pick. Inlines `DispatchStrategyName`
         * (operations/dispatch.ts): this file is the dependency root and never
         * imports from operations, so keep the two unions in sync.
         */
        strategy: "failover" | "round-robin" | "weighted" | "sticky";
        /** Index of the selected target in the `.dispatch()` target list. */
        targetIndex: number;
    };
    /** `failover` ran out of targets: every one failed and none handled the exchange. */
    "route:operation:dispatch:exhausted": ExchangeScoped & {
        strategy: "failover";
        /** How many targets were tried before giving up. */
        targetCount: number;
    };
    /** The sampler admitted this exchange. */
    "route:operation:sample:passed": ExchangeScoped & {
        /** `"count"` for `every`-based sampling, `"interval"` for `intervalMs`. */
        mode: "count" | "interval";
    };
    /** The sampler dropped this exchange (between samples). */
    "route:operation:sample:dropped": ExchangeScoped & {
        mode: "count" | "interval";
    };
    /** The key was unseen; it is reserved and the exchange continues. */
    "route:operation:dedupe:pass": ExchangeScoped & {
        /** The derived key reserved for this exchange. */
        key: string;
    };
    /** The key was already reserved or committed; the exchange is dropped. */
    "route:operation:dedupe:duplicate": ExchangeScoped & {
        /** The derived key that was already seen. */
        key: string;
    };
    /** An exchange entered the debounce window and is being held (timer armed/reset). */
    "route:operation:debounce:held": ExchangeScoped & {
        /** The partition key the exchange was held under, when `key` is set. */
        key?: string;
    };
    /** A held exchange was superseded by a newer arrival in the same burst and dropped. */
    "route:operation:debounce:dropped": ExchangeScoped & {
        key?: string;
    };
    /** The quiet window (or `maxWait` cap) elapsed; the last held exchange is released downstream. */
    "route:operation:debounce:released": ExchangeScoped & {
        key?: string;
        /**
         * Why the exchange was released: `"quiet"` when the `waitMs` window
         * closed, `"maxWait"` when the `maxWaitMs` cap fired during continuous
         * activity, or `"flush"` when a drain / shutdown released it early.
         */
        reason: "quiet" | "maxWait" | "flush";
    };
    "route:agent:started": ExchangeScoped & {
        agentName?: string;
        model: string;
        toolNames: string[];
        maxTurns: number;
    };
    /**
     * A tool was refused admission to an agent's tool list by
     * `agentPlugin({ toolPolicy })` and never offered to the model.
     *
     * Emitted once per denied tool per dispatch, alongside whichever log
     * that denial produced: `warn` when a rule decided against the tool,
     * `error` when a rule threw (the tool is denied to fail closed, and
     * the warn line is suppressed so one failure is not reported twice).
     * The two channels serve different consumers: the log is for someone
     * reading text, the event is for alerting and audit, which is what a
     * policy decision needs to be queryable from.
     *
     * `reason` distinguishes a rule that decided against the tool from a
     * rule that threw (denied to fail closed) and from provenance the
     * resolver could not classify. `unknown-provenance` covers every tool
     * whose `source` is missing or carries a kind the policy surface does
     * not define, since no rule runs in either case; `toolKind` is
     * reported as `"unknown"` for both.
     */
    "route:agent:tool:denied": ExchangeScoped & {
        agentName?: string;
        toolName: string;
        toolKind: string;
        reason: "rule" | "rule-error" | "unknown-provenance";
    };
    /**
     * A call the model made was refused by the tool's guard, at call time,
     * on a tool the model could see and was allowed to attempt.
     *
     * Distinct from `denied`, which fires when a policy withholds a tool at
     * selection time so the model never sees it. Counting the two together
     * would mix "this agent may not have that tool" with "this agent asked
     * for something its grant does not cover", and it is the second that
     * tells an operator an agent is probing the edges of its allowlist.
     * That signal is the whole reason an allowlist is worth auditing.
     *
     * The payload is deliberately bounded to identity plus the error code.
     * The refused input is what carries the secret material (a command line
     * can hold a token someone passed as an argument), and a refusal is
     * exactly the case where that input is least trustworthy, so it is not
     * carried here even under snapshot capture.
     */
    "route:agent:tool:refused": ToolCallScoped & {
        /** Error code when the guard threw a Routecraft error, e.g. `RC5002`. */
        rc?: string;
    };
    "route:agent:tool:invoked": ToolCallScoped & {
        _snapshot: {
            input: unknown;
        };
    };
    "route:agent:tool:result": ToolCallScoped & {
        _snapshot: {
            output: unknown;
        };
        duration: number;
    };
    "route:agent:tool:error": ToolCallScoped & {
        errorName: string;
        _snapshot: {
            error: unknown;
        };
        duration: number;
    };
    "route:agent:block:loaded": ExchangeScoped & {
        toolCallId: string;
        blockName: string;
        _snapshot: {
            output: unknown;
        };
        duration: number;
    };
    "route:agent:block:error": ExchangeScoped & {
        toolCallId: string;
        blockName: string;
        errorName: string;
        _snapshot: {
            error: unknown;
        };
        duration: number;
    };
    "route:agent:finished": ExchangeScoped & {
        agentName?: string;
        model: string;
        finishReason: string;
        inputTokens?: number;
        outputTokens?: number;
        totalTokens?: number;
    };
    /**
     * Emitted after every successful agent dispatch alongside
     * `route:agent:finished`. Carries the full token breakdown for the
     * dispatch so consumers can compute cost without subscribing to the
     * broader lifecycle event.
     *
     * Cache fields are present only when the provider reports them (e.g.
     * Anthropic with prompt caching enabled).
     */
    "route:agent:usage": ExchangeScoped & {
        agentName?: string;
        model: string;
        inputTokens?: number;
        outputTokens?: number;
        totalTokens?: number;
        cacheReadTokens?: number;
        cacheWriteTokens?: number;
    };
    "route:agent:error": ExchangeScoped & {
        agentName?: string;
        model: string;
        error: unknown;
    };
    /**
     * A message arrived for a session whose turn is running and was queued
     * for the next turn boundary. The caller was acknowledged, not answered.
     */
    "route:agent:session:queued": ExchangeScoped & {
        agentName: string;
        session: string;
        /** Inbox depth after this message was appended. */
        depth: number;
        /** The message asked for the running turn to be interrupted. */
        interrupt: boolean;
    };
    /** A running turn was cancelled by a later message with `interrupt: true`. */
    "route:agent:session:interrupted": ExchangeScoped & {
        agentName: string;
        session: string;
    };
    /**
     * A turn started on a session whose previous turn was cut short by a
     * restart: its partial transcript was kept, its inbox was intact, and
     * every background call it was waiting on was reported lost.
     */
    "route:agent:session:restored": ExchangeScoped & {
        agentName: string;
        session: string;
        lostBackground: number;
    };
    /**
     * A turn ended with work outstanding (background calls running, or
     * messages queued), so its exchange's continuation was stored: what a
     * completion, the queued messages, or a boot revives to run the next
     * turn and the route's downstream steps.
     */
    "route:agent:session:deferred": ExchangeScoped & {
        agentName: string;
        session: string;
        deferralId: string;
        /** Messages waiting when the deferral was stored. */
        inbox: number;
        /** Background calls still running when the deferral was stored. */
        background: number;
    };
    /**
     * A stored continuation was revived and this turn is the one it runs:
     * the inbox is its user message and the route's downstream steps follow.
     * Emitted on the revived exchange, after core's `route:exchange:resumed`.
     */
    "route:agent:session:revived": ExchangeScoped & {
        agentName: string;
        session: string;
        deferralId: string;
    };
    /** A background tool dispatched its route and returned a handle to the model. */
    "route:agent:session:background:started": ExchangeScoped & {
        agentName: string;
        session: string;
        handle: string;
        toolName: string;
    };
    /** A background tool's route finished and its result was posted to the session inbox. */
    "route:agent:session:background:completed": ExchangeScoped & {
        agentName: string;
        session: string;
        handle: string;
        toolName: string;
        duration: number;
    };
    /** A background tool's route failed and the failure was posted to the session inbox. */
    "route:agent:session:background:failed": ExchangeScoped & {
        agentName: string;
        session: string;
        handle: string;
        toolName: string;
        errorName: string;
        duration: number;
    };
    "agent:registered": {
        agentId: string;
        description?: string;
        model?: string;
        source: "registered";
    };
    "agent:tool:registered": {
        toolName: string;
        description?: string;
        tags?: string[];
        source: "registered";
    };
    "server:listening": {
        server: string;
        port: number;
        host: string;
    };
    "server:failed": {
        server: string;
        error: unknown;
    };
    "server:closed": {
        server: string;
    };
    /** A protocol request was refused before authentication or SDK dispatch. */
    "server:request:rejected": {
        server: string;
        mount: string;
        reason: "host" | "origin";
    };
    /**
     * A health component changed status, so an operator can alert on the
     * transition rather than polling for it. The ops listener's own lifecycle
     * is reported by the server events above, since the ops surface mounts on a
     * named server rather than owning a socket.
     */
    "plugin:ops:health:changed": HealthChange;
    "plugin:http:request:completed": {
        method: string;
        path: string;
        status: number;
        durationMs: number;
        routeId?: string;
        principal?: {
            subject: string;
        } | undefined;
        /**
         * Why a streaming response ended badly, when it did.
         *
         * A stream fails after its status line is already on the wire, so
         * `status` still reports what was sent and cannot say the response
         * broke. Without this an operator counting completions would score a
         * truncated stream as a 200 success, and only the logs would disagree.
         * Absent on every response that completed normally.
         */
        error?: {
            name: string;
            message: string;
        };
    };
    /** The plugin's `apply()` hook is about to run, at context build time. */
    "plugin:applying": {
        pluginId: string;
        pluginIndex: number;
    };
    /** The plugin's `apply()` hook returned. */
    "plugin:applied": {
        pluginId: string;
        pluginIndex: number;
    };
    /**
     * The plugin's `start()` hook is about to run, after every route has
     * signalled readiness or the readiness backstop elapsed, so it is not
     * proof that every source is listening.
     * Until 0.7 this pair bracketed `apply()`; that phase is now
     * `plugin:applying` / `plugin:applied`, so the event vocabulary matches
     * the lifecycle: applying, starting, stopping.
     */
    "plugin:starting": {
        pluginId: string;
        pluginIndex: number;
    };
    /** The plugin's `start()` hook resolved. */
    "plugin:started": {
        pluginId: string;
        pluginIndex: number;
    };
    "plugin:stopping": {
        pluginId: string;
        pluginIndex: number;
    };
    "plugin:stopped": {
        pluginId: string;
        pluginIndex: number;
    };
}
/**
 * Union of all event names: the keys of {@link EventDetailsMap} plus the
 * catch-all `"*"` accepted by `on()` / `once()` (never emitted itself).
 */
type EventName = keyof EventDetailsMap;
type EventPayload<K extends EventName> = {
    ts: string;
    contextId: string;
    details: EventDetailsMap[K];
    /** The exact event name that was emitted. Set by context.emit(). */
    _event: string;
};
type EventHandler<K extends EventName> = (payload: EventPayload<K>) => void | Promise<void>;
/**
 * Event names whose payload carries a `routeId`, i.e. the events
 * {@link forRoute} can meaningfully filter. Subscribing `forRoute` to a
 * route-less event (context, auth, plugin lifecycle) would silently never
 * fire, so the constraint makes that a compile error instead.
 */
type RouteScopedEventName = {
    [K in EventName]: "routeId" extends keyof EventDetailsMap[K] ? K : never;
}[EventName];
/**
 * Wrap an event handler so it only fires for events whose payload carries
 * the given `routeId`. Identity lives in the payload (event names are a
 * fixed set), so per-route subscription is a filter:
 *
 * ```typescript
 * ctx.on("route:exchange:failed", forRoute("orders", ({ details }) => {
 *   console.error("orders failed:", details.error);
 * }));
 * ```
 */
declare function forRoute<K extends RouteScopedEventName>(routeId: string, handler: EventHandler<K>): EventHandler<K>;

/**
 * Callable validator function. Receives the full exchange, returns the
 * validated (possibly coerced) body value. Throws on failure.
 *
 * @template T - Input body type
 * @template R - Output body type (may differ if the validator coerces)
 */
type CallableValidator<T = unknown, R = T, Ex extends Exchange<T> = Exchange<T>> = (exchange: Ex) => R | Promise<R>;
/**
 * Validator adapter: validates the exchange body and returns the validated
 * value. Throws on failure (e.g., RC5002 for schema violations).
 *
 * @template T - Input body type
 * @template R - Output body type
 */
interface Validator<T = unknown, R = T> extends Adapter {
    validate: CallableValidator<T, R>;
}
/**
 * Creates a Validator adapter from a Standard Schema. On success the
 * validated (possibly coerced) value replaces the exchange body. On
 * failure throws RC5002 with formatted issue details.
 *
 * Use with `.validate(schema(...))` or the `.schema()` sugar method.
 *
 * @param standardSchema - Any Standard Schema v1 implementation (Zod, Valibot, ArkType, etc.)
 * @returns A Validator adapter that throws RC5002 on failure
 *
 * @example
 * ```ts
 * import { z } from "zod";
 * craft()
 *   .from(source)
 *   .validate(schema(z.object({ name: z.string() })))
 *   .to(dest)
 * ```
 */
declare function schema<S extends StandardSchemaV1>(standardSchema: S): Validator<unknown, StandardSchemaV1.InferOutput<S>>;

/**
 * Machine-readable detail attached to an `RC5038` error's cause, naming
 * exactly what the principal lacked. Read it off `error.cause` to drive a
 * consent flow:
 *
 * ```ts
 * const missing = (err.cause as InsufficientAuthority | undefined)?.missing
 * if (missing?.mode === "any") offerChoice(missing.scopes)
 * else if (missing?.scopes) requestGrant(missing.scopes)
 * ```
 *
 * Carries the scopes the principal lacked for a `scopes` refusal, and the
 * whole accepted set for an `anyScope` one, where any single entry would
 * have opened the door.
 *
 * In-process only: `RoutecraftError.toJSON()` serialises the cause's message
 * and stack, not its own properties, so a consumer reading the failure from
 * a serialised event log sees the scope names in the message text but not
 * this structured field.
 */
interface InsufficientAuthority extends Error {
    missing: {
        scopes: string[];
        /**
         * How to read `scopes`. `"all"` lists the required scopes the
         * principal lacked, every one of them needed. `"any"` lists the whole
         * accepted set of an `anyScope` check, of which ONE suffices, so a
         * consent flow can offer the choice rather than requesting all of them.
         *
         * Optional because an application throwing this shape itself (the
         * documented workaround before `anyScope` existed) predates the field;
         * `authorize()` always sets it. Absent means `"all"`.
         */
        mode?: "all" | "any";
    };
}
/**
 * Whether `error` is a refusal raised by an {@link authorize} check, as
 * opposed to the same code thrown by anything else.
 *
 * Doors use this to answer a refusal with a client status (401 / 403)
 * while an adapter's `RC5012` for a rejected upstream login stays a server
 * fault. With `caller`, only a refusal of that caller counts: raised on an
 * exchange of the route the door dispatched, about the very principal the
 * door admitted (compared by reference, the way identity is carried per
 * hop). A refusal raised further down the call chain, or of an identity the
 * pipeline substituted, is the instance's fault and does not match.
 *
 * @param error - Any thrown value
 * @param caller - The route the door dispatched and the principal it
 *   admitted (`undefined` when it admitted none)
 * @returns `true` when `authorize()` raised this exact error object, for
 *   `caller` when given
 */
declare function isAuthorizationRefusal(error: unknown, caller?: {
    routeId: string;
    principal: Principal | undefined;
}): error is RoutecraftError;
/**
 * Constraint on who is driving the request (the outermost `actor`).
 *
 * - `'none'`: reject when any actor is present. This is the DEFAULT: a
 *   capability is not reachable through delegation unless it says so, per
 *   the security-defaults policy (production-safe unconfigured default).
 * - `'any'`: accept any actor (and no actor).
 * - {@link ActorMatcher}: require an actor matching the given identity.
 * - Array: OR across entries; include `'none'` to also accept direct calls.
 * - Predicate: full custom check over `(actor, subject)`.
 *
 * Per RFC 8693 section 4.1, only the OUTERMOST actor is considered; prior
 * actors in a nested chain are audit data and never a policy input.
 */
type ActorSpec = "none" | "any" | ActorMatcher | Array<"none" | ActorMatcher> | ((actor: Principal | undefined, subject: Principal) => boolean);
/**
 * Constraint on whose authority is being exercised (the subject). All
 * provided fields must match; array-valued fields are an OR across values.
 */
interface SubjectMatcher {
    /** Subject id(s) to accept. */
    subject?: string | string[];
    /** Issuer the subject is scoped to. */
    issuer?: string;
    /** Entity profile(s) to accept (e.g. restrict a route to `ai_agent`). */
    profile?: PrincipalProfile | PrincipalProfile[];
}
/**
 * Options accepted by {@link authorize}. All criteria are AND-combined: the
 * principal must satisfy every provided constraint to pass the check.
 */
interface AuthorizeOptions {
    /**
     * Required roles. The principal must carry every listed role on
     * `principal.roles`. Roles are SUBJECT attributes: they describe who the
     * action is for and pass through delegation unchanged, so this checks the
     * subject even when an actor is driving. Defaults to no role check.
     */
    roles?: string[];
    /**
     * Required scopes. The principal must carry every listed scope on
     * `principal.scopes`. Scopes are CREDENTIAL capabilities: delegation
     * intersects them at every hop, so this checks the effective (narrowed)
     * set. Defaults to no scope check.
     */
    scopes?: string[];
    /**
     * Required scopes, any ONE of which admits the principal, where `scopes`
     * requires every one. For a scope family whose variants are
     * interchangeable at the door (`leave:read`, `leave:read:self`,
     * `leave:read:base`): any of them opens it, and the exact variant held
     * narrows what the pipeline returns further down.
     *
     * Refuses with RC5038 naming the whole accepted set rather than one
     * entry, because no single entry was required and a consent flow should
     * be able to offer the caller the choice.
     *
     * Composes with `scopes` as an AND of the two conditions: every entry of
     * `scopes`, and at least one entry of `anyScope`. Defaults to no check.
     *
     * An empty array is refused with RC2001 when the validator is built,
     * rather than read as no check. It is the one list on these options whose
     * empty form is not vacuously satisfied: a requirement of no scopes admits
     * everyone, while an accepted set naming nobody admits nobody, and a set
     * computed empty would otherwise remove a route's only scope gate in
     * silence. Omit the option to mean no check.
     */
    anyScope?: string[];
    /**
     * Whether `scopes` and `anyScope` may also be satisfied from the ACTOR's
     * scopes. Defaults to `false`, so a route that does not ask is unchanged.
     *
     * With `true` the scope checks read the subject's ring plus the OUTERMOST
     * actor's, which is how an agent exercises its own standing authority on
     * a caller's behalf: an agent legitimately holds scopes nobody who asks
     * it for something holds. Only the outermost actor is read, matching the
     * rule `actor` already follows (RFC 8693 section 4.1); prior actors in a
     * nested chain stay audit data.
     *
     * Never applies to `roles` under any combination. A role is what the
     * principal IS; scopes are what a keyring CARRIES, and only keyrings are
     * inheritable. An agent driving a request does not become the subject.
     *
     * A no-op under the default `actor: 'none'`, which admits no actor for
     * the flag to read. That combination is a harmless misconfiguration
     * rather than an error.
     *
     * It reads `actor.scopes`, so the actor has to carry some. An actor minted
     * by `delegate()` does. An actor parsed from a token's RFC 8693 `act`
     * claim does NOT: the claim has no scope member, and the parser will not
     * invent authority from an unstandardised one. For token-borne delegation,
     * map whatever your IdP emits with `ClaimMappers.actor`, or the check sees
     * an empty ring and refuses.
     *
     * The check reads the UNION of the two rings, so a caller passes on their
     * own scopes or on the agent's. The agent is not a cap: `delegate()`
     * deliberately does not intersect delegated scopes with the actor's own,
     * and this flag does not either. What an agent's grant bounds is the
     * additional authority a caller gains by going through it, which is why
     * this is opt-in per route rather than a context-wide setting: a gate that
     * must stay on the subject's own ring simply does not set it.
     */
    effective?: boolean;
    /**
     * Custom predicate for advanced checks. Return `false` to reject. Runs
     * after the built-in checks.
     */
    predicate?: (principal: Principal) => boolean;
    /**
     * Clock skew tolerance in seconds applied to the `expiresAt` check.
     * Matches the semantics of `jwt({ clockToleranceSec })` and
     * `jwks({ clockToleranceSec })`: a token whose `expiresAt` is less than
     * `clockToleranceSec` seconds in the past is still accepted. Defaults to
     * `0` (strict). Set to the same value used on the source-side verifier so
     * a token accepted at the route boundary is not rejected mid-pipeline by
     * a fraction of a second.
     */
    clockToleranceSec?: number;
    /**
     * Constrain whose authority is exercised. Throws RC5035 on mismatch.
     * Defaults to no subject constraint.
     */
    subject?: SubjectMatcher | ((subject: Principal) => boolean);
    /**
     * Constrain who is driving. Defaults to `'none'`: a principal carrying an
     * actor (a delegate acting on the subject's behalf) is rejected with
     * RC5034 unless the route explicitly admits one. See {@link ActorSpec}.
     */
    actor?: ActorSpec;
    /**
     * Maximum delegation chain length (number of nested actors). Applies only
     * once the `actor` spec admits an actor at all. Defaults to `1`: one
     * delegation hop is accepted, a re-delegated chain (agent to sub-agent)
     * throws RC5036 until a route raises the limit deliberately.
     */
    maxDelegationDepth?: number;
}
/**
 * Build a {@link CallableValidator} that **checks** the exchange carries an
 * authenticated principal and (optionally) that the principal has every
 * required role and scope, an admissible subject, and an admissible actor.
 * This is a verification primitive: it asserts an existing identity meets
 * the criteria. It does NOT issue, mint, or attach credentials to the
 * exchange (use `.authenticate()` / `.delegate()` for that), and it trusts
 * only principals established by a trusted origin.
 *
 * Delegation awareness (RFC 8693): `roles` are checked on the subject
 * (they pass through delegation), `scopes` on the effective narrowed set,
 * and the `actor` spec on the OUTERMOST actor only; nested prior actors are
 * audit data. The default `actor: 'none'` means a route is not reachable
 * through delegation unless it says so.
 *
 * Scope checks read the subject's ring alone unless `effective: true`
 * widens them to the outermost actor's as well, which is how an agent
 * exercises its own standing authority on a caller's behalf. Roles are
 * never widened that way: a role is what the principal IS, and only a
 * keyring is inheritable.
 *
 * Throws `RC5012` when no principal is present, `RC5043` when the
 * principal was restored from a deferral rather than verified live,
 * `RC5023` when a principal is present but was not established by a
 * trusted origin, `RC5020` on
 * expiry, `RC5034` when the actor is not admitted, `RC5035` when the
 * subject is not admitted, `RC5036` when the delegation chain exceeds
 * `maxDelegationDepth`, `RC5015` when the principal fails the role or
 * predicate check, and `RC5038` when a required scope is missing
 * (recoverable; the cause carries `missing.scopes`, naming the whole
 * accepted set for an `anyScope` refusal).
 *
 * Throws `RC2001` when the validator is built with an empty `anyScope`,
 * which would name an accepted set that admits nobody.
 *
 * Every refusal is recognisable through {@link isAuthorizationRefusal}, which
 * is how the `http()` source and the ops dispatch door answer a refusal of
 * the route they dispatched with 401 or 403 rather than 500.
 *
 * Most routes should declare authorization at the route boundary using the
 * pre-from `.authorize()` builder method, which wires this validator as a
 * route-entry guard. Use this function directly with `.validate(...)` only
 * when the check must run mid-pipeline (for example, after an
 * `.authenticate()` or `.delegate()` step, or inside a `.choice()` branch).
 *
 * @example Route-entry guard (preferred)
 * ```ts
 * craft()
 *   .id("delete-user")
 *   .authorize({ roles: ["admin"], actor: "none" })
 *   .from(mcp({ annotations: { destructiveHint: true } }))
 *   .to(deleteUserDestination)
 * ```
 *
 * @example Admit one named agent alongside direct callers
 * ```ts
 * craft()
 *   .id("send-reply")
 *   .authorize({
 *     scopes: ["mail:send"],
 *     actor: ["none", { subject: "agent:aria", issuer: "https://acme.example" }],
 *   })
 *   .from(direct())
 *   .to(smtp())
 * ```
 *
 * @example Any one of a scope family, satisfiable by the agent's own ring
 * ```ts
 * craft()
 *   .id("read-leave")
 *   .authorize({
 *     anyScope: ["leave:read", "leave:read:self", "leave:read:base"],
 *     effective: true,
 *     actor: ["none", { subject: "agent:aria", issuer: "https://agents.example" }],
 *   })
 *   .from(direct())
 *   .to(leaveDestination)
 * ```
 *
 * @example Mid-pipeline check (escape hatch)
 * ```ts
 * import { authorize } from "@routecraft/routecraft";
 *
 * craft()
 *   .from(http({ path: "/admin", method: "POST" }))
 *   .authenticate(() => ({ subject: "service-account", roles: ["admin"] }))
 *   .validate(authorize({ roles: ["admin"] }))
 *   .to(adminDestination)
 * ```
 */
declare function authorize(options?: AuthorizeOptions): CallableValidator<unknown, unknown>;

/**
 * Identity claims accepted by {@link authenticate}. Derived from
 * {@link Principal} so the two never drift: `kind` and `scheme` are optional
 * (they default), every other `Principal` field is carried through, and
 * `subject` stays required because every minted identity must name who it
 * represents.
 */
type PrincipalClaims = Partial<Pick<Principal, "kind" | "scheme">> & Omit<Principal, "kind" | "scheme" | "actor" | "grantId">;
/**
 * Mint an authenticated {@link Principal} from identity claims you have
 * already verified yourself.
 *
 * This is the explicit, greppable way to establish identity from a source
 * the framework cannot verify on its own: an inbound e-mail whose sender you
 * validated, a Slack event signature you checked, a webhook HMAC, and so on.
 * The returned principal is branded as authentic (see `markAuthentic`) and
 * frozen, so `authorize()` trusts it. A plain object written onto
 * `headers["routecraft.auth.principal"]` is NOT trusted: minting must be a
 * deliberate call, not an incidental header write.
 *
 * Inside a route, prefer the `.authenticate()` builder operation, which is
 * sugar over this helper. Use this function directly in tests, in custom
 * source adapters, or inside a `.process()` / `.choice()` branch where the
 * builder step does not fit.
 *
 * @throws RC5024 when `subject` is missing or empty.
 *
 * @example Mid-pipeline / custom source
 * ```ts
 * import { authenticate } from "@routecraft/routecraft";
 *
 * const principal = authenticate({
 *   scheme: "email",
 *   subject: sender.address,
 *   roles: sender.address.endsWith("@acme.com") ? ["internal"] : [],
 * });
 * ```
 */
declare function authenticate(claims: PrincipalClaims): Principal;

/**
 * Options accepted by {@link delegate}.
 */
interface DelegateOptions {
    /**
     * Scope ceiling from the caller's consent mechanism (an OAuth grant, a
     * grant table, static config). Effective scopes on the delegated
     * principal are the intersection of the subject's scopes and this
     * ceiling; omitting it leaves the subject's scopes as they are.
     *
     * The actor's OWN scopes are deliberately NOT a term. They describe what
     * the actor may do under its own identity (when it is the subject of an
     * autonomous run), which is a different question from what a user may
     * delegate to it. Intersecting them would make it impossible to grant an
     * agent something it must never do standalone: an agent with no write
     * access of its own could never be granted write access on a user's
     * behalf, because the term it lacks would strip the grant. Delegated
     * authority derives from the subject and the consent record; the actor's
     * reachability is enforced by `authorize({ actor })` at each route.
     *
     * Roles are never intersected either: the subject's roles pass through
     * (they describe who the subject IS, RFC 9068 section 2.2.3.1), and the
     * actor's own roles stay on `actor.roles` for matching.
     */
    scopes?: string[];
    /** Consent record id to carry on the delegated principal for audit. */
    grantId?: string;
}
/**
 * Mint a delegated {@link Principal}: `subject` acting through `actor`.
 *
 * This is the delegation sibling of `authenticate()`: a pure function with
 * no I/O. The caller resolves WHAT the actor may do (a consent record, an
 * OAuth grant, static config) and passes the resulting scope ceiling;
 * `delegate()` mints. Where the ceiling came from is the caller's business,
 * exactly as `authenticate()` does not care how an identity was verified.
 *
 * Semantics (see the delegation table in the docs):
 *
 * - `subject`, `roles`, `claims`, `email`, `name` pass through unchanged.
 * - `scopes` become the intersection of the subject's scopes and the
 *   `options.scopes` ceiling. The actor's own scopes are NOT a term (see
 *   {@link DelegateOptions.scopes}): an agent must be grantable something
 *   it may never do standalone.
 * - `actor` is set to the minted actor principal; a pre-existing actor
 *   nests one level down, expressing the chain (RFC 8693 section 4.1).
 *   The outermost entry is the current actor.
 * - `expiresAt` becomes the earlier of the subject's and the actor's.
 * - The result carries a fresh authenticity brand; nested actors are
 *   branded transitively because the chain is constructed here and only
 *   here.
 *
 * Routecraft supports delegation only, never impersonation (RFC 8693
 * section 1.1): the subject is always retained and the actor always named.
 *
 * @throws RC5023 when `subject` is not an authentic principal. A chain may
 *   only be built on an identity the framework already trusts; this is what
 *   keeps authenticity a property of the whole chain.
 * @throws RC5037 when `subject.mayAct` is present and no entry matches the
 *   requested actor.
 *
 * Note for custom steps calling this helper directly: the `.delegate()`
 * route operation defaults to DROPPING a non-delegated direct principal
 * when its resolver returns `undefined` (fail closed;
 * `DelegateStepOptions.otherwise: "keep"` is the opt-out). The helper
 * itself only mints. A custom step that skips minting on a missing grant
 * must decide what happens to the caller's direct principal, or the
 * continuation runs with the caller's full direct authority precisely
 * when consent is absent.
 *
 * @example
 * ```ts
 * const delegated = delegate(ex.principal, zoeIdentity, {
 *   scopes: grant.scopes,
 *   grantId: grant.id,
 * })
 * ```
 */
declare function delegate(subject: Principal, actor: PrincipalClaims, options?: DelegateOptions): Principal;

/**
 * DANGER: every principal passed to this function becomes trusted by
 * `authorize()`. Call it ONLY after you have verified the caller's identity
 * yourself. Passing an unverified or attacker-influenced principal is a
 * privilege-escalation bug, the framework cannot check your work here.
 *
 * Mark a principal as authentic and freeze it. Authenticity is the
 * framework's signal that a principal was established by a trusted origin: an
 * explicit `authenticate()` mint, or a source-side verifier (`jwt()`,
 * `jwks()`, OAuth). `authorize()` trusts only branded principals; a plain
 * object written onto `headers["routecraft.auth.principal"]` is rejected.
 *
 * Always returns a frozen copy (never the input object, so the caller's
 * principal is not mutated or frozen as a side effect), registered in the
 * private authenticity set. Idempotent: a principal that is already authentic
 * is returned unchanged.
 *
 * Returning a frozen object matters: the exchange constructor only clones an
 * unfrozen principal header, so a frozen branded principal flows downstream
 * by reference and keeps its set membership. Always use the return value;
 * never assume the argument was branded in place.
 *
 * This is a trusted primitive, exported for adapter and source authors who
 * verify identity themselves (for example a custom Slack or e-mail source).
 * Application route code should mint identities with `authenticate()` instead.
 */
declare function markAuthentic<P extends Principal>(principal: P): P;
/**
 * Whether a value is a principal that was established by a trusted origin
 * (see {@link markAuthentic}). Returns `false` for plain objects, `null`,
 * `undefined`, and non-objects.
 */
declare function isAuthentic(principal: unknown): principal is Principal;

/**
 * Whether the process is running a named development or test environment.
 *
 * Deliberately an allowlist rather than `NODE_ENV !== "production"`: an
 * unset `NODE_ENV` is the most common production misconfiguration, and
 * under the negated form it would silently relax a production guard on a
 * real deployment. Per `.standards/security.md` section 6a, the relaxed
 * mode is the one that has to be named. Shared with `@routecraft/ai`, whose
 * MCP resource guard follows the same rule.
 *
 * @internal
 */
declare function isDevelopmentRuntime(): boolean;

/**
 * Whether a token verification error represents an expired token.
 *
 * An expired token is a routine part of the client lifecycle: clients present a
 * stale cached token, receive a 401, then refresh and retry. Callers log it at
 * `debug` so the `warn` channel stays reserved for failures that genuinely
 * warrant attention (bad signature, wrong audience or issuer, malformed token).
 *
 * Detection keys off `jose`'s stable `ERR_JWT_EXPIRED` code, thrown by `jwks()`
 * and surfaced unchanged through userinfo enrichment, and also tagged on
 * `jwt()`'s expiry error so both built-in verifiers classify uniformly. `jose`
 * raises this code only for expiry, so audience and issuer mismatches
 * (`ERR_JWT_CLAIM_VALIDATION_FAILED`) correctly fall through. Validators that
 * reject expiry without this code also fall through to `warn`, the safe default
 * for an unclassified rejection.
 */
declare function isExpiredTokenError(err: unknown): boolean;
/**
 * Whether a token verification error is a server-side infrastructure failure
 * (JWKS endpoint unreachable, timed out, or returning a bad response) rather
 * than the verifier rejecting the presented token.
 *
 * The distinction matters for the HTTP status: an infrastructure failure must
 * map to 500 (so the client retries later), never to `401 invalid_token`, which
 * would make every client discard its valid cached token and stampede an
 * already-struggling IdP with refreshes. A token rejection is the opposite: it
 * must be 401 so the client refreshes. Callers therefore treat anything that is
 * NOT an infrastructure failure (and not a framework error) as a token
 * rejection, which keeps custom and built-in `jwt()` validators that throw a
 * plain `Error` mapping to 401.
 *
 * The whole `cause` chain is inspected, not just the immediate error: Node /
 * undici nest the real errno under a `fetch failed` TypeError, and a verifier
 * may wrap the underlying failure one or more levels deep. The walk is bounded
 * to guard against a self-referential `cause` cycle.
 */
declare function isInfrastructureError(err: unknown): boolean;
/**
 * Bounded vocabulary for the reasons a token-verification throw can classify
 * to. The full `auth:rejected` vocabulary is wider (`missing_header`,
 * `unsupported_scheme`, `insufficient_scope`, the api-key and signature
 * literals); this type covers only the verifier-throw classification shared by
 * the HTTP and MCP bearer paths.
 */
type AuthRejectionReason = "expired" | "infrastructure" | "invalid_token";
/**
 * Map a token-verification error to the bounded `auth:rejected` reason
 * vocabulary. Never derived from the raw error message: a custom verifier
 * controls that message and could embed the bearer token, leaking a secret
 * into an aggregator-indexed event field (see `.standards/security.md`
 * sections 4 and 10). The full error stays operator-only via the structured
 * `{ err }` log binding.
 *
 * `infrastructure` mirrors the predicate the 500 mapping uses (framework
 * errors and JWKS infrastructure failures), so the event payload always
 * matches the HTTP status the client receives.
 */
declare function classifyRejectionReason(err: unknown): AuthRejectionReason;

/**
 * Whether a verified principal's expiry has passed.
 *
 * The boundary is inclusive and floored to whole seconds, matching `jose`
 * (`exp <= now - tolerance`) and RFC 7519 section 4.1.4, which requires the
 * current time to be strictly before `exp`. A fractional `now` would put this
 * boundary up to a second ahead of the verifier's; an exclusive `>` would put
 * it a second behind and honour a token for a further second.
 *
 * Non-finite inputs fail closed: a NaN comparison is always false and would
 * silently disable the check (see `.standards/security.md` section 7).
 *
 * A principal without an `expiresAt` passes: a credential with no expiry
 * concept (an API key behind a custom validator) is a legitimate result, and
 * requiring `exp` belongs to the verifier layer (section 1), never here.
 *
 * This predicate is the single source of the boundary. Three checkpoints call
 * it: `authorize()` (RC5020), the HTTP bearer middleware, and
 * {@link principalExpirySignal}, which closes a stream when the credential
 * that admitted it lapses. All three pass the same `clockToleranceSec`, which
 * is what keeps them from disagreeing by a second on one credential; calling
 * this predicate while dropping its tolerance argument buys the appearance of
 * that guarantee without the substance.
 */
declare function isPrincipalExpired(principal: Pick<Principal, "expiresAt">, clockToleranceSec?: number): boolean;

/**
 * Mark a principal as restored from durable storage, and freeze it.
 *
 * A deferred exchange is serialized to a store and rehydrated hours or
 * days later, possibly in a different process. What comes back is the
 * SHAPE of the principal that was verified at defer time, with nothing
 * behind it: no live token, no signature check, no revocation lookup. It is
 * therefore deliberately NOT authentic. `authorize()` rejects it with
 * `RC5043`, which is the whole point of this mark: without it, a rehydrated
 * principal would be indistinguishable from a self-asserted plain object
 * and would report the confusing `RC5023` ("not established by a trusted
 * origin") instead of the actionable "this identity came back from a
 * deferral; re-verify it".
 *
 * This closes the direct route back to #355's bug class. Deferral is the
 * easiest way to reintroduce laundering, because the natural implementation
 * is to re-mark whatever principal was serialized as authentic on the way
 * back in.
 *
 * The principal remains readable: routes still see who the exchange was
 * running as, and `resumedBy` records who resumed it. What it cannot do is
 * pass an authorization check on its own.
 *
 * @param principal - The principal shape read back from a deferral.
 * @returns A frozen copy registered as restored. Always use the return
 *   value; the argument is neither mutated nor frozen.
 */
declare function markRestored<P extends Principal>(principal: P): P;
/**
 * Whether a value is a principal that was rehydrated from durable storage
 * (see {@link markRestored}). Restored principals are never authentic, so
 * this is not the inverse of `isAuthentic`: a plain self-asserted object is
 * neither.
 *
 * Returns a plain boolean rather than a type predicate on purpose. A
 * predicate here would narrow the FALSE branch of an already-`Principal`
 * value to `never`, which is not what a caller means by "this principal is
 * not restored".
 */
declare function isRestored(principal: unknown): boolean;

/**
 * Constant-time equality for a secret and a candidate presented by a caller.
 *
 * Reach for this wherever a request is admitted by comparing something it
 * carried against something the process knows: a shared secret behind a
 * custom `validator`, a signature, a digest. `===` on those returns as soon
 * as two bytes differ, and the time it took is a measurement an attacker can
 * repeat to recover the secret one byte at a time.
 *
 * Wraps `timingSafeEqual` with the explicit length guard it requires: a
 * length mismatch is an ordinary rejection, not an exception. Length itself
 * is not treated as secret; digest lengths are fixed per algorithm, so a
 * mismatch only reveals that the candidate is malformed.
 *
 * @param expected - The value the process knows
 * @param candidate - The value the caller presented
 */
declare function timingSafeStringEqual(expected: string, candidate: string): boolean;

/**
 * Identity helper for typing a {@link CraftConfig}. Returns the input
 * unchanged at runtime; at compile time it gives the literal the same
 * checking a `const config: CraftConfig = {...}` annotation does: autocomplete
 * for every key (including keys augmented by ecosystem packages such as
 * `@routecraft/ai`) and an error for any key `CraftConfig` does not declare,
 * at every nesting level.
 *
 * The parameter is deliberately not generic. TypeScript checks excess
 * properties only against a concrete target type, so a `<T extends
 * CraftConfig>` parameter let a stale or misspelled key compile and fail at
 * boot instead.
 *
 * @param config - Config object
 * @returns The same config object
 *
 * @example
 * ```typescript
 * import { defineConfig } from "@routecraft/routecraft";
 * import "@routecraft/ai"; // augments CraftConfig with `llm`, `mcp`, etc.
 *
 * export const craftConfig = defineConfig({
 *   cron: { timezone: "UTC" },
 *   llm: { providers: { openai: { apiKey: process.env.OPENAI_API_KEY! } } },
 * });
 * ```
 */
declare function defineConfig(config: CraftConfig): CraftConfig;

/**
 * Build a {@link CraftPlugin} from the value found at a given key on
 * {@link CraftConfig}. Receives the non-undefined value of `config[K]` and
 * returns a plugin whose `apply` and (optional) `teardown` participate in the
 * standard plugin lifecycle.
 *
 * @template K - Key on `CraftConfig` this applier handles
 */
type ConfigApplier<K extends keyof CraftConfig> = (options: NonNullable<CraftConfig[K]>) => CraftPlugin;
/**
 * Register a function that converts a {@link CraftConfig} key into a plugin.
 *
 * Ecosystem packages call this once at module load time (typically from a
 * side-effect import) so that setting `config[key]` becomes equivalent to
 * pushing the corresponding plugin onto `config.plugins`. Resulting plugins
 * participate in the standard lifecycle: `apply()` runs during
 * `initPlugins()`, `teardown()` runs during `context.stop()`.
 *
 * The framework invokes the applier whenever `config[key] !== undefined`.
 * Falsy values (`false`, `0`, `""`, `null`) are still passed through; only
 * `undefined` means "not set". This lets primitive-valued keys behave
 * sensibly without needing a wrapper object.
 *
 * Re-registering a key replaces the previous registration: last writer wins.
 * The registry is shared across copies of the package via `Symbol.for`, but
 * an applier registered by one copy of an ecosystem package is a different
 * function reference from the same applier registered by another copy. If
 * two copies of `@routecraft/ai` end up in the same workspace, the last one
 * to load is the one whose applier (and therefore whose `llmPlugin`
 * instance) runs. Structure your workspace to avoid duplicate copies of the
 * same ecosystem package; this registry does not transparently de-duplicate.
 *
 * @template K - Key on `CraftConfig` this applier handles
 * @param key - The `CraftConfig` key
 * @param applier - Factory that builds a plugin from the value at `config[key]`
 *
 * @example
 * ```typescript
 * declare module "@routecraft/routecraft" {
 *   interface CraftConfig {
 *     myKey?: MyOptions;
 *   }
 * }
 *
 * registerConfigApplier("myKey", (options) => myPlugin(options));
 * ```
 */
declare function registerConfigApplier<K extends keyof CraftConfig>(key: K, applier: ConfigApplier<K>): void;

/**
 * Everything a discoverer is given about the folder it matched and the
 * project around it.
 *
 * Passed as one object rather than positional arguments so the contract
 * can grow (a logger, a dry-run flag) without breaking every ecosystem
 * package that implements one, and so a discoverer never has to derive
 * a path the runner already knows. Deriving `contentRoot` from
 * `directory` looks harmless but bakes in an invariant the runner does
 * not promise.
 */
interface ProjectDiscoveryContext {
    /** Absolute path of the discovered folder. */
    readonly directory: string;
    /**
     * Absolute path of the content root the folder was found under: the
     * project root, or its `src` when the project uses that layout. A
     * sibling convention folder lives here.
     */
    readonly contentRoot: string;
    /** Absolute path of the project root, where `craft.config.ts` lives. */
    readonly projectRoot: string;
    /**
     * Configuration accumulated so far: the project's own
     * `craft.config.ts` plus every fragment from a discoverer that ran
     * earlier. Never mutated.
     */
    readonly config: Readonly<CraftConfig>;
    /**
     * The project's own configuration, before any discoverer contributed.
     *
     * This is the one that answers "did the project declare this?", which
     * {@link config} cannot: by the time a later discoverer runs, an
     * earlier one's fragment is indistinguishable from something the
     * author wrote. Use it for precedence decisions and for reporting
     * where a value came from; use `config` to see what is actually in
     * effect.
     */
    readonly declared: Readonly<CraftConfig>;
}
/**
 * Turn a convention folder into a `CraftConfig` fragment.
 *
 * A project runner (`craft start`) walks the filesystem and knows which
 * folders exist; it does not know what the contents mean. A discoverer
 * supplies that meaning for one folder name, which is how `agents/` and
 * `skills/` are understood by `@routecraft/ai` without the CLI ever
 * depending on it.
 *
 * Two rules follow from being handed the accumulated config:
 *
 * - **Precedence is the discoverer's job.** Code wins and convention
 *   fills the gaps, so a discoverer inspects `ctx.config` and declines
 *   to produce anything the project already declared.
 * - **Return the contribution, not the base.** The merge preserves what
 *   is already there, so a fragment should carry only what the
 *   discoverer adds. Copying existing values back into the fragment is
 *   redundant and, for an array-valued field, duplicates entries.
 *
 * The return type is `Partial<CraftConfig>`, which is shallow: it
 * cannot express "a partial value nested inside a record". A fragment
 * that patches one entry of `agent.agents` is still a patch, and may
 * need a cast at the boundary. That is a limitation of the type, not
 * permission to return complete values you did not compute.
 */
type ProjectDiscoverer = (ctx: ProjectDiscoveryContext) => Promise<Partial<CraftConfig>>;
/**
 * Registration options for {@link registerProjectDiscoverer}.
 */
interface ProjectDiscovererOptions {
    /**
     * Folder names whose fragments must already be in `ctx.config` when
     * this discoverer runs. Declaring the dependency beats picking a
     * number: it says which discoverer you need rather than where you
     * hope to sit, and a third party can target a folder name without
     * importing a constant it cannot see.
     *
     * Two edge semantics, both deliberate:
     *
     * - A name nobody registered is a **satisfied** constraint, not an
     *   error. A discoverer that composes another's output when present
     *   must still run when that package is absent.
     * - A cycle is an **error**, raised by {@link getProjectDiscoverers},
     *   because no run order can satisfy it and silently picking one
     *   would make the outcome depend on import order.
     */
    after?: readonly string[];
}
/**
 * A discoverer as held by the registry.
 */
interface RegisteredProjectDiscoverer {
    /** Folder name, relative to the project's content root. */
    readonly folder: string;
    /** Folder names that must run before this one. */
    readonly after: readonly string[];
    /** The discoverer itself. */
    readonly discover: ProjectDiscoverer;
}
/**
 * Register a discoverer for one convention folder.
 *
 * Ecosystem packages call this at module load time from a side-effect
 * import, the same way `registerConfigApplier` promotes a config key.
 * Registering the same folder twice replaces the previous
 * registration: last writer wins.
 *
 * Registration happens on **import**, which is worth stating plainly
 * because it is the failure mode users hit: a project whose
 * `craft.config.ts` only carries `import type { ... }` from the
 * package never registers anything, because a type-only import is
 * erased at compile time.
 *
 * @param folder - Folder name relative to the project's content root
 * @param discoverer - Builds a config fragment from that folder
 * @param options - Declared dependencies on other folders
 *
 * @example
 * ```typescript
 * registerProjectDiscoverer(
 *   "agents",
 *   async (ctx) => ({ agent: { agents: await load(ctx) } }),
 *   { after: ["skills"] },
 * );
 * ```
 */
declare function registerProjectDiscoverer(folder: string, discoverer: ProjectDiscoverer, options?: ProjectDiscovererOptions): void;
/**
 * Get the registered discoverers in run order.
 *
 * Sorted so every declared `after` dependency runs first, with
 * registration order preserved between independent entries so the
 * result is stable. A dependency on a folder nobody registered is
 * satisfied by definition.
 *
 * @throws RC5003 when the declared dependencies form a cycle.
 */
declare function getProjectDiscoverers(): readonly RegisteredProjectDiscoverer[];
/**
 * Merge a discoverer's fragment into a configuration and return a new
 * object. Neither input is mutated.
 *
 * Rules, in order:
 *
 * 1. An `undefined` value in the fragment is ignored, so a discoverer
 *    that produces nothing can return `{}` or omit the key.
 * 2. Two plain objects merge recursively. This is what puts a
 *    discovered agent beside a config-declared one instead of
 *    replacing the whole map.
 * 3. Two arrays concatenate, base first, which is how a discovered
 *    plugin joins the ones the project declared.
 * 4. Anything else: the fragment's value replaces the base's.
 *
 * Rule 4 is the reason precedence lives in the discoverer rather than
 * here. The merge cannot tell an intentional override from an
 * accidental one; the discoverer can, because it is handed the config
 * before it decides what to return.
 */
declare function mergeProjectConfig(base: CraftConfig, fragment: Partial<CraftConfig>): CraftConfig;

/**
 * Result of running the auth middleware on a request.
 *
 * - `admit` always carries a {@link Principal}: every implemented strategy
 *   (apiKey static / verify, validator bearer) produces one on the admit
 *   path.
 * - `absent` is returned when the request carried no credential at all (no
 *   `Authorization` header for bearer; no header / query parameter for
 *   apiKey). The dispatcher converts this to 401 on `auth: "required"`
 *   routes and lets the request through with no principal on
 *   `auth: "optional"` routes. Carries the `scheme` only; the dispatcher
 *   decides whether to issue a Response based on the route's auth mode.
 * - `reject` is returned when a credential was presented but failed
 *   verification. It carries the canonical response the dispatcher should
 *   return (401, or 500 when verification itself failed on the server
 *   side), plus the `reason` and `scheme` that drive the `auth:rejected`
 *   event payload.
 */
type AuthResult = {
    kind: "admit";
    principal: Principal;
    /**
     * Raw credential passed through for protocol adapters such as MCP.
     * This is secret material: never log it, emit it in an event, include it
     * in an error, or persist it outside the request lifetime.
     */
    credential: string;
    /**
     * Clock skew the verification that admitted this credential allowed.
     *
     * Carried on the verdict rather than re-derived from config by each
     * consumer, because anything re-checking the same credential later (a
     * stream that outlives its admission) must apply the same boundary.
     * Two resolutions of one setting can drift; an inherited value cannot.
     */
    clockToleranceSec: number;
} | {
    kind: "absent";
    scheme: string;
} | {
    kind: "reject";
    response: Response;
    reason: string;
    scheme: string;
    cause?: unknown;
};
/**
 * Build an API-key auth strategy. Use with `http: { auth: apiKey({...}) }`.
 *
 * @example Static allowlist (most common case)
 * ```ts
 * http: { port: 8080, auth: apiKey({ keys: [process.env.API_KEY!] }) }
 * ```
 *
 * @example Database-backed lookup that resolves to a per-user principal
 * ```ts
 * apiKey({
 *   in: "header",
 *   name: "x-api-key",
 *   verify: async (key) => {
 *     const user = await db.users.findByApiKey(key);
 *     if (!user) return null;
 *     return { kind: "custom", scheme: "apiKey", subject: user.id, roles: user.roles };
 *   },
 * })
 * ```
 *
 * @experimental
 */
declare function apiKey(opts: Omit<ApiKeyAuthOptions, "kind">): ApiKeyAuthOptions;

interface HttpServerDefinition {
    kind?: "http";
    host?: string;
    port: number;
    /**
     * Additional trusted public hostnames for protocol mounts on this server.
     * Exact hostnames only, without scheme, path, port or wildcard. Bound
     * addresses and supported loopback aliases remain accepted. Never inferred
     * from Host, Forwarded or X-Forwarded-Host request headers.
     */
    allowedHostnames?: readonly string[];
    /**
     * Server-level credential validator inherited by every mount that does not
     * set its own `auth`. Verification config only: each mount still owns its
     * admission policy and refusal wire format.
     */
    auth?: ValidatorAuthOptions;
    /**
     * How long a graceful close may drain in-flight work before the listener is
     * force-closed. Defaults to 30000.
     */
    shutdownGrace?: Duration;
    /**
     * How long a connection may sit idle before the listener reaps it.
     * Defaults to `"255s"`, which is Bun's maximum and so the ceiling on both
     * runtimes: a larger value is refused at construction rather than silently
     * clamped, because a config that means one thing on Bun and another on
     * Node is worse than a config that will not start.
     *
     * Streaming responses are exempt from this per request, and bounded by
     * {@link HttpServerDefinition.maxStreamingRequests} instead.
     */
    idleTimeout?: Duration;
    /**
     * How many streaming responses this listener will carry at once, past
     * which it answers 503 with `Retry-After`. Defaults to 500.
     *
     * A backstop, not a capacity plan: a streaming response is exempt from the
     * idle reaper, so without a ceiling a client that opens streams and never
     * reads them takes the process to its file-descriptor limit and every
     * in-flight request with it. The number is meant to sit below that cliff so
     * an operator gets a clean refusal instead, the way `maxBodySize`'s 10 MB
     * does. Per-route admission is a different tool: see `.concurrency()`.
     *
     * Deliberately not named for HTTP/2's `SETTINGS_MAX_CONCURRENT_STREAMS`,
     * which counts multiplexed streams inside one connection and is a
     * different thing entirely.
     */
    maxStreamingRequests?: number;
}
type ServerDefinitions = Record<string, HttpServerDefinition>;
type PathClaim = {
    readonly kind: "exact";
    readonly path: string;
    readonly methods?: readonly HttpMethod[];
} | {
    readonly kind: "prefix";
    readonly path: string;
} | {
    readonly kind: "pattern";
    readonly matcher: PathMatcher;
    readonly staticPrefix: string;
    readonly methods?: readonly HttpMethod[];
};
interface HttpMount {
    readonly id: string;
    /**
     * Enforce the shared protocol Host and browser-origin gate before dispatch.
     * MCP and ACP always register this policy. Other HTTP surfaces retain their
     * own admission contract unless they register it too.
     */
    readonly requestValidation?: {
        /** Mount-specific trusted hostnames, in addition to the server's. */
        readonly allowedHostnames?: readonly string[];
        /** Exact HTTP(S) browser origins. Unset denies requests carrying Origin. */
        readonly browserOrigins?: readonly string[];
    };
    /**
     * Every path this mount answers, evaluated once during the server's
     * `start()` validation. The thunk exists so claims registered after mount
     * time (route subscriptions) are visible at validation; the evaluated set
     * is the immutable routing input afterwards.
     *
     * `{ kind: "prefix", path: "/" }` is the catch-all fallback: it loses to
     * every other claim at dispatch and at most one mount per server may
     * declare it.
     */
    readonly claims: () => readonly PathClaim[];
    /**
     * Mount-level auth override. Unset inherits the server's validator as this
     * mount's effective auth. A config of its own replaces the server's.
     * `false` removes the wall while keeping the inherited validator reachable
     * for pull-based verification (a route's `.authorize()`), so an open
     * surface on an authenticated server is a visible config decision that
     * never strands routes needing identity.
     */
    readonly auth?: HttpAuth | false;
    /**
     * Whether this surface enforces the resolved wall. Defaults to true. The
     * ops surface sets false because its health paths answer every probe
     * without a credential whatever the facts say; the registry uses this to
     * keep the inherited-authentication log from claiming a gate the surface
     * never enforces.
     */
    readonly enforcesWall?: boolean;
    /**
     * Responses on this mount may stream or stay quiet indefinitely (MCP
     * streamable HTTP, SSE). The ingress exempts its requests from the
     * listener's idle timeout so a silent stream is not reaped, while every
     * other connection keeps the bounded default.
     */
    readonly longLived?: boolean;
    /**
     * What the RFC 9728 metadata document for this mount's paths may say
     * beyond the effective validator's issuer. Declared, never inferred: the
     * ops mount passes its resolved tier scopes here, and a mount that
     * declares nothing gets a document carrying only what the validator
     * config states. Served by the ingress for any metadata path no mount
     * claims itself (the MCP mount claims and serves its own).
     */
    readonly resourceMetadata?: {
        readonly scopesSupported?: readonly string[];
    };
    readonly handler: (request: Request, context: HttpMountContext) => Response | Promise<Response>;
}
/**
 * Resolved auth facts for a mount: which validator is effective and whether
 * the author asked for a wall. Facts, not policy: the registry computes them
 * in one place so no surface re-derives the rule, and each surface decides
 * for itself whether to honour `walled` (http and mcp do; ops never walls its
 * health paths).
 */
interface HttpMountAuth {
    /**
     * Only three combinations are reachable, one per spelling of `auth`:
     * unset resolves { own: false, optedOut: false, walled: configured },
     * a config of its own { own: true, optedOut: false, configured: true,
     * walled: true }, and `false` { own: false, optedOut: true, walled: false }.
     */
    /** An effective validator exists (the mount's own, or inherited). */
    readonly configured: boolean;
    /** The mount declared its own validator rather than inheriting. */
    readonly own: boolean;
    /** The mount said `auth: false`: no wall, inherited validator reachable. */
    readonly optedOut: boolean;
    /** `configured && !optedOut`. The author asked for a wall. */
    readonly walled: boolean;
}
/**
 * Resolved facts about the mount's effective auth (mount `auth`, else the
 * inherited server validator), so protocol handlers never re-parse the raw
 * config union at request time.
 */
interface HttpMountAuthPolicy {
    /** Issuer(s) the effective validator advertises, for metadata documents. */
    readonly issuer?: string | string[];
}
interface HttpMountContext {
    readonly serverName: string;
    /**
     * Resolve this request's credential through the mount's effective auth.
     * Memoized per request, and the ingress emits `auth:success` /
     * `auth:rejected` exactly once, on first resolution. Returns `undefined`
     * when the mount has no effective auth.
     *
     * The ingress never calls this itself: the mount owns its gate, so public
     * protocol paths (discovery documents, health probes, CORS preflight) and
     * routes that opt out of auth simply never trigger verification.
     */
    readonly authenticate: () => Promise<AuthResult | undefined>;
    readonly authPolicy: HttpMountAuthPolicy | undefined;
    /** Resolved auth facts for this mount. */
    readonly auth: HttpMountAuth;
    /**
     * Claim a streaming slot for this one request.
     *
     * Two things at once, because they are the same decision: the request is
     * exempted from the listener's idle reaper, and it is counted against
     * `maxStreamingRequests`. The mount-level {@link HttpMount.longLived} flag
     * says every request on a surface may stay quiet; this says one of them
     * will, which is what a mount needs when the body type decides.
     *
     * Returns a release callback to call when the response ends, or
     * `undefined` when the listener is already at its cap, in which case the
     * caller must refuse rather than stream.
     */
    readonly claimStreamingSlot: () => (() => void) | undefined;
}
interface WebIngress {
    readonly serverName: string;
    /**
     * Resolve the auth facts a mount option would get on this server. Pure in
     * the option and the server's own validator, so a surface can consult it
     * before or after mounting (bind-time refusals, startup warnings) and the
     * request-time `HttpMountContext.auth` is guaranteed to agree.
     */
    resolveMountAuth(auth: HttpMount["auth"]): HttpMountAuth;
    /**
     * Whether a mount with this id is registered on the same server.
     *
     * Only meaningful from inside a `claims()` thunk, which the server evaluates
     * once every mount has registered. It exists so a surface can stand down for
     * one that supersedes it, rather than colliding at bind time over a path
     * both would answer.
     */
    hasMount(id: string): boolean;
    readonly boundAddress: {
        readonly host: string;
        readonly port: number;
    } | undefined;
    mountHttp(mount: HttpMount): () => void;
}

declare module "@routecraft/routecraft" {
    interface CraftConfig {
        servers?: ServerDefinitions;
    }
}

declare module "@routecraft/routecraft" {
    interface CraftConfig {
        /** HTTP server config for inbound http() sources (port, auth, etc.) */
        http?: HttpConfig;
    }
}

declare module "@routecraft/routecraft" {
    interface CraftConfig {
        /** Operational surface: health endpoints, and later the action namespace. */
        ops?: OpsConfig;
    }
}

/**
 * HTTP client for a running instance's ops server.
 *
 * Spans two surfaces that behave differently and must not be flattened.
 * `/health` never walls, so a probe with no credential works, and it
 * returns MORE when authenticated: per-component `details` are gated by
 * `health.details`. `/ops` answers by tier: 404 when a tier is off, open
 * when `true`, scope-checked when a scope string is configured.
 *
 * So this client presents a credential whenever one is configured, on both
 * surfaces, and degrades when none is. That is a correctness requirement
 * rather than a nicety: unauthenticated, a route component says `degraded`
 * and nothing else; authenticated, it says `degraded` because a breaker is
 * open. The bare status does not answer the question an operator is asking.
 *
 * Two callers share it. The `craft` CLI drives one instance from a
 * terminal, and the remotes plugin imports another instance's dispatchable
 * routes into a running context. Neither knows anything the other does
 * not about the wire, so the client lives in core beside the server it
 * speaks to, and each caller supplies only the words its own reader needs
 * (where the address came from, and what to do when refused).
 */

/** Why a call did not produce an answer. Each needs a different remedy. */
type OpsFailureKind = 
/** The instance could not be reached at all; the request never left. */
"unreachable"
/**
 * The request may have reached the instance: the connection was lost
 * after it was sent, or while the answer was being read. Whatever it
 * asked for may have run.
 */
 | "interrupted"
/** The door refused: no credential, a bad one, or a missing scope. */
 | "refused"
/** The tier is disabled, or the thing asked for does not exist. */
 | "absent"
/** The instance answered, and the answer was an error. */
 | "error";
/** A call that did not produce an answer, with what to do about it. */
declare class OpsClientError extends Error {
    readonly kind: OpsFailureKind;
    readonly status?: number | undefined;
    readonly detail?: unknown | undefined;
    constructor(kind: OpsFailureKind, message: string, status?: number | undefined, detail?: unknown | undefined);
}
/**
 * The bearer presented on every call: a string, or a function evaluated
 * per request. A rotation reaches a running process only through a function
 * that reads a source that changes (a mounted secret file, a secret manager);
 * a change made outside the process never reaches its `process.env`. A
 * function returning `undefined` presents no credential for that call.
 */
type OpsBearerToken = string | (() => string | undefined | Promise<string | undefined>);
/** What a caller supplies to build a client. */
interface OpsHttpClientOptions {
    /** The instance's base URL. A trailing slash is tolerated. */
    url: string;
    /** Credential for both surfaces. Absent means every call is unauthenticated. */
    token?: OpsBearerToken;
    /** Per-request deadline. Defaults to 30 seconds. */
    timeout?: Duration;
    /**
     * How the address is named in an error a reader must act on. A wrong
     * pinned address is otherwise indistinguishable from a stopped instance,
     * so the CLI says where it read the address from and the remotes plugin
     * says which remote it is.
     */
    describeAddress?: () => string;
    /** Sentences appended to a refusal or a transport failure, naming the caller's own remedy. */
    advice?: {
        /** What to do when the door wants a credential and none was presented. */
        missingCredential?: string;
        /** What to do when nothing answered at the address. */
        unreachable?: string;
    };
    /**
     * Override the runtime detection behind the per-dispatch connection.
     *
     * A test seam rather than a knob: the behaviour is a property of the
     * runtime, not of a deployment, so nothing in production should set it.
     * It exists because the alternative is asserting a connection policy by
     * running the suite twice on two Bun builds.
     *
     * @internal
     */
    replaysDroppedRequests?: boolean;
}
interface OpsHttpClient {
    /** Whether a credential is configured, for rendering the view. */
    readonly authenticated: boolean;
    health(): Promise<HealthReport>;
    ready(): Promise<HealthReport>;
    routeHealth(id: string): Promise<HealthComponent>;
    indicatorHealth(name: string): Promise<HealthComponent>;
    listRoutes(filter?: OpsRouteFilter): Promise<OpsRouteSummary[]>;
    describeRoute(id: string): Promise<OpsRouteDetail>;
    dispatch(id: string, body: unknown): Promise<OpsDispatchOutcome>;
    /**
     * One page of deferrals, and the cursor for the next when there is one.
     *
     * The page rather than the whole collection, which is the opposite of
     * {@link OpsHttpClient.listRoutes}. A route inventory is bounded by what
     * an author wrote; an instance can hold every exchange it has ever
     * deferred, so walking it would be a request to load an unbounded set
     * into memory to print the first screen of it.
     */
    listDeferrals(filter?: OpsDeferralFilter): Promise<OpsPage<OpsDeferralSummary>>;
    describeDeferral(id: string): Promise<OpsDeferralSummary>;
}
/** What `GET /ops/deferrals` accepts. */
interface OpsDeferralFilter {
    /** Waiting by default on the server; `all` asks for both states. */
    state?: DeferralState | "all";
    /** Only deferrals belonging to this route. */
    route?: string;
    /** Rows in one page. The server bounds it and refuses a larger ask. */
    limit?: number;
    /** The previous page's `nextCursor`, passed back unchanged. */
    after?: string;
}
/**
 * localhost, 127.0.0.0/8 and ::1, as `URL.hostname` renders them.
 *
 * The one place a bearer may travel over plain `http:`: the bytes never
 * leave the machine. Every caller that refuses clear-text bearers decides
 * with this predicate so the exception cannot drift between them.
 */
declare function isLoopbackHostname(hostname: string): boolean;
declare function createOpsHttpClient(options: OpsHttpClientOptions): OpsHttpClient;

/**
 * Public types for the remotes plugin.
 *
 * A remote is another running instance whose dispatchable routes become
 * direct endpoints here. The options are deliberately small: an address,
 * a credential for that instance's door, and two cadences. Everything
 * about what the remote exposes is the remote's own configuration, read
 * through its ops management API, and nothing here restates it.
 */

/** One remote instance, keyed by name in `defineConfig({ remotes })`. */
interface RemoteDefinition {
    /**
     * The instance's base URL, the origin its ops surface is mounted on.
     * A bearer travels over plain `http:` only to a loopback address, for
     * the same reason the CLI refuses it: every hop in between can read it.
     */
    url: string;
    /**
     * Credential for the remote's door, as a string or as a function evaluated
     * per request. The function lets a rotated token reach a running process
     * only when it reads a source that changes underneath it (a mounted secret
     * file, a secret manager); a change made outside the process (a deployment
     * variable, `.env`) never reaches its `process.env`. The identity the
     * remote sees is whatever its own validator mints from it; this plugin
     * makes no call on api keys versus JWTs.
     */
    auth?: {
        token?: OpsBearerToken;
    };
    /** Per-request deadline against the remote. Defaults to `"30s"`. */
    timeout?: Duration;
    /**
     * How often the inventory is re-read. Defaults to `"60s"`; `false`
     * disables the interval, leaving the boot read and the refresh a
     * dispatch forces when it meets a 404 for a route the inventory still
     * lists.
     */
    refresh?: Duration | false;
}
/**
 * The `remotes` config key: remotes by name.
 *
 * Git-style naming. The routes of `default` are advertised bare, exactly
 * as a local route would be, so `direct('hello')` and `Direct(hello)` reach
 * them with nothing to learn; every other remote's routes are qualified
 * `name:id`, and `default:id` names the default remote explicitly. Two
 * remotes therefore never collide, and a local route with the same id as
 * a default-remote route shadows it: the local one answers, the remote
 * stays reachable as `default:id`, and the overlap is logged as a warning
 * rather than refused, because it is the window in which a capability is
 * being promoted from a laptop to the server.
 */
type RemotesConfig = Record<string, RemoteDefinition>;
/** Options for {@link remotesPlugin}; the same shape as the config key. */
type RemotesPluginOptions = RemotesConfig;

declare module "@routecraft/routecraft" {
    interface CraftConfig {
        /** Other running instances whose dispatchable routes become direct endpoints here. */
        remotes?: RemotesConfig;
    }
}

declare module "@routecraft/routecraft" {
    interface CraftConfig {
        /** Default options applied to all cron() sources in this context */
        cron?: Partial<CronOptions>;
    }
}

/**
 * @deprecated Use `CraftConfig.direct` (a `Pick<DirectBaseOptions, "channelType">`) instead.
 * Previously a no-op placeholder (`Record<string, unknown>`), now removed.
 * This alias exists only for migration; it will be removed in the next major version.
 */
type DirectConfig = Pick<DirectBaseOptions, "channelType">;
type DirectChannelType<T extends DirectChannel> = new (endpoint: string) => T;
type DirectEndpoint<T = unknown> = RegisteredDirectEndpoint | ((exchange: Exchange<T>) => string);
/**
 * DirectChannel interface for synchronous inter-route communication.
 *
 * Semantics:
 * - Single consumer per endpoint (last subscriber wins)
 * - Synchronous blocking behavior (sender waits for response)
 * - Point-to-point messaging (not pub/sub)
 */
interface DirectChannel<T = unknown> {
    send(endpoint: string, message: T): Promise<T>;
    subscribe(context: CraftContext, endpoint: string, handler: (message: T) => Promise<T>): Promise<void>;
    unsubscribe(context: CraftContext, endpoint: string): Promise<void>;
}
/**
 * Base options shared between source and destination.
 */
interface DirectBaseOptions {
    /** Custom channel implementation */
    channelType?: DirectChannelType<DirectChannel>;
}
/**
 * Options when using direct adapter as a Server (`.from()`).
 *
 * The shared discovery metadata (title, description, input, output) lives
 * on the route via `.title()` / `.description()` / `.input()` / `.output()`
 * and is enforced by the framework regardless of adapter.
 */
interface DirectServerOptions extends DirectBaseOptions {
    /**
     * Close the route's external doors: it stays composable in-process
     * (`direct("id")` enrichers, `forward`) but is neither dispatchable
     * through the ops management API nor resolvable as an agent
     * `directTool`. For a subroutine that trusts its caller because a
     * boundary route carries `.input()`, `.description()` and
     * `.authorize()` for it. Defaults to false: a `direct()` route is a
     * capability, and capabilities are what `craft exec` runs.
     */
    internal?: boolean;
}
/**
 * Options when using direct adapter as a Client (`.to()`, `.tap()`).
 * Room for future options (e.g. timeout, retryPolicy).
 */
type DirectClientOptions = DirectBaseOptions;
/**
 * Options when using direct as a server or client (union).
 */
type DirectOptions = DirectServerOptions | DirectClientOptions;

declare module "@routecraft/routecraft" {
    interface CraftConfig {
        /** Default channel implementation for all direct() adapters (e.g. swap in-memory for Kafka) */
        direct?: Pick<DirectBaseOptions, "channelType">;
    }
}

/**
 * Manages per-account IMAP connection pools and SMTP transporters.
 * Created by the ContextBuilder when `mail` config is present.
 */
declare class MailClientManager {
    private readonly pools;
    private readonly transports;
    readonly config: MailContextConfig;
    readonly defaultAccount: string;
    constructor(config: MailContextConfig);
    /**
     * Acquire an IMAP client for the given account.
     * Creates the account pool lazily on first access.
     */
    acquireImap(account?: string, mailbox?: string): Promise<InstanceType<typeof imapflow.ImapFlow>>;
    /**
     * Release an IMAP client back to its account pool.
     */
    releaseImap(account: string | undefined, client: InstanceType<typeof imapflow.ImapFlow>): void;
    /**
     * Update the tracked mailbox for a pooled client.
     */
    trackMailbox(account: string | undefined, client: InstanceType<typeof imapflow.ImapFlow>, mailbox: string): void;
    /**
     * Get the SMTP transporter for the given account (lazy init).
     */
    getSmtp(account?: string): Promise<ReturnType<typeof nodemailer.createTransport>>;
    /**
     * Resolve IMAP options: adapter overrides > account config > shared defaults > built-in defaults.
     */
    resolveImapOptions(account?: string, overrides?: Partial<MailServerOptions>): MailServerOptions;
    /**
     * Resolve SMTP options: adapter overrides > account config > shared defaults.
     */
    resolveSmtpOptions(account?: string, overrides?: Partial<MailClientOptions>): MailClientOptions;
    /**
     * Drain all pools and transports. Called during context teardown.
     */
    drain(): Promise<void>;
}

/**
 * Store key for the mail client manager.
 * Set by the ContextBuilder when `mail` config is present.
 * @internal
 */
declare const MAIL_CLIENT_MANAGER: unique symbol;
declare module "@routecraft/routecraft" {
    interface StoreRegistry {
        [MAIL_CLIENT_MANAGER]: MailClientManager;
    }
}
/**
 * Header keys the mail source sets for the message envelope. Keys live
 * under the reserved `routecraft.mail.*` namespace; the value types are
 * merged into `RoutecraftHeaders` in `./types.ts`.
 */
declare const MailHeaders: {
    /** IMAP UID of the source message. */
    readonly UID: "routecraft.mail.uid";
    /** IMAP folder of the source message. */
    readonly FOLDER: "routecraft.mail.folder";
    /** `Message-ID` of the source message. */
    readonly MESSAGE_ID: "routecraft.mail.messageId";
    /** Literal `From:` address. */
    readonly FROM: "routecraft.mail.from";
    /** Recipient address(es) (always an array). */
    readonly TO: "routecraft.mail.to";
    /** CC recipient address(es). */
    readonly CC: "routecraft.mail.cc";
    /** BCC recipient address(es). */
    readonly BCC: "routecraft.mail.bcc";
    /** Subject line. */
    readonly SUBJECT: "routecraft.mail.subject";
    /** Date the message was sent. */
    readonly DATE: "routecraft.mail.date";
    /** Reply-To address. */
    readonly REPLY_TO: "routecraft.mail.replyTo";
    /** IMAP flags. */
    readonly FLAGS: "routecraft.mail.flags";
    /** Computed effective sender (when `verify !== "off"`). */
    readonly SENDER: "routecraft.mail.sender";
    /** Raw email headers (requested via `includeHeaders`). */
    readonly RAW_HEADERS: "routecraft.mail.rawHeaders";
    /**
     * SMTP send receipt: `Message-ID` of the SENT email. Deliberately not
     * {@link MailHeaders.MESSAGE_ID}: the inbound message and an outbound
     * reply are different entities, so a `.from(mail(...))....to(mail())`
     * route keeps the source message's id intact for correlation.
     */
    readonly SENT_MESSAGE_ID: "routecraft.mail.sentMessageId";
    /** SMTP send receipt: accepted recipient addresses. */
    readonly ACCEPTED: "routecraft.mail.accepted";
    /** SMTP send receipt: rejected recipient addresses. */
    readonly REJECTED: "routecraft.mail.rejected";
    /** SMTP send receipt: raw SMTP server response string. */
    readonly RESPONSE: "routecraft.mail.response";
};

/**
 * Sender analysis for received mail messages.
 *
 * Derives the "effective sender" by unwinding mailing-list and auto-forward
 * rewrites using already-present headers (`List-Id`, `X-Original-From`,
 * `Authentication-Results`, `ARC-*`). No network, no crypto. For cryptographic
 * verification see `strict-verify.ts`.
 */
/**
 * How a message reached the recipient.
 */
type ForwardType = "direct" | "auto-forward" | "mailing-list";
/**
 * Trust state of the effective sender.
 */
type TrustLevel = "verified" | "unverified" | "failed";
/**
 * Parsed email address.
 */
interface EmailAddress {
    address: string;
    name?: string;
    domain: string;
}
/**
 * One hop in a forward chain.
 */
interface ForwardHop {
    via: EmailAddress;
    type: "auto-forward" | "mailing-list";
    arcInstance?: number;
}
/**
 * Effective sender plus the evidence used to resolve it.
 */
interface MailSender extends EmailAddress {
    /** How the message reached us. */
    forwardType: ForwardType;
    /** Chain of forwarders, nearest hop first. Empty for direct mail. */
    forwardChain: ForwardHop[];
    /** Trust state of this sender. */
    trust: TrustLevel;
    /** Machine-readable reason, e.g. "list-forward-arc-verified". */
    reason: string;
    /** Authentication verdicts from the receiving server's Authentication-Results. */
    authentication: {
        dkim: "pass" | "fail" | "neutral" | "none";
        spf: "pass" | "fail" | "neutral" | "none";
        dmarc: "pass" | "fail" | "neutral" | "none";
        arc: "pass" | "fail" | "none";
    };
    /** Literal `From:` header, only set when it differs from the effective sender. */
    headerFrom?: EmailAddress;
}
/**
 * Lowercased header names relevant to sender analysis. Always extracted from
 * a parsed message even when the caller has not requested `includeHeaders`.
 */
declare const ANALYSIS_HEADER_NAMES: readonly ["from", "sender", "reply-to", "x-original-from", "x-original-sender", "list-id", "list-post", "list-unsubscribe", "precedence", "authentication-results", "arc-authentication-results", "arc-message-signature", "arc-seal", "received"];
type AuthVerdict = "pass" | "fail" | "neutral" | "none";
interface ParsedAuthResults {
    dkim: AuthVerdict;
    spf: AuthVerdict;
    dmarc: AuthVerdict;
    /** header.from reported by dmarc, if present. */
    dmarcHeaderFrom?: string;
    /** header.i (or header.d) reported by the strongest dkim result. */
    dkimDomain?: string;
}
/**
 * Parse an `Authentication-Results` style header value.
 *
 * Format (RFC 8601): `authserv-id; method=result (comment) property=value; ...`
 * We pluck out method verdicts plus a couple of properties we care about.
 */
declare function parseAuthResults(value: string | undefined): ParsedAuthResults;
/**
 * Derive a {@link MailSender} from the auth-relevant headers of a received
 * message. Pure function, no I/O.
 *
 * @param headers - Lowercased header map, as returned by {@link extractAnalysisHeaders}.
 */
declare function analyzeHeaders(headers: Record<string, string | string[]>): MailSender;

/**
 * Mail adapter type definitions.
 *
 * Server options configure IMAP (read/receive).
 * Client options configure SMTP (send).
 */

/**
 * Authentication credentials for mail servers.
 * Supports app passwords and standard user/pass authentication.
 */
interface MailAuth {
    user: string;
    pass: string;
}
/**
 * IMAP connection settings for a named account.
 */
interface MailAccountImapConfig {
    /** IMAP host (e.g. 'imap.gmail.com') */
    host?: string;
    /** IMAP port (default 993) */
    port?: number;
    /** Use TLS (default true) */
    secure?: boolean;
    /** Authentication credentials */
    auth?: MailAuth;
    /** Max concurrent IMAP connections for this account (default 3) */
    poolSize?: number;
}
/**
 * SMTP connection settings for a named account.
 */
interface MailAccountSmtpConfig {
    /** SMTP host (e.g. 'smtp.gmail.com') */
    host?: string;
    /** SMTP port (default 465) */
    port?: number;
    /** Use TLS (default true) */
    secure?: boolean;
    /** Authentication credentials */
    auth?: MailAuth;
    /** Default sender address */
    from?: string;
    /** Default reply-to address */
    replyTo?: string;
    /** Default CC recipients */
    cc?: string | string[];
    /** Default BCC recipients */
    bcc?: string | string[];
}
/**
 * Configuration for a named mail account.
 * Each account defines its own IMAP and/or SMTP connection.
 *
 * @example
 * ```typescript
 * {
 *   imap: { host: 'imap.gmail.com', auth: { user: 'me@co.com', pass: 'xxx' } },
 *   smtp: { host: 'smtp.gmail.com', auth: { user: 'me@co.com', pass: 'xxx' }, from: 'me@co.com' },
 * }
 * ```
 */
interface MailAccountConfig {
    /** IMAP connection settings */
    imap?: MailAccountImapConfig;
    /** SMTP connection settings */
    smtp?: MailAccountSmtpConfig;
}
/**
 * Context-level mail configuration. Added to CraftConfig via `.with({ mail: {...} })`.
 *
 * @example
 * ```typescript
 * new ContextBuilder().with({
 *   mail: {
 *     accounts: {
 *       default: { imap: {...}, smtp: {...} },
 *       support: { imap: {...}, smtp: {...} },
 *     },
 *     folder: 'INBOX',
 *     markSeen: true,
 *   },
 * })
 * ```
 */
interface MailContextConfig {
    /** Named mail accounts */
    accounts?: Record<string, MailAccountConfig>;
    /** Default IMAP folder across all accounts (default 'INBOX') */
    folder?: string;
    /** Default markSeen behavior across all accounts (default true) */
    markSeen?: boolean;
}
/**
 * Tuning for the mail source's connection-recovery behaviour. Applies to
 * every connection-type failure the source can hit: the initial connect at
 * route start, IDLE drops, and fetch failures in both IDLE and poll mode.
 * Authentication failures never reconnect; they are fatal immediately.
 *
 * Delays grow exponentially from `baseDelay` up to `maxDelay`, with full
 * jitter (each delay is drawn uniformly from [0, current backoff]).
 */
interface MailReconnectOptions {
    /**
     * Give up after this many consecutive failed attempts; the source then
     * rejects with RC5010 and the route stops (`route:source:failed` fires).
     * Pass `Infinity` for a channel that must never give up.
     *
     * @default 30
     */
    maxAttempts?: number;
    /**
     * Backoff for the first retry.
     *
     * @default 1000
     */
    baseDelay?: Duration;
    /**
     * Upper bound for the exponential backoff.
     *
     * @default 60000
     */
    maxDelay?: Duration;
}
/**
 * Options when using the mail adapter as a Server (IMAP read).
 * Used with `.enrich(mail({...}))` or `.from(mail(folder, {...}))`.
 */
interface MailServerOptions {
    /** IMAP host (e.g. 'imap.gmail.com') */
    host?: string;
    /** IMAP port (default 993) */
    port?: number;
    /** Use TLS (default true) */
    secure?: boolean;
    /** Authentication credentials */
    auth?: MailAuth;
    /**
     * IMAP mailbox folder. Required in the object-form fetch destination
     * (`mail({ folder: 'INBOX', ... })`), where it is the key that
     * distinguishes a fetch from an SMTP send. Optional on this type only
     * because the source form passes it positionally
     * (`mail('INBOX', { ... })`).
     */
    folder?: string;
    /** Mark fetched messages as seen (default true) */
    markSeen?: boolean;
    /** Only fetch messages since this date */
    since?: Date;
    /** Only fetch unseen messages (default true) */
    unseen?: boolean;
    /** Filter by sender address (IMAP FROM search, case-insensitive). Array = OR. */
    from?: string | string[];
    /** Filter by recipient address (IMAP TO search, case-insensitive). Array = OR. */
    to?: string | string[];
    /** Filter by subject text (IMAP SUBJECT search, case-insensitive). Array = OR. */
    subject?: string | string[];
    /** Filter by body text (IMAP TEXT search, case-insensitive). Array = OR. */
    body?: string | string[];
    /**
     * Filter by arbitrary IMAP headers (IMAP HEADER search).
     * Keys are header names, values are substring matches. Array values = OR.
     *
     * @example
     * ```typescript
     * // Match emails with Reply-To containing "no-reply"
     * mail({ folder: "INBOX", header: { "Reply-To": "no-reply" } })
     *
     * // Match emails with a specific List-Id
     * mail({ folder: "INBOX", header: { "List-Id": "announcements.example.com" } })
     *
     * // OR within a header: match "noreply" or "no-reply" in Reply-To
     * mail({ folder: "INBOX", header: { "Reply-To": ["noreply", "no-reply"] } })
     * ```
     */
    header?: Record<string, string | string[]>;
    /** Maximum number of messages to fetch per call */
    limit?: number;
    /** Human-readable description for route discovery */
    description?: string;
    /** Keywords for route discovery and categorization */
    keywords?: string[];
    /** Poll interval for Source mode (default: use IMAP IDLE) */
    pollInterval?: Duration;
    /** Named account from context config (uses default if omitted) */
    account?: string;
    /**
     * Raw email headers to include on fetched messages.
     * Pass `true` to include all headers, or an array of header names to
     * include only specific ones (case-insensitive). Defaults to none.
     *
     * @example
     * ```typescript
     * // Include all headers (useful for discovery)
     * mail('INBOX', { includeHeaders: true })
     *
     * // Include specific headers only (keeps exchange size small)
     * mail('INBOX', { includeHeaders: ['Return-Path', 'DKIM-Signature', 'X-Spam-Status'] })
     * ```
     */
    includeHeaders?: true | string[];
    /**
     * How hard to verify the sender. Populates `MailMessage.sender` so apps can
     * gate on the real origin of mailing-list and auto-forwarded mail without
     * re-parsing headers themselves.
     *
     * - `"off"`: skip analysis, `sender` is omitted.
     * - `"headers"` (default): parse `Authentication-Results`, `ARC-*`, `List-Id`,
     *   `X-Original-From` that the receiving server already wrote. No network.
     * - `"strict"`: additionally run cryptographic verification via `mailauth`.
     *   Does DNS lookups and is slower; only use when the receiving server is
     *   not trusted to have verified the chain for you.
     */
    verify?: "off" | "headers" | "strict";
    /**
     * How to handle a per-message MIME parse failure (`mailparser`'s
     * `simpleParser` throwing on malformed input). All modes mark the
     * malformed message as Seen so it does not refetch indefinitely.
     *
     * - `'fail'` (default): `route:exchange:failed` fires for the bad message,
     *   or `route:error:caught` when the route's `.error()` handler recovers
     *   it; the poll loop continues.
     * - `'abort'`: `route:exchange:failed` fires for the bad message, then the
     *   source rejects and `context:error` fires.
     * - `'drop'`: `route:exchange:dropped` fires with `reason: "parse-failed"` and
     *   the poll loop continues. Use this when malformed mail is expected
     *   and you want it counted in `route:exchange:dropped` metrics rather than
     *   surfaced as route errors.
     *
     * Pre-#187 behaviour was equivalent to `'drop'` but logged at debug
     * with no event; the new `'fail'` default routes the failure through
     * `.error()` and is observable. Set `onParseError: 'drop'` to keep the
     * lossy-ingest semantics with proper observability.
     *
     * @default "fail"
     */
    onParseError?: OnParseError;
    /**
     * Reconnect behaviour for connection-type failures on the long-running
     * source connection (initial connect, IDLE drops, fetch failures). Pass an
     * object to tune the backoff, or `false` to disable reconnection entirely
     * so the first connection failure stops the route. Defaults to
     * `{ maxAttempts: 30, baseDelay: 1000, maxDelay: 60000 }`.
     *
     * Only meaningful in Source mode (`.from(mail(folder, {...}))`); the fetch
     * destination performs one-shot fetches and ignores this option.
     *
     * Note that with reconnection enabled the source signals readiness before
     * the first connection succeeds, so `route:started` no longer guarantees
     * the mailbox was reachable: an unreachable server at startup leaves the
     * route running in a degraded-but-recovering state instead of failing.
     *
     * @example
     * ```typescript
     * // A channel that must never give up (multi-channel agent harness)
     * mail('INBOX', { reconnect: { maxAttempts: Infinity } })
     *
     * // Fail fast: any connection failure stops the route
     * mail('INBOX', { reconnect: false })
     * ```
     *
     * @default { maxAttempts: 30, baseDelay: 1000, maxDelay: 60000 }
     */
    reconnect?: MailReconnectOptions | false;
}
/**
 * Options when using the mail adapter as a Client (SMTP send).
 * Used with `.to(mail())` or `.to(mail({...}))`.
 */
interface MailClientOptions {
    /** SMTP host (e.g. 'smtp.gmail.com') */
    host?: string;
    /** SMTP port (default 465) */
    port?: number;
    /** Use TLS (default true) */
    secure?: boolean;
    /** Authentication credentials */
    auth?: MailAuth;
    /** Default sender address */
    from?: string;
    /** Default reply-to address */
    replyTo?: string;
    /** Default CC recipients */
    cc?: string | string[];
    /** Default BCC recipients */
    bcc?: string | string[];
    /** Named account from context config (uses default if omitted) */
    account?: string;
}
/**
 * Options when using mail as a server or client (union).
 */
type MailOptions = MailServerOptions | MailClientOptions;
/**
 * Custom extractor for resolving message identity from an exchange.
 * Returns the UIDs and source folder needed to operate on messages.
 */
type MailTargetExtractor = (exchange: Exchange<unknown>) => {
    uids: number[];
    folder: string;
};
/**
 * Shared base for all mail action types.
 * Every action can select a named account and provide a custom target extractor.
 */
interface MailActionBase {
    /** Named account from context config (uses default if omitted) */
    account?: string;
    /** Custom extractor for uid/folder when not using standard header/body locations */
    target?: MailTargetExtractor;
}
/**
 * Move message(s) to another IMAP folder.
 */
type MailMoveAction = MailActionBase & {
    action: "move";
    folder: string;
};
/**
 * Copy message(s) to another IMAP folder.
 */
type MailCopyAction = MailActionBase & {
    action: "copy";
    folder: string;
};
/**
 * Delete message(s) permanently.
 */
type MailDeleteAction = MailActionBase & {
    action: "delete";
};
/**
 * Add IMAP flags to message(s).
 */
type MailFlagAction = MailActionBase & {
    action: "flag";
    flags: string | string[];
};
/**
 * Remove IMAP flags from message(s).
 */
type MailUnflagAction = MailActionBase & {
    action: "unflag";
    flags: string | string[];
};
/**
 * Append a composed message to an IMAP folder (drafts, imports).
 */
type MailAppendAction = MailActionBase & {
    action: "append";
    folder: string;
    flags?: string | string[];
    date?: Date;
};
/**
 * Discriminated union for IMAP operations on mail messages.
 * The `action` field narrows available options via TypeScript.
 */
type MailAction = MailMoveAction | MailCopyAction | MailDeleteAction | MailFlagAction | MailUnflagAction | MailAppendAction;
/**
 * The payload an email message carries, delivered on `exchange.body` by the
 * mail source. This is the content a route operates on with `.transform()`,
 * `.filter()`, and friends. Envelope metadata (from, subject, recipients, ...)
 * travels on `routecraft.mail.*` headers instead. See
 * {@link MailMessage} for the full object returned by the fetch destination.
 *
 * `text` and `html` are two representations of the same content; either, both,
 * or neither may be populated depending on what the sender composed
 * (`multipart/alternative` vs a single-part message). Attachments are message
 * content (not envelope), so they stay on the body alongside `text`/`html`.
 */
interface MailBody {
    /** Plain text body, when the message included a `text/plain` part. */
    text?: string;
    /** HTML body, when the message included a `text/html` part. */
    html?: string;
    /** File attachments carried by the message. */
    attachments?: MailAttachment[];
}
/**
 * A parsed email message returned by the mail adapter fetch destination
 * (`.enrich(mail(...))`), as an array element of {@link MailFetchResult}.
 *
 * The streaming source (`.from(mail(...))`) does not deliver this shape; it
 * splits the message into a {@link MailBody} on `exchange.body` and
 * `routecraft.mail.*` headers. This object keeps the whole message together
 * because a batch fetch returns many messages and single-valued headers cannot
 * hold N envelopes.
 */
interface MailMessage {
    /** IMAP UID */
    uid: number;
    /** Message-ID header */
    messageId: string;
    /**
     * Literal `From:` header.
     *
     * For mailing-list forwards (e.g. Google Groups) this is the rewritten list
     * address. Use {@link MailSender.address} on {@link MailMessage.sender} for
     * the real sender when `verify !== "off"`.
     */
    from: string;
    /** Recipient address(es) */
    to: string | string[];
    /** Subject line */
    subject: string;
    /** Date the message was sent */
    date: Date;
    /**
     * Message body. `text` and `html` are two representations of the same
     * content and either, both, or neither may be populated depending on what
     * the sender composed (`multipart/alternative` vs a single-part message).
     */
    body: {
        /** Plain text body, when the message included a `text/plain` part. */
        text?: string;
        /** HTML body, when the message included a `text/html` part. */
        html?: string;
    };
    /** CC recipients */
    cc?: string[];
    /** BCC recipients */
    bcc?: string[];
    /** Reply-to address */
    replyTo?: string;
    /** File attachments */
    attachments?: MailAttachment[];
    /**
     * Raw email headers (only those requested via the `includeHeaders` option).
     * Keys are lowercased header names, values are strings or arrays for
     * multi-value headers (e.g. multiple Received lines).
     */
    rawHeaders?: Record<string, string | string[]>;
    /** IMAP flags (e.g. \Seen, \Flagged) */
    flags: Set<string>;
    /** The IMAP folder this message was fetched from */
    folder: string;
    /**
     * Computed effective sender with forward-chain and authentication evidence.
     * Omitted when the adapter is configured with `verify: "off"`.
     *
     * For mailing-list forwards (e.g. Google Groups) this resolves to the
     * original sender, not the rewritten `From:` header. For auto-forwards it
     * mirrors `from`. See {@link MailSender} for the full shape.
     */
    sender?: MailSender;
}
/**
 * A file attachment on a mail message.
 */
interface MailAttachment {
    /** Filename if available */
    filename?: string;
    /** MIME content type */
    contentType: string;
    /** Size in bytes */
    size: number;
    /** Raw attachment content */
    content: Buffer;
}
/**
 * Payload expected in exchange.body when sending email via `.to(mail())`.
 */
interface MailSendPayload {
    /** Recipient address(es) */
    to: string | string[];
    /** Subject line */
    subject: string;
    /** Plain text body */
    text?: string;
    /** HTML body */
    html?: string;
    /** CC recipients */
    cc?: string | string[];
    /** BCC recipients */
    bcc?: string | string[];
    /** Sender address (overrides option-level from) */
    from?: string;
    /** Reply-to address (overrides option-level replyTo) */
    replyTo?: string;
    /**
     * `Message-ID` of the message this send replies to. Sets the
     * `In-Reply-To` header and, when `references` is not given (or is
     * empty), also seeds the `References` header so the reply stitches
     * into the original thread in real mail clients. The inbound side
     * exposes the value as the `routecraft.mail.messageId` header
     * ({@link MailHeaders.MESSAGE_ID}).
     */
    inReplyTo?: string;
    /**
     * Explicit `References` chain for threading (oldest first). Overrides
     * the chain derived from `inReplyTo`. Pass the original message's
     * `References` plus its `Message-ID` to preserve deep threads.
     */
    references?: string | string[];
    /**
     * Custom RFC 5322 headers set on the outgoing message (e.g.
     * `X-Auto-Response-Suppress`, `List-Id`). Threading is easier via
     * `inReplyTo` / `references`, which win over the same keys given here.
     */
    headers?: Record<string, string>;
    /** File attachments */
    attachments?: Array<{
        filename: string;
        content: Buffer | string;
        contentType?: string;
    }>;
}
/**
 * Result returned by the fetch role (array of messages).
 */
type MailFetchResult = MailMessage[];
declare module "@routecraft/routecraft" {
    interface RoutecraftHeaders {
        /** IMAP UID of the source message. */
        [MailHeaders.UID]?: number;
        /** IMAP folder the message was fetched from. */
        [MailHeaders.FOLDER]?: string;
        /** `Message-ID` header of the source message. */
        [MailHeaders.MESSAGE_ID]?: string;
        /**
         * Literal `From:` header. For mailing-list forwards this is the rewritten
         * list address; use {@link MailSender} on `routecraft.mail.sender` for the
         * real sender when `verify !== "off"`.
         */
        [MailHeaders.FROM]?: string;
        /** Recipient address(es), always normalised to an array. */
        [MailHeaders.TO]?: string[];
        /** CC recipient address(es). Absent when the message had none. */
        [MailHeaders.CC]?: string[];
        /** BCC recipient address(es). Absent when the message had none. */
        [MailHeaders.BCC]?: string[];
        /** Subject line. */
        [MailHeaders.SUBJECT]?: string;
        /** Date the message was sent. */
        [MailHeaders.DATE]?: Date;
        /** Reply-To address, when present. */
        [MailHeaders.REPLY_TO]?: string;
        /** IMAP flags (e.g. `\Seen`, `\Flagged`). */
        [MailHeaders.FLAGS]?: ReadonlySet<string>;
        /**
         * Computed effective sender with forward-chain and authentication
         * evidence. Absent when the source is configured with `verify: "off"`.
         */
        [MailHeaders.SENDER]?: MailSender;
        /**
         * Raw email headers requested via the `includeHeaders` option. Keys are
         * lowercased header names; values are strings or arrays for multi-value
         * headers (e.g. multiple `Received` lines).
         */
        [MailHeaders.RAW_HEADERS]?: Readonly<Record<string, string | string[]>>;
        /**
         * SMTP send receipt: `Message-ID` of the SENT email (set by
         * `.to(mail())`). Distinct from {@link MailHeaders.MESSAGE_ID}, which
         * stays the SOURCE message's id.
         */
        [MailHeaders.SENT_MESSAGE_ID]?: string;
        /**
         * SMTP send receipt: accepted recipient addresses (set by `.to(mail())`).
         * `readonly` because exchange headers are frozen: a typed consumer that
         * pushed onto this array would compile and then throw.
         */
        [MailHeaders.ACCEPTED]?: readonly string[];
        /**
         * SMTP send receipt: rejected recipient addresses (set by `.to(mail())`).
         * `readonly` for the same reason as {@link MailHeaders.ACCEPTED}.
         */
        [MailHeaders.REJECTED]?: readonly string[];
        /** SMTP send receipt: raw SMTP server response string (set by `.to(mail())`). */
        [MailHeaders.RESPONSE]?: string;
    }
}

declare module "@routecraft/routecraft" {
    interface CraftConfig {
        /** Mail adapter configuration with named accounts */
        mail?: MailContextConfig;
    }
}

/**
 * CardDAV adapter type definitions.
 *
 * The adapter reads and writes vCard documents ({@link VCard}) over CardDAV.
 * Credentials live in context-level named accounts (see
 * {@link CarddavContextConfig}); per-adapter options select which account and
 * address book to use.
 *
 * @experimental
 */

/**
 * Connection settings for a named CardDAV account.
 *
 * For iCloud, `username` is the Apple ID and `appPassword` is an app-specific
 * password generated at appleid.apple.com (not the account password).
 * `serverUrl` defaults to iCloud when omitted.
 */
interface CarddavAccountConfig {
    /** DAV server base URL (default: iCloud `https://contacts.icloud.com`). */
    serverUrl?: string;
    /** Account username (Apple ID for iCloud). */
    username: string;
    /** App-specific password (Basic auth secret). Never logged. */
    appPassword: string;
    /** Default address book display name for this account. */
    addressBook?: string;
}
/**
 * Context-level CardDAV configuration. Added to {@link CraftConfig} via
 * `defineConfig({ carddav: {...} })` or `new CraftContext({ carddav: {...} })`.
 *
 * @example
 * ```typescript
 * defineConfig({
 *   carddav: {
 *     accounts: {
 *       default: {
 *         username: process.env.ICLOUD_ID!,
 *         appPassword: process.env.ICLOUD_APP_PW!,
 *       },
 *     },
 *   },
 * });
 * ```
 *
 * @experimental
 */
interface CarddavContextConfig {
    /** Named CardDAV accounts. The key `default` (or the first key) is the default. */
    accounts?: Record<string, CarddavAccountConfig>;
    /** Default server URL across all accounts (default: iCloud). */
    serverUrl?: string;
    /** Default address book display name across all accounts. */
    addressBook?: string;
}
/**
 * The destination action, mirroring the `mail` adapter's `action` flag.
 *
 * Absent (read role): `.from(carddav())` reads all contacts as a source and
 * `.enrich(carddav())` fetches all contacts as an array. Present (write role):
 *
 * - `"save"`: write to the contact at `url`, else create it (upsert).
 * - `"create"`: always create a new contact (generates a `UID` if absent).
 * - `"update"`: write to the contact at `url`, throwing `RC5014` if no `url` is
 *   resolvable. Read the contact first so it carries its `url`/`etag`.
 * - `"delete"`: delete the contact resolved from the body, headers, or `target`.
 *
 * A write serializes the whole {@link VCard} and replaces the card; it does not
 * merge. Because reading is lossless (every property round-trips), a
 * read-modify-write keeps data you did not touch. Removing a property from the
 * document removes it from the card, exactly like an `UPDATE` of a row.
 */
type CarddavAction = "save" | "create" | "update" | "delete";
/**
 * Resolve which contact a write/delete targets from the exchange, for cases
 * where the body is not a {@link VCard} carrying `url`/`uid`. Mirrors the mail
 * adapter's `target` extractor.
 */
type CarddavTargetExtractor = (exchange: Exchange<unknown>) => {
    url?: string;
    uid?: string;
};
/** Fields shared by every adapter role. */
interface CarddavCommonOptions {
    /** Named account from context config (uses the default account if omitted). */
    account?: string;
    /** Address book display name (uses the account/context default, else the first book). */
    addressBook?: string;
    /** Human-readable description for route discovery. */
    description?: string;
    /** Keywords for route discovery and categorization. */
    keywords?: string[];
}
/**
 * Server-role options: `.from(carddav())` (source) and `.enrich(carddav())`
 * (fetch-all). Named per the two-sided adapter policy (Server = we receive),
 * matching `MailServerOptions`.
 */
interface CarddavServerOptions extends CarddavCommonOptions {
    action?: undefined;
    /** Maximum number of contacts to read. */
    limit?: number;
}
/**
 * Client-role options: `.to(carddav({ action }))` for writes (`'save'`,
 * `'create'`, `'update'`) and deletes (`'delete'`). Named per the two-sided
 * adapter policy (Client = we send), matching `MailClientOptions`.
 */
interface CarddavClientOptions extends CarddavCommonOptions {
    action: CarddavAction;
    /** Resolve the target contact when the body lacks `url`/`uid`. */
    target?: CarddavTargetExtractor;
}
/**
 * Options for the CardDAV adapter. The `action` flag selects the role: absent
 * means read (`.from`/`.enrich`); present means write or delete (`.to`).
 */
type CarddavOptions = CarddavServerOptions | CarddavClientOptions;

declare module "@routecraft/routecraft" {
    interface CraftConfig {
        /** CardDAV adapter configuration with named accounts */
        carddav?: CarddavContextConfig;
    }
}

/**
 * SQLite-specific options for the telemetry plugin.
 *
 * These settings only apply when the SQLite backend is active.
 */
interface TelemetrySqliteOptions {
    /**
     * Path to the SQLite database file.
     * Defaults to `.routecraft/telemetry.db` in the current working directory.
     */
    dbPath?: string;
    /**
     * Maximum number of events to buffer before flushing to the SQLite
     * `events` table. Defaults to `50`.
     */
    eventBatchSize?: number;
    /**
     * Maximum time between event flushes.
     * Defaults to `1000` (1 second).
     */
    eventFlushInterval?: Duration;
    /**
     * Maximum number of exchange rows to keep in the database.
     * Older exchanges are pruned periodically. Set to `0` to disable pruning.
     * Defaults to `50000`.
     */
    maxExchanges?: number;
    /**
     * Maximum number of event rows to keep in the database.
     * Older events are pruned periodically. Set to `0` to disable pruning.
     * Defaults to `100000`.
     */
    maxEvents?: number;
    /**
     * Capture exchange headers and body at terminal lifecycle events
     * (completed, failed, dropped). Stored in a separate
     * `exchange_snapshots` table for on-demand inspection in the TUI.
     *
     * Disabled by default because bodies may contain sensitive data
     * and serialization adds overhead per exchange.
     *
     * Defaults to `false`.
     */
    captureSnapshots?: boolean;
    /**
     * Maximum serialized snapshot size in bytes. Bodies exceeding this
     * limit are truncated and flagged. Only applies when
     * `captureSnapshots` is `true`.
     *
     * Defaults to `65536` (64 KB).
     */
    maxSnapshotBytes?: number;
}
/**
 * Configuration options for the telemetry plugin.
 */
interface TelemetryOptions {
    /**
     * External OTel TracerProvider. When provided, spans are created via
     * this provider in addition to the default SQLite backend.
     *
     * Install `@opentelemetry/sdk-trace-base` and an exporter to use:
     *
     * @example
     * ```typescript
     * import { BasicTracerProvider, BatchSpanProcessor } from '@opentelemetry/sdk-trace-base'
     * import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http'
     *
     * const tracerProvider = new BasicTracerProvider()
     * tracerProvider.addSpanProcessor(
     *   new BatchSpanProcessor(new OTLPTraceExporter({ url: '...' }))
     * )
     * tracerProvider.register()
     *
     * telemetry({ tracerProvider })
     * ```
     */
    tracerProvider?: TracerProvider;
    /**
     * Disable the default SQLite backend. Only use when providing your
     * own `tracerProvider` for external export.
     *
     * Defaults to `false`.
     */
    disableSqlite?: boolean;
    /**
     * SQLite-specific configuration. Only applies when the SQLite backend
     * is active (`disableSqlite` is not `true`).
     */
    sqlite?: TelemetrySqliteOptions;
}
/**
 * Minimal logger interface for telemetry internals.
 *
 * Accepts the same signature as pino's `warn(bindings, message)` so we
 * can pass `ctx.logger` directly without coupling to pino types.
 */
interface TelemetryLogger {
    warn(bindings: Record<string, unknown>, message: string): void;
}
/**
 * A telemetry event record persisted to the SQLite `events` table.
 */
interface TelemetryEvent {
    /** Auto-incremented primary key */
    id?: number;
    /** ISO 8601 timestamp from the event payload */
    timestamp: string;
    /** Context ID from the event payload */
    contextId: string;
    /** Full event name (e.g. "route:myRoute:exchange:started") */
    eventName: string;
    /** JSON-serialized event details */
    details: string;
    /** Exchange ID extracted from payload details (nullable for non-exchange events) */
    exchangeId?: string;
    /** Correlation ID extracted from payload details (nullable for non-exchange events) */
    correlationId?: string;
}

declare module "@routecraft/routecraft" {
    interface CraftConfig {
        /** Telemetry plugin configuration (SQLite, OpenTelemetry) */
        telemetry?: TelemetryOptions;
    }
}

/**
 * HTTP plugin. Owns the route registries and request dispatchers for its
 * path-scoped mounts, registered on a named server (the listener itself
 * belongs to `defineConfig({ servers })`). Materialised by the config
 * applier so users typically configure it via `defineConfig({ http: {...} })`
 * rather than pushing it onto `config.plugins`. The function is still
 * exported for advanced users who want to wire it manually.
 *
 * The mount is the authentication wall: a mount with an effective validator
 * (its own `auth`, or the server's) requires a valid credential for every
 * route; `auth: false` removes the wall while keeping the inherited validator
 * reachable, so routes never see credentials except those that declare
 * `.authorize()`, which pull verification through it.
 *
 * Lifecycle:
 *   - `apply(ctx)`: validate options, publish the mount table on the context
 *     store, and mount each dispatcher on its mount's named server.
 *   - `teardown(ctx)`: unmount the dispatchers and clear the registries.
 */
declare function httpPlugin(options: HttpPluginOptions): CraftPlugin;

declare function serversPlugin(definitions: ServerDefinitions): CraftPlugin;

declare const WEB_INGRESSES: unique symbol;
declare module "@routecraft/routecraft" {
    interface StoreRegistry {
        [WEB_INGRESSES]: ReadonlyMap<string, WebIngress>;
    }
}
declare function requireWebIngress(ctx: CraftContext, serverName?: string): WebIngress;

/**
 * Validate and normalise a static pathname claim: an http mount prefix or the
 * MCP endpoint path.
 *
 * Dispatch compares the request URL's parsed pathname literally against these
 * strings, so a claim the WHATWG parser would rewrite (dot segments raw or
 * encoded, backslashes, spaces, non-ASCII) can never match what the server
 * dispatches on, and percent-encoding makes two spellings of the same
 * resource compare differently. A colon is allowed inside a segment (a legal
 * pathname character the parser preserves) but not at its start, which is the
 * `:param` shape route patterns treat as dynamic. Everything outside the
 * canonical form is refused at construction with RC5003.
 *
 * Normalisation strips exactly one trailing slash (`"/api/"` becomes
 * `"/api"`); repeated trailing slashes are a typo and fall through to the
 * empty-segment rejection instead of being silently collapsed, including the
 * bare `"//"` that would otherwise collapse into the catch-all.
 */
declare function normalizeStaticPathPrefix(raw: unknown, owner: string): string;

/**
 * Streaming response bodies for the http source: SSE framing for an
 * `AsyncIterable`, byte passthrough for a `ReadableStream`.
 *
 * The dispatcher normalises every route result to a `Response`, and a
 * streaming body is one more entry in that convention table rather than a
 * transport of its own. SSE needs no upgrade and no second request shape:
 * one exchange, one response, the pre-from chain applied once at entry.
 * That is why it lives on `http()` and not behind an `sse()` adapter.
 *
 * Both runtimes already carry the bytes. `Bun.serve` streams a
 * stream-bodied `Response` natively, and the `node:http` shim pumps the
 * body reader chunk by chunk with client-abort propagation. What this
 * module adds is the framing, the cancel path into the route's iterator,
 * and the single end-of-stream signal the dispatcher needs to close out
 * its per-request event.
 */

/**
 * One yielded SSE event.
 *
 * A yielded object is read as this descriptor when it carries an own `data`
 * property; every other object is itself the payload and is JSON-encoded
 * into `data`. Keys outside the four SSE fields are not sent, so a domain
 * object that happens to have a `data` field is mapped in a `.transform()`
 * step rather than yielded raw.
 */
interface SseEvent {
    /** Payload. Strings are sent verbatim, anything else is JSON-encoded. */
    data: unknown;
    /** Event name, read by `addEventListener(name)` on an `EventSource`. */
    event?: string;
    /** Last event id, echoed back by a reconnecting client as `Last-Event-ID`. */
    id?: string | number;
    /** Reconnection delay in whole milliseconds. */
    retry?: number;
}

/**
 * RFC 9728 OAuth 2.0 Protected Resource Metadata, shared by every http
 * surface.
 *
 * The document is how a refused caller learns who issues acceptable
 * credentials: a 401 challenge carries a `resource_metadata` URL, the
 * caller fetches it, and `authorization_servers` plus `scopes_supported`
 * name the way in. Core owns the builder and the serving fallback (see
 * `HttpMountRegistry.dispatch`); the MCP transport consumes the same
 * builder for the document it serves on its own claimed path.
 *
 * Everything here is sourced from configuration the operator already
 * wrote: issuer from `jwt()` / `jwks()`, scopes from what a mount
 * declares. A validator with no issuer produces an honest minimal
 * document rather than an invented one.
 */
/** Root path of the RFC 9728 protected-resource metadata document. */
declare const PROTECTED_RESOURCE_METADATA_PATH = "/.well-known/oauth-protected-resource";
/**
 * RFC 9728 OAuth 2.0 Protected Resource Metadata payload returned by
 * `GET /.well-known/oauth-protected-resource` (and its path-suffixed
 * variants). Optional fields are omitted from the JSON when unset.
 */
interface ProtectedResourceMetadata {
    resource: string;
    resource_name?: string;
    authorization_servers?: string[];
    bearer_methods_supported: ["header"];
    scopes_supported?: string[];
    resource_documentation?: string;
}
/** What a metadata document is built from; every field beyond `resource` is optional. */
interface ProtectedResourceMetadataInput {
    /** Absolute URL identifying the protected resource. */
    resource: string;
    /** Human-readable name (RFC 9728 `resource_name`). */
    resourceName?: string;
    /** Issuer(s) of acceptable tokens, from the effective validator. */
    issuer?: string | string[];
    /** Scopes this resource understands, from resolved configuration. */
    scopesSupported?: readonly string[];
    /** Documentation URL (RFC 9728 `resource_documentation`). */
    documentationUrl?: string;
}
/**
 * Build the RFC 9728 protected-resource metadata document.
 *
 * `resource` is a required input rather than a default the caller patches
 * afterwards: the resolved identity depends on the bound address, and a
 * builder that returned a knowingly wrong placeholder would let any future
 * call site silently advertise it.
 *
 * `authorization_servers` is populated from the effective validator's
 * `issuer`. When the verifier exposes no issuer, the field is omitted
 * (RFC 9728 allows that): bearer is accepted and no AS is discoverable,
 * which is the truth of a bare `{ validator }`.
 */
declare function buildProtectedResourceMetadata(input: ProtectedResourceMetadataInput): ProtectedResourceMetadata;
/**
 * The RFC 9728 metadata URL a challenge on `requestUrl` should hint at.
 *
 * Path insertion per RFC 9728 section 3.1: the well-known prefix goes
 * between the origin and the resource path, so `/ops/routes` hints at
 * `/.well-known/oauth-protected-resource/ops/routes`. The origin comes
 * from the request URL, which reflects the Host header the caller used,
 * so the hint survives port forwards and reverse proxies that preserve
 * Host.
 */
declare function resourceMetadataUrlFor(requestUrl: string): string;
/**
 * Build the RFC 6750 bearer challenge every routecraft-owned surface emits
 * on a refusal.
 *
 * One builder rather than one string per call site, because the challenge
 * is a single wire contract with a single consumer-side parser (the CLI's
 * refusal enrichment): a parameter added in one copy and not another would
 * still parse and silently say less. `realm` leads and `resource_metadata`
 * trails, matching what the MCP mount already emits, so parsers keyed on
 * either order hold.
 *
 * `requestUrl` is required, not optional: every bearer refusal hints
 * (`.standards/security.md` section 6), and an optional parameter would let
 * the next refusal path compile while quietly dropping the hint.
 */
declare function bearerChallenge(options: {
    requestUrl: string;
    params?: Record<string, string>;
}): string;

/**
 * CORS for browser-facing http surfaces on a named server.
 *
 * Owned by core so every surface that needs a browser to read its responses
 * (the MCP HTTP transport is the first consumer) shares one policy engine and
 * one header math, instead of each protocol mount growing a slightly
 * different copy.
 *
 * The default is **loopback-only**: a request whose `Origin` is on `localhost`,
 * `127.0.0.1`, or `::1` (any port, http or https) gets reflected; everything
 * else gets no `Access-Control-Allow-Origin` header back and is blocked by the
 * browser. Protocol mounts separately require an explicit `browserOrigins`
 * opt-in before processing any request carrying Origin, including loopback.
 * CORS configuration never grants browser admission. See `.standards/security.md` ->
 * "Security defaults policy" for the broader principle.
 *
 * Server-to-server callers (curl, the craft CLI, `mcp-remote`) are unaffected
 * by CORS because they do not send an `Origin` header.
 *
 * The public option surface is intentionally minimal: only `origin` is
 * configurable. Method, header, expose-header, credentials, and preflight-cache
 * values are framework-controlled constants -- chosen to satisfy the RFC 9728
 * discovery contract and the MCP JSON-RPC handshake -- and can be expanded
 * later if a real use case demands it.
 */
/**
 * Resolver form of `origin`. Receives the request's `Origin` header (or
 * `undefined` when absent) and returns either the value to echo in
 * `Access-Control-Allow-Origin`, or `false` to disallow.
 *
 * Implementations SHOULD NOT throw. A thrown error is caught at the request
 * boundary and treated as `false` (fail-closed), but emitting an exception
 * also clears CORS for that request silently. Return `false` explicitly to
 * disallow.
 *
 * Keeping this transport-agnostic (no `IncomingMessage`) lets the helper run
 * on Bun, Node, and in tests without coupling to `node:http`.
 */
type HttpCorsOriginResolver = (requestOrigin: string | undefined) => string | false;
/**
 * CORS configuration for a browser-facing http surface. The MCP transport
 * passes it via `mcpPlugin({ cors: { origin: ... } })`.
 *
 * Omitting the config entirely applies the loopback-only default. Consumers
 * accept `false` in their own option slot to disable CORS handling completely
 * (useful when a reverse proxy or CDN owns CORS).
 */
interface HttpCorsOptions {
    /**
     * Allowed origin(s).
     *
     * - `"*"` -- permissive, no `Vary: Origin` emitted.
     * - `string` -- exact match against the request `Origin`; non-match returns no allow header.
     * - `string[]` -- allowlist; if the request `Origin` matches one entry, it is reflected.
     * - {@link HttpCorsOriginResolver} -- custom resolver, returns the value to echo or `false` to disallow.
     */
    origin: "*" | string | string[] | HttpCorsOriginResolver;
}
/**
 * Internal resolved CORS shape. The consumer never has to branch on string vs
 * array vs function form of `origin`. Not exported beyond this file.
 *
 * @internal
 */
interface ResolvedHttpCors {
    resolveOrigin: HttpCorsOriginResolver;
    /** `true` when `origin` was the literal `"*"`. Skips `Vary: Origin`. */
    isWildcard: boolean;
}
/**
 * Default origin resolver: reflect the request `Origin` iff it is loopback
 * AND in canonical form per RFC 6454 §7.1 (`scheme://host[:port]`, no path,
 * no userinfo, no query, no fragment). Returns `false` otherwise.
 *
 * Real browsers never emit anything other than a canonical Origin, so this
 * tightening costs nothing in practice while ensuring we never echo a
 * malformed value into `Access-Control-Allow-Origin`.
 */
declare function defaultLoopbackOriginResolver(requestOrigin: string | undefined): string | false;
/**
 * Resolve a `cors` config slot into either a fully-populated internal shape or
 * `null` (CORS disabled entirely). `undefined` produces the loopback default.
 */
declare function resolveCorsOptions(input: false | HttpCorsOptions | undefined): ResolvedHttpCors | null;
/**
 * Build the response headers to add for a given request `Origin`.
 *
 * Returns an empty object when CORS is disabled (`cors === null`).
 *
 * When the policy is origin-dependent (non-wildcard), `Vary: Origin` is
 * **always** included -- including for rejected origins -- so a shared cache
 * keyed by the response cannot serve a no-CORS response back to a loopback
 * origin. Disallowed origins receive `{ Vary: "Origin" }` only, with no
 * `Access-Control-Allow-Origin`.
 *
 * The caller is responsible for applying these headers: spread the record
 * into the response headers, appending `Vary` when a prior value exists.
 *
 * @param cors Resolved CORS options, or `null` to short-circuit.
 * @param requestOrigin Value of the request's `Origin` header.
 * @param preflight `true` to include `Access-Control-Allow-Methods/Headers`.
 */
declare function buildCorsHeaders(cors: ResolvedHttpCors | null, requestOrigin: string | undefined, preflight: boolean): Record<string, string>;

/**
 * Ops plugin: the operational surface, with health as its first capability.
 *
 * It folds framework lifecycle events into a per-context {@link HealthState}
 * and serves the result over HTTP. The judgement lives in `state.ts` and the
 * response contract in `report.ts`; this file is the wiring.
 *
 * The surface is a mount on a named server rather than a listener of its own,
 * so an internal-only ops port is a second entry in `defineConfig({ servers })`
 * that this mount points at, and the socket's lifecycle belongs to the server
 * plugin.
 */

/**
 * The operational surface for a routecraft app.
 *
 * Materialised by the config applier, so apps normally configure it with
 * `defineConfig({ ops: {} })` rather than pushing it onto `config.plugins`.
 * The function is exported for advanced wiring.
 *
 * What it reports needs no application code: route lifecycle, circuit-breaker
 * position and the context's own serving state are all derived from events the
 * framework already emits. Indicators are the one thing an app adds by hand,
 * for dependencies the framework cannot see.
 *
 * Lifecycle:
 * - `apply(ctx)`: build the ledger, bind indicators, subscribe to lifecycle
 *   events, and register the mount. Nothing is listening yet, so a
 *   misconfiguration fails the build rather than a live surface.
 * - `start(ctx)`: check that every route-bound indicator names a real route.
 *   The server binds its listener in its own `start()`, after routes are up,
 *   so a probe arriving before that gets connection refused, which every
 *   orchestrator reads as not-ready.
 * - `teardown(ctx)`: unmount, unsubscribe, and release the indicator bindings.
 *
 * The health surface never walls, whatever `auth` says: the ingress never
 * authenticates on its own, and this surface calls `authenticate()` only to
 * decide whether to serve `details`. A probe carrying no credential still
 * gets every status, which is the only way an orchestrator can use it, while
 * an operator holding a token the effective validator (the mount's own
 * `auth`, else the server's) admits also gets the diagnostics.
 */
declare function opsPlugin(options?: OpsPluginOptions): CraftPlugin;

/**
 * Health state for one context.
 *
 * Pure and framework-free on purpose: it deals in route-id strings and its own
 * types, never in context or adapter modules. The plugin translates framework
 * events into calls here; this file holds the judgement and is unit-tested in
 * isolation with an injected clock.
 *
 * What health answers is deliberately narrow: can this component serve at all?
 * A route is `down` only when it is not running (its source gave up) and
 * `degraded` only when a circuit breaker is holding calls off or it was taken
 * offline on purpose. The outcome of an individual exchange never decides it.
 * A refused caller, a validation error, or a business rule saying no are all a
 * running route behaving correctly, and paging on them turns every scope gap
 * and every malformed request into an incident. Those outcomes are still
 * counted, and the count still surfaces in `details` so a human reading the
 * report can see a route that is serving badly; they just do not change its
 * status. Escalating repeated failure into a health signal is the circuit
 * breaker's job, because only the breaker knows which errors it counts
 * (routecraft excludes non-retryable ones, so authorization failures cannot
 * trip it) and only the breaker actually stops the route serving.
 */

/**
 * The read surface other components get.
 *
 * Published on the store instead of {@link HealthState} itself. Withholding
 * the constructor prevents nothing: `ctx.getStore(OPS_HEALTH_STATE)` hands
 * back the live instance, so a wider type would let any consumer call
 * `sourceDied` or `reportIndicator` and drive the ledger into a state the
 * framework never observed, which is the invariant the whole design rests on.
 * The `/ops` action surface will get a deliberate mutating interface when it
 * ships, rather than inheriting every method by default.
 */
interface HealthLedger {
    /** Where the app is in its serving lifecycle. */
    readonly lifecycle: ContextState;
    report(view?: HealthView): HealthReport;
    routeComponentOf(routeId: string): HealthComponent | undefined;
    indicatorComponentOf(name: string): HealthComponent | undefined;
}

/**
 * Indicator handles: the one thing an app writes by hand for health.
 *
 * Routes, circuit breakers and the serving lifecycle are all derived from
 * events the framework already emits, so an app that only wants those writes
 * no code at all. An indicator exists for the other case: a dependency whose
 * health the framework cannot see, such as a mailbox, a third-party API, or a
 * licence server.
 */

/**
 * Declare an indicator: a named dependency whose health the app reports.
 *
 * The returned handle is both the declaration and the push surface, and it is
 * inert until an ops plugin binds it to a context. Register it through
 * `ops.indicators` so a push has a ledger to land in; a handle that is never
 * registered is reported at context start, where the message can name the fix,
 * rather than by throwing from whatever step happened to push it.
 *
 * Two ways to report, and the first needs no code in the route:
 *
 * ```typescript
 * // Bound to a probe route: a completed exchange reports up, a failed one
 * // reports down, and no exchange within maxAge goes stale.
 * export const mailHealth = defineIndicator({
 *   name: "mail",
 *   maxAge: "15m",
 *   route: "probe-mail",
 * });
 *
 * // Pushed by hand, from any .process() or .error() step.
 * mailHealth.down({ subsystem: "imap" });
 * ```
 *
 * A handle used against several live contexts reports into each of their
 * ledgers, because a push carries no context of its own and routecraft exposes
 * no ambient accessor inside an `.error()` handler. In the ordinary
 * single-context process that is exactly one ledger.
 *
 * Pushing through an unbound handle is deliberately inert rather than a throw.
 * Health instrumentation must not be able to kill the code it instruments: an
 * exchange draining during shutdown, after teardown released the binding, would
 * otherwise take an error out of its `.error()` handler and into the route.
 *
 * @param definition - Name, optional staleness window, failure domain, and
 *   optional route binding.
 * @returns A handle to register in `ops.indicators` and push through.
 */
declare function defineIndicator(definition: IndicatorDefinition): Indicator;

/**
 * Symbol key the ops plugin publishes its per-context ledger under.
 *
 * Exposed on the store so other surfaces can read health without going
 * through HTTP: the CLI's TUI, a future management console, and the `/ops`
 * action endpoints all need the same ledger the endpoints report from.
 * `Symbol.for` so the key is shared across duplicate package copies in a
 * workspace, matching every other plugin's convention.
 */
declare const OPS_HEALTH_STATE: unique symbol;
/**
 * Symbol key for the management resources other packages contribute, keyed
 * by resource name. Written by {@link registerOpsResource}, read by the ops
 * mount per request, so a resource registered by a plugin applied before
 * or after the ops plugin is served alike.
 */
declare const OPS_RESOURCES: unique symbol;
/**
 * Contribute a read-only resource to the management API. See
 * {@link OpsResource} for the contract and where it is served.
 *
 * Call it from a plugin's `apply()`. It needs no ops plugin to be present:
 * the registration lives on the context store and is served when an ops
 * mount exists, and inert otherwise.
 *
 * @throws RC5053 on a reserved or malformed name, or a name already taken
 */
declare function registerOpsResource<TItem>(ctx: CraftContext, resource: OpsResource<TItem>): void;
/**
 * An indicator another plugin contributes, without the app listing it.
 *
 * `defineIndicator` is the app's API: a handle declared in source and named
 * in `ops.indicators`. A plugin that watches a dependency the app never
 * wrote a line for (the remotes plugin and the instances it imports from)
 * has no such handle to hand the app, so it contributes the declaration
 * here and reports through the function the contribution returns. The
 * ops plugin binds it to its ledger at start, and before that, or without
 * an ops plugin at all, a report is inert for the same reason a push
 * through an unbound handle is: health instrumentation must not be able
 * to fail the code it instruments.
 */
interface ContributedIndicator {
    readonly name: string;
    readonly domain?: FailureDomain;
    readonly maxAge?: Duration;
    /**
     * Where reports go: one sink per ops ledger that bound the indicator, so a
     * context carrying two ops mounts reports into both. Empty until an ops
     * plugin binds it, and empty again after teardown.
     */
    readonly sinks: Set<(health: Health, reportedAt: number) => void>;
    /**
     * The most recent report, replayed to a ledger that binds after it was
     * made. A contributor whose start() ran before the ops plugin's would
     * otherwise have its first verdict lost, and a remote unreachable at boot
     * would read as up until its next refresh.
     */
    last?: {
        health: Health;
        at: number;
    };
}
/**
 * Symbol key for the indicators other plugins contribute, keyed by name.
 * Written by {@link contributeOpsIndicator}, bound by the ops plugin's
 * `start()`, so a contribution made from any plugin's `apply()` is served
 * whatever order the plugins were applied in.
 *
 * @internal
 */
declare const OPS_CONTRIBUTED_INDICATORS: unique symbol;
declare module "@routecraft/routecraft" {
    interface StoreRegistry {
        [OPS_HEALTH_STATE]: HealthLedger;
        [OPS_RESOURCES]: Map<string, OpsResource>;
    }
}
declare module "@routecraft/routecraft" {
    interface StoreRegistry {
        [OPS_CONTRIBUTED_INDICATORS]: Map<string, ContributedIndicator>;
    }
}

/**
 * Paging the management API's collections.
 *
 * Keyset cursors, matching `DeferralStore.findExpired`'s idiom rather
 * than inventing a second one. The reason is not consistency for its own
 * sake: the collections this API will grow (deferrals, exchange
 * history) are live and mutating while an operator reads them, and offset
 * paging over a mutating set silently skips rows and repeats others. That
 * surfaces as "the console lost a deferred payout", never as an error.
 *
 * A cursor is valid only for the filter that produced it, exactly as the
 * deferral store's cursor is valid only against the store that produced
 * it. Replaying one under a different filter would hand back a page from a
 * different result set with no way for the caller to notice, so it is
 * refused instead.
 */

/**
 * Page size when the caller names none.
 *
 * Exported so a contributed resource defaults to the same number rather
 * than picking its own: two independent defaults that happen to agree
 * drift the moment one is changed, and the collections would then page
 * differently for no reason a reader could see.
 */
declare const DEFAULT_PAGE_SIZE = 50;
/**
 * The result set a cursor pages, for a collection the mount does not own:
 * a contributed resource renders its own filter canonically (fixed field
 * order, absent fields as `null`) and hands the string here, so its
 * cursors are bound to its filters exactly as the route listing's are.
 */
interface CursorScope {
    readonly fingerprint: string;
}
/** What binds a cursor: the route filter, or a contributor's own scope. */
type PageFilter = OpsRouteFilter | CursorScope;
/**
 * The one refusal for a cursor this API cannot use.
 *
 * Named once because it is thrown from three places: both arms of
 * {@link decodeCursor} and any contributed resource decoding a keyset of
 * its own. Three copies of the sentence meant the same failure answered
 * differently depending on which half rejected it.
 *
 * @throws RC5059 always
 */
declare function malformedCursor(): never;
/**
 * Build a cursor scope for a contributed collection: the resource name,
 * then its filter fields in a fixed order.
 *
 * A function rather than a paragraph a contributor re-reads and re-types.
 * The recipe fails silently when it is got wrong: leave a filter field
 * out of the fingerprint and the cursors it mints are honoured across
 * that filter, handing back a page of a different result set with no
 * error, which is the one thing the fingerprint exists to prevent.
 */
declare function cursorScope(resource: string, ...fields: ReadonlyArray<string | number | boolean | null | undefined>): CursorScope;
/**
 * Read `limit` and `after` off a resource's raw query, as the mount reads
 * them for the route listing: a `limit` that is not a positive integer is
 * `RC5059`, which the mount answers as a 400 naming the rule.
 */
declare function parsePageQuery(query: Readonly<Record<string, string>>): {
    limit?: number;
    after?: string;
};
/**
 * Mint a cursor pointing just past `key`, bound to the filter that
 * produced the page.
 *
 * Opaque to the caller by construction: base64url of a shape this module
 * owns. A client that decodes it and constructs its own is outside the
 * contract, which is the point of publishing a string rather than a key.
 *
 * The key is whatever orders the contributor's own result set strictly:
 * {@link takePage} passes a row's `id`, and a collection ordered by
 * something else renders its keyset into one string and reads it back
 * itself. The deferral listing does that, ordering by `(deferredAt, id)`
 * because a deferral id says nothing about time.
 */
declare function encodeCursor(key: string, filter: PageFilter): string;
/**
 * Decode a cursor and check it was minted under this same filter.
 *
 * Both failure modes are the caller's, and they are deliberately one code
 * with different messages: a garbled cursor and a cursor replayed under a
 * changed filter are both "this cursor cannot be used here", and neither
 * says anything about the data behind it.
 */
declare function decodeCursor(cursor: string, filter: PageFilter): string;
/**
 * Take one page from an id-ordered list.
 *
 * The list must already be sorted by `id` on the same strict total order
 * the cursor assumes; `compareCodeUnits` is that order.
 */
declare function takePage<T extends {
    id: string;
}>(sorted: readonly T[], filter: PageFilter, limit: number | undefined, after: string | undefined): {
    items: T[];
    nextCursor?: string;
};

/**
 * Reading a runtime's own version string.
 *
 * Two places need it and they must not answer differently: the CLI gate
 * refuses a Bun below the supported floor, and the ops client decides
 * whether this Bun re-sends a dropped non-idempotent request by itself.
 * Written twice, the two copies disagreed on the same input within one
 * release: one read a two-segment `"1.4"` as `1.4.0` and the other as
 * unparseable.
 */
/** A SemVer core, with prerelease and build metadata already dropped. */
interface RuntimeVersion {
    readonly major: number;
    readonly minor: number;
    readonly patch: number;
}
/**
 * Parse a runtime version string, or `undefined` when it is not one.
 *
 * A missing patch (or minor) segment reads as zero, matching how a
 * runtime that reports `"1.4"` means `1.4.0`. Prerelease and build
 * metadata are stripped per SemVer, so a canary compares as its release.
 *
 * @internal
 */
declare function parseRuntimeVersion(version: string): RuntimeVersion | undefined;
/**
 * Negative when `a` is older than `b`, zero when they are the same core.
 *
 * @internal
 */
declare function compareRuntimeVersion(a: RuntimeVersion, b: RuntimeVersion): number;

/**
 * Remotes plugin: the dispatchable routes of other instances become direct
 * endpoints here.
 *
 * The consumer is a deployment where one constrained instance hosts
 * approved capabilities behind its own door and every engineer runs a
 * local instance with their own agents. The local instance names the
 * server under `remotes`, reads its route inventory through the ops
 * management API, and registers each route in the direct store and the
 * capability registry under a local endpoint. From then on nothing else
 * in the framework knows the route is elsewhere: `direct()`, `forward()`,
 * `directTool()`, `Direct(...)` in an agent's tool list, the tool policy
 * and the local ops listing all see a capability.
 *
 * The server keeps its service credentials and its `.authorize()`; this
 * side holds only a bearer for the server's door, and the local caller's
 * principal is never forwarded. What the server's validator mints from the
 * bearer is the identity every imported route runs under.
 */

/**
 * Another instance's dispatchable routes as direct endpoints here.
 *
 * Materialised by the config applier, so apps normally write
 * `defineConfig({ remotes: { default: { url, auth } } })` rather than
 * pushing it onto `config.plugins`.
 *
 * `apply` validates, builds a client per remote and contributes an
 * indicator per remote to the health report. `start` reads every
 * inventory once, awaited, so a route the remote exposes is a local
 * endpoint by the time the context reports ready, and a remote that is
 * unreachable registers nothing, logs, and reports its indicator down;
 * its routes appear on the refresh that first reaches it. `teardown`
 * clears the timers and removes every endpoint this plugin installed.
 */
declare function remotesPlugin(options: RemotesPluginOptions): CraftPlugin;

/**
 * Directive returned from an {@link ErrorHandler} to drop the failing
 * exchange instead of recovering with a body. The engine marks the
 * exchange dropped and emits `route:exchange:dropped` with `reason`;
 * `route:exchange:completed` does not fire and no recovery body is produced.
 */
interface RecoveryDrop {
    readonly kind: "drop";
    readonly reason: string;
}
/**
 * Directive returned from an {@link ErrorHandler} to propagate the
 * original error, declining recovery. Equivalent to `throw error` inside
 * the handler: the engine follows the handler-threw path
 * (`route:error-handler:failed`, then the route-level cascade for
 * step-scope handlers or the `route:exchange:failed` path for route scope).
 */
interface RecoveryRethrow {
    readonly kind: "rethrow";
}
/**
 * Branded directive an error handler may return instead of a recovery
 * body. Plain return values (anything unbranded) keep their existing
 * meaning: they become the recovered exchange body. The brand makes the
 * directive unambiguous, so a handler that legitimately recovers with a
 * `{ kind: "drop" }`-shaped body is never misread; directives are only
 * created via the {@link recovery} helpers.
 */
type Recovery = RecoveryDrop | RecoveryRethrow;
/**
 * Helpers for building {@link Recovery} directives inside `.error()`
 * handlers (route scope and step scope alike).
 *
 * @example
 * ```ts
 * craft()
 *   .error((err, ex) =>
 *     isTransient(err) ? recovery.rethrow() : recovery.drop("poison message"),
 *   )
 *   .from(source)
 * ```
 */
declare const recovery: {
    /**
     * Drop the failing exchange. The `reason` surfaces on the
     * `route:exchange:dropped` event (and the TUI), mirroring filter drop
     * semantics.
     */
    drop(reason?: string): RecoveryDrop;
    /**
     * Decline recovery and propagate the original error, exactly as if the
     * handler had thrown it.
     */
    rethrow(): RecoveryRethrow;
};
/**
 * Type guard for {@link Recovery} directives. Checks the brand AND the
 * directive shape: a branded object with an unknown `kind` (e.g. a
 * hand-built object reusing the `Symbol.for` brand) must not pass as a
 * directive, so only the two known shapes are accepted; anything else
 * keeps its plain-recovery-body meaning.
 */
declare function isRecovery(value: unknown): value is Recovery;

/**
 * Function form of a processor: receives the full exchange and returns a new
 * exchange. Use with `.process(processor)`. Prefer pure logic; use `.to()`
 * for IO side effects.
 *
 * The returned exchange must be a new value; the parameter is `Readonly<>`
 * and the framework will TypeError if user code reassigns its fields. Build
 * the result via spread:
 *
 * ```ts
 * .process((ex) => ({
 *   ...ex,
 *   body: { ...ex.body, hello: "world" },
 *   headers: { ...ex.headers, "x-tag": "v" },
 * }))
 * ```
 *
 * The framework re-wraps a plain spread back into a proper exchange instance
 * via {@link DefaultExchange.rewrap}, preserving the internal context binding.
 *
 * The second argument carries the step's {@link StepSignalContext}: when an
 * enclosing `.timeout()` expires, `ctx.signal` aborts, so a processor doing
 * cancellation-aware IO can forward it (`fetch(url, { signal })`). Declaring
 * only the first parameter remains valid.
 *
 * @template T - Current body type
 * @template R - Result body type (default T)
 */
type CallableProcessor<T = unknown, R = T, Ex extends Exchange<T> = Exchange<T>> = (exchange: Ex, ctx?: StepSignalContext) => Promise<Exchange<R>> | Exchange<R>;
/**
 * Processor adapter: transforms the whole exchange (body, headers). Used with `.process()`.
 * Use when you need headers or full exchange; use `.transform()` for body-only mapping.
 *
 * @template T - Current body type
 * @template R - Result body type
 */
interface Processor<T = unknown, R = T> extends Adapter {
    process: CallableProcessor<T, R>;
}

/**
 * Type-only symbol used to mark enrich aggregators that declare a merge shape
 * (e.g. only(getValue, "links")). .enrich() infers result body as Current & that shape.
 * Not used at runtime.
 */
declare const ENRICH_MERGE_TYPE: unique symbol;
/**
 * Returns true if the value is a CraftContext instance.
 */
declare function isCraftContext(obj: unknown): boolean;
/**
 * Returns true if the value is a Route (DefaultRoute) instance.
 */
declare function isRoute(obj: unknown): boolean;
/**
 * Returns true if the value is a RouteBuilder instance (has .build()).
 */
declare function isRouteBuilder(obj: unknown): boolean;
/**
 * Returns true if the value is a RouteDefinition (from craft().from().build()).
 */
declare function isRouteDefinition(obj: unknown): boolean;
/**
 * Returns true if the value is a RoutecraftError instance.
 */
declare function isRoutecraftError(obj: unknown): boolean;
/**
 * A RoutecraftError's RC code, or `undefined` for anything else.
 *
 * Lives beside the guard because every caller of one wants the other, and the
 * knowledge that the code sits on `.rc` was previously re-encoded as an
 * unchecked cast at each site. A cast fails silently when the field moves; one
 * reader fails loudly.
 */
declare function rcCodeOf(error: unknown): string | undefined;
/**
 * Returns true if the value is an Exchange instance.
 */
declare function isExchange(obj: unknown): boolean;

/**
 * Function form of an enricher: receives the exchange and produces a value
 * (a lookup result, a file's parsed content, an API response). Used with
 * `.enrich()`, and accepted by `.to()` / `.tap()` where the returned value
 * replaces the body / is discarded respectively.
 *
 * The second argument carries the step's {@link StepSignalContext}: when an
 * enclosing `.timeout()` expires, `ctx.signal` aborts, so an enricher doing
 * cancellation-aware IO can forward it (`fetch(url, { signal })`). Declaring
 * only the first parameter remains valid.
 *
 * @template T - Current body type
 * @template R - Produced value type
 */
type CallableEnricher<T = unknown, R = unknown, Ex extends Exchange<T> = Exchange<T>> = (exchange: Ex, ctx?: StepSignalContext) => Promise<R> | R;
/**
 * Enricher adapter: pulls a value IN per exchange (HTTP GET, file read, IMAP
 * fetch, LLM call). Used with `.enrich()`; also accepted by `.to()` (the
 * result replaces the body) and `.tap()` (the result is discarded).
 *
 * The pull-in counterpart of {@link Destination}: `send` pushes out and is
 * void, `fetch` pulls in and produces a value. An adapter may implement both
 * roles on one object (e.g. `file()`: send writes, fetch reads); the
 * operation keyword selects the role, and `.to()` prefers `send`.
 *
 * @template T - Current body type
 * @template R - Produced value type
 */
interface Enricher<T = unknown, R = unknown> extends Adapter {
    fetch: CallableEnricher<T, R>;
}
/**
 * Aggregator used by `.enrich()` to merge the fetched value with the current
 * exchange. Receives the original exchange and the enrichment result; returns
 * the (derived) exchange.
 *
 * @template T - Current body type
 * @template R - Type produced by the enricher
 */
type EnrichAggregator<T = unknown, R = unknown> = (original: Exchange<T>, enrichmentData: R) => Exchange<T>;
/**
 * When an aggregator is branded with [ENRICH_MERGE_TYPE], `.enrich()` infers the result body as `Current & shape`.
 * Used by `only(getValue, into)` when `into` is a string literal for type inference.
 */
type EnrichMergeShape = Record<string, unknown>;
/**
 * Returns an aggregator for `.enrich()` that merges a single value from the enrichment result into the body.
 *
 * - `getValue(enrichmentData)` extracts the value; null/undefined are not merged.
 * - If `into` is omitted: plain objects are spread onto body; primitives go to `body.stdout`; arrays to `body.array`.
 * - If `into` is provided: the value is set at `body[into]`. When `into` is a string literal, the builder infers body as `Current & { [into]: V }`.
 *
 * @param getValue - Function to extract the value from the enrichment result
 * @param into - Optional key to set on body (enables type inference when a string literal)
 * @returns An aggregator usable with `.enrich(enricher, aggregator)`
 *
 * @example
 * ```typescript
 * .enrich(http({ url: (ex) => `https://api.example.com/users/${ex.body.userId}` }), only((r) => r.body.name, 'userName'))
 * // Body type becomes Current & { userName: string }
 * ```
 */
declare function only<R, V, K extends string>(getValue: (enrichmentData: R) => V, into: K): EnrichAggregator<unknown, unknown> & {
    [ENRICH_MERGE_TYPE]: Record<K, V>;
};
declare function only<T = unknown, R = unknown, V = unknown>(getValue: (enrichmentData: R) => V, into?: string): EnrichAggregator<T, R>;
/**
 * No-op aggregator for `.enrich()`: returns the original exchange unchanged (enrichment is ignored).
 * Use when you only need the side effect of the fetch (e.g. warming a cache) while gating the pipeline on it.
 *
 * @example
 * ```typescript
 * .enrich(http({ url: 'https://api.example.com/ping' }), none())
 * ```
 */
declare const none: <T = unknown, R = unknown>() => EnrichAggregator<T, R>;

/**
 * Context handed to a destination's `send`. Extends the abort surface with a
 * header sink: a send that produces a receipt (a message id, an etag, a
 * created-resource URL) surfaces it by calling `setHeader`, and the `.to()`
 * step merges the collected headers onto the continuing exchange. The body is
 * never touched by a send; receipts ride headers, results ride `fetch`.
 *
 * `.tap()` also provides the sink, but the tap runs against a detached
 * snapshot, so headers set there are discarded with it.
 *
 * The parameter is optional at the call site (adapters invoked directly in
 * tests may omit it), so implementations should guard: `ctx?.setHeader(...)`.
 */
interface SendContext extends StepSignalContext {
    /** Record a receipt header to merge onto the continuing exchange. */
    setHeader(key: string, value: HeaderValue): void;
}
/**
 * Function form of a destination: receives the exchange and performs a side
 * effect. Strictly void: a returned value is not a body replacement (use an
 * {@link Enricher} or `.enrich()` when the step should produce data).
 *
 * The second argument carries the step's {@link SendContext}: `signal` aborts
 * when an enclosing `.timeout()` expires (forward it into cancellation-aware
 * IO), and `setHeader` records receipt headers for the continuing exchange.
 * Declaring only the first parameter remains valid.
 *
 * @template T - Current body type
 */
type CallableDestination<T = unknown> = (exchange: Exchange<T>, ctx?: SendContext) => Promise<void> | void;
/**
 * Destination adapter: pushes the exchange OUT to an external system (HTTP
 * call, queue, file write, SMTP send). Used with `.to()` and `.tap()`.
 *
 * `send` is strictly void: the body flows through a `.to()` step unchanged.
 * A send that produces a receipt surfaces it via `ctx.setHeader` (see
 * {@link SendContext}); an adapter whose purpose is to PRODUCE data
 * implements {@link Enricher} instead (or additionally).
 *
 * @template T - Current body type
 */
interface Destination<T = unknown> extends Adapter {
    send: CallableDestination<T>;
}
/**
 * Anything `.to()` accepts: a Destination (send wins when both slots exist),
 * an Enricher (fetch-only pull-in; the result replaces the body), or a
 * function form routed by its inferred return type.
 *
 * @template T - Current body type
 * @template R - Fetch result type for the enricher / function forms
 */
type ToTarget<T = unknown, R = unknown> = Destination<T> | Enricher<T, R> | CallableDestination<T> | CallableEnricher<T, R>;

/**
 * Store key for the map of split group IDs to their parent exchanges.
 * Used by the aggregate step to restore the parent exchange identity
 * after merging children.
 */
declare const SPLIT_PARENT_STORE: "routecraft.split.parents";
declare module "@routecraft/routecraft" {
    interface StoreRegistry {
        [SPLIT_PARENT_STORE]: Map<string, Exchange>;
    }
}
/**
 * Per-child envelope produced by {@link splitChild}: a body plus optional
 * header OVERRIDES for that child. The brand makes the envelope
 * unambiguous -- a split item that happens to have a `body` property is
 * still treated as a plain body unless it went through `splitChild`.
 *
 * @template R - Body type of the child
 */
interface SplitChild<R = unknown> {
    readonly body: R;
    readonly headers?: ExchangeHeaders;
}
/**
 * Wrap one split child with per-child header overrides. Plain return values
 * from a splitter become child bodies that inherit the parent's headers;
 * use this helper only when a child needs its own header values on top.
 *
 * @example
 * ```ts
 * .split((exchange) =>
 *   exchange.body.lines.map((line, i) => splitChild(line, { "x-line": i })),
 * )
 * ```
 */
declare function splitChild<R>(body: R, headers?: ExchangeHeaders): SplitChild<R>;
/** Type guard for {@link SplitChild} envelopes. */
declare function isSplitChild(value: unknown): value is SplitChild;
/**
 * What a splitter produces per child: the child's body, or a
 * {@link splitChild} envelope when the child needs header overrides. The
 * FRAMEWORK constructs the child exchanges (fresh id, parent headers
 * inherited, `routecraft.split_hierarchy` maintained); splitters never
 * build `Exchange` instances themselves.
 *
 * @template R - Body type of the child
 */
type SplitResult<R = unknown> = R | SplitChild<R>;
/**
 * Function form of a splitter: takes the current exchange and returns the
 * child bodies (or {@link splitChild} envelopes). Use with
 * `.split(splitter)` or no-arg `.split()` for arrays.
 *
 * @template T - Current body type
 * @template R - Body type of each child
 */
type CallableSplitter<T = unknown, R = unknown> = (exchange: Exchange<T>) => Promise<Array<SplitResult<R>>> | Array<SplitResult<R>>;
/**
 * Splitter adapter: turns one body into many; each item is processed as a separate exchange.
 * Used with `.split()`. Default (no adapter): array bodies are split into elements; non-arrays become one item.
 *
 * @template T - Current body type
 * @template R - Item type
 */
interface Splitter<T = unknown, R = unknown> extends Adapter {
    split: CallableSplitter<T, R>;
}

/**
 * What an aggregator returns: the combined body plus optional headers for
 * the resulting exchange. When `headers` is omitted the engine keeps the
 * base exchange's headers. The engine always rewraps the result onto the
 * parent exchange's identity, so aggregators no longer fabricate a fake
 * `Exchange`; returning a full exchange still works structurally.
 *
 * @template R - Result body type
 */
type AggregateResult<R = unknown> = {
    body: R;
    headers?: ExchangeHeaders;
};
/**
 * Function form of an aggregator: takes an array of exchanges and returns the combined result.
 * Use with `.aggregate(aggregator)`. Default aggregator collects bodies into an array.
 *
 * @template T - Body type of incoming exchanges
 * @template R - Result body type (default T)
 */
type CallableAggregator<T = unknown, R = T> = (exchanges: Exchange<T>[]) => Promise<AggregateResult<R>> | AggregateResult<R>;
/**
 * Aggregator adapter: combines multiple exchanges (e.g. after a split) into one.
 * Used with `.aggregate()`. Default: collect bodies into an array (with one-level flattening).
 *
 * @template T - Body type of incoming exchanges
 * @template R - Result body type
 */
interface Aggregator<T = unknown, R = unknown> extends Adapter {
    aggregate: CallableAggregator<T, R>;
}

/**
 * Function form of a transformer: maps the body to a new value. Headers are unchanged.
 * Use with `.transform(transformer)`. Prefer over `.process()` when only the body changes.
 * The current exchange is passed as a second, read-only argument so a
 * transformer can derive the new body from context (the principal, headers,
 * correlation id) without dropping to `.process()`. A transformer still
 * returns only the body; to rewrite headers or the principal use `.process()`.
 * The third argument carries the step's {@link StepSignalContext}: when an
 * enclosing `.timeout()` expires, `ctx.signal` aborts, so a transformer doing
 * cancellation-aware IO can forward it (`fetch(url, { signal })`).
 * Adding parameters is backwards compatible: a one-argument
 * `(message) => ...` is still a valid transformer.
 * @template T - Current body type
 * @template R - Result body type (default T)
 */
type CallableTransformer<T = unknown, R = T, Ex extends Exchange<T> = Exchange<T>> = (message: T, exchange: Ex, ctx?: StepSignalContext) => Promise<R> | R;
/**
 * Result of the field-shaping helpers (`keep`, `mask`). Generic over the
 * actual body so it preserves the precise type whether applied to a single
 * record or, element-wise, to an array of records. `T` is the record
 * (element) type in both cases, so grant predicates and mask functions always
 * see one record. Assignable to {@link CallableTransformer}, so it drops
 * straight into `.transform(...)`.
 */
type FieldTransform<T> = <B extends T | T[]>(body: B, exchange?: Exchange<B>) => B;
/**
 * Transformer adapter: body-only conversion. Used with `.transform()`.
 * Headers and exchange metadata are preserved. Use `.process()` to change headers or the full exchange.
 * @template T - Current body type
 * @template R - Result body type
 */
interface Transformer<T = unknown, R = T> extends Adapter {
    transform: CallableTransformer<T, R>;
}
/**
 * Creates a transformer from declarative field mappings. Each key in the
 * mapping corresponds to a field in the output type, with a function that
 * extracts the value from the source body.
 * Use with `.transform(mapper({...}))` or the `.map()` sugar method.
 * @template T - Source body type
 * @template R - Result body type
 * @param fieldMappings - Object mapping output field names to extractor functions
 * @returns A callable transformer that maps each field via the provided functions
 * @example
 * ```ts
 * craft()
 *   .from(source)
 *   .transform(mapper<ApiUser, DbUser>({
 *     id: (user) => user.userId,
 *     name: (user) => user.fullName,
 *   }))
 *   .to(dest)
 * ```
 */
declare function mapper<T, R>(fieldMappings: {
    [K in keyof R]: (src: T) => R[K];
}): CallableTransformer<T, R>;

/**
 * Obfuscates a single field value. Receives the current value and the whole
 * record it belongs to (typed `R`), and returns the value to show in its
 * place. Pure with respect to identity: `mask` never looks at the principal.
 * `value` stays `unknown` because the value at an arbitrary dot path is not
 * statically known.
 */
type MaskFn<R = unknown> = (value: unknown, record: R) => unknown;
/**
 * Map of dot-path -> obfuscation function. Only the listed fields are
 * rewritten; every other field is left as-is.
 */
type MaskRules<R = unknown> = Record<string, MaskFn<R>>;
/**
 * Transform helper that obfuscates field values, regardless of who is asking.
 * Use it for values that should never be shown verbatim at a boundary even to
 * an authorised caller, for example masking an e-mail on a public HTTP
 * response. To remove fields a caller is not allowed to see at all, compose
 * `keep` before `mask`.
 * Returns a {@link FieldTransform}, so drop it straight into
 * `.transform(mask({ ... }))`. Applies to the body when it is a single
 * record, and element-wise when the body is an array of records. For a
 * wrapped collection, mask the inner array:
 * `.transform((b, ex) => ({ ...b, items: mask(rules)(b.items, ex) }))`.
 * @example
 * ```ts
 * craft()
 *   .from(source)
 *   .transform(mask({
 *     email: (v) => maskEmail(String(v)),
 *     "card.number": (v) => "**** " + String(v).slice(-4),
 *   }))
 *   .to(dest)
 * ```
 */
declare function mask<T>(rules: MaskRules<T>): FieldTransform<T>;

/**
 * A grant the caller must hold to keep a field. Either a role name matched
 * against `principal.roles`, or a predicate evaluated against the record and
 * the caller's principal. `self` and relationships like "manages" are written
 * as predicates; there is no magic string, `admin` is just a role name.
 */
type Grant<T = unknown> = string | ((record: T, principal: Principal | undefined) => boolean);
/**
 * Rule for one field: `true` keeps it for everyone who reaches this step, or a
 * list of grants any one of which keeps it.
 */
type KeepRule<T = unknown> = true | Grant<T>[];
/**
 * Map of dot-path -> {@link KeepRule}.
 */
type KeepRules<T = unknown> = Record<string, KeepRule<T>>;
/**
 * Options for {@link keep}.
 */
interface KeepOptions {
    /**
     * `true` (default): strict allowlist. Only fields listed in the rules
     * survive, each kept when its grant holds; anything not listed is dropped.
     * Safe by default, a new sensitive field stays hidden until you list it.
     *
     * `false`: gate only the listed fields. A listed field is dropped when its
     * grant fails; every unlisted field passes through untouched.
     */
    strict?: boolean;
}
/**
 * Transform helper that keeps fields based on the caller's grants, removing
 * the rest. This is the access-control half of field shaping: a field the
 * caller has no grant for is dropped entirely (compose `mask` after `keep` to
 * obfuscate what remains). Reads the caller from the exchange the transform
 * step now provides. It fails closed: only an authentic principal (one
 * established by a source verifier or `authenticate()`) is trusted; a
 * self-asserted principal header is treated as missing, so role and predicate
 * grants do not pass, matching `authorize()`.
 * Strict by default: only listed fields survive (use `true` to keep a field
 * for any caller). Pass `{ strict: false }` to instead gate only the listed
 * fields and pass everything else through.
 * Returns a {@link FieldTransform}, so use `.transform(keep({ ... }))`. `T` is
 * the record (element) type: applies to the body when it is a single record,
 * element-wise when it is an array of records, preserving the precise type
 * either way. For a wrapped collection, keep the inner array:
 * `.transform((b, ex) => ({ ...b, items: keep(rules)(b.items, ex) }))`.
 * @example
 * ```ts
 * const self = (e: Employee, p) => e.email === p?.email;
 * craft()
 *   .from(source)
 *   .transform(keep({
 *     id: true,
 *     email: true,
 *     yearlyWage: [self, "hr"],   // own salary, or the hr role
 *     internalNotes: ["hr"],      // hr only, dropped for everyone else
 *   }))
 *   .to(dest)
 * ```
 */
declare function keep<T>(rules: KeepRules<T>, options?: KeepOptions): FieldTransform<T>;

/**
 * Returned by a filter predicate to drop an exchange with a reason.
 * The reason is recorded in telemetry and shown in the TUI.
 */
interface FilterDropResult {
    reason: string;
}
/**
 * Predicate over the full exchange. Return `true` to keep the exchange,
 * `false` to drop it, or `{ reason: "..." }` to drop with an explanation.
 *
 * @template T - Body type of the exchange
 *
 * @example
 * ```ts
 * .filter((ex) => {
 *   if (!ex.body.name) return { reason: "name is required" };
 *   if (ex.body.age < 18) return { reason: "age must be 18 or older" };
 *   return true;
 * })
 * ```
 */
type CallableFilter<T = unknown, Ex extends Exchange<T> = Exchange<T>> = (exchange: Ex) => Promise<boolean | FilterDropResult> | boolean | FilterDropResult;
/**
 * Filter adapter: keeps or drops the exchange based on a predicate. Used with `.filter()`.
 *
 * @template T - Body type
 */
interface Filter<T = unknown> extends Adapter {
    filter: CallableFilter<T>;
}

/**
 * Options for the `.sample()` flow-control operation. Exactly one of
 * `every` (count-based) or `interval` (time-based) must be set; the union
 * makes them mutually exclusive at compile time (passing both, or neither,
 * is a type error), and {@link resolveSampleOptions} re-checks at runtime
 * for JS callers.
 */
type SampleOptions = {
    /**
     * Count-based: pass every Nth exchange and drop the rest, so
     * `{ every: 5 }` passes the 5th, 10th, 15th, ... exchange. Must be a
     * finite integer >= 1.
     */
    every: number;
    interval?: never;
} | {
    /**
     * Time-based: pass the first exchange seen in each `interval` window
     * and drop the rest until the window elapses. Must be at least 1ms.
     */
    interval: Duration;
    every?: never;
};
/**
 * {@link SampleOptions} with the sampling mode resolved and validated. A
 * discriminated union, so narrowing on `mode` proves which numeric field is
 * present (no non-null assertions at the use site).
 *
 * @internal
 */
type ResolvedSampleOptions = {
    mode: "count";
    every: number;
} | {
    mode: "interval";
    intervalMs: number;
};
/** Marker adapter for the sample step; carries no configuration. */
interface SampleAdapter extends Adapter {
    readonly adapterId: "routecraft.operation.sample";
}
/**
 * Step that samples exchanges by count (`every`) or time window
 * (`interval`), passing the admitted ones and dropping the rest. A drop
 * is silent (no error), exactly like a `filter` predicate returning false:
 * it emits `route:operation:sample:dropped` and `route:exchange:dropped`
 * (reason `"sampled"`) so telemetry and the TUI can count it.
 *
 * Sampler state is per-route (see {@link SampleController}), so every
 * exchange on a given Route shares one counter / window while distinct
 * Routes stay isolated.
 */
declare class SampleStep implements Step<SampleAdapter> {
    #private;
    operation: OperationType;
    label?: string;
    adapter: SampleAdapter;
    skipStepEvents: boolean;
    constructor(options: SampleOptions);
    execute(exchange: Exchange): Promise<StepOutcome>;
}

/**
 * Options for the `.dedupe()` flow-control operation.
 */
interface DedupeOptions {
    /**
     * Derive the deduplication key from the exchange. The returned string is
     * the identity two exchanges are compared on.
     *
     * When omitted, the key is a SHA-256 over the principal's `issuer` and
     * `subject` plus those of every `actor` hop when the exchange carries
     * one, and a SHA-256 of `JSON.stringify(body)` (see
     * {@link hashExchangeBody}). Two callers with different identities
     * sending the same body are therefore not duplicates of each other, and
     * neither are two delegates acting for the same subject. Identity means
     * issuer and subject per hop: exchanges with no principal all share one
     * identity, and principals differing only in `clientId` or `grantId`
     * count as the same caller. The route is not part of the
     * key: each `.dedupe()` already keeps its own seen-key set per route.
     * The default needs a body: an `undefined` body (a bodiless `http()`
     * GET) or one `JSON.stringify` cannot represent fails with `RC5033`.
     *
     * A custom `key` is used VERBATIM: nothing is added to it, so every
     * caller returning the same key dedupes against every other. When
     * callers must not dedupe each other, put the caller's identity
     * (`ex.principal?.issuer` and `subject`, plus `ex.principal?.actor` on a
     * route that admits delegation) in the key. Supply `key` as well when
     * the body is not JSON-serialisable or when a stable identity lives in a
     * header (a file path, an event id) that should survive body changes.
     */
    key?: (exchange: Exchange) => string;
    /**
     * Time to live in milliseconds for a committed key. The TTL is a sliding
     * (inactivity) window, not a fixed lifetime from commit: each duplicate hit
     * refreshes it, so an actively-arriving duplicate stream keeps being
     * suppressed and a key only expires once it has been quiet for `ttl`. After
     * expiry the next exchange with that key is treated as new (passes again).
     * When omitted, committed keys are retained until LRU eviction at `maxKeys`.
     *
     * This is the memory bound for long-running routes: without a `ttl`, only
     * `maxKeys` caps the committed set, and an evicted key's next occurrence
     * is no longer recognised as a duplicate.
     */
    ttl?: Duration;
    /**
     * Maximum number of committed keys retained per route. The committed set
     * is an LRU keyed by recency of use (a duplicate hit counts as a use, not
     * just the original commit), so memory stays bounded even with an unbounded
     * key space: the least-recently-seen key is evicted, and its next
     * occurrence passes as new. Default `10_000`.
     */
    maxKeys?: number;
}
/**
 * {@link DedupeOptions} with every field resolved and validated.
 *
 * @internal
 */
interface ResolvedDedupeOptions {
    key: (exchange: Exchange) => string;
    ttl: number | undefined;
    maxKeys: number;
}
/** Marker adapter for the dedupe step; carries no configuration. */
interface DedupeAdapter extends Adapter {
    readonly adapterId: "routecraft.operation.dedupe";
}
/**
 * Step that suppresses duplicate exchanges by a derived key. The first time
 * a key is seen it is reserved and the exchange continues; a subsequent
 * exchange whose key is still reserved (in flight) or already committed
 * (handled) is dropped silently, exactly like a `filter` returning false.
 *
 * Reservation semantics give single-flight behaviour and correct retries:
 * the key is committed only when the exchange completes the route cleanly
 * (`route:exchange:completed`) and released when it fails or is dropped
 * (`route:exchange:failed` / `:dropped`), so an input that was not actually
 * handled is not permanently suppressed. State is in-memory and per-route
 * (see {@link DedupeController}); a cross-instance provider is a future
 * addition.
 *
 * Emits `route:operation:dedupe:pass` when a key is reserved and
 * `route:operation:dedupe:duplicate` (plus `route:exchange:dropped`, reason
 * `"duplicate"`) when one is suppressed.
 *
 * Known limitation: the commit/release decision is keyed on the entering
 * exchange's terminal event, so placing `.dedupe()` before a `split` (or
 * other fan-out) whose children fail still commits the parent's key (the
 * parent completes even when children fail), suppressing a retriable
 * re-send. Place `.dedupe()` after a fan-out until lineage-aware settlement
 * lands (tracked as a follow-up).
 */
declare class DedupeStep implements Step<DedupeAdapter> {
    #private;
    operation: OperationType;
    label?: string;
    adapter: DedupeAdapter;
    skipStepEvents: boolean;
    constructor(options?: DedupeOptions);
    execute(exchange: Exchange): Promise<StepOutcome>;
}

/**
 * Options for the `.debounce()` flow-control operation.
 */
interface DebounceOptions<In = unknown> {
    /**
     * Quiet window. An exchange is released only after `wait` has elapsed with
     * no newer arrival in its group; each new arrival resets the window and
     * supersedes (drops) the one being held. Must be at least 1ms.
     */
    wait: Duration;
    /**
     * Partition selector: exchanges sharing a key are debounced independently
     * (for example one quiet window per file path). When omitted, the whole
     * route shares a single window.
     */
    key?: (exchange: Exchange<In>) => string;
    /**
     * Upper bound on how long an exchange may be held from the START of its
     * burst, guaranteeing eventual release under continuous activity
     * (otherwise a steady stream of arrivals could reset `wait` forever and
     * starve the trailing edge). Measured from the first arrival in the burst
     * and NOT reset by later arrivals. Must be `>= wait` when set.
     */
    maxWait?: Duration;
}
/** Marker adapter for the debounce step; carries no configuration. */
interface DebounceAdapter extends Adapter {
    readonly adapterId: "routecraft.operation.debounce";
}
/**
 * Step that suppresses bursts of exchanges, releasing only the LAST one in a
 * burst after a quiet period. The archetypal use is collapsing a flurry of
 * file-change or search-as-you-type events down to their final state.
 *
 * Each arrival is held (not passed downstream) and resets a `waitMs` quiet
 * timer; a newer arrival in the same group supersedes and drops the one being
 * held. When the timer finally fires (or the optional `maxWait` cap elapses
 * from the burst's start, guaranteeing progress under continuous activity),
 * the held exchange is released through the steps that follow `.debounce()`.
 * An optional `key` selector debounces independently per group.
 *
 * This is the only operation that breaks the "process each exchange
 * immediately" model: it holds an exchange OUTSIDE the pipeline queue and
 * re-runs it later via the executor's captured downstream continuation, so a
 * released exchange runs the post-debounce steps as a fresh exchange (new id,
 * preserved correlation id) with its own `route:exchange:started` / `:completed`
 * lifecycle. Because the hold lives outside the queue, a pending exchange is
 * flushed on `drain()` / shutdown rather than being lost.
 *
 * Emits `route:operation:debounce:held` (arrival held / timer reset),
 * `route:operation:debounce:dropped` (a held exchange superseded), and
 * `route:operation:debounce:released` (the trailing exchange released).
 */
declare class DebounceStep<In = unknown> implements Step<DebounceAdapter> {
    #private;
    operation: OperationType;
    label?: string;
    adapter: DebounceAdapter;
    skipStepEvents: boolean;
    constructor(options: DebounceOptions<In>);
    execute(exchange: Exchange<In>, ctx: StepContext): Promise<StepOutcome>;
}

/**
 * Derive a stable SHA-256 hex digest from an exchange body by hashing its
 * JSON serialisation. The default `.dedupe()` key hashes it together with
 * the principal, and the default `.cache()` key with the route and
 * principal, so the two operations agree on what "the same body" means.
 *
 * Works for JSON-shaped bodies: primitives, arrays, and plain objects with
 * string keys. It does NOT canonicalise object key order, so two objects
 * with the same entries in a different order hash differently; supply an
 * explicit `key` when a stable identity must survive key reordering.
 *
 * Throws a plain `Error` when the body is not JSON-serialisable: a
 * top-level `undefined`, function, or symbol (which `JSON.stringify`
 * renders as `undefined`), or a `BigInt` / circular reference (which it
 * throws on). Callers translate the throw into their operation-specific
 * `RoutecraftError` with an actionable message, so the failure points the
 * user at the right `key` option.
 *
 * Performance: this serialises and hashes the body on every call. For hot
 * paths or large bodies, supply a `key` that returns a stable identifier
 * already to hand (an id field, a content hash in a header) to avoid the
 * re-serialise and re-hash.
 *
 * @internal
 */
declare function hashExchangeBody(body: unknown): string;

/**
 * Function form of a tap. One signature covers both role shapes (a
 * {@link CallableDestination} written for `.to()` and a
 * {@link CallableEnricher}) so either drops into `.tap()` unchanged and the
 * exchange parameter stays contextually typed: the `ctx` is a
 * {@link SendContext} (its `setHeader` sink discards receipts with the
 * snapshot), and any returned value is discarded.
 *
 * @template T - Current body type
 */
type TapCallable<T = unknown, Ex extends Exchange<T> = Exchange<T>> = (exchange: Ex, ctx?: SendContext) => unknown;
/**
 * Anything `.tap()` accepts: a Destination (send), an Enricher (fetch and
 * discard), or a function form. Results are always discarded; a tap
 * observes.
 *
 * @template T - Current body type
 */
type TapTarget<T = unknown, Ex extends Exchange<T> = Exchange<T>> = Destination<T> | Enricher<T, unknown> | TapCallable<T, Ex>;

/**
 * Resolve identity claims for the current exchange. Return claims to mint and
 * attach an authenticated principal, or `undefined` to leave the exchange as
 * it is (the caller stays anonymous, or keeps an already-attached identity).
 *
 * @template T - Body type of the exchange
 */
type CallableAuthenticator<T = unknown> = (exchange: Exchange<T>) => PrincipalClaims | undefined | Promise<PrincipalClaims | undefined>;

/**
 * Delegation directive returned by a {@link CallableDelegator}: the actor
 * identity plus the consent-derived scope ceiling.
 */
interface DelegationClaims extends DelegateOptions {
    /** Identity claims of the party that will act on the subject's behalf. */
    actor: PrincipalClaims;
}
/**
 * Resolve the delegation for the current exchange. Return a directive to
 * mark an actor as acting on the current principal's behalf, or `undefined`
 * when no consent exists. What `undefined` does to the exchange is governed
 * by {@link DelegateStepOptions.otherwise}: by default the subject's direct
 * principal is stripped (the continuation runs anonymous), so an actor
 * downstream never wields an identity nobody consented to hand it.
 *
 * @template T - Body type of the exchange
 */
type CallableDelegator<T = unknown> = (exchange: Exchange<T>) => DelegationClaims | undefined | Promise<DelegationClaims | undefined>;
/**
 * Options for the `.delegate()` operation.
 */
interface DelegateStepOptions {
    /**
     * What happens to the exchange when the resolver returns `undefined`
     * (no consent record):
     *
     * - `"drop"` (default): strip the subject's direct principal so the
     *   exchange continues anonymous. This is the right mode when the
     *   continuation acts THROUGH someone else (an agent, a service): without
     *   consent, the actor must not inherit the caller's full direct
     *   authority, which is exactly what passing the principal through would
     *   grant. Downstream `authorize()` then refuses with RC5012 instead of
     *   silently acting with undelegated power. The strip is precise: it
     *   only removes a principal that is present, not already delegated (no
     *   `actor`), and not an autonomous agent subject
     *   (`subjectProfile: "ai_agent"`). Anonymous exchanges, delegated
     *   principals, and agent subjects pass through untouched.
     *
     * - `"keep"`: leave the exchange untouched, preserving the caller's
     *   direct principal. This is the right mode when the continuation
     *   serves the caller DIRECTLY (the delegation was an optional
     *   enhancement, not the authority boundary), so an ungranted caller
     *   should keep acting as themselves.
     */
    otherwise?: "drop" | "keep";
}

/**
 * Programmatic client for dispatching messages into running routes.
 *
 * Use this to call routes from external code (CLI frameworks, HTTP servers,
 * application logic) without coupling to the CraftContext internals.
 *
 * Returned alongside the context from `ContextBuilder.build()`.
 *
 * @example
 * ```typescript
 * const { context, client } = await new ContextBuilder()
 *   .routes(capabilities)
 *   .build();
 *
 * await context.start();
 *
 * // Dispatch from Commander action
 * program.command('greet').action(async (name) => {
 *   const result = await client.sendDirect('greet', { name });
 *   console.log(result);
 * });
 * ```
 */
declare class CraftClient {
    private readonly ctx;
    constructor(ctx: CraftContext);
    /**
     * Send a message to a direct endpoint and return the result. The name
     * carries the transport: future transports (e.g. HTTP dispatch) get
     * their own verbs instead of overloading one `send`.
     *
     * The context must be started and the target route must be subscribed
     * before calling sendDirect.
     *
     * @param endpoint - Direct endpoint name (must match the endpoint string passed to `direct(endpoint, options)`)
     * @param body - Request body
     * @param headers - Optional exchange headers
     * @returns The response body from the route. `R` defaults to `unknown`:
     *   the route's output type is not derivable from the request type, so
     *   callers narrow explicitly.
     * @throws {RoutecraftError} RC5004 if no direct channel exists for the endpoint
     */
    sendDirect<T = unknown, R = unknown>(endpoint: string, body: T, headers?: ExchangeHeaders): Promise<R>;
}

/**
 * Name of a dispatch selection strategy. Surfaced on the
 * `route:operation:dispatch:selected` event so observers can attribute a
 * pick to the strategy that made it. The event payloads in `types.ts`
 * inline this union (types.ts is the dependency root and never imports
 * from operations); keep the two in sync when adding a strategy.
 */
type DispatchStrategyName = "failover" | "round-robin" | "weighted" | "sticky";
/**
 * Strategy argument accepted as the required leading parameter of
 * `.dispatch(strategy, ...targets)`. There is no safe default strategy
 * (each makes a materially different routing decision), so it is required.
 *
 * - String form for the strategies that carry no extra configuration:
 *   `"failover"`, `"round-robin"`, `"weighted"`.
 * - Object form when the strategy needs config. `sticky` REQUIRES a `key`
 *   selector (it has nothing to partition on otherwise) and so has no string
 *   form, and accepts an optional `maxKeys` bound on the affinity map.
 *
 * The config-less object arm (`{ strategy: "failover" | ... }`) is kept
 * deliberately for forward-compat symmetry: a strategy can gain options
 * later without a shape change at call sites, and the issue-spec examples
 * use it (`.dispatch({ strategy: "weighted" }, ...)`). Prefer the string
 * form when there is no config.
 *
 * @template In - Body type of the exchange at the point of the dispatch
 */
type DispatchStrategy<In = unknown> = "failover" | "round-robin" | "weighted" | {
    strategy: "failover" | "round-robin" | "weighted";
} | {
    strategy: "sticky";
    /** Partition selector: exchanges sharing a key stick to one target. */
    key: (exchange: Exchange<In>) => string;
    /**
     * Maximum number of distinct keys retained in the affinity map (an
     * LRU). When the cap is reached the least-recently-seen key is evicted
     * and its next occurrence is reassigned (possibly to a different
     * target). Default {@link DEFAULT_MAX_KEYS}.
     */
    maxKeys?: number;
};
/**
 * Brand marking a {@link WeightedTarget}. A symbol (not a string field) so a
 * user destination or body can never collide with it, and so the wrapper is
 * invisible to ordinary property enumeration.
 */
declare const WEIGHTED: unique symbol;
/**
 * A dispatch target with its relative weight co-located. Produced by
 * {@link weighted}; consumed only by the `weighted` strategy (other
 * strategies ignore the weight). Keeping the weight next to its target makes
 * the target list reorder-safe and mixable with un-weighted targets, which
 * default to weight 1.
 *
 * @template In  - Body type entering the target
 * @template Out - Body type the target produces (discarded; dispatch is
 *   side-effect-only)
 */
interface WeightedTarget<In = unknown, Out = unknown> {
    readonly [WEIGHTED]: true;
    readonly weight: number;
    readonly path: Path<In, Out>;
}
/**
 * A single dispatch target: a bare destination, a sub-pipeline callback (the
 * shared {@link Path} surface), or either of those wrapped in a relative
 * {@link weighted} weight.
 *
 * @template In  - Body type entering the target
 * @template Out - Body type the target produces (discarded)
 */
type DispatchTarget<In = unknown, Out = unknown> = Path<In, Out> | WeightedTarget<In, Out>;
/**
 * Co-locate a relative weight with a dispatch target for the `weighted`
 * strategy. Weights are relative, not percentages, so `weighted(a, 3)` and
 * `weighted(b, 1)` send roughly three exchanges to `a` for each one to `b`.
 * Mixable with un-weighted targets, which take a default weight of 1.
 *
 * Rejected at build time (RC5003) if the weight is not a finite number > 0,
 * so a mis-typed weight fails when the route is built rather than silently
 * starving a target.
 *
 * @param path - The destination or sub-pipeline callback to weight
 * @param weight - Relative weight; must be a finite number > 0
 * @returns A weighted target consumed by `.dispatch("weighted", ...)`
 */
declare function weighted<In = unknown, Out = unknown>(path: Path<In, Out>, weight: number): WeightedTarget<In, Out>;
/** Marker adapter for the dispatch step; the targets live on the step itself. */
interface DispatchAdapter extends Adapter {
    readonly adapterId: "routecraft.operation.dispatch";
}
/**
 * Step that runs EXACTLY ONE of its targets, chosen by strategy, and lets the
 * original exchange continue downstream unchanged. The sibling of `multicast`
 * (all targets) and `choice` (one target by predicate); dispatch is one target
 * by load-balancing strategy.
 *
 * Side-effect-only: the selected target runs on its own deep clone (fresh id,
 * preserved correlation id), exactly like a multicast path, so a target that
 * reshapes the body does not change what continues downstream. There is no
 * branch-convergence requirement, so a target's output type is unconstrained.
 *
 * Strategies:
 * - `failover`: try targets in order from the current preferred cursor until
 *   one settles without failing (a target that deliberately drops the exchange
 *   counts as handled). On a failure, advance to the next target and retry; the
 *   cursor persists so a healthy target keeps serving and a dead one is not
 *   re-probed every exchange. If every target fails, emit
 *   `route:operation:dispatch:exhausted` and let the original continue. Pairs
 *   naturally with per-target `.retry()` / `.circuitBreaker()`.
 * - `round-robin`: hand out targets in order, cycling.
 * - `weighted`: smooth weighted round-robin over the `weighted()` weights, so
 *   the distribution matches the weights and is deterministic (testable)
 *   rather than random.
 * - `sticky`: exchanges sharing a `key` go to the same target; new keys are
 *   round-robined across targets and remembered in an LRU-bounded map.
 *
 * A failing target fires its own clone's error events (`route:error` /
 * `route:exchange:failed`) but never fails the route or the dispatch step
 * itself, matching multicast's isolation contract.
 */
declare class DispatchStep<In = unknown> implements Step<DispatchAdapter> {
    #private;
    operation: OperationType;
    adapter: DispatchAdapter;
    constructor(strategy: DispatchStrategy<In>, targets: readonly DispatchTarget<In, unknown>[]);
    /**
     * Expose the compiled targets to framework-level walks of the route's
     * step tree. `rejoins: false`: a target runs as an isolated nested
     * pipeline whose result the main flow does not carry, so the
     * defer-site resolver refuses a `.defer()` inside one.
     *
     * @internal
     */
    [NESTED_STEPS](): ReadonlyArray<NestedSteps>;
    execute(exchange: Exchange<In>, ctx: StepContext): Promise<StepOutcome>;
}

/**
 * Builder for creating a Routecraft context with routes and configuration.
 *
 * This builder provides a fluent API for configuring and creating a CraftContext
 * with routes, startup/shutdown handlers, and initial store values.
 *
 * @example
 * ```typescript
 * // Create a context with routes and handlers
 * const { context, client } = await new ContextBuilder()
 *   .with({ store: new Map() })
 *   .on('context:starting', ({ ts }) => console.log('Starting at', ts))
 *   .store('routecraft.adapter.channel.store', new Map())
 *   .routes(routes1)
 *   .routes([routes2, routes3])
 *   .build();
 *
 * // Start the context to begin processing
 * await context.start();
 *
 * // Dispatch messages programmatically
 * await client.sendDirect('my-endpoint', { data: 'hello' });
 * ```
 *
 * Plugins run before routes are registered, allowing them to:
 * - Set up stores and state
 * - Dynamically register additional routes
 * - Subscribe to lifecycle events
 * - Perform other initialization
 */
declare class ContextBuilder {
    protected config?: CraftConfig;
    protected definitions: RouteDefinition[];
    protected initialStores: Map<keyof StoreRegistry, unknown>;
    protected eventHandlers: Map<keyof EventDetailsMap, Set<EventHandler<keyof EventDetailsMap>>>;
    protected onceHandlers: Map<keyof EventDetailsMap, Set<EventHandler<keyof EventDetailsMap>>>;
    protected plugins: Array<CraftPlugin>;
    constructor();
    /**
     * Configure the context with the provided config object.
     *
     * Merge semantics across multiple `with()` calls are not symmetric:
     *
     * - `plugins` accumulates: every `with()` call appends its `plugins[]`
     *   to a builder-side list. Builder stores and event handlers also
     *   accumulate.
     * - Every other key (`store`'s value map aside, plus `cron`, `direct`,
     *   `http`, `mail`, `telemetry`, and any ecosystem-augmented keys such
     *   as `llm`, `mcp`) is last-writer-wins: a second `with()` replaces
     *   the previously stored config object, and only the most recent
     *   non-`plugins` keys reach the constructor.
     *
     * If you need to combine non-`plugins` keys across sources, merge them
     * into a single object before calling `with()` (or call `with()` once).
     *
     * @param config The configuration object for the context
     * @returns This builder instance for method chaining
     */
    with(config: CraftConfig): this;
    /**
     * Register an event listener to be attached to the built context.
     */
    on<K extends EventName>(event: K, handler: EventHandler<K>): this;
    /**
     * Register a one-time event listener to be attached to the built context.
     * The handler fires once and then auto-unsubscribes.
     */
    once<K extends EventName>(event: K, handler: EventHandler<K>): this;
    /**
     * Add an initial value to the context store.
     *
     * @template K The store key type
     * @param key The store key
     * @param value The initial value for the store
     * @returns This builder instance for method chaining
     *
     * @example
     * ```typescript
     * // Add an initial channel store
     * builder.store('routecraft.adapter.channel.store', new Map());
     * ```
     */
    store<K extends keyof StoreRegistry>(key: K, value: StoreRegistry[K]): this;
    /**
     * Add routes to the context.
     *
     * Routes can be added as individual RouteDefinitions, RouteBuilders, or arrays of either.
     * RouteBuilder-like objects (duck-typed by having a .build() that returns RouteDefinition[])
     * are supported so that builders from another copy of the package (e.g. CLI vs user module)
     * are still recognized.
     *
     * @param routes Individual or array of route definitions/builders to add
     * @returns This builder instance for method chaining
     *
     * @example
     * ```typescript
     * // Add a single route
     * builder.routes(myRoute);
     *
     * // Add multiple routes
     * builder.routes([route1, route2, route3]);
     *
     * // Add a route builder
     * builder.routes(
     *   craft()
     *     .from(simple("hello"))
     *     .to(log())
     * );
     * ```
     */
    routes(routes: RouteDefinition[] | AnyRouteBuilder[] | RouteDefinition | AnyRouteBuilder): this;
    /**
     * Build and return a configured CraftContext and CraftClient.
     *
     * This finalizes the configuration, runs plugins, and creates a ready-to-use
     * context with all the configured routes, handlers, and store values.
     * The client provides a programmatic API for dispatching messages into routes.
     *
     * @returns A promise resolving to `{ context, client }`
     *
     * @example
     * ```typescript
     * const { context, client } = await new ContextBuilder()
     *   .routes(capabilities)
     *   .build();
     *
     * await context.start();
     * await client.sendDirect('greet', { name: 'World' });
     * ```
     */
    build(): Promise<{
        context: CraftContext;
        client: CraftClient;
    }>;
}
/**
 * Any route builder, regardless of its tracked {@link BuilderState}.
 *
 * `RouteBuilder<S>` is invariant in its state bag (the body type appears in
 * both parameter and return positions), so a fully chained
 * `RouteBuilder<{ body: X }>` is not assignable to
 * `RouteBuilder<BuilderState>`. Positions that accept "some finished route
 * builder" (`ContextBuilder.routes`, the CLI loader, test harnesses) only
 * ever call `.build()`, which does not involve the bag at all, so this
 * minimal structural alias is the correct parameter type for them.
 */
type AnyRouteBuilder = Pick<RouteBuilder, "build">;
/**
 * Options for configuring a route.
 */
type RouteOptions = Partial<Pick<RouteDefinition, "consumer">> & {
    /**
     * Unique identifier for the route.
     */
    id: string;
};
/**
 * Route-scope staging methods shared by both pre-`.from()` surfaces
 * ({@link PreFromBuilder} and {@link PreFromTypedBuilder}). Methods return
 * `this` so the chain keeps whichever surface it is on: staging calls after
 * a typed `.input()` do not lose the staged body type.
 *
 * @template S - The {@link BuilderState} bag carried into the next route
 */
interface PreFromStaging<S extends BuilderState = BuilderState> {
    /** Set the route id for the next route. See {@link RouteBuilder.id}. */
    id(id: string): this;
    /** Set a human-readable title for the next route. See {@link RouteBuilder.title}. */
    title(value: string): this;
    /** Set a human-readable description for the next route. See {@link RouteBuilder.description}. */
    description(value: string): this;
    /** Gate the next route on a predicate. See {@link RouteBuilder.enabled}. */
    enabled(predicate: EnablementPredicate, options?: EnablementOptions): this;
    /**
     * Declare input schemas for the next route and retype the chain. When a
     * body schema is given (bare, or as `{ body }`), the schema's inferred
     * output type becomes the body type the following `.from(source)` opens
     * the pipeline with, so no duplicated `.from<T>()` generic is needed.
     * See {@link RouteBuilder.input}.
     */
    input<Schema extends StandardSchemaV1>(schemas: Schema | (RouteSchemas & {
        body: Schema;
    })): PreFromTypedBuilder<SetBody<S, StandardSchemaV1.InferOutput<Schema>>>;
    /** Declare input schemas (no body schema, so no retyping). See {@link RouteBuilder.input}. */
    input(schemas: RouteSchemas): this;
    /** Declare output schemas for the next route. See {@link RouteBuilder.output}. */
    output(schemas: RouteSchemas | StandardSchemaV1): this;
    /** Tag the next route. See {@link RouteBuilder.tag}. */
    tag(value: Tag | Tag[]): this;
    /** Configure batch processing for the next route. See {@link RouteBuilder.batch}. */
    batch(options?: {
        size?: number;
        flushInterval?: Duration;
    }): this;
    /**
     * Attach a ROUTE-SCOPE error handler (catch-all) to the next route. The
     * step-scope variant lives on the post-`.from()` builder; position picks
     * the mode. See {@link RouteBuilder.error}.
     */
    error(handler: ErrorHandler): this;
    /**
     * Configure ROUTE-SCOPE caching for the next route (whole-pipeline
     * memoisation); a failed exchange is never stored. After `.from()` only
     * the next step's output is cached, see {@link RouteBuilder.cache}.
     */
    cache(options?: CacheOptions<unknown>): this;
    /**
     * Configure a ROUTE-SCOPE retry for the next route (re-run the whole
     * pipeline on failure, chain position 7). The step-scope variant
     * lives on the post-`.from()` builder. See {@link RouteBuilder.retry}.
     */
    retry(options?: RetryOptions): this;
    /**
     * Configure a ROUTE-SCOPE timeout for the next route (per-attempt
     * deadline over the whole pipeline, chain position 8). The
     * step-scope variant lives on the post-`.from()` builder. See
     * {@link RouteBuilder.timeout}.
     */
    timeout(duration: Duration): this;
    /**
     * Configure a ROUTE-SCOPE throttle for the next route (rate-limit the
     * whole pipeline, chain position 5). The step-scope variant lives on
     * the post-`.from()` builder. See {@link RouteBuilder.throttle}.
     */
    throttle(options: ThrottleOptions): this;
    /**
     * Configure a ROUTE-SCOPE circuit breaker for the next route (protect
     * the whole pipeline, chain position 6). The step-scope variant lives
     * on the post-`.from()` builder. See {@link RouteBuilder.circuitBreaker}.
     */
    circuitBreaker(options: CircuitBreakerOptions): this;
    /**
     * Configure a ROUTE-SCOPE concurrency limiter (bulkhead) for the next
     * route (bound how many exchanges run the whole pipeline at once,
     * innermost resilience position). The step-scope variant lives on the
     * post-`.from()` builder. See {@link RouteBuilder.concurrency}.
     */
    concurrency(options: ConcurrencyOptions): this;
    /** Declare an authorization requirement on the next route. See {@link RouteBuilder.authorize}. */
    authorize(options?: AuthorizeOptions): this;
    /** Finalize and return the route definition(s). See {@link RouteBuilder.build}. */
    build: RouteBuilder<S>["build"];
}
/**
 * The route builder BEFORE `.from()`: only route-scope staging is reachable.
 *
 * `craft()` returns this type, and every staging method on the full
 * {@link RouteBuilder} (`.id()`, `.title()`, ...) flips the chain back into
 * it, so calling a pipeline operation (`.to()`, `.transform()`, `.split()`,
 * ...) before `.from()` is a COMPILE error rather than only the runtime
 * RC2001/RC2002 it has always been. The runtime guards remain for plain
 * JavaScript users; this interface is the type-level mirror of the same
 * contract.
 *
 * There is no separate runtime class: the value behind this type is the one
 * `RouteBuilder` instance, re-surfaced. `.from()` opens the route and hands
 * back the full pipeline surface. A `.input()` call with a body schema
 * flips the chain into {@link PreFromTypedBuilder} instead, which seeds
 * `.from()` with the schema's inferred body type.
 *
 * @template S - The {@link BuilderState} bag carried into the next route
 */
interface PreFromBuilder<S extends BuilderState = BuilderState> extends PreFromStaging<S> {
    /**
     * Open the route: define its source(s) and enter the pipeline surface.
     * Derived from the class via an indexed-access type so the (ordering
     * sensitive) overload set is defined exactly once, on
     * {@link RouteBuilder.from}; a future overload change cannot diverge
     * between the pre-`from` and post-`from` surfaces.
     */
    from: RouteBuilder<S>["from"];
}
/**
 * The pre-`.from()` surface after `.input()` declared a body schema: the
 * schema's inferred output type is staged in `S`, and `.from(source)` opens
 * the pipeline with that body type instead of inferring (typically
 * `unknown`) from the source adapter. The engine validates every inbound
 * body against the schema before the first step runs, which is what makes
 * seeding the static type from the schema sound.
 *
 * An explicit `.from<T>(source)` generic still overrides the staged type.
 *
 * @template S - The {@link BuilderState} bag, body already set from the schema
 */
interface PreFromTypedBuilder<S extends BuilderState = BuilderState> extends PreFromStaging<S> {
    /**
     * Open the route with the body type staged by `.input()`. Accepts one or
     * more sources; multi-ingress routes require the `.input()` body schema
     * anyway (RC2001), so every channel validates to this one type. The
     * spread forms of {@link RouteBuilder.from} apply here too.
     */
    from(...sources: SourceList): RouteBuilder<S>;
    /**
     * Open the route with an explicit body type, overriding the staged one.
     */
    from<T>(...sources: SourceList): RouteBuilder<SetBody<S, T>>;
}
declare class RouteBuilder<S extends BuilderState = BuilderState> extends StepBuilderBase<S> {
    protected currentRoute?: RouteDefinition;
    protected routes: RouteDefinition[];
    /**
     * Routes whose id was generated because no `.id()` was staged, mapped to
     * whether their route-scope `.cache()` uses the default key.
     */
    private readonly unnamedRoutes;
    protected pendingOptions?: {
        id?: string;
        consumer?: {
            type: ConsumerType<Consumer>;
            options?: unknown;
        };
        errorHandler?: ErrorHandler;
        cacheConfig?: ResolvedCacheOptions;
        retryConfig?: ResolvedRetryOptions;
        timeoutConfig?: ResolvedTimeoutOptions;
        throttleConfigs?: ResolvedThrottleOptions[];
        circuitBreakerConfig?: ResolvedCircuitBreakerOptions;
        concurrencyConfigs?: ResolvedConcurrencyOptions[];
        discovery?: RouteDiscovery;
        enablement?: RouteEnablement;
        authorizers?: AuthorizeOptions[];
    } | undefined;
    constructor();
    /**
     * Set the route id for the next route to be created.
     * Stages the id; does not affect the current route if one already exists.
     *
     * @param id - Unique route identifier (used in logs and context.getRouteById())
     * @returns This builder for chaining
     *
     * @example
     * ```typescript
     * craft().id('ingest-api').from(http({ path: '/ingest', method: 'POST' })).to(log()).build();
     * ```
     */
    id(id: string): PreFromBuilder;
    /**
     * Set a human-readable title for the next route. Mirrored into the
     * direct / mcp registries so discovery consumers (agents, docs) can
     * display it alongside the id.
     */
    title(value: string): PreFromBuilder;
    /**
     * Set a human-readable description for the next route. Used by
     * discovery-aware adapters when exposing the route to external consumers
     * (agents, MCP clients).
     */
    description(value: string): PreFromBuilder;
    /**
     * Gate the next route on a predicate. A route whose predicate is false is
     * `disabled`: registered and known to the context, not started, not
     * intaking, and not advertised as an agent tool.
     *
     * This is what makes "the agent cannot call this until I supply
     * credentials" true by construction. The tool surface is derived from what
     * the context has enabled, so a disabled capability is never offered to
     * the model rather than being offered and failing when called.
     *
     * Returning `true` enables the route. Returning a STRING disables it and
     * that string is the reason ops reports, which is why there is no separate
     * reason argument: one declaration cannot drift from the other. A
     * predicate that throws leaves the route disabled with the error message
     * as its reason and never fails the boot, because a missing credential is
     * a configuration state and not a reason to take the process down.
     *
     * Route metadata, not a filter: this decides whether the route runs at
     * all, so it sits beside `.id()` and `.description()` and never enters the
     * pre-from filter chain. It is evaluated per route lifecycle, never per
     * exchange.
     *
     * @param predicate - Returns `true`, or a string naming why it is off.
     * @param options - `refresh` re-evaluates on an interval or a cron
     *   schedule. Omitted (or `"manual"`) is MANUAL: evaluated once as the
     *   route starts and never again until something explicitly asks, which
     *   keeps the common environment-variable case free of any recurring cost.
     *
     * @example
     * ```typescript
     * craft()
     *   .id('mail-inbound')
     *   .description('Triage inbound mail')
     *   .enabled(() =>
     *     env.MAIL_USER && env.MAIL_APP_PASSWORD
     *       ? true
     *       : 'MAIL_USER and MAIL_APP_PASSWORD are not set',
     *   )
     *   .from(mail({ account: 'default', folder: 'INBOX' }))
     *   .to(direct('triage'));
     * ```
     */
    enabled(predicate: EnablementPredicate, options?: EnablementOptions): PreFromBuilder;
    /**
     * Declare input schemas for the next route. The engine validates incoming
     * message bodies and headers against these schemas before any pipeline
     * step runs, so the pipeline never sees an invalid message. A failure
     * throws `RC5065`, which a route `.error()` handler can recover;
     * unrecovered, it emits `route:exchange:failed`. Accepts either a bundle
     * (`{ body, headers }`) or a bare Standard Schema as a body-only shorthand.
     *
     * Issue messages are client-facing. The `http()` source and the ops
     * dispatch door answer an unrecovered failure with 400 carrying each
     * issue's path and message verbatim, so a custom message on a refinement
     * or an async validator reaches the caller as written: keep internal
     * detail out of it.
     *
     * When a body schema is given, the chain is retyped: the following
     * `.from(source)` opens the pipeline with the schema's inferred output
     * type, so the type does not have to be repeated as a `.from<T>()`
     * generic. An explicit `.from<T>()` still overrides the staged type.
     *
     * @example
     * ```typescript
     * craft()
     *   .id('lookup-user')
     *   .input({ body: UserQuerySchema })
     *   .from(direct())
     *   // the body is already typed as the schema output
     *   .transform((body) => findUser(body.userId))
     * ```
     */
    input<Schema extends StandardSchemaV1>(schemas: Schema | (RouteSchemas & {
        body: Schema;
    })): PreFromTypedBuilder<SetBody<S, StandardSchemaV1.InferOutput<Schema>>>;
    input(schemas: RouteSchemas): PreFromBuilder;
    /**
     * Declare output schemas for the next route. The engine validates the
     * final exchange against these schemas before the primary destination
     * fires; a validation failure is routed to the error handler. Accepts
     * either a bundle (`{ body, headers }`) or a bare Standard Schema as a
     * body-only shorthand.
     */
    output(schemas: RouteSchemas | StandardSchemaV1): PreFromBuilder;
    /**
     * Tag the next route. Accepts a single tag or an array; multiple
     * `.tag()` calls before `.from()` accumulate (deduplicated, insertion
     * order preserved). Empty strings are rejected.
     *
     * Tags drive selectors like `tools({ tagged: "read-only" })` in
     * `@routecraft/ai`; use the `KnownTag` literals (`"read-only"`,
     * `"destructive"`, `"idempotent"`, `"open-world"`) where they fit, and any
     * string otherwise. On a route exposed via `.from(mcp())`, these four tags
     * also derive the MCP tool annotation hints (`readOnlyHint`,
     * `destructiveHint`, `idempotentHint`, `openWorldHint`), so the same fact is
     * declared once; explicit `annotations` on `mcp()` still override per-key.
     */
    tag(value: Tag | Tag[]): PreFromBuilder;
    private mergeDiscovery;
    private normalizeSchemas;
    /**
     * Configure batch processing for the next route to be created.
     * Stages the batch consumer; does not affect the current route if one already exists.
     *
     * @param options - Optional `size` (batch size) and `flushInterval`
     * @returns This builder for chaining
     *
     * @example
     * ```typescript
     * craft().batch({ size: 10, flushInterval: "1s" }).from(timer({ interval: "1s" })).to(log()).build();
     * ```
     */
    batch(options?: {
        size?: number;
        flushInterval?: Duration;
    }): PreFromBuilder;
    /**
     * Attach an error handler. Dual-mode based on position relative to
     * `.from()`:
     *
     * - **Before `.from()`** (route scope): stages a catch-all for the
     *   route's pipeline. When any step throws an unhandled error the
     *   handler runs and the pipeline does NOT resume; the handler's
     *   return value becomes the route's final exchange body.
     * - **After `.from()`** (step scope): wraps the immediately next
     *   step. When that step throws the handler runs, its return value
     *   replaces `exchange.body`, and the pipeline continues with the
     *   next step. Subsequent steps see the recovery as if nothing went
     *   wrong.
     *
     * The handler signature is identical in both positions
     * (`(error, exchange, forward) => unknown`). When a step-scope
     * handler itself throws, the wrapper rethrows so a route-scope
     * handler (when set) catches it; otherwise the default error path
     * fires (`route:error`, `context:error`, `route:exchange:failed`). The
     * route is NOT stopped.
     *
     * @param handler - Receives the error, the exchange at the point of
     *   failure, and a `forward` function to delegate to another route
     *   via the direct adapter.
     * @returns This builder for chaining
     *
     * @example Route-scope catch-all
     * ```ts
     * craft()
     *   .id('process-orders')
     *   .error((err, ex, forward) => forward('error-route', { reason: String(err) }))
     *   .from(timer({ interval: "1m" }))
     *   .to(dangerousDestination)
     * ```
     *
     * @example Step-scope recovery (pipeline continues)
     * ```ts
     * craft()
     *   .id('resilient-pipeline')
     *   .from(timer({ interval: "1m" }))
     *   .transform(prepareRequest)
     *   .error((err) => ({ fallback: true, reason: String(err) }))
     *   .to(http({ url: 'https://flaky.api/endpoint' }))
     *   .to(database())
     * ```
     *
     * wrapper pattern. See `.standards/resilience-wrappers.md`.
     */
    error(handler: ErrorHandler): this;
    /**
     * Cache. Dual-mode, and the position decides what is cached:
     *
     * - **Before `.from()` (route scope):** caches the whole route. The
     *   route looks up its provider before any pipeline step runs. On a
     *   hit, the entire pipeline is skipped and the cached body is
     *   returned to the source as the route's final exchange body. On a
     *   miss, the pipeline runs and the terminal body is stored only when
     *   the exchange completes; a failed exchange is never stored. Side
     *   effects (e.g. `.to(destination)` calls) do NOT replay on a hit.
     *
     * - **After `.from()` (step scope):** caches only the output of the
     *   immediately-next step, whatever the rest of the route does. A step
     *   that returns an error reply without throwing (an `http()` enricher
     *   with `throwOnHttpError: false` answering 503) has that reply
     *   cached. See {@link StepBuilderBase.cache} for the step-scope
     *   contract.
     *
     * The default key is namespaced by route id (plus the cache's site at
     * step scope) and by the principal's issuer and subject with its actor
     * chain, then the body; a bodiless exchange needs an explicit `key`,
     * which is used verbatim. See {@link CacheOptions.key}.
     *
     * Route scope is refused at build (`RC5003`) on a route whose pipeline
     * contains `.authenticate()`: the cache check runs before the pipeline,
     * so a hit would skip authentication.
     *
     * Routes with an unbalanced `.split()` are not supported at route
     * scope (the pipeline produces N terminals rather than one) and throw
     * `RC5003` at build time. Use step-scope `.cache()` to wrap the
     * expensive step inside such a route.
     */
    cache(options?: CacheOptions<S["body"]>): this;
    /**
     * Timeout. Dual-mode:
     *
     * - **Before `.from()` (route scope):** bounds each run of the whole
     *   pipeline with a deadline at pre-from filter chain position 8
     *   (inside `.retry()`, so every attempt gets its own deadline). On
     *   expiry the pipeline throws `RC5011`, which a route-scope
     *   `.error()` handler catches like any other failure.
     *
     * - **After `.from()` (step scope):** wraps the immediately-next
     *   step; see {@link StepBuilderBase.timeout} for the step-scope
     *   contract.
     *
     * The bounded work is not cancelled on expiry (promises cannot be
     * cancelled); the timeout bounds how long the route waits, not the
     * work itself.
     */
    timeout(duration: Duration): this;
    /**
     * Retry. Dual-mode:
     *
     * - **Before `.from()` (route scope):** re-runs the whole pipeline
     *   on failure at pre-from filter chain position 7 (outside
     *   `.timeout()`, inside `.error()`). Every attempt re-runs the
     *   chain tail including the cache check, so a value cached by a
     *   previous attempt short-circuits the next one. After the final
     *   attempt fails, the error reaches the route-scope `.error()`
     *   handler (when set) or the default error path.
     *
     * - **After `.from()` (step scope):** wraps the immediately-next
     *   step; see {@link StepBuilderBase.retry} for the step-scope
     *   contract.
     *
     * Route-scope re-attempts re-run user steps and their side effects;
     * wrap only the flaky step with step-scope `.retry()` when the rest
     * of the pipeline must not repeat.
     *
     * With a `.split()` in the pipeline, every child still processes to
     * completion on each attempt, but only a failure of the MAIN
     * exchange triggers a re-attempt: a failed split child resolves
     * through the per-child failure events exactly as it would without
     * `.retry()`. Wrap a flaky per-child step with step-scope `.retry()`
     * after the split instead.
     */
    retry(options?: RetryOptions): this;
    /**
     * Throttle. Dual-mode:
     *
     * - **Before `.from()` (route scope):** rate-limits the whole pipeline
     *   at pre-from filter chain position 5, OUTSIDE the resilience
     *   wrappers (a throttled request never reaches retry / timeout). The
     *   gate runs before the cache check, so a paced request does not
     *   consume a cache lookup until it is admitted. Each gate's limiter
     *   is built per Route, so a definition reused across contexts does
     *   not share buckets.
     *
     *   Stacking is supported: multiple `.throttle()` calls before
     *   `.from()` AND-combine into independent gates (e.g. a global
     *   ceiling plus a per-principal `key` limit); the exchange must be
     *   admitted by all of them.
     *
     *   This gate paces exchanges WITHIN the pipeline: it rate-limits the
     *   downstream work but does not pause the source consumer, so under
     *   high concurrency exchanges queue in flight while they wait for a
     *   token. True source backpressure (a consumer that stops pulling) is
     *   a follow-up; see `.standards/resilience-wrappers.md` section 7.
     *
     * - **After `.from()` (step scope):** wraps the immediately-next step;
     *   see {@link StepBuilderBase.throttle} for the step-scope contract.
     */
    throttle(options: ThrottleOptions): this;
    /**
     * Circuit breaker. Dual-mode:
     *
     * - **Before `.from()` (route scope):** protects the whole pipeline at
     *   pre-from filter chain position 6, OUTSIDE `.retry()` (#7) and
     *   `.timeout()` (#8) and INSIDE `.throttle()` (#5). When the breaker
     *   is open the pipeline is skipped entirely and the configured
     *   `fallback` becomes the body (or `RC5025` is thrown when no fallback
     *   is set, which a route-scope `.error()` handler can catch). Because
     *   it sits outside retry, one fully exhausted attempt is recorded as a
     *   single breaker failure rather than one per retry. State is per
     *   Route, so a definition reused across contexts does not share a
     *   circuit.
     *
     * - **After `.from()` (step scope):** wraps the immediately-next step;
     *   see {@link StepBuilderBase.circuitBreaker} for the step-scope
     *   contract.
     *
     * Unlike `.throttle()`, circuit breakers do not stack: a single breaker
     * per route protects the pipeline. A second `.circuitBreaker()` before
     * `.from()` overwrites the first.
     */
    circuitBreaker(options: CircuitBreakerOptions): this;
    /**
     * Concurrency limiter (bulkhead). Dual-mode:
     *
     * - **Before `.from()` (route scope):** bounds the whole pipeline to
     *   `max` simultaneous in-flight exchanges at the INNERMOST resilience
     *   position, inside `.retry()` (#7) and `.timeout()` (#8) and inside
     *   `.circuitBreaker()` (#6) / `.throttle()` (#5). Innermost means a slot
     *   is acquired per attempt and released between retry backoffs, so a
     *   scarce slot is never held while a retry sleeps; it also means an
     *   outer `.retry()` can re-acquire a slot after a `reject`-mode
     *   `RC5026`. State is per Route, so a definition reused across contexts
     *   does not share a slot pool. Multiple `.concurrency()` calls stack and
     *   nest (e.g. a global `max` plus a per-key `max`).
     *
     * - **After `.from()` (step scope):** wraps the immediately-next step;
     *   see {@link StepBuilderBase.concurrency} for the step-scope contract.
     */
    concurrency(options: ConcurrencyOptions): this;
    /**
     * Declare an authorization requirement on the next route. **Route-only**:
     * stages the authorizer onto the next-route options and runs at route
     * entry, before any pipeline step. Same staging convention as `.id`,
     * `.title`, `.description`, `.input`, `.output`, `.tag`, and `.batch`:
     * a route-level pipeline op (e.g. `.to()`, `.transform()`) called while
     * authorizers are staged but no new `.from()` has opened a route throws
     * RC2001. For a mid-pipeline check use `.validate(authorize({...}))`
     * directly.
     *
     * The check verifies that the inbound exchange carries an authenticated
     * principal and (optionally) that the principal has every required role
     * and scope. It does NOT issue, mint, or attach any credential: it
     * asserts an existing identity meets the criteria.
     *
     * Multiple `.authorize()` calls stack and AND-combine: each runs in
     * declaration order, so a missing role in the first call short-circuits
     * before later predicates run.
     *
     * Failures throw RC5012 (no principal) or RC5015 (principal failed the
     * role / scope / predicate check). A route-level `.error()` handler
     * catches both like any other validation failure.
     *
     * @param options - Required roles, scopes, or a custom predicate. When
     *   omitted, only existence of an authenticated principal is checked.
     *
     * @example Route-entry guard on an MCP tool
     * ```ts
     * craft()
     *   .id('delete-user')
     *   .description('Delete a user by id')
     *   .authorize({ roles: ['admin'] })
     *   .from(mcp({ annotations: { destructiveHint: true } }))
     *   .to(deleteUserDestination)
     * ```
     *
     * @example Stacked authorizers on an HTTP route
     * ```ts
     * craft()
     *   .id('admin-billing')
     *   .authorize({ roles: ['admin'] })
     *   .authorize({ scopes: ['billing:write'] })
     *   .from(http({ path: '/admin/billing', method: 'POST' }))
     *   .to(billingDestination)
     * ```
     *
     * @example Chained routes
     * ```ts
     * craft()
     *   .id('public').from(simple('hi')).to(noop())
     *   .id('admin').authorize({ roles: ['admin'] }).from(adminSrc).to(noop())
     * ```
     */
    authorize(options?: AuthorizeOptions): PreFromBuilder;
    /**
     * Define the source of data for this route.
     * This is typically the first step in defining a route.
     *
     * @template T The type of data produced by the source
     * @param sources One or more source adapters or functions. Multiple
     *   sources require `.input({ body })` declared first (RC2001) so every
     *   ingress validates to the same body type.
     * @returns A RouteBuilder with the specified type T
     * @example
     * // Simple source with inferred type
     * .from<string[]>(http({ path: '/api/data', method: 'GET' }))
     *
     * // Source with callable function
     * .from<User[]>(async () => {
     *   const response = await fetch('https://api.example.com/users');
     *   return response.json();
     * })
     *
     * // After `.input({ body: schema })`, the schema's inferred output type
     * // flows through the chain automatically (see PreFromTypedBuilder):
     * // .input({ body: MySchema }).from(direct())
     *
     * // Expose one capability on several ingresses (internal + agents +
     * // integrations) that all feed the same pipeline. Multi-ingress requires
     * // `.input()` so every channel validates and normalizes to one body type:
     * // .input(QuerySchema).from(direct(), mcp(), http({ path: '/q', method: 'POST' }))
     *
     * // Spread sources in; `.from(list)` without the spread is ONE Iterable
     * // source that emits each element as a body. A spread on its own needs a
     * // `SourceList` return type:
     * // .input(QuerySchema).from(direct(), ...extraIngresses)
     * // .input(QuerySchema).from(...ingresses())
     *
     * The multiple-source `.input()` requirement is a deliberate build-time
     * precondition, enforced at `.from()` with RC2001 rather than in the type
     * system: the variadic overload is statically reachable on THIS class.
     * Chains that declare `.input({ body })` first go through
     * {@link PreFromTypedBuilder.from} instead, where the staged schema type
     * seeds the body so multi-ingress is typed without an explicit generic.
     */
    from<T>(source: SourceLike<T>): RouteBuilder<SetBody<S, T>>;
    from<T>(...sources: SourceList): RouteBuilder<SetBody<S, T>>;
    /**
     * Re-surface this instance as the pre-`.from()` staging type. The single
     * cast point for the route-scope staging methods, mirroring `retype()` on
     * the base class: there is one runtime object, and position in the chain
     * decides which type-level surface is reachable.
     */
    private prelude;
    /**
     * Internal method to ensure a source has been defined for the current route.
     * Throws an error if no source has been defined.
     *
     * @returns The current route definition
     * @throws Error if no source has been defined
     * @private
     */
    private requireSource;
    /**
     * Append a step to the current route. Implements the abstract hook from
     * {@link StepBuilderBase}, so every inherited pipeline operation (and
     * every registered DSL sugar) flows through this method. The route-only
     * operations that stay on `RouteBuilder` (`split`, `aggregate`, `choice`)
     * call it too.
     *
     * @param step - The step to append
     * @throws {RoutecraftError} RC2002 if `.from()` has not been called yet
     */
    protected pushStep<T extends Adapter>(step: Step<T>): void;
    /**
     * Split into multiple exchanges for fan-out. Each returned exchange is processed independently.
     * If no splitter is provided: array bodies are split into one exchange per element; non-array bodies
     * are treated as a single item (one exchange). Framework maintains `routecraft.split_hierarchy`
     * headers for aggregation.
     *
     * Splitters return the child BODIES (or `splitChild(body, headers)`
     * envelopes for per-child header overrides); the framework constructs the
     * child exchanges, assigns fresh ids, and inherits the parent's headers.
     *
     * @template ItemType The type of items in the array (inferred from array if not specified)
     * @param splitter Optional adapter or function `(exchange) => SplitResult<ItemType>[]`
     * @returns A RouteBuilder with the item type
     * @example
     * // Automatically split an array of numbers
     * .from<number[]>(source)
     * .split() // ItemType is inferred as number
     *
     * // Custom splitting logic - return the child bodies
     * .from(source)
     * .split<User>((exchange) => exchange.body.users)
     *
     * // Split a string by delimiter, with per-child header overrides
     * .split<string>((exchange) =>
     *   exchange.body.split(",").map((part, i) => splitChild(part, { "x-part": i })))
     */
    split<ItemType = S["body"] extends Array<infer U> ? U : S["body"]>(splitter?: Splitter<S["body"], ItemType> | CallableSplitter<S["body"], ItemType>): RouteBuilder<SetBody<S, ItemType>>;
    /**
     * Aggregate multiple items into a single result.
     * This is often used after a split operation to collect and combine the results.
     * If no aggregator is provided, items are collected into an array.
     *
     * @template ResultType The resulting type after aggregation
     * @param aggregator Optional function that combines multiple items into a single result
     * @returns A RouteBuilder with the new aggregated type
     * @example
     * // Automatically collect items into an array
     * .split()
     * .process((exchange) => ({ ...exchange, body: exchange.body * 2 }))
     * .aggregate() // Returns array of processed items
     *
     * // Custom aggregation logic
     * .aggregate<number>((exchanges) => {
     *   const sum = exchanges.reduce((acc, ex) => acc + ex.body, 0);
     *   return { body: sum, headers: exchanges[0].headers };
     * })
     */
    aggregate<ResultType = Array<S["body"]>>(aggregator?: Aggregator<S["body"], ResultType> | CallableAggregator<S["body"], ResultType>): RouteBuilder<SetBody<S, ResultType>>;
    /**
     * Conditionally route the exchange through one of several branches.
     *
     * Branches are passed variadically as {@link when} / {@link otherwise}
     * descriptors built from the standalone helpers, the same path surface
     * shared with `multicast`. Predicates are evaluated in registration order;
     * the first match wins. An optional `otherwise` branch catches exchanges
     * that no `when` matched. If no branch matches and no `otherwise` is
     * registered, the exchange is dropped with `reason: "unmatched"`.
     *
     * By default, a matched branch's steps are inlined before the remaining
     * main-pipeline steps, so the exchange converges back into the main flow
     * after the choice. A branch that ends in `b.halt()` short-circuits: the
     * exchange is dropped with `reason: "halted"` and the main pipeline does
     * not resume for it.
     *
     * Every branch's output (a sub-pipeline's final body, or a bare
     * destination's `.to()` result) is checked against `Out`, which becomes the
     * builder's body type after the choice. `Out` defaults to the current body,
     * so when all branches keep or converge on one type you write nothing
     * extra. When branches produce DIFFERENT types, name `Out` as the union and
     * narrow downstream:
     * `.choice<Report | Audit>(when(p, b => b.transform(toReport)), otherwise(...))`.
     * Each branch must produce a member of the union; the downstream sees the
     * union and must narrow it. The compiler enforces both.
     *
     * @template Out - Body type the choice produces (union of the branch outputs;
     *   defaults to the current body and is checked against every branch)
     * @param descriptors - `when(...)` / `otherwise(...)` branch descriptors
     * @returns A RouteBuilder typed at `Out`
     *
     * @example
     * ```ts
     * .choice(
     *   when(ex => ex.body.priority === 'urgent', b => b.to(urgentQueue)),
     *   when(ex => ex.body.amount > 1000,         b => b.to(reviewQueue)),
     *   otherwise(                                b => b.to(errorSink).halt()),
     * )
     * .to(finalDest)
     * ```
     */
    choice<Out = S["body"]>(...descriptors: ChoiceDescriptor<S["body"], Out>[]): RouteBuilder<SetBody<S, Out>>;
    /**
     * Fan the exchange out to multiple independent paths in parallel.
     *
     * Each path is either a bare destination or a sub-pipeline callback (the
     * same path surface as `choice`). Every path receives its own deep clone
     * of the exchange (fresh id, preserved correlation id) and runs as an
     * isolated nested pipeline; all paths run concurrently and the step waits
     * for every one to settle (`Promise.allSettled` semantics). A path that
     * throws fires its own clone's error events but does not fail the route or
     * its sibling paths, and a path that `.halt()`s only stops itself. Once
     * every path has settled, the ORIGINAL exchange continues downstream
     * unchanged, so the body type is preserved.
     *
     * Fire-and-forget is intentionally not offered; use `tap` (already
     * fire-and-forget) for that.
     *
     * A path output type is unconstrained (`Path<S["body"], unknown>`): a path
     * may reshape the body however it likes because its result is discarded;
     * only the original exchange continues. This differs from `choice`, where
     * branches must converge on one `Out`.
     *
     * Notes and limitations:
     * - The route-scope `.error()` handler does NOT fire for a path failure: a
     *   path that throws resolves through its own clone's default error events
     *   (`route:error` / `context:error` / `route:exchange:failed`). Wrap
     *   per-path recovery inside the path (`b => b.error(...).to(...)`) if you
     *   need it.
     * - Only the body is deep-copied. Object-valued user headers are shared by
     *   reference across the clones and the original; mutating a nested header
     *   field from a path is not isolated (an anti-pattern, as for `tap`).
     * - The body must be structured-cloneable (`structuredClone`); a body that
     *   cannot be cloned (class instances with methods, streams, functions)
     *   fails the multicast step.
     *
     * @param paths - Bare destinations or sub-pipeline callbacks to fan out to
     * @returns This RouteBuilder, body type unchanged
     *
     * @example
     * ```ts
     * .from(http('/orders'))
     * .multicast(
     *   queue('audit'),                                // bare destination
     *   b => b.transform(toWarehouse).to(http('/wh')), // sub-pipeline path
     * )
     * .to(next); // runs on the original exchange after all paths settle
     * ```
     */
    multicast(...paths: Path<S["body"], unknown>[]): RouteBuilder<S>;
    /**
     * Run EXACTLY ONE of several targets, chosen by a load-balancing strategy.
     * The sibling of `multicast` (all targets) and `choice` (one target by
     * predicate); dispatch is one target by strategy.
     *
     * The required leading argument is the strategy; the rest are the targets.
     * A target is a bare destination, a sub-pipeline callback `(b) => b...` (the
     * same path surface as `multicast`), or either wrapped in {@link weighted}
     * to co-locate a relative weight. There is no safe default strategy, so it
     * is required:
     *
     * - `"failover"` -- try targets in order until one succeeds; pairs with
     *   per-target `.retry()` / `.circuitBreaker()`.
     * - `"round-robin"` -- cycle through targets in order.
     * - `"weighted"` -- distribute by the `weighted()` weights (smooth weighted
     *   round-robin, deterministic).
     * - `{ strategy: "sticky", key }` -- exchanges sharing a `key` stick to one
     *   target. Object form only, because `key` is required.
     *
     * Side-effect-only, like `multicast`: the selected target runs on its own
     * deep clone, and the ORIGINAL exchange continues downstream unchanged, so
     * the body type is preserved and a target's output is unconstrained. A
     * target that throws fires its own clone's error events but does not fail
     * the route or the dispatch step (for `failover`, a failure advances to the
     * next target instead; if all fail, `route:operation:dispatch:exhausted`
     * fires and the original still continues).
     *
     * @param strategy - The selection strategy (string or object form)
     * @param targets - Destinations, sub-pipeline callbacks, or `weighted(...)`
     * @returns This RouteBuilder, body type unchanged
     *
     * @example
     * ```ts
     * .dispatch("failover", primary, secondary)
     * .dispatch("round-robin", workerA, workerB, workerC)
     * .dispatch("weighted", weighted(stable, 95), weighted(canary, 5))
     * .dispatch({ strategy: "sticky", key: (ex) => ex.body.userId }, a, b)
     * ```
     */
    dispatch(strategy: DispatchStrategy<S["body"]>, ...targets: DispatchTarget<S["body"], unknown>[]): RouteBuilder<S>;
    /**
     * Suppress bursts of exchanges, releasing only the LAST one in a burst
     * after a quiet period. The archetypal use is collapsing a flurry of
     * file-change or search-as-you-type events down to their final state.
     *
     * Each arrival is held (not passed downstream) and resets a `waitMs` quiet
     * timer; a newer arrival supersedes and drops the one being held. When the
     * timer fires (or the optional `maxWait` cap elapses from the burst's
     * start, guaranteeing progress under continuous activity), the held
     * exchange is released through the steps after `.debounce()`. An optional
     * `key` selector debounces independently per group.
     *
     * Unlike the other flow-control operations, debounce holds an exchange
     * OUTSIDE the pipeline queue and re-runs it later, so a released exchange
     * runs the downstream steps as a fresh exchange (new id, preserved
     * correlation id). A pending exchange is flushed on `drain()` / shutdown
     * rather than being lost. State is per-route; it is a route-scope operation
     * and is deliberately not available inside a fan-out path.
     *
     * @param options - `{ wait }`, plus optional `key` selector and `maxWait` cap
     * @returns This RouteBuilder, body type unchanged
     *
     * @example
     * ```ts
     * .from(file({ path: "./config", watch: true }))
     * .debounce({ wait: "500ms" }) // wait for editing to finish
     * .process(reloadConfig)
     * ```
     */
    debounce(options: DebounceOptions<S["body"]>): RouteBuilder<S>;
    /**
     * Finalize and return the route definition(s). Call after defining all steps.
     *
     * @returns Array of RouteDefinition (one per `.from()` in this builder chain)
     *
     * @example
     * ```typescript
     * const definitions = craft()
     *   .from<string[]>(source)
     *   .split()
     *   .process((ex) => ({ ...ex, body: (ex.body as string).toUpperCase() }))
     *   .to(destination)
     *   .build();
     * const { context } = await new ContextBuilder().routes(definitions).build();
     * await context.start();
     * ```
     */
    build(): RouteDefinition[];
    /**
     * Throw when a step-scope wrapper (`.error()`, `.retry()`, `.timeout()`,
     * `.throttle()`, `.circuitBreaker()`, `.concurrency()`, `.cache()`,
     * `.delay()`) was staged but the user is starting a
     * new route or finalising the build without consuming it. A wrapper
     * attaches to the immediately next pipeline step; if no step
     * follows on the current route, the wrapper would silently leak
     * into the next route's first step. Symmetric with the existing
     * "metadata staged but never consumed" rule.
     *
     * @internal
     */
    private assertNoPendingWrappers;
}
/**
 * Create a new route builder.
 *
 * This is the entry point for defining routes in a fluent way.
 *
 * @returns A new RouteBuilder instance
 *
 * @example
 * ```typescript
 * // Define a route that processes data
 * const myRoute = craft()
 *   .from(simple("Hello, World!"))
 *   .transform(data => data.toUpperCase())
 *   .to(log())
 * ```
 */
declare function craft(): PreFromBuilder;

/**
 * Builder hook that wraps a single step in a "dual-mode wrapper"
 * (e.g. `.error()`, `.retry()`, `.timeout()`, `.cache()`, `.delay()`).
 * Pushed onto {@link StepBuilderBase}'s pending wrapper stack when the
 * builder method runs in step scope; folded around the next pushed
 * step inside {@link StepBuilderBase.applyPendingWrappers}.
 *
 * @internal
 */
type StepWrapperFactory = <T extends Adapter>(inner: Step<T>) => Step<T>;

/**
 * The type-state bag threaded through the builder chain.
 *
 * Every builder generic (`RouteBuilder<S>`, `PathBuilder<S>`,
 * `StepBuilderBase<S>`) is parameterised by ONE bag rather than by loose
 * type arguments, because declaration merging freezes generic arity: the
 * moment an ecosystem package augments `interface StepBuilderBase<S>`, the
 * parameter list can never change again. With a bag, new tracked facets
 * (typed headers, accumulated tags, ...) become new OPTIONAL fields on this
 * interface, which is a non-breaking change for every augmentation already
 * in the wild.
 *
 * `body` is the only field today: the body type entering the next step.
 */
interface BuilderState {
    /** Body type entering the next pipeline step. */
    body: unknown;
    /**
     * Type of `ex.deferral.result` for the steps that follow a
     * `.defer({ schema })`, threaded in from the declared schema the way
     * `body` is threaded in from `.input()`. `unknown` before any defer.
     *
     * Optional, per the extension rule above: an existing augmentation or a
     * hand-written state bag that predates this field still satisfies the
     * constraint. Framework-internal bags always carry it explicitly, because
     * a bag that OMITS the key is a different shape from one that has it, and
     * the two do not interconvert (the builders are invariant in this bag).
     */
    deferral?: unknown;
}
/**
 * Replace the `body` field of a state bag, preserving every other (current
 * or future) field. The single way builder methods advance the body type;
 * using it everywhere means a new `BuilderState` field flows through every
 * existing chain method untouched.
 *
 * @template S - The incoming state bag
 * @template B - The new body type
 */
type SetBody<S extends BuilderState, B> = {
    [K in keyof S]: K extends "body" ? B : S[K];
};
/**
 * Replace the `deferral` field of a state bag, preserving every other
 * field. The `.defer()` counterpart of {@link SetBody}: it advances the
 * type of `ex.deferral.result` for the rest of the chain.
 *
 * `Omit` plus an intersection rather than a mapped type, because a mapped
 * type preserves optionality: mapping the OPTIONAL `deferral` key would
 * type the result as `R | undefined` and force a needless narrowing on
 * every read after a defer. After a `.defer()` the field is known.
 *
 * @template S - The incoming state bag
 * @template R - The expected-result type declared by `.defer({ schema })`
 */
type SetDeferral<S extends BuilderState, R> = Omit<S, "deferral"> & {
    deferral: R;
};
/**
 * The exchange type a callable sees at this point in the chain: the body
 * type from the bag, plus `ex.deferral.result` narrowed to whatever the
 * last `.defer({ schema })` declared.
 *
 * An intersection rather than a rewritten `Exchange`, so the narrowing is
 * additive: `Exchange<T>` already carries `deferral`, and
 * `DeferralAffordance<unknown> & DeferralAffordance<R>` reads `result`
 * as `R`. Before any defer the bag's field is `unknown` and the
 * intersection is a no-op.
 *
 * @template S - The state bag at this chain position
 */
type ExchangeOf<S extends BuilderState> = Exchange<S["body"]> & {
    readonly deferral: DeferralAffordance<S["deferral"]>;
};
/**
 * A path's state bag: a fresh chain over body `T`.
 *
 * Spelled out (rather than `{ body: T }`) because the builders are
 * invariant in their bag: a sub-pipeline that ends in a `.defer()`
 * produces a bag WITH the `deferral` key, and it is only assignable back
 * to the declared path type if that type has the key too.
 *
 * @template T - Body type entering the path
 */
type PathState<T> = {
    body: T;
    deferral: unknown;
};
/**
 * Body type after a bare pull-in step (`.enrich(x)` with no aggregator, or a
 * fetch-only adapter in `.to()`). A fetch that resolves `undefined` means
 * "no value" and leaves the body unchanged at runtime, so a result type that
 * includes `undefined` yields the union of the previous body and the defined
 * results; this keeps the static claim honest for nullable enrichers (a
 * cache miss, `(ex) => map.get(k)`). Return `null` instead when a miss
 * should be an observable replacement value. Result types without
 * `undefined` collapse to plain `R`.
 *
 * `void` is handled first and separately: an enricher declared to produce
 * nothing never replaces the body, so the body carries through as `Current`
 * rather than widening to `Current | void`. This mirrors the callable `.to()`
 * overload, which collapses a `void`-returning function the same way.
 *
 * @template Current - Body type entering the step
 * @template R - Value type the fetch produces
 */
type FetchedBody<Current, R> = R extends void ? Current : undefined extends R ? Current | Exclude<R, undefined> : R;
/**
 * Maps the polymorphic `this` type of a `StepBuilderBase` call to the same
 * concrete subclass re-typed at the new state bag `S2`. Enables methods on
 * the shared base class to return `RouteBuilder<S2>` or `PathBuilder<S2>`
 * automatically based on the receiver at the call site, without each subclass
 * overriding every method to narrow its return.
 *
 * Closed-world on purpose: only the framework-owned subclasses participate.
 * External subclasses fall through to `never`, which is intentional -- the
 * shared base class is not a public extension point today. Any future
 * framework-owned subclass (for example, a `dispatch` target builder) must
 * be added to the union below.
 *
 * @template This - The polymorphic `this` type inside a method on StepBuilderBase
 * @template S2 - The new state bag to re-type the subclass at
 */
type Retyped<This, S2 extends BuilderState> = This extends RouteBuilder<infer _RS extends BuilderState> ? RouteBuilder<S2> : This extends PathBuilder<infer _BS extends BuilderState> ? PathBuilder<S2> : never;
/**
 * Shared abstract base for builders that accumulate pipeline steps.
 *
 * Implements the pipeline operations that are identical across
 * `RouteBuilder` and `PathBuilder` (`to`, `transform`, `enrich`). Each
 * subclass provides its own `pushStep` hook describing where steps go --
 * `RouteBuilder` pushes into the current route definition (and enforces
 * that `.from()` has been called via `requireSource`), while
 * `PathBuilder` pushes into its internal step array.
 *
 * Return types are threaded through the polymorphic `this` via
 * {@link Retyped}, so a `.transform()` call on a `RouteBuilder<{ body: A }>`
 * returns `RouteBuilder<{ body: B }>` and the same call on
 * `PathBuilder<{ body: A }>` returns `PathBuilder<{ body: B }>`.
 *
 * The class value is framework-internal and must not be subclassed outside
 * the framework (the {@link Retyped} conditional is closed-world and external
 * subclasses would silently resolve to `never`). The TYPE, however, is the
 * documented augmentation point for DSL sugar: `registerDsl` adds the runtime
 * method here, and ecosystem packages declare its type by merging into
 * `interface StepBuilderBase<S extends BuilderState>` (see `registerDsl`).
 *
 * @template S - The {@link BuilderState} bag for the chain position
 */
declare abstract class StepBuilderBase<S extends BuilderState = BuilderState> {
    /**
     * Stack of step-scope wrapper factories declared since the last
     * pushed step, in declaration order. Folded around the next pushed
     * step by {@link applyPendingWrappers}; the first-declared wrapper
     * is outermost (`.retry().timeout().process(slow)` means
     * `retry(timeout(process))`). Cleared after each push.
     *
     * @internal
     */
    protected pendingStepWrappers: StepWrapperFactory[];
    /**
     * Fold any wrappers staged since the last push around `step`,
     * returning the (possibly wrapped) step that subclasses should hand
     * to their target collection. Clears the stack on every call so a
     * wrapper attaches to exactly one step.
     *
     * @internal
     */
    protected applyPendingWrappers<T extends Adapter>(step: Step<T>): Step<T>;
    /**
     * Append a step to the builder's pipeline. Implemented by each subclass
     * to route the step into the right collection (current route definition
     * vs. branch step array). Subclass-specific validation (e.g.
     * `RouteBuilder.requireSource`) lives in the implementation. Subclasses
     * MUST run `step` through {@link applyPendingWrappers} so dual-mode
     * wrappers (`.error()`, `.retry()`, `.timeout()`, etc.) attach to the right
     * step.
     *
     * @param step - The step to append
     */
    protected abstract pushStep<T extends Adapter>(step: Step<T>): void;
    /**
     * Attach an error handler to the next step. When the wrapped step
     * throws, the handler runs with `(err, exchange, forward)` (same
     * shape as the route-level handler), its return value replaces
     * `exchange.body`, and the pipeline continues with the next step.
     *
     * On `RouteBuilder`, this method is dual-mode: when called BEFORE
     * `.from()` it stages a route-level catch-all (existing behaviour);
     * when called AFTER `.from()` it wraps the next step. On
     * `PathBuilder`, it is always step-scope.
     *
     * If the handler itself throws, the wrapper rethrows so the
     * route-level handler (when set) catches it; otherwise the route's
     * default error path fires (`route:error`, `context:error`,
     * `route:exchange:failed`). The route is NOT stopped.
     *
     * Stacks left-to-right: `.error(h1).error(h2).to(dest)` produces
     * `h1` outermost wrapping `h2` wrapping `dest`. `h2` runs first; if
     * it rethrows, `h1` gets a chance.
     *
     * wrapper pattern (see `.standards/resilience-wrappers.md`).
     */
    error(handler: ErrorHandler): this;
    /**
     * Cache the result of the next step. When a cached value exists for
     * the derived key, the wrapped step is skipped and the cached body
     * replaces `exchange.body`. On a miss, the step runs and its output
     * body is written to the cache for future calls.
     *
     * Only the next step's output is cached, and only when that step
     * does not throw: a throw propagates and leaves the cache untouched,
     * and dropped exchanges (filter / halt) are not cached. A step that
     * returns an error reply without throwing (an `http()` enricher with
     * `throwOnHttpError: false` answering 503) succeeded as far as the
     * cache can tell, so that reply IS cached. Use route scope, or make
     * the step throw, when a failure must not be remembered.
     *
     * Concurrent exchanges with the same key share one computation via
     * the provider's `getOrCompute`, so a slow underlying operation
     * runs at most once per key per TTL window.
     *
     * On `RouteBuilder`, this method is dual-mode: called BEFORE
     * `.from()` it caches the whole route and never stores a failed
     * exchange (see {@link RouteBuilder.cache}). On `PathBuilder`, it is
     * always step-scope.
     *
     * Stacks left-to-right with other wrappers: `.error(h).cache().to(d)`
     * produces `error(cache(d))`, so the cache runs inside the error
     * handler's recovery scope.
     *
     * @param options Optional `{ key, ttl, provider }`. Defaults: a key
     *   namespaced by route id (plus, at step scope, this cache's site in the
     *   route) and the principal's issuer and subject (with its actor chain),
     *   then a SHA-256 of
     *   `JSON.stringify(body)` (see {@link CacheOptions.key}; a bodiless
     *   exchange needs an explicit `key`, used verbatim); no TTL;
     *   process-wide in-memory provider.
     */
    cache(options?: CacheOptions<S["body"]>): this;
    /**
     * Wait a fixed time before the next step runs. Pass-through: the
     * exchange is unchanged by the wait. The wait is cancelled when the
     * route shuts down mid-wait; the wrapped step still runs, so no
     * exchange is silently dropped by a shutdown.
     *
     * Step scope only: there is no route-scope form (a route-scope delay
     * is equivalent to a delay before the first step) and the pre-from
     * filter chain reserves no slot for it.
     *
     * Stacks with other wrappers in declaration order (first-declared
     * outermost): `.retry().delay(1000).process(op)` waits before each
     * attempt, because retry re-runs the delay-wrapped step.
     *
     * @param duration - How long to wait before the next step
     * @returns This builder (same subclass, same body type)
     */
    delay(duration: Duration): this;
    /**
     * Bound the next step with a deadline. When the step settles in time
     * its outcome passes through unchanged; when the deadline fires first
     * the wrapper throws `RC5011` (Request timeout, `retryable: true`),
     * so an outer `.retry()` re-attempts it by default and `.error()`
     * handlers can branch on the code.
     *
     * The step is not cancelled on expiry (promises cannot be
     * cancelled): it keeps running in the background and its eventual
     * result is discarded, so side effects of the abandoned attempt may
     * still happen. The timeout bounds how long the pipeline waits, not
     * the work itself.
     *
     * On `RouteBuilder`, this method is dual-mode: called BEFORE
     * `.from()` it bounds each run of the whole pipeline at pre-from
     * filter chain position 8 (inside `.retry()`, so each attempt gets
     * its own deadline); called AFTER `.from()` it wraps the next step.
     *
     * @param duration - The deadline
     * @returns This builder (same subclass, same body type)
     */
    timeout(duration: Duration): this;
    /**
     * Re-attempt the next step on failure with configurable backoff.
     * Each attempt receives the same (frozen) exchange, so a re-attempt
     * always starts from the input that failed. After the final attempt
     * fails, the original error propagates unchanged to outer wrappers
     * or the route-level handler.
     *
     * By default only errors with `retryable: false` (validation, auth,
     * config) are NOT re-attempted; everything else, including timeouts
     * (`RC5011`) and unknown third-party errors, is retried. Override
     * with `retryOn`.
     *
     * On `RouteBuilder`, this method is dual-mode: called BEFORE
     * `.from()` it re-runs the whole pipeline at pre-from filter chain
     * position 7 (outside `.timeout()`, inside `.error()`); called AFTER
     * `.from()` it wraps the next step.
     *
     * Stacks with other wrappers in declaration order (first-declared
     * outermost): `.retry().timeout(5000).to(dest)` gives each attempt
     * its own 5s deadline.
     *
     * @param options - `maxAttempts` (default 3), `backoff` (a `Duration`,
     *   default 1000 ms), `factor` (growth multiplier, default 1 = fixed),
     *   `maxBackoff` (a `Duration`, the wait ceiling), `jitter` (`"none"` | `"full"` |
     *   `0..1`, default `"none"`), `retryOn` (default: skip non-retryable
     *   RoutecraftErrors)
     * @returns This builder (same subclass, same body type)
     */
    retry(options?: RetryOptions): this;
    /**
     * Rate-limit the next step to `rate` calls per `per` window (token
     * bucket). Exchanges that exceed the rate are paced (delayed) rather
     * than dropped, so backpressure flows back through the pipeline.
     *
     * By default the limiter is one bucket shared across the route (a
     * global limit). Pass a `key` selector to partition it per user / IP /
     * tenant: each distinct key gets its own bucket, bounded by `maxKeys`.
     * After an idle window up to `burst` calls (default `rate`) pass
     * immediately, then admissions settle to the configured rate.
     *
     * On `RouteBuilder`, this method is dual-mode: called BEFORE
     * `.from()` it rate-limits the whole pipeline at pre-from filter chain
     * position 5 (outside the resilience wrappers, so a throttled request
     * never reaches retry / timeout); called AFTER `.from()` it wraps the
     * next step. Multiple `.throttle()` calls AND-combine into independent
     * limits.
     *
     * The pacing wait is cancellable: when the route shuts down mid-wait
     * the exchange is admitted immediately rather than dropped.
     *
     * @param options - `{ rate, per?, burst?, key?, maxKeys? }`
     * @returns This builder (same subclass, same body type)
     */
    throttle(options: ThrottleOptions): this;
    /**
     * Protect the next step with a circuit breaker. Counts the step's
     * failures over a sliding `windowMs`; once `failureThreshold` failures
     * accumulate the breaker trips OPEN and subsequent calls fast-fail
     * (returning `fallback(exchange)` when set, otherwise throwing
     * `RC5025`) without running the step. After `cooldownMs` the breaker
     * goes HALF-OPEN and admits up to `halfOpenMax` probe calls: one
     * success closes it, one failure re-opens it.
     *
     * Deterministic errors do not count toward the threshold by default
     * (any `RoutecraftError` flagged `retryable: false`, e.g. auth or
     * validation), since they are not evidence the downstream is unhealthy;
     * override with `isFailure`.
     *
     * Only the immediately-next step is protected; later steps run
     * normally. The breaker state is shared per route (one circuit across
     * every exchange on the route), not per exchange.
     *
     * On `RouteBuilder`, this method is dual-mode: called BEFORE `.from()`
     * it protects the whole pipeline at pre-from filter chain position 6
     * (outside `.retry()` / `.timeout()`, so it records one tripped call
     * per fully exhausted attempt); called AFTER `.from()` it wraps the
     * next step.
     *
     * Stacks with other wrappers in declaration order (first-declared
     * outermost).
     *
     * @param options - `failureThreshold` (required), `windowMs` (default
     *   60_000), `cooldownMs` (default 30_000), `halfOpenMax` (default 1),
     *   optional `fallback`, `onStateChange`, `isFailure`, and `label`.
     * @returns This builder (same subclass, same body type)
     */
    circuitBreaker(options: CircuitBreakerOptions): this;
    /**
     * Bound the next step to `max` simultaneous in-flight exchanges
     * (a bulkhead). Where `.throttle()` caps a RATE (calls per window),
     * `.concurrency()` caps SIMULTANEITY (how many run at once) -- protect a
     * connection pool, a memory-bound step, or a downstream with a hard
     * concurrency cap. The two compose but are not substitutes.
     *
     * When all slots are busy the default `queue` mode makes the exchange
     * wait FIFO for a slot (backpressure), bounded by `maxQueue`; `reject`
     * mode fails fast with `RC5026` instead. Pass a `key` selector to give
     * each user / tenant / pool its own independent slots, bounded by
     * `maxKeys`. The queue wait is cancellable: on route shutdown a waiting
     * exchange is admitted rather than dropped.
     *
     * On `RouteBuilder`, this method is dual-mode: called BEFORE `.from()` it
     * bounds the whole pipeline at the innermost resilience position (inside
     * `.retry()` / `.timeout()`, so a slot is acquired per attempt and
     * released between retry backoffs, never held while sleeping); called
     * AFTER `.from()` it wraps the next step.
     *
     * Stacks with other wrappers in declaration order (first-declared
     * outermost).
     *
     * @param options - `{ max, mode?, maxQueue?, key?, maxKeys?, label? }`
     * @returns This builder (same subclass, same body type)
     */
    concurrency(options: ConcurrencyOptions): this;
    /**
     * Return `this` re-typed to the concrete subclass with the state bag's
     * `body` replaced by `B` (other bag fields preserved).
     *
     * The single cast point used by every pipeline method that changes the
     * body type. Centralising it means `RouteBuilder` and `PathBuilder`
     * do not each need their own `withType<T>()` helper, and the closed-world
     * {@link Retyped} conditional resolves the return type to the caller's
     * concrete subclass.
     *
     * @template B - New body type
     * @returns This instance, re-typed
     */
    protected retype<B>(): Retyped<this, SetBody<S, B>>;
    /**
     * Hand the exchange to a destination (push out) or enricher (pull in).
     *
     * Role resolution: an adapter with a `send` slot is a push-out, and the
     * body continues unchanged (receipts surface via headers, see
     * {@link SendContext}); when an adapter has both `send` and `fetch`,
     * `send` wins ("to a file means save to it"). A fetch-only adapter (e.g.
     * `http({ url })`, `direct("endpoint")`) is a pull-in, and the fetched
     * value replaces the body; a fetch resolving `undefined` means "no value"
     * and leaves the body unchanged (see {@link FetchedBody}). Function forms
     * follow their inferred return type: `(ex) => void` is a send,
     * `(ex) => R` replaces the body with `R`.
     *
     * @param target - Destination, Enricher, or callable
     * @returns The subclass builder re-typed to the step's output body
     * @template R - Fetched result body type for pull-in targets
     */
    to(destination: Destination<S["body"]>): Retyped<this, S>;
    to<R>(enricher: Enricher<S["body"], R>): Retyped<this, SetBody<S, FetchedBody<S["body"], R>>>;
    to<R = void>(fn: (exchange: ExchangeOf<S>, ctx?: SendContext) => Promise<R> | R): Retyped<this, SetBody<S, R extends void ? S["body"] : R>>;
    /**
     * Transform the exchange body. The transformer receives the current
     * body and returns the replacement body. Headers and exchange identity
     * are preserved. Use `.process()` when the full exchange is needed.
     *
     * @param transformer - Adapter or callable that maps the body to a new value
     * @returns The subclass builder re-typed to the transformer's output
     * @template Return - Result body type
     */
    transform<Return>(transformer: Transformer<S["body"], Return> | CallableTransformer<S["body"], Return, ExchangeOf<S>>): Retyped<this, SetBody<S, Return>>;
    /**
     * Enrich the exchange with data pulled in by an {@link Enricher} (e.g. an
     * HTTP lookup or a file read). With no aggregator the fetched value
     * REPLACES the body. Pass an aggregator to merge instead: `only(...)`
     * carries an `ENRICH_MERGE_TYPE` brand that drives the body-type
     * inference, `none()` keeps the body, and a custom aggregator returns the
     * derived exchange itself.
     *
     * A fetch resolving `undefined` means "no value" and leaves the body
     * unchanged ({@link FetchedBody} reflects this in the inferred type);
     * return `null` when a miss should be an observable replacement value.
     *
     * @param enricher - Enricher adapter or callable that produces the data
     * @param aggregator - Optional merge strategy; omitted = replace the body
     * @returns The subclass builder re-typed to the resulting body shape
     * @template R - Value type produced by the enricher
     * @template A - Aggregator type (drives body shape inference)
     */
    enrich<R>(enricher: Enricher<S["body"], R> | CallableEnricher<S["body"], R, ExchangeOf<S>>): Retyped<this, SetBody<S, FetchedBody<S["body"], R>>>;
    enrich<R, A extends EnrichAggregator<S["body"], R> | (EnrichAggregator<unknown, unknown> & {
        [ENRICH_MERGE_TYPE]?: EnrichMergeShape;
    })>(enricher: Enricher<S["body"], R> | CallableEnricher<S["body"], R, ExchangeOf<S>>, aggregator: A): Retyped<this, SetBody<S, A extends {
        [ENRICH_MERGE_TYPE]: infer M;
    } ? S["body"] & M : S["body"]>>;
    /**
     * Process the exchange with a custom function with full access to
     * headers, body, and context. Use when you need more control than
     * `.transform()` (which only operates on the body).
     *
     * @param processor - Function that receives and returns the exchange
     * @returns The subclass builder re-typed to the processor's output body
     * @template Return - Result body type (defaults to the current body)
     */
    process<Return = S["body"]>(processor: Processor<S["body"], Return> | CallableProcessor<S["body"], Return, ExchangeOf<S>>): Retyped<this, SetBody<S, Return>>;
    /**
     * Set or override a single header on the current exchange. Body type is
     * unchanged.
     *
     * @param key - Header key to set (e.g. `x-request-id`, `routecraft.custom`)
     * @param valueOrFn - Static value or a function returning the value from the exchange
     * @returns This builder (same subclass, same body type)
     */
    header(key: string, valueOrFn: HeaderLiteral | ((exchange: ExchangeOf<S>) => HeaderValue | Promise<HeaderValue>)): this;
    /**
     * Establish the authenticated principal for the exchange. The resolver
     * returns identity claims you have verified yourself (an e-mail sender, a
     * Slack signature, a webhook HMAC); they are minted into a branded
     * principal and attached to the exchange. Return `undefined` to leave the
     * caller anonymous. Body type is unchanged.
     *
     * This is the explicit, greppable way to mint identity. `authorize()`
     * trusts only principals established this way (or by a source verifier);
     * a plain object written via `.header("routecraft.auth.principal", ...)`
     * is rejected. Sugar over the `authenticate()` helper.
     *
     * @param resolver - Returns the caller's claims, or `undefined` to skip
     * @returns This builder (same subclass, same body type)
     *
     * @example
     * ```ts
     * craft()
     *   .from(mail("INBOX"))
     *   .filter(verifiedSenders)
     *   .authenticate((ex) => {
     *     // The mail source attaches the computed sender to a header.
     *     const sender = ex.headers["routecraft.mail.sender"];
     *     return {
     *       scheme: "email",
     *       subject: sender.address,
     *       roles: sender.address.endsWith("@acme.com") ? ["internal"] : [],
     *     };
     *   })
     *   .authorize({ roles: ["internal"] })
     *   .to(dest)
     * ```
     */
    authenticate(resolver: CallableAuthenticator<S["body"]>): this;
    /**
     * Mark the exchange's principal as being exercised by an actor (an agent,
     * a service) on the subject's behalf. The resolver returns the actor's
     * identity claims plus the consent-derived scope ceiling; they are minted
     * into a delegated principal (subject unchanged, actor set, scopes
     * intersected) and attached to the exchange. Body type is unchanged.
     *
     * A resolver that returns `undefined` (no consent record) fails closed by
     * default: the subject's direct principal is STRIPPED so the continuation
     * runs anonymous and downstream `authorize()` refuses with RC5012. An
     * actor downstream must never inherit a caller's full direct authority
     * precisely because consent is absent. The strip skips anonymous
     * exchanges, already-delegated principals, and autonomous agent subjects
     * (`subjectProfile: "ai_agent"`). Pass `{ otherwise: "keep" }` when the
     * continuation serves the caller directly and an ungranted caller should
     * keep acting as themselves.
     *
     * Sugar over the `delegate()` helper; see it for the full semantics
     * (scope intersection, role pass-through, chain nesting, mayAct
     * enforcement). Requires an authentic principal on the exchange when a
     * directive is returned.
     *
     * @param resolver - Returns the delegation directive, or `undefined`
     * @param options - No-consent behavior; default `{ otherwise: "drop" }`
     * @returns This builder (same subclass, same body type)
     *
     * @example
     * ```ts
     * craft()
     *   .from(mail("INBOX"))
     *   .authenticate(mailPrincipal)
     *   .delegate((ex) => {
     *     const grant = grants.find(ex.principal?.subject, "agent:zoe")
     *     if (!grant) return undefined // no consent: principal is dropped
     *     return { actor: zoeIdentity, scopes: grant.scopes, grantId: grant.id }
     *   })
     *   .to(agent("zoe"))
     * ```
     */
    delegate(resolver: CallableDelegator<S["body"]>, options?: DelegateStepOptions): this;
    /**
     * Execute a side effect without changing the data. Fire-and-forget --
     * the tap runs asynchronously (tracked for drain) while the main flow
     * continues. Tap receives a snapshot of the exchange (body/headers
     * cloned). Accepts a Destination (send), a fetch-only Enricher (fetch and
     * discard, e.g. `.tap(http({ url }))` as a fire-and-forget call), or a
     * function form. Errors are emitted as events and rethrown for
     * observability, but do not stop the pipeline.
     *
     * @param target - Destination, Enricher, or callable for the side effect
     * @returns This builder (same subclass, same body type)
     */
    tap(target: TapTarget<S["body"], ExchangeOf<S>>): this;
    /**
     * Filter the exchange based on a predicate. Return `true` to keep the
     * exchange, `false` to drop it, or `{ reason: string }` to drop with
     * an explanation recorded in telemetry.
     *
     * @param filter - Filter adapter or callable predicate
     * @returns This builder (same subclass, same body type)
     */
    filter(filter: Filter<S["body"]> | CallableFilter<S["body"], ExchangeOf<S>>): this;
    /**
     * Sample exchanges by count or time interval, passing the admitted ones
     * and dropping the rest (silently, like a `filter` returning false).
     * Useful for reducing volume from a high-frequency source while staying
     * representative. Pass exactly one of `every` (count-based: every Nth
     * exchange) or `intervalMs` (time-based: the first exchange per window).
     * Sampler state is per-route.
     *
     * @param options - `{ every }` for count-based or `{ intervalMs }` for time-based sampling
     * @returns This builder (same subclass, same body type)
     */
    sample(options: SampleOptions): this;
    /**
     * Suppress duplicate exchanges by a derived key, so the same input is not
     * processed more than once. The key is derived from the body by default
     * (SHA-256 of its JSON serialisation) or from an explicit `key` function.
     * A key is reserved on entry and committed when the exchange completes
     * (released on failure, so an errored input may retry); a duplicate is
     * dropped silently. State is in-memory and per-route.
     *
     * @param options - Optional `key` deriver, `ttl` (ms), and `maxKeys` bound
     * @returns This builder (same subclass, same body type)
     */
    dedupe(options?: DedupeOptions): this;
    /**
     * Validate the exchange body using a Validator adapter or callable. On
     * success the (possibly coerced) return value replaces the body. On
     * failure the adapter throws and the route error handler (if configured)
     * or the default error path handles it. For Standard Schema, prefer the
     * `.schema()` sugar or pass the `schema()` factory.
     *
     * @param validator - Validator adapter or callable
     * @returns The subclass builder re-typed to the validator's output body
     * @template R - Output body type after validation (defaults to the current body)
     */
    validate<R = S["body"]>(validator: Validator<S["body"], R> | CallableValidator<S["body"], R, ExchangeOf<S>>): Retyped<this, SetBody<S, R>>;
    /**
     * Symbol-keyed append used by `registerDsl` to add sugar methods
     * without exposing `pushStep` as public API. Lives on the base so
     * both `RouteBuilder` and `PathBuilder` inherit it and registered
     * sugar works on both.
     *
     * @internal
     */
    [PUSH_STEP]<T extends Adapter>(step: Step<T>): this;
}

/**
 * Predicate that decides whether a choice branch matches an exchange.
 *
 * Predicates are synchronous by design for phase 1. Async predicates can be
 * introduced later without changing the runtime shape; the branch registration
 * API would add an `asyncWhen` or widen `predicate` to return a Promise.
 *
 * @template T - Body type of the exchange at the point of the choice
 */
type ChoicePredicate<T = unknown> = (exchange: Exchange<T>) => boolean;
/**
 * A single fan-out path: either a bare destination (the exchange is sent to
 * it) or a callback that builds a sub-pipeline on a {@link PathBuilder}. This
 * is the one shared path shape used by `choice` (`when` / `otherwise`),
 * `multicast`, and future branch operations.
 *
 * A callable destination (a bare function with a `send` method) is NOT a
 * valid bare path here, because it is indistinguishable at runtime from a
 * builder callback; wrap it as `(b) => b.to(callableDest)` instead.
 *
 * @template In  - Body type entering the path
 * @template Out - Body type the path produces (defaults to `In`)
 */
type Path<In = unknown, Out = In> = Destination<In> | Enricher<In, unknown> | ((b: PathBuilder<PathState<In>>) => PathBuilder<PathState<Out>>);
/**
 * Descriptor produced by {@link when}: a predicate plus the path that runs
 * when it matches. Opaque to callers; consumed by `.choice(...)`.
 *
 * @template In  - Body type entering the branch
 * @template Out - Body type the branch produces
 */
interface WhenDescriptor<In = unknown, Out = In> {
    readonly kind: "when";
    readonly predicate: ChoicePredicate<In>;
    readonly path: Path<In, Out>;
}
/**
 * Descriptor produced by {@link otherwise}: the default path taken when no
 * `when` predicate matches. Opaque to callers; consumed by `.choice(...)`.
 *
 * @template In  - Body type entering the branch
 * @template Out - Body type the branch produces
 */
interface OtherwiseDescriptor<In = unknown, Out = In> {
    readonly kind: "otherwise";
    readonly path: Path<In, Out>;
}
/**
 * Either kind of branch descriptor accepted by `.choice(...)`.
 *
 * @template In  - Body type entering the branches
 * @template Out - Body type every branch must converge on
 */
type ChoiceDescriptor<In = unknown, Out = In> = WhenDescriptor<In, Out> | OtherwiseDescriptor<In, Out>;
/**
 * Register a conditional branch for `.choice(...)`. The predicate receives
 * the exchange at the point of the choice; the path runs when it returns
 * true. Branches are evaluated in registration order and the first match
 * wins.
 *
 * Three overloads, so the branch's OUTPUT type is checked against the choice's
 * converged `Out` either way: a sub-pipeline callback `(b) => b...` produces
 * the body type its chain ends on, and a bare adapter follows `.to()`
 * semantics (a Destination's send leaves the body unchanged, a fetch-only
 * Enricher replaces it with the fetched value). When the branches differ, set
 * the choice output to the union and narrow downstream:
 * `.choice<Report | Audit>(when(p, b => b.transform(toReport)), otherwise(...))`.
 *
 * When `when(...)` is passed directly as a `.choice(...)` argument, the body
 * type flows in by contextual typing, so `ex.body` is typed without an
 * annotation. Only when a descriptor is built OUTSIDE the call (assigned to a
 * variable first) is there no context to infer from; annotate the predicate
 * parameter or supply the `In` type argument
 * (`when<Order>((ex) => ex.body.priority === "urgent", ...)`) in that case.
 *
 * @param predicate - Receives the exchange; returns true if this branch handles it
 * @param branch - Sub-pipeline callback (overload 1) or bare destination (overload 2)
 */
declare function when<In = unknown, Out = In>(predicate: ChoicePredicate<In>, branch: (b: PathBuilder<PathState<In>>) => PathBuilder<PathState<Out>>): WhenDescriptor<In, Out>;
declare function when<In = unknown>(predicate: ChoicePredicate<In>, destination: Destination<In>): WhenDescriptor<In, In>;
declare function when<In = unknown, R = unknown>(predicate: ChoicePredicate<In>, enricher: Enricher<In, R>): WhenDescriptor<In, FetchedBody<In, R>>;
/**
 * Register the default branch for `.choice(...)`, taken when no `when`
 * predicate matches. Equivalent to Camel's `.otherwise()`. If omitted and no
 * branch matches, the exchange is dropped with `reason: "unmatched"`. At most
 * one `otherwise` may be passed to a single `.choice(...)`.
 *
 * Like {@link when}, the overloads accept a sub-pipeline callback or a bare
 * adapter, both with their output checked against the choice's `Out`.
 *
 * @param branch - Sub-pipeline callback (overload 1) or bare adapter (overloads 2 and 3)
 */
declare function otherwise<In = unknown, Out = In>(branch: (b: PathBuilder<PathState<In>>) => PathBuilder<PathState<Out>>): OtherwiseDescriptor<In, Out>;
declare function otherwise<In = unknown>(destination: Destination<In>): OtherwiseDescriptor<In, In>;
declare function otherwise<In = unknown, R = unknown>(enricher: Enricher<In, R>): OtherwiseDescriptor<In, FetchedBody<In, R>>;
/**
 * Sub-builder that defines the step pipeline for a single fan-out path.
 *
 * Exposed to the user as the `b` parameter inside `when(pred, b => ...)`,
 * `otherwise(b => ...)`, and `multicast(b => ...)`. Pipeline operations
 * (`to`, `transform`, `enrich`, ...) are inherited from
 * {@link StepBuilderBase} and behave identically to their counterparts on
 * `RouteBuilder`; the polymorphic return types ensure a chained call re-types
 * this builder as `PathBuilder<NewT>`.
 *
 * PathBuilder adds `.halt()` for explicit short-circuit of the enclosing
 * path. Path-unsafe ops like `.split()` / `.aggregate()` / `.from()` are
 * deliberately absent because they have no coherent meaning inside a path.
 *
 * @template S - The {@link BuilderState} bag entering this path
 */
declare class PathBuilder<S extends BuilderState = BuilderState> extends StepBuilderBase<S> {
    private readonly steps;
    protected pushStep<T extends Adapter>(step: Step<T>): void;
    /**
     * Short-circuit the pipeline for this exchange. Once `halt()` executes, no
     * further steps run -- neither the remaining path steps nor (for a choice
     * branch) the steps after the enclosing `.choice()` on the main pipeline.
     * The exchange emits `route:exchange:dropped` with `reason: "halted"`.
     *
     * Useful for branches that handle error cases and do not want the rest of
     * the main pipeline to run, e.g.
     * `.otherwise(b => b.to(errorSink).halt())`.
     *
     * @returns This builder (for chaining, though no further steps will execute)
     */
    halt(): PathBuilder<S>;
    /**
     * Hand the compiled step array to the enclosing step. Symbol-keyed so it
     * does not pollute the public autocomplete surface on the builder.
     *
     * @internal
     */
    [COLLECT_STEPS](): Step<Adapter>[];
}

/**
 * Marker adapter for the MulticastStep. Exposes no configuration; the paths
 * live on the step itself.
 */
interface MulticastAdapter extends Adapter {
    readonly adapterId: "routecraft.operation.multicast";
}
/**
 * Step that fans the exchange out to multiple independent paths in parallel.
 *
 * Each path receives its own deep clone of the exchange (fresh id, preserved
 * correlation id) and runs as an isolated nested pipeline. All paths run
 * concurrently and the step waits for every one to settle
 * (`Promise.allSettled` semantics): a path that throws fires that clone's own
 * error events but does not fail the route or its sibling paths, and a path
 * that `.halt()`s only stops itself. Once every path has settled the ORIGINAL
 * exchange continues downstream unchanged.
 *
 * Path failures do NOT reach the route-scope `.error()` handler: each path is
 * a self-contained sub-flow whose failure resolves through its own clone's
 * default error events. Only the body is deep-copied; object-valued user
 * headers are shared by reference across clones (mutating a nested header
 * field from a path is not isolated). The body must be structured-cloneable;
 * a non-cloneable body fails this step.
 *
 * Fire-and-forget is intentionally not offered here; use `tap` (already
 * fire-and-forget) for that.
 */
declare class MulticastStep<In = unknown> implements Step<MulticastAdapter> {
    private readonly paths;
    operation: OperationType;
    adapter: MulticastAdapter;
    constructor(paths: Step<Adapter>[][]);
    /**
     * Expose the fan-out paths to framework-level walks of the route's step
     * tree. `rejoins: false`: a path runs as an isolated nested pipeline on
     * its own clone and never flows back into the main pipeline, so the
     * defer-site resolver refuses a `.defer()` inside one.
     *
     * @internal
     */
    [NESTED_STEPS](): ReadonlyArray<NestedSteps>;
    execute(exchange: Exchange<In>, ctx: StepContext): Promise<StepOutcome>;
}

/**
 * Function that returns the value for a header. Can be async. Use with `.header(key, valueOrFn)`.
 *
 * @template T - Body type of the exchange
 */
type CallableHeaderSetter<T = unknown> = (exchange: Exchange<T>) => Promise<HeaderValue> | HeaderValue;
/**
 * Header setter adapter: sets or overrides one exchange header. Body is unchanged.
 * Used by the builder's `.header(key, valueOrFn)`.
 *
 * @template T - Body type
 */
interface HeaderSetter<T = unknown> extends Adapter {
    /** Header key to set (e.g. `x-request-id`, `routecraft.custom`) */
    key: string;
    /** Computes the header value from the exchange (or static value via wrapper) */
    set: CallableHeaderSetter<T>;
}

/**
 * Options for `.defer()`.
 *
 * Notification, conditional asking, and consuming the verdict are all
 * expressible with operations the DSL already has, so none of them is an
 * option here: notify with a `.tap()` before the defer, gate with
 * `.choice()`, consume with `.filter()` after it.
 *
 * Who may RESUME is not an option here either, and deliberately so: the
 * framework has no model of what makes a resuming principal legitimate.
 * `meta` carries whatever the application's own policy needs onto the
 * record, and `.resume({ authorize })` is where that policy runs.
 *
 * @template Schema - The `schema` option, whose output types `ex.deferral.result`
 */
interface DeferOptions<Schema extends StandardSchemaV1 = StandardSchemaV1> {
    /**
     * The declared shape of the resume payload. Optional.
     *
     * The framework has no approve/deny concept: a deferral is a durable
     * pause with one single-use payload slot of arbitrary shape, and this
     * route's own continuation interprets whatever arrives. Declaring a
     * schema buys three things: the JSON Schema rendering advertised on the
     * acknowledgment so an approval UI or a calling agent can render a form,
     * pre-claim validation of the payload (`RC5049`, so garbage cannot spend
     * the link), and the typing of `ex.deferral.result` downstream.
     *
     * Absent, none of those apply: no ingress validation, and the result
     * types `unknown`. A click-yes consent flow stops paying schema ceremony
     * it never needed.
     */
    schema?: Schema;
    /**
     * How long the deferral stays resumable. Omit for no expiry.
     *
     * An expired deferral is not a dead end: a resume arriving late (or the
     * sweeper reaching it first) re-enters this route's error channel with
     * `RC5047`, so a route-scope `.error()` can notify the recipient and
     * re-ask.
     */
    ttl?: Duration;
    /**
     * Anything the resuming route needs to decide who may resume, or that an
     * operator needs to read off the record.
     *
     * Plain JSON, persisted verbatim, and never interpreted by the framework:
     * how approvals work is the application's design. A defer site that snapshots
     * its policy here gets "policy travels with the deferral" for free, because
     * the record is what `.resume({ authorize })` reads and editing this site
     * cannot reach records already deferred.
     */
    meta?: unknown;
}

/**
 * The record, as the resume route's `authorize` hook sees it.
 *
 * Deliberately no access to the deferred body. The hook runs BEFORE the
 * resuming principal has been authorized and before the record's own
 * lifecycle is disclosed, so a body-reading hook would put the deferred
 * payload in front of exactly the party the check exists to reject.
 */
interface DeferralRecordView {
    /** Deferral identity, the same value the acknowledgment carried. */
    readonly id: string;
    /**
     * Whatever the deferring step attached at deferral.
     *
     * The framework never reads it: this is where the deferral carries the
     * application's own policy inputs. A defer site that snapshots its policy
     * here gets "policy travels with the deferral" for free, because the record
     * is what the hook reads and editing the site cannot reach it.
     *
     * On the agent surface a tool handler supplies it, which means the MODEL
     * influenced it, and the model has read whatever untrusted tool output is
     * in its thread. Treat it as what the defer site chose, not as a fact the
     * framework vouches for.
     */
    readonly meta?: unknown;
    /** Route the deferred exchange belongs to. Not the resume ingress route. */
    readonly routeId: string;
    readonly deferredAt: Date;
    readonly expiresAt?: Date;
}
/**
 * What a `.resume({ authorize })` hook is handed.
 *
 * The two principals are not the same kind of thing, and the types say so.
 * `principal` was verified live by this ingress route's own
 * `.authenticate()`. `deferred` came back out of the store, so it is marked
 * restored (`auth/restored.ts`) and `authorize()` refuses it anywhere it is
 * offered as a credential; here it is reference data, which is what makes a
 * "not the requester" comparison expressible at all.
 */
interface ResumeAuthorizerInput {
    /** Who is resuming, verified live by this route. Anonymous when it verified nobody. */
    readonly principal: Principal | undefined;
    /** Who deferred the exchange, restored from storage. Never a credential. */
    readonly deferred: Principal | undefined;
    /**
     * The submission, exactly as it arrived.
     *
     * Raw at hook time: `schema` validation runs only once the hook has
     * passed, so a hook that refuses a submission spends nothing and a
     * malformed one never reaches the validator. A hook that reads into this
     * is reading unvalidated input and should narrow it itself.
     */
    readonly payload: unknown;
    readonly record: DeferralRecordView;
}
/**
 * Decides whether this principal may resume this deferral.
 *
 * The framework has no opinion about what makes a resuming principal
 * legitimate: it guarantees that the decision happens before the single-use
 * claim is spent and that a "no" costs the rightful principal nothing. What
 * "no" means is this function's business.
 *
 * Returning false, throwing, and failing to settle before the route stops
 * or its `.timeout()` fires are one refusal on the wire; the log
 * distinguishes them.
 */
type ResumeAuthorizer = (input: ResumeAuthorizerInput) => boolean | Promise<boolean>;

/**
 * What `.resume()`'s mapping function produces: which deferral to revive,
 * and the payload to revive it with.
 *
 * The split is the boundary between the two halves of a resume. The mapping
 * function owns SHAPE (find the token in a mail reply, lift an approval out
 * of a chat webhook), because only the ingress route knows what its
 * transport looks like. Revival owns VALIDATION, because only the
 * deferral knows the schema the deferring step declared.
 */
interface ResumeRequest {
    /** The signed token minted when the exchange deferred. */
    token: string;
    /** The submitted payload, validated against the deferring step's `schema`. */
    result: unknown;
    /**
     * Who resumed it. Defaults to the ingress exchange's own principal, which
     * is the value worth recording: it was verified live on the route that
     * accepted the submission, unlike anything read back out of the store.
     * Set it explicitly only when the resuming principal is not the caller
     * (an ops tool resuming on someone's behalf).
     */
    resumedBy?: PrincipalRef;
}
/**
 * What the resume DOOR contributes, as opposed to what its mapper produced.
 *
 * Kept separate from {@link ResumeRequest} deliberately. The mapper is user
 * code shaping a transport payload, and a payload is exactly what an
 * attacker controls; letting it name the resuming principal or supply the
 * hook would let the untrusted half of an ingress choose what the trusted
 * half checks.
 *
 * @internal
 */
interface ResumeDoor {
    /** The door's own authorization policy, when it declares one. */
    readonly authorize?: ResumeAuthorizer;
    /** The principal this ingress route verified live, if any. */
    readonly principal?: Principal;
    /** The ingress step's abort signal, which is what bounds an async hook. */
    readonly signal?: AbortSignal;
}
/**
 * What `.resume()` puts in the ingress route's body once revival settles.
 *
 * The ingress route continues after this, which is what lets it reply on
 * the caller's own channel ("thanks, the payout is on its way"). It therefore
 * reports how execution two ended rather than just that the token was
 * accepted.
 */
interface ResumeAcknowledgment {
    /**
     * `"resumed"` when this call revived the exchange; `"duplicate"` when the
     * deferral had already been resumed and this is the cached result of that
     * first revival. A duplicate re-runs nothing.
     */
    readonly status: "resumed" | "duplicate";
    readonly deferralId: string;
    /** Route the revived exchange belongs to. Not the ingress route. */
    readonly routeId: string;
    /**
     * How execution two ended.
     *
     * Named for the run rather than called an outcome, because
     * {@link Deferral.outcome} is how the DEFERRAL ended (resumed, expired,
     * denied) and the two would otherwise share a word while meaning
     * different things on adjacent types.
     */
    readonly continuation: SerializedOutcome;
}
/**
 * Revive a deferred exchange and run its continuation to completion.
 *
 * The order of checks is the security contract, and it is ordered rather
 * than merely "pre-claim" because the window before the claim is NOT inert:
 * the deadline arm and the continuation arm each take a compare-and-swap
 * that settles the record and drives the deferred route's error channel,
 * which in practice sends the approver a message. A credential that has no
 * business here must be refused before it can reach either, or the wrong
 * holder can burn the rightful principal's claim and drive an outbound
 * notification with it.
 *
 * 1. The token verifies (`RC5041`) and the deferral exists (`RC5046`).
 * 2. The credential was minted for THIS call (`RC5055`), read from the
 *    record alone.
 * 3. The route's own `authorize` hook accepts the principal (`RC5056`), if
 *    it declared one. This is where an application's policy runs; the
 *    framework has none of its own.
 * 4. Only now the lifecycle: a duplicate gets the cached continuation result
 *    rather than a second execution, an expired record `RC5047`, a denied
 *    one `RC5050`. Steps 2 and 3 sit above this deliberately, so a refused
 *    caller learns nothing about the record's state.
 * 5. Its route is still registered and still leads to the same continuation
 *    (`RC5048`), so an approval cannot authorize steps that were edited
 *    under it. The hash is COMPARED non-destructively; only a mismatch
 *    reached by a caller steps 2 and 3 already accepted may settle it.
 * 6. The payload satisfies the deferring step's `schema` (`RC5049`, in
 *    the ingress route only), and the compare-and-swap out of `deferred`
 *    is won here and not by a concurrent resume or the expiry sweeper.
 *
 * Every failure throws in the ingress route. A failure that leaves the
 * approver STRANDED (an expiry, a changed continuation, a denied
 * deferral) additionally re-enters the deferred route's error channel,
 * because only that route can notify and re-ask. A rejected payload
 * (`RC5049`) deliberately does not: it is a per-request input error rather
 * than a change in the world, the deferral stays resumable, and routing
 * it through the deferred route would let any token holder drive that
 * route's re-ask path with junk. The two authorization refusals are the
 * same: they leave the record exactly as they found it.
 *
 * @param context - The context reviving the exchange (the ingress route's)
 * @param request - Token plus submitted payload, as the mapper produced them
 * @param door - What the ingress route itself declares and verified
 * @returns The acknowledgment for the ingress route's body
 *
 * @internal
 */
declare function reviveDeferral(context: CraftContext, request: ResumeRequest, door?: ResumeDoor): Promise<ResumeAcknowledgment>;

/**
 * Maps the ingress exchange to the deferral it resumes.
 *
 * The preferred form of `.resume()`, because the ingress transport decides
 * where the token and the payload actually live: a token in a mail subject
 * line and a verdict in the first line of the reply, a chat webhook's
 * button payload, an ops CLI's flags.
 *
 * @template T - Body type of the ingress exchange
 */
type ResumeMapper<T = unknown> = (exchange: Exchange<T>, ctx?: {
    readonly signal?: AbortSignal;
}) => ResumeRequest | Promise<ResumeRequest>;
/**
 * Options for `.resume()`.
 */
interface ResumeOptions {
    /**
     * Decides whether the principal presenting this token may resume the
     * deferral it names.
     *
     * The framework has no model of what makes a resuming principal
     * legitimate, so it does not ship one. What it guarantees is the part an
     * application cannot build from outside: this runs BEFORE the store's
     * compare-and-swap, so a "no" never spends the rightful principal's
     * single-use link, and before the record's lifecycle is disclosed, so a
     * refused caller learns nothing about it.
     *
     * Receives the live principal (whatever this route's `.authenticate()`
     * resolved, or undefined when it resolved nobody), the deferred principal
     * restored from storage, the raw submitted payload, and the record's
     * context, including the `meta` the defer site attached. Never the
     * deferred body.
     *
     * Omitted, the door is bearer: any holder of a valid token may resume.
     * That is the historical behaviour and it stays the default, so securing
     * a resume ingress is a thing you do, not a thing you inherit.
     */
    authorize?: ResumeAuthorizer;
}

/**
 * Step-scope `.error()` handler. Wraps a single step. On wrapped-step
 * success the pipeline continues unchanged; on wrapped-step failure
 * the user-supplied handler runs, its return value replaces
 * `exchange.body`, and the pipeline continues with the next step.
 *
 * Mirrors the route-level `errorHandler` semantics (`(err, exchange,
 * forward) => unknown`), but bound to one step instead of the whole
 * pipeline. The handler receives the same `forward` callable as the
 * route-level handler, so a step-scope handler can delegate recovery
 * to a direct route the same way:
 *
 * ```ts
 * .error((err, ex, forward) => forward('errors.dlq', ex.body))
 * .to(http({ url: 'https://flaky.api/x' }))
 * ```
 *
 * If the handler itself throws, the wrapper rethrows so the route's
 * outer catch in `runPipeline` fires the route-level handler when one is
 * defined, or the default `route:error` / `context:error` /
 * `route:exchange:failed` path otherwise. The route is NOT stopped.
 *
 * Emits scope-aware lifecycle events:
 * - `route:error-handler:invoked`  ({ scope: "step", stepLabel })
 * - `route:error-handler:recovered` on handler success
 * - `route:error-handler:failed`    on handler throw (rethrown)
 */
declare class ErrorWrapperStep<T extends Adapter = Adapter> extends WrapperStep<T> {
    private readonly handler;
    constructor(inner: Step<T>, handler: ErrorHandler);
    protected describeOptions(): unknown;
    protected runInner(exchange: Exchange, ctx: StepContext): Promise<StepOutcome>;
}

/**
 * Step-scope `.delay()` wrapper. Waits a fixed time, then runs the
 * wrapped step. Pass-through: the exchange is unchanged by the wait.
 *
 * The wait is tied to the route's INTAKE signal: when shutdown begins
 * mid-wait, the remaining wait is skipped and the wrapped step still
 * runs, so no exchange is silently dropped by a shutdown. The
 * `route:delay:stopped` event carries `cancelled: true` in that case.
 * Intake rather than execution because releasing early does not change
 * what the exchange does, only when: sitting out the timer would make a
 * graceful drain wait for a delay that buys nothing once no new work is
 * arriving.
 *
 * Step scope only: there is no route-scope form. A route-scope delay
 * would be equivalent to a delay before the first step, so the
 * builder does not stage one (see `.standards/resilience-wrappers.md`
 * and the pre-from filter chain, which reserves no slot for delay).
 *
 * Emits scope-aware lifecycle events:
 * - `route:delay:started` when the wait begins.
 * - `route:delay:stopped` when the wait ends (elapsed, cancelled flag).
 */
declare class DelayWrapperStep<T extends Adapter = Adapter> extends WrapperStep<T> {
    #private;
    constructor(inner: Step<T>, duration: Duration);
    protected describeOptions(): unknown;
    protected runInner(exchange: Exchange, ctx: StepContext): Promise<StepOutcome>;
}

/**
 * Pino-compatible log levels for LogAdapter.
 */
type LogLevel = "trace" | "debug" | "info" | "warn" | "error" | "fatal";
/**
 * Options for LogAdapter.
 */
interface LogOptions {
    /** Log level to use (default: "info"). */
    level?: LogLevel;
}

/**
 * Creates a logging destination that logs each exchange (or a formatted value) via the exchange logger.
 *
 * @template T - Body type of the exchange
 * @param formatter - Optional function (exchange) => value to log; default logs id, body, headers
 * @param options - Optional `level` (default "info")
 * @returns A Destination usable with `.to(log())` or `.tap(log())`
 *
 * @example
 * ```typescript
 * .to(log())
 * .to(log((ex) => ({ id: ex.id, body: ex.body })))
 * .to(log(undefined, { level: 'debug' }))
 * ```
 */
declare function log<T = unknown>(formatter?: (exchange: Exchange<T>) => unknown, options?: LogOptions): Destination<T>;
/**
 * Same as `log()` but with level fixed to `"debug"`. Useful for verbose pipelines.
 *
 * @template T - Body type of the exchange
 * @param formatter - Optional (exchange) => value to log
 * @param options - Optional config (level is always "debug")
 * @returns A Destination that logs at debug level
 */
declare function debug<T = unknown>(formatter?: (exchange: Exchange<T>) => unknown, options?: Omit<LogOptions, "level">): Destination<T>;

/**
 * DSL registration system for RouteBuilder sugar methods.
 *
 * Built-in sugar (.log, .debug, .map, .schema) is registered at module
 * scope so it is available as soon as anything is imported from the
 * package. External packages follow the same pattern: import their
 * index, and their sugar is registered automatically.
 */

/**
 * Primitive step kinds. Used as documentation in DslRegistration to
 * indicate which core step the sugar delegates to. Not enforced at
 * runtime since the factory creates the step directly.
 */
type PrimitiveKind = "process" | "transform" | "tap" | "filter" | "validate";
/**
 * Registration descriptor for a DSL sugar method.
 */
interface DslRegistration {
    /** The core primitive step kind this DSL method delegates to. */
    kind: PrimitiveKind;
    /** Display label shown in traces, logs, and step events. */
    label: string;
    /** Factory that receives the user's call-site arguments and returns a Step. */
    factory: (...args: any[]) => Step<Adapter>;
}
/**
 * Register a sugar method on `StepBuilderBase` that delegates to a core
 * primitive step type. The method is added to the shared base prototype
 * so it is available on both `RouteBuilder` and `PathBuilder` (and any
 * future framework-owned subclass).
 *
 * TypeScript types for the new method must be provided separately via
 * module augmentation. Augment `StepBuilderBase<S extends BuilderState>`
 * once (the type parameter list must match the declaration exactly) and
 * both subclasses inherit the method via class-interface inheritance.
 * Type-preserving sugar should return `this`; type-changing sugar should
 * use `Retyped<this, SetBody<S, NewBody>>` so the concrete subclass is
 * preserved across the chain and any future `BuilderState` fields flow
 * through untouched. `StepBuilderBase`, `BuilderState`, `SetBody`, and
 * `Retyped` are exposed as type-only re-exports from the package entry
 * for exactly this purpose.
 *
 * @param name - Method name to add to the shared base prototype
 * @param registration - Kind, label, and factory for the sugar method
 * @throws If a method with the given name already exists on the base
 *
 * @example
 * ```ts
 * registerDsl("myStep", {
 *   kind: "tap",
 *   label: "myStep",
 *   factory: (opts) => new TapStep(myAdapter(opts)),
 * });
 *
 * declare module "@routecraft/routecraft" {
 *   interface StepBuilderBase<S extends BuilderState> {
 *     // Type-preserving: returns `this` (resolves to the concrete subclass)
 *     myStep(opts: MyOpts): this;
 *
 *     // Type-changing variant would look like:
 *     // myMap<Return>(
 *     //   fn: (src: S["body"]) => Return,
 *     // ): Retyped<this, SetBody<S, Return>>;
 *   }
 * }
 * ```
 */
declare function registerDsl(name: string, registration: DslRegistration): void;
declare module "@routecraft/routecraft" {
    interface StepBuilderBase<S extends BuilderState> {
        /**
         * Log the current exchange at info level. Type-preserving tap.
         *
         * @param formatter - Optional function to format the log output
         * @param options - Optional log options (level defaults to "info")
         */
        log(formatter?: (exchange: Exchange<S["body"]>) => unknown, options?: LogOptions): this;
        /**
         * Log the current exchange at debug level. Type-preserving tap.
         *
         * @param formatter - Optional function to format the log output
         * @param options - Optional log options (level is always "debug")
         */
        debug(formatter?: (exchange: Exchange<S["body"]>) => unknown, options?: Omit<LogOptions, "level">): this;
        /**
         * Map fields from the current data to create a new object. Sugar
         * for `.transform(mapper({...}))`.
         *
         * @template Return - The resulting type after mapping
         * @param fieldMappings - Object mapping output field names to extractor functions
         * @example
         * ```ts
         * .map<DbUser>({
         *   id: (apiUser) => apiUser.userId,
         *   name: (apiUser) => apiUser.fullName,
         * })
         * ```
         */
        map<Return>(fieldMappings: {
            [K in keyof Return]: (src: S["body"]) => Return[K];
        }): Retyped<this, SetBody<S, Return>>;
        /**
         * Validate the exchange body against a Standard Schema. Sugar for
         * `.validate(schema(standardSchema))`. On failure throws RC5002.
         *
         * @param standardSchema - Any Standard Schema v1 (Zod, Valibot, ArkType, etc.)
         * @example
         * ```ts
         * import { z } from "zod";
         * craft()
         *   .from(source)
         *   .schema(z.object({ name: z.string() }))
         *   .to(dest)
         * ```
         */
        schema<Schema extends StandardSchemaV1>(standardSchema: Schema): Retyped<this, SetBody<S, StandardSchemaV1.InferOutput<Schema>>>;
        /**
         * Defer the exchange durably and exit the pipeline, to be resumed later
         * at the next step.
         *
         * This run ends here and replies immediately with the `Deferred`
         * acknowledgment, because a durable defer cannot hold a caller: the
         * resume payload arrives in hours or days and the process will be
         * restarted first. Nothing is scheduled, no worker waits, and the route
         * stays live for every other exchange. The route's real output flows to
         * its destinations on execution two, when `.resume()` revives the
         * exchange with the payload.
         *
         * The body is unchanged across the deferral, so a branch that defers
         * rejoins the main flow with the contract it left on. The payload
         * arrives beside it, on `ex.deferral.result`, typed by `schema`.
         *
         * @param options - `schema` (what a valid resume payload looks like), a
         *   `ttl` after which the deferral stops being resumable, and `meta`:
         *   anything the resuming route's `.resume({ authorize })` hook needs to
         *   decide who may resume
         * @example
         * ```ts
         * craft()
         *   .id("payout")
         *   .input({ body: PayoutRequest })
         *   .from(http({ path: "/payouts", method: "POST" }))
         *   .choice(
         *     when((ex) => ex.body.amountCents >= 50_000, (b) =>
         *       b
         *         .tap(direct("notify-approver"))
         *         .defer({ schema: Approval, ttl: "72h" })
         *         .filter((ex) =>
         *           ex.deferral.result.approved
         *             ? true
         *             : { reason: `rejected by ${ex.deferral.resumedBy?.subject}` },
         *         ),
         *     ),
         *   )
         *   .to(payouts())
         * ```
         */
        defer<Schema extends StandardSchemaV1>(options?: DeferOptions<Schema>): Retyped<this, SetDeferral<S, StandardSchemaV1.InferOutput<Schema>>>;
        /**
         * Revive a deferred exchange and run its continuation.
         *
         * Addresses an EXCHANGE by signed token, not a route by name: any route
         * ending in `.resume()` is a resume ingress, whether it is fed by an
         * HTTP webhook, a mail-reply parser, or an ops CLI. The original source
         * takes no part in execution two, which is what lets a mail-born
         * exchange be continued by a chat-born resume.
         *
         * The mapping function owns SHAPE (find the token, build the payload);
         * validation against the deferring step's `schema` happens at revival,
         * because only the deferral knows that schema. The bare form expects
         * the body to already be `{ token, result }`.
         *
         * Authorizing the resuming principal belongs on this route, through the
         * `authorize` option: the token proves the deployment minted it, not
         * that its holder may resume. The hook runs before the store's claim
         * and before the record's lifecycle is disclosed, so a refusal costs
         * the rightful principal nothing and tells a refused caller nothing.
         * Whoever this route authenticated is recorded as `resumedBy`. A door
         * exposed publicly wants a `.throttle()` in front of it.
         *
         * The revived route runs to completion before this step continues, so
         * the acknowledgment placed in the body reports how execution two
         * ended, and the ingress route can reply on the caller's own channel.
         * A duplicate resume returns the first one's cached continuation result
         * without re-running anything.
         *
         * @param map - Maps the ingress exchange to `{ token, result }`
         * @param options - `authorize`, deciding who may resume. Omitted, the
         *   door is bearer: any holder of a valid token may resume.
         * @example
         * ```ts
         * craft()
         *   .id("approval-replies")
         *   .from(mail("INBOX"))
         *   .authenticate(mailPrincipal)
         *   .resume((ex) => ({
         *     token: tokenFrom(ex.headers["routecraft.mail.subject"]),
         *     result: { approved: /^yes/i.test(ex.body.text ?? "") },
         *   }))
         *   .to(log())
         * ```
         */
        resume(map?: (exchange: ExchangeOf<S>, ctx?: {
            readonly signal?: AbortSignal;
        }) => ReturnType<ResumeMapper<S["body"]>>, options?: ResumeOptions): Retyped<this, SetBody<S, ResumeAcknowledgment>>;
        resume(options: ResumeOptions): Retyped<this, SetBody<S, ResumeAcknowledgment>>;
    }
}

/**
 * Run Standard Schema validation against a value. Returns the validated
 * value on success (schemas can legitimately transform to `undefined`,
 * so presence of the `value` key is what decides success, not truthiness)
 * or a human-readable message on failure.
 *
 * Exported for adapter and plugin authors who validate at a protocol
 * boundary and need the failure as a message to hand back over the wire
 * rather than as a thrown error.
 *
 * The validated value carries the schema's output type, which for a
 * transforming schema is not the type that went in. `issues` accompanies
 * `message` so a caller can build a structured rejection (a JSON-RPC
 * `error.data`, an HTTP 422 field map) instead of only a sentence.
 *
 * Standard Schema allows `validate()` to return a thenable rather than a
 * real `Promise`, so awaiting one runs schema-author `then` code on this
 * path: a schema that never settles hangs the validation instead of
 * silently passing, which is the safer of the two failures. Nothing bounds
 * that wait. `.input()` is position #4 of the pre-from chain and `.timeout()`
 * is #8, so a route timeout sits below validation and cannot reclaim it.
 *
 * `schema` is assumed to carry a callable `~standard.validate`; this helper
 * dereferences it unguarded, so a caller holding a value from configuration
 * checks that first and chooses its own refusal.
 *
 * @param schema - The Standard Schema to validate with
 * @param value - The value to validate
 * @returns `{ ok: true, value }` with the validated (possibly transformed)
 *   value, or `{ ok: false, message, issues }` with the failure both
 *   formatted and raw. A schema that returns something other than a result
 *   record fails the same way, with an empty `issues` and a message naming
 *   what came back
 *
 * @example
 * ```ts
 * const result = await validateAgainst(schema, exchange.body);
 * if (!result.ok) return { isError: true, message: result.message };
 * ```
 */
declare function validateAgainst<S extends StandardSchemaV1>(schema: S, value: unknown): Promise<{
    ok: true;
    value: StandardSchemaV1.InferOutput<S>;
} | {
    ok: false;
    message: string;
    issues: readonly StandardSchemaV1.Issue[];
}>;
/**
 * Machine-readable detail attached to an `RC5065` error's cause: which part
 * of the input failed the route's `.input()` schema, and the schema's own
 * issues. Read it off `error.cause` through {@link isInputValidationFailure}
 * to build a structured rejection instead of parsing the message:
 *
 * ```ts
 * if (isInputValidationFailure(err.cause)) {
 *   for (const issue of err.cause.invalid.issues) report(issue.path, issue.message)
 * }
 * ```
 *
 * The http doors (the `http()` source and the ops dispatch mount) send
 * `in` and each issue's path and message to the caller, so issue messages
 * are client-facing: a schema author's custom message reaches the wire
 * verbatim.
 *
 * In-process only, like `InsufficientAuthority`: `RoutecraftError.toJSON()`
 * serialises the cause's message and stack, not its own properties.
 */
interface InputValidationFailure extends Error {
    invalid: {
        /** Which part of the input the schema refused. */
        in: "body" | "headers";
        /** The schema's issues, as it returned them. */
        issues: readonly StandardSchemaV1.Issue[];
        /**
         * The route whose `.input()` refused. A route calling another through
         * `direct()` receives the callee's RC5065 as its own step failure, and
         * what the callee refused was the caller route's output, not input
         * anyone outside supplied.
         */
        routeId: string;
    };
}
/**
 * Whether `value` (typically an RC5065 error's `cause`) carries the
 * {@link InputValidationFailure} detail.
 *
 * @param value - Any value, usually `error.cause`
 * @returns `true` when the value is an Error carrying a well-formed `invalid` detail
 */
declare function isInputValidationFailure(value: unknown): value is InputValidationFailure;
/**
 * Machine-readable detail attached to the cause of an error raised because a
 * result broke its declared output schema: which part failed, the schema's
 * own issues, and the route or tool. Read it off `error.cause` through
 * {@link isOutputValidationFailure}.
 *
 * Two checks attach it: a route's `.output()` (`RC5002`) and the MCP
 * server's check of a tool result against the `outputSchema` it advertised
 * (`AI2001`, for a tool the pipeline did not validate). `RC5002` also covers
 * a mid-pipeline `.validate()` and an empty aggregation, whose causes carry
 * no such detail, so its presence is what tells a door the result broke a
 * declared contract. The MCP server sends the body issues to the caller,
 * because the tool advertised that schema.
 *
 * In-process only, like {@link InputValidationFailure}.
 */
interface OutputValidationFailure extends Error {
    invalidOutput: {
        /** Which part of the result the schema refused. */
        in: "body" | "headers";
        /** The schema's issues, as it returned them. */
        issues: readonly StandardSchemaV1.Issue[];
        /**
         * The route whose `.output()` refused, or the tool whose advertised
         * schema refused. A route calling another through `direct()` receives
         * the callee's RC5002 as its own step failure.
         */
        routeId: string;
    };
}
/**
 * Whether `value` (typically an RC5002 error's `cause`) carries the
 * {@link OutputValidationFailure} detail.
 *
 * @param value - Any value, usually `error.cause`
 * @returns `true` when the value is an Error carrying a well-formed `invalidOutput` detail
 */
declare function isOutputValidationFailure(value: unknown): value is OutputValidationFailure;

/** One schema issue as a door shows it to a caller: where, and what. */
interface WireIssue {
    /** Dot-joined issue path, absent for an issue about the whole value. */
    path?: string;
    message: string;
}
/**
 * Schema issues bounded for the wire: the first {@link MAX_WIRE_ISSUES}, and
 * how many more there were.
 */
interface WireIssues {
    issues: WireIssue[];
    /** Issues left out of `issues`; `0` when all of them fit. */
    omitted: number;
}
/**
 * Reduce Standard Schema issues to what a door may put on the wire: each
 * issue's path and message, at most {@link MAX_WIRE_ISSUES} of them, each
 * clipped to {@link MAX_WIRE_ISSUE_TEXT} characters.
 *
 * The message is the schema's own text, so a schema author's custom message
 * reaches the caller verbatim. A non-string message becomes `"invalid"`.
 *
 * @param issues - The issues a schema returned
 * @returns The first issues as path and message, and the count left out
 */
declare function wireIssues(issues: readonly StandardSchemaV1.Issue[]): WireIssues;
/**
 * A route failure the caller caused, classified by what the caller can do
 * about it. Each door renders it in its own protocol: an http status and
 * body, an MCP tool error, and so on.
 *
 * - `input`: the route's `.input()` schema refused what the caller sent.
 *   Carries the part and the issues, never the error message, which names
 *   the route.
 * - `unauthenticated`: the route needs an identity and the caller presented
 *   none.
 * - `expired`: the caller's credential expired while the route ran.
 * - `insufficient_permissions`: the identity is not permitted, as itself or
 *   through the delegation it arrived by. One class for four codes, because
 *   the caller's remedy is the same and naming the check that failed would
 *   tell a prober which part of the policy it tripped.
 * - `insufficient_scope`: the credential lacks a scope. `scopes` lists the
 *   missing ones, or with `anyOf` the whole accepted set, of which one
 *   suffices.
 */
type CallerRefusal = ({
    kind: "input";
    in: "body" | "headers";
} & WireIssues) | {
    kind: "unauthenticated";
} | {
    kind: "expired";
} | {
    kind: "insufficient_permissions";
} | {
    kind: "insufficient_scope";
    scopes: string[];
    anyOf: boolean;
};
/** What a door knows about the call whose route failed. */
interface CallerRefusalOrigin {
    /**
     * The route the door dispatched. A failure raised by any other route
     * reached this one through a `direct()` call, and what that route refused
     * was this route's doing rather than the caller's.
     */
    routeId: string;
    /**
     * The principal the door put on the exchange, by reference, or `undefined`
     * when it put none. A refusal maps only when it is this exact principal
     * that `authorize()` refused.
     */
    principal: Principal | undefined;
    /**
     * Whether presenting a credential could have changed the outcome: the
     * door consulted a validator and the call went without a principal.
     *
     * Decides whether a missing principal (`RC5012`) is the caller's to fix.
     * When it is not, the door never reads a credential for this route, so
     * telling the caller to present one would send it after something that
     * changes nothing, and the failure stays the route's.
     */
    credentialCouldHelp?: boolean;
}
/**
 * Classify a route failure the caller caused, or return `undefined` for one
 * the instance owns.
 *
 * One classification for every door that runs a route on a caller's behalf
 * (the `http()` source, the ops dispatch mount, the MCP server), so the same
 * refusal cannot be the caller's on one door and the instance's on another.
 * A door answers everything this returns `undefined` for with the error
 * code alone: an error message routinely interpolates the cause, and the
 * cause of a route failure is whatever its steps threw, hostnames, file
 * paths and upstream response text included.
 *
 * Attribution is by origin, never by code:
 *
 * - `RC5065` maps only when it carries the `InputValidationFailure` detail
 *   for the dispatched route. One without it was thrown by something other
 *   than `.input()`, and one naming another route came up through
 *   `direct()`, so neither is the caller's.
 * - The authorization codes map only when {@link isAuthorizationRefusal}
 *   says `authorize()` raised them on the dispatched route about the
 *   principal the door admitted. The same codes come out of adapters for an
 *   upstream login refused, and a check of an identity the pipeline swapped
 *   in (`.authenticate()`, a delegation) refused the instance; both stay the
 *   instance's, which also keeps an internal identity's requirements off the
 *   wire. `RC5012` additionally needs `credentialCouldHelp`. `RC5023` (a
 *   self-asserted principal) and `RC5043` (one restored from a deferral) are
 *   never mapped: a door brands every principal it verifies, so either one
 *   was put there by the route.
 *
 * @param error - What the route threw
 * @param origin - The dispatched route and the principal the door admitted
 * @returns The refusal to render, or `undefined` when the failure is the instance's
 */
declare function callerRefusalOf(error: unknown, origin: CallerRefusalOrigin): CallerRefusal | undefined;

/**
 * Reading the non-standard `~standard.jsonSchema` extension.
 *
 * Standard Schema itself defines no JSON Schema export, so everything here
 * is opportunistic: Zod, ArkType and the AI SDK bridge expose the extension,
 * and a library without it yields nothing while nothing else changes.
 *
 * Two callers share it for different reasons. The deferral descriptor
 * (`deferral/hash.ts`) folds the rendering into `continuationHash` so a
 * schema edited under a deferred exchange is caught. The ops management API
 * publishes it so an operator can see what a route accepts without reading
 * the source.
 *
 * The dialect is a required argument rather than a default here, because
 * one of those callers hashes what comes back: a default changed in this
 * module would change every stored digest without a line of deferral code
 * moving. Each caller pins its own constant and passes it.
 *
 * The module also holds `isStandardSchema`, which reads the same bag for a
 * callable `validate` rather than for the JSON Schema arms.
 */

/**
 * Whether a value is a Standard Schema carrying a callable validator.
 *
 * The check every validation boundary has to make before handing a
 * caller-supplied value to `validateAgainst`, which dereferences
 * `~standard.validate` without guarding. Seven sites hand-rolled the same
 * index cast and predicate before this existed (#575).
 *
 * Deliberately only the predicate: the refusal stays with the caller,
 * because the error code and message differ per boundary on purpose. A
 * plugin option validator throws a plain `Error` for its own message, the
 * fn registry throws `RC5003` naming the fn, and the structured-text
 * fallback declines to a `undefined` rather than throwing at all.
 *
 * @param value - Any value, typically arriving from user configuration
 * @returns Whether `value["~standard"].validate` is callable. That is all it
 *   proves: `version` and `vendor` are spec-required but not checked, and
 *   the local `StandardExtension` treats both as optional because schemas
 *   omitting them reach the framework in practice. A caller that reads
 *   either should still guard it.
 *
 * @example
 * ```ts
 * if (!isStandardSchema(schema)) {
 *   throw new Error("options.schema must be a Standard Schema");
 * }
 * const result = await validateAgainst(schema, value);
 * ```
 */
declare function isStandardSchema(value: unknown): value is StandardSchemaV1;

/**
 * Reject options that no longer exist, so a stale name fails at build
 * rather than being ignored.
 *
 * TypeScript already refuses an unknown key, but only on an object literal.
 * A plain-JS caller, an `as any`, or an options object assembled elsewhere
 * and spread in gets no such check, and the option is simply dropped. A
 * timer that quietly keeps its 1000ms default because `intervalMs` no
 * longer means anything is a far worse failure than one that refuses to
 * build, so every removal is named here.
 *
 * Two kinds of staleness are caught. Any key ending in `Ms` is stale by
 * construction: authored time options take a {@link Duration} and carry no
 * unit suffix, so `Ms` on an authored option can only be a pre-0.7 name.
 * Anything else removed for its own reasons is listed per call site.
 *
 * @param options - The user-supplied options object, if any
 * @param surface - Call shape quoted in the error, e.g. `timer`
 * @param removed - Removed key mapped to the sentence saying what to write instead
 * @throws RC5003 naming the stale option and its replacement
 *
 * @internal
 */
declare function rejectStaleOptions(options: unknown, surface: string, removed?: Readonly<Record<string, string>>): void;

/**
 * Composing cancellation scopes.
 *
 * A step can be cancelled by more than one owner: the route stopping, an
 * enclosing `.timeout()` expiring, a client disconnecting, a credential
 * reaching its expiry. Each site that needs the union was deciding three
 * things for itself, and the sites had already drifted on the third: filter
 * out the absent signals, avoid allocating for the single-signal case, and
 * answer what "no owner at all" means. This is the one answer.
 */
/**
 * Compose cancellation scopes into one signal.
 *
 * Absent signals are ignored, so a caller passes its optional owners
 * positionally without pre-filtering. With no present signal the result
 * never aborts, which is the honest reading of "nothing can cancel this"
 * and is what every call site previously spelled differently.
 *
 * @param signals - Cancellation owners, any of which may be absent
 * @returns The union: aborts when the first present signal aborts
 */
declare function anySignal(...signals: readonly (AbortSignal | undefined)[]): AbortSignal;

/**
 * Register SIGINT/SIGTERM handlers for graceful two-stage shutdown.
 *
 * **First signal** (Ctrl+C): closes intake so sources stop producing, lets
 * in-flight exchanges run to their natural end, runs plugin teardown, then
 * exits 0. In-flight work is NOT cancelled here. Repeated SIGINT/SIGTERM
 * signals are ignored while this graceful shutdown is in progress.
 *
 * **Dedicated force signals** (Ctrl+Backslash/SIGQUIT or Ctrl+Break/SIGBREAK):
 * force an immediate exit for when graceful shutdown is stuck or taking too
 * long. They force exit even when graceful shutdown has not started.
 *
 * Stage one is bounded by `shutdown: { timeout }` even without a force signal,
 * which is what an orchestrator needs: it sends one SIGTERM and then SIGKILLs,
 * so there is no dedicated force signal coming. On that deadline in-flight
 * execution is abandoned and the process exits 1, so exit-code-sensitive
 * tooling can tell a forced shutdown from a clean one.
 *
 * @param context - A built `CraftContext` to shut down on signal
 *
 * @example
 * ```typescript
 * const { context } = await builder.build();
 * shutdownHandler(context);
 * await context.start();
 * ```
 */
declare function shutdownHandler(context: CraftContext): () => void;

/**
 * Stamp an adapter instance with its factory and construction args so that
 * `testContext().override(mockAdapter(factory, ...))` can match the instance
 * back to its factory at route execution time.
 *
 * Tagging is optional: adapters that skip it can still be mocked by passing
 * the adapter class to `mockAdapter(Class, ...)` (class-based resolution).
 * Tagging is preferred for single-role factories where the factory reference
 * is what users import and think in terms of.
 *
 * @param adapter - Adapter instance returned by a factory
 * @param factory - Factory function that produced the instance (self-reference)
 * @param args - Args that were passed to the factory
 * @returns The same adapter instance (for chaining)
 */
declare function tagAdapter<A extends object>(adapter: A, factory: unknown, args: unknown[]): A;
/**
 * Build the `args` tuple passed to {@link tagAdapter} from a variadic
 * factory's parameter list, trimming trailing `undefined` entries so the
 * recorded length matches what the user actually typed at the call site.
 *
 * Use this helper from every adapter factory that forwards user args to
 * `tagAdapter`, so mock authors see a consistent `args.length` across
 * adapters (for example, `mail()`, `mcp(endpoint)` and `http({})` all
 * record a single-element tuple when only one argument was passed).
 *
 * @example
 * ```ts
 * function mcp(endpoint, options?) {
 *   return tagAdapter(new McpAdapter(...), mcp, factoryArgs(endpoint, options));
 * }
 * ```
 */
declare function factoryArgs(...args: unknown[]): unknown[];

/**
 * Dynamically load an optional peer dependency. If the package is not
 * installed, throw a Routecraft error (RC5017) that names the missing
 * package and the install command. Other failures (an installed package
 * that throws during initialisation, ESM/CJS interop bugs, native binding
 * crashes) are rethrown unchanged so the surface message is not a
 * misleading "install &lt;pkg&gt;" suggestion.
 *
 * Use this anywhere a driver is declared as an optional peer dependency,
 * not only in adapters: the deferral store and the telemetry SQLite sink
 * are neither adapters nor in an adapter directory, and both load one. Pass
 * a thunk like `() => import("croner")` so the bundler sees the literal
 * package name and can keep it external.
 *
 * @param loader - Thunk that performs the dynamic `import("...")` call.
 * @param ctx - Names used in the error message: the subsystem that wanted
 *              the package (`cron adapter`, `deferral store (sqlite)`,
 *              ...) and the missing package itself. `consumer` is used as
 *              written, so it carries its own noun.
 */
declare function loadOptionalPeer<T>(loader: () => Promise<T>, ctx: {
    consumer: string;
    packageName: string;
}): Promise<T>;

declare class SimpleConsumer implements Consumer<undefined> {
    readonly context: CraftContext;
    readonly definition: RouteDefinition;
    readonly channel: ProcessingQueue<Message>;
    readonly options: undefined;
    constructor(deps: ConsumerDeps);
    register(handler: (envelope: Message) => Promise<Exchange>): void;
}

type BatchOptions = {
    /**
     * The size of the batch.
     */
    size?: number;
    /**
     * The timeout between batches in milliseconds.
     */
    time?: number;
    /**
     * The function to merge the produced messages.
     */
    merge?: (exchanges: {
        message: unknown;
        headers?: ExchangeHeaders;
    }[]) => {
        message: unknown;
        headers?: ExchangeHeaders;
    };
};
declare class BatchConsumer implements Consumer<Required<BatchOptions>> {
    /** Messages wait in the buffer until the batch flushes. See {@link ConsumerType.buffers}. */
    static readonly buffers = true;
    readonly context: CraftContext;
    readonly definition: RouteDefinition;
    readonly channel: ProcessingQueue<Message>;
    readonly options: Required<BatchOptions>;
    constructor(deps: ConsumerDeps);
    /**
     * Register the route handler for batched delivery.
     *
     * **Principal handling.** The merged-batch path inherits whatever the
     * configured `merge` produces for headers; the default merge keeps the
     * last-write-wins value for `routecraft.auth.principal` if multiple
     * items in the batch carry one, which is rarely meaningful. Routes that
     * need per-message identity attribution should use the simple consumer
     * or attach a principal in a `.process()` step after the batch is
     * unpacked.
     *
     * The per-item parse-failure escape hatch (where a bad item is routed as
     * its own exchange instead of joining the batch) forwards the source's
     * headers verbatim, so any `routecraft.auth.principal` set by the source
     * survives into `.error()` for authorization checks.
     */
    register(handler: (envelope: Message) => Promise<Exchange>): void;
}

/**
 * Creates a source that produces one or more exchanges.
 * Use as the first step in a route with `.from(simple(...))`.
 *
 * When the producer returns (or is) an **array**, each element becomes a
 * separate exchange processed independently through the pipeline. This is
 * useful for seeding multiple messages from a single source. To pass an
 * array as the body of a single exchange, wrap it:
 * `simple({ items: [1, 2, 3] })` or use a transform after a string source.
 *
 * **Note:** If you need to emit a function itself as a value (not call it as a producer),
 * use `simple.value(myFunction)` instead of `simple(myFunction)`.
 *
 * @template T - Body type produced
 * @param producer - Static value, or function that returns T | Promise<T>
 * @returns A Source usable with `.from(simple(producer))`
 *
 * @example
 * ```typescript
 * // Single exchange with string body
 * .from(simple('hello'))
 *
 * // Two separate exchanges (one per array element)
 * .from(simple([1, 2]))
 *
 * // Single exchange with array body (wrap in object)
 * .from(simple({ items: [1, 2] }))
 *
 * // Async producer
 * .from(simple(() => fetch('/api/data').then(r => r.json())))
 *
 * // Emit a function as a value
 * .from(simple.value(myCallback))
 * ```
 */
declare function simple<T = unknown>(producer: (() => T | Promise<T>) | T): Source<T>;
declare namespace simple {
    var value: <T>(value: T) => Source<T>;
}

/**
 * Create a no-operation adapter that does nothing.
 *
 * This can be useful for testing or as a placeholder.
 *
 * @template T The type of data this adapter processes
 * @returns A Destination that discards all messages
 */
declare function noop<T = unknown>(): Destination<T>;

/**
 * Store key for the direct channel map (endpoint name -> channel instance).
 * @internal
 */
declare const ADAPTER_DIRECT_STORE: unique symbol;
/**
 * Store key for the context-level direct channel type.
 * Set via `CraftConfig.direct` to swap all direct endpoints to a custom
 * channel implementation (e.g. Kafka, Redis) instead of in-memory.
 * @internal
 */
declare const ADAPTER_DIRECT_OPTIONS: unique symbol;
declare module "@routecraft/routecraft" {
    interface StoreRegistry {
        [ADAPTER_DIRECT_STORE]: Map<string, DirectChannel<Exchange>>;
        [ADAPTER_DIRECT_OPTIONS]: Pick<DirectBaseOptions, "channelType">;
    }
}

/**
 * Creates a direct adapter for synchronous, in-process inter-route messaging.
 *
 * - **Source (for `.from()`):** Call with channel options (`channelType`,
 *   `internal`) or with no arguments. The endpoint is always the route id;
 *   discoverable metadata (title, description, input, output) lives on the
 *   route via `.title()`, `.description()`, `.input()`, `.output()`.
 *   `direct({ internal: true })` keeps the in-process endpoint and closes
 *   the external doors: not dispatchable through ops, not resolvable as an
 *   agent `directTool`; only composable from another route.
 * - **Enricher (for `.to()` / `.enrich()` / `.tap()`):** Call with a string
 *   or function naming the target route: `direct("fetch-order")` or
 *   `direct((exchange) => exchange.headers["x-endpoint"] as string)`. The
 *   call is a pull-in: the target route's response body replaces the body in
 *   `.to()` / bare `.enrich()`, feeds the aggregator in `.enrich(x, agg)`,
 *   and is discarded by `.tap()`.
 * - **Enricher with explicit input/output types:** Supply two type
 *   arguments to express a route whose response body shape differs from
 *   the caller's input shape, e.g. `direct<ChatInput, AgentResult>("agent")`.
 *   Works with both string and function endpoints. When
 *   `DirectEndpointRegistry` is populated, the endpoint string is still
 *   constrained to registered keys.
 *
 * Semantics: single consumer per endpoint (last subscriber wins), blocking
 * send (sender waits for response).
 *
 * @example
 * ```ts
 * // Source route (endpoint = route id)
 * craft()
 *   .id("ingest")
 *   .title("Ingest API")
 *   .description("Accept ingest payloads")
 *   .input({ body: mySchema })
 *   .from(direct())
 *
 * // Agent-only source (no id -> UUID endpoint, not callable from code)
 * craft()
 *   .description("Internal knowledge base lookup")
 *   .input({ body: querySchema })
 *   .from(direct())
 *
 * // Destination
 * .to(direct("ingest"))
 * .to(direct((ex) => ex.headers["x-endpoint"] as string))
 *
 * // Destination with input != output (e.g. in-process agent call)
 * .transform((b) => ({ name: b.agent, query: b.text }))
 * .enrich(direct<{ name: string; query: string }, AgentResult>("agent"))
 * ```
 */
declare function direct(options: DirectServerOptions): Source<unknown>;
declare function direct(): Source<unknown>;
declare function direct<K extends RegisteredDirectEndpoint>(endpoint: K): Enricher<ResolveBody<DirectEndpointRegistry, K>, unknown>;
declare function direct<T = unknown>(endpoint: DirectEndpoint<T>): Enricher<T, T>;
/**
 * Enricher with explicit input and output body types. Use when the
 * target route's response body shape differs from the caller's input
 * shape (e.g. an in-process agent or RPC-style call). Accepts a string
 * endpoint (constrained to registered keys when `DirectEndpointRegistry`
 * is populated) or a function endpoint resolved from the exchange.
 *
 *   actually returns a value matching `TOut`. The caller asserts the
 *   output shape. A future release may require a matching
 *   `.output({ body: schema })` on the callee and validate the response
 *   automatically; until then, treat `TOut` as a caller-side assertion
 *   rather than a framework-enforced contract.
 */
declare function direct<TIn, TOut>(endpoint: RegisteredDirectEndpoint | ((exchange: Exchange<TIn>) => string)): Enricher<TIn, TOut>;

interface TimerOptions {
    /**
     * Time between executions.
     * @default 1000
     */
    interval?: Duration;
    /**
     * Delay before the first execution.
     * @default 0
     */
    delay?: Duration;
    /**
     * Number of times to trigger before stopping
     * @default Infinity
     */
    repeatCount?: number;
    /**
     * Ensures execution happens at exact intervals (ignoring execution time)
     * @default false
     */
    fixedRate?: boolean;
    /**
     * Upper bound on a random delay added to each scheduled run, to stop many
     * instances firing in lockstep. Each wait is drawn uniformly from
     * `[0, maxJitter)`.
     * @default 0
     */
    maxJitter?: Duration;
}
/**
 * Header keys the timer source sets on every emitted exchange. Keys live
 * under the reserved `routecraft.timer.*` namespace; the value types are
 * merged into `RoutecraftHeaders` below.
 */
declare const TimerHeaders: {
    /** The exact timestamp when the timer fired, in ISO 8601 format */
    readonly TIME: "routecraft.timer.time";
    /** The timestamp when the exchange was created, in ISO 8601 format */
    readonly FIRED_TIME: "routecraft.timer.firedTime";
    /** The period in milliseconds between timer firings */
    readonly PERIOD_MS: "routecraft.timer.periodMs";
    /** The number of times the timer has fired */
    readonly COUNTER: "routecraft.timer.counter";
    /** The next timestamp when the timer will fire, in ISO 8601 format */
    readonly NEXT_RUN: "routecraft.timer.nextRun";
};
declare module "@routecraft/routecraft" {
    interface RoutecraftHeaders {
        /** The exact timestamp when the timer fired, in ISO 8601 format */
        [TimerHeaders.TIME]?: string;
        /** The timestamp when the exchange was created, in ISO 8601 format */
        [TimerHeaders.FIRED_TIME]?: string;
        /** The period in milliseconds between timer firings */
        [TimerHeaders.PERIOD_MS]?: number;
        /** The number of times the timer has fired */
        [TimerHeaders.COUNTER]?: number;
        /** The next timestamp when the timer will fire, in ISO 8601 format */
        [TimerHeaders.NEXT_RUN]?: string;
    }
}

/**
 * Creates a source that emits at a fixed interval. Body is undefined; timer
 * metadata is in exchange headers (routecraft.timer.*).
 *
 * For a wall-clock schedule ("every weekday at 09:00") use `cron()`, which
 * supports timezones.
 *
 * @param options - interval, delay, repeatCount, fixedRate, maxJitter
 * @returns A Source usable with `.from(timer(options))`
 *
 * @example
 * ```typescript
 * .from(timer({ interval: "5s", repeatCount: 10 }))
 * .from(timer({ interval: "1m", maxJitter: "5s" }))
 * ```
 */
declare function timer(options?: TimerOptions): Source<undefined>;

/**
 * Store key for merged cron adapter options.
 * Set context-level defaults (e.g., maxJitter) once and share across all
 * cron sources in the same context.
 * @internal
 */
declare const ADAPTER_CRON_OPTIONS: unique symbol;
declare module "@routecraft/routecraft" {
    interface StoreRegistry {
        [ADAPTER_CRON_OPTIONS]: Partial<CronOptions>;
    }
}

/**
 * Creates a source that emits on a cron schedule. Body is undefined; cron metadata is in exchange headers (routecraft.cron.*).
 *
 * Supports standard 5-field cron, 6-field (with seconds), and nicknames (@daily, @weekly, @hourly, @monthly, @yearly, @annually, @midnight).
 *
 * @param expression - Cron expression string
 * @param options - timezone, maxFires, maxJitter, name, protect, startAt, stopAt
 * @returns A Source usable with `.from(cron(expression, options))`
 *
 * @example
 * ```typescript
 * .from(cron("0 9 * * 1-5"))                              // weekdays at 9am
 * .from(cron("@daily", { timezone: "America/New_York" }))  // daily in EST
 * .from(cron("0 0 1 * *", { name: "monthly-report" }))    // first of each month
 * ```
 */
declare function cron(expression: CronExpression, options?: CronOptions): Source<undefined>;

/**
 * Statuses that carry a redirect.
 *
 * `304 Not Modified` is deliberately absent: it is a cache answer rather than
 * a hop, it names no `Location`, and a route asking about redirects is asking
 * about hops. The obvious hand-rolled predicate (`status >= 300 && status <
 * 400`) includes it and therefore disagrees with the adapter, which is why
 * this set is exported rather than left for every route to re-derive.
 */
declare const HTTP_REDIRECT_STATUSES: ReadonlySet<number>;
/**
 * True when a result carries a redirect the route may choose to follow.
 *
 * The predicate a `redirect: "manual"` route branches on, and the same rule
 * the adapter itself applies when deciding that a 3xx is the outcome the
 * route asked for rather than an http error. Excludes `304`, per
 * {@link HTTP_REDIRECT_STATUSES}.
 *
 * @example
 * ```typescript
 * .enrich(http({ url: (ex) => ex.body.url, redirect: "manual" }))
 * .choice(when(isRedirect, revalidateAndFollow))
 * ```
 */
declare function isRedirect(result: Pick<HttpResult, "status">): boolean;

/**
 * Create an HTTP source. Use with `.from(...)`. Requires `http: {...}` to be
 * configured on the context (typically via `defineConfig({ http: {...} })`)
 * so the plugin owns the port and the global auth check.
 *
 * @example
 * ```typescript
 * .from(http({ path: "/orders/:id", method: "GET" }))
 * .from(http({ path: "/health", method: "GET", auth: "skip" }))
 * ```
 *
 * @experimental
 */
declare function http(options: HttpServerOptions): Source<HttpRequestBody>;
/**
 * Create an HTTP client enricher (a pull-in). Use with `.enrich()`, `.to()`
 * (the result replaces the body), or `.tap()` (fire-and-forget). Supports
 * dynamic url, headers, query, and body from the exchange.
 *
 * The client shape is selected by key presence (`url`), and the operation
 * keyword enforces the category: `.from(http({ url }))` fails to compile
 * because the client has no `subscribe`.
 *
 * `responseBody: "bytes"` does NOT change this signature's result type. Name
 * the body yourself: `http<In, Uint8Array>({ url, responseBody: "bytes" })`.
 * An option value that selects the adapter's type is what Option Law 2
 * forbids, and the two ways of getting it here both fail: a bytes overload
 * with one type parameter is skipped by the two-argument form the examples
 * and templates use, which is then told its body is `Out` while the runtime
 * hands back bytes, and overloads narrow enough to refuse that also refuse
 * any options object whose mode is not a literal.
 *
 * @param options - method, url (string or (exchange) => string), optional headers, query, body, timeout, throwOnHttpError, maxBodySize, redirect, responseBody
 * @returns An Enricher whose fetch returns { status, headers, body, url }
 *
 * @example
 * ```typescript
 * .to(http({ url: 'https://api.example.com/ingest', method: 'POST', body: (ex) => ex.body }))
 * .enrich(http({ url: (ex) => `https://api.example.com/users/${ex.body.userId}` }), only((r) => r.body, 'user'))
 * .enrich(http({ url: (ex) => ex.body.mediaUrl, responseBody: 'bytes' }), only((r) => r.body, 'media'))
 * ```
 */
declare function http<T = unknown, R = unknown>(options: HttpClientOptions<T>): Enricher<T, HttpResult<R>>;

interface FileOptions {
    /**
     * File path string or function that returns the path.
     * The function form receives the exchange (send/fetch roles only; the
     * source role needs a static string because no exchange exists yet).
     */
    path: string | ((exchange: Exchange) => string);
    /**
     * Text encoding. Default: 'utf-8'
     */
    encoding?: BufferEncoding;
    /**
     * Create parent directories if they don't exist (send role only).
     * Default: false
     */
    createDirs?: boolean;
    /**
     * Send role behavior: append to the file instead of overwriting it.
     * Mutually exclusive with `delete`. Default: false (overwrite)
     */
    append?: boolean;
    /**
     * Send role behavior: delete the file instead of writing it. Idempotent:
     * an already-absent path is a no-op. The body is unchanged. Mutually
     * exclusive with `append`. Default: false
     */
    delete?: boolean;
    /**
     * When true, the source emits one exchange per line instead of the entire
     * file content. Source role only; the send/fetch roles are identical under
     * chunked. Each chunked exchange includes FILE_LINE and FILE_PATH headers.
     * Default: false
     */
    chunked?: boolean;
}
/**
 * Header keys the file source sets on chunked-mode exchanges. Keys live
 * under the reserved `routecraft.file.*` namespace; the value types are
 * merged into `RoutecraftHeaders` below.
 */
declare const FileHeaders: {
    /** The 1-based line number when reading a file in chunked mode */
    readonly LINE: "routecraft.file.line";
    /** The file path when reading a file in chunked mode */
    readonly PATH: "routecraft.file.path";
};
declare module "@routecraft/routecraft" {
    interface RoutecraftHeaders {
        /** The 1-based line number when reading a file in chunked mode */
        [FileHeaders.LINE]?: number;
        /** The file path when reading a file in chunked mode */
        [FileHeaders.PATH]?: string;
    }
}

/**
 * Combined file adapter type: all three roles on one honest type. The
 * operation keyword selects the role (`.from()` subscribes, `.to()` sends,
 * `.enrich()` fetches).
 */
type FileAdapter = Source<string> & Destination<unknown> & Enricher<unknown, string> & {
    readonly adapterId: string;
};
/**
 * Creates a file adapter for plain text files. One factory, one type; the
 * POSITION in the route selects the role:
 *
 * - **`.from(file({ path }))`** reads the file and emits its content
 *   (`chunked: true` emits one exchange per line with FILE_LINE / FILE_PATH
 *   headers). The source role needs a static string path.
 * - **`.to(file({ path }))`** writes the exchange body to the file
 *   (overwrite; `append: true` appends; `delete: true` removes the file).
 *   The body flows through unchanged.
 * - **`.enrich(file({ path }))`** reads the file mid-route and the content
 *   replaces the body (pass an aggregator such as `only()` to merge
 *   instead). Dynamic (function) paths resolve against the exchange.
 *
 * @param options - File path, encoding, createDirs, append/delete, chunked
 * @returns The combined Source + Destination + Enricher adapter
 *
 * @example
 * ```typescript
 * // Read file as source
 * .from(file({ path: './input.txt' }))
 *
 * // Read one exchange per line
 * .from(file({ path: './input.txt', chunked: true }))
 *
 * // Write to file
 * .to(file({ path: './output.txt' }))
 *
 * // Append to log
 * .to(file({ path: './log.txt', append: true }))
 *
 * // Pull a file into the body mid-route, alongside the existing data
 * .enrich(file({ path: './config.txt' }), only((s: string) => s, 'config'))
 *
 * // Dynamic path with directory creation
 * .to(file({
 *   path: (ex) => `./data/${ex.body.date}.txt`,
 *   createDirs: true
 * }))
 * ```
 */
declare function file(options: FileOptions): FileAdapter;

/**
 * One file (or directory) discovered while scanning a directory. This is the
 * body shape the directory source emits, one exchange per entry.
 *
 * All metadata lives on the body rather than on headers: the entry is a
 * structured object, so duplicating its fields into `routecraft.directory.*`
 * headers would just be two copies of the same state. Filter and route on
 * the body directly (`.filter((ex) => ex.body.ext === ".json")`), then read
 * the content with the file adapter (`file({ path: (ex) => ex.body.path })`).
 */
interface DirectoryEntry {
    /**
     * Path to the entry, resolved against the scanned directory, suitable for
     * handing straight to `file({ path })`. Relative when the scanned path is
     * relative, absolute when it is absolute.
     */
    path: string;
    /** Base name including extension, e.g. "report.json". */
    name: string;
    /** Directory containing the entry. */
    dir: string;
    /**
     * Lowercased file extension including the leading dot, e.g. ".json".
     * Empty string when the name has no extension. Lowercased so filtering is
     * predictable across platforms; `name` and `path` keep their original case.
     */
    ext: string;
    /**
     * Path relative to the scanned directory root. Useful with `recursive: true`
     * to see where in the tree the entry lives (e.g. "sub/report.json").
     */
    relativePath: string;
    /** File size in bytes (0 for directories on most platforms). */
    size: number;
    /** Last modification time. */
    modifiedAt: Date;
    /**
     * Creation time (birthtime). Some filesystems do not track this and report
     * the modification time (or epoch) instead.
     */
    createdAt: Date;
    /** True when the entry is a directory (only emitted when `includeDirs`). */
    isDirectory: boolean;
}
/**
 * Options for the directory adapter, in both of its roles. As a source
 * (`.from()`) it scans a directory and emits the listing; as an enricher
 * (`.enrich()` / `.to()`) its `fetch` returns the listing, so a directory can
 * be listed mid-route (a listing is a read, like the file adapter's fetch).
 * `recursive`, `includeDirs`, and the deterministic ordering behave
 * identically in either role; `chunked` is a source-only emission shape.
 */
interface DirectoryOptions {
    /**
     * Directory to scan: a path string, or a function that returns one.
     * The source role requires a static string (a source is not per-exchange);
     * the enricher role also accepts the function form, which receives the
     * exchange when the scan runs.
     */
    path: string | ((exchange: Exchange) => string);
    /**
     * Descend into subdirectories. When false, only the immediate children of
     * `path` are emitted. Default: false.
     */
    recursive?: boolean;
    /**
     * Also emit directory entries, not just files. Default: false (files only).
     * When recursive, the source still descends into subdirectories regardless
     * of this flag; this only controls whether the directories themselves are
     * emitted as exchanges.
     */
    includeDirs?: boolean;
    /**
     * Emission shape, matching the `csv` / `jsonl` convention:
     * - `false` (default): emit a single exchange whose body is the full
     *   `DirectoryEntry[]` listing. Good for acting on the collection as a whole,
     *   counting, or deciding before you `.split()`.
     * - `true`: emit one exchange per entry (body is a single `DirectoryEntry`).
     *   Good for filtering by metadata or name with `.filter()` and reading each
     *   file's content with the file adapter.
     */
    chunked?: boolean;
}

/**
 * Directory adapter type: source and enricher on one honest type. The
 * operation keyword selects the role (`.from()` subscribes and emits the
 * listing, `.enrich()` fetches it mid-route). There is no `send`: a listing
 * is a read, so `.to(directory({ path }))` resolves to the fetch and the
 * listing replaces the body.
 */
type DirectoryAdapter = Source<DirectoryEntry[]> & Enricher<unknown, DirectoryEntry[]> & {
    readonly adapterId: string;
};
/**
 * Directory adapter type in chunked mode: the source emits one
 * {@link DirectoryEntry} per exchange. The enricher role is unaffected by
 * `chunked` (a fetch produces one value) and still returns the full listing.
 */
type DirectoryChunkedAdapter = Source<DirectoryEntry> & Enricher<unknown, DirectoryEntry[]> & {
    readonly adapterId: string;
};
/**
 * Creates a directory adapter in chunked mode: the source emits one exchange
 * per entry, each body a {@link DirectoryEntry}. Filter by metadata or name
 * with `.filter()`, then read content with the file adapter. Chunked is a
 * source-only emission shape, so the path must be a static string.
 *
 * @param options - Directory options with `chunked: true`
 * @returns A Source emitting one {@link DirectoryEntry} per entry (plus the
 *   unchanged enricher role)
 *
 * @example
 * ```typescript
 * // Read the content of every .json file in a directory
 * craft()
 *   .from(directory({ path: "./inbox", chunked: true }))
 *   .filter((ex) => ex.body.ext === ".json")
 *   .enrich(
 *     file({ path: (ex) => ex.body.path }),
 *     only((content: string) => content, "content"),
 *   )
 *   .to(log());
 * ```
 */
declare function directory(options: Omit<DirectoryOptions, "path"> & {
    path: string;
    chunked: true;
}): DirectoryChunkedAdapter;
/**
 * Creates a directory adapter that scans a directory and produces the full
 * {@link DirectoryEntry}`[]` listing (sorted by relative path). One factory,
 * one type; the POSITION in the route selects the role:
 *
 * - **`.from(directory({ path }))`** emits a single exchange whose body is the
 *   listing, mirroring the non-chunked `csv` / `jsonl` adapters; pass
 *   `chunked: true` to emit one exchange per entry instead. The source role
 *   needs a static string path.
 * - **`.enrich(directory({ path }))`** scans the directory mid-route and the
 *   listing replaces the body (pass an aggregator such as `only()` to merge
 *   instead). Dynamic (function) paths resolve against the exchange.
 * - **`.to(directory({ path }))`** has no `send` to prefer, so it resolves to
 *   the same fetch and the listing becomes the body. This is what makes the
 *   adapter usable inside a `direct()` capability.
 *
 * Filtering is not built in by design: list the entries, then narrow with the
 * normal operations (`.filter()` per-entry in chunked mode, or `.split()` /
 * `.transform()` on the array), and read content with the file adapter. This
 * keeps "find the files" and "decide which ones" composable.
 *
 * @param options - Directory path plus `recursive`, `includeDirs`, `chunked`
 * @returns The combined Source + Enricher adapter
 *
 * @example
 * ```typescript
 * // Get the whole listing as one body, then act on the collection
 * craft()
 *   .from(directory({ path: "./inbox" }))
 *   .transform((entries) => entries.filter((e) => e.ext === ".json"))
 *   .split((ex) => ex.body)
 *   .enrich(
 *     file({ path: (ex) => ex.body.path }),
 *     only((content: string) => content, "content"),
 *   )
 *   .to(log());
 *
 * // List a directory mid-route, e.g. inside a direct() capability
 * craft()
 *   .id("search-notes")
 *   .from(direct())
 *   .to(directory({ path: "./notes", recursive: true }))
 *   .transform((entries) => entries.filter((e) => e.ext === ".md"))
 *   .to(log());
 * ```
 */
declare function directory(options: DirectoryOptions): DirectoryAdapter;

type HtmlResult = string | string[];
interface HtmlOptions<T = unknown, R = unknown> {
    /**
     * CSS selector to match elements.
     * Optional for the send role (writing needs no extraction).
     * Required for the transformer, source, and fetch roles.
     */
    selector?: string;
    /**
     * What to extract. Default: "text".
     * - text: cheerio .text() (all descendant text), trimmed, with
     *   `style` and `script` subtrees removed
     * - html: inner HTML (cheerio .html())
     * - attr: attribute value (requires attr option)
     * - outerHtml: element including its tag (cheerio .prop('outerHTML'))
     * - innerText: same as textContent; server-side there is no layout
     * - textContent: identical to "text"
     *
     * The three text modes return the page's text decoded and unsanitised.
     * Entities are resolved, so a page that escaped markup yields it as
     * written, and whitespace inside the match survives: only the ends are
     * trimmed. Escape the value at the sink before writing it into HTML or
     * into any line-structured format.
     */
    extract?: "text" | "html" | "attr" | "outerHtml" | "innerText" | "textContent";
    /** Attribute name when extract is "attr". */
    attr?: string;
    /** Pluck HTML string from body. If omitted: body is used when it's a string, or body.body when body is an object (e.g. after http()). */
    from?: (body: T) => string;
    /** Where to put the extracted result. If omitted, result replaces the entire body (same default as from). Use e.g. (body, result) => ({ ...body, field: result }) to write to a sub-field. */
    to?: (body: T, result: HtmlResult) => R;
    /**
     * File path. Presence of `path` gives html() the file roles (source /
     * send / fetch) instead of the transformer role. The source and fetch
     * roles read the file and extract via the selector; the send role writes
     * the exchange body (HTML string) to the file. The function form receives
     * the exchange (send/fetch roles only; the source role needs a static
     * string).
     */
    path?: string | ((exchange: Exchange) => string);
    /**
     * Send role behavior: append to the file instead of overwriting it.
     * Mutually exclusive with `delete`. Default: false (overwrite)
     */
    append?: boolean;
    /**
     * Send role behavior: delete the file instead of writing it. Idempotent:
     * an already-absent path is a no-op. The body is unchanged. Mutually
     * exclusive with `append`. Default: false
     */
    delete?: boolean;
    /**
     * Text encoding (only when path is provided). Default: 'utf-8'
     */
    encoding?: BufferEncoding;
    /**
     * Create parent directories if they don't exist (send role only, only when path is provided).
     * Default: false
     */
    createDirs?: boolean;
    /**
     * How to handle an `extractHtml` failure on the file content (source role
     * only).
     *
     * - `'fail'` (default): `route:exchange:failed` fires, or
     *   `route:error:caught` when the route's `.error()` handler recovers.
     * - `'abort'`: `route:exchange:failed` fires, then the source dies
     *   (`context:error`).
     * - `'drop'`: `route:exchange:dropped` fires with `reason: "parse-failed"`.
     *
     * See `OnParseError` for full semantics.
     *
     * @default "fail"
     */
    onParseError?: OnParseError;
}

/**
 * Combined HTML file adapter type: the file roles on one honest type. The
 * operation keyword selects the role (`.from()` subscribes, `.to()` sends,
 * `.enrich()` fetches). The transformer role lives on the no-`path` variant
 * of the factory (an extraction over the body needs no file).
 */
type HtmlAdapter = Source<HtmlResult> & Destination<unknown> & Enricher<unknown, HtmlResult> & {
    readonly adapterId: string;
};
/**
 * Create an HTML adapter that extracts data from HTML using CSS selectors (cheerio).
 *
 * **Transformer role** (no `path` option): extracts data from the HTML
 * string in the exchange body. Use `from` to read a sub-field and `to` to
 * write the result to a sub-field.
 *
 * **File roles** (`path` present); the POSITION in the route selects the role:
 * - **`.from(html({ path, selector }))`** reads the file, extracts via the
 *   selector, and emits the result.
 * - **`.to(html({ path }))`** writes the HTML string from the body to the
 *   file (overwrite; `append: true` appends; `delete: true` removes the
 *   file). The body flows through unchanged.
 * - **`.enrich(html({ path, selector }))`** extracts from the file
 *   mid-route; the result replaces the body (pass an aggregator such as
 *   `only()` to merge instead).
 *
 * Requires `cheerio` to be installed as an optional peer dependency.
 *
 * @param options - selector, extract type, optional path for file roles, optional from/to for the transformer role
 * @returns A Transformer (no path) or the combined file adapter (path)
 *
 * @example
 * ```typescript
 * // Transformer role
 * .transform(html({ selector: 'title', extract: 'text' }))
 *
 * // Source role: read HTML file and extract
 * .from(html({ path: './page.html', selector: 'h1', extract: 'text' }))
 *
 * // Fetch mid-route: extract from a file and merge the result
 * .enrich(html({ path: './page.html', selector: 'h1' }), only((h1) => h1, 'h1'))
 *
 * // Send role: write HTML to file
 * .to(html({ path: './output.html' }))
 *
 * // Delete an HTML file (idempotent)
 * .to(html({ path: (ex) => ex.body.processedPath, delete: true }))
 * ```
 */
declare function html<T = unknown, R = HtmlResult>(options: HtmlOptions<T, R> & {
    path: string | ((exchange: Exchange) => string);
}): HtmlAdapter;
declare function html<T = unknown, R = HtmlResult>(options: HtmlOptions<T, R> & {
    path?: undefined;
}): Transformer<T, R> & {
    readonly adapterId: string;
};

/**
 * Transformer-mode options (current behavior).
 */
interface JsonTransformerOptions<T = unknown, R = unknown, V = unknown> {
    /**
     * Dot-notation pointer to extract from the parsed JSON, e.g.
     * "data.items[0].name". If omitted, the full parsed JSON is returned.
     * Named `pointer` (not `path`) so file-role options and transformer
     * options never collide: `path` always means a file path.
     */
    pointer?: string;
    /** Pluck JSON string from body. If omitted: body is used when it's a string, or body.body when body is an object (e.g. after http()). */
    from?: (body: T) => string;
    /**
     * Extract or transform the parsed value; return type V is inferred and used for result (and for to(body, result)).
     * When omitted, parsed/path result is used as-is and typed as unknown.
     */
    getValue?: (parsed: unknown) => V;
    /** Where to put the parsed/extracted result. If omitted, result replaces the entire body (same default as from). Use e.g. (body, result) => ({ ...body, parsed: result }) to write to a sub-field. Result is typed as V when getValue is provided. */
    to?: (body: T, result: V) => R;
}
/**
 * File-role options (`path` present): the adapter carries the source, send,
 * and fetch roles for a JSON file; the operation keyword selects the role.
 */
interface JsonFileOptions {
    /**
     * File path string or function that returns the path. Presence of `path`
     * makes json() a file adapter instead of a transformer. The function form
     * receives the exchange (send/fetch roles only; the source role requires
     * a static string path).
     */
    path: string | ((exchange: Exchange) => string);
    /**
     * Text encoding. Default: 'utf-8'
     */
    encoding?: BufferEncoding;
    /**
     * Create parent directories if they don't exist (send role only).
     * Default: false
     */
    createDirs?: boolean;
    /**
     * Send role behavior: append to the file instead of overwriting it.
     * Mutually exclusive with `delete`. Default: false (overwrite)
     */
    append?: boolean;
    /**
     * Send role behavior: delete the JSON file instead of writing it.
     * Idempotent: an already-absent path is a no-op. The body is unchanged.
     * Mutually exclusive with `append`. Default: false
     */
    delete?: boolean;
    /**
     * Number of spaces for JSON formatting (send role only).
     * Default: 0 (compact JSON)
     * Alias: Can also use 'indent' for compatibility.
     */
    space?: number;
    /**
     * Alias for 'space'. Number of spaces for JSON formatting.
     */
    indent?: number;
    /**
     * JSON.parse reviver function (source/fetch roles).
     */
    reviver?: (key: string, value: unknown) => unknown;
    /**
     * JSON.stringify replacer function (send role only).
     */
    replacer?: (key: string, value: unknown) => unknown;
    /**
     * How to handle a `JSON.parse` failure on the file content (source role
     * only).
     *
     * - `'fail'` (default): `route:exchange:failed` fires, or
     *   `route:error:caught` when the route's `.error()` handler recovers.
     * - `'abort'`: `route:exchange:failed` fires, then the source dies
     *   (`context:error`).
     * - `'drop'`: `route:exchange:dropped` fires with `reason: "parse-failed"`.
     *
     * See `OnParseError` for full semantics.
     *
     * @default "fail"
     */
    onParseError?: OnParseError;
}
type JsonOptions<T = unknown, R = unknown, V = unknown> = JsonTransformerOptions<T, R, V> | JsonFileOptions;

/**
 * Combined JSON file adapter type: all three roles on one honest type. The
 * operation keyword selects the role (`.from()` subscribes, `.to()` sends,
 * `.enrich()` fetches). The parsed value is typed `T` (default `unknown`);
 * pass it explicitly (`json<Product[]>(...)`) for a typed body.
 *
 * @template T - Parsed value type (caller-asserted)
 */
type JsonFileAdapterType<T = unknown> = Source<T> & Destination<unknown> & Enricher<unknown, T> & {
    readonly adapterId: string;
};
/**
 * Creates a JSON adapter.
 *
 * **Transformer role** (no `path` option):
 * Parses a JSON string and optionally extracts a value by `pointer`
 * (dot-notation into the parsed value). By default uses body (or body.body
 * when object) as the JSON string and replaces the body with the result.
 *
 * **File roles** (`path` present); the POSITION in the route selects the role:
 * - **`.from(json({ path }))`** reads + parses the file and emits the value.
 * - **`.to(json({ path }))`** stringifies the body and writes it (overwrite;
 *   `append: true` appends; `delete: true` removes the file). The body flows
 *   through unchanged.
 * - **`.enrich(json({ path }))`** reads + parses mid-route; the value
 *   replaces the body (pass an aggregator such as `only()` to merge instead).
 *
 * @param options - Transformer options (`from`, `pointer`, `getValue`, `to`) or file options (`path`, `space`, etc.)
 * @returns A Transformer (no path) or the combined file adapter (path)
 *
 * @example
 * ```typescript
 * // Transformer role
 * .transform(json({ pointer: 'data.items' }))
 * .transform(json({ from: (b) => b.raw, getValue: (p) => p as User[] }))
 *
 * // Source role
 * .from(json({ path: './data.json' }))
 *
 * // Read mid-route (the parsed value replaces the body)
 * .enrich(json<Product[]>({ path: './data.json' }), only((p) => p, 'catalogue'))
 *
 * // Send role (write)
 * .to(json({ path: './output.json', space: 2 }))
 * .to(json({ path: (ex) => `./data/${ex.body.id}.json`, createDirs: true }))
 * ```
 */
declare function json<T, R, V>(options: JsonTransformerOptions<T, R, V> & {
    getValue: (parsed: unknown) => V;
    to?: undefined;
}): Transformer<T, V>;
declare function json<T = unknown>(options: JsonFileOptions): JsonFileAdapterType<T>;
declare function json<T = unknown, R = unknown, V = unknown>(options?: JsonTransformerOptions<T, R, V>): Transformer<T, R>;

/**
 * Parsing/formatting options shared by transformer and file modes.
 */
interface CsvParseOptions {
    /**
     * Whether the CSV has a header row (parse) or should include headers (format).
     * Default: true
     */
    header?: boolean;
    /**
     * Field delimiter. Default: ','
     */
    delimiter?: string;
    /**
     * Quote character. Default: '"'
     */
    quoteChar?: string;
    /**
     * Skip empty lines. Default: true
     */
    skipEmptyLines?: boolean;
}
/**
 * Transformer-mode options (no `path`): parse a CSV string already in the body.
 */
interface CsvTransformerOptions<T = unknown, R = unknown> extends CsvParseOptions {
    /**
     * Pluck the CSV string from the body. If omitted: body is used when it's a
     * string, or body.body when body is an object (e.g. after http()).
     */
    from?: (body: T) => string;
    /**
     * Where to put the parsed rows. If omitted, the result replaces the entire
     * body. Use e.g. (body, rows) => ({ ...body, rows }) to write to a sub-field.
     */
    to?: (body: T, result: CsvData) => R;
}
/**
 * Source/Destination mode options (with `path`).
 */
interface CsvFileOptions extends CsvParseOptions {
    /**
     * File path for source/destination mode.
     */
    path: string | ((exchange: Exchange) => string);
    /**
     * Text encoding. Default: 'utf-8'
     */
    encoding?: BufferEncoding;
    /**
     * Create parent directories if they don't exist (send role only).
     * Default: false
     */
    createDirs?: boolean;
    /**
     * Send role behavior: append rows to the file instead of overwriting it
     * (the header row is only written when the file does not exist yet).
     * Mutually exclusive with `delete`. Default: false (overwrite)
     */
    append?: boolean;
    /**
     * Send role behavior: delete the CSV file instead of writing it.
     * Idempotent: an already-absent path is a no-op. The body is unchanged.
     * Mutually exclusive with `append`. Default: false
     */
    delete?: boolean;
    /**
     * When true, the source emits one exchange per row instead of the entire
     * parsed array. Source role only; the send/fetch roles are identical under
     * chunked. Each chunked exchange includes CSV_ROW and CSV_PATH headers.
     * Default: false
     */
    chunked?: boolean;
    /**
     * How to handle a Papa Parse row error (chunked mode) or parse error
     * (non-chunked mode).
     *
     * - `'fail'` (default): `route:exchange:failed` fires for the bad row, or
     *   `route:error:caught` when the route's `.error()` handler recovers it;
     *   chunked mode continues to the next row.
     * - `'abort'`: `route:exchange:failed` fires, then the source dies
     *   (`context:error`).
     * - `'drop'`: `route:exchange:dropped` fires with `reason: "parse-failed"`;
     *   chunked mode continues.
     *
     * See `OnParseError` for full semantics.
     *
     * @default "fail"
     */
    onParseError?: OnParseError;
}
type CsvOptions<T = unknown, R = unknown> = CsvTransformerOptions<T, R> | CsvFileOptions;
type CsvRow = Record<string, unknown> | string[];
type CsvData = CsvRow[];
/**
 * Header keys the CSV source sets on chunked-mode exchanges. Keys live
 * under the reserved `routecraft.csv.*` namespace; the value types are
 * merged into `RoutecraftHeaders` below.
 */
declare const CsvHeaders: {
    /** The 1-based row number when reading a CSV file in chunked mode */
    readonly ROW: "routecraft.csv.row";
    /** The file path when reading a CSV file in chunked mode */
    readonly PATH: "routecraft.csv.path";
};
declare module "@routecraft/routecraft" {
    interface RoutecraftHeaders {
        /** The 1-based row number when reading a CSV file in chunked mode */
        [CsvHeaders.ROW]?: number;
        /** The file path when reading a CSV file in chunked mode */
        [CsvHeaders.PATH]?: string;
    }
}

/**
 * Combined CSV file adapter type: all three roles on one honest type. The
 * operation keyword selects the role (`.from()` subscribes, `.to()` sends,
 * `.enrich()` fetches).
 */
type CsvAdapter = Source<CsvData> & Destination<unknown> & Enricher<unknown, CsvData> & {
    readonly adapterId: string;
};
/**
 * Chunked CSV adapter: identical to {@link CsvAdapter} except the source
 * emits one exchange per row (`CsvRow`) instead of one `CsvData` array. The
 * send/fetch roles are unchanged (the chunked option concerns the subscribe
 * role only).
 */
type CsvChunkedAdapter = Source<CsvRow> & Destination<unknown> & Enricher<unknown, CsvData> & {
    readonly adapterId: string;
};
/**
 * Creates a CSV adapter in chunked source mode: one exchange per row with
 * CSV_ROW and CSV_PATH headers. `chunked` must be the literal `true`; a
 * widened boolean is a compile error, so dynamic chunking is an explicit
 * branch at the call site.
 *
 * Requires `papaparse` to be installed as a peer dependency.
 *
 * @param options - CSV file options with chunked: true
 * @returns The combined adapter with a per-row Source
 */
declare function csv(options: CsvFileOptions & {
    chunked: true;
}): CsvChunkedAdapter;
/**
 * Creates a CSV adapter for a CSV file. One factory, one type; the POSITION
 * in the route selects the role:
 *
 * - **`.from(csv({ path }))`** reads + parses the file and emits the rows.
 * - **`.to(csv({ path }))`** formats the exchange body as CSV and writes it
 *   (overwrite; `append: true` appends; `delete: true` removes the file).
 *   The body flows through unchanged.
 * - **`.enrich(csv({ path }))`** reads + parses mid-route; the rows replace
 *   the body (pass an aggregator such as `only()` to merge instead).
 *
 * Requires `papaparse` to be installed as a peer dependency.
 *
 * @param options - CSV path, parsing/formatting options
 * @returns The combined Source + Destination + Enricher adapter
 *
 * @example
 * ```typescript
 * // Read CSV file as source
 * .from(csv({ path: './data.csv', header: true }))
 *
 * // Read mid-route (the parsed rows replace the body)
 * .enrich(csv({ path: './data.csv' }))
 *
 * // Write to CSV file
 * .to(csv({ path: './output.csv', header: true }))
 *
 * // Append to CSV file
 * .to(csv({ path: './log.csv', append: true }))
 *
 * // Delete a CSV file (idempotent)
 * .to(csv({ path: (ex) => ex.body.processedPath, delete: true }))
 * ```
 */
declare function csv(options: CsvFileOptions & {
    chunked?: false;
}): CsvAdapter;
/**
 * Creates a CSV transformer that parses a CSV string already in the body.
 *
 * Requires `papaparse` to be installed as a peer dependency.
 *
 * @param options - Transformer options (`from`, `to`, parsing options); no `path`
 * @returns A Transformer
 */
declare function csv<T = unknown, R = unknown>(options?: CsvTransformerOptions<T, R>): Transformer<T, R> & {
    readonly adapterId: string;
};

/**
 * Parsing options shared by transformer, source, and read-destination modes.
 *
 * The attribute / text / CDATA naming keys (`attributeNamePrefix`,
 * `textNodeName`, `cdataPropName`, `ignoreAttributes`) are also honoured when
 * building XML in destination mode, so a parse then build round-trip preserves
 * structure when the same options are used on both ends.
 */
interface XmlParseOptions {
    /**
     * Drop XML attributes from the parsed output (and omit them when building).
     * Routecraft defaults this to `false` so attributes survive a round-trip;
     * fast-xml-parser's own default is `true`.
     * Default: false
     */
    ignoreAttributes?: boolean;
    /**
     * Prefix applied to attribute keys in the parsed object (and recognised when
     * building). Default: '@_'
     */
    attributeNamePrefix?: string;
    /**
     * Property name used for the text content of a node that also has attributes
     * or children. Default: '#text'
     */
    textNodeName?: string;
    /**
     * Property name used for CDATA sections. When omitted, CDATA content is
     * merged into the node text. Default: undefined
     */
    cdataPropName?: string;
    /**
     * Coerce attribute string values to number / boolean. Default: false
     */
    parseAttributeValue?: boolean;
    /**
     * Coerce tag text values to number / boolean. Default: true
     */
    parseTagValue?: boolean;
    /**
     * Trim whitespace around text values. Default: true
     */
    trimValues?: boolean;
    /**
     * Strip namespace prefixes from tag and attribute names (e.g. `ns:tag` ->
     * `tag`). Default: false
     */
    removeNSPrefix?: boolean;
    /**
     * Force specific tags to always parse as arrays, regardless of how many
     * times they occur. Without this, a tag that appears once parses as an
     * object while repeated occurrences parse as an array, a well-known
     * fast-xml-parser footgun for consumers that expect a stable shape for
     * repeatable elements (e.g. `<items><item/></items>`). Return true for the
     * tags you want to always be arrays.
     *
     * Default: undefined (fast-xml-parser's own occurrence-based heuristic)
     */
    isArray?: (tagName: string, jPath: string, isLeafNode: boolean, isAttribute: boolean) => boolean;
}
/**
 * Formatting options used when building XML in destination write mode.
 */
interface XmlBuildOptions {
    /**
     * Pretty-print the output with line breaks and indentation. Default: false
     */
    format?: boolean;
    /**
     * Indentation unit used when `format` is true. Default: '  ' (two spaces)
     */
    indentBy?: string;
    /**
     * Collapse empty nodes to self-closing tags (`<a/>` instead of `<a></a>`).
     * Default: false
     */
    suppressEmptyNode?: boolean;
}
/**
 * Transformer-mode options (no `path`): parse an XML string already in the body.
 */
interface XmlTransformerOptions<T = unknown, R = unknown> extends XmlParseOptions {
    /**
     * Pluck the XML string from the body. If omitted: body is used when it's a
     * string, or body.body when body is an object (e.g. after http()).
     */
    from?: (body: T) => string;
    /**
     * Where to put the parsed object. If omitted, the result replaces the entire
     * body. Use e.g. (body, parsed) => ({ ...body, parsed }) to write to a
     * sub-field.
     */
    to?: (body: T, parsed: XmlData) => R;
}
/**
 * File-role options (with `path`): the adapter carries the source, send, and
 * fetch roles for an XML file; the operation keyword selects the role.
 *
 * Note: XML has no `append` behavior. Appending serialized fragments to an
 * XML document produces multiple root elements and an invalid document, so
 * the adapter deliberately omits it. Read the file, mutate the parsed
 * object, and write it back instead.
 */
interface XmlFileOptions extends XmlParseOptions, XmlBuildOptions {
    /**
     * File path. The function form (resolved per exchange) is valid for the
     * send/fetch roles only; the source role requires a static string path.
     */
    path: string | ((exchange: Exchange) => string);
    /**
     * Text encoding. Default: 'utf-8'
     */
    encoding?: BufferEncoding;
    /**
     * Create parent directories if they don't exist (send role only).
     * Default: false
     */
    createDirs?: boolean;
    /**
     * Send role behavior: delete the XML file instead of writing it.
     * Idempotent: an already-absent path is a no-op. The body is unchanged.
     * Default: false
     */
    delete?: boolean;
    /**
     * How to handle a parse failure on the file content (source role only).
     *
     * - `'fail'` (default): `route:exchange:failed` fires, or
     *   `route:error:caught` when the route's `.error()` handler recovers.
     * - `'abort'`: `route:exchange:failed` fires, then the source dies
     *   (`context:error`).
     * - `'drop'`: `route:exchange:dropped` fires with `reason: "parse-failed"`.
     *
     * See `OnParseError` for full semantics.
     *
     * @default "fail"
     */
    onParseError?: OnParseError;
}
type XmlOptions<T = unknown, R = unknown> = XmlTransformerOptions<T, R> | XmlFileOptions;
/** A parsed XML document represented as a plain object. */
type XmlData = Record<string, unknown>;

/**
 * Combined XML file adapter type: all three roles on one honest type. The
 * operation keyword selects the role (`.from()` subscribes, `.to()` sends,
 * `.enrich()` fetches). The parsed object is typed `T` (default `XmlData`);
 * pass it explicitly (`xml<MyDoc>(...)`) for a typed body.
 *
 * @template T - Parsed object type (caller-asserted)
 */
type XmlAdapter<T = XmlData> = Source<T> & Destination<unknown> & Enricher<unknown, T> & {
    readonly adapterId: string;
};
/**
 * Creates an XML adapter.
 *
 * **Transformer role** (no `path` option): parses an XML string already in
 * the body.
 *
 * **File roles** (`path` present); the POSITION in the route selects the role:
 * - **`.from(xml({ path }))`** reads + parses the file and emits the object.
 * - **`.to(xml({ path }))`** builds the body object into an XML document and
 *   writes it (`delete: true` removes the file instead). The body flows
 *   through unchanged.
 * - **`.enrich(xml({ path }))`** reads + parses mid-route; the object
 *   replaces the body (pass an aggregator such as `only()` to merge instead).
 *
 * Requires `fast-xml-parser` to be installed as an optional peer dependency.
 *
 * @param options - Transformer options (no `path`) or file options
 * @returns A Transformer (no path) or the combined file adapter (path)
 *
 * @example
 * ```typescript
 * // Parse an XML string already in the body (transformer role)
 * .transform(xml({ from: (b) => b.body }))
 *
 * // Read an XML file as a source
 * .from(xml({ path: './data.xml' }))
 *
 * // Read mid-route (the parsed object replaces the body)
 * .enrich(xml({ path: './data.xml' }), only((doc) => doc, 'doc'))
 *
 * // Write to an XML file (pretty-printed)
 * .to(xml({ path: './output.xml', format: true }))
 *
 * // Delete an XML file (idempotent)
 * .to(xml({ path: (ex) => ex.body.processedPath, delete: true }))
 * ```
 */
declare function xml<T = XmlData>(options: XmlFileOptions): XmlAdapter<T>;
declare function xml<T = unknown, R = unknown>(options?: XmlTransformerOptions<T, R>): Transformer<T, R> & {
    readonly adapterId: string;
};

/**
 * Single options type for the jsonl file family: one options shape per
 * adapter, shared by all three roles (the file-family pattern shared with
 * `JsonFileOptions` / `CsvFileOptions`). The operation keyword selects the
 * role; options only tune behavior within a role.
 */
interface JsonlFileOptions {
    /**
     * File path string or function that returns the path. Function paths
     * receive the exchange (send/fetch roles only; the source role requires a
     * static string path).
     */
    path: string | ((exchange: Exchange) => string);
    /**
     * Text encoding. Default: 'utf-8'
     */
    encoding?: BufferEncoding;
    /**
     * When true, the source emits one exchange per line instead of a parsed
     * array. Source role only; the send/fetch roles are identical under
     * chunked. Each chunked exchange includes `JsonlHeaders.LINE` and
     * `JsonlHeaders.PATH` headers.
     * Default: false
     */
    chunked?: boolean;
    /**
     * Send role behavior: append lines to the file instead of overwriting it.
     * Mutually exclusive with `delete`. Default: false (overwrite; note this
     * changed from the pre-role-model default, which appended)
     */
    append?: boolean;
    /**
     * Send role behavior: delete the file instead of writing it. Idempotent:
     * an already-absent path is a no-op. The body is unchanged. Mutually
     * exclusive with `append`. Default: false
     */
    delete?: boolean;
    /**
     * Create parent directories if they don't exist (send role only).
     * Default: false
     */
    createDirs?: boolean;
    /**
     * Optional reviver function passed to JSON.parse (source/fetch roles).
     */
    reviver?: (key: string, value: unknown) => unknown;
    /**
     * Optional replacer passed to JSON.stringify (send role).
     * Can be a function or an array of allowed keys.
     */
    replacer?: ((key: string, value: unknown) => unknown) | Array<string | number> | null;
    /**
     * How to handle a `JSON.parse` failure on a line (chunked mode) or any
     * line of the file (non-chunked mode). Source mode only.
     *
     * - `'fail'` (default): `route:exchange:failed` fires for the bad line, or
     *   `route:error:caught` when the route's `.error()` handler recovers it;
     *   chunked mode continues.
     * - `'abort'`: `route:exchange:failed` fires, then the source dies
     *   (`context:error`).
     * - `'drop'`: `route:exchange:dropped` fires with `reason: "parse-failed"`;
     *   chunked mode continues.
     *
     * See `OnParseError` for full semantics.
     *
     * @default "fail"
     */
    onParseError?: OnParseError;
}
/**
 * Transformer-mode options (no `path`): parse a JSONL string already in the
 * body into an array.
 */
interface JsonlTransformerOptions<T = unknown, R = unknown> {
    /**
     * Pluck the JSONL string from the body. If omitted: body is used when it's a
     * string, or body.body when body is an object (e.g. after http()).
     */
    from?: (body: T) => string;
    /**
     * Where to put the parsed array. If omitted, the result replaces the entire
     * body. Use e.g. (body, rows) => ({ ...body, rows }) to write to a sub-field.
     */
    to?: (body: T, result: unknown[]) => R;
    /**
     * Optional reviver passed to JSON.parse.
     */
    reviver?: (key: string, value: unknown) => unknown;
}
type JsonlOptions = JsonlFileOptions | JsonlTransformerOptions;
/**
 * Header keys the JSONL source sets on chunked-mode exchanges. Keys live
 * under the reserved `routecraft.jsonl.*` namespace; the value types are
 * merged into `RoutecraftHeaders` below.
 */
declare const JsonlHeaders: {
    /** The 1-based line number when reading a JSONL file in chunked mode */
    readonly LINE: "routecraft.jsonl.line";
    /** The file path when reading a JSONL file in chunked mode */
    readonly PATH: "routecraft.jsonl.path";
};
declare module "@routecraft/routecraft" {
    interface RoutecraftHeaders {
        /** The 1-based line number when reading a JSONL file in chunked mode */
        [JsonlHeaders.LINE]?: number;
        /** The file path when reading a JSONL file in chunked mode */
        [JsonlHeaders.PATH]?: string;
    }
}

/**
 * Combined JSONL file adapter type: all three roles on one honest type. The
 * operation keyword selects the role (`.from()` subscribes, `.to()` sends,
 * `.enrich()` fetches).
 *
 * @template T - Element type of the parsed array (caller-asserted)
 */
type JsonlAdapter<T = unknown> = Source<T[]> & Destination<unknown> & Enricher<unknown, T[]> & {
    readonly adapterId: string;
};
/**
 * Chunked JSONL adapter: identical to {@link JsonlAdapter} except the source
 * emits one exchange per line (`T`) instead of one `T[]` array. The
 * send/fetch roles are unchanged (the chunked option concerns the subscribe
 * role only).
 *
 * @template T - Element type of each emitted line (caller-asserted)
 */
type JsonlChunkedAdapter<T = unknown> = Source<T> & Destination<unknown> & Enricher<unknown, T[]> & {
    readonly adapterId: string;
};
/**
 * Creates a JSONL adapter in chunked source mode: one exchange per line with
 * `JsonlHeaders.LINE` and `JsonlHeaders.PATH` headers. `chunked` must be the
 * literal `true`; a widened boolean is a compile error, so dynamic chunking
 * is an explicit branch at the call site.
 *
 * @param options - JSONL file options with chunked: true
 * @returns The combined adapter with a per-line Source
 */
declare function jsonl<T = unknown>(options: JsonlFileOptions & {
    chunked: true;
}): JsonlChunkedAdapter<T>;
/**
 * Creates a JSONL adapter for a JSON Lines file. One factory, one type; the
 * POSITION in the route selects the role:
 *
 * - **`.from(jsonl({ path }))`** reads + parses the file and emits the
 *   array (`chunked: true` emits one exchange per line).
 * - **`.to(jsonl({ path }))`** stringifies the body to JSONL and writes it
 *   (overwrite; `append: true` appends; `delete: true` removes the file).
 *   Array bodies write one line per element. The body flows through
 *   unchanged.
 * - **`.enrich(jsonl({ path }))`** reads + parses mid-route; the array
 *   replaces the body (pass an aggregator such as `only()` to merge
 *   instead).
 *
 * @param options - JSONL file path, encoding, append/delete, and parse options
 * @returns The combined Source + Destination + Enricher adapter
 *
 * @example
 * ```typescript
 * // Read JSONL as array
 * .from(jsonl({ path: './events.jsonl' }))
 *
 * // Read JSONL per-line
 * .from(jsonl({ path: './events.jsonl', chunked: true }))
 *
 * // Read mid-route (the parsed array replaces the body)
 * .enrich(jsonl({ path: './events.jsonl' }))
 *
 * // Append to JSONL (an event log)
 * .to(jsonl({ path: './output.jsonl', append: true }))
 *
 * // Delete a JSONL file (idempotent)
 * .to(jsonl({ path: (ex) => ex.body.processedPath, delete: true }))
 * ```
 */
declare function jsonl<T = unknown>(options: JsonlFileOptions & {
    chunked?: false;
}): JsonlAdapter<T>;
/**
 * Creates a JSONL transformer that parses a JSONL string already in the body.
 *
 * @param options - Transformer options (`from`, `to`, `reviver`); no `path`
 * @returns A Transformer
 */
declare function jsonl<T = unknown, R = unknown>(options?: JsonlTransformerOptions<T, R>): Transformer<T, R> & {
    readonly adapterId: string;
};

/**
 * Comparator for grouping: returns true when two items should be in the same group.
 * Used with `group({ comparator })`.
 *
 * @template T - Item type (e.g. object with an embedding field)
 */
interface Comparator<T = unknown> {
    compare: (a: T, b: T) => boolean;
}
/**
 * Options for the cosine similarity comparator.
 */
interface CosineOptions {
    /** Property on each item that holds the embedding vector (number[]). */
    field: string;
    /** Similarity threshold in 0-1. Items are grouped when similarity > threshold. Default: 0.82 */
    threshold?: number;
}

/**
 * Creates a comparator that groups items by cosine similarity of a numeric vector field.
 * Use with `group({ comparator: cosine(options) })`.
 *
 * @param options - `field` (path to number[] on each item), optional `threshold` (default 0.82)
 * @returns A Comparator that returns true when two items' vectors have similarity > threshold
 *
 * @example
 * ```typescript
 * .transform(group({
 *   comparator: cosine({ field: 'embedding', threshold: 0.85 }),
 *   from: (body) => body.items,
 *   map: (cluster) => ({ count: cluster.length, centroid: cluster[0] })
 * }))
 * ```
 */
declare function cosine<T = unknown>(options: CosineOptions): Comparator<T>;

interface GroupOptions<T = unknown, R = unknown> {
    comparator: Comparator<T>;
    /** Read the array to group from the body. Default: body is the array. */
    from?: (body: unknown) => T[];
    /** Shape each cluster into the output. Default: returns the raw cluster (T[]). */
    map?: (group: T[]) => R;
    /** Write the grouped result back. Default: replaces the entire body. */
    to?: (body: unknown, result: R[]) => unknown;
}

/**
 * Creates a transformer that groups an array into clusters using a comparator (e.g. cosine similarity).
 * By default uses body as the array and replaces the body with the array of clusters. Use `from`/`to` to read/write sub-fields; use `map` to shape each cluster.
 *
 * @param options - `comparator` (e.g. from `cosine()`), optional `from(body)`, `map(cluster)`, `to(body, result)`
 * @returns A Transformer usable with `.transform(group(options))`
 *
 * @example
 * ```typescript
 * .transform(group({
 *   comparator: cosine({ field: 'embedding', threshold: 0.82 }),
 *   from: (body) => body.items,
 *   map: (cluster) => ({ size: cluster.length, first: cluster[0] })
 * }))
 * ```
 */
declare function group<T = unknown, R = T[]>(options: GroupOptions<T, R>): Transformer<unknown, unknown>;

/**
 * Event filter options for the event source adapter.
 * Supports single event names, arrays, and wildcard patterns.
 */
type EventFilter = EventName | EventName[] | string | string[];
/**
 * Options for the event source adapter.
 */
interface EventSourceOptions {
    /**
     * Event name(s) to listen for.
     * Supports:
     * - Single event name: 'route:started'
     * - Array of event names: ['route:started', 'route:stopped']
     * - Wildcard patterns: 'route:exchange:*', 'route:operation:**', 'route:**', '*'
     */
    filter: EventFilter;
}

/**
 * Creates a source that produces exchanges from framework events.
 * Use as the first step in a route with `.from(event(...))`.
 *
 * Event names are a fixed set; the route id and the exchange live in the
 * payload's `details`, so scope to one route by filtering on
 * `details.routeId`. Patterns match the emitted name:
 *
 * - `*` matches exactly one colon-separated segment: `route:exchange:*`
 *   matches `route:exchange:failed` but not `route:started`.
 * - `**` matches zero or more segments: `route:**` matches every route event.
 * - `*` on its own matches every event.
 *
 * Events the route's own exchanges emit are not delivered back to it; see
 * {@link EventSourceAdapter}.
 *
 * @template T - Event payload type
 * @param filter - Event name(s) or wildcard pattern to listen for
 * @returns A Source usable with `.from(event(filter))`
 *
 * @example
 * ```typescript
 * // Single event
 * .from(event('route:started'))
 *
 * // Multiple events
 * .from(event(['route:started', 'route:stopped']))
 *
 * // Every exchange event: started, completed, failed, dropped, ...
 * .from(event('route:exchange:*'))
 *
 * // Every operation event, at any depth
 * .from(event('route:operation:**'))
 *
 * // Every route event
 * .from(event('route:**'))
 *
 * // Match all events
 * .from(event('*'))
 * ```
 */
declare function event(filter: EventFilter): Source<EventPayload<EventName>>;

/**
 * The read side of the mail adapter: one object carrying both read roles, so
 * the operation keyword picks between them instead of the call shape.
 * `.from()` subscribes (IDLE / polling), `.enrich()` fetches the folder as a
 * batch.
 */
type MailFolderAdapter = Source<MailBody> & Enricher<unknown, MailFetchResult>;
/**
 * Creates a mail adapter for reading email via IMAP, sending via SMTP,
 * or performing IMAP operations (move, copy, delete, flag, unflag, append).
 *
 * **Reading a folder (`.from()` / `.enrich()`):** name a folder, either as
 * `mail(folder, options?)` or as `mail({ folder, ...options })`. Both carry
 * BOTH read roles and the operation keyword picks between them: `.from()`
 * subscribes (IMAP IDLE or polling, pushing new messages into the route) and
 * `.enrich()` fetches the folder as a batch. The `folder` key is what
 * distinguishes a read from a send (mirroring `http`'s `path` vs `url`
 * split); passing options does not change the role, so `mail('INBOX')` and
 * `mail('INBOX', { markSeen: true })` differ only in configuration.
 *
 * **Send Destination (for `.to()`):** Call with no arguments or client options
 * (no `folder`). Sends email via SMTP using the exchange body as the payload.
 * The send is void: the body flows through unchanged and the receipt
 * (`routecraft.mail.sentMessageId`, `.accepted`, `.rejected`, `.response`)
 * lands on headers. The sent id is deliberately its own key: an inbound
 * `routecraft.mail.messageId` set by the source is left untouched so a
 * mail-to-mail route keeps its correlation id.
 *
 * **Operation Destination (for `.to()`):** Call with a MailAction object.
 * Performs IMAP operations (move, copy, delete, flag, unflag, append) on messages.
 *
 * @example
 * ```typescript
 * // Fetch mail via .enrich() (primary pattern)
 * craft()
 *   .from(cron('0 0/5 * * * *'))
 *   .enrich(mail('INBOX'))
 *   .to(processMessages())
 *
 * // Fetch with options: `folder` is required and marks the fetch intent
 * craft()
 *   .from(cron('0 0/5 * * * *'))
 *   .enrich(mail({ folder: 'INBOX', unseen: true, limit: 10 }))
 *   .to(processMessages())
 *
 * // Source: IMAP IDLE for push-based processing
 * craft()
 *   .from(mail('INBOX', { markSeen: true }))
 *   .to(processMessage())
 *
 * // Send mail via .to()
 * craft()
 *   .id('outbound')
 *   .from(direct())
 *   .to(mail())
 *
 * // IMAP operations
 * craft()
 *   .from(mail('INBOX', { unseen: true }))
 *   .to(mail({ action: 'move', folder: 'Archive' }))
 *
 * // Named account
 * craft()
 *   .from(mail('INBOX', { account: 'support' }))
 *   .to(mail({ action: 'flag', flags: '\\Seen', account: 'support' }))
 * ```
 *
 * @param folder - IMAP mailbox folder name (e.g. 'INBOX')
 * @param options - Server options for IMAP connection and fetch behavior
 * @returns Source, Enricher, Send Destination, or Operation Destination depending on arguments
 */
declare function mail(folder: string, options?: MailServerOptions): MailFolderAdapter;
declare function mail(action: MailAction): Destination<unknown>;
declare function mail(options: MailServerOptions & {
    folder: string;
}): MailFolderAdapter;
declare function mail(options?: MailClientOptions): Destination<MailSendPayload>;

/**
 * Low-level vCard lexer and emitter primitives.
 *
 * Parses raw vCard text into a flat list of {@link RawRecord}s (one per logical
 * line, folding undone, every parameter captured verbatim) and emits a single
 * property line back to RFC 6350 wire form (escaping, folding, parameter
 * quoting). The {@link VCard} document model in `vcard.ts` is built on top of
 * these; there is no typed projection here and nothing Apple-specific.
 *
 * @experimental
 */
/** A single vCard parameter, captured verbatim (name lowercased, value dequoted). */
interface VCardParam {
    /** Parameter name, lowercased (e.g. `type`, `x-service-type`). */
    name: string;
    /** Parameter value with surrounding quotes removed, original casing kept. */
    value: string;
}

/**
 * vCard document: a plain-data body plus an optional {@link VCard} wrapper.
 *
 * The exchange body is plain, serialization-safe data ({@link VCardBody}): a
 * version string and an ordered list of {@link VCardPropertyData}. It survives
 * `structuredClone`, `JSON.stringify`, queues, and `tap` with nothing lost,
 * because it is just data.
 *
 * For ergonomics, wrap a body in a {@link VCard} (`VCard.wrap(body)`,
 * `VCard.create()`, `VCard.parse(string)`). The wrapper reads and edits the
 * underlying data in place and exposes `.data` to get the plain body back. The
 * wrapper is a transient view, never the body itself, so the body stays plain.
 *
 * @experimental
 */

/**
 * A single vCard property as plain data. `value` is the escaped wire value (the
 * lossless source of truth); use {@link VCardProperty.value} on a wrapper for
 * the decoded text, or {@link VCardProperty.components} for structured values.
 */
interface VCardPropertyData {
    /** Property name as written (e.g. `"TEL"`, `"X-SOCIALPROFILE"`). */
    name: string;
    /** Group prefix (e.g. `"item1"`), if any. */
    group?: string;
    /** Parameters, in order, captured verbatim. */
    params: VCardParam[];
    /** Escaped wire value (post-unfold), exactly as it appears after the colon. */
    value: string;
}
/** A vCard document as plain data. This is the exchange body. */
interface VCardBody {
    /** vCard version (default `"3.0"`). */
    version: string;
    /** The ordered property list. */
    properties: VCardPropertyData[];
}
/** Options when adding a property. */
interface VCardPropertyOptions {
    /** Group prefix (e.g. `"item1"`) for label-grouped properties. */
    group?: string;
    /** Parameters to attach (e.g. `[{ name: "type", value: "home" }]`). */
    params?: VCardParam[];
}
/**
 * A transient view over one {@link VCardPropertyData}. Reads and writes go
 * straight through to the underlying plain object, so edits are reflected in the
 * body. `value` is decoded text; `raw` is the escaped wire form.
 */
declare class VCardProperty {
    private readonly data;
    constructor(data: VCardPropertyData);
    /** Property name as written. */
    get name(): string;
    /** Group prefix, or undefined. */
    get group(): string | undefined;
    /** Parameters, in order. */
    get params(): VCardParam[];
    /** Decoded text value (RFC 6350 escapes resolved). */
    get value(): string;
    set value(v: string);
    /** The escaped wire value, exactly as it appears after the colon. */
    get raw(): string;
    /** Decoded components of a structured value, split on unescaped `separator`. */
    components(separator?: string): string[];
    /** Set a structured value from decoded components (each escaped, then joined). */
    setComponents(parts: string[], separator?: string): this;
    /** First value of the named parameter (case-insensitive), if present. */
    param(name: string): string | undefined;
}
/**
 * An ergonomic wrapper around a {@link VCardBody}. Construct one with
 * {@link VCard.wrap}, {@link VCard.create}, or {@link VCard.parse}; read it with
 * `get`/`first`/`text`; edit it with `set`/`add`/`remove`; and read `.data` to
 * get the plain body to put back on the exchange.
 */
declare class VCard {
    /** The underlying plain-data body. */
    readonly data: VCardBody;
    private constructor();
    /** Wrap an existing plain body (edits write through to it). */
    static wrap(body: VCardBody): VCard;
    /** Create a wrapper over a fresh, empty body. */
    static create(version?: string): VCard;
    /**
     * Parse a single vCard string into a wrapper. `.data` is the plain body.
     *
     * @throws If the input is not a single `BEGIN:VCARD ... END:VCARD` block.
     */
    static parse(raw: string): VCard;
    /** Serialize a plain body to wire form (`BEGIN:VCARD` ... `END:VCARD`). */
    static serialize(body: VCardBody): string;
    /** vCard version. */
    get version(): string;
    set version(v: string);
    /** Property views, in order. */
    get properties(): VCardProperty[];
    /** All properties with the given name (case-insensitive). */
    get(name: string): VCardProperty[];
    /** The first property with the given name (case-insensitive), if any. */
    first(name: string): VCardProperty | undefined;
    /** Decoded value of the first property with the given name. */
    text(name: string): string | undefined;
    /** Decoded values of every property with the given name. */
    values(name: string): string[];
    /** The vCard `UID`, if present. */
    get uid(): string | undefined;
    set uid(value: string | undefined);
    /** Append a property (a decoded value, escaped on the way in). */
    add(name: string, value: string, options?: VCardPropertyOptions): this;
    /** Replace every property of `name` with a single one (case-insensitive). */
    set(name: string, value: string, options?: VCardPropertyOptions): this;
    /** Remove every property with the given name (case-insensitive). */
    remove(name: string): this;
    /** Serialize this card's data to wire form. */
    toString(): string;
    /** A deep, independent copy (wrapper over cloned data). */
    clone(): VCard;
    /** Plain representation for `JSON.stringify` / logging (the body). */
    toJSON(): VCardBody;
}
/** Parse a vCard string into a {@link VCard} wrapper. */
declare function parseVCard(raw: string): VCard;

/**
 * CardDAV adapter: reads vCard documents as a source, fetches them for
 * `.enrich()`, and creates / updates / deletes them as a destination.
 *
 * The body is a plain {@link VCardBody} (a `version` plus a property list). Wrap
 * it in a {@link VCard} for ergonomic reads/edits. DAV identity (`url`, `uid`,
 * `etag`) lives on the exchange headers (`routecraft.carddav.*`), not the body,
 * the same way the mail adapter carries its envelope metadata.
 *
 * The role is selected the same way the mail adapter selects its mode, via an
 * `action` flag on the options:
 *
 * - no action (read): `.from(carddav())` emits one `VCardBody` per address-book
 *   entry; `.enrich(carddav())` fetches all cards as a `VCardBody[]` body
 *   (pass an aggregator such as `only()` to merge instead of replacing).
 * - `action: 'save' | 'create' | 'update'`: `.to(carddav(...))` serializes the
 *   exchange body and writes it. A write replaces the card; it does not merge.
 *   Reading is lossless, so a read-modify-write keeps properties you did not
 *   touch; removing a property removes it. The write receipt (`url` / `uid` /
 *   `etag`, plus `created` for insert-vs-update) lands on the
 *   `routecraft.carddav.*` headers.
 * - `action: 'delete'`: deletes the contact resolved from the headers, the body,
 *   or a custom `target` extractor.
 *
 * Update and delete target the `routecraft.carddav.url` header and send the
 * read-time `routecraft.carddav.etag` as an `If-Match` precondition, so a
 * concurrent change surfaces as a conflict (RC5030) instead of being silently
 * overwritten. They do not re-fetch the address book; only an upsert without a
 * known url (or a delete by uid alone) pays a lookup.
 *
 * @experimental
 */

/**
 * CardDAV facade: source (read all, one exchange each), enricher (fetch all
 * as an array), and destination (write / delete with receipt headers). The
 * factory exposes the role slots that match the configured `action`.
 *
 * @experimental
 */
declare class CarddavAdapter implements Source<VCardBody>, Destination<unknown>, Enricher<unknown, VCardBody[]> {
    readonly adapterId = "routecraft.adapter.carddav";
    private readonly options;
    constructor(options?: CarddavOptions);
    subscribe(sub: Subscription<VCardBody>): Promise<void>;
    fetch: (exchange: Exchange<unknown>) => Promise<VCardBody[]>;
    send(exchange: Exchange<unknown>, ctx?: SendContext): Promise<void>;
    /** Observability metadata for the fetch role: the fetched card array. */
    getMetadata(result: unknown): Record<string, unknown>;
    /**
     * Observability metadata for the send role: receives the receipt-header
     * record collected by the `.to()` step (send is void).
     */
    getSendMetadata(receiptHeaders: unknown): Record<string, unknown>;
    /** Fetch all contacts as an array (best-effort: malformed cards are skipped). */
    private fetchAll;
    private write;
    /** PUT a full serialization of `body` to `url`, with `If-Match` when known. */
    private put;
    /** Create a new card. Relies on the driver's `If-None-Match: *` precondition. */
    private create;
    private createResult;
    private remove;
    /** Acquire a logged-in client (no address-book lookup). */
    private connect;
    /** Acquire a client and resolve the target address book (read/create paths). */
    private openRead;
    private buildHeaders;
    private resolveBook;
    /** Resolve the target contact from a custom extractor, the headers, or the body. */
    private resolveTarget;
    /** Locate a card by vCard UID (falls back to the resource filename). */
    private findByUid;
}

/**
 * Shared CardDAV adapter helpers: store key, client-manager access, the minimal
 * DAV driver surface the adapter depends on, and HTTP/error mapping.
 *
 * @experimental
 */

/** Default CardDAV server for iCloud Contacts. */
declare const DEFAULT_CARDDAV_SERVER_URL = "https://contacts.icloud.com";
/**
 * Store key for the CardDAV client manager.
 * Set by the ContextBuilder when `carddav` config is present.
 * @experimental
 */
declare const CARDDAV_CLIENT_MANAGER: unique symbol;
/**
 * Header keys the CardDAV adapter sets for contact metadata. Keys live
 * under the reserved `routecraft.carddav.*` namespace; the value types are
 * merged into `RoutecraftHeaders` below.
 * @experimental
 */
declare const CarddavHeaders: {
    /** vCard UID of a contact. */
    readonly UID: "routecraft.carddav.uid";
    /** DAV object URL of a contact. */
    readonly URL: "routecraft.carddav.url";
    /** DAV ETag of a contact. */
    readonly ETAG: "routecraft.carddav.etag";
    /** Named account a contact was read from. */
    readonly ACCOUNT: "routecraft.carddav.account";
    /** Write receipt: true when the write created a new contact, false when it updated one. */
    readonly CREATED: "routecraft.carddav.created";
};
declare module "@routecraft/routecraft" {
    interface StoreRegistry {
        [CARDDAV_CLIENT_MANAGER]: CarddavClientManager;
    }
}
declare module "@routecraft/routecraft" {
    interface RoutecraftHeaders {
        /** vCard UID of a contact. */
        [CarddavHeaders.UID]?: string;
        /** DAV object URL of a contact. */
        [CarddavHeaders.URL]?: string;
        /** DAV ETag of a contact. */
        [CarddavHeaders.ETAG]?: string;
        /** Named account a contact was read from. */
        [CarddavHeaders.ACCOUNT]?: string;
        /** Write receipt: true when the write created a new contact, false when it updated one. */
        [CarddavHeaders.CREATED]?: boolean;
    }
}
/** Address book collection as returned by the driver. */
interface DAVAddressBookLike {
    url: string;
    displayName?: string | Record<string, unknown>;
}
/** A single vCard object as returned by the driver. */
interface DAVVCardLike {
    url: string;
    etag?: string;
    data?: string;
}
/**
 * The subset of a tsdav client the CardDAV adapter calls. Declaring our own
 * surface keeps the adapter `any`-free (tsdav types `data` as `any`) and lets
 * tests substitute a lightweight fake.
 */
interface CarddavDriverClient {
    fetchAddressBooks(params?: {
        account?: unknown;
    }): Promise<DAVAddressBookLike[]>;
    fetchVCards(params: {
        addressBook: DAVAddressBookLike;
    }): Promise<DAVVCardLike[]>;
    createVCard(params: {
        addressBook: DAVAddressBookLike;
        vCardString: string;
        filename: string;
    }): Promise<Response>;
    updateVCard(params: {
        vCard: DAVVCardLike;
    }): Promise<Response>;
    deleteVCard(params: {
        vCard: DAVVCardLike;
    }): Promise<Response>;
}

/**
 * CardDAV client manager: one logged-in DAV client per named account.
 *
 * Created by the ContextBuilder when `carddav` config is present. Adapters get
 * it from the context store and request a client by account name. The
 * underlying tsdav client is HTTP/stateless, so there are no sockets to pool;
 * the manager simply caches the logged-in client (login is the only async cost).
 *
 * @experimental
 */

/** Connection inputs resolved from account + context config. */
interface ResolvedCarddavConnection {
    serverUrl: string;
    username: string;
    password: string;
}
/**
 * Manages per-account logged-in CardDAV clients.
 *
 * @experimental
 */
declare class CarddavClientManager {
    /**
     * Login seam. Resolves a driver client for the given connection. Exposed as a
     * static so tests can substitute a fake client without a network round-trip
     * (mirrors the cron adapter's `loadDriver` pattern).
     * @internal
     */
    static createDriverClient: (connection: ResolvedCarddavConnection) => Promise<CarddavDriverClient>;
    private readonly clients;
    readonly config: CarddavContextConfig;
    readonly defaultAccount: string;
    constructor(config: CarddavContextConfig);
    /** Resolve the connection inputs for an account, throwing RC5003 if incomplete. */
    resolveConnection(account?: string): ResolvedCarddavConnection;
    /** The default address book display name for an account, if configured. */
    resolveAddressBookName(account?: string): string | undefined;
    /** Acquire (and cache) a logged-in client for the given account. */
    getClient(account?: string): Promise<CarddavDriverClient>;
    /**
     * Release cached clients. Called during context teardown. Awaits any logins
     * still in flight (via `allSettled`) so a slow login that rejects after the
     * map has been cleared does not surface as an `unhandledRejection`.
     */
    drain(): Promise<void>;
}

/**
 * Well-known vCard property and parameter names.
 *
 * A convenience catalog of the standardized vocabulary (RFC 6350 plus the common
 * Apple `X-` extensions), NOT a constraint: every {@link VCard} method accepts an
 * arbitrary `string`, so any property name (including ones not listed here) still
 * works. Use these for autocomplete and typo-safety on the names you know.
 *
 * @experimental
 */
/** Well-known vCard property names (RFC 6350 and common Apple extensions). */
declare const VCARD: {
    /** Formatted display name (`FN`). Mandatory in a vCard. */
    readonly FN: "FN";
    /** Structured name: `family;given;additional;prefixes;suffixes` (`N`). */
    readonly N: "N";
    /** Nickname(s) (`NICKNAME`). */
    readonly NICKNAME: "NICKNAME";
    /** Organization: `org;unit1;unit2` (`ORG`). */
    readonly ORG: "ORG";
    /** Job title (`TITLE`). */
    readonly TITLE: "TITLE";
    /** Telephone number (`TEL`). */
    readonly TEL: "TEL";
    /** Email address (`EMAIL`). */
    readonly EMAIL: "EMAIL";
    /** Structured postal address (`ADR`). */
    readonly ADR: "ADR";
    /** Associated URL (`URL`). */
    readonly URL: "URL";
    /** Instant-messaging handle (`IMPP`). */
    readonly IMPP: "IMPP";
    /** Birthday (`BDAY`). */
    readonly BDAY: "BDAY";
    /** Free-form note (`NOTE`). */
    readonly NOTE: "NOTE";
    /** Photo, inline base64 or a URI (`PHOTO`). */
    readonly PHOTO: "PHOTO";
    /** Tags / groups, comma-separated (`CATEGORIES`). */
    readonly CATEGORIES: "CATEGORIES";
    /** Stable unique identifier (`UID`). */
    readonly UID: "UID";
    /** Revision timestamp (`REV`). */
    readonly REV: "REV";
    /** Product identifier of the authoring application (`PRODID`). */
    readonly PRODID: "PRODID";
    /** Social-media profile, iCloud extension (`X-SOCIALPROFILE`). */
    readonly X_SOCIALPROFILE: "X-SOCIALPROFILE";
    /** IM service name, iCloud extension (`X-SERVICE-TYPE`). */
    readonly X_SERVICE_TYPE: "X-SERVICE-TYPE";
    /** Custom label for a grouped property, iCloud extension (`X-ABLabel`). */
    readonly X_ABLABEL: "X-ABLabel";
    /** Labeled custom date such as an anniversary, iCloud extension (`X-ABDATE`). */
    readonly X_ABDATE: "X-ABDATE";
    /** Labeled related person, iCloud extension (`X-ABRELATEDNAMES`). */
    readonly X_ABRELATEDNAMES: "X-ABRELATEDNAMES";
};
/** Well-known vCard parameter names (lowercased, matching the parsed form). */
declare const VPARAM: {
    /** Property kind/label, e.g. `home`, `work`, `cell` (`TYPE`). */
    readonly TYPE: "type";
    /** Value-type override, e.g. `uri` (`VALUE`). */
    readonly VALUE: "value";
    /** Inline binary encoding, e.g. `b` for base64 (`ENCODING`). */
    readonly ENCODING: "encoding";
};
/** Union of the well-known property names in {@link VCARD}. */
type KnownProperty = (typeof VCARD)[keyof typeof VCARD];
/** Union of the well-known parameter names in {@link VPARAM}. */
type KnownParam = (typeof VPARAM)[keyof typeof VPARAM];

/**
 * Create a CardDAV adapter for reading and writing contacts. Defaults to Apple
 * iCloud Contacts; works with any CardDAV server. Credentials come from context
 * `carddav` config (named accounts). The `action` flag selects the role, the
 * same way the mail adapter does.
 *
 * The body is a plain {@link VCardBody} (a `version` plus a property list), not
 * a typed contact. Wrap it in a {@link VCard} (`VCard.wrap(body)`,
 * `VCard.create()`, `VCard.parse(string)`) for ergonomic reads and edits, then
 * read `.data` to put the plain body back. Identity (`url`/`uid`/`etag`) lives
 * on the exchange headers. Reading is lossless and a write replaces the card
 * with the document you hand back.
 *
 * **Read (`.from()` / `.enrich()`):** call with no `action`. `.from(carddav())`
 * emits one {@link VCardBody} per address-book entry; `.enrich(carddav())`
 * fetches all cards and the `VCardBody[]` replaces the body (pass an
 * aggregator such as `only()` to merge instead).
 *
 * **Write (`.to()`):** `action: 'save'` upserts (writes to the card's `url`,
 * else creates), `'create'` always inserts, `'update'` writes to the card's
 * `url` (else `RC5014`). The send is void: the card body flows through
 * unchanged and the write receipt (`routecraft.carddav.url` / `.uid` /
 * `.etag`, plus `.created` for insert-vs-update) lands on the same headers
 * the read side sets.
 *
 * **Delete (`.to()`):** `action: 'delete'` removes the contact resolved from the
 * body (`url`/`uid`), the read headers, or a custom `target` extractor. The
 * deleted resource's identity lands on the receipt headers.
 *
 * @example
 * ```typescript
 * // Read all contacts (source).
 * craft().from(carddav()).to(processCard());
 *
 * // Read, edit one property, write back (everything else is preserved).
 * craft()
 *   .from(carddav())
 *   .transform((card) => card.set("NOTE", "synced from CRM"))
 *   .to(carddav({ action: "update" }));
 *
 * // Delete stale contacts.
 * craft().from(carddav()).filter(isStale).to(carddav({ action: "delete" }));
 * ```
 *
 * @experimental
 */
declare function carddav(options?: CarddavServerOptions): Source<VCardBody> & Enricher<unknown, VCardBody[]>;
declare function carddav(options: CarddavClientOptions & {
    action: "save" | "create" | "update";
}): Destination<VCardBody>;
declare function carddav(options: CarddavClientOptions & {
    action: "delete";
}): Destination<unknown>;

/**
 * Create a telemetry plugin that instruments the framework with
 * OpenTelemetry traces and persists data to SQLite for the TUI.
 *
 * When no `tracerProvider` is given and `disableSqlite` is false (default),
 * events are persisted to a local SQLite database for the TUI to read.
 *
 * @param options - TracerProvider, SQLite path, and buffer configuration
 * @returns A CraftPlugin instance
 *
 * @example
 * ```typescript
 * import { telemetry } from "@routecraft/routecraft";
 *
 * // Default SQLite backend
 * telemetry()
 *
 * // Export to Better Stack via OTLP
 * telemetry({ tracerProvider: myTracerProvider })
 *
 * // External only, no SQLite
 * telemetry({ tracerProvider, disableSqlite: true })
 * ```
 */
declare function telemetry(options?: TelemetryOptions): CraftPlugin;

/**
 * Options accepted by {@link SqliteConnection.open}.
 */
interface SqliteConnectionOptions {
    /** Path to the SQLite database file. */
    dbPath?: string;
    /** Enable WAL mode (defaults to `true`). */
    walMode?: boolean;
    /**
     * Maximum number of exchange rows to retain.
     * Older rows are pruned on startup and periodically.
     * Set to `0` to disable exchange pruning. Defaults to `0` (disabled).
     */
    maxExchanges?: number;
    /**
     * Maximum number of event rows to retain.
     * Older rows are pruned on startup and periodically.
     * Set to `0` to disable event pruning. Defaults to `0` (disabled).
     */
    maxEvents?: number;
}
/**
 * Shared SQLite connection for telemetry.
 *
 * Encapsulates database opening, WAL mode, DDL execution, and data
 * retention pruning. Pruning is a storage-layer concern and is managed
 * entirely within this class.
 *
 * Used by both {@link SqliteSpanProcessor} and {@link SqliteEventWriter}.
 *
 * Backed by whichever synchronous driver the runtime provides:
 * `bun:sqlite` under Bun, `better-sqlite3` as an optional peer under Node.
 * When neither resolves, {@link open} returns `null` and the calling plugin
 * disables the SQLite path with a warn log, leaving an OTLP exporter
 * configured via `telemetry({ tracerProvider })` as the way to keep
 * telemetry flowing.
 */
declare class SqliteConnection {
    readonly db: TelemetryDatabase;
    readonly logger: TelemetryLogger | undefined;
    private pruneTimer;
    private constructor();
    /**
     * Open (or create) the telemetry database.
     *
     * When `maxExchanges` or `maxEvents` are greater than 0, the connection
     * prunes on startup and schedules periodic pruning automatically.
     * The timer is stopped when {@link close} is called.
     *
     * @param options - Database path and retention limits.
     * @param logger - Optional telemetry logger for the failure paths.
     * @param loaders - Driver loader injection point for tests.
     * @returns A connection, or `null` when no driver resolved or the
     *   database could not be opened.
     */
    static open(options?: SqliteConnectionOptions, logger?: TelemetryLogger, loaders?: SqliteDriverLoaders): Promise<SqliteConnection | null>;
    /**
     * Run an initial prune and schedule periodic pruning if limits are set.
     */
    private startPruning;
    /**
     * Delete old rows beyond the configured retention limits.
     * Uses ROWID ordering for efficient deletion without scanning timestamps.
     */
    private prune;
    close(): void;
}
/**
 * The shared minimal surface plus the one member telemetry needs on top:
 * batched event inserts run inside a transaction. Both drivers expose it
 * with this shape.
 */
interface TelemetryDatabase extends SqliteDatabase {
    transaction<T>(fn: (...args: T[]) => void): (...args: T[]) => void;
}

/**
 * Semantic attribute keys used by the telemetry plugin to tag spans.
 */
declare const ATTR: {
    readonly SPAN_KIND: "routecraft.span.kind";
    readonly ROUTE_ID: "routecraft.route.id";
    readonly CONTEXT_ID: "routecraft.context.id";
    readonly EXCHANGE_ID: "routecraft.exchange.id";
    readonly CORRELATION_ID: "routecraft.correlation.id";
    readonly DURATION_MS: "routecraft.duration_ms";
    readonly DROP_REASON: "routecraft.drop.reason";
    readonly DROPPED: "routecraft.dropped";
    readonly ERROR: "routecraft.error";
    readonly OPERATION_TYPE: "routecraft.operation.type";
    readonly ADAPTER_ID: "routecraft.adapter.id";
};
/**
 * Span kind values used to identify what a span represents.
 */
declare const SPAN_KIND: {
    readonly ROUTE: "route";
    readonly EXCHANGE: "exchange";
    readonly OPERATION: "operation";
};
/**
 * Duck-typed OTel ReadableSpan for use in `onEnd`.
 * Only the fields SqliteSpanProcessor actually reads.
 */
interface OTelReadableSpan {
    name: string;
    attributes: Record<string, unknown>;
    status: {
        code: number;
        message?: string;
    };
    startTime: [number, number];
    endTime: [number, number];
}
/**
 * Duck-typed OTel Span for use in `onStart`.
 */
interface OTelSpan {
    setAttribute(key: string, value: unknown): void;
    attributes?: Record<string, unknown>;
    spanContext?(): {
        traceId: string;
        spanId: string;
    };
}
/**
 * SQLite-backed SpanProcessor that writes route and exchange lifecycle
 * data to the `routes` and `exchanges` tables.
 *
 * Implements the OTel SpanProcessor interface via duck typing so
 * `@opentelemetry/sdk-trace-base` is not required at runtime for
 * the default SQLite path.
 *
 * The plugin calls `onStart`/`onEnd` directly from event handlers;
 * it also works when registered with a `BasicTracerProvider` for
 * external export scenarios.
 */
declare class SqliteSpanProcessor {
    private readonly logger;
    private readonly upsertRouteStmt;
    private readonly updateRouteStatusStmt;
    private readonly insertExchangeStmt;
    private readonly updateExchangeCompletedStmt;
    private readonly updateExchangeFailedStmt;
    private readonly updateExchangeDroppedStmt;
    private readonly upsertSnapshotStmt;
    constructor(connection: SqliteConnection);
    writeRoute(routeId: string, contextId: string, registeredAt: string): void;
    updateRouteStatus(routeId: string, contextId: string, status: string): void;
    writeExchange(exchangeId: string, routeId: string, contextId: string, correlationId: string, startedAt: string): void;
    completeExchange(exchangeId: string, contextId: string, completedAt: string, durationMs: number): void;
    failExchange(exchangeId: string, contextId: string, completedAt: string, durationMs: number, error: string): void;
    dropExchange(exchangeId: string, contextId: string, droppedAt: string, reason: string): void;
    writeSnapshot(exchangeId: string, contextId: string, headers: string, body: string | null, truncated: boolean): void;
    onStart(span: OTelSpan, _parentContext?: unknown): void;
    onEnd(span: OTelReadableSpan): void;
    forceFlush(): Promise<void>;
    shutdown(): Promise<void>;
}

/**
 * Buffered batch writer for the SQLite `events` table.
 *
 * Accumulates events in memory and flushes them in batches
 * (by size threshold or time interval) for performance.
 *
 * This is a SQLite-specific materialized view of the raw event stream.
 * External backends derive the same view from trace data.
 */
declare class SqliteEventWriter {
    private readonly logger;
    private readonly batchSize;
    private readonly flushIntervalMs;
    private readonly insertStmt;
    private readonly insertManyTxn;
    private buffer;
    private flushTimer;
    constructor(connection: SqliteConnection, batchSize: number, flushIntervalMs: number);
    write(event: TelemetryEvent): void;
    flush(): void;
    close(): void;
}

/**
 * A database file path as the drivers want it: absolute, or the
 * `":memory:"` sentinel untouched.
 *
 * Shared because a store that resolves the path differently in two places
 * (an existence probe and the open beside it) reports an empty store while
 * a database sits on disk holding its records.
 */
declare function resolveDatabasePath(path: string): string;
/**
 * Whether a driver error is SQLite reporting lock contention rather than a
 * permanent fault. Both drivers surface it in the message; better-sqlite3
 * additionally sets a `code`.
 *
 * Shared because this is knowledge about the drivers rather than about any
 * one store, and a store that answers a transient lock as a permanent
 * failure sends its caller to the wrong remedy.
 */
declare function isSqliteBusy(cause: unknown): boolean;
/**
 * Which store a database file belongs to, stamped into
 * `PRAGMA application_id` so a store can tell its own file from another's.
 *
 * Every store in the repository writes into `.routecraft/` and versions
 * itself through `PRAGMA user_version`, which is one integer per file. Two
 * stores pointed at one path therefore cannot both be satisfied, and
 * without an identity the loser can only report the version it found,
 * which reads as "upgrade your build" for a file no build will ever
 * understand.
 *
 * The values are the ASCII of a four-letter tag, which is what
 * `application_id` is conventionally used for and what `file` and
 * `sqlite3` will show an operator.
 */
declare const SQLITE_APPLICATION_IDS: {
    /** "RCDE", the deferral store. */
    readonly deferral: 1380140101;
    /** "RCSE", the agent session store. */
    readonly session: 1380143941;
};
/** A stamped identity, or 0 for a file no build has claimed. */
type SqliteApplicationId = (typeof SQLITE_APPLICATION_IDS)[keyof typeof SQLITE_APPLICATION_IDS] | 0;
/** The tag a stamped file carries, for naming it in a refusal. */
declare function sqliteApplicationName(id: number): string | undefined;
/** What went wrong in {@link migrateSqlite}, for the consumer's own error. */
interface SqliteMigrationFailure {
    /**
     * `foreign` is a file belonging to a different store, which is a
     * configuration mistake rather than a version problem; `downgrade` is a
     * file written by a newer build of THIS store, which no migration can
     * repair; `migrate` is a statement that failed.
     */
    readonly kind: "foreign" | "downgrade" | "migrate";
    readonly cause: unknown;
    /** The version the file is on. */
    readonly current: number;
    /**
     * The file's own tables, so a refusal can say what the file actually is
     * rather than only what it is not. Empty for a file with no schema.
     */
    readonly tables: readonly string[];
    /**
     * The identity stamped on the file: another store's id, or 0 when the
     * file predates stamping and was identified by its tables instead.
     */
    readonly applicationId: number;
}
/**
 * Bring a database's schema up to date from `PRAGMA user_version`, inside
 * one transaction so an interrupted upgrade leaves the file on its previous
 * version rather than half way between two.
 *
 * The version is read INSIDE the write transaction. Two processes starting
 * against one file would otherwise both read version 0, both try to create
 * the tables, and the loser fail on an existing table, which for a store
 * that falls back to memory means losing durability at exactly the moment
 * a deployment restarts.
 *
 * Before any of that, the file is checked to be this store's own. A store
 * adopts a file only when the file is empty, or already carries this
 * store's identity, or predates stamping and holds this store's own table.
 * Anything else is refused as `foreign`, because two stores sharing one
 * path is a configuration mistake that no migration can resolve.
 *
 * @param options.schemaVersion - The version this build understands.
 * @param options.migrations - Forward-only statements; index `n` migrates
 *   version `n` to `n + 1`, so a fresh file runs them all.
 * @param options.applicationId - This store's identity, stamped into
 *   `PRAGMA application_id` on adoption.
 * @param options.identityTable - A table this store's schema always has,
 *   used to adopt files written before stamping existed.
 * @param options.onFailure - Builds the store's own error for a failure.
 *   The returned error is thrown as it is, so each store keeps its code.
 */
declare function migrateSqlite(db: SqliteDatabase, options: {
    schemaVersion: number;
    migrations: ReadonlyArray<string>;
    applicationId: SqliteApplicationId;
    identityTable: string;
    onFailure: (failure: SqliteMigrationFailure) => Error;
}): void;
/**
 * Say what a foreign file actually is, for the refusal that names it.
 *
 * A stamped file names itself. One that predates stamping is described by
 * its tables, which is the only evidence there is, and is worth printing
 * because it is what an operator sees running `sqlite3` against the file.
 */
declare function describeSqliteFile(failure: SqliteMigrationFailure): string;

/** A path already held by a different subsystem. */
interface SqlitePathConflict {
    /** The path as configured, before resolution, for the message. */
    readonly path: string;
    /** The subsystem that claimed it first, named as its setting. */
    readonly held: string;
    /** The subsystem claiming it now. */
    readonly claimant: string;
}
/**
 * Record that `claimant` opens the database at `path` in this context, and
 * refuse when another subsystem already opened the same file.
 *
 * `":memory:"` is exempt: each in-memory database is private to the
 * connection that opened it, so two stores asking for one never meet.
 *
 * A claimant holds at most one path, because each names one setting and a
 * setting chooses one store. Claiming a second path releases the first: an
 * unconfigured default is resolved and later replaced by the block that
 * configures it, and the path the default gave up must not go on blocking
 * another store that legitimately wants it.
 *
 * @param options.scope - The context the claim belongs to.
 * @param options.path - Database path as configured.
 * @param options.claimant - The setting that chose it, e.g.
 *   `sessions: { store }`, quoted back to the reader in the error.
 * @param options.onConflict - Builds the caller's own error, so each
 *   subsystem keeps its code. The returned error is thrown as it is.
 */
declare function claimDatabasePath(options: {
    scope: object;
    path: string;
    claimant: string;
    onConflict: (conflict: SqlitePathConflict) => Error;
}): void;
/**
 * Give up whatever this claimant holds, for a store that resolved to a
 * backend with no file at all: the memory fallback, or one a caller
 * supplied. Those never reach {@link claimDatabasePath}, so without this
 * the path an earlier default claimed would go on blocking a store that
 * legitimately wants it.
 */
declare function releaseClaimant(options: {
    scope: object;
    claimant: string;
}): void;

/**
 * In-process deferral store.
 *
 * The default under `testContext()` and the fallback when no durable
 * backend is available. Everything it holds dies with the process, so it is
 * the right choice for tests and for a route whose deferrals are
 * genuinely ephemeral, and the wrong choice for the feature's headline
 * promise: an exchange deferred here does not survive a restart. The store
 * factory logs a warning whenever it falls back to this backend for that
 * reason.
 *
 * Records are cloned on the way in and on the way out, so a caller cannot
 * reach into stored state through a reference it kept, and the backend
 * behaves like a real one that round-trips through storage.
 *
 * The compare-and-swap methods complete within a single event-loop turn
 * (they never await between reading the status and writing it), which is
 * what makes them atomic on this backend.
 */
declare class MemoryDeferralStore implements DeferralStore {
    #private;
    /**
     * The live record map, bypassing the transitions and the clone-on-read
     * boundary. A test seam: the purge contract must hold for shapes the
     * public transitions cannot produce (a settled record with no outcome),
     * and proving that on this backend requires injecting one.
     * Sqlite's equivalent seam is raw SQL against the database file.
     *
     * @internal
     */
    static unsafeRecords(store: MemoryDeferralStore): Map<string, Deferral>;
    create(record: NewDeferral): Promise<void>;
    get(id: string): Promise<Deferral | undefined>;
    markResumed(id: string, resumption: DeferralResumption): Promise<DeferralCasResult>;
    claimExpiry(id: string, at: Date): Promise<DeferralCasResult>;
    markExpired(id: string): Promise<DeferralCasResult>;
    markDenied(id: string, reason?: string): Promise<DeferralCasResult>;
    releaseClaims(before: Date): Promise<number>;
    replaceStepState(id: string, expected: string, stepState: unknown): Promise<DeferralCasResult>;
    recordContinuation(id: string, continuation: SerializedOutcome): Promise<void>;
    findExpired(now: Date, limit: number, after?: ExpiredScanCursor): Promise<Deferral[]>;
    resumedWithoutContinuation(limit?: number): Promise<Deferral[]>;
    pending(): Promise<PendingDeferralSummary>;
    list(query: DeferralListQuery): Promise<DeferralSummary[]>;
    purgeSettled(before: Date): Promise<number>;
    /**
     * Releases nothing, because there is nothing to release. It deliberately
     * does NOT clear the records: `close()` means "release backend
     * resources" on every other backend, and a call that is a handle release
     * on sqlite but a data wipe here would make the two non-substitutable
     * for any code written against the interface. The map is collected with
     * the store. Use {@link MemoryDeferralStore.reset} to discard records.
     */
    close(): Promise<void>;
    /**
     * Discard every record. Not part of {@link DeferralStore}: wiping is
     * specific to this backend, and a test wanting isolation should
     * construct a fresh store rather than rely on a method an arbitrary
     * backend may not have.
     */
    reset(): void;
}

/**
 * Default location of the deferral database, relative to the working
 * directory. Deployments that mount a volume (the Docker showcase does)
 * override it via `deferral: { store: { path } }` or
 * `ROUTECRAFT_DEFERRAL_STORE`.
 */
declare const DEFAULT_DEFERRAL_DB_PATH = ".routecraft/deferrals.db";
/**
 * Durable deferral store on SQLite.
 *
 * One implementation over two drivers: `bun:sqlite` under Bun and
 * `better-sqlite3` under Node. Both are synchronous, which is what makes
 * the compare-and-swap methods genuinely atomic here: a single `UPDATE
 * ... WHERE state = 'waiting' AND claimed_at IS NULL` either changes one row
 * or none, and the driver returns which. See `shared/sqlite/driver.ts` for the runtime-split
 * decision, the version matrix behind it, and the graduation condition for
 * `node:sqlite`.
 *
 * Open it with {@link SqliteDeferralStore.open}; the constructor is
 * private because a store is only usable after its schema has been
 * migrated.
 */
declare class SqliteDeferralStore implements DeferralStore {
    #private;
    /** Which driver backs this store. Surfaced for logging and tests. */
    readonly driver: ResolvedSqliteDriver["name"];
    private constructor();
    /**
     * Open (creating if absent) the deferral database and bring its schema
     * up to date.
     *
     * @param options.path - Database file path, absolute or relative to the
     *   working directory. `":memory:"` opens a private in-process database,
     *   which is useful for exercising the sqlite code paths in tests without
     *   touching disk.
     * @param options.loaders - Driver loader injection point for tests.
     * @throws RC5017 under Node when `better-sqlite3` is not installed.
     */
    static open(options: {
        path: string;
        loaders?: SqliteDriverLoaders;
    }): Promise<SqliteDeferralStore>;
    create(record: NewDeferral): Promise<void>;
    get(id: string): Promise<Deferral | undefined>;
    markResumed(id: string, resumption: DeferralResumption): Promise<DeferralCasResult>;
    claimExpiry(id: string, at: Date): Promise<DeferralCasResult>;
    markExpired(id: string): Promise<DeferralCasResult>;
    markDenied(id: string, reason?: string): Promise<DeferralCasResult>;
    releaseClaims(before: Date): Promise<number>;
    /**
     * Unlike the `mark*` transitions this cannot be one conditional `UPDATE`:
     * the compare is a digest of a JSON column, which SQLite cannot compute.
     * The read and the write therefore share one `BEGIN IMMEDIATE`, which
     * takes the write lock at the read, so no other connection can move the
     * row in between. That is the same guarantee the single-statement form
     * gives, bought with a lock held for one extra statement.
     */
    replaceStepState(id: string, expected: string, stepState: unknown): Promise<DeferralCasResult>;
    recordContinuation(id: string, continuation: SerializedOutcome): Promise<void>;
    findExpired(now: Date, limit: number, after?: ExpiredScanCursor): Promise<Deferral[]>;
    list(query: DeferralListQuery): Promise<DeferralSummary[]>;
    resumedWithoutContinuation(limit?: number): Promise<Deferral[]>;
    pending(): Promise<PendingDeferralSummary>;
    purgeSettled(before: Date): Promise<number>;
    close(): Promise<void>;
}

/**
 * Digest of a deferral's `stepState` slot, used as the compare half of
 * the store's `replaceStepState` compare-and-swap.
 *
 * A digest rather than the value itself, for two reasons. The slot holds an
 * arbitrarily large blob (an agent's whole message thread is the motivating
 * case), and shipping it back to the store to be compared would double the
 * write. And equality on the blob is only meaningful under a canonical
 * form: the two backends round-trip it through different machinery
 * (`structuredClone` and `JSON.parse`), so key order is not a property a
 * caller can rely on. Hashing the canonical rendering makes the comparison
 * structural.
 *
 * A record with no step state gets its own digest, distinct from one
 * holding `null`, rather than being special-cased at every call site. That
 * makes "the record had no step state" an expectation a caller can hold and
 * lose like any other.
 */
declare function stepStateFingerprint(stepState: unknown): string;

/**
 * What a defer-capable adapter resolves when it raises a deferral from
 * inside its own execution: the same pieces `.defer({ schema, ttl })`
 * declares statically, plus the closure state only the step can produce.
 */
interface DeferSignalRequest {
    /**
     * Schema describing what a valid resume payload looks like. Optional: absent
     * declares no contract at all, and the descriptor records that, so a site
     * edited from a declared schema to none moves the digest rather than
     * quietly accepting anything.
     *
     * Folded into the continuation hash and rendered onto the `Deferred`
     * acknowledgment. For a re-entrant site it is descriptive only at resume
     * time: the live schema exists in the raising step's own code and cannot
     * be read back off the route, so revival delivers the raw payload and the
     * step is the validator. See `DeferSite.reentrant`.
     */
    readonly schema?: StandardSchemaV1;
    /** How long the deferral stays resumable. Absent means the context default. */
    readonly ttl?: Duration;
    /**
     * Anything the resuming route needs to decide who may resume. Plain
     * JSON, persisted verbatim, never interpreted by the framework.
     */
    readonly meta?: unknown;
    /**
     * Identity of the call this deferral belongs to, so a batch that mints one
     * credential per call cannot have one call's recipient resume another's
     * deferral.
     */
    readonly callBinding?: string;
    /**
     * Closure state owned by the raising step, persisted verbatim in the
     * record's `stepState` slot and handed back to the step when the
     * exchange resumes. Subject to the same plain-JSON rule as the exchange
     * (`RC5042`).
     */
    readonly stepState?: unknown;
}
/**
 * The throwable a defer-capable adapter raises to defer the exchange it is
 * executing.
 *
 * An `Error` subclass on purpose: the signal is control flow, and the
 * `.to()` / `.enrich()` step that hosts the site converts it into the
 * ordinary `defer` StepOutcome before any wrapper can observe it, but a
 * signal raised somewhere without a revivable site (a `.tap()` snapshot, an
 * unbuilt route, a synthetic dispatch) surfaces as a legible failure rather
 * than an opaque thrown object.
 *
 * Never `instanceof`-checked: the brand survives duplicate copies of this
 * package in one process, which is the same reason every other framework
 * brand uses `Symbol.for`.
 */
declare class DeferSignal extends Error {
    readonly name = "DeferSignal";
    readonly request: DeferSignalRequest;
    constructor(request: DeferSignalRequest);
}
/**
 * Whether a thrown value is the framework's own {@link DeferSignal}.
 *
 * Public alongside {@link DeferSignal} for the same audience: a runtime
 * hosting defer-capable steps (the agent tier is the shipped one) uses it
 * to let a raised deferral pass through its own error accounting instead
 * of reporting a deferral as a failure.
 */
declare function isDeferSignal(value: unknown): value is DeferSignal;

/**
 * Store a continuation for an exchange that completes normally.
 *
 * A `.defer()` deferral ends the run and answers with the acknowledgment. An
 * aside deferral does not: the run goes on to complete, and what is stored is
 * a way to re-enter the route at `site` later, on this process, with the
 * exchange's body and headers exactly as a deferral stores them. The agent
 * tier uses it for a session turn that ends with work still outstanding
 * (a background tool running, messages queued): the caller has its reply,
 * and the continuation is what a completion revives to run the next turn
 * and the route's downstream steps.
 *
 * No `route:exchange:deferred` is emitted and the exchange is not marked
 * deferred, because it is not: it completes, and one `route:exchange:started`
 * must reach exactly one terminal. Revival is a first-class run of the
 * route with its own pair. The record carries no deadline, since what it
 * waits on has none the framework knows.
 *
 * @param stepState - Built from the deferral id, so the state a revival
 *   hands back can name the record it came from
 * @param announce - Awaited with the id before the record is written, so
 *   the caller's own record can name the deferral from the first write on
 * @returns The deferral id, which `reviveDeferral` takes back
 * @throws RC5052 without a deferral runtime, RC5042 when the exchange
 *   cannot be persisted, RC5044 when the store write fails
 *
 * @internal
 */
declare function deferAside(context: CraftContext, exchange: Exchange, site: DeferRequest["site"], routeId: string, stepState: (deferralId: string) => unknown, announce?: (deferralId: string) => Promise<void>): Promise<{
    deferralId: string;
}>;

export { ANALYSIS_HEADER_NAMES, ATTR, type ActorMatcher, type ActorSpec, type Adapter, type AdapterOverride, type AdapterSendCall, type AdapterSourceCall, type Aggregator, type AnyRouteBuilder, type ApiKeyAuthOptions, type AuthRejectionReason, type AuthorizeOptions, BatchConsumer, type BatchOptions, type BuilderState, CARDDAV_CLIENT_MANAGER, type CacheOptions, type CacheProvider, CacheWrapperStep, type CallableAuthenticator, type CallableDelegator, type CallableDestination, type CallableEnricher, type CallableSource, type CallableTransformer, type CallableValidator, type CallerRefusal, type CallerRefusalOrigin, type Capability, type CarddavAccountConfig, type CarddavAction, CarddavAdapter, CarddavClientManager, type CarddavClientOptions, type CarddavContextConfig, type CarddavDriverClient, CarddavHeaders, type CarddavOptions, type CarddavServerOptions, type CarddavTargetExtractor, type ChoiceDescriptor, type ChoicePredicate, type CircuitBreakerOptions, type CircuitBreakerState, CircuitBreakerWrapperStep, type CircuitState, type ClaimMappers, type Comparator, type ConcurrencyOptions, ConcurrencyWrapperStep, type ConfigApplier, type Consumer, type ConsumerDeps, type ConsumerType, ContextBuilder, type ContextState, type CosineOptions, CraftClient, type CraftConfig, CraftContext, type CraftPlugin, type CronExpression, CronHeaders, type CronOptions, type CsvAdapter, type CsvChunkedAdapter, type CsvData, type CsvFileOptions, CsvHeaders, type CsvOptions, type CsvRow, type CsvTransformerOptions, type CursorScope, type DAVAddressBookLike, type DAVVCardLike, DEFAULT_CARDDAV_SERVER_URL, DEFAULT_DEFERRAL_DB_PATH, DEFAULT_ON_PARSE_ERROR, DEFAULT_PAGE_SIZE, DEFAULT_SHUTDOWN_TIMEOUT_MS, DEFERRAL_RUNTIME, DEFERRAL_SECRET_ENV, DEFERRAL_STORE_ENV, DEFERRED_JSON_SCHEMA, type DebounceOptions, DebounceStep, type DedupeOptions, DedupeStep, DefaultExchange, DefaultRoute, type DeferOptions, DeferSignal, type DeferSignalRequest, type DeferSite, type Deferral, type DeferralAffordance, type DeferralCasResult, type DeferralConfig, DeferralHeaders, type DeferralListCursor, type DeferralListQuery, type DeferralOutcome, type DeferralRecordView, type DeferralResumption, type DeferralRuntime, type DeferralSchema, type DeferralState, type DeferralStore, type DeferralStoreConfig, type DeferralSummary, type DeferralWaitingFor, type Deferred, DelayWrapperStep, type DelegateOptions, type DelegateStepOptions, type DelegationClaims, type Destination, type DirectBaseOptions, type DirectChannel, type DirectChannelType, type DirectClientOptions, type DirectConfig, type DirectEndpointRegistry, type DirectOptions, type DirectServerOptions, type DirectoryAdapter, type DirectoryChunkedAdapter, type DirectoryEntry, type DirectoryOptions, DispatchStep, type DispatchStrategy, type DispatchStrategyName, type DispatchTarget, type DslRegistration, type Duration, type DurationUnit, type EmailAddress, type EnablementOptions, type EnablementPredicate, type EnablementState, type EnablementVerdict, type EnrichAggregator, type Enricher, type ErrorCodeRegistry, type ErrorHandler, ErrorWrapperStep, type EventDetailsMap, type EventFilter, type EventHandler, type EventName, type EventPayload, type EventSourceOptions, type Exchange, type ExchangeHeaders, type ExchangeOf, type ExpiredScanCursor, type FailureDomain, type FetchedBody, type FieldTransform, type FileAdapter, FileHeaders, type FileOptions, type Filter, type FilterDropResult, type ForwardFn, type ForwardHop, type ForwardType, type GeneratorSource, type Grant, type GroupOptions, HTTP_REDIRECT_STATUSES, type HeaderLiteral, type HeaderSetter, type HeaderValue, HeadersKeys, type Health, type HealthChange, type HealthComponent, type HealthDetailValue, type HealthDetails, type HealthDetailsExposure, type HealthLedger, type HealthReport, type HealthStatus, type HealthView, type HtmlAdapter, type HtmlOptions, type HtmlResult, type HttpAuth, type HttpBuiltinOptions, type HttpBuiltinsOptions, type HttpClientOptions, type HttpConfig, type HttpCorsOptions, type HttpCorsOriginResolver, type HttpMethod, type HttpMount, type HttpMountAuth, type HttpMountAuthPolicy, type HttpMountContext, type HttpOpenApiBuiltinOptions, type HttpOpenApiInfo, type HttpPluginOptions, type HttpRedirectMode, type HttpRequestBody, type HttpRequestPayload, type HttpRespondContext, type HttpRespondRequest, type HttpResponder, type HttpResponseBodyMode, type HttpResponseDescriptor, type HttpResponseHint, type HttpResult, type HttpServerDefinition, type HttpServerOptions, type HttpWebhookSignatureOptions, type HttpWebhookSignatureScheme, type Indicator, type IndicatorDefinition, type InputValidationFailure, type InsufficientAuthority, type JsonFileAdapterType, type JsonFileOptions, type JsonOptions, type JsonTransformerOptions, type JsonlAdapter, type JsonlChunkedAdapter, type JsonlFileOptions, JsonlHeaders, type JsonlOptions, type JsonlTransformerOptions, type JwksOptions, type JwtAudience, type JwtAuthOptions, type JwtHmacOptions, type JwtRsaOptions, type KeepOptions, type KeepRule, type KeepRules, type KnownErrorCategory, type KnownParam, type KnownProperty, type KnownTag, type LivenessReport, type LogFileDiversion, type LogLevel, type LogOptions, MANUAL_REFRESH, type MailAccountConfig, type MailAccountImapConfig, type MailAccountSmtpConfig, type MailAction, type MailAppendAction, type MailAttachment, type MailAuth, type MailBody, MailClientManager, type MailClientOptions, type MailContextConfig, type MailCopyAction, type MailDeleteAction, type MailFetchResult, type MailFlagAction, type MailFolderAdapter, MailHeaders, type MailMessage, type MailMoveAction, type MailOptions, type MailReconnectOptions, type MailSendPayload, type MailSender, type MailServerOptions, type MailTargetExtractor, type MailUnflagAction, type MaskFn, type MaskRules, MemoryCacheProvider, type MemoryCacheProviderOptions, MemoryDeferralStore, type MergedOptions, type Message, MulticastStep, NEVER_FORCE, type NewDeferral, type OAuthPrincipal, type OAuthTokenVerifier, type OAuthValidatorAuthOptions, OPS_HEALTH_STATE, OPS_RESOURCES, OPS_SCOPE_DISPATCH, OPS_SCOPE_EVENTS, OPS_SCOPE_INTROSPECTION, type OnParseError, OperationType, type OpsBearerToken, OpsClientError, type OpsConfig, type OpsDeferralFilter, type OpsDeferralSummary, type OpsDispatchOutcome, type OpsEventTailItem, type OpsFailureKind, type OpsHealthOptions, type OpsHttpClient, type OpsHttpClientOptions, type OpsPage, type OpsPluginOptions, type OpsResource, type OpsRouteDetail, type OpsRouteFilter, type OpsRouteQuery, type OpsRouteSchemas, type OpsRouteSummary, type OpsTier, type OpsTiers, type OtherwiseDescriptor, type OutputValidationFailure, PROTECTED_RESOURCE_METADATA_PATH, type PageFilter, type Path, PathBuilder, type PathClaim, type PathState, type PendingDeferralSummary, type PreFromBuilder, type PreFromStaging, type PreFromTypedBuilder, type PrimitiveKind, type Principal, type PrincipalClaims, type PrincipalProfile, type PrincipalRef, type ProcessingQueue, type Processor, type ProjectDiscoverer, type ProjectDiscovererOptions, type ProjectDiscoveryContext, type ProtectedResourceMetadata, type ProtectedResourceMetadataInput, type QueryParams, RC, type RCCode, type RCMeta, RC_ADAPTER_OVERRIDES, RUNNER_ARGV, type Recovery, type RecoveryDrop, type RecoveryRethrow, type RefreshCadence, type RegisteredDirectEndpoint, type RegisteredProjectDiscoverer, type RemoteDefinition, type RemotesConfig, type RemotesPluginOptions, type ResolveBody, type ResolveKey, type ResolvedCarddavConnection, type ResolvedCircuitBreakerOptions, type ResolvedDedupeOptions, type ResolvedRetryOptions, type ResolvedSampleOptions, type ResolvedSqliteDriver, type ResolvedThrottleOptions, type ResolvedTimeoutOptions, type ResumeAcknowledgment, type ResumeAuthorizer, type ResumeAuthorizerInput, type ResumeMapper, type ResumeOptions, type ResumeRequest, type RetryOptions, RetryWrapperStep, type Retyped, type Route, RouteBuilder, type RouteDefinition, type RouteDiscovery, type RouteEnablement, type RouteLifecycle, type RouteOptions, type RouteSchemas, RoutecraftError, type RoutecraftHeaders, type RuntimeVersion, SOURCE_FIXTURE, SPAN_KIND, SQLITE_APPLICATION_IDS, type SampleOptions, SampleStep, type SendContext, type SendOverrideHandler, type SerializedExchange, type SerializedOutcome, type ServerDefinitions, type SetBody, type SetDeferral, type ShutdownConfig, type ShutdownOutcome, SimpleConsumer, type Source, type SourceFixture, type SourceLike, type SourceList, type SourceMessage, type SourceMeta, type SourceOverrideBehavior, type SplitChild, type SplitResult, type Splitter, type SqliteApplicationId, SqliteConnection, type SqliteDatabase, type SqliteDatabaseConstructor, SqliteDeferralStore, type SqliteDriverLoaders, type SqliteDriverName, SqliteEventWriter, type SqliteMigrationFailure, type SqlitePathConflict, SqliteSpanProcessor, type SqliteStatement, type SseEvent, type Step, StepBuilderBase, type StepContext, type StepOutcome, type StepOutcomeMetadata, type StepSignalContext, type StoreRegistry, type SubjectMatcher, type Subscription, type Tag, type TeardownInfo, type TelemetryEvent, type TelemetryOptions, type TelemetrySqliteOptions, type ThrottleOptions, type ThrottleTimeUnit, ThrottleWrapperStep, TimeoutWrapperStep, TimerHeaders, type TimerOptions, type ToTarget, type TokenVerifier, type Transformer, type TrustLevel, VCARD, VCard, type VCardBody, type VCardParam, VCardProperty, type VCardPropertyData, type VCardPropertyOptions, VPARAM, type Validator, type ValidatorAuthOptions, type WebIngress, type WeightedTarget, type WhenDescriptor, type WireIssue, type WireIssues, WrapperStep, type XmlAdapter, type XmlBuildOptions, type XmlData, type XmlFileOptions, type XmlOptions, type XmlParseOptions, type XmlTransformerOptions, analyzeHeaders, anySignal, apiKey, authenticate, authorize, bearerChallenge, buildCorsHeaders, buildProtectedResourceMetadata, callerRefusalOf, carddav, claimDatabasePath, claimed, classifyRejectionReason, compareRuntimeVersion, cosine, craft, createOpsHttpClient, cron, csv, cursorScope, debug, decodeCursor, defaultLoopbackOriginResolver, deferAside, deferralPlugin, deferredSchema, defineConfig, defineIndicator, delegate, describeSqliteFile, direct, directory, encodeCursor, event, factoryArgs, file, forRoute, formatSchemaIssues, getExchangeContext, getExchangeRoute, getProjectDiscoverers, group, hashExchangeBody, html, http, httpPlugin, isAuthentic, isAuthorizationRefusal, isCraftContext, isDeferSignal, isDeferred, isDevelopmentRuntime, isDropped, isExchange, isExpiredTokenError, isInfrastructureError, isInputValidationFailure, isInternalEndpoint, isLoopbackHostname, isOutputValidationFailure, isPrincipalExpired, isRecovery, isRedirect, isRestored, isRoute, isRouteBuilder, isRouteDefinition, isRoutecraftError, isSourceFixture, isSplitChild, isSqliteBusy, isStandardSchema, json, jsonl, jwks, jwt, keep, loadOptionalPeer, log, logFileDiversion, logger, mail, malformedCursor, mapper, markAuthentic, markDeferCapable, markRestored, mask, mergeProjectConfig, migrateSqlite, none, noop, normalizeStaticPathPrefix, only, opsPlugin, otherwise, parseAuthResults, parseDuration, parsePageQuery, parseRuntimeVersion, parseVCard, peekResumeStepState, rcCodeOf, rcError, recovery, registerCapability, registerConfigApplier, registerDsl, registerErrorCodes, registerInternalEndpoint, registerOpsResource, registerProjectDiscoverer, rejectStaleOptions, releaseClaimant, remotesPlugin, requireWebIngress, resolveCorsOptions, resolveDatabasePath, resolveSqliteDriver, resourceMetadataUrlFor, resumable, reviveDeferral, routeCanDefer, schema, serversPlugin, shutdownHandler, simple, splitChild, sqliteApplicationName, stepStateFingerprint, summariseDeferral, tagAdapter, takePage, telemetry, timer, timingSafeStringEqual, validateAgainst, wasOutputValidated, weighted, when, wireIssues, xml };