@volter/world-core 2.0.0

package/dist/src/derived.d.ts

@@ -0,0 +1,84 @@
+/** The slice of a generated surface the dispatch reads. */
+export type DerivedOperation = {
+    id: string;
+    method: string;
+    path: string;
+    class: string;
+    resource?: string;
+    /** query values that tell this operation from another at the same method and path */
+    discriminator?: Record<string, string | null>;
+    /** request headers that name the operation, for a wire whose operations share a path (AWS JSON's X-Amz-Target) */
+    headers?: Record<string, string | null>;
+    /** the status the vendor answers success with (201 for a create, 204 for an empty answer) */
+    successStatus?: number;
+    /** a form-encoded operation's number and boolean fields, by bracket path (`items.[].quantity`, `metadata.*`) */
+    scalars?: Readonly<Record<string, string | undefined>>;
+    /** what the success answer is: a resource, a list of them, and the envelope key holding it */
+    answers?: {
+        resource: string;
+        list: boolean;
+        key?: string;
+    };
+    /** the path its own server puts before it, where the operation names a server other than the surface's */
+    basePath?: string;
+};
+/** `basePath` is what the vendor's server URL puts before every operation path; `spanning` names the
+ *  path parameters whose values may hold slashes (a git ref, a file path), which no spec says. */
+export type DerivedSurface = {
+    version: string;
+    basePath?: string;
+    spanning?: ReadonlyArray<string>;
+    operations: ReadonlyArray<DerivedOperation>;
+};
+/** What a semantics handler receives: the request, the operation it matched, and its path parameters. */
+export type DerivedCall = {
+    request: Request;
+    operation: DerivedOperation;
+    params: Record<string, string>;
+};
+export type DerivedHandler = (call: DerivedCall) => Promise<Response>;
+/** What the derived core made of an operation: an answer, or why it cannot model it. */
+export type DerivedCoreOutcome = {
+    served: Response;
+} | {
+    unmodeled: string;
+};
+export type DerivedFetchOptions = {
+    surface: DerivedSurface;
+    /** Semantics handlers by operationId. A handler naming an operation the surface lacks is refused. */
+    handlers?: Record<string, DerivedHandler>;
+    /** The derived core, and which operations it owns (those of the resources the manifest declares). */
+    core?: {
+        owns: (operation: DerivedOperation) => boolean;
+        serve: (call: DerivedCall) => Promise<DerivedCoreOutcome>;
+    };
+    /** An RPC wire: every method is reached by any HTTP method (Slack's clients POST reads too). */
+    anyMethod?: boolean;
+    /** The pack's existing fetch while it moves: everything no handler or core owns, and what the core cannot model. */
+    legacy?: (request: Request) => Promise<Response>;
+    /** What every operation a handler or the core serves passes through (read-only refusal, version
+     *  checks, idempotent replay); the pack's existing fetch keeps its own while it moves. */
+    around?: (call: DerivedCall, next: () => Promise<Response>) => Promise<Response>;
+    /** The vendor's answer for an operation nothing models: the pack's gap. */
+    gap: (request: Request, operation: DerivedOperation | undefined, reason: string) => Response;
+};
+type Route = {
+    operation: DerivedOperation;
+    pattern: RegExp;
+    names: string[];
+    literals: number;
+};
+/** Routes per method, most literal segments first, so `/v1/customers/search` wins over `/v1/customers/{customer}`. */
+export declare function compileSurface(surface: DerivedSurface): Map<string, Route[]>;
+export declare function matchOperation(routes: Map<string, Route[]>, method: string, pathname: string, query?: URLSearchParams, headers?: Headers): {
+    operation: DerivedOperation;
+    params: Record<string, string>;
+} | undefined;
+export type DerivedOwner = 'handler' | 'core' | 'legacy' | 'gap';
+export type DerivedFetch = ((request: Request) => Promise<Response>) & {
+    /** Per operationId, who serves it: a semantics handler, the derived core, the pack's existing
+     *  fetch while it moves, or nothing (the vendor's gap). */
+    owners(): Record<string, DerivedOwner>;
+};
+export declare function createDerivedFetch(options: DerivedFetchOptions): DerivedFetch;
+export {};

package/dist/src/derived.js

