@mcp-b/do-runtime 0.1.0

package/dist/src/server/actor-container.d.ts

@@ -0,0 +1,525 @@
+/**
+ * ← workerd `src/workerd/server/server.c++` — `ActorNamespace::ActorContainer`
+ * (`:2383-2968`), which is at once the supervisor's per-actor record, its
+ * `Worker::Actor::FacetManager`, and the code that builds the storage engine.
+ *
+ * Composes the gates, the context, the storage engine and the facet tree into
+ * one actor. Constructs the Durable Object class under workerd's boot
+ * semantics, and on break aborts facets, abandons scheduled writes, refuses
+ * re-entry, and surfaces `onBroken`.
+ *
+ * **The three line ranges this file was handed are all in the wrong class, and
+ * the right ones are above.** `server.c++:1199-1214`, `:1225-1237` and
+ * `:1293-1297` are all inside `Server::DiskDirectoryService` (`:1058`) — the
+ * directory-listing branch of a static-file handler, its entry-type switch, and
+ * a `sendError(501, "Not Implemented")`. None of them has anything to do with
+ * actors. The three things they were offered for are real, and are at
+ * `:2864-2877` (alarm hooks installed only `if (parent == kj::none)`, with
+ * `// TODO(someday): Support alarms in facets, somehow.`), `:2885-2897`
+ * (`afterReset`, where `deleteAll()`'s cascade to descendant facet storage
+ * lives) and `:2603-2620` / `:2953-2956` (`getFacetContainer` and
+ * `actorClass->newActor`, the two halves of facet actor construction). Every
+ * citation in this file was checked line by line against
+ * `e8f1e125bd48f048a3e82c48d37e5e3902fffbd6`, which is the tree Section 6a's
+ * citations were taken from and agree with.
+ *
+ * **Ordering, because it is the part that cannot be read off upstream.**
+ * Upstream builds the actor lazily inside `getActor()`, so `ctx.storage` does
+ * not exist until the first request arrives and nothing can observe the gap.
+ * Here `ActorContainer.state` is a plain property that promises a
+ * `DurableObjectState` answering `.storage`, and the database behind it opens
+ * asynchronously (`SqlDatabaseProvider.open`, Section 3's seam). Something has to
+ * give, and the honest one is the factory: `createActorContainer` returns a
+ * promise, and everything it returns is fully built. The alternative — a `state`
+ * property that throws until `start()` — is a worse lie, because it makes the
+ * one declared field of the public interface conditional on a call the type
+ * system cannot see.
+ *
+ * Spec: §1.6, §1.10, decisions 6 and 14 in
+ * docs/decisions.md.
+ */
+import { DurableObjectState } from "../api/actor-state.js";
+import type { FetchPort } from "../api/global-scope.js";
+import { ActorGlobalScope } from "../api/global-scope.js";
+import type { AcceptedWebSocket, RawWebSocket } from "../api/web-socket.js";
+import type { IsolateChannelFactory, WorkerLoaderOptions } from "../api/worker-loader.js";
+import { WorkerLoader } from "../api/worker-loader.js";
+import type { AlarmOutlet } from "../io/actor-sqlite.js";
+import type { AlarmResult } from "./alarm-scheduler.js";
+import type { Timer } from "../io/io-context.js";
+import type { SqlDatabase, SqlDatabaseProvider } from "../util/sqlite.js";
+import type { IndexFile } from "./facet-tree-index.js";
+import { FacetReferenceEpochs } from "./facet-deletion.js";
+export type FacetId = number;
+export type FacetStartRequest = {
+    id: FacetId;
+    /** The `facets.get` name, `class\0name` form preserved. */
+    name: string;
+    /** Resolved against `ctx.exports` by `api/actor-state.ts`. */
+    className: string;
+    /** This facet's depth. The container enforces <= 4 including the root. */
+    depth: number;
+    /**
+     * The `ctx.id` the child was told to take, present only when the startup
+     * options supplied one. Absent means the child inherits the parent's, which
+     * is upstream's `ioCtx.getActorOrThrow().cloneId()` (`actor-state.c++:1026`).
+     *
+     * The scaffolding called this "the DurableObjectId name". It is not
+     * necessarily a name: `FacetStartupOptions.id` is `DurableObjectId | string`
+     * (`actor-state.h:453`), so this carries a 64-hex id string whenever the app
+     * passed a `DurableObjectId`, and whatever the app chose whenever it passed a
+     * string. The host decides what to do with it, exactly as upstream's
+     * `Worker::Actor::Id` leaves that to the supervisor.
+     */
+    routedId?: string;
+};
+export interface FacetHandle {
+    /**
+     * The placement's outcome, resolving to what `facets.get` will call —
+     * Fetcher-shaped per §1.10: no id, no name.
+     *
+     * `start` is synchronous because `facets.get` is, but placing an actor is not: a database
+     * has to open and a constructor has to run. Upstream has exactly this shape and
+     * does not have to say so — `getFacetContainer` hands `ActorChannelImpl` a
+     * `kj::Promise<ClassAndId>` (`server.c++:2603-2620`) and the channel is
+     * returned before it resolves, so a failure to construct reaches the caller at
+     * the first call on the stub. Measured on workerd 1.20260722.1: a facet whose
+     * constructor throws returns a stub from `facets.get()`, rejects the first call
+     * with the constructor's own message, and leaves the parent untouched.
+     *
+     * Keeping the placement promise here makes construction failures observable at
+     * the first call and leaves `asFacetTransport` as the sole deferral layer.
+     */
+    stub: Promise<object>;
+    /**
+     * Rejects when a RUNNING facet breaks — the signal upstream gets from
+     * `actor.onBroken()` and monitors in `monitorOnBroken`
+     * (`server.c++:2767-2800`).
+     *
+     * **A break travels DOWN and never up, so nothing here reaches the parent.**
+     * `ActorContainer::abort` (`:2565-2589`) and `monitorOnBroken` each loop
+     * `for (auto& facet: facets)` and abort the container's OWN children; a broken
+     * child takes itself and its subtree, and nothing above it notices.
+     * `conformance/suite/facets.spec.ts` guards this against workerd: the parent and
+     * its other facets remain live.
+     *
+     * `FacetManagerImpl` consumes this signal for `monitorOnBroken`'s two local
+     * effects: tell the host to tear down the broken placement (which aborts its
+     * descendants), and erase it from the PARENT's facet map (`:2777-2780`,
+     * `:2794-2798`). That frees the name for a fresh placement without changing
+     * the parent or its siblings.
+     *
+     * **A placement that never completed does not belong here** — it is a start
+     * that failed, not a break, and it travels through `stub`. Measured on
+     * workerd: a facet whose construction fails does not break its parent, and the
+     * next `facets.get` runs the startup callback again.
+     */
+    broken: Promise<never>;
+}
+/**
+ * The facet port. Substrate is only placement, the callable stub across that
+ * placement, and physical storage deletion for children a parent cannot open.
+ *
+ * NOT substrate, and therefore not in this interface: naming, ids, the
+ * depth/name/count limits, deletion receipts and epochs, and `clone()`
+ * orchestration. Those are package-owned. In particular there is no
+ * addressing-strategy port: once
+ * the package speaks facet ids, the app-address mapping is the browser
+ * adapter's private business and needs no interface at all.
+ *
+ * This is NOT the interface `api/actor-state.ts` consumes. That one is
+ * `io/worker.ts`'s `FacetManager`, upstream's own `Worker::Actor::FacetManager`,
+ * which this file implements on top of this port — see that file's header for
+ * why the two were conflated and why the fix was to widen rather than reshuffle.
+ * The `clone()` orchestration named above is `cloneFacet`'s body, and the
+ * limits named above are enforced by `DurableObjectFacets` where upstream
+ * enforces them.
+ *
+ * One host serves a whole actor tree, as upstream's `ActorNamespace` does: every
+ * `FacetId` it is handed is an id in the root's index, so a facet's own host
+ * must be able to place and remove any of its descendants.
+ */
+export interface FacetHost {
+    /**
+     * Synchronous, like `facets.get` itself — but the placement it begins is not,
+     * and `FacetHandle.stub` is where that is declared. A host reports a placement
+     * it could not finish by rejecting that promise, and reports nothing about it
+     * on `broken`: see `FacetHandle`.
+     *
+     * A synchronous throw is still legal and still means the same thing — the
+     * facet cannot be started — and `getFacet` turns it into the same rejected
+     * stub. What is no longer possible is a host that fails asynchronously and has
+     * nowhere to say so.
+     */
+    start(request: FacetStartRequest): FacetHandle;
+    /**
+     * Kills the instance; storage survives (measured on workerd).
+     *
+     * **Never called while a placement for `id` is in flight**, and never before
+     * that placement's `stub` has settled. The container orders the two against
+     * each other, so a host needs no queue of its own and is never handed an abort
+     * for a facet it is still placing — which it could only no-op, its placement
+     * map having no entry for the id yet.
+     *
+     * It may still be called for an id that never ran: a placement that failed, or
+     * one refused before `start` was reached. Upstream's is too — `abortFacet`
+     * finds the container whether or not its `kj::Promise<ClassAndId>` ever
+     * resolved (`server.c++:2635-2640`) — so a host that has nothing to kill
+     * should return, not throw.
+     */
+    abort(id: FacetId, reason?: string): void;
+    /**
+     * Physical removal, descendants included. `subtree` is the descendants alone,
+     * deepest first — upstream removes children before the parent
+     * (`server.c++:2754-2759`) — and `id` is the facet itself.
+     */
+    deleteStorage(id: FacetId, subtree: readonly FacetId[]): Promise<void>;
+    /**
+     * Physical copy of one facet's storage onto another, for `cloneFacet`. The
+     * recursive walk of the source subtree is this file's; copying one database
+     * is the substrate's, the same split `deleteStorage` already makes.
+     */
+    copyStorage(src: FacetId, dst: FacetId): Promise<void>;
+}
+/**
+ * The `FacetHost` for a host that places no facets — the shape of every first
+ * integration, provided so hosts stop re-typing it. `start` refuses by name.
+ * `abort` returns, per its contract above: a host with nothing to kill returns.
+ * The storage operations refuse, because a call to either proves a facet once
+ * existed — which this host could not have placed.
+ */
+export declare const noFacets: FacetHost;
+/**
+ * The four ports. Each one is a seam workerd itself takes as a constructor
+ * input; a port that would exist only because our code is currently shaped
+ * badly is an invented seam and was rejected. Rejected, for the record:
+ * a transport port (one implementation per substrate, forever), a logger port
+ * (fail closed — errors throw, breakage surfaces on `onBroken`), a value-codec
+ * port (giving lanes different codecs would make the Node lane lie about the
+ * browser), and an addressing-strategy port (unnecessary once the package
+ * speaks facet ids).
+ *
+ * A fifth, `isolates?: IsolateHost`, was here from the scaffolding and Section 7b
+ * removed it. A Worker Loader is a **binding**, not a port: upstream builds it
+ * from `Global::WorkerLoader{channel}` alongside every other binding
+ * (`server/workerd-api.c++:748`) and it reaches an application through `env`,
+ * exactly as `DurableObjectNamespace` and `ctx.exports` already do here. A host
+ * constructs `WorkerLoader` over its own `IsolateChannelFactory` and puts it in
+ * `env`; the container never sees one. See `api/worker-loader.ts`'s header.
+ */
+export type ActorPorts = {
+    sql: SqlDatabaseProvider;
+    /**
+     * Root containers only — facets have no alarm slot (§1.10).
+     *
+     * `AlarmScheduler.hooks(actorId)` is the implementation to put here: upstream
+     * builds one `AlarmScheduler` per namespace and gives each actor a
+     * three-line `ActorSqliteHooks` adapter over it (`server.c++:2325-2350`,
+     * `:3199-3219`), which is the same composition.
+     */
+    alarms: AlarmOutlet;
+    facets: FacetHost;
+    timer: Timer;
+    /**
+     * ← the global outbound `Fetcher` a Worker's `fetch` resolves
+     * (`api/global-scope.c++:1160`), which `container.globals.fetch` gates.
+     *
+     * Optional, and absence is upstream's `globalOutbound: null` posture rather
+     * than a missing port: a Worker configured that way has no ambient `fetch` at
+     * all, which is how Code Mode forces every I/O through connectors (§1.11).
+     * `fetch` then refuses by name instead of reaching a `fetch` this package does
+     * not own — an ungated one that works is the failure this layer exists to
+     * prevent.
+     */
+    fetch?: FetchPort;
+};
+/**
+ * The whole-tree facet state, which belongs to the root container and is shared
+ * by every container in one actor tree.
+ *
+ * Upstream keeps the same thing in the same place — "FacetTreeIndex for this
+ * actor. Only initialized on the root" (`server.c++:2680-2681`), reached from a
+ * facet by `root.ensureFacetTreeIndex()` (`:2697`) — and can do so with a plain
+ * reference because every facet of an actor is an object in one process. None of
+ * these methods can cross a worker boundary: `facets.get()` is synchronous all
+ * the way down, so `getId` has to answer without yielding. A facet in another
+ * worker cannot be handed this object and therefore cannot have facets of its
+ * own. Every host here
+ * now places in the parent's realm and passes the root's object straight through.
+ *
+ * It is an interface rather than a plain reference anyway, because a facet
+ * container is constructed on its own and the root's index is the one piece of
+ * state it cannot build for itself: ids are sequential across the whole tree. A
+ * host that does not supply one gets a facet that cannot have facets of its own
+ * and says so, rather than a per-parent counter that would collide the storage.
+ */
+export interface FacetTree {
+    /** ← `FacetTreeIndex::getId`. Assigns on first sight, stable thereafter. */
+    getId(parent: FacetId, name: string): FacetId;
+    /** ← `FacetTreeIndex::forEachChild`, collected. Ordered by the child's UTF-8 name. */
+    children(parent: FacetId): readonly {
+        readonly id: FacetId;
+        readonly name: string;
+    }[];
+    /** ← `deleteDescendantStorage`'s recursion, as a list: descendants only, deepest first. */
+    descendants(id: FacetId): FacetId[];
+    /**
+     * Records the intent durably now, then removes `id` and its descendants after
+     * the current parent and descendant operations represented by `waitBeforeDelete`.
+     */
+    deleteSubtree(id: FacetId, waitBeforeDelete: Promise<unknown>): Promise<void>;
+    /** Copies the whole `src` subtree onto `dst`, minting `dst`'s children as it goes. */
+    copySubtree(src: FacetId, dst: FacetId): Promise<void>;
+    /** Runs one placement or abort after every earlier operation on the same stable facet id. */
+    runOperation(id: FacetId, operation: () => Promise<void>): void;
+    /** Snapshots the current operation tail for `id` and every indexed descendant. */
+    subtreeOperationBarrier(id: FacetId): Promise<void>;
+    /**
+     * Resolves once no queued deletion still covers `id`, which is what makes a
+     * facet re-created under a name that is still being deleted safe to start.
+     */
+    settled(id: FacetId): Promise<void>;
+    /** Every capability captured before an ancestor abort or delete goes stale here. */
+    readonly epochs: FacetReferenceEpochs;
+    /** ← boot. Carries out every deletion a previous session recorded and did not finish. */
+    recoverDeletions(): Promise<void>;
+}
+/**
+ * ← `IoContext::awaitIo`, as the one primitive a host needs in order to build a
+ * platform async primitive of its own.
+ */
+export type ActorContainerOptions = {
+    /** The DurableObjectId name. */
+    id: string;
+    /**
+     * The namespace's unique key, upstream's `uniqueKey` configuration field
+     * (`server.c++:2919`, read from `config::Worker::DurableObjectNamespace::Durable`).
+     * `ActorIdFactoryImpl` derives its factory key as `SHA256(uniqueKey)` and an
+     * id as 16 bytes of base plus 16 bytes of `HMAC-SHA256(key, base)`.
+     *
+     * **The host must keep this stable forever.** `ctx.id` is
+     * `idFromName(options.id)` under this key, and the id names the actor's
+     * storage, so a key that changes across a restart changes every id and every
+     * actor loses its data. There is no default and it is not optional, because a
+     * default is exactly the shape that would let a host acquire this obligation
+     * without noticing it. This package cannot check the property for itself —
+     * nothing it can observe distinguishes "a new key" from "a new actor" — so
+     * this comment is the whole of the enforcement.
+     */
+    uniqueKey: string;
+    /** The `ctx.exports` class registry. Keys are the consumer's concern. */
+    exports: Record<string, unknown>;
+    env: unknown;
+    ports: ActorPorts;
+    /** Present when this container hosts a facet rather than a root. */
+    facet?: {
+        /** Root is 0, a direct child of the root is 1. `getDepth()` answers with it. */
+        depth: number;
+        /** This facet's own id, the one its parent allocated from the tree index. */
+        id: FacetId;
+        /** The root-owned tree this facet and every descendant share. */
+        tree: FacetTree;
+    };
+};
+/** The local entry proxy: data properties stay local; every method becomes one async event. */
+export type ActorEntry<T extends object> = {
+    [K in keyof T]: T[K] extends (...args: infer Args) => infer Result ? (...args: Args) => Promise<Awaited<Result>> : T[K];
+};
+export interface ActorContainer {
+    /** Implements the workers-types interface. No `as unknown as` cast (§2.4). */
+    readonly state: DurableObjectState;
+    /**
+     * The actor tree this container belongs to, which a root builds for itself and
+     * a facet is handed.
+     *
+     * It is on the interface because the host is the only thing that can carry it
+     * from a parent to a child: `FacetHost.start` builds the nested container, and
+     * a facet that may have facets of its own needs the root's index rather than
+     * one of its own (see `FacetTree`). Upstream needs no equivalent because a
+     * facet reaches `root.ensureFacetTreeIndex()` through a plain reference
+     * (`server.c++:2697`), and every facet of an actor is an object in one process.
+     *
+     */
+    readonly facetTree: FacetTree;
+    /**
+     * Whether this container owns the synchronous actor slice on the JS stack.
+     * This is the narrow identity check a host loopback needs to call the raw
+     * instance instead of queueing behind the lock it already holds. It resolves
+     * no container and carries no state into continuations.
+     */
+    isCurrentSlice(): boolean;
+    /**
+     * Construct the instance under workerd's boot semantics: the input gate is
+     * held for the constructor's synchronous slice, and boot-time
+     * deletion-receipt replay precedes it.
+     */
+    start<T extends object>(construct: (ctx: DurableObjectState, env: unknown) => T): Promise<T>;
+    /**
+     * THE door for RPC targets. A proxy whose every method invocation is one
+     * gated event. This single wrapper is what replaces the serialised tail,
+     * all three dispatch tables, and the 33 hand-written exemptions.
+     *
+     * EVERY call queues, including one made while this actor is holding its own
+     * lock across an await. That is §1.2's whole content and the suite pins it: a
+     * second event posted while a storage await holds the gate must not interleave,
+     * and a door that reused the held lock could not tell that event apart from a
+     * call the actor made to itself. Telling them apart needs to know WHO is
+     * calling, which is a host's question rather than a container's — see the
+     * extension host's `loopbackStub`, where an actor reaching its own
+     * `DurableObjectNamespace` binding skips this door entirely because the lock it
+     * would take is the one it is already holding.
+     */
+    entry<T extends object>(target: T): ActorEntry<T>;
+    /**
+     * The door for events that are not method calls — one WebSocket frame, one
+     * host-originated callback. Upstream: `IoContext::run`.
+     */
+    run<T>(event: () => T | PromiseLike<T>): Promise<T>;
+    /**
+     * ← `IoContext::awaitIo`. The form a HOST-PROVIDED async primitive must take,
+     * and the only gate primitive this package makes public.
+     *
+     * Every platform async thing an application can await — `scheduler.wait`, a
+     * `fetch`, a WebSocket round trip — is an io-context primitive upstream, which
+     * is why "resuming from an await re-enters the isolate with a fresh input
+     * lock" needs saying nowhere in workerd: there is no other kind of await.
+     * There is here. A raw `setTimeout` resolves a promise the runtime does not
+     * own, the application's continuation resumes with an empty invocation stack,
+     * and its next `ctx.storage` call throws `no input lock available in this
+     * context` — the README's divergence 147. Wrapping the promise in this makes
+     * the continuation resume inside a gated slice, which is what upstream's does.
+     *
+     * It releases the input gate for the duration, per §1.3, so the actor stays
+     * re-entrant while it waits. The holding form,
+     * `IoContext::awaitIoWithInputLock`, is deliberately NOT public: that one is
+     * the transaction boundary of §1.7.1, it belongs to the four async storage
+     * calls, and a host holding it by hand is the serialised tail growing back.
+     */
+    awaitIo<T>(promise: Promise<T>): Promise<T>;
+    /**
+     * ← `ServiceWorkerGlobalScope`, the async-primitive half: this actor's
+     * `setTimeout`, `clearTimeout`, `setInterval`, `clearInterval`, `fetch` and
+     * `scheduler` (`api/global-scope.ts`).
+     *
+     * **This is what "own the primitives in the worker global" means, and the
+     * ownership is the point.** `awaitIo` above is the primitive a host needs to
+     * build one of these; this is the set already built, so a host installs rather
+     * than reimplements the surface.
+     *
+     * **One scope per actor, installed lexically, and never resolved from an
+     * ambient.** Upstream's globals read `IoContext::current()` because acquisition
+     * is structural there; this one holds its context. A host puts it where its
+     * actor's code reads it — `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 (§1.11:
+     * a dynamic Worker has its own global scope bound to its own context). What
+     * happens when a facet reaches past its binding to a parent's scope is
+     * `ActorGlobalScope`'s `requireOwnSlice`.
+     */
+    readonly globals: ActorGlobalScope;
+    /**
+     * ← `WebSocket::accept()` / `state.acceptWebSocket()`
+     * (`api/web-socket.c++:133`, `:426`), whose gating is `api/web-socket.ts`.
+     *
+     * Separate from `globals` because accepting is an act rather than a binding:
+     * the critical section is captured at THIS call, so a socket accepted inside
+     * `blockConcurrencyWhile` delivers its frames inside that section (§1.8).
+     */
+    acceptWebSocket(socket: RawWebSocket): AcceptedWebSocket;
+    /**
+     * ← `WorkerInterface::runAlarm(scheduledTime, retryCount)`
+     * (`io/worker-interface.h:107`), which is what `AlarmScheduler` calls and what
+     * `ServiceWorkerGlobalScope::runAlarm` answers. Strictly serialised (§1.8).
+     *
+     * It reports rather than throws, because the two bits the scheduler's ladder
+     * turns on — retry, and whether the retry counts against the limit — are not
+     * derivable from "the promise rejected".
+     *
+     * `retryCount` reaches the handler as `AlarmInvocationInfo`. It is the
+     * scheduler's `countedRetry` for this alarm, so the container takes it as an
+     * argument exactly as upstream's `runAlarm` does.
+     */
+    deliverAlarm(scheduledTime: number, retryCount: number): Promise<AlarmResult>;
+    /**
+     * ← `WorkerInterface::abandonAlarm` (`io/worker-interface.h:114`), forwarded to
+     * `ActorSqlite::abandonAlarm` (`io/actor-sqlite.c++:1039-1060`).
+     *
+     * Called when the scheduler has given up retrying, so the actor clears its own
+     * alarm state and `getAlarm()` stops reporting a time that will never fire.
+     * Answers the actor's stored alarm time when it differs from `scheduledTime` —
+     * meaning the application set a different one — and null when the alarm was
+     * cleared or there was none.
+     */
+    abandonAlarm(scheduledTime: number): Promise<number | null>;
+    /**
+     * Output-gate wait for outbound sends that do not ride an `entry()` reply.
+     * A broadcast path calls this before each frame (decision 5).
+     */
+    waitOutputLocks(): Promise<void>;
+    /** For the host's idle check — today's `drainWaitUntil`. */
+    drainWaitUntil(): Promise<void>;
+    /**
+     * ← `WorkerdApi::compileGlobals`'s `Global::WorkerLoader` arm
+     * (`server/workerd-api.c++:748-752`), which is the step that turns a configured
+     * loader channel into the JS binding an application finds in `env`.
+     *
+     * **The one binding the runtime has to construct, and the reason is the
+     * context.** Upstream's `WorkerLoader` holds a channel number and a
+     * validation mode and nothing else, because `get()` and `load()` read
+     * `IoContext::current()` when they are called. This package deliberately has no
+     * ambient of any kind, so the context is a constructor input — and it must be
+     * *this* container's, since `makeReentryCallback` inherits the critical section
+     * a `blockConcurrencyWhile` is holding (decision 13). `IoContext` is not
+     * exported, on purpose (see `src/index.ts`'s header), so this method is how a
+     * host gets a loader bound to the right one.
+     *
+     * The host still owns the name: assign the result onto the `env` object it
+     * passed in, which is what upstream's binding compilation does one layer down.
+     * A container whose host never calls this simply has no loader binding, exactly
+     * as a Worker with no `workerLoader` in its config does.
+     */
+    workerLoader(channel: IsolateChannelFactory, options: WorkerLoaderOptions): WorkerLoader;
+    /**
+     * Rejects when either gate breaks, or when a facet the parent did not abort
+     * breaks (decisions 6 and 14). The host consumes this: terminate the worker,
+     * respawn on the next event.
+     */
+    readonly onBroken: Promise<never>;
+    /** The programmatic `ctx.abort()` path. */
+    abort(reason?: unknown): void;
+}
+/**
+ * A facet has no alarm slot, and this is where that becomes visible.
+ *
+ * `server.c++:2864-2877` installs alarm hooks only `if (parent == kj::none)` and
+ * gives a facet `ActorSqlite::Hooks::getDefaultHooks()`, whose `scheduleRun`
+ * throws — so on workerd a `setAlarm()` inside a facet appears to succeed and
+ * then breaks the whole actor asynchronously, which is open bug
+ * https://github.com/cloudflare/workerd/issues/6810. This runtime refuses at the
+ * call instead, as recorded in §2.7. A deliberate semantic
+ * divergence: the observable behaviour is a synchronous throw naming the facet
+ * where workerd's is a destroyed actor three turns later.
+ */
+export declare const FACET_ALARM_UNIMPLEMENTED_MESSAGE: string;
+/**
+ * ← the `kj::File` `FacetTreeIndex` is constructed over, backed by one BLOB.
+ *
+ * `datasync()` is a no-op and that is a property of the substrate rather than a
+ * shortcut: nothing else ever opens a transaction on this connection, so every
+ * statement below is its own implicit SQLite transaction and is durable by the
+ * time `exec` returns. The read-modify-write is O(file) per append, which is
+ * what upstream's own bound makes affordable — the format is four bytes plus a
+ * name per facet and there can be at most 65,535 facets over an actor's whole
+ * lifetime (`facet-tree-index.h:19-22`).
+ */
+export declare function newDatabaseIndexFile(db: SqlDatabase): IndexFile;
+/**
+ * Builds one actor: the two gates, the `IoContext` over them, the storage engine
+ * over the actor's database, the facet tree, the id factory, and the `api/`
+ * classes on top.
+ *
+ * Asynchronous because `SqlDatabaseProvider.open` is — see this file's header for
+ * why that surfaces here rather than being hidden behind a lazily-opening
+ * `state`.
+ */
+export declare function createActorContainer(options: ActorContainerOptions): Promise<ActorContainer>;

