@mcp-b/do-runtime 0.1.0

package/dist/src/api/export-loopback.d.ts

@@ -0,0 +1,264 @@
+/**
+ * ← workerd `src/workerd/api/export-loopback.{h,c++}`
+ *
+ * The four types `ctx.exports` is made of. Upstream's own comment on the first
+ * says what they all are: "the type of a property of `ctx.exports` which points
+ * back at a … entrypoint of this Worker", specialized by *invoking* it.
+ *
+ *  - `LoopbackServiceStub` (`export-loopback.h:18`) — a stateless entrypoint. A
+ *    `Fetcher` with empty props, callable to get one with props.
+ *  - `LoopbackDurableObjectClass` (`:116`) — an actor class with **no storage
+ *    configured**. A `DurableObjectClass`, callable to get a specialized one.
+ *  - `LoopbackDurableObjectNamespace` (`:155`) — an actor class **with** storage:
+ *    "we want a binding that behaves *both* like a LoopbackDurableObjectClass
+ *    *and* like a DurableObjectNamespace binding."
+ *  - `LoopbackColoLocalActorNamespace` (`:192`) — the same, for a colo-local
+ *    (ephemeral) namespace binding.
+ *
+ * The third is why this file blocks `server/`. The vendored consumer reads
+ * `ctx.exports[className]` and needs one value to answer both `idFromName`
+ * (`vendor/agents/packages/agents/src/index.ts:10829`, `:10855`) and
+ * `ctx.facets.get`'s class check (`:10857`) — namespace-shaped and class-shaped
+ * at once, which is exactly what `LoopbackDurableObjectNamespace` is for.
+ * Upstream's own `api/tests/worker-loader-test.js:449-450` pins the same pair.
+ *
+ * **`JSG_CALLABLE` becomes a `Proxy` with an `apply` trap.** A JS value can only
+ * be invoked if it is a function, and a class instance is not one; the private
+ * fields these classes inherit mean the callable cannot simply be a function
+ * whose prototype is the instance, because an inherited method would then run
+ * with `this` set to the function. So each class keeps its behaviour and an
+ * `asLoopback…` function produces the JS-visible value — the same split, for the
+ * same reason, that `asDurableObjectStub` already makes for `JSG_INHERIT`.
+ * `getPrototypeOf` is what keeps `instanceof` answering, which is how
+ * `DurableObjectFacets.get` discriminates the three arms of its class switch.
+ *
+ * **Two `IoChannelFactory` methods are declared here rather than in
+ * `io/io-channels.ts`.** `getSubrequestChannel` and `getActorClass` are what
+ * `export-loopback.c++` reaches for, and both take a channel *number* upstream —
+ * which this package does not have (`io/io-channels.ts`'s header: there is no
+ * numbered channel table). So each collapses into a factory taking an object
+ * request, exactly as `api/actor.ts` already does for `IoChannelFactory`'s
+ * `getGlobalActor` and `getColoLocalActor`, and each is declared beside its one
+ * consumer for the same reason `ActorChannelFactory` is. Section 7 fills them.
+ *
+ * **Non-serializability survives, and Section 7b is where it is enforced.**
+ * Upstream is explicit that `LoopbackServiceStub` is "intentionally NOT
+ * serializable, unlike its parent class Fetcher", and
+ * `api/tests/worker-loader-test.js:104` asserts the message;
+ * `LoopbackDurableObjectClass` likewise declares no `JSG_SERIALIZABLE` where
+ * `DurableObjectClass` (`actor.h:389`) does, and neither namespace type declares
+ * one either — `JSG_INHERIT` does not carry serializability, which is what the
+ * test's own comment says it is checking.
+ *
+ * An earlier revision of this paragraph said the refusal did not survive, and
+ * named `src/transport/` as the layer that would have to make it. Both halves
+ * were wrong about *where*: the test reaches the refusal through
+ * `worker.getEntrypoint(name, {props})`, and `WorkerStub::getEntrypoint`'s first
+ * act is `Frankenvalue::fromJs`, which runs `jsg::Serializer` inside
+ * `api/worker-loader.c++`. So `api/worker-loader.ts`'s `requireSerializableProps`
+ * refuses all four of these in `props` and in `env`, with upstream's message and
+ * a `DataCloneError`. `DurableObjectClass.serialize` remains a separate named
+ * substrate boundary that throws for every class, loopback or not.
+ *
+ * The version half of `LoopbackServiceStub` is present and `Options`, the
+ * flag-off form, is not: `FeatureFlags::getEnableVersionApi()` is read as on
+ * here, the same current-behaviour reading `api/actor.ts` gives the four
+ * compatibility flags it meets. That makes this a superset of
+ * `@cloudflare/workers-types` 4.20260702.1, which generated the flag-off
+ * signature — the same relationship `DurableObjectNamespace.getExisting` has.
+ *
+ * Spec: §1.10, §1.11, decisions 14 and 16 in
+ * docs/decisions.md.
+ */
+import type { ActorIdFactory } from "../io/actor-id.js";
+import type { ActorClassChannel } from "../io/io-channels.js";
+import { ColoLocalActorNamespace, DurableObjectClass, DurableObjectNamespace, type ActorChannelFactory, type ColoLocalActorChannelFactory } from "./actor.js";
+/**
+ * ← what JSG's struct unwrapper does with a value that is not an object
+ * (`jsg/struct.h:246`). Undefined and null are **not** in that set: a struct
+ * whose every field is optional — which both option structs here are — unwraps
+ * from either as an empty struct (`jsg/struct.h:236-243`), so `ctx.exports.Foo()`
+ * is upstream's own empty-options call and not an error.
+ */
+export declare const LOOPBACK_OPTIONS_NOT_AN_OBJECT_MESSAGE = "A ctx.exports binding is invoked with an options object: pass { props }, or nothing at all.";
+/** ← what JSG does unwrapping a `jsg::JsRef<jsg::JsObject>` from a non-object. */
+export declare const LOOPBACK_PROPS_NOT_AN_OBJECT_MESSAGE = "`props` must be an object. Upstream unwraps it as a jsg::JsObject, which refuses anything else.";
+/** ← `IoChannelFactory::VersionRequest` (`io/io-channels.h:123-131`). */
+export type VersionRequest = {
+    /** "Request a version within the given cohort." */
+    readonly cohort: string | undefined;
+};
+/**
+ * ← the two arguments `IoChannelFactory::getSubrequestChannel` takes besides the
+ * channel number (`io/io-channels.h:243-245`). Upstream: "`props` and
+ * `versionRequest` can only be specified if this is a loopback channel (i.e.
+ * from ctx.exports)."
+ */
+export type SubrequestChannelRequest = {
+    /** ← `kj::Maybe<Frankenvalue> props`. */
+    readonly props: unknown;
+    readonly version: VersionRequest | undefined;
+};
+/**
+ * ← `IoChannelFactory::getSubrequestChannel` composed with the `Fetcher` upstream
+ * builds over the `SubrequestChannel` it returns.
+ *
+ * The composition is `api/actor.ts`'s: a `SubrequestChannel` is only ever driven
+ * through `startRequest()` → `WorkerInterface`, which has no port, while the
+ * JS-visible product is a `Fetcher` — so the channel and the stub it produces are
+ * one object here.
+ */
+export interface SubrequestChannelFactory {
+    getSubrequestChannel(request: SubrequestChannelRequest): Fetcher;
+}
+/** ← the `props` argument of `IoChannelFactory::getActorClass` (`io/io-channels.h:315`). */
+export type ActorClassRequest = {
+    readonly props: unknown;
+};
+/** ← `IoChannelFactory::getActorClass`, which returns the token `io/io-channels.ts` ports. */
+export interface ActorClassChannelFactory {
+    getActorClass(request: ActorClassRequest): ActorClassChannel;
+}
+/** ← `LoopbackServiceStub::OptionsWithVersion::Version` (`export-loopback.h:32-36`). */
+export type LoopbackServiceStubVersion = {
+    /** `jsg::Optional<kj::Maybe<kj::String>>`: omitted and null are the same request. */
+    readonly cohort?: string | null;
+};
+/** ← `LoopbackServiceStub::OptionsWithVersion` (`export-loopback.h:31-42`). */
+export type LoopbackServiceStubOptions = {
+    readonly props?: unknown;
+    readonly version?: LoopbackServiceStubVersion;
+};
+/** ← `LoopbackDurableObjectClass::Options` (`export-loopback.h:120-124`). */
+export type LoopbackDurableObjectClassOptions = {
+    readonly props?: unknown;
+};
+/**
+ * ← `LoopbackServiceStub` (`export-loopback.h:18-109`).
+ *
+ * Upstream is a `Fetcher` on the loopback channel and holds the channel number a
+ * second time so `callImpl` can re-specialize it. Here the `Fetcher` is the
+ * transport's — `api/http.{h,c++}` is not ported — so the unspecialized stub is
+ * what the factory returns for a request with no props and no version, and the
+ * factory is the thing held twice over.
+ */
+export declare class LoopbackServiceStub {
+    #private;
+    constructor(channel: SubrequestChannelFactory);
+    /** The `Fetcher` upstream inherits from rather than holds, as `DurableObject`'s is. */
+    getFetcher(): Fetcher;
+    /**
+     * ← `LoopbackServiceStub::callImpl` (`export-loopback.c++:11-29`) reached
+     * through `callWithVersion` (`export-loopback.h:53-55`), which is the callable
+     * when `enableVersionApi` is on. "Create a specialized Fetcher which can be
+     * passed over RPC."
+     */
+    callWithVersion(options: LoopbackServiceStubOptions): Fetcher;
+}
+/**
+ * ← `js.alloc<LoopbackServiceStub>(…)` plus `JSG_CALLABLE(callWithVersion)`.
+ *
+ * The declared type is a superset of `@cloudflare/workers-types`' by exactly the
+ * `version` field, for the reason in this module's header.
+ */
+export type LoopbackServiceStubValue<T extends Rpc.WorkerEntrypointBranded | undefined = undefined> = Fetcher<T> & ((options?: LoopbackServiceStubOptions) => Fetcher<T>);
+export declare function asLoopbackServiceStub<T extends Rpc.WorkerEntrypointBranded | undefined = undefined>(stub: LoopbackServiceStub): LoopbackServiceStubValue<T>;
+/**
+ * ← `LoopbackDurableObjectClass` (`export-loopback.h:116-148`). "Similar to
+ * LoopbackServiceStub, but for actor classes … this is used for actor classes
+ * that do *not* have any storage configured. If you simply export a class
+ * extending `DurableObject` but you don't configure storage for it, it shows up
+ * in `ctx.exports` as this type. This can be used to create a Durable Object
+ * facet."
+ *
+ * Upstream's base `DurableObjectClass` holds the channel *number*, and
+ * `getChannel(ioctx)` resolves it lazily. There is no numbered arm here, so the
+ * unspecialized channel is requested once, in the constructor — which is the same
+ * value `getActorClass(channel)` with default props would have produced.
+ */
+export declare class LoopbackDurableObjectClass<T extends Rpc.DurableObjectBranded | undefined = undefined> extends DurableObjectClass<T> {
+    #private;
+    constructor(channel: ActorClassChannelFactory);
+    /**
+     * ← `LoopbackDurableObjectClass::call` (`export-loopback.c++:31-40`). "Create a
+     * specialized DurableObjectClass which can be passed over RPC."
+     *
+     * The result is a plain `DurableObjectClass`, as `js.alloc<DurableObjectClass>`
+     * is: specializing a loopback class does not produce another loopback class.
+     */
+    call(options: LoopbackDurableObjectClassOptions): DurableObjectClass<T>;
+}
+/** ← `js.alloc<LoopbackDurableObjectClass>(…)` plus `JSG_CALLABLE(call)`. */
+export type LoopbackDurableObjectClassValue<T extends Rpc.DurableObjectBranded | undefined = undefined> = DurableObjectClass<T> & ((options?: LoopbackDurableObjectClassOptions) => DurableObjectClass<T>);
+export declare function asLoopbackDurableObjectClass<T extends Rpc.DurableObjectBranded | undefined = undefined>(actorClass: LoopbackDurableObjectClass<T>): LoopbackDurableObjectClassValue<T>;
+/**
+ * ← `LoopbackDurableObjectNamespace` (`export-loopback.h:155-189`).
+ *
+ * Upstream: "used when the class has storage configured. In this case, we want a
+ * binding that behaves *both* like a LoopbackDurableObjectClass *and* like a
+ * DurableObjectNamespace binding. Easy enough, we'll inherit
+ * DurableObjectNamespace, but also make the binding invokable as a function like
+ * LoopbackDurableObjectClass."
+ */
+export declare class LoopbackDurableObjectNamespace<T extends Rpc.DurableObjectBranded | undefined = undefined> extends DurableObjectNamespace<T> {
+    #private;
+    constructor(channel: ActorChannelFactory, idFactory: ActorIdFactory, loopbackClass: LoopbackDurableObjectClass<T>);
+    /** ← `getClass()`. "getClass() accessor for use from C++ only." */
+    getClass(): LoopbackDurableObjectClass<T>;
+    /** ← `call`. "Invoking the binding creates a specialization of the class -- not the namespace." */
+    call(options: LoopbackDurableObjectClassOptions): DurableObjectClass<T>;
+}
+/**
+ * ← `js.alloc<LoopbackDurableObjectNamespace>(…)` plus `JSG_CALLABLE(call)`.
+ *
+ * This is the type of a `ctx.exports` entry for a Durable Object class with
+ * storage, and the reason it is stated in terms of this package's classes rather
+ * than `@cloudflare/workers-types`' `LoopbackDurableObjectNamespace` is that the
+ * pinned interface is `interface LoopbackDurableObjectNamespace extends
+ * DurableObjectNamespace {}` — no call signature, because that resource type
+ * carries no `JSG_TS_OVERRIDE` to generate one from. `Cloudflare.Exports`
+ * describes the same value correctly, as `LoopbackDurableObjectClass<T> &
+ * DurableObjectNamespace<T>`, and `PinnedLoopbackTypes` below checks against
+ * that rather than against the interface.
+ *
+ * `call` is omitted because `JSG_CALLABLE` registers it as the object's call
+ * behaviour rather than as a property: on the value, `.call` is
+ * `Function.prototype.call`, which is what `asCallable`'s `get` trap answers.
+ */
+export type LoopbackDurableObjectNamespaceValue<T extends Rpc.DurableObjectBranded | undefined = undefined> = Omit<LoopbackDurableObjectNamespace<T>, "call"> & ((options?: LoopbackDurableObjectClassOptions) => DurableObjectClass<T>);
+export declare function asLoopbackDurableObjectNamespace<T extends Rpc.DurableObjectBranded | undefined = undefined>(namespace: LoopbackDurableObjectNamespace<T>): LoopbackDurableObjectNamespaceValue<T>;
+/**
+ * ← `LoopbackColoLocalActorNamespace` (`export-loopback.h:192-220`). "Like
+ * LoopbackDurableObjectNamespace, but for colo-local (ephemeral) actor
+ * namespaces."
+ */
+export declare class LoopbackColoLocalActorNamespace extends ColoLocalActorNamespace {
+    #private;
+    constructor(channel: ColoLocalActorChannelFactory, loopbackClass: LoopbackDurableObjectClass);
+    /** ← `getClass()`. "getClass() accessor for use from C++ only." */
+    getClass(): LoopbackDurableObjectClass;
+    /** ← `call`. "Invoking the binding creates a specialization of the class -- not the namespace." */
+    call(options: LoopbackDurableObjectClassOptions): DurableObjectClass;
+}
+/**
+ * ← `js.alloc<LoopbackColoLocalActorNamespace>(…)` plus `JSG_CALLABLE(call)`,
+ * with `call` omitted for the reason given on the durable namespace above.
+ */
+export type LoopbackColoLocalActorNamespaceValue = Omit<LoopbackColoLocalActorNamespace, "call"> & ((options?: LoopbackDurableObjectClassOptions) => DurableObjectClass);
+export declare function asLoopbackColoLocalActorNamespace(namespace: LoopbackColoLocalActorNamespace): LoopbackColoLocalActorNamespaceValue;
+/** `Value` must be assignable to `Declared`; declaring the constraint is the check. */
+type Assignable<Value extends Declared, Declared> = Value;
+/**
+ * Checked rather than claimed: every value this module produces satisfies the
+ * shape `@cloudflare/workers-types` 4.20260702.1 declares for it. The last two
+ * are checked against `Cloudflare.Exports`' own description of a `ctx.exports`
+ * entry — `LoopbackForExport<T>` intersected with the namespace — because the
+ * two named interfaces there are call-signature-less, per the note above.
+ */
+export type PinnedLoopbackTypes = [
+    Assignable<LoopbackServiceStubValue, globalThis.LoopbackServiceStub>,
+    Assignable<LoopbackDurableObjectClassValue, globalThis.LoopbackDurableObjectClass>,
+    Assignable<LoopbackDurableObjectNamespaceValue, globalThis.LoopbackDurableObjectClass & globalThis.DurableObjectNamespace>,
+    Assignable<LoopbackColoLocalActorNamespaceValue, globalThis.LoopbackDurableObjectClass & globalThis.ColoLocalActorNamespace>
+];
+export {};