@@ -0,0 +1,122 @@
+// THE DERIVED DISPATCH — the generated wire's router (docs/contributing/architecture.md, "The derived
+// pack"). A derived pack's surface (`src/generated/surface.gen.json`, written by scripts/derive-pack.ts)
+// names every operation the vendor publishes. This matches a request to one of them and hands it to its
+// owner: the pack's semantics handler for that operationId when there is one, otherwise the pack's
+// existing fetch, which keeps serving everything not yet moved (and every route outside the spec, such
+// as the `/twin` door). `owners` says, per operation, which of the two serves it: the count a pack's
+// move is measured by. Workerd-clean: no fs, no clock, nothing at import.
+class Unmodeled extends Error {
+}
+function compile(operation, basePath, spanning) {
+    const names = [];
+    let literals = 0;
+    const body = ((operation.basePath ?? basePath) + operation.path)
+        .split('/')
+        .map((seg) => {
+        const m = /^\{([^}]+)\}$/.exec(seg);
+        if (m) {
+            names.push(m[1]);
+            // a parameter the vendor lets hold slashes (a ref, a file path) takes the rest of its segments
+            return spanning.has(m[1]) ? '(.+?)' : '([^/]+)';
+        }
+        literals++;
+        // a segment templated in part (OpenAPI's `/report.{format}`, Tinybird's `/v0/pipes/{pipe}.json`) holds its
+        // labels between its literal text, and counts as literal: it is more specific than a bare label
+        return seg.split(/(\{[^}]+\})/).map((part) => {
+            const label = /^\{([^}]+)\}$/.exec(part);
+            if (!label)
+                return part.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+            names.push(label[1]);
+            return '([^/]+?)';
+        }).join('');
+    })
+        .join('/');
+    return { operation, pattern: new RegExp(`^${body}/?$`), names, literals };
+}
+const compiled = new WeakMap(); // cache: compiled routes per surface; a surface is immutable generated data
+/** Routes per method, most literal segments first, so `/v1/customers/search` wins over `/v1/customers/{customer}`. */
+export function compileSurface(surface) {
+    const hit = compiled.get(surface);
+    if (hit)
+        return hit;
+    const byMethod = new Map();
+    for (const operation of surface.operations) {
+        const method = operation.method.toUpperCase();
+        const list = byMethod.get(method) ?? [];
+        list.push(compile(operation, surface.basePath ?? '', new Set(surface.spanning ?? [])));
+        byMethod.set(method, list);
+    }
+    // most literal segments first; among equals, an operation with a query discriminator before the one without
+    const disc = (r) => Object.keys(r.operation.discriminator ?? {}).length + Object.keys(r.operation.headers ?? {}).length;
+    for (const list of byMethod.values())
+        list.sort((a, b) => b.literals - a.literals || disc(b) - disc(a) || a.operation.path.localeCompare(b.operation.path));
+    compiled.set(surface, byMethod);
+    return byMethod;
+}
+export function matchOperation(routes, method, pathname, query, headers) {
+    for (const route of routes.get(method.toUpperCase()) ?? []) {
+        const m = route.pattern.exec(pathname);
+        if (!m)
+            continue;
+        // a null value asks only that the key be present (S3's UploadPart, `uploadId`)
+        if (Object.entries(route.operation.discriminator ?? {}).some(([k, v]) => (v === null ? !query?.has(k) : query?.get(k) !== v)))
+            continue;
+        if (Object.entries(route.operation.headers ?? {}).some(([k, v]) => (v === null ? !headers?.has(k) : headers?.get(k) !== v)))
+            continue;
+        const params = {};
+        try {
+            route.names.forEach((name, i) => {
+                params[name] = decodeURIComponent(m[i + 1]);
+            });
+        }
+        catch {
+            // a malformed escape matches no operation: whoever serves unmatched requests answers it
+            return undefined;
+        }
+        return { operation: route.operation, params };
+    }
+    return undefined;
+}
+export function createDerivedFetch(options) {
+    const handlers = options.handlers ?? {};
+    const known = new Set(options.surface.operations.map((o) => o.id));
+    const unknown = Object.keys(handlers).filter((id) => !known.has(id));
+    if (unknown.length)
+        throw new Error(`derived dispatch: handlers name operations the surface does not have: ${unknown.sort().join(', ')}`);
+    const routes = compileSurface(options.surface);
+    const fallback = (request, operation, reason) => options.legacy ? options.legacy(request) : Promise.resolve(options.gap(request, operation, reason));
+    const fetch = (async (request) => {
+        const url = new URL(request.url);
+        const matched = options.anyMethod
+            ? [...routes.keys()].map((m) => matchOperation(routes, m, url.pathname, url.searchParams, request.headers)).find(Boolean)
+            : matchOperation(routes, request.method, url.pathname, url.searchParams, request.headers);
+        if (!matched)
+            return fallback(request, undefined, 'no operation at this path');
+        const call = { request, operation: matched.operation, params: matched.params };
+        const around = options.around ?? ((_c, next) => next());
+        const handler = handlers[matched.operation.id];
+        if (handler)
+            return around(call, () => handler(call));
+        if (options.core?.owns(matched.operation)) {
+            // the core reads the body; a clone keeps it for whatever serves an operation the core cannot
+            // model, and that case leaves `around` by a throw, so nothing it records (an idempotent
+            // answer) is recorded for a request the core did not serve
+            try {
+                return await around(call, async () => {
+                    const outcome = await options.core.serve({ ...call, request: request.clone() });
+                    if ('served' in outcome)
+                        return outcome.served;
+                    throw new Unmodeled(outcome.unmodeled);
+                });
+            }
+            catch (error) {
+                if (error instanceof Unmodeled)
+                    return fallback(request, matched.operation, error.message);
+                throw error;
+            }
+        }
+        return fallback(request, matched.operation, 'no handler');
+    });
+    fetch.owners = () => Object.fromEntries(options.surface.operations.map((o) => [o.id, handlers[o.id] ? 'handler' : options.core?.owns(o) ? 'core' : options.legacy ? 'legacy' : 'gap']));
+    return fetch;
+}

