@mcp-b/do-runtime 0.1.0

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

@@ -0,0 +1,298 @@
+/**
+ * ← workerd `src/workerd/io/io-gate.{h,c++}`
+ *
+ * An I/O gate allows someone to "lock" a type of I/O so that other concurrent tasks trying to
+ * perform that type of I/O are blocked until the lock is released.
+ *
+ * I/O gates are used in actors to implement consistency guarantees, allowing in-memory state and
+ * storage to be synchronized.
+ *
+ * Each Actor has two main gates:
+ * - Input gate: While locked, blocks all incoming I/O events of any type from being delivered to
+ *   the actor, other than the specific event or events that hold the lock. This includes
+ *   blocking responses to subrequests, timer events, input streams, etc. Used when storage
+ *   operations are outstanding, so that awaiting a storage operation does not risk allowing
+ *   concurrent events that render the state inconsistent.
+ * - Output gate: While locked, blocks all outgoing messages from an actor that would allow the
+ *   rest of the world to observe the actor's state. Held while writes that have been confirmed
+ *   to the application are still being flushed to disk. If the flush fails, these messages will
+ *   never be sent, so that the rest of the world cannot observe a prematurely-confirmed write.
+ *
+ * Three things kj gives for free and JS does not, resolved the same way at every site:
+ *
+ *  1. **Destructors.** `~Lock` releases and `~CriticalSection` diagnoses a dropped section as
+ *     deadlock. Both become explicit: `Lock.release()` and `CriticalSection.drop()`. A `Lock`
+ *     released twice throws rather than corrupting the refcount.
+ *  2. **Cancel-by-drop.** Dropping a `kj::Promise` unwinds its waiter. Every such site takes an
+ *     `AbortSignal`, the convention `Timer.afterDelay` already set in `io-context.ts`. Aborting a
+ *     `wait()` rejects it with `CanceledError`; a never-settling promise would be an invisible
+ *     hang, which is what this repo's fail-closed tenet exists to prevent.
+ *  3. **`kj::ForkedPromise` holding an exception with no branches.** JS reports that as an
+ *     unhandled rejection, so every promise this module stores keeps a no-op `catch` of its own
+ *     and hands observers a separate view.
+ *
+ * Error strings are copied verbatim from upstream; users and upstream tests match on them.
+ *
+ * Not ported: `SpanParent`/`SpanBuilder` tracing, since there is no `trace.h` here and upstream's
+ * own tests pass `nullptr` at every call site; and the `~InputGate` assertion that no locks
+ * outlive the gate, which guards against dangling references GC makes impossible.
+ *
+ * Spec: §1.1, §1.2, §1.5, decisions 3, 5 and 13 in
+ * docs/decisions.md.
+ */
+/**
+ * Raised when a `wait()` is cancelled through its `AbortSignal`.
+ *
+ * kj has no equivalent, because a cancelled continuation simply never runs. It is deliberately
+ * NOT a gate failure: a cancelled waiter leaves the gate exactly as it found it, so
+ * `CriticalSection.wait()` rethrows this one without calling `setBroken()`.
+ */
+export declare class CanceledError extends Error {
+    readonly name = "CanceledError";
+}
+/**
+ * ← `kj::OneOf<kj::Own<kj::PromiseFulfiller<void>>, kj::Exception> brokenState`.
+ *
+ * `InputGate` starts in `fulfiller` — it builds its promise in the constructor — while
+ * `OutputGate` starts in `none` and only makes one when `onBroken()` is first called.
+ */
+type BrokenState = {
+    readonly kind: "none";
+} | {
+    readonly kind: "fulfiller";
+    readonly reject: (exception: unknown) => void;
+} | {
+    readonly kind: "exception";
+    readonly exception: unknown;
+};
+/**
+ * Hooks that can be used to customize InputGate behavior.
+ *
+ * Technically, everything implemented here could be accomplished by a class that wraps
+ * InputGate, but the part of the code that wants to implement these hooks is far away from the
+ * part of the code that calls into the InputGate, and so it was more convenient to give the
+ * caller a way to inject behavior into InputGate.
+ */
+export interface InputGateHooks {
+    inputGateLocked(): void;
+    inputGateReleased(): void;
+    inputGateWaiterAdded(): void;
+    inputGateWaiterRemoved(): void;
+}
+/** ← `InputGate::Hooks::DEFAULT`. */
+export declare const DEFAULT_INPUT_GATE_HOOKS: InputGateHooks;
+/** ← `InputGate::Waiter`: a `kj::List` node plus the adapted promise's fulfiller. */
+declare class Waiter {
+    #private;
+    /** Rewritten by `CriticalSection.succeeded()` when a straggler is reparented. */
+    gate: InputGate;
+    readonly isChildWaiter: boolean;
+    /** ← `link.isLinked()`. */
+    linked: boolean;
+    constructor(gate: InputGate, isChildWaiter: boolean, resolve: (lock: Lock) => void, reject: (exception: unknown) => void);
+    unlink(): void;
+    fulfill(lock: Lock): void;
+    reject(exception: unknown): void;
+}
+/**
+ * An InputGate blocks incoming events from being delivered to an actor while the lock is held.
+ *
+ * Upstream marks the state below `private` and befriends `Lock` and `CriticalSection`.
+ * TypeScript has no friendship, and `protected` would not let `CriticalSection` reach these
+ * members on its *parent* gate, which `succeeded()` does. The boundary that actually holds is
+ * the package facade in `src/index.ts`, which exports none of these types.
+ */
+export declare class InputGate {
+    #private;
+    readonly hooks: InputGateHooks;
+    /**
+     * How many instances of `Lock` currently exist? When this reaches zero, we'll release some
+     * waiters.
+     *
+     * Upstream also carries a `bool isCriticalSection`, because `CriticalSection` inherits
+     * `InputGate` privately and has to `static_cast` back. `instanceof` is the same test with no
+     * cast and no field that can disagree with the object it describes.
+     */
+    lockCount: number;
+    readonly waiters: Waiter[];
+    /**
+     * Waiters representing CriticalSections that are ready to start. These take priority over other
+     * waiters.
+     */
+    readonly waitingChildren: Waiter[];
+    /** A fulfiller for onBroken(), or an exception if already broken. */
+    brokenState: BrokenState;
+    constructor(hooks?: InputGateHooks);
+    /** Wait until there are no `Lock`s, then create a new one and return it. */
+    wait(signal?: AbortSignal): Promise<Lock>;
+    /**
+     * Rejects if and when calls to `wait()` become broken due to a failed critical section. The
+     * actor should be shut down in this case. This promise never resolves, only rejects.
+     */
+    onBroken(): Promise<never>;
+    /** ← `kj::newAdaptedPromise<Lock, Waiter>(gate, isChildWaiter, span)`. */
+    newWaiterPromise(isChildWaiter: boolean, signal?: AbortSignal): Promise<Lock>;
+    releaseLock(): void;
+    /** Called when a critical section fails. All future waiters will throw this exception. */
+    setBroken(exception: unknown): void;
+}
+/** ← `InputGate::Lock`. A lock that blocks all new events from being delivered while it exists. */
+export declare class Lock {
+    #private;
+    constructor(gate: InputGate);
+    /** ← `~Lock`. */
+    release(): void;
+    /**
+     * Increments the lock's refcount, returning a duplicate `Lock`. All `Lock`s must be released
+     * before the gate is unlocked.
+     */
+    addRef(): Lock;
+    /**
+     * Start a new critical section from this lock. After `wait()` has been called on the returned
+     * critical section for the first time, no further Locks will be handed out by
+     * InputGate::wait() until the CriticalSection has been dropped.
+     *
+     * CriticalSections can be nested. If this Lock is itself part of a CriticalSection, the new
+     * CriticalSection will be nested within it and the outer CriticalSection's wait() won't
+     * produce a Lock again until the inner CriticalSection is dropped.
+     */
+    startCriticalSection(): CriticalSection;
+    /** If this lock was taken in a CriticalSection, return it. */
+    getCriticalSection(): CriticalSection | undefined;
+    isFor(otherGate: InputGate): boolean;
+    /** ← `operator==`. */
+    equals(other: Lock): boolean;
+}
+/** ← `InputGate::CriticalSection::State`. */
+type CriticalSectionState = 
+/** wait() hasn't been called. */
+"NOT_STARTED"
+/** wait() has been called once, and that wait hasn't finished yet. */
+ | "INITIAL_WAIT"
+/** First lock has been obtained, waiting for success() or failed(). */
+ | "RUNNING"
+/** success() or failed() has been called. */
+ | "REPARENTED";
+/**
+ * A CriticalSection is a procedure that must not be interrupted by anything "external".
+ * While a CriticalSection is running, all events that were not initiated by the
+ * CriticalSection itself will be blocked from being delivered.
+ *
+ * The difference between a Lock and a CriticalSection is that a critical section may succeed
+ * or fail. A failed critical section permanently breaks the input gate. Locks, on the other
+ * hand, are simply released when dropped.
+ *
+ * A CriticalSection itself holds a Lock, which blocks the "parent scope" from continuing
+ * execution until the critical section is done. Meanwhile, the code running inside the critical
+ * section obtains nested Locks. These nested locks control concurrency of the operations
+ * initiated within the critical section in the same way that input locks normally do at the
+ * top-level scope. E.g., if a critical section initiates a storage read and a fetch() at the
+ * same time, the fetch() is prevented from returning until after the storage read has returned.
+ */
+export declare class CriticalSection extends InputGate {
+    #private;
+    state: CriticalSectionState;
+    constructor(parent: InputGate);
+    /**
+     * Wait for a nested lock in order to continue this CriticalSection.
+     *
+     * The first call to wait() begins the CriticalSection. After that wait completes, until the
+     * CriticalSection is done and dropped, no other locks will be allowed on this InputGate, except
+     * locks requested by calling wait() on this CriticalSection -- or one of its children.
+     *
+     * Everything before the first `await` runs in the caller's synchronous slice, which is what
+     * lets the NOT_STARTED path take its parent lock before any other event can queue behind it.
+     */
+    wait(signal?: AbortSignal): Promise<Lock>;
+    /**
+     * Call when the critical section has completed successfully. If this is not called before the
+     * CriticalSection is dropped, then failed() is called implicitly.
+     *
+     * Returns the input lock that was held on the parent critical section. This can be used to
+     * continue execution in the parent before any other input arrives.
+     */
+    succeeded(): Lock;
+    /**
+     * Call to indicate the CriticalSection has failed with the given exception. This immediately
+     * breaks the InputGate.
+     */
+    failed(exception: unknown): void;
+    /** ← `~CriticalSection`. */
+    drop(): void;
+    /** Return a reference for the parent scope, skipping any reparented CriticalSections */
+    parentAsInputGate(): InputGate;
+}
+/**
+ * ← the gate half of `IoContext::makeReentryCallback()` (`io-context.h:1507`), which is
+ * `ctx.run(func, cs)` with the critical section captured here rather than looked up later.
+ *
+ * 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."
+ *
+ * `criticalSection` must come from the capturing lock's `getCriticalSection()`, at the moment of
+ * capture. It cannot be recovered from gate state on invocation: a *new* external event that
+ * inherited the running section would skip the queue, and `blockConcurrencyWhile` would silently
+ * block nothing (Part 4).
+ *
+ * The lock covers the callback's synchronous slice and is released when the callback returns
+ * control — decision 1, and the reason a callback that awaits something does not wedge the gate.
+ * A callback needing the lock across an await takes `lock.addRef()`, which is upstream's
+ * `awaitIoWithInputLock` in the one shape io-gate can express (§1.2).
+ *
+ * The returned function can be called multiple times.
+ */
+export declare function makeReentryCallback<Args extends unknown[], Result>(gate: InputGate, criticalSection: CriticalSection | undefined, func: (lock: Lock, ...args: Args) => Result | PromiseLike<Result>): (...args: Args) => Promise<Result>;
+/**
+ * Hooks that can be used to customize OutputGate behavior. See `InputGateHooks` for why these
+ * are injected rather than wrapped.
+ */
+export interface OutputGateHooks {
+    /**
+     * Optionally make a promise which should be raced with the lock promise to implement a
+     * timeout. The returned promise should be something that throws an exception after some
+     * timeout has expired.
+     */
+    makeTimeoutPromise(): Promise<never>;
+    outputGateLocked(): void;
+    outputGateReleased(): void;
+    outputGateWaiterAdded(): void;
+    outputGateWaiterRemoved(): void;
+}
+/** ← `OutputGate::Hooks::DEFAULT`. */
+export declare const DEFAULT_OUTPUT_GATE_HOOKS: OutputGateHooks;
+/**
+ * An OutputGate blocks outgoing messages from an Actor until writes which they might depend on
+ * are confirmed.
+ *
+ * A promise chain, not a counter (§1.1): each `lockWhile` joins a new link onto the chain and
+ * re-forks it, so a `wait()` is bound to exactly the locks outstanding when it was taken and is
+ * unaffected by any later `lockWhile`.
+ */
+export declare class OutputGate {
+    #private;
+    constructor(hooks?: OutputGateHooks);
+    /**
+     * Block all future `wait()` calls until `promise` completes. Returns a wrapper around
+     * `promise`. If `promise` rejects, the exception will propagate to all future `wait()`s. If the
+     * returned promise is canceled before completion, all future `wait()`s will also throw.
+     */
+    lockWhile<T>(promise: Promise<T>, signal?: AbortSignal): Promise<T>;
+    /**
+     * Wait until all preceding locks are released. The wait will not be affected by any future
+     * call to `lockWhile()`.
+     */
+    wait(): Promise<void>;
+    /**
+     * Rejects if and when calls to `wait()` become broken due to a failed lockWhile(). The actor
+     * should be shut down in this case. This promise never resolves, only rejects.
+     *
+     * This method can only be called once.
+     */
+    onBroken(): Promise<never>;
+    isBroken(): boolean;
+}
+export {};