package/dist/src/api/global-scope.d.ts

@@ -0,0 +1,262 @@
+/**
+ * ← workerd `src/workerd/api/global-scope.{h,c++}` — the alarm half, and the
+ * async-primitive half `ServiceWorkerGlobalScope` exposes to an application.
+ *
+ * The event surface (`fetch`/`scheduled`/`trace`/`queue` handlers) still has no
+ * port: that belongs to layers this package does not have. What is here is the
+ * other thing that class is, and the thing a Durable Object actually reaches —
+ * `JSG_METHOD(setTimeout)`, `clearTimeout`, `setInterval`, `clearInterval`,
+ * `JSG_METHOD(fetch)`, and `JSG_LAZY_INSTANCE_PROPERTY(scheduler, getScheduler)`
+ * (`global-scope.h:776-808`). `Scheduler` itself is `api/basics.h:781-797`; it
+ * is one class with one method and it lives beside its only exposure rather than
+ * in a `api/basics.ts` that would hold nothing else, since everything else in
+ * that file — `Event`, `EventTarget`, `AbortController`, `AbortSignal` — the
+ * substrate already provides.
+ *
+ * **Why this file gained a half.** Workerd's globals hold no context: each one
+ * reads `IoContext::current()` at call time (`global-scope.c++:944`, `:961`,
+ * `:989`, `:1160`), because acquisition is structural and every entry into the
+ * isolate has already taken the lock. There is no isolate hook here, so a
+ * continuation that resumes from a promise the runtime does not own comes back
+ * with an empty invocation stack and its next `ctx.storage` call throws `no
+ * input lock available in this context`. Every host-provided async primitive
+ * therefore has to gate itself, and this is where they do.
+ *
+ * The three primitives take three different mechanisms, and flattening them into
+ * "wrap it in awaitIo" would be wrong three ways:
+ *
+ *  - **Timers** capture the critical section at the ARMING call and re-enter
+ *    through `ctx.run(callback, cs)` when they fire. Not `awaitIo`, deliberately
+ *    — see `TimeoutManager` in `io/io-context.ts` for upstream's own reason.
+ *  - **`fetch`** is `awaitIo` (`http.c++` has ten of them and zero
+ *    `awaitIoWithInputLock`), preceded by an output-gate wait so nothing departs
+ *    ahead of the writes it might reveal (`http.c++:1488`). §1.3.
+ *  - **WebSocket** is neither: `api/web-socket.ts`, because a socket is a long
+ *    stream of events rather than one result.
+ *
+ * **The context is held, not looked up, and that is the whole of the
+ * enforcement substitution.** One scope per actor. See `requireOwnSlice` for
+ * what happens when a facet reaches a scope that is not its own.
+ *
+ * Spec: §1.2, §1.3, §1.8 and decisions 1 and 16 in
+ * docs/decisions.md.
+ */
+import { type IoContext } from "../io/io-context.js";
+/**
+ * ← `AlarmInvocationInfo` (`api/global-scope.h:386-412`): "a jsg::Object used to
+ * pass alarm invocation info to an alarm handler."
+ *
+ * `scheduledTime` is already milliseconds here where upstream converts a
+ * `kj::Date` to them at construction (`global-scope.h:390`), which is the same
+ * unit `@cloudflare/workers-types` declares and the same one `setAlarm` takes.
+ */
+export declare class AlarmInvocationInfo implements globalThis.AlarmInvocationInfo {
+    readonly scheduledTime: number;
+    readonly retryCount: number;
+    constructor(scheduledTime: number, retry: number);
+    get isRetry(): boolean;
+}
+/**
+ * ← `isAlarmFailureUserError` (`api/global-scope.c++:501-515`), whose own
+ * comment lists the three arms: "Returns true if an alarm failure should count
+ * against the user's retry limit. A failure is user-generated if any of: the
+ * exception was explicitly tagged with EXCEPTION_IS_USER_ERROR at construction
+ * time (e.g. state.abort(), exceededCpu, exceededMemory, overload queue); the
+ * exception originated from user code throwing inside blockConcurrencyWhile,
+ * which breaks the input gate as a secondary side-effect; the exception is a
+ * plain jsg.* error without broken.* or jsg-internal.* prefixes, meaning the
+ * user's handler threw directly."
+ *
+ * The first two arms port exactly: this package writes both markers itself —
+ * `DurableObjectState.abort()` sets the detail, and `IoContext` annotates a
+ * broken input gate with upstream's own prefix.
+ *
+ * **The third arm has no input here, and its default is inverted deliberately.**
+ * Upstream reads it off jsg's exception tunnelling: a `jsg.Error:` prefix that
+ * is neither `jsg-internal.` nor a Durable Object reset means the user's handler
+ * threw. There is no tunnelling in this runtime — an `Error` out of a handler
+ * carries no provenance at all — so a plain exception is reported here as NOT a
+ * user error, where upstream would report it as one.
+ *
+ * That inversion is narrower than it sounds, and it is the safe direction. The
+ * caller is
+ * `shouldRetryCountsAgainstLimits = !isOutputGateBroken() || isUserGeneratedError`
+ * (`global-scope.c++:624`), so for an intact actor a handler failure counts
+ * whatever this answers; the only case the two readings disagree on is a handler
+ * failure that arrives together with a broken output gate. Upstream counts that
+ * and eventually abandons the alarm. This does not, so the alarm outlives the
+ * actor's reset and is retried after the restart — which is what
+ * `!tunneled.isDurableObjectReset` (`:514`) is reaching for on the arm above it
+ * and what the product ranking asks for outright. A default of "user error"
+ * would abandon exactly the alarms that most need keeping.
+ */
+export declare function isAlarmFailureUserError(exception: unknown): boolean;
+/** ← `Scheduler::WaitOptions` (`api/basics.h:775-778`). */
+export type SchedulerWaitOptions = {
+    signal?: AbortSignal;
+};
+/**
+ * ← `Scheduler` (`api/basics.h:781-797`), whose own comment is: "The scheduler
+ * class is an emerging web platform standard API that is meant to be global and
+ * provides task scheduling APIs. We currently only implement a subset of the API
+ * that is being defined."
+ *
+ * `wait` is "essentially an awaitable alternative to setTimeout()", and upstream
+ * implements it as exactly that — `setTimeoutInternal` onto the same timeout
+ * manager (`basics.c++:1007`), which is why it inherits the gating rather than
+ * having any of its own.
+ */
+export declare class Scheduler {
+    #private;
+    constructor(scope: ActorGlobalScope);
+    /** ← `Scheduler::wait` (`basics.c++:989-1020`). */
+    wait(delay: number, options?: SchedulerWaitOptions): Promise<void>;
+    /**
+     * NO upstream correspondence: `scheduler.yield()` is the Prioritized Task
+     * Scheduling API's, which workerd does not implement — `Scheduler` above has
+     * exactly one `JSG_METHOD`. It is here because Chrome ships a `scheduler`
+     * global in workers that DOES have `yield` and no `wait`, so a scope that
+     * replaced Chrome's and dropped `yield` would break page-shaped code that a
+     * Durable Object never runs but a shared worker global might. A zero-delay
+     * gated timer is the closest honest reading and it keeps the lock property.
+     */
+    yield(): Promise<void>;
+}
+/**
+ * ← `ServiceWorkerGlobalScope`'s `crypto`. The synchronous members are the
+ * platform's own; `subtle` is the gated one above.
+ */
+declare class GatedCrypto {
+    #private;
+    readonly subtle: SubtleCrypto;
+    constructor(requireOwnSlice: (op: string) => void, ctx: IoContext, crypto: Crypto);
+    getRandomValues<T extends ArrayBufferView | null>(array: T): T;
+    randomUUID(): `${string}-${string}-${string}-${string}-${string}`;
+}
+/** What the host supplies beneath `ServiceWorkerGlobalScope::fetch`. */
+export type FetchPort = (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+export type ActorGlobalScopeOptions = {
+    /** Opaque identity of the external entry whose synchronous body is running. */
+    readonly currentExternalEntry?: (() => object | undefined) | undefined;
+    /**
+     * The `Crypto` the gated one delegates to. Defaults to the realm's own, which
+     * is what a host wants: unlike `fetch`, there is no per-actor outbound to
+     * route this through — `SubtleCrypto` is pure computation, and the only thing
+     * the actor's scope adds is the gate around its promise.
+     */
+    readonly crypto?: Crypto | undefined;
+    /**
+     * ← the global outbound `Fetcher` `ServiceWorkerGlobalScope::fetch` resolves
+     * (`global-scope.c++:1160`). Absent means this actor has no ambient outbound,
+     * which is upstream's `globalOutbound: null` posture (§1.11) — `fetch` then
+     * refuses by name rather than reaching a `fetch` this package does not own.
+     */
+    readonly fetch?: FetchPort | undefined;
+};
+/** Thrown where `globalOutbound` is absent. Asserted rather than skipped, so it cannot drift. */
+export declare const NO_GLOBAL_OUTBOUND_MESSAGE = "fetch(): this actor has no global outbound, so an ambient fetch cannot be gated.";
+/**
+ * The message a scope answers with when it is reached from another actor's
+ * slice. Exported because the failure it names is the one thing about this layer
+ * that cannot be found by reading the calling code — see `requireOwnSlice`.
+ */
+export declare const FOREIGN_SLICE_MESSAGE: string;
+/**
+ * ← `ServiceWorkerGlobalScope`, the async-primitive half. One per actor.
+ *
+ * A consumer installs this into whatever scope its actor's code reads —
+ * `globalThis` for a class in the worker's own module graph, a module-scoped
+ * binding for a class that arrived as a dynamically-loaded Worker source, which
+ * is upstream's own arrangement (a dynamic Worker has its own global scope bound
+ * to its own context, §1.11).
+ */
+export declare class ActorGlobalScope {
+    #private;
+    readonly scheduler: Scheduler;
+    readonly crypto: GatedCrypto;
+    constructor(ctx: IoContext, options?: ActorGlobalScopeOptions);
+    /** Opaque identity available only during an external entry's synchronous body. */
+    get currentExternalEntry(): object | undefined;
+    /** Re-enter this actor after a host promise settles. */
+    awaitIo<T>(promise: Promise<T>): Promise<T>;
+    /** ← `ServiceWorkerGlobalScope::setTimeout` (`global-scope.c++:944-950`). */
+    setTimeout(callback: (...args: never[]) => void, msDelay?: number, ...args: unknown[]): number;
+    /** ← `ServiceWorkerGlobalScope::clearTimeout` (`global-scope.c++:967-975`). */
+    clearTimeout(id?: number | null): void;
+    /** ← `ServiceWorkerGlobalScope::setInterval` (`global-scope.c++:959-965`). */
+    setInterval(callback: (...args: never[]) => void, msDelay?: number, ...args: unknown[]): number;
+    /** ← `ServiceWorkerGlobalScope::clearInterval`, which is `clearTimeout`'s own body. */
+    clearInterval(id?: number | null): void;
+    /**
+     * ← `ServiceWorkerGlobalScope::fetch` (`global-scope.h:703-705`) reaching
+     * `fetchImpl` (`http.c++:1740-1760`).
+     *
+     * Two gates, in upstream's order. The OUTPUT gate first, because an outbound
+     * request is exactly the observation §1.1 exists to hold back — "blocks all
+     * outgoing messages from an actor that would allow the rest of the world to
+     * observe the actor's state" — and `fetchImpl` waits on it before the request
+     * departs (`http.c++:1488`, `:1759`). The INPUT gate is released for the
+     * duration and re-taken on resumption, which is `awaitIo` and which is what
+     * makes an actor awaiting the network stay re-entrant (§1.3).
+     */
+    fetch(input: RequestInfo | URL, init?: RequestInit): Promise<Response>;
+}
+/**
+ * The bound form of `ActorGlobalScope`, which is what a scope object actually
+ * holds. Bound, because these are read as free variables — `setTimeout(…)`, not
+ * `scope.setTimeout(…)` — so a method that needed its receiver would break the
+ * moment it was destructured, which is exactly how a dynamically-loaded Worker
+ * source receives them.
+ */
+export type ActorScopeBindings = {
+    readonly awaitIo: <T>(promise: Promise<T>) => Promise<T>;
+    readonly scheduler: {
+        wait(delay: number, options?: SchedulerWaitOptions): Promise<void>;
+        yield(): Promise<void>;
+    };
+    readonly setTimeout: (callback: (...args: never[]) => void, msDelay?: number, ...args: unknown[]) => number;
+    readonly clearTimeout: (id?: number | null) => void;
+    readonly setInterval: (callback: (...args: never[]) => void, msDelay?: number, ...args: unknown[]) => number;
+    readonly clearInterval: (id?: number | null) => void;
+    readonly fetch: (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+    readonly crypto: Crypto;
+    readonly currentExternalEntry?: object | undefined;
+};
+/**
+ * The capabilities an actor's code reads, bound to one scope.
+ *
+ * `resolve` is a thunk because the owner may change across root respawns, or a
+ * shared realm may select the actor whose synchronous slice is running. It is
+ * consulted only when an operation begins; it does not propagate identity
+ * across a promise continuation. Actor-owned code should retain its explicit
+ * scope instead. A single-actor host simply writes `() => scope`.
+ */
+export declare function actorScopeBindings(resolve: () => ActorGlobalScope): ActorScopeBindings;
+/**
+ * Write the web-platform bindings onto a scope object — `globalThis` for a class in the worker's
+ * own module graph, a plain object a dynamically-loaded source destructures for
+ * one that is not.
+ *
+ * **A host should call this rather than assigning the names itself**, and the
+ * reason is the failure it prevents: a host that installs five of the six leaves
+ * one primitive ungated, and an ungated primitive that WORKS is invisible until
+ * a continuation after it touches storage — possibly never, on the path that
+ * matters. The set is the package's, so it can grow without every host growing
+ * with it.
+ *
+ * **It ASSIGNS, and that is not incidental.** Chrome ships a `scheduler` global
+ * in dedicated workers — the Prioritized Task Scheduling API, `postTask` and
+ * `yield`, no `wait` — so a host writing `??=` silently keeps Chrome's and every
+ * timer await fails somewhere else entirely with `scheduler.wait is not a
+ * function`. Measured on the browser conformance lane, and the extension meets
+ * the same global at cutover.
+ *
+ * **What a host must do first:** capture whatever raw timers its own substrate
+ * needs. Everything BELOW the runtime — a `Timer` port, a transport's own
+ * retries — has to keep the platform's, or arming a timeout goes through a
+ * timeout. That is not hypothetical: pointing the node lane at these primitives
+ * without capturing first produced `RangeError: Maximum call stack size
+ * exceeded` on the first row.
+ */
+export declare function installActorScope(target: object, resolve: () => ActorGlobalScope): void;
+export {};

package/dist/src/api/http.d.ts

@@ -0,0 +1,52 @@
+/**
+ * ← workerd `src/workerd/api/http.{h,c++}` — the gating, and nothing else.
+ *
+ * `http.c++` is 2,400 lines of `Request`, `Response`, `Headers`, `Body`,
+ * `Fetcher` and the redirect machine. None of it is ported: the substrate ships
+ * all of it, to the same specification, and re-implementing WHATWG Fetch over
+ * `fetch` would be the feature-subset failure the porting philosophy describes,
+ * with a much larger surface than the eighty lines it saves.
+ *
+ * What the substrate's copy cannot have is the half that is not in the spec at
+ * all: **every asynchronous step of a fetch is an io-context operation**, so on
+ * workerd the code after `await res.json()` resumes holding an input lock the
+ * same way the code after `await fetch(…)` does. §1.3 is the whole of it —
+ * `api/http.c++` contains ten `awaitIo(` calls and zero
+ * `awaitIoWithInputLock`, so an outbound request releases the input gate and its
+ * continuation re-takes one.
+ *
+ * A `Response` is where that matters and where it is easiest to miss. `fetch`
+ * itself is one `awaitIo` in `api/global-scope.ts`, which is obvious; the body
+ * is a SECOND await, arbitrarily later, and a raw `Response` would resolve it
+ * from a promise this package does not own. The continuation would come back
+ * with an empty invocation stack and the next `ctx.storage` call would throw —
+ * divergence 147, arriving from a line that looks like it only parses JSON.
+ *
+ * Upstream reaches the same place by construction rather than by wrapping: a
+ * `Response`'s body is an `IoOwn<ReadableStream>`, and `IoOwn` is precisely "a
+ * thing that may only be touched from inside its IoContext"
+ * (`io-context.h`'s `IoOwn`/`IoPtr`/`DeleteQueue` block). There is no such
+ * ownership here — GC makes a cross-context dereference impossible in the way
+ * that block guards against, which is why the package does not port it — so the
+ * property it produced has to be produced by the wrapper below.
+ *
+ * Spec: §1.3 and decision 1 in
+ * docs/decisions.md.
+ */
+type IoAwaiter = {
+    awaitIo<T>(promise: Promise<T>): Promise<T>;
+};
+/** Wrap a host-provided request so consuming or streaming its body resumes gated. */
+export declare function gateRequestBody(ctx: IoAwaiter, request: Request): Request;
+/** Wrap an outbound response so consuming or streaming its body resumes gated. */
+export declare function gateResponseBody(ctx: IoAwaiter, response: Response): Response;
+/**
+ * ← the same property one layer down: a body read through `getReader()` is a
+ * sequence of awaits, so each `read()` is one.
+ *
+ * Only the default reader is covered. A BYOB reader is refused rather than
+ * passed through ungated — see `BYOB_READER_UNGATABLE_MESSAGE`.
+ */
+export declare const BYOB_READER_UNGATABLE_MESSAGE: string;
+export declare function gateReadableStream<T>(ctx: IoAwaiter, stream: ReadableStream<T>): ReadableStream<T>;
+export {};