package/dist/src/emit.d.ts

@@ -0,0 +1,106 @@
+/** One event type a pack can synthesize, and the twin resource type that supplies its payload. */
+export type EmittableEvent = {
+    type: string;
+    /** twin resource type whose current state becomes the event payload (`data.object` for Stripe). */
+    subjectType: string;
+    description?: string;
+};
+/** A delivery destination registered IN TWIN STATE (at rest — the emit CLI runs in its own
+ *  process, so in-memory registries don't count; endpoints must be resolvable from the root). */
+export type EmitEndpoint = {
+    /** the vendor resource id of the registration (e.g. Stripe `we_…`), when it has one. */
+    id?: string;
+    url: string;
+    /** event-type subscriptions; `*` wildcards supported. Absent ⇒ subscribed to everything. */
+    enabledEvents?: string[];
+};
+/** A fully built, signed delivery for one endpoint: exact body bytes + headers to POST. */
+export type SynthesizedDelivery = {
+    /** the exact payload string — the signature covers THESE bytes, do not re-serialize. */
+    payload: string;
+    headers: Record<string, string>;
+    /** the synthesized event envelope (for reporting/assertions). */
+    event: Record<string, unknown>;
+};
+/** What a pack declares to support `emit` — see `TwinPack.emitter`. All state reads take the
+ *  same `root` every pack verb takes, so the CLI composes with worlds unchanged. */
+export type TwinEmitter = {
+    vendor: string;
+    /** the emittable catalog (drives `--list` and the unknown-event error). */
+    events(): EmittableEvent[];
+    /** endpoints registered in twin state (e.g. Stripe webhook_endpoint rows). */
+    endpoints(root?: string): EmitEndpoint[];
+    /** subject ids present in state for a subject type (drives `--list` + unknown-subject errors). */
+    subjects(subjectType: string, root?: string): string[];
+    /** synthesize the signed delivery for one endpoint. MUST throw loudly on an unknown subject. */
+    synthesize(opts: {
+        type: string;
+        subjectId: string;
+        endpoint: EmitEndpoint;
+        root?: string;
+        occurredAt?: string;
+    }): SynthesizedDelivery;
+};
+export type EmitDeliveryResult = {
+    endpoint: EmitEndpoint;
+    ok: boolean;
+    /** HTTP status when the POST completed; absent when the request itself failed. */
+    status?: number;
+    error?: string;
+    event: Record<string, unknown>;
+};
+export type EmitReport = {
+    vendor: string;
+    type: string;
+    subjectId: string;
+    deliveries: EmitDeliveryResult[];
+    /** true only when EVERY delivery reached its endpoint and got a 2xx back. */
+    ok: boolean;
+};
+/** Vendor wildcard subscription match (Stripe semantics: `*` matches all;
+ *  `invoice.*` matches every invoice event; otherwise exact). */
+export declare function eventSubscriptionMatches(pattern: string, type: string): boolean;
+/** The `--list` view: everything emittable right now — event types, the subject ids present in
+ *  state for each subject type, and the registered endpoints. Pure state read. */
+export declare function listEmittable(emitter: TwinEmitter, root?: string): {
+    vendor: string;
+    events: Array<EmittableEvent & {
+        subjects: string[];
+    }>;
+    endpoints: EmitEndpoint[];
+};
+/**
+ * DELIVER: synthesize the event for (`type`, `subjectId`) from current twin state and POST it,
+ * signed, to every registered endpoint subscribed to that event type (or the one endpoint
+ * `endpoint` names by url or id). Loud failures:
+ *   • event type the pack can't synthesize → throws, listing the emittable types;
+ *   • unknown subject id → the pack's synthesize throws (listing available ids);
+ *   • no registered/subscribed endpoint → throws (register one via the vendor API first);
+ *   • a delivery that errors or comes back non-2xx → reported per-endpoint, report.ok=false.
+ * `fetchFn` is the delivery seam (tests inject; default real fetch).
+ */
+export declare function emitTwinEvent(emitter: TwinEmitter, opts: {
+    type: string;
+    subjectId: string;
+    root?: string;
+    /** restrict delivery to the endpoint with this url or vendor id. */
+    endpoint?: string;
+    occurredAt?: string;
+    fetchFn?: (url: string, init: {
+        method: string;
+        headers: Record<string, string>;
+        body: string;
+    }) => Promise<{
+        status: number;
+    }>;
+}): Promise<EmitReport>;
+/**
+ * Shared CLI glue so every pack's `emit` verb behaves identically:
+ *   world-<vendor> emit --list [--root DIR] [--json]
+ *   world-<vendor> emit <event.type> <subject-id> [--root DIR] [--endpoint URL|ID] [--at ISO] [--json]
+ * Returns the process exit code (0 delivered; 1 loud failure / any failed delivery; 2 usage).
+ */
+export declare function runEmitCli(emitter: TwinEmitter, argv: string[], io?: {
+    out: (s: string) => void;
+    err: (s: string) => void;
+}): Promise<number>;

package/dist/src/emit.js

@@ -0,0 +1,157 @@
+// The DELIVER verb (`emit`) — fire a vendor-shaped, SIGNED webhook/event at the app under
+// test, synthesized from CURRENT TWIN STATE, without hand-constructing the envelope or the
+// signature. The engine here is vendor-agnostic; everything vendor-shaped (which event types
+// exist, which twin resource supplies `data.object`, where registered endpoints + signing
+// secrets live in state, how a delivery is signed) is a pack's knowledge, declared as a
+// `TwinEmitter` and registered on its `TwinPack.emitter` (same argument as `browserRouting`:
+// vendor knowledge in the descriptor, kernel stays vendor-agnostic).
+//
+// The operator surface is the PACK's bin (`world-stripe emit …`), exactly like the mirror
+// UIs — the kernel never imports packs, so `volter-twin emit <service>` only works when a
+// consumer registered the pack in-process, and otherwise fails loudly pointing at the
+// vendor bin. Unlike the twin's own background emission on state changes (fire-and-forget,
+// vendor-faithful), an explicit DELIVER is an operator asking for exactly this delivery, so
+// every failure here is LOUD: unknown event type, unknown subject, no registered endpoint,
+// and non-2xx delivery responses all throw / report instead of being swallowed.
+/** Vendor wildcard subscription match (Stripe semantics: `*` matches all;
+ *  `invoice.*` matches every invoice event; otherwise exact). */
+export function eventSubscriptionMatches(pattern, type) {
+    if (pattern === '*')
+        return true;
+    if (pattern.endsWith('.*'))
+        return type.startsWith(pattern.slice(0, -1));
+    return pattern === type;
+}
+function endpointSubscribed(endpoint, type) {
+    if (!endpoint.enabledEvents || endpoint.enabledEvents.length === 0)
+        return true;
+    return endpoint.enabledEvents.some((p) => eventSubscriptionMatches(p, type));
+}
+/** The `--list` view: everything emittable right now — event types, the subject ids present in
+ *  state for each subject type, and the registered endpoints. Pure state read. */
+export function listEmittable(emitter, root) {
+    const subjectsByType = new Map();
+    const events = emitter.events().map((e) => {
+        let subjects = subjectsByType.get(e.subjectType);
+        if (!subjects) {
+            subjects = emitter.subjects(e.subjectType, root);
+            subjectsByType.set(e.subjectType, subjects);
+        }
+        return { ...e, subjects };
+    });
+    return { vendor: emitter.vendor, events, endpoints: emitter.endpoints(root) };
+}
+/**
+ * DELIVER: synthesize the event for (`type`, `subjectId`) from current twin state and POST it,
+ * signed, to every registered endpoint subscribed to that event type (or the one endpoint
+ * `endpoint` names by url or id). Loud failures:
+ *   • event type the pack can't synthesize → throws, listing the emittable types;
+ *   • unknown subject id → the pack's synthesize throws (listing available ids);
+ *   • no registered/subscribed endpoint → throws (register one via the vendor API first);
+ *   • a delivery that errors or comes back non-2xx → reported per-endpoint, report.ok=false.
+ * `fetchFn` is the delivery seam (tests inject; default real fetch).
+ */
+export async function emitTwinEvent(emitter, opts) {
+    const catalog = emitter.events();
+    const known = catalog.find((e) => e.type === opts.type);
+    if (!known) {
+        throw new Error(`emit: the ${emitter.vendor} pack cannot synthesize "${opts.type}". Emittable event types:\n  ${catalog.map((e) => `${e.type} (subject: ${e.subjectType})`).join('\n  ')}`);
+    }
+    const all = emitter.endpoints(opts.root);
+    if (all.length === 0) {
+        throw new Error(`emit: no ${emitter.vendor} webhook endpoint is registered in twin state — nothing to deliver to. ` +
+            `Register one through the vendor API first (for Stripe: POST /v1/webhook_endpoints with url + enabled_events).`);
+    }
+    let targets = all.filter((e) => endpointSubscribed(e, opts.type));
+    if (opts.endpoint) {
+        targets = targets.filter((e) => e.url === opts.endpoint || e.id === opts.endpoint);
+        if (targets.length === 0) {
+            throw new Error(`emit: no registered endpoint matches "${opts.endpoint}" for event "${opts.type}". Registered endpoints:\n  ${all.map((e) => `${e.id ?? '-'} ${e.url} [${(e.enabledEvents ?? ['*']).join(', ')}]`).join('\n  ')}`);
+        }
+    }
+    if (targets.length === 0) {
+        throw new Error(`emit: ${all.length} endpoint(s) registered but none subscribes to "${opts.type}". Registered endpoints:\n  ${all.map((e) => `${e.id ?? '-'} ${e.url} [${(e.enabledEvents ?? ['*']).join(', ')}]`).join('\n  ')}`);
+    }
+    const fetchFn = opts.fetchFn ?? (async (url, init) => {
+        const res = await fetch(url, init);
+        return { status: res.status };
+    });
+    const deliveries = [];
+    for (const endpoint of targets) {
+        // synthesize PER ENDPOINT: signatures are per-endpoint secrets (real Stripe signs each
+        // delivery with the destination endpoint's own whsec). Unknown subject throws here — loudly.
+        const built = emitter.synthesize({ type: opts.type, subjectId: opts.subjectId, endpoint, ...(opts.root !== undefined ? { root: opts.root } : {}), ...(opts.occurredAt !== undefined ? { occurredAt: opts.occurredAt } : {}) });
+        try {
+            const res = await fetchFn(endpoint.url, { method: 'POST', headers: built.headers, body: built.payload });
+            deliveries.push({ endpoint, ok: res.status >= 200 && res.status < 300, status: res.status, event: built.event, ...(res.status >= 200 && res.status < 300 ? {} : { error: `endpoint responded ${res.status}` }) });
+        }
+        catch (error) {
+            deliveries.push({ endpoint, ok: false, error: error instanceof Error ? error.message : String(error), event: built.event });
+        }
+    }
+    return { vendor: emitter.vendor, type: opts.type, subjectId: opts.subjectId, deliveries, ok: deliveries.every((d) => d.ok) };
+}
+/**
+ * Shared CLI glue so every pack's `emit` verb behaves identically:
+ *   world-<vendor> emit --list [--root DIR] [--json]
+ *   world-<vendor> emit <event.type> <subject-id> [--root DIR] [--endpoint URL|ID] [--at ISO] [--json]
+ * Returns the process exit code (0 delivered; 1 loud failure / any failed delivery; 2 usage).
+ */
+export async function runEmitCli(emitter, argv, io = { out: (s) => process.stdout.write(s), err: (s) => process.stderr.write(s) }) {
+    const flags = new Map();
+    const positional = [];
+    let list = false;
+    let json = false;
+    for (let i = 0; i < argv.length; i += 1) {
+        const a = argv[i];
+        if (a === '--list')
+            list = true;
+        else if (a === '--json')
+            json = true;
+        else if (a.startsWith('--')) {
+            flags.set(a, argv[i + 1] ?? '');
+            i += 1;
+        }
+        else
+            positional.push(a);
+    }
+    const root = flags.get('--root');
+    if (list) {
+        const view = listEmittable(emitter, root);
+        if (json) {
+            io.out(`${JSON.stringify(view, null, 2)}\n`);
+        }
+        else {
+            io.out(`emittable ${view.vendor} events (synthesized from current twin state):\n`);
+            for (const e of view.events) {
+                io.out(`  ${e.type}  (subject: ${e.subjectType}${e.subjects.length ? ` — ${e.subjects.join(', ')}` : ' — none in state'})\n`);
+            }
+            io.out(view.endpoints.length === 0
+                ? 'no webhook endpoints registered — deliveries have nowhere to go.\n'
+                : `endpoints:\n${view.endpoints.map((e) => `  ${e.id ?? '-'} ${e.url} [${(e.enabledEvents ?? ['*']).join(', ')}]`).join('\n')}\n`);
+        }
+        return 0;
+    }
+    const [type, subjectId] = positional;
+    if (!type || !subjectId) {
+        io.err(`Usage: world-${emitter.vendor} emit --list [--root DIR] [--json]\n       world-${emitter.vendor} emit <event.type> <subject-id> [--root DIR] [--endpoint URL|ID] [--at ISO] [--json]\n`);
+        return 2;
+    }
+    try {
+        const endpointFlag = flags.get('--endpoint');
+        const at = flags.get('--at');
+        const report = await emitTwinEvent(emitter, { type, subjectId, ...(root !== undefined ? { root } : {}), ...(endpointFlag !== undefined ? { endpoint: endpointFlag } : {}), ...(at !== undefined ? { occurredAt: at } : {}) });
+        if (json)
+            io.out(`${JSON.stringify(report, null, 2)}\n`);
+        else {
+            for (const d of report.deliveries) {
+                io.out(`${d.ok ? 'delivered' : 'FAILED'} ${report.type} (${String(d.event.id ?? '')}) → ${d.endpoint.url}${d.status !== undefined ? ` [${d.status}]` : ''}${d.error ? ` — ${d.error}` : ''}\n`);
+            }
+        }
+        return report.ok ? 0 : 1;
+    }
+    catch (error) {
+        io.err(`${error instanceof Error ? error.message : String(error)}\n`);
+        return 1;
+    }
+}