package/dist/src/server/actor-id-impl.d.ts

@@ -0,0 +1,118 @@
+/**
+ * ← workerd `src/workerd/server/actor-id-impl.{h,c++}`
+ *
+ * The implementation behind `io/actor-id.ts`'s two interfaces, which that file's
+ * header names as Section 6's problem: "upstream's is a keyed SHA-256
+ * construction … a faithful port of it needs a synchronous digest, which the
+ * browser does not expose."
+ *
+ * **What upstream computes.** The factory's key is `SHA256(uniqueKey)`, where
+ * `uniqueKey` is the namespace's configured string (`workerd-api.c++:675`).
+ * An id is 32 bytes in two halves: a 16-byte base and the first 16 bytes of
+ * `HMAC-SHA256(key, base)` — `computeMac` (`actor-id-impl.c++:115-125`), which
+ * writes a full 32-byte HMAC into a 48-byte working buffer of which only the
+ * first 32 bytes ever become the id. `idFromName` derives the base from
+ * `HMAC-SHA256(key, name)` (`:71-83`); `newUniqueId` draws it from the entropy
+ * source (`:48-69`); `idFromString` takes it from the supplied hex and refuses
+ * the string unless the MAC it recomputes matches the half that came with it
+ * (`:85-100`). `toString` is `kj::encodeHex` of the 32 bytes.
+ *
+ * **The digest is written out; the bytes are unchanged.** Every method on
+ * `ActorIdFactory` is synchronous (`io/actor-id.h:66-71`) and no browser API
+ * offers a synchronous digest, so `server/sha256.ts` supplies SHA-256 and
+ * HMAC-SHA-256 in place of BoringSSL. It computes what FIPS 180-4 and RFC 2104
+ * specify, so this is decision 16's **substrate** divergence and not a semantic
+ * one: `idFromName` here produces the identical 64 hex digits workerd produces
+ * from the same unique key, which keeps workerd usable as an oracle for ids.
+ *
+ * That equality is why the construction is ported whole rather than narrowed.
+ * The reduced threat model would have tolerated much less — ids never cross the
+ * host boundary, there is no colo, no jurisdiction routing and no second worker
+ * re-deriving an id from the same key, so nothing here forges an id — but only
+ * two of the contract's properties are cheap to satisfy any other way. The other
+ * two are not: `idFromName` must be **stable forever**, because the id names the
+ * actor's storage and a name that hashed differently after a restart loses its
+ * data; and `idFromString` must **refuse a string this namespace did not mint**,
+ * which is a decision only the keyed MAC half can make. A narrower construction
+ * would have satisfied both and cost the oracle, turning every future question
+ * about an id into original research on a bespoke artifact — the failure the
+ * "Porting philosophy" section describes.
+ *
+ * **`isPredictableModeForTest()` is absent** (`actor-id-impl.c++:59-62`). It is a
+ * `util/thread-scopes.h` process-global test hack with no port here, it makes
+ * `newUniqueId` return a counter, and `actor-id-impl-test.c++` does not use it.
+ * Its body is also wrong upstream: `kj::arrayPtr(id).slice(counter)` slices by
+ * the counter's *value*, which is a no-op for every counter it can legitimately
+ * reach and out of bounds once the counter passes the buffer's 48 bytes.
+ *
+ * Spec: §1.10 in docs/decisions.md.
+ */
+import type { ActorId, ActorIdFactory } from "../io/actor-id.js";
+/**
+ * ← `JSG_REQUIRE(jurisdiction == kj::none, Error, …)` (`actor-id-impl.c++:50-51`,
+ * `:108`).
+ *
+ * Verbatim, "in workerd" and all: the conformance suite runs one assertion
+ * against both runtimes, so a reworded message would be a difference where there
+ * is none.
+ */
+export declare const JURISDICTION_UNIMPLEMENTED_MESSAGE = "Jurisdiction restrictions are not implemented in workerd.";
+/** ← the first `JSG_REQUIRE` in `idFromString` (`actor-id-impl.c++:87-89`). */
+export declare const INVALID_ACTOR_ID_MESSAGE = "Invalid Durable Object ID: must be 64 hex digits";
+/** ← the second `JSG_REQUIRE` in `idFromString` (`actor-id-impl.c++:96-97`). */
+export declare const WRONG_NAMESPACE_ACTOR_ID_MESSAGE = "Durable Object ID is not valid for this namespace.";
+/**
+ * Upstream `kj::downcast`s the argument of `equals` (`actor-id-impl.c++:33`),
+ * which asserts in a debug build and is undefined in a release one. There is one
+ * `ActorId` implementation here, so a correct caller cannot reach this; it fails
+ * closed rather than comparing something meaningless.
+ */
+export declare const FOREIGN_ACTOR_ID_MESSAGE = "This actor id was not created by this runtime, so it cannot be compared with one that was.";
+/** ← `ActorIdFactoryImpl::ActorIdImpl` (`actor-id-impl.h:13-30`). */
+export declare class ActorIdImpl implements ActorId {
+    #private;
+    /**
+     * ← the constructor (`actor-id-impl.c++:14-18`). Its parameter is declared
+     * `const kj::byte idParam[SHA256_DIGEST_LENGTH]` and its body `memcpy`s
+     * exactly `sizeof(id)` bytes, so a caller may hand over the longer working
+     * buffer and only its first 32 bytes become the id. The copy is upstream's
+     * too — a later write to the caller's buffer is not seen here.
+     */
+    constructor(id: Uint8Array, name: string | undefined);
+    /** ← `toString()` — `kj::encodeHex`, which is lowercase (`actor-id-impl.c++:20-22`). */
+    toString(): string;
+    /** ← `getName()` (`actor-id-impl.c++:24-26`). */
+    getName(): string | undefined;
+    /** ← `getJurisdiction()`, which is unconditionally none (`actor-id-impl.c++:28-30`). */
+    getJurisdiction(): string | undefined;
+    /**
+     * ← `equals()` (`actor-id-impl.c++:32-34`). The id bytes only — the name is
+     * deliberately not part of identity, which is what upstream's own table
+     * asserts by giving two equal ids different names.
+     */
+    equals(other: ActorId): boolean;
+    /** ← `clearName()` (`actor-id-impl.h:23-25`). Not JS-visible; `server/` calls it. */
+    clearName(): void;
+}
+/** ← `ActorIdFactoryImpl` (`actor-id-impl.h:8-46`). */
+export declare class ActorIdFactoryImpl implements ActorIdFactory {
+    #private;
+    /**
+     * ← both constructors (`actor-id-impl.c++:40-46`). C++ overloads on the
+     * parameter type; one constructor branching on it is the same two behaviours.
+     * The string form is the namespace's configured `uniqueKey`
+     * (`workerd-api.c++:675`, `:680`); the byte form exists for
+     * `cloneWithJurisdiction`, which passes the already-derived key.
+     */
+    constructor(uniqueKey: string | Uint8Array);
+    /** ← `newUniqueId()` (`actor-id-impl.c++:48-69`). */
+    newUniqueId(jurisdiction: string | undefined): ActorId;
+    /** ← `idFromName()` (`actor-id-impl.c++:71-83`). */
+    idFromName(name: string): ActorId;
+    /** ← `idFromString()` (`actor-id-impl.c++:85-100`). */
+    idFromString(str: string): ActorId;
+    /** ← `cloneWithJurisdiction()` (`actor-id-impl.c++:102-109`). */
+    cloneWithJurisdiction(maybeJurisdiction: string | undefined): ActorIdFactory;
+    /** ← `matchesJurisdiction()`, which is unconditionally true (`actor-id-impl.c++:111-113`). */
+    matchesJurisdiction(_id: ActorId): boolean;
+}