package/dist/src/io/worker-source.d.ts

@@ -0,0 +1,108 @@
+/**
+ * ← workerd `src/workerd/io/worker-source.h` — the `ModulesSource` arm.
+ *
+ * "Represents the source code for a Worker … WorkerSource is a data structure
+ * that can be constructed from either representation -- as well as from
+ * non-capnp-based sources, like the dynamic worker loader API." That last clause
+ * is why this file exists at all: `api/worker-loader.ts`'s `extractSource`
+ * produces one of these, and `io/io-channels.ts`'s `DynamicWorkerSource` carries
+ * it, so it has to live in `io/` where both can see it.
+ *
+ * **A partial port, in the shape `io/io-channels.ts` already established.** Three
+ * things upstream has here have nothing to port onto:
+ *
+ *  - **The `ScriptSource` arm** — Service Workers syntax, one file plus injected
+ *    globals. It arrives from a worker *configuration*, and configuration
+ *    compilation (`server/workerd-api.c++`'s `compileScript`) has no port here.
+ *    `WorkerLoader::extractSource` provably cannot produce one either: its single
+ *    `return` is a `ModulesSource` (`api/worker-loader.c++:271-275`). So
+ *    `WorkerSource.variant` is declared with the one arm this package can reach,
+ *    and stays a tagged union so the other is additive rather than a reshape.
+ *  - **`capnpSchemas`, `pythonMemorySnapshot`, `CapnpModule` and
+ *    `dynamicEnvBuilder`** — capnp readers and an edge-runtime `env` hack, none of
+ *    which has a schema or a reader here.
+ *  - **`clone()`** — upstream deep-copies because a `WorkerSource` holds
+ *    `StringPtr`s into a buffer someone else owns and `loadIsolate`'s callback
+ *    "technically may be called any number of times" (`api/worker-loader.c++:90`).
+ *    A JS value has no such lifetime: the same frozen object is handed back on
+ *    every call, which is what `clone()` was reproducing. `ownContent` and
+ *    `ownContentIsRpcResponse` on `DynamicWorkerSource` are the other half of the
+ *    same kj bookkeeping and are absent for the same reason.
+ *
+ * **A `kj::OneOf` is tagged by its C++ type; a JS union needs the tag in the
+ * value.** Every variant here carries a `type` naming upstream's struct, so
+ * `content.is<Worker::Script::EsModule>()` becomes `content.type === "esModule"`.
+ * That is the same substitution `util/sqlite.ts` makes for statement kinds and
+ * the reason it is stated once, here.
+ *
+ * Spec: §1.11, decision 15 in docs/decisions.md.
+ */
+/** ← `WorkerSource::EsModule`. `ownBody` is a Rust transpiler artifact with no port. */
+export type EsModule = {
+    readonly type: "esModule";
+    readonly body: string;
+};
+/** ← `WorkerSource::CommonJsModule`. */
+export type CommonJsModule = {
+    readonly type: "commonJsModule";
+    readonly body: string;
+    /** Upstream's field. `WorkerLoader::extractSource` never fills it. */
+    readonly namedExports?: readonly string[];
+};
+/** ← `WorkerSource::TextModule`. "text blob, imports as a string". */
+export type TextModule = {
+    readonly type: "textModule";
+    readonly body: string;
+};
+/** ← `WorkerSource::DataModule`. "byte blob, imports as ArrayBuffer". */
+export type DataModule = {
+    readonly type: "dataModule";
+    readonly body: Uint8Array;
+};
+/** ← `WorkerSource::WasmModule`. "Compiled .wasm file content." */
+export type WasmModule = {
+    readonly type: "wasmModule";
+    readonly body: Uint8Array;
+};
+/**
+ * ← `WorkerSource::JsonModule`. "JSON-encoded content; will be parsed
+ * automatically when imported."
+ */
+export type JsonModule = {
+    readonly type: "jsonModule";
+    readonly body: string;
+};
+/** ← `WorkerSource::PythonModule`. */
+export type PythonModule = {
+    readonly type: "pythonModule";
+    readonly body: string;
+};
+/**
+ * ← `WorkerSource::ModuleContent`, minus the two arms no ported caller can
+ * produce: `PythonRequirement` (a system-provided package, named by a
+ * configuration this package does not compile) and `CapnpModule` (a type id into
+ * a schema bundle with no reader).
+ */
+export type ModuleContent = EsModule | CommonJsModule | TextModule | DataModule | WasmModule | JsonModule | PythonModule;
+/** ← `WorkerSource::Module`. */
+export type Module = {
+    readonly name: string;
+    readonly content: ModuleContent;
+    /** ← "Hack for tests: register this as an internal module. Not allowed in production." */
+    readonly treatAsInternalForTest?: boolean;
+};
+/** ← `WorkerSource::ModulesSource`. "source code for a worker using ES Modules syntax." */
+export type ModulesSource = {
+    readonly type: "modulesSource";
+    /** "Path to the main module, which can be looked up in the module registry." */
+    readonly mainModule: string;
+    /** "All the Worker's modules." */
+    readonly modules: readonly Module[];
+    readonly isPython: boolean;
+};
+/** ← `WorkerSource::variant`, whose `ScriptSource` arm is a boundary — see the header. */
+export type WorkerSourceVariant = ModulesSource;
+/** ← `WorkerSource`. */
+export type WorkerSource = {
+    readonly variant: WorkerSourceVariant;
+};