package/dist/src/executor.d.ts

@@ -0,0 +1,120 @@
+import type { CredentialPayload } from './credential.js';
+import type { RemoteExecute } from './remote-execute.js';
+import type { HostRule } from './packRegistry.js';
+/**
+ * HOW A VENDOR AUTHENTICATES — a fact about the vendor, declared by the pack (`TwinPack.auth`) and
+ * applied here (docs/concepts/the-model.md#the-rules, rule 5: the executor "applies the credential by strategy").
+ *
+ * The executor dispatches on the STRATEGY NAME and never on vendor identity, and imports no pack:
+ * architecture invariant A2's own instruction is that vendor-specific knowledge lives in the
+ * descriptor rather than a kernel switch table. Absent means header replacement, which is what
+ * `credential.headers` has always done — so a pack that declares nothing keeps today's behaviour
+ * and no sealed credential migrates.
+ */
+export type TwinAuthStrategy = 
+/** the key rides in the query string (`?key=…`, `?appid=…`) — no header will do */
+{
+    in: 'query';
+    name: string;
+}
+/** AWS Signature Version 4 — a signature computed per request over the whole canonical request.
+ *  `scope` answers which region and service THIS request is for, because a pack may route several
+ *  services over one executor (aws routes six); it is pure and is handed no secret. */
+ | {
+    in: 'signature';
+    algorithm: 'aws-sigv4';
+    scope: (req: {
+        method: string;
+        path: string;
+        host: string;
+        headers: Record<string, string>;
+        body?: string | Uint8Array;
+    }) => {
+        region: string;
+        service: string;
+    };
+}
+/** a signature computed PER REQUEST over bytes only the pack can canonicalize */
+ | {
+    in: 'signature';
+    algorithm: 'hmac-sha256';
+    encoding: 'hex' | 'base64';
+    header: string;
+    /** The exact bytes to sign, from the request as the kernel will send it. Pure: it is handed no
+     *  secret, which is what keeps the secret out of pack code while the pack still decides what
+     *  the vendor signs.
+     *
+     *  `null` means THIS REQUEST IS NOT SIGNED — a real thing vendors do (Veriff exempts
+     *  `POST /sessions`, the call that has no session to sign for yet). It is the pack stating the
+     *  vendor's own rule, not a failure: an unsigned request the vendor expects to be unsigned is
+     *  correct, and the alternative would be signing bytes the vendor will reject. */
+    canonical: (req: {
+        method: string;
+        path: string;
+        body?: string;
+    }) => string | null;
+}
+/** A TOKEN EXCHANGE: the sealed secret is traded for a short-lived token the calls then carry (Bluesky's
+ *  createSession from an app password, an OAuth refresh-token grant). The kernel sends `request` itself —
+ *  its body fields are literals or `{ credential: '<field>' }` read from the sealed credential — keeps
+ *  the token it answers to itself, and puts it on every later call; a `retryOn` answer (401 by default)
+ *  exchanges once more and retries the call once. The pack never holds the secret or the token: what it
+ *  needs to know about the session it asks the vendor for with an ordinary authenticated call. */
+ | {
+    in: 'exchange';
+    request: {
+        method: 'POST';
+        path: string;
+        format: 'json' | 'form';
+        body: Record<string, string | {
+            credential: string;
+        }>;
+        /** HTTP Basic client authentication on the token request (an OAuth confidential client), from sealed fields */
+        basicAuth?: {
+            user: {
+                credential: string;
+            };
+            password: {
+                credential: string;
+            };
+        };
+    };
+    /** the token's field in the JSON answer (a dotted path) */
+    token: string;
+    /** the header it rides in (default `authorization`) and its scheme (default `Bearer`; '' for none) */
+    header?: string;
+    scheme?: string;
+    retryOn?: number[];
+    /** the vendor's code for an expired token in the answer's `error` field (Bluesky's `ExpiredToken`): with it,
+     *  a retryOn status exchanges again only when the answer names that code, so a bad request never spends
+     *  the shared token or the vendor's session allowance */
+    retryCode?: string;
+    /** A vendor that ROTATES the secret each exchange spends (X issues a new refresh token with every refresh grant,
+     *  and the old one no longer works): the answer's field holding the new one (a dotted path) and the sealed field
+     *  it replaces. The kernel keeps the new value for its next exchange and hands the updated credential to the
+     *  root's custody to seal (`onRotate`), so the root outlives the first refresh token. */
+    rotate?: {
+        answer: string;
+        credential: string;
+    };
+};
+/** Throws with the precise refusal; returns the parsed URL when the origin is usable. */
+export declare function validateRemoteOrigin(origin: string, opts?: {
+    allowInsecureLoopback?: boolean;
+}): URL;
+/** `vendorHosts`: the pack's declared vendor host rules (its descriptor's `hosts`). An absolute https URL
+ *  on one of them — an exact `host` rule whose `pathPattern` the path matches — is a second host of the
+ *  same vendor that takes the credential (LinkedIn's image uploads on www.linkedin.com/dms-uploads,
+ *  Instagram's rupload host); it is sent credentialed like an anchored call. Any other absolute URL is
+ *  refused, as before. */
+/** Where a credential is kept (the head's and refresh's root: head.ts rootCustody): `key` names the credential stably
+ *  across rotations and anew when another is sealed in its place (the token cache is keyed by it, not by the secret's value), `open` reads it as sealed now, `seal` keeps a rotated one. */
+export type CredentialCustody = {
+    key: string;
+    open: () => Promise<CredentialPayload>;
+    seal: (credential: CredentialPayload) => Promise<void> | void;
+};
+export type RemoteExecuteOptions = {
+    custody?: CredentialCustody;
+};
+export declare function buildRemoteExecute(origin: URL, credential: CredentialPayload, auth?: TwinAuthStrategy, vendorHosts?: readonly HostRule[], options?: RemoteExecuteOptions): RemoteExecute;