@mcp-b/do-runtime 0.1.0

package/dist/src/api/actor-state.d.ts

@@ -0,0 +1,396 @@
+/**
+ * ← workerd `src/workerd/api/actor-state.{h,c++}`
+ *
+ * The JS-facing storage objects: `DurableObjectStorageOperations` and its two
+ * subclasses, `DurableObjectFacets`, and `DurableObjectState`. Everything below
+ * this file is reached through one of them.
+ *
+ * **`DurableObjectStorage` satisfies workers-types with no cast (§2.4).** That
+ * was checked rather than asserted, and two shapes here exist only because it
+ * has to: `sql.Cursor` and `sql.Statement` must be constructible with no
+ * arguments (see `sql.ts`), and `storage.kv` is required, which is why
+ * `api/sync-kv.ts` exists at all. The narrowings that remain are all one thing —
+ * `get<T>` returns the caller's claim about the shape of a value SQLite handed
+ * back as bytes, which no check can confirm and which upstream states the same
+ * way, as a `jsg::JsRef<jsg::JsValue>` behind a `JSG_TS_OVERRIDE`'d
+ * `Promise<T>`. There is no `as unknown as` anywhere in this layer.
+ *
+ * **Every throw is synchronous, including from the promise-returning methods.**
+ * That is upstream's: a `JSG_REQUIRE` inside a method returning `jsg::Promise`
+ * throws into the isolate before the promise exists, so `put(k, undefined)`
+ * throws rather than rejecting. The same goes for a value that will not decode,
+ * because §1.4 makes the SQLite path take `transformCacheResult`'s value arm and
+ * run the decoder synchronously.
+ *
+ * **What the input gate does and does not do here.** Every entry point calls
+ * `requireInputLock` — see its comment in `io/io-context.ts`, which is the one
+ * place this package decides what an empty invocation stack means. Nothing else
+ * takes a lock: a read returns a value, a write returns a resolved promise, and
+ * `atCheckpointEnd` is what keeps the whole chain inside one transaction
+ * (§1.7.1). The two exceptions are upstream's own — `sync()` and the bookmark
+ * pair release the gate via `awaitIo`, and `transaction()` takes a critical
+ * section.
+ *
+ * **Decision 2's branch has one reachable site**, and it is not where upstream's
+ * is. `transformCacheResult` branches on `allowConcurrency` because upstream's
+ * `ActorCacheOps` returns `kj::OneOf<T, kj::Promise<T>>`; §1.4 measures that the
+ * SQLite arm is always the immediate one, so Section 4 collapsed the `OneOf` and
+ * the branch has nothing to select between. `transformMaybeBackpressure` keeps
+ * it, because `DeleteAllResults.backpressure` is still a promise in
+ * `io/actor-cache.ts`. Both helpers are kept under upstream's names so the
+ * question "where did `allowConcurrency` go" is answered by reading them.
+ *
+ * Not ported, because the substrate has no equivalent: Hibernatable WebSockets,
+ * which is the whole reason `DurableObjectState`'s eight WebSocket methods are
+ * named throwing stubs; V8's private wire bytes, replaced by a browser-safe
+ * structured-clone encoding with the same public value semantics; the billing
+ * counters
+ * (`billingUnits`, `ActorObserver`, `updateStorageWriteUnit`) and the trace
+ * spans, both already absent throughout; `enableSql`, a workerd namespace option
+ * that exists to simulate a non-SQLite Durable Object; and `ReplicaActorOutgoingFactory`,
+ * whose replication half is a named boundary in `io/actor-cache.ts`.
+ *
+ * Spec: §1.4, §1.5, §1.10, §2.4, §2.5, decisions 2, 4 and 14 in
+ * docs/decisions.md.
+ */
+import type { ActorCacheInterface, ActorCacheOps, ActorCacheTransaction } from "../io/actor-cache.js";
+import type { IoContext } from "../io/io-context.js";
+import type { FacetManager } from "../io/worker.js";
+import type { SqliteKv } from "../util/sqlite-kv.js";
+import type { SqliteDatabase } from "../util/sqlite.js";
+import type { ActorScopeBindings } from "./global-scope.js";
+import { SqlStorage } from "./sql.js";
+import { SyncKvStorage } from "./sync-kv.js";
+/**
+ * ← `MAX_FACET_NAME_LENGTH` / `MAX_FACET_TREE_DEPTH`
+ * (`actor-state.c++:943,947`), in the anonymous namespace beside the facet code
+ * that enforces them. The scaffolding had them in `server/`, which is neither
+ * where upstream puts them nor where they are checked.
+ */
+export declare const FACET_NAME_MAX_LENGTH = 256;
+/** Root is at depth 0, so the deepest allowed facet is at depth 3. */
+export declare const FACET_TREE_MAX_DEPTH = 4;
+/**
+ * The substrate boundary named in the package README: Hibernatable WebSockets
+ * exist so the platform can evict an actor while keeping its sockets open, and
+ * Chrome exposes no equivalent lifecycle. Under this repo's fail-closed tenet
+ * the throw IS the specified behaviour, which is why §2.5 orders the four
+ * silent no-op stubs beside it replaced.
+ */
+export declare const HIBERNATION_UNIMPLEMENTED_MESSAGE: string;
+/**
+ * ← what falls off the end of `DurableObjectFacets::get`'s class switch
+ * (`actor-state.c++:1029-1043`).
+ *
+ * Upstream accepts three things as `FacetStartupOptions.class`: a bare
+ * `DurableObjectClass`, a `LoopbackDurableObjectNamespace`, or a
+ * `LoopbackColoLocalActorNamespace`, unwrapping the last two through
+ * `getClass()`. All three are ported — the loopback pair by
+ * `api/export-loopback.ts` — and `KJ_UNREACHABLE` is the fourth case there
+ * because JSG has already refused anything else while unwrapping the
+ * `kj::OneOf`. The check has to be written here because
+ * `@cloudflare/workers-types` declares `interface DurableObjectClass<_T> {}`,
+ * which every object satisfies, so nothing refuses it before the method body.
+ */
+export declare const FACET_CLASS_UNSUPPORTED_MESSAGE: string;
+/**
+ * ← `serializeV8Value`. The wire bytes differ because V8's serializer is not
+ * available in browsers; the public structured-clone value semantics do not.
+ * The short header keeps the new representation unambiguous while old JSON rows
+ * remain readable.
+ */
+export declare function serializeValue(_key: string, value: unknown): Uint8Array;
+/**
+ * ← `deserializeV8Value`.
+ *
+ * Upstream logs "the key (to help find the data in the database if it hasn't
+ * been deleted), the length of the value, and the first three bytes of the value
+ * (which is just the v8-internal version header and the tag that indicates the
+ * type of the value, but not its contents)". Our four-byte header carries only
+ * a marker and version for the same reason.
+ */
+export declare function deserializeValue(key: string, buffer: Uint8Array): unknown;
+/** ← `DurableObjectStorageOperations::CompiledListOptions`. */
+export type CompiledListOptions = {
+    readonly start: string;
+    readonly end: string | undefined;
+    readonly reverse: boolean;
+    readonly limit: number | undefined;
+};
+/**
+ * ← `DurableObjectStorageOperations::compileListOptions`
+ * (`actor-state.c++:314-417`). Returns undefined if the list operation would
+ * provably return no results. Public because `SyncKvStorage` reuses it, exactly
+ * as upstream's comment says it must.
+ *
+ * Two translations. `startAfter` gains ONE null character where upstream's
+ * `kj::String` gains two, because the second of upstream's is the terminator and
+ * a JS string has none. And every comparison here is on UTF-16 code units where
+ * upstream's is on UTF-8 bytes, while the range the database actually applies is
+ * SQLite's `BINARY` collation over UTF-8 — the two orders agree for every key
+ * outside the astral planes, and a key that mixes astral characters with a
+ * prefix can land on the wrong side of a clamp this function computes.
+ */
+export declare function compileListOptions(options: DurableObjectListOptions | undefined): CompiledListOptions | undefined;
+/**
+ * ← `DurableObjectStorageOperations`. "Common implementation of
+ * DurableObjectStorage and DurableObjectTransaction. This class is designed to
+ * be used as a mixin."
+ */
+export declare abstract class DurableObjectStorageOperations {
+    #private;
+    protected readonly ctx: IoContext;
+    constructor(ctx: IoContext);
+    protected abstract getCache(op: string): ActorCacheOps;
+    /** Whether to skip caching and allow concurrency on all operations. */
+    protected useDirectIo(): boolean;
+    /**
+     * ← `configureOptions`. Both subclasses answer `useDirectIo()` false, so this
+     * is the identity today; it is upstream's hook and the only place the two
+     * flags are forced on.
+     */
+    protected configureOptions<T extends {
+        allowConcurrency?: boolean;
+        noCache?: boolean;
+    }>(options: T): T;
+    get<T = unknown>(key: string, options?: DurableObjectGetOptions): Promise<T | undefined>;
+    get<T = unknown>(keys: string[], options?: DurableObjectGetOptions): Promise<Map<string, T>>;
+    getAlarm(maybeOptions?: DurableObjectGetAlarmOptions): Promise<number | null>;
+    list<T = unknown>(maybeOptions?: DurableObjectListOptions): Promise<Map<string, T>>;
+    put<T>(key: string, value: T, options?: DurableObjectPutOptions): Promise<void>;
+    put<T>(entries: Record<string, T>, options?: DurableObjectPutOptions): Promise<void>;
+    delete(key: string, options?: DurableObjectPutOptions): Promise<boolean>;
+    delete(keys: string[], options?: DurableObjectPutOptions): Promise<number>;
+    setAlarm(scheduledTime: number | Date, maybeOptions?: DurableObjectSetAlarmOptions): Promise<void>;
+    deleteAlarm(maybeOptions?: DurableObjectSetAlarmOptions): Promise<void>;
+}
+/**
+ * The engine `DurableObjectStorage` drives.
+ *
+ * Upstream holds an `ActorCacheInterface` and reaches `getSqliteDatabase()` /
+ * `getSqliteKv()` through it, both `kj::Maybe`s that are non-null exactly when
+ * the actor is SQLite-backed — which here it always is. `transactionSync` is the
+ * third member and is one layer lower than upstream's for the reason
+ * `io/actor-sqlite.ts` records: the savepoint depth counter and `notifyWrite`
+ * both live there, so this file's is a one-line forward the way
+ * `blockConcurrencyWhile` already is.
+ */
+export type StorageCache = ActorCacheInterface & {
+    getSqliteDatabase(): SqliteDatabase;
+    getSqliteKv(): SqliteKv;
+    transactionSync<T>(callback: () => T): T;
+};
+export declare class DurableObjectStorage extends DurableObjectStorageOperations implements globalThis.DurableObjectStorage {
+    #private;
+    constructor(ctx: IoContext, cache: StorageCache);
+    /** ← `DurableObjectStorage::getActorCacheInterface`, which `DurableObjectState::abort` needs. */
+    getActorCacheInterface(): StorageCache;
+    /** ← `DurableObjectStorage::getSqliteDb`. Always SQLite-backed here; see the header. */
+    getSqliteDb(): SqliteDatabase;
+    /** ← `DurableObjectStorage::getSqliteKv`. */
+    getSqliteKv(): SqliteKv;
+    protected getCache(): ActorCacheOps;
+    /** ← `JSG_LAZY_INSTANCE_PROPERTY(sql, getSql)`. */
+    get sql(): SqlStorage;
+    /** ← `JSG_LAZY_INSTANCE_PROPERTY(kv, getKv)`. */
+    get kv(): SyncKvStorage;
+    /**
+     * ← `DurableObjectStorage::deleteAll`.
+     *
+     * `deleteAlarm` is upstream's `FeatureFlags::get(js).getDeleteAllDeletesAlarm()`,
+     * a compatibility flag that exists so Workers published before it keep the old
+     * behaviour. A runtime with no deployed history takes the current behaviour.
+     */
+    deleteAll(maybeOptions?: DurableObjectPutOptions): Promise<void>;
+    /**
+     * ← `DurableObjectStorage::transaction`.
+     *
+     * The critical section is load bearing and upstream says why: "the call to
+     * `startTransaction()` is when the SQLite-backed implementation will actually
+     * invoke `BEGIN TRANSACTION`, so it's important that we're inside the
+     * blockConcurrencyWhile block before that point so we don't accidentally catch
+     * some other asynchronous event in our transaction."
+     *
+     * The exception is packed into the result rather than thrown out of the
+     * section, and then rethrown outside it. Upstream's reason: "We don't actually
+     * want to reset the object, we only want to roll back the transaction and
+     * propagate the exception." A throw out of a critical section permanently
+     * breaks the input gate (§1.5), so a failing transaction callback would
+     * destroy the actor.
+     */
+    transaction<T>(closure: (txn: DurableObjectTransaction) => Promise<T>): Promise<T>;
+    /** ← `DurableObjectStorage::transactionSync`, a forward for the reason above. */
+    transactionSync<T>(callback: () => T): T;
+    /**
+     * ← `DurableObjectStorage::sync`.
+     *
+     * Upstream's `awaitIo` rather than `awaitIoWithInputLock`, which is the one
+     * storage method that deliberately opens the gate: "we're merely checking if
+     * we have any pending or in-flight operations, and providing a promise that
+     * resolves when they succeed."
+     */
+    sync(): Promise<void>;
+    /**
+     * Real, not a boundary: `ActorSqlite`'s is "an ersatz implementation that's
+     * good enough for local dev with D1's Session API", built on the metadata
+     * table's local-development bookmark. Anything above this package that
+     * surfaces it to an application should know it is a counter and not a
+     * recovery point — as it is on workerd.
+     */
+    getCurrentBookmark(): Promise<string>;
+    waitForBookmark(bookmark: string): Promise<void>;
+    /** Substrate boundary: point-in-time recovery. Upstream reaches the cache directly, as this does. */
+    getBookmarkForTime(timestamp: number | Date): Promise<string>;
+    /** Substrate boundary: point-in-time recovery. */
+    onNextSessionRestoreBookmark(bookmark: string): Promise<string>;
+    /** Substrate boundary: replication. */
+    ensureReplicas(): void;
+    /** Substrate boundary: replication. */
+    disableReplicas(): void;
+    /**
+     * ← `DurableObjectStorage::getPrimary` / `isReplica`. `maybePrimary` is set
+     * only by the replica constructor, and nothing constructs a replica here, so
+     * these answer upstream's own non-replica case rather than a stubbed one.
+     */
+    getPrimary(): undefined;
+    isReplica(): boolean;
+}
+export declare class DurableObjectTransaction extends DurableObjectStorageOperations implements globalThis.DurableObjectTransaction {
+    #private;
+    constructor(ctx: IoContext, cacheTxn: ActorCacheTransaction);
+    protected getCache(op: string): ActorCacheOps;
+    /** Called from JS. */
+    rollback(): void;
+    /** Just throws an exception saying this isn't supported. */
+    deleteAll(): never;
+    /**
+     * Called from the runtime, not JS, after the transaction callback has
+     * completed. Does nothing if the transaction is already committed or rolled
+     * back. Synchronous, because `ActorCacheTransaction::commit` is (§1.4).
+     */
+    maybeCommit(): void;
+    /** Same, for the failure path. Upstream's drops the transaction, whose destructor rolls back. */
+    maybeRollback(): void;
+}
+/**
+ * ← `DurableObjectFacets`.
+ *
+ * **`clone` is the fourth method, and the vendored C++ snapshot does not have
+ * it.** The design record cites `actor-state.h:431-497` and
+ * `server.c++:721-749`; neither line range contains it, `DurableObjectFacets`
+ * there exposes exactly `get`, `abort` and `delete`, and
+ * `Worker::Actor::FacetManager` has exactly `getDepth`, `getFacet`, `abortFacet`
+ * and `deleteFacet`. It is real all the same: `@cloudflare/workers-types`
+ * 4.20260702.1 — a month newer than the snapshot — declares
+ * `clone(src: string, dst: string): void` on `DurableObjectFacets`. So the
+ * signature comes from the types and the semantics from §1.10 (abort dst, delete
+ * dst storage, recursive copy of the src subtree), and the orchestration is
+ * `server/`'s `cloneFacet`. There is nothing upstream to check the body against,
+ * which makes it the one method here with no reference — worth knowing when it
+ * is wrong.
+ */
+export declare class DurableObjectFacets implements globalThis.DurableObjectFacets {
+    #private;
+    constructor(ctx: IoContext, facetManager: FacetManager | undefined, parentId: string);
+    /**
+     * Get a facet by name, starting it if it isn't already running.
+     * `getStartupOptions` is invoked only if the facet wasn't already running.
+     *
+     * Returns a `Fetcher` instead of a `DurableObject` because the returned stub
+     * does not have the `id` or `name` methods that a DO stub normally has.
+     */
+    get<T extends Rpc.DurableObjectBranded | undefined = undefined>(name: string, getStartupOptions: () => FacetStartupOptions<T> | Promise<FacetStartupOptions<T>>): Fetcher<T>;
+    abort(name: string, reason: unknown): void;
+    delete(name: string): void;
+    clone(src: string, dst: string): void;
+}
+export type DurableObjectStateOptions = {
+    id: DurableObjectId;
+    /** The `ctx.exports` class registry. */
+    exports: Record<string, unknown>;
+    props: unknown;
+    storage?: DurableObjectStorage;
+    /** Absent for an actor whose host offers no facets, as upstream's `kj::Maybe` is. */
+    facets?: FacetManager;
+    /** ← `ActorVersion`, a deployment cohort with nothing to read it here. */
+    version?: {
+        cohort?: string;
+    };
+    /**
+     * This actor's `ServiceWorkerGlobalScope` half — the container's own
+     * `globals`. Required, unlike `storage` and `facets`: a host that offers no
+     * storage is a real posture upstream has, but an actor with no gated timers
+     * is not, and the failure of a missing one is an ungated timer that WORKS
+     * until a continuation after it touches storage. See
+     * `DurableObjectState.globals`.
+     */
+    globals: ActorScopeBindings;
+};
+/** The type passed as the first parameter to a Durable Object class's constructor. */
+export declare class DurableObjectState implements globalThis.DurableObjectState {
+    #private;
+    constructor(ctx: IoContext, options: DurableObjectStateOptions);
+    get id(): DurableObjectId;
+    get props(): unknown;
+    /** ← `JSG_LAZY_INSTANCE_PROPERTY(exports, getExports)`, behind `enableCtxExports` upstream. */
+    get exports(): Record<string, unknown>;
+    get version(): {
+        cohort?: string;
+    } | undefined;
+    /**
+     * NO upstream correspondence, because upstream needs none: a
+     * `ServiceWorkerGlobalScope` IS the isolate's global object there, so an
+     * actor's class reaches its gated `setTimeout` by writing `setTimeout`.
+     *
+     * Here one realm hosts several actors, so the names on `globalThis` can only
+     * be bound to one of them and a continuation cannot be asked which one it
+     * belongs to. `ctx` is the one reference every Durable Object class already
+     * holds and that already means exactly one actor — the constructor was handed
+     * it — so it is where the scope goes. An actor's method writes
+     * `this.ctx.globals.setTimeout(…)`; a free function it calls takes the scope
+     * as a parameter.
+     *
+     * `installActorScope` still exists and is still what a host uses for a
+     * dynamically-loaded Worker source, which has no `ctx` to reach through and
+     * its own module scope to destructure into. The two are the same object.
+     */
+    get globals(): ActorScopeBindings;
+    get storage(): DurableObjectStorage;
+    /** ← `JSG_LAZY_INSTANCE_PROPERTY(facets, getFacets)`. */
+    get facets(): DurableObjectFacets;
+    waitUntil(promise: Promise<unknown>): void;
+    /**
+     * ← `DurableObjectState::blockConcurrencyWhile` (`actor-state.c++:1128-1131`),
+     * which is a one-line forward and nothing else. The 30-second deadline, the
+     * brokenness annotation and the never-settled promise on failure all live in
+     * `IoContext::blockConcurrencyWhile`, which Section 2 already implements.
+     *
+     * Its precondition comes with it: `IoContext::blockConcurrencyWhile` calls
+     * `getInputLock()`, which asserts, so this is reachable only from inside a
+     * gated slice.
+     */
+    blockConcurrencyWhile<T>(callback: () => Promise<T>): Promise<T>;
+    /**
+     * ← `DurableObjectState::abort`. Reset the object, including breaking the
+     * output gate and canceling any writes that haven't been committed yet.
+     *
+     * `js.terminateExecutionNow()` has no port — there is no isolate to terminate —
+     * so the caller's own slice keeps running to its next await, where `IoContext`
+     * refuses to re-enter.
+     */
+    abort(reason?: string): void;
+    /** ← `DurableObjectState::getPrimaryStub`. Non-null only for a replica; see the storage note. */
+    get primaryStub(): undefined;
+    /** Substrate boundary: replication. */
+    configureReadReplication(options: {
+        mode: string;
+    }): Promise<void>;
+    acceptWebSocket(_ws: WebSocket, _tags?: string[]): never;
+    getWebSockets(_tag?: string): never;
+    setWebSocketAutoResponse(_maybeReqResp?: WebSocketRequestResponsePair): never;
+    getWebSocketAutoResponse(): never;
+    getWebSocketAutoResponseTimestamp(_ws: WebSocket): never;
+    setHibernatableWebSocketEventTimeout(_timeoutMs?: number): never;
+    getHibernatableWebSocketEventTimeout(): never;
+    getTags(_ws: WebSocket): never;
+}