package/dist/src/io/worker.d.ts

@@ -0,0 +1,88 @@
+/**
+ * ← workerd `src/workerd/io/worker.h` — `Worker::Actor::FacetManager` only
+ * (`io/worker.h:901`).
+ *
+ * This file exists to settle a layering question the scaffolding got backwards.
+ * The facet surface `api/actor-state.ts` consumes was declared in
+ * `server/actor-container.ts`, which would give `api/` → `server/` a dependency
+ * upstream does not have: `api/actor-state.c++` includes from `api/`, `io/` and
+ * `jsg/` and from `server/` never, and the manager it reaches for is a nested
+ * class of `Worker::Actor` in `io/worker.h`. Per the README's rule for a
+ * legitimate upstream include crossing a wall, the reference widens to match
+ * upstream rather than the files being reshuffled to avoid it.
+ *
+ * `FacetManager` is not the same interface as `server/actor-container.ts`'s
+ * `FacetHost`, and conflating them is what produced the inverted dependency.
+ * `FacetHost` is the substrate PLACEMENT port — where a facet runs, the callable
+ * stub across that placement, and physical storage deletion — and it has no
+ * upstream twin, because workerd's facets are in-process. `FacetManager` is the
+ * package-owned layer above it that owns naming, ids, the limits, receipts and
+ * `clone()` orchestration, and it is the only facet thing `api/` may see.
+ * `server/` implements it on top of `FacetHost`.
+ *
+ * The rest of `worker.h` — `Worker`, `Worker::Isolate`, `Worker::Lock`,
+ * `Worker::Actor` itself — is isolate machinery with no port. The three
+ * `Worker::Actor` members `io/io-context.ts` reaches for are declared there, as
+ * that file's own comment explains; `assertCanSetAlarm()` joins them because
+ * `api/actor-state.c++` reaches for it through
+ * `IoContext::current().getActorOrThrow()`.
+ *
+ * Spec: §1.10, decision 14 in docs/decisions.md.
+ */
+import type { ActorClassChannel } from "./io-channels.js";
+/**
+ * ← `Worker::Actor::FacetManager::StartInfo`.
+ *
+ * `actorClass` is upstream's own type — a resolved
+ * `IoChannelFactory::ActorClassChannel`, which `io/io-channels.ts` ports and
+ * `DurableObjectClass.getChannel()` produces. An earlier revision typed it as
+ * `DurableObjectClass`, the `@cloudflare/workers-types` interface, which is
+ * declared `interface DurableObjectClass<_T> {}` and therefore accepts any
+ * object at all: it was `unknown` with a name, and it left `server/` with
+ * nothing to resolve a class against. Upstream resolves it one step earlier —
+ * `DurableObjectFacets::get` calls `actorClass.getChannel(ioCtx)` inside the
+ * reentry callback (`actor-state.c++:1044`) — so `api/actor-state.ts` now does
+ * the same and this field carries the resolved channel.
+ *
+ * `id` is upstream's `Worker::Actor::Id` as the string form of a
+ * `DurableObjectId`, which is all a `DurableObjectId` is once it leaves this
+ * package, since ids never cross the host boundary.
+ */
+export type FacetStartInfo = {
+    readonly actorClass: ActorClassChannel;
+    /** `ctx.id` for the child. Defaults to the parent's, as upstream's does. */
+    readonly id: string;
+};
+/**
+ * ← `Worker::Actor::FacetManager` (`io/worker.h:901-931`).
+ *
+ * Upstream's comment on the last three: "These methods are C++ equivalents of
+ * the JavaScript ctx.facets API."
+ *
+ * `cloneFacet` is the fourth, and it is not in the vendored C++ snapshot — see
+ * the note on `DurableObjectFacets.clone` in `api/actor-state.ts`.
+ */
+export interface FacetManager {
+    /** Returns the nesting depth of this facet. Root = 0, direct child of root = 1, etc. */
+    getDepth(): number;
+    getFacet<T extends Rpc.DurableObjectBranded | undefined = undefined>(name: string, getStartInfo: () => Promise<FacetStartInfo>): Fetcher<T>;
+    abortFacet(name: string, reason: unknown): void;
+    deleteFacet(name: string): void;
+    /** Aborts `dst`, deletes its storage, then copies the whole `src` subtree onto it. */
+    cloneFacet(src: string, dst: string): void;
+}
+/**
+ * The one type assertion the facet surface needs, in one named place so an
+ * implementation does not have to reinvent it.
+ *
+ * `Fetcher<T>` for an unresolved `T` is `Rpc.Provider<T, …> & { fetch, connect }`
+ * — a conditional type TypeScript defers until `T` is known, and `T` is the
+ * caller's claim about the shape of a class it named. No value can confirm that
+ * claim, so no value can be checked against it. Upstream is in exactly the same
+ * position and answers it the same way: `DurableObjectFacets::get` returns a
+ * plain `jsg::Ref<Fetcher>` and the type parameter exists only inside a
+ * `JSG_TS_OVERRIDE`. What IS checked is the half that carries behaviour —
+ * `fetch` and `connect` — because the argument is a `Fetcher` before it is
+ * widened.
+ */
+export declare function asFacetStub<T extends Rpc.DurableObjectBranded | undefined>(stub: Fetcher): Fetcher<T>;