@mcp-b/do-runtime 0.1.0

package/dist/src/io/io-channels.d.ts

@@ -0,0 +1,191 @@
+/**
+ * ← workerd `src/workerd/io/io-channels.h` — `IoChannelFactory::ActorClassChannel`,
+ * `ResourceLimits`, `WorkerStubChannel` and `DynamicWorkerSource`.
+ *
+ * **A partial port, and deliberately so.** `io-channels.h` is 492 lines and
+ * almost all of it is outgoing I/O: `SubrequestChannel`, `CacheClient`,
+ * `TimerChannel`, logfwdr and channel tokens. Every one of those is either a
+ * substrate boundary or a transport concern, and none of them is reachable from
+ * the files this module exists to serve. What IS reachable is four types. One is
+ * the token `DurableObjectClass` holds and
+ * `Worker::Actor::FacetManager::StartInfo` carries, which has to live in `io/`
+ * because `io/worker.ts` names it and `io/` may not see `api/`. The other three
+ * are the dynamic-worker half `api/worker-loader.ts` consumes; an earlier
+ * revision of this header deferred them to Section 7, which is where they landed.
+ *
+ * Two things upstream has here that this package does not, both for the same
+ * reason. `IoChannelFactory` itself is absent because **there is no numbered
+ * channel table**: upstream resolves a binding to a `uint` at configuration time
+ * and every channel method takes that number, while here a binding is a property
+ * of the `env` object the consumer supplies. So every `kj::OneOf<uint,
+ * IoOwn<...>>` in `api/actor.ts` keeps only its object arm — which is upstream's
+ * own alternative, offered on `DurableObjectNamespace` for exactly the case
+ * where a namespace "is constructed dynamically within an execution context,
+ * rather than being a long-lived binding". And `ActorChannel` is absent because
+ * its one method returns a `WorkerInterface`, capnp dispatch with no port; the
+ * JS-visible product of an actor channel is a `Fetcher`, so the two collapse —
+ * the same collapse `io/worker.ts`'s `FacetManager.getFacet` and
+ * `server/actor-container.ts`'s `FacetHandle.stub` already make. That collapse
+ * reaches `SubrequestChannel` too, which is why `DynamicWorkerSource`'s outbound
+ * and tail fields below are `Fetcher`s.
+ *
+ * Spec: §1.10, §1.11, decisions 14 and 15 in
+ * docs/decisions.md.
+ */
+import type { WorkerSource } from "./worker-source.js";
+/**
+ * ← `IoChannelFactory::ActorClassChannel`. Upstream: "a reference to an actor
+ * class in another worker. This class acts as a token which can be passed into
+ * other interfaces that might use the actor class, particularly
+ * `Worker::Actor::FacetManager`" and "This class has no functional methods, since
+ * it serves as a token to be passed to other interfaces (namely the facets API)."
+ *
+ * Ours is the same token with the contents workerd keeps opaque made visible,
+ * because they have to be: upstream's token is opaque precisely because the class
+ * is in another isolate and only the supervisor can resolve it, whereas here the
+ * container resolves it against the `ctx.exports` record the consumer handed in.
+ * The class name is the host-visible value the container needs to resolve the
+ * otherwise opaque token against `ctx.exports`.
+ *
+ * `requireAllowsTransfer()` is upstream's and is kept, because it is the one
+ * behaviour on the token rather than data: it decides whether a stub over this
+ * channel may be serialized, and `DurableObjectClass.serialize` calls it before
+ * anything else.
+ */
+export interface ActorClassChannel {
+    /** The `ctx.exports` key the container resolves this class under. */
+    readonly className: string;
+    /**
+     * ← `requireAllowsTransfer()`. "Throws a JSG error if a Fetcher backed by this
+     * channel should not be serialized and passed to other workers."
+     */
+    requireAllowsTransfer(): void;
+}
+/**
+ * ← `ResourceLimits` (`io-channels.h:375-386`). "provides a means to control the
+ * resource allocation for a worker stage via a set of optionally overridden
+ * parameters."
+ *
+ * **It is a no-op in workerd and it is a no-op here.** The bag is accepted by
+ * `WorkerLoader.load`, by `WorkerStub.getEntrypoint`/`getDurableObjectClass`, and
+ * by both `WorkerStubChannel` methods; the one implementation that receives it —
+ * `Server::WorkerLoaderNamespace::WorkerStubImpl::getEntrypointResolved` and
+ * `::getActorClassResolved` (`server.c++:4359`, `:4364`) — names the parameter
+ * and never reads it. `DynamicWorkerSource.limits` is likewise written by
+ * `toDynamicWorkerSource` (`worker-loader.c++:165`) and read by nothing in the
+ * open-source tree. So local development never reproduces limit enforcement on
+ * either runtime, and a reader who assumes otherwise is reading a field that is
+ * carried to production and dropped in workerd. `clone()` is absent for the
+ * reason `io/worker-source.ts`'s header gives.
+ */
+export type ResourceLimits = {
+    readonly cpuMs?: number;
+    readonly subRequests?: number;
+};
+/**
+ * ← `CompatibilityDateValidation` (`io/compatibility-date.h:12-32`). How far into
+ * the future a dynamic Worker's `compatibilityDate` may be, which upstream says
+ * "will differ between workerd vs. production".
+ */
+export type CompatibilityDateValidation = 
+/** "Allow dates up through the date specified by `supportedCompatibilityDate`." */
+"codeVersion"
+/** "Allow dates up to through the current date. This should ONLY be used by Cloudflare." */
+ | "currentDateForCloudflare"
+/** "Allow any future date. This should only be used to test `compileCompatibilityFlags` itself." */
+ | "futureForTest";
+/**
+ * ← the arguments `compileCompatibilityFlags` takes
+ * (`io/compatibility-date.h:38-44`), where upstream's `DynamicWorkerSource` holds
+ * the compiled `CompatibilityFlags::Reader` it returns.
+ *
+ * **The compilation is a substrate boundary and this is the request that replaces
+ * it.** `compileCompatibilityFlags` walks the capnp *schema* of
+ * `CompatibilityFlags` reflectively — every flag's enable/disable names, its
+ * default-on date and its experimental annotation are schema annotations
+ * (`io/compatibility-date.c++:102-260`) — and this package has no
+ * `compatibility-date.capnp`, no schema reflection and no `FeatureFlags`. It is
+ * the same absence the four flags `api/actor.ts` meets already records. So the
+ * inputs travel to whatever is on the far side of `loadIsolate`, which is the
+ * layer that has an isolate to configure and therefore the only layer that could
+ * validate them.
+ */
+export type CompatibilityFlagsRequest = {
+    readonly compatibilityDate: string;
+    readonly compatibilityFlags: readonly string[];
+    readonly allowExperimental: boolean;
+    readonly dateValidation: CompatibilityDateValidation;
+};
+/**
+ * ← the two arguments `WorkerStubChannel`'s methods take besides the entrypoint
+ * name (`io-channels.h:397-406`).
+ *
+ * `props` is upstream's `Frankenvalue`, which is a JS value plus a cap table; here
+ * it is the JS value, because there is no numbered channel table for a cap table
+ * to index.
+ */
+export type EntrypointRequest = {
+    /** `kj::none` selects the default entrypoint, as `"default"` does. */
+    readonly name: string | undefined;
+    readonly props: unknown;
+    readonly limits: ResourceLimits | undefined;
+};
+/**
+ * ← `WorkerStubChannel` (`io-channels.h:390-408`). "Represents a dynamically-loaded
+ * Worker to which requests can be sent. This object is returned before the Worker
+ * actually loads, so if any errors occur while loading, any requests sent to the
+ * Worker will fail, propagating the exception."
+ *
+ * That last sentence is the contract `api/worker-loader.ts` depends on twice over:
+ * it is why `WorkerLoader.get` can return a stub synchronously while its code
+ * callback has not run, and it is why upstream's own tests assert a bad module
+ * list from `worker.getEntrypoint().greet(...)` rather than from `get()`
+ * (`api/tests/worker-loader-test.js:812`).
+ *
+ * Upstream splits each method in two — a non-virtual half that "waits for `props`
+ * to resolve first" and a virtual `…Resolved` half. The waiting half resolves
+ * `Frankenvalue` cap-table entries that are still promises; a JS value has no
+ * unresolved arm, so the pair collapses to one method.
+ */
+export interface WorkerStubChannel {
+    /** ← `getEntrypoint` / `getEntrypointResolved`, with `SubrequestChannel` collapsed. */
+    getEntrypoint(request: EntrypointRequest): Fetcher;
+    /** ← `getActorClass` / `getActorClassResolved`. */
+    getActorClass(request: EntrypointRequest): ActorClassChannel;
+}
+/**
+ * ← `DynamicWorkerSource` (`io-channels.h:411-455`). "Source code needed to
+ * dynamically load a Worker."
+ *
+ * Field for field, with three departures, each recorded on the type it touches:
+ * `compatibilityFlags` carries the request rather than the compiled reader
+ * (`CompatibilityFlagsRequest` above), the three `SubrequestChannel` fields are
+ * `Fetcher`s (this file's header), and `ownContent` / `ownContentIsRpcResponse` /
+ * `clone()` / `ensureAllResolved()` are kj lifetime bookkeeping with nothing to
+ * bookkeep (`io/worker-source.ts`'s header).
+ */
+export type DynamicWorkerSource = {
+    readonly source: WorkerSource;
+    readonly compatibilityFlags: CompatibilityFlagsRequest;
+    readonly limits: ResourceLimits | undefined;
+    /**
+     * "`env` object to pass to the loaded worker. Can contain anything that can be
+     * serialized to a `Frankenvalue`."
+     */
+    readonly env: unknown;
+    /**
+     * "Where should global fetch() (and connect()) be sent?"
+     *
+     * **`undefined` means blocked, and that is upstream's encoding rather than a
+     * shorthand.** The JS-facing `globalOutbound` has three states — omitted, `null`,
+     * a `Fetcher` — and `toDynamicWorkerSource` collapses them to two here:
+     * `kj::none` is written only for the explicit `null`, while the omitted case is
+     * resolved at that layer into the calling worker's own outbound
+     * (`worker-loader.c++:122-139`). By the time a source exists, "inherit" is no
+     * longer a state.
+     */
+    readonly globalOutbound: Fetcher | undefined;
+    /** "Tail workers that should receive tail events for invocations of the dynamic worker." */
+    readonly tails: readonly Fetcher[];
+    readonly streamingTails: readonly Fetcher[];
+};

package/dist/src/io/io-context.d.ts

@@ -0,0 +1,451 @@
+/**
+ * ← workerd `src/workerd/io/io-context.{h,c++}`
+ *
+ * IoContext: the one door, plus the two await forms.
+ *
+ * This is the file with no true upstream correspondence for its *enforcement*.
+ * Workerd acquires the input gate at isolate entry, so acquisition is
+ * structural. We have no isolate hook, so a lock is taken at our own dispatch
+ * boundary instead. See "The enforcement point is the one thing we cannot port"
+ * in the design record.
+ *
+ * What this file does, stated before anything about how it got here:
+ *
+ *  1. `#currentInputLocks` is a STACK of the locks held by the slices that are
+ *     running. It is upstream's single `kj::Maybe<InputGate::Lock>
+ *     currentInputLock` member (`io-context.h:993`) with the `Maybe` widened,
+ *     and a "frame" is an entry in it. A frame carries nothing else: the only
+ *     two things ever read from one are the lock (`getInputLock`) and the
+ *     critical section that lock belongs to (`getCriticalSection`), and the
+ *     lock answers both.
+ *  2. A lock is released, and leaves the stack, at the END OF THE MICROTASK
+ *     CHECKPOINT of the slice holding it — not when that slice's synchronous
+ *     body returns. That is upstream's own boundary, not a relaxation of it:
+ *     `runImpl`'s inner `KJ_DEFER` calls `js.runMicrotasks()`
+ *     (`io-context.c++:1262`) and `runInContextScope`'s outer one then clears
+ *     `currentInputLock` (`:1214`), inner scope first, so the whole checkpoint
+ *     drains under the lock. `currentInputLock` holds the `Lock` by value, so
+ *     clearing it is the release. `atCheckpointEnd` below is that point.
+ *  3. NEITHER await form releases anything at the moment of the await.
+ *     `awaitIo` reads `getCriticalSection()` and `awaitIoWithInputLock` takes
+ *     an `addRef`; both then return a promise and let the slice end normally.
+ *     So an invocation that calls `awaitIo` keeps the gate until its own
+ *     checkpoint-end exit and the gate opens there — which is still before any
+ *     real I/O can complete, so "a bare timer releases the input gate" holds.
+ *     Upstream is the same: `getCriticalSection()` (`io-context.c++:362`) does
+ *     not touch `currentInputLock`, and `:1214` is the only place that clears
+ *     it. The difference between the two forms is entirely on the far side —
+ *     `awaitIo` re-enters through `run(func, criticalSection)` and queues for a
+ *     fresh lock, `awaitIoWithInputLock` re-enters holding the ref it took.
+ *  4. Removal from the stack is by identity, not by popping, because entries do
+ *     overlap — three deep in the unit tests. One invocation can have several
+ *     held awaits outstanding (`Promise.all` over two storage reads), and a
+ *     section's last body slice overlaps the slice that resolves it.
+ *
+ * Two mechanics were validated against real workerd before this scaffolding
+ * landed, and both are easy to get wrong:
+ *
+ *  1. The ambient "which lock am I under" must be a STACK of invocation frames,
+ *     not a single slot, so that `current` always names the running invocation.
+ *     The prototype that found this stated it as "`awaitIo` splices its frame
+ *     out and re-pushes the SAME frame on resume". That is not what happens
+ *     here and the difference is worth knowing: nothing splices at the point of
+ *     the await, because a lock already leaves the stack when its slice ends,
+ *     which is the same event that releases it (`#exit` does both). A
+ *     resumption then pushes a fresh lock. The prototype needed the splice
+ *     because its door held one lock for a whole invocation; the identity that
+ *     has to survive an await here is the critical section, and that is
+ *     captured at the call rather than looked up later.
+ *  2. That ambient is safe here for a reason that does NOT generalise to the
+ *     §2.3 ambient-field hazard: the gate guarantees pushes and pops nest
+ *     properly in time, because only one holder chain is inside at once.
+ *     `_cf_currentSubAgentBridge` has no such guarantee, which is why it is a
+ *     live bug and this is not.
+ *
+ * Consequence: no async context is required. Do not add a dependency on
+ * decision 8 here without re-running the conformance gate suite first.
+ *
+ * The invariant a future simplifier has to re-check: a single slot would pass
+ * every test in `io-context.test.ts`, and that was established by trying it,
+ * not by argument. `current()` is only read from inside a slice, every slice
+ * pushes its own lock last, and no second slice can begin while an earlier
+ * frame is still waiting for its checkpoint-end exit — that frame is holding
+ * the gate. So the top of a stack and the last write to a slot always agree.
+ * The stack is still what is here, because a slot would be holding a stale
+ * value at every one of the overlaps in (4), and that is unobservable for
+ * exactly as long as the invariant holds. Tightening (2) back to the end of the
+ * synchronous body breaks it immediately, which is the regime the mechanic was
+ * found in.
+ *
+ * Spec: §1.2, §1.3, §1.5, §1.6, §1.7.1, §1.9, decisions 1, 2, 4 and 13 in
+ * docs/decisions.md.
+ *
+ * `TimeoutManager` is the only part of this file a consumer's own code reaches
+ * directly: every host-provided async primitive a
+ * Durable Object can await has to route through here, or the continuation after
+ * it resumes with an empty invocation stack. `TimeoutManager` below is the
+ * timer half; `api/global-scope.ts` and `api/web-socket.ts` are the rest.
+ *
+ * Not ported, because the substrate has no equivalent to port onto: isolate and
+ * async locks (`Worker::Lock`, `jsg::Lock`, `takeAsyncLock`) and everything
+ * that exists to enter or leave an isolate — which is precisely the thing this
+ * file substitutes for; the limit enforcer and `afterLimitTimeout` (the
+ * deadline takes the `Timer` port instead); trace spans, already a recorded
+ * divergence documented in §1.12; subrequest channels and HTTP, which are
+ * `api/http.ts`'s gating over the substrate's own `fetch`;
+ * `IoOwn`/`IoPtr`/`DeleteQueue`, which guard cross-context dereferences that GC
+ * makes impossible; hang detection and `registerPendingEvent`, which need the
+ * isolate's own idea of pending work; and the thread-local
+ * `IoContext::current()` static, whose lock-resolving half the invocation stack
+ * replaces — its *identity* half is `currentSlice` below, narrowed to the
+ * synchronous slice, with one consumer and no resolver. `EventOutcome` and
+ * `RequestObserver` are metrics types with no port, so `waitUntilStatus()`
+ * returns the first exception instead.
+ */
+import { CriticalSection, type InputGate, Lock, type OutputGate } from "./io-gate.js";
+/**
+ * ← `kj::Timer`, threaded into IoContext upstream.
+ *
+ * A port with one production implementation would be an invented seam; this
+ * one has two (real clock in browser and workerd) plus a fake the conformance
+ * suite cannot exist without — the 30-second critical-section deadline and the
+ * alarm retry ladder are not assertable on wall-clock time in CI.
+ */
+export interface Timer {
+    now(): number;
+    /** `kj::Timer::afterDelay`. The signal replaces kj's cancel-by-drop. */
+    afterDelay(ms: number, signal?: AbortSignal): Promise<void>;
+}
+/**
+ * ← the `Worker::Actor` surface reached through an `IoContext`:
+ * `a.getInputGate()`, `a.getOutputGate()` and `a.shutdownActorCache()` from
+ * `io-context.{h,c++}` itself, plus `assertCanSetAlarm()`, which
+ * `api/actor-state.c++:486` reaches through
+ * `IoContext::current().getActorOrThrow()`.
+ *
+ * `Worker::Actor` lives in `io/worker.h`, the same Bazel target as this file, so
+ * naming the members its consumers use is upstream's own layering rather than a
+ * new seam. Every context here is an actor context — there is no non-actor
+ * request in a Durable Object runtime — so upstream's
+ * `kj::Maybe<Worker::Actor&>` and every branch that tests it collapse to this
+ * being required, and `getActorOrThrow()` cannot actually throw.
+ */
+export interface Actor {
+    getInputGate(): InputGate;
+    getOutputGate(): OutputGate;
+    /** Abort abandons scheduled writes rather than flushing them (§1.6). */
+    shutdownActorCache(reason: unknown): void;
+    /**
+     * ← `Worker::Actor::assertCanSetAlarm()` (`io/worker.c++:4090`). Every branch
+     * of it reads the actor's class-instance lifecycle, which `server/` owns, so
+     * `api/actor-state.ts`'s obligation is to call it and the container's is to
+     * answer it.
+     */
+    assertCanSetAlarm(): void;
+}
+/** ← `afterLimitTimeout(30 * kj::SECONDS)` in `IoContext::blockConcurrencyWhile`. */
+export declare const BLOCK_CONCURRENCY_WHILE_TIMEOUT_MS = 30000;
+/** Copied verbatim: users and upstream tests match on it. */
+export declare const BLOCK_CONCURRENCY_WHILE_TIMEOUT_MESSAGE: string;
+/**
+ * THE check every storage entry point in `api/` makes before touching the
+ * database, and the only place this package throws for a missing input lock.
+ *
+ * Upstream never faces the question. `IoContext::current()` is a thread-local
+ * read with a `KJ_REQUIRE` behind it, and it cannot fail for a storage call
+ * because isolate entry is the only way into an actor and it always took a
+ * lock. We have no isolate hook (see this file's header), so a continuation
+ * that resumed from a raw `setTimeout`, a raw `fetch`, or any other promise the
+ * runtime does not own comes back with an empty invocation stack, and its next
+ * storage call reaches `ActorSqlite` — which is synchronous, touches no gate,
+ * and would happily serve it outside any transaction boundary.
+ *
+ * So this throws, matching the assert. It is deliberately ONE function called
+ * from every entry point rather than a check written at each of them: the
+ * policy is a design decision that belongs to the design record, and when it
+ * changes it has to change in one place rather than across a surface the
+ * vendored consumer reaches from hundreds of call sites. There is no lenient
+ * mode, no flag, and no implicit acquire — a lost invocation is loud, and a
+ * lost transaction boundary is not.
+ */
+export declare function requireInputLock(ctx: IoContext, op: string): void;
+/**
+ * The end of the microtask checkpoint — the moment `runImpl`'s `KJ_DEFER` fires.
+ *
+ * Upstream drains the whole checkpoint INSIDE the isolate run: the defer calls
+ * `js.runMicrotasks()` and only the outer defer in `runInContextScope` then
+ * clears `currentInputLock`. So a continuation that awaits nothing but
+ * already-resolved promises stays under the same lock, and a continuation that
+ * waits on real I/O does not. In JS the only observable end of a microtask drain
+ * is the next macrotask, so that is where a lock leaves the invocation stack.
+ *
+ * Measured, because the obvious alternatives are wrong in ways nothing catches:
+ * releasing synchronously when the invoked function returns, or on the next
+ * microtask, both hand the lock back BEFORE the code awaiting the I/O resumes as
+ * soon as one promise sits between the two — one `async` wrapper, a `.then`, a
+ * `Promise.all` — and `actor-state.ts` is exactly such a wrapper. The gate would
+ * then open in the middle of a storage await with no test failing, which is the
+ * silent loss of atomicity §1.7.1 names.
+ *
+ * `MessageChannel` and not `setTimeout`, decided by benchmark rather than by
+ * argument, because the two are three orders of magnitude apart on the shapes
+ * that wait for a release. A chain of these schedules each hand-off from inside
+ * the previous one's callback, so a `setTimeout` chain's nesting level climbs
+ * past five and stays there, where browsers clamp it to 4ms. Median per hand-off
+ * over 50 chained hops:
+ *
+ *   |                        | setTimeout | MessageChannel |
+ *   | node                   | 1.273 ms   | 0.018 ms       |
+ *   | chromium page          | 4.96 ms    | 0.024 ms       |
+ *   | chromium Worker        | 5.542 ms   | 0.022 ms       |
+ *
+ * Only two shapes pay it: an `awaitIo` chain, which has to re-acquire the lock
+ * its slice gave up, and a queue of events waiting on the holder. A chain of
+ * held storage awaits does not — the lock passes from `addRef` to `addRef` and
+ * the release is off the critical path. So 50 sequential facet RPCs cost 277ms
+ * of pure clamp in a Worker under `setTimeout` and 1.1ms under this.
+ *
+ * One channel per BATCH, and a batch is an explicit array: `atCheckpointEnd`
+ * pushes onto `pendingCheckpointEnds` and only the push that finds it empty opens
+ * a channel. Ordering then comes from the array, which the language guarantees,
+ * rather than from delivery order across separate channels, which no
+ * specification does. That mattered because the storage engine below depends on
+ * a commit scheduled inside a slice running before the release scheduled at the
+ * end of that slice; separate channels do deliver in post order in Node,
+ * measured across 200 of them including one scheduled from inside another's
+ * callback, but a browser that chose otherwise would open the gate onto a
+ * transaction a previous event left open, and nothing would say so.
+ *
+ * A callback scheduled DURING a drain lands in the next batch, which is the
+ * semantics to want: one hand-off is one checkpoint end, and a slice that begins
+ * inside this drain gets its own. The drain runs every callback even if one
+ * throws, and rethrows the first exception afterwards, because abandoning the
+ * rest of a batch is how a gate wedges with nothing to see.
+ *
+ * A long-lived shared port was rejected for the reason it always is: it has to be
+ * closed on abort and `unref`'d so it cannot hold a test runner's event loop
+ * open, and an `unref`'d port can drop a release at exit — a wedged gate. A
+ * channel that lives for exactly one message cannot. Batching gets most of what
+ * a shared port was worth anyway: a slice that schedules a commit and a release
+ * now allocates one channel where it used to allocate two.
+ *
+ * **Exported because `kj::evalLater()` is this same point.** `ActorSqlite` opens
+ * its implicit transaction on the first write and commits it "on the next turn of
+ * the event loop" (`actor-sqlite.c++:352-357`); upstream's next turn is after the
+ * isolate run, which is after `js.runMicrotasks()`, which is after
+ * `currentInputLock` is cleared. Upstream's two boundaries are one boundary, and
+ * they stay one here only if the commit rides the same primitive as the release.
+ * Two consequences the storage engine depends on, both properties of this
+ * function rather than of `ActorSqlite`:
+ *
+ *  1. **Everything that holds the input lock across an await is a microtask
+ *     chain.** `awaitIoWithInputLock` resumes through `#awaitIoImpl`'s `.then`
+ *     into `run(func, lock)`, which never waits on the gate. So a whole run of
+ *     held storage awaits finishes before the next hand-off and its writes are
+ *     one transaction (§1.7.1 row 1).
+ *  2. **Everything that releases it needs at least one hand-off.** `awaitIo`
+ *     resumes through `gate.wait()`, which cannot resolve until `#exit` runs
+ *     here. So a timer or outbound await puts the commit between the two writes
+ *     (§1.7.1 row 2).
+ *
+ */
+export declare function atCheckpointEnd(run: () => void): void;
+/** ← `IoContext::tryCurrent()` (`io-context.c++:1416-1422`), over the narrowed scope above. */
+export declare function tryCurrentSlice(): IoContext | undefined;
+/**
+ * ← `jsg::isExceptionFromInputGateBroken` (`jsg/exception.c++:168-172`):
+ * "annotateBroken() produces 'broken.inputGateBroken; {message}', optionally
+ * prefixed with 'remote.' when crossing RPC boundaries. Strip the remote prefix
+ * first, then check the tag."
+ *
+ * Its writer is `annotateInputGateBroken` directly above, which is why the two
+ * live together rather than the reader moving to its consumer: `jsg/` has no
+ * module here, and a prefix known in two places is a prefix that drifts.
+ */
+export declare function isExceptionFromInputGateBroken(exception: unknown): boolean;
+/**
+ * ← `jsg::EXCEPTION_IS_USER_ERROR` (`jsg/exception.h:160`), a
+ * `kj::Exception::DetailTypeId` attached to an arbitrary exception rather than a
+ * type of exception.
+ *
+ * A symbol-keyed property is the closest JS has: it rides any thrown object,
+ * survives a rethrow, and cannot collide with anything an application writes.
+ * `Symbol.for` rather than `Symbol()` so the detail is still legible after the
+ * exception crosses a realm — the mistake decision 18 records capnweb making.
+ */
+export declare const EXCEPTION_IS_USER_ERROR: unique symbol;
+/** ← `error.setDetail(jsg::EXCEPTION_IS_USER_ERROR, kj::heapArray<byte>(0))`. */
+export declare function setUserErrorDetail(exception: unknown): void;
+/** ← `e.getDetail(jsg::EXCEPTION_IS_USER_ERROR) != kj::none`. */
+export declare function hasUserErrorDetail(exception: unknown): boolean;
+export declare class IoContext {
+    #private;
+    constructor(actor: Actor, timer: Timer);
+    /**
+     * Get the current input lock. Throws an exception if no input lock is held (e.g. because
+     * this is not an actor request).
+     *
+     * ← `KJ_ASSERT_NONNULL(currentInputLock, ...).addRef()`. The `addRef` IS the §1.2
+     * distinction: it is the only way to hold the gate past the end of this slice.
+     */
+    getInputLock(): Lock;
+    /** Get the current CriticalSection, if there is one, or returns null if not. */
+    getCriticalSection(): CriticalSection | undefined;
+    /** Is a gated slice running? The question `IoContext::hasCurrent()` answers upstream. */
+    hasCurrent(): boolean;
+    /**
+     * ← `IoContext::isCurrent()` (`io-context.c++:1428-1430`), over the narrowed
+     * scope `currentSlice` documents: true only while a synchronous body of THIS
+     * context is on the JS stack.
+     *
+     * Distinct from `hasCurrent()` above, which asks whether this context holds a
+     * lock at all — true throughout an outstanding held await, and true for a
+     * parent whose slice is awaiting a facet while the facet's body runs. This one
+     * is the question a shared global has to answer: is the code calling me this
+     * actor's?
+     */
+    isCurrentSlice(): boolean;
+    /**
+     * ← `IoContext::getActorOrThrow()`. Upstream's throws when the request is not
+     * an actor request; there is no such request here, so it is a plain accessor.
+     */
+    getActorOrThrow(): Actor;
+    /** ← `IoContext::now()` (`io-context.h:703`), which reads the same timer. */
+    now(): number;
+    /**
+     * ← `IoContext::setTimeoutImpl` (`io-context.c++:885-899`), clamp included.
+     *
+     * The generator parameter is gone with `TimeoutId::Generator` — see
+     * `TimeoutManager`'s header — so the signature is upstream's minus that one
+     * argument.
+     */
+    setTimeoutImpl(repeat: boolean, callback: () => void, msDelay: number): number;
+    /** ← `IoContext::clearTimeoutImpl` (`io-context.c++:901-903`). */
+    clearTimeoutImpl(id: number): void;
+    /** ← `IoContext::getTimeoutCount` (`io-context.c++:905-907`). */
+    getTimeoutCount(): number;
+    /**
+     * Wait until all outstanding output locks have been unlocked. Does not wait for future
+     * output locks, even if they are created before past locks are unlocked.
+     */
+    waitForOutputLocks(): Promise<void>;
+    /**
+     * Check if the output gate is currently broken. This indicates that there was a problem
+     * with committing storage writes.
+     */
+    isOutputGateBroken(): boolean;
+    /** Lock output until the given promise completes. */
+    lockOutputWhile<T>(promise: Promise<T>, signal?: AbortSignal): Promise<T>;
+    /**
+     * Rejects if and when the context should be aborted, e.g. because a gate broke. This
+     * promise never resolves, only rejects.
+     */
+    onAbort(): Promise<never>;
+    /** Force context abort now. */
+    abort(exception: unknown): void;
+    /**
+     * Await the given promise and, if it throws, call `abort()` with the exception. The promise
+     * given here should just be a monitoring promise, it should not represent any sort of
+     * background work beyond monitoring.
+     */
+    abortWhen(promise: Promise<unknown>): void;
+    /**
+     * Arrange for the given promise to execute as part of this request.
+     *
+     * "In Actors, we treat all tasks as wait-until tasks, because it's perfectly legit to start
+     * a task under one request and then expect some other request to handle it later." Every
+     * context here is an actor context, so that branch is the only branch.
+     */
+    addTask(promise: Promise<void>): void;
+    /**
+     * Indicates that the script has requested that it stay active until the given promise
+     * resolves. `drainWaitUntil()` waits until all such promises have completed. Touches
+     * neither gate (§1.9).
+     */
+    addWaitUntil(promise: Promise<void>): void;
+    /** Returns the number of times addTask() has been called (even if the tasks have completed). */
+    taskCount(): number;
+    /**
+     * The first exception a background task failed with, if any.
+     *
+     * ← `waitUntilStatus()`, which returns an `EventOutcome` derived from the exception by
+     * `RequestObserver`. There is no observer here, so the exception itself is the status —
+     * and keeping it is what stops a failed background task from being swallowed, since
+     * upstream's other half of `taskFailed()` is a log this package has no port for.
+     */
+    waitUntilStatus(): unknown;
+    /**
+     * ← `IncomingRequest::drain()`, actor branch. "For actors, all promises are canceled on
+     * actor shutdown, not on a fixed timeout, because work doesn't necessarily happen on a
+     * per-request basis in actors."
+     */
+    drainWaitUntil(): Promise<void>;
+    /**
+     * Run the given callback within this context, holding an input lock.
+     *
+     * ← the two `IoContext::run()` overloads: given a CriticalSection it waits on that, given
+     * an already-held Lock it runs under it, and given neither it takes a fresh lock from the
+     * gate. The third case is what a new external event does, and it is the reason inheritance
+     * cannot be read from gate state — see `makeReentryCallback`.
+     */
+    run<T>(func: (lock: Lock) => T | PromiseLike<T>, ilOrCs?: Lock | CriticalSection): Promise<T>;
+    /**
+     * Make a function which, when called, re-enters this IoContext to run some code.
+     *
+     * Upstream, on why the critical section travels with the callback at all:
+     *
+     * > "What if the call was made within blockConcurrencyWhile()? The callback will be blocked
+     * > until the critical section ends, which could lead to deadlock if the critical section
+     * > code is waiting on it? ... The callback is allowed to run within the critical section
+     * > (blockConcurrencyWhile()) from which it was called."
+     *
+     * The section is read here, at the point of capture, and never on invocation: a new
+     * external event that inherited the running section would skip the queue and
+     * `blockConcurrencyWhile` would silently block nothing (Part 4, mechanic 2).
+     *
+     * The returned function can be called multiple times.
+     *
+     * It does not route through `io-gate.ts`'s `makeReentryCallback`, which is the same idea
+     * expressed at the gate. Upstream's `IoContext::makeReentryCallback` is literally
+     * `ctx.run(func, cs)`, and going through the gate helper instead would take a lock this
+     * file then has to make current a second time. The gate copy stays: it is the shape a
+     * consumer holding only a gate needs, and Section 1's tests cover it.
+     */
+    makeReentryCallback<Args extends unknown[], Result>(func: (lock: Lock, ...args: Args) => Result | PromiseLike<Result>): (...args: Args) => Promise<Result>;
+    /**
+     * Waits for some background I/O to complete, then executes `func` on the result.
+     *
+     * The input lock is NOT held across the wait: the resumption re-enters through
+     * `run(func, criticalSection)` and takes a fresh lock, so it queues behind whatever
+     * arrived in the meantime. This is what makes a Durable Object awaiting another Durable
+     * Object fully re-entrant (§1.3).
+     *
+     * `func` is a parameter rather than something the caller chains, for upstream's reason:
+     * chaining "required returning to the KJ event loop between running func() and running
+     * whatever JavaScript code was waiting on it". Here the equivalent cost is a promise hop
+     * outside the lock.
+     */
+    awaitIo<T>(promise: Promise<T>): Promise<T>;
+    awaitIo<T, R>(promise: Promise<T>, func: (value: T) => R | PromiseLike<R>): Promise<R>;
+    /**
+     * Waits for the given I/O while holding the input lock, so that all other I/O is blocked
+     * from completing in the meantime (unless it is also holding the same input lock).
+     *
+     * This is the whole of §1.2's asymmetry, and per §1.7.1 it is also the implicit-transaction
+     * boundary: the four async storage calls take this form, everything else takes `awaitIo`.
+     * Calling it outside a gated slice throws rather than inventing a lock — a lost invocation
+     * is loud, a lost transaction boundary is not.
+     */
+    awaitIoWithInputLock<T>(promise: Promise<T>): Promise<T>;
+    awaitIoWithInputLock<T, R>(promise: Promise<T>, func: (value: T) => R | PromiseLike<R>): Promise<R>;
+    /**
+     * Runs `callback` within its own critical section, returning its final result. If
+     * `callback` throws, the input lock will break, resetting the actor.
+     *
+     * Three behaviours live here rather than in `io-gate.ts`, which has no timer, and rather
+     * than in `api/actor-state.ts`, whose own `blockConcurrencyWhile` is a one-line forward:
+     * the 30-second deadline, the brokenness annotation, and the fact that on failure the
+     * returned promise is never settled at all.
+     */
+    blockConcurrencyWhile<T>(callback: (lock: Lock) => T | PromiseLike<T>): Promise<T>;
+}