@mcp-b/do-runtime 0.1.0

package/dist/src/server/alarm-scheduler.d.ts

@@ -0,0 +1,201 @@
+/**
+ * ← workerd `src/workerd/server/alarm-scheduler.{h,c++}`
+ *
+ * Delivery and retry: the `_cf_ALARM` table, the watchdog arming, the queued
+ * alarm, and the retry ladder. Measured on real workerd: an alarm re-armed for
+ * `Date.now()` from inside a running handler does NOT re-enter — delivery is
+ * serialised (`enter:1, exit:1, enter:2, exit:2`). That property is load
+ * bearing; `_cf_executingScheduleRowId` upstream is safe only because of it
+ * (§2.3). Here it falls out of the queued alarm: a `setAlarm` that arrives
+ * while a handler runs is stored on the entry and started only after the run
+ * finishes (`alarm-scheduler.c++:116-124`, `:220-227`).
+ *
+ * **This is runtime-internal, and it is what a host puts behind
+ * `ActorPorts.alarms`.** Upstream wires it the same way: `ActorSqliteHooks`
+ * (`server.c++:3199-3219`) is a three-line adapter whose `scheduleRun` is
+ * `setAlarm`/`deleteAlarm` on the scheduler, and the scheduler is built once per
+ * namespace (`server.c++:2325-2350`) rather than once per actor. `hooks(actorId)`
+ * below is that adapter, so a host composes the two instead of writing its own
+ * ladder.
+ *
+ * **One deliberate divergence, and it is the table's shape.** Upstream keeps the
+ * retry ladder in memory and reloads every alarm with its counters at zero,
+ * which is right for a process that lives for hours and is a regression on a
+ * service worker Chrome evicts after seconds — see `_cf_ALARM` below and the
+ * README's divergence table. Everything else here is upstream's, line for line.
+ *
+ * Spec: §1.8, §2.6, decisions 6, 11 and 16 in
+ * docs/decisions.md.
+ */
+import type { AlarmOutlet } from "../io/actor-sqlite.js";
+import type { Timer } from "../io/io-context.js";
+import { type SqlDatabase } from "../util/sqlite.js";
+/**
+ * ← `WorkerInterface::ALARM_RETRY_START_SECONDS` (`io/worker-interface.h:130`),
+ * re-declared as `AlarmScheduler::RETRY_START_SECONDS` (`alarm-scheduler.h:42`).
+ *
+ * "not a duration so we can left shift it" — upstream's own comment, and the
+ * reason the ladder below is a shift rather than a table.
+ */
+export declare const ALARM_RETRY_START_SECONDS = 2;
+/**
+ * ← `WorkerInterface::ALARM_RETRY_MAX_TRIES` (`io/worker-interface.h:131`) /
+ * `AlarmScheduler::RETRY_MAX_TRIES` (`alarm-scheduler.h:45`).
+ *
+ * "Max number of 'valid' retry attempts, i.e the worker returned an error."
+ * It bounds `countedRetry`, NOT `backoff`: a run of failures that do not count
+ * against the limit is retried forever, and its delay is bounded by
+ * `RETRY_BACKOFF_MAX` instead.
+ */
+export declare const ALARM_RETRY_MAX_TRIES = 6;
+/**
+ * ← `AlarmScheduler::RETRY_BACKOFF_MAX` (`alarm-scheduler.h:50`).
+ *
+ * "Bound for exponential backoff when RETRY_MAX_TRIES is exceeded due to
+ * internal errors. 2 << 9 is 1024 seconds, about 17 minutes. Total time spent in
+ * retries once the backoff limit is reached is over 30 minutes."
+ */
+export declare const RETRY_BACKOFF_MAX = 9;
+/**
+ * ← `AlarmScheduler::RETRY_JITTER_FACTOR` (`alarm-scheduler.h:54`).
+ *
+ * "How much jitter should be applied to retry times to avoid bundled retries
+ * overloading some common dependency between a set of failed alarms."
+ */
+export declare const RETRY_JITTER_FACTOR = 0.25;
+/**
+ * ← `(AlarmScheduler::RETRY_START_SECONDS << backoff) * kj::SECONDS`
+ * (`alarm-scheduler.c++:270`), before jitter.
+ *
+ * It refuses a backoff outside `[0, RETRY_BACKOFF_MAX]` rather than shifting it,
+ * because JS's `<<` is a 32-bit operator: an unclamped counter would wrap to a
+ * zero or negative delay — a hot retry loop — instead of saturating. The ladder
+ * clamps immediately above its own call, exactly where upstream does; this is
+ * what makes that clamp load bearing rather than decorative.
+ */
+export declare function alarmRetryDelayMs(backoff: number): number;
+/**
+ * ← `EventOutcome` (`io/outcome.capnp`), restricted to the values the alarm path
+ * can produce.
+ *
+ * The whole enum is a metrics type with no port — divergence 154 records that
+ * for `waitUntilStatus()` — but `runAlarm` reads one bit of it
+ * (`alarm-scheduler.c++:162`, `result.outcome != EventOutcome::OK`), so the
+ * values `ServiceWorkerGlobalScope::runAlarm` actually returns are named here
+ * and the rest are not.
+ */
+export type EventOutcome = "ok" | "canceled" | "script-not-found" | "exception" | "exceeded-cpu" | "unknown";
+/**
+ * ← `WorkerInterface::AlarmResult` (`io/worker-interface.h:71-81`).
+ *
+ * Upstream defaults all three fields; here every one is required, because the
+ * producer is `server/actor-container.ts` rather than a capnp wire default and a
+ * silently-defaulted `retryCountsAgainstLimit` is the difference between an
+ * alarm that survives a broken actor and one that is abandoned.
+ */
+export type AlarmResult = {
+    readonly retry: boolean;
+    readonly retryCountsAgainstLimit: boolean;
+    readonly outcome: EventOutcome;
+    readonly errorDescription?: string;
+};
+/**
+ * ← the `WorkerInterface` `GetActorFn` hands back
+ * (`alarm-scheduler.c++:160`, `:244`), restricted to its two alarm members.
+ *
+ * `WorkerInterface` itself has no port — it is capnp dispatch, and divergence
+ * 176 records it collapsing into the stub the transport returns — so the seam is
+ * the two methods the scheduler calls. `ActorContainer` satisfies it
+ * structurally; `deliverAlarm` is upstream's `runAlarm` under the name Section
+ * 6b already gave it.
+ */
+export interface AlarmTarget {
+    deliverAlarm(scheduledTime: number, retryCount: number): Promise<AlarmResult>;
+    /**
+     * ← `WorkerInterface::abandonAlarm` (`io/worker-interface.h:114`): "Returns the
+     * actor's stored alarm time if it differs from scheduledTime (i.e. the user
+     * set a new alarm), or null if the alarm was cleared or no alarm was stored."
+     */
+    abandonAlarm(scheduledTime: number): Promise<number | null>;
+}
+/** ← `AlarmScheduler::GetActorFn` (`alarm-scheduler.h:56`). */
+export type GetActorFn = (actorId: string) => AlarmTarget;
+export type AlarmSchedulerOptions = {
+    /**
+     * ← the `const kj::Clock&` and the `kj::Timer&` upstream takes separately
+     * (`alarm-scheduler.h:58-59`). One object here because `Timer.now()` is
+     * already wall-clock milliseconds — `IoContext::now()` reads the same one —
+     * so nothing distinguishes the two. `checkTimestamp`'s re-check loop stays,
+     * because a JS timer really can fire a fraction of a millisecond early
+     * relative to the clock it is compared against.
+     */
+    timer: Timer;
+    /**
+     * The database `_cf_ALARM` lives in — upstream's `metadata.sqlite`, one per
+     * namespace beside the per-actor files (`server.c++:2336-2346`).
+     *
+     * Already open, where upstream's constructor opens it from a vfs and a path:
+     * `SqlDatabaseProvider.open` is asynchronous and a constructor cannot await,
+     * which is the same reason `createActorContainer` is a promise.
+     */
+    db: SqlDatabase;
+    getActor: GetActorFn;
+    /**
+     * Browser hosts can mirror the earliest durable wake onto a platform watchdog
+     * such as `chrome.alarms`. Workerd needs no such seam because its process owns
+     * the scheduler timer.
+     */
+    projectWake?: (scheduledTime: number | null) => Promise<void> | void;
+    /**
+     * ← `std::default_random_engine`, seeded from the monotonic clock
+     * (`alarm-scheduler.c++:20-27`). A test seam on a runtime-internal class, not
+     * a substrate port: the jitter is the one part of the ladder that is
+     * deliberately not a function of its inputs.
+     */
+    random?: () => number;
+};
+/**
+ * Allows scheduling alarm executions at specific times, returning a promise
+ * representing the completion of the alarm event.
+ */
+export declare class AlarmScheduler {
+    #private;
+    constructor(options: AlarmSchedulerOptions);
+    /**
+     * ← `getAlarm` (`alarm-scheduler.c++:84-99`), including its TODO: "Might be
+     * able to simplify AlarmScheduler somewhat, now that ActorSqlite no longer
+     * relies on it for getAlarm()?"
+     */
+    getAlarm(actorId: string): number | null;
+    /**
+     * ← `setAlarm` (`alarm-scheduler.c++:101-127`).
+     *
+     * The `boolean` is upstream's `query.changeCount() > 0`, and it is constant
+     * true against SQLite's semantics: an `INSERT … ON CONFLICT DO UPDATE` always
+     * reports one changed row, even when the value is unchanged. No caller reads it
+     * — `ActorSqliteHooks::scheduleRun` discards it — so it is kept as upstream's
+     * shape rather than as a signal.
+     */
+    setAlarm(actorId: string, scheduledTime: number): boolean;
+    /** ← `deleteAll` (`alarm-scheduler.c++:129-134`). */
+    deleteAll(): void;
+    /** ← `deleteAlarm` (`alarm-scheduler.c++:136-156`). */
+    deleteAlarm(actorId: string): boolean;
+    /**
+     * ← `ActorSqliteHooks` (`server.c++:3199-3219`), which is the whole of how an
+     * actor's storage engine reaches a scheduler: one adapter per actor, holding
+     * that actor's key, turning a time into `setAlarm` or `deleteAlarm`.
+     */
+    hooks(actorId: string): AlarmOutlet;
+    /**
+     * ← `taskFailed`'s `KJ_LOG(WARNING, e)` (`alarm-scheduler.c++:289-291`), and
+     * the two other log sites in `makeAlarmTask` that report a failure and carry
+     * on (`:202`, `:285`).
+     *
+     * This package has no logger, so the exception is kept instead of written —
+     * the same treatment divergence 154 records for `waitUntilStatus()`, and for
+     * the same reason: a background failure that is neither logged nor readable is
+     * one nothing can notice.
+     */
+    taskFailure(): unknown;
+}

package/dist/src/server/facet-deletion.d.ts

@@ -0,0 +1,156 @@
+/**
+ * ← workerd `NO upstream correspondence`
+ *
+ * Generation-fenced deletion receipts, serialized subtree deletion, reference
+ * epochs. Keyed by facet id, never by an app address.
+ *
+ * **Why there is no upstream twin.** `ActorContainer::deleteFacet`
+ * (`server.c++:2642-2655`) aborts the child and then calls
+ * `directory->remove(...)` — synchronous, in-process, on a real filesystem. It
+ * cannot be interrupted between "the app asked" and "the bytes are gone", so it
+ * needs no record that it was asked. Here the same call is
+ * `FacetHost.deleteStorage`, which is asynchronous because it is the HOST's and a
+ * host's storage removal is not required to be prompt: OPFS removal is
+ * asynchronous in general, and the extension's supervisor crosses a worker to do
+ * it. `ctx.facets.delete()` is synchronous and `void` regardless — so the app's
+ * request outlives the process that has to carry it out. §2.7 records the browser
+ * host's answer to that, generation-fenced receipts, as "a genuine improvement
+ * over workerd, which has no equivalent because its facets are in-process". This
+ * is that answer, moved down into the runtime and re-keyed.
+ *
+ * In-process facets do not remove this gap. What upstream gets from them is that
+ * `kj::Directory::remove` is a synchronous call it can finish before returning.
+ * The seam here is `Promise<void>` whoever implements it, so the gap between "the
+ * app asked" and "the bytes are gone" is still real and still spans a possible
+ * teardown. The two conformance lanes happen to close that gap promptly — one
+ * through `rmSync`, one through the SAH pool's `unlink` — and the receipt is what
+ * makes a host that cannot, such as the extension's supervisor, survivable.
+ *
+ * **What changed in the move, and it is the whole of the change.** The
+ * extension's version (`offscreen/worker/host/facet-deletion.ts`) is keyed by an
+ * `AgentWorkerAddress` — a root name plus a path of `{className, name}` steps —
+ * and derives "is this address inside that subtree" by comparing path prefixes.
+ * Here the key is a `FacetId`, the small integer `server/facet-tree-index.ts`
+ * assigns, and ancestry is not derivable from it: id 7 says nothing about who its
+ * parent is. So every operation that needs a subtree is *given* one, computed
+ * from the index by the caller that already holds it, and this file has no
+ * opinion about tree shape at all. That is a smaller module, not a larger one:
+ * three of the extension's helpers — `isAgentAddressInTree`,
+ * `isAgentStorageKeyInTree`, `isAgentStorageEntryInTree` — exist only to answer
+ * the ancestry question from a string, and none of them has anything to do here.
+ *
+ * Storage is the facet-tree database rather than the actor's own, and that is
+ * load bearing: `SqliteKv::deleteAll()` calls `db.reset()`
+ * (`util/sqlite-kv.ts`), which replaces the actor's database file wholesale. A
+ * receipt recorded there would be destroyed by the very `deleteAll()` whose
+ * cascade it exists to make recoverable. It sits beside the tree index for the
+ * same reason the index does — both are facts about the tree rather than about
+ * any one actor's contents.
+ *
+ * Spec: §2.7, decision 14 in docs/decisions.md.
+ */
+import { type SqlDatabase } from "../util/sqlite.js";
+import type { FacetId } from "./actor-container.js";
+/**
+ * One recorded intent to delete a facet's storage.
+ *
+ * `generation` is the fence. A receipt is cleared only if the row still carries
+ * the generation this receipt was issued with, so a delete that was requested
+ * again while the first deletion was in flight cannot have its second request
+ * erased by the first request's completion.
+ */
+export type FacetDeletionReceipt = {
+    readonly id: FacetId;
+    readonly generation: number;
+};
+/**
+ * Parent-owned durable receipts for the synchronous `ctx.facets.delete()`
+ * boundary. The doomed child never owns its own deletion decision — it may not
+ * be running, and if it is, it is the thing being destroyed.
+ */
+export declare class FacetDeletionReceiptStore {
+    #private;
+    constructor(db: SqlDatabase);
+    /** Bumps the generation for `id` and returns the receipt naming it. */
+    record(id: FacetId): FacetDeletionReceipt;
+    read(id: FacetId): FacetDeletionReceipt | undefined;
+    /**
+     * Every outstanding receipt, oldest facet first, for boot-time replay.
+     *
+     * The `ORDER BY` cannot be shown to matter and is kept anyway: `facet_id` is
+     * an `INTEGER PRIMARY KEY`, which is the rowid, so both backends scan the
+     * table in that order with or without it. Removing it survives the whole
+     * suite — a mutant that no test can kill, because killing it needs a SQLite
+     * that returns rows out of rowid order, and nothing this package can reach
+     * does. Relying on the scan order rather than saying so is the kind of thing
+     * that is right until a schema change makes it silently wrong.
+     */
+    list(): FacetDeletionReceipt[];
+    /**
+     * Clears the receipt if and only if it is still the one that was issued.
+     * Returns false when a newer request has superseded it, which is the whole
+     * point of the generation.
+     */
+    clear(receipt: FacetDeletionReceipt): boolean;
+}
+/**
+ * Replays and generation-fences one parent's durable child-deletion receipts.
+ *
+ * Recording is synchronous — that is the boundary `ctx.facets.delete()` has to
+ * hold — and only the physical deletion crosses an async boundary. A second
+ * delete of the same facet while the first is in flight records a newer
+ * generation and queues behind it rather than racing it, so a facet cannot be
+ * half-deleted by two overlapping attempts.
+ */
+export declare class FacetDeletionController {
+    #private;
+    constructor(receipts: FacetDeletionReceiptStore, deleteSubtree: (receipt: FacetDeletionReceipt) => Promise<void>);
+    /**
+     * Record the intent durably now, then carry it out after the caller's actor
+     * ordering has settled. The record is synchronous even when the barrier is
+     * still pending.
+     */
+    delete(id: FacetId, waitBeforeDelete?: Promise<unknown>): Promise<void>;
+    /** Carry out whatever is still recorded for `id`, until nothing is. */
+    flush(id: FacetId): Promise<void>;
+    /** ← boot. Every receipt a previous session left behind is carried out before the actor runs. */
+    recoverAll(): Promise<void>;
+}
+/**
+ * Serializes physical subtree deletion while retaining subtree-aware waits.
+ *
+ * Two deletions that overlap in the tree must not run at once: the inner one
+ * would be removing files the outer one is walking. Serializing every deletion
+ * is the simplest thing that is correct, and deletion is not on any hot path.
+ * `waitFor` is the other half — anything about to *use* a facet has to wait for
+ * a pending deletion that covers it, and the ids each pending operation covers
+ * are recorded rather than derived, because a facet id does not encode its
+ * ancestry.
+ */
+export declare class SerializedSubtreeDeletionQueue {
+    #private;
+    /** Runs `operation` after every operation already queued, covering `ids`. */
+    run(ids: Iterable<FacetId>, operation: () => Promise<void>): Promise<void>;
+    /** Resolves once no queued deletion covers `id`. Failures are not the waiter's to report. */
+    waitFor(id: FacetId): Promise<void>;
+}
+/**
+ * Epochs make every capability captured before an ancestor abort or delete
+ * stale.
+ *
+ * The hazard this closes has no workerd equivalent for the same reason the
+ * receipts do not: upstream's `abortFacet` erases the map entry and the stub
+ * that was handed out is refcounted against a container that is now broken, so
+ * a later call on it fails by itself. Here the stub is a value that outlives the
+ * placement, so something has to be able to say "the thing you are holding was
+ * torn down". Invalidation is by explicit subtree because a `FacetId` does not
+ * encode ancestry.
+ */
+export declare class FacetReferenceEpochs {
+    #private;
+    /** The epoch to remember alongside a capability. */
+    capture(id: FacetId): number;
+    /** Bumps `root` and every id in `subtree`, so captures older than this call stop matching. */
+    invalidate(root: FacetId, subtree?: Iterable<FacetId>): void;
+    isCurrent(id: FacetId, epoch: number): boolean;
+}

package/dist/src/server/facet-tree-index.d.ts

@@ -0,0 +1,94 @@
+/**
+ * ← workerd `src/workerd/server/facet-tree-index.{h,c++}`
+ *
+ * Upstream's own summary: "Implements an index, stored on disk, which maps
+ * leaves of a tree to small integers in a stable way." One facet — id zero — is
+ * the root; every other facet has a parent and a name, names are unique among
+ * siblings but not globally, and each (parent, name) pair is assigned the next
+ * sequential id the first time it is seen. Deleting a facet does not release its
+ * id: recreating the same name under the same parent gets the same id back,
+ * which is what decision 14 means by "stable ids across delete-and-recreate."
+ *
+ * The whole index is held in memory, loaded at construction, because upstream
+ * assumes "the total number of facets created for a single Durable Object over
+ * its entire lifetime will never be very large" (`facet-tree-index.h:19-22`).
+ * That is what makes the file append-only, and the append-only format is what
+ * makes a torn tail safe to discard: an entry written but not synced cannot have
+ * been relied on, so a nonsensical entry ends the read and the remainder is
+ * truncated away.
+ *
+ * **The one seam: `kj::File` becomes `IndexFile`.** Upstream takes a
+ * `kj::Own<const kj::File>` and calls exactly four members on it —
+ * `readAllBytes`, `write`, `truncate` and `datasync`. There is no `kj/filesystem`
+ * port and no reason to build one for four methods, so those four become an
+ * interface and `server/` supplies it. Every method is synchronous because every
+ * method upstream is, and because `facets.get` is synchronous all the way down;
+ * both substrates can answer that (`FileSystemSyncAccessHandle` in a worker,
+ * `node:fs`'s sync family), which is the same shape the storage backends already
+ * take.
+ *
+ * **A name is its UTF-8 bytes, not its JS string.** Upstream's names are
+ * `kj::String`s, so the on-disk bytes *are* the identity and the ordering.
+ * `TextEncoder` is not injective on JS strings — every lone surrogate encodes to
+ * U+FFFD — so keying this index by the JS string would let two distinct names
+ * collide on disk and share one facet's storage file after a reload. Entries are
+ * therefore identified and ordered by their encoded bytes, and `forEachChild`
+ * reports the round-tripped name, which is what a reload would report. That also
+ * makes the ordering exact: upstream's `kj::TreeSet` orders by `kj::String`'s
+ * byte comparison, where JS `<` would order by UTF-16 code unit and disagree for
+ * any name mixing astral characters with U+E000..U+FFFF.
+ *
+ * **The scaffolding recorded a divergence here that is wrong, and it is not
+ * kept.** That header said workerd keeps one index per root actor while "our tree
+ * spans workers, so each parent indexes its direct children." Upstream's index
+ * already *is* keyed by (parent, name) — `getId(parent, name)`,
+ * `forEachChild(parentId, …)` — so a per-parent index changes nothing about what
+ * is indexed and only changes what an id *means*: upstream's ids are sequential
+ * across the whole tree, and they name storage files in one flat namespace,
+ * `<actor-id>.<facetId>.sqlite` (`server.c++:2737-2743`). Per-parent counters
+ * would mint id 1 under every parent and collide those files. Nor does the
+ * premise hold: the index is owned by the root *container*, not by an actor's
+ * worker (`server.c++:2680-2681`, `:2697`), and `FacetHost` already speaks a flat
+ * `FacetId = number` with a precomputed subtree — which only a whole-tree index
+ * can produce. Ported as upstream has it.
+ *
+ * Spec: §1.10, decision 14 in docs/decisions.md.
+ */
+/**
+ * ← the `kj::File` members `FacetTreeIndex` calls, and nothing else.
+ *
+ * `datasync()` is not decoration: the format's recovery story is that an entry
+ * which was written but never synced was never relied upon, so a substrate that
+ * drops it turns a torn tail from "discard and reassign" into "two facets, one
+ * id".
+ */
+export interface IndexFile {
+    /** ← `kj::File::readAllBytes()`. Called once, at construction. */
+    readAllBytes(): Uint8Array;
+    /** ← `kj::File::write(offset, data)`. Extends the file when it writes past the end. */
+    write(offset: number, data: Uint8Array): void;
+    /** ← `kj::File::truncate(size)`. Only ever shrinks, to drop a corrupted tail. */
+    truncate(size: number): void;
+    /** ← `kj::File::datasync()`. */
+    datasync(): void;
+}
+/** ← `FacetTreeIndex` (`facet-tree-index.h:50-123`). */
+export declare class FacetTreeIndex {
+    #private;
+    /**
+     * ← the constructor (`facet-tree-index.c++:11-86`). "Construct the index,
+     * reading the given file to populate the initial index, and then arranging to
+     * append new entries to the file as needed."
+     */
+    constructor(file: IndexFile);
+    /** ← `FacetTreeIndex::getId`. "Gets the ID for the given facet, assigning it if needed." */
+    getId(parent: number, name: string): number;
+    /**
+     * ← `FacetTreeIndex::forEachChild`. "For each child of the given parent ID,
+     * call the callback."
+     *
+     * Upstream walks a `kj::TreeSet` range, so children arrive ordered by name
+     * rather than by id; the sort here is that ordering, over the same bytes.
+     */
+    forEachChild(parentId: number, callback: (childId: number, name: string) => void): void;
+}

package/dist/src/server/sha256.d.ts

@@ -0,0 +1,39 @@
+/**
+ * ← workerd `NO upstream correspondence`
+ *
+ * The substrate replacement for the two includes `server/actor-id-impl.{h,c++}`
+ * makes — `<openssl/sha.h>` and `<openssl/hmac.h>` — and nothing else. Only
+ * `actor-id-impl.ts` consumes it, which is why it sits here rather than in
+ * `util/`: `src/util/` corresponds 1:1 to `src/workerd/util/`, and workerd has no
+ * digest there. `server/facet-deletion.ts` sets the precedent for a file in this
+ * directory with no upstream twin.
+ *
+ * **Why this exists at all.** Every method on `ActorIdFactory` is synchronous
+ * (`io/actor-id.h:66-71`), and the browser exposes no synchronous digest:
+ * `crypto.subtle.digest` returns a promise, and `node:crypto` is one lane only.
+ * So the algorithm is written out. It is a **substrate** divergence in decision
+ * 16's sense and not a semantic one — the bytes are the bytes FIPS 180-4 and RFC
+ * 2104 specify, which is exactly what BoringSSL computes, so an id minted here is
+ * the same 64 hex digits workerd mints from the same unique key. That equality is
+ * the whole reason for writing the real digest rather than a cheaper keyed
+ * function the reduced threat model would have tolerated: it keeps workerd
+ * available as an oracle for ids, where an invented construction would have made
+ * every future id question original research.
+ *
+ * No dependency was added. Nothing in the workspace ships a synchronous SHA-256,
+ * and the catalog's `crypto-browserify` is a CommonJS bundler shim for the
+ * extension that would not typecheck under this package's `WebWorker`-only lib.
+ */
+/** ← `SHA256_DIGEST_LENGTH`. */
+export declare const SHA256_DIGEST_LENGTH = 32;
+/** ← `SHA256(data, length, out)`. FIPS 180-4 §6.2. */
+export declare function sha256(message: Uint8Array): Uint8Array;
+/**
+ * ← `HMAC(EVP_sha256(), key, keyLength, data, dataLength, out, &outLength)`.
+ * RFC 2104.
+ *
+ * Upstream's comment on why a MAC is used for something that is not
+ * authentication: "We're using HMAC as a keyed hash here, not actually for
+ * authentication, but it works" (`actor-id-impl.c++:74-75`).
+ */
+export declare function hmacSha256(key: Uint8Array, message: Uint8Array): Uint8Array;

package/dist/src/transport/rpc-session.d.ts

@@ -0,0 +1,34 @@
+/**
+ * ← workerd `NO upstream correspondence (capnweb adaptation)`
+ *
+ * The one door onto a capnweb session, so that decision 18's identity graft
+ * cannot be skipped by establishing one some other way.
+ *
+ * The `RpcTarget` identity graft lives here because the guarantee belongs to
+ * the call that establishes a session, not to whichever sibling module happened
+ * to run a side effect first. It is re-applied for every session and is
+ * idempotent.
+ *
+ * **What this deliberately is not.** It is not a transport abstraction and takes
+ * no options capnweb does not: a lane or a host that needs
+ * `newWebSocketRpcSession` instead should call `reconcileRpcTargetIdentity()`
+ * itself and say so, rather than growing this into a second capnweb API. The
+ * `MessagePort` form is the only one this substrate uses — the extension's
+ * offscreen↔worker hop and the browser lane's page↔actor and page↔alarms hops are
+ * all `newMessagePortRpcSession` — and a port carries structured clone, which is
+ * what makes capnweb's `structuredClonable` encoding level available.
+ *
+ * Spec: decision 18 in docs/decisions.md.
+ */
+import { type RpcStub } from "capnweb";
+/** Make the declared Workers RpcTarget recognizable to capnweb by reference. */
+export declare function reconcileRpcTargetIdentity(): void;
+/**
+ * Establish a capnweb session over a `MessagePort`, with the `RpcTarget`
+ * identity reconciled first.
+ *
+ * `localMain` is what the peer reaches; the returned stub is what the peer
+ * exposed. Both ends call this — a session is symmetric — and either side may
+ * omit its main when it exports nothing.
+ */
+export declare function newRpcSession<T = unknown>(port: MessagePort, localMain?: unknown): RpcStub<T>;

package/dist/src/util/sqlite-kv.d.ts

@@ -0,0 +1,98 @@
+/**
+ * ← workerd `src/workerd/util/sqlite-kv.{h,c++}`
+ *
+ * KV storage on top of SQLite, for Durable Object storage.
+ *
+ * The table is named `_cf_KV`. The naming is designed so that if the
+ * application is allowed to perform direct SQL queries, we can block it from
+ * accessing any table prefixed with `_cf_`.
+ *
+ * This layer is bytes in, bytes out, exactly as upstream is. The structured
+ * value encoding happens above it, in `api/actor-state.ts`, which is where
+ * upstream V8-serializes.
+ *
+ * Three translations, each of them forced:
+ *
+ *  - `get`'s callback exists upstream to avoid copying bytes out of a live
+ *    sqlite row. Our backends have already materialised the row by the time we
+ *    see it, so there is no copy to avoid and the value is returned.
+ *  - `delete_` is spelled `delete` — the C++ name carries a trailing underscore
+ *    only because `delete` is a keyword there.
+ *  - Upstream's `Uninitialized` / `Initialized` pair exists solely to hold
+ *    thirteen `SqliteDatabase::Statement`s. Prepared statements are not part of
+ *    our backend seam (each `exec` prepares), so the pair collapses into the
+ *    `tableCreated` flag it already sits beside. The statements survive as
+ *    `STMT` below: same names, same order, SQL copied verbatim, so the
+ *    correspondence a reader needs is intact.
+ *
+ * Not ported: `SqliteKvRegulator`. Its remaining job is `shouldAddQueryStats`,
+ * which is row-count billing; neither backend exposes those counters.
+ *
+ * Spec: §2.4 in docs/decisions.md.
+ */
+import { type ResetListener, type SqliteDatabase } from "./sqlite.js";
+export type KeyPtr = string;
+export type ValuePtr = Uint8Array;
+/** ← `SqliteKv::Order`. */
+export type Order = "FORWARD" | "REVERSE";
+/** ← `SqliteKv::WriteOptions`. */
+export type WriteOptions = {
+    allowUnconfirmed?: boolean;
+};
+/** ← `SqliteKv::ListCursor::KeyValuePair`, and the shape `put(pairs)` iterates. */
+export type KeyValuePair = {
+    key: KeyPtr;
+    value: ValuePtr;
+};
+export declare class SqliteKv implements ResetListener {
+    #private;
+    constructor(db: SqliteDatabase);
+    /**
+     * Search for a match for the given key. Returns the value if found, undefined
+     * if not.
+     */
+    get(key: KeyPtr): ValuePtr | undefined;
+    /**
+     * Search for all known keys and values in a range. `end` and `limit` can be
+     * undefined to request no constraint be enforced.
+     *
+     * With a callback, calls it for each row seen and returns the count. Without
+     * one, returns a cursor which can be iterated one at a time.
+     */
+    list(begin: KeyPtr, end: KeyPtr | undefined, limit: number | undefined, order: Order): SqliteKvListCursor;
+    list(begin: KeyPtr, end: KeyPtr | undefined, limit: number | undefined, order: Order, callback: (key: KeyPtr, value: ValuePtr) => void): number;
+    /** Store a value into the table, or atomically store multiple values. */
+    put(key: KeyPtr, value: ValuePtr, options?: WriteOptions): void;
+    put(pairs: Iterable<KeyValuePair>, options: WriteOptions): void;
+    /** Delete the key and return whether it was matched. */
+    delete(key: KeyPtr, options?: WriteOptions): boolean;
+    deleteAll(): number;
+    /** ResetListener interface: we'll need to recreate the table on the next operation. */
+    beforeSqliteReset(): void;
+    /** Called by a cursor that has run out of rows, mirroring `~ListCursor::State`. */
+    releaseCursor(cursor: SqliteKvListCursor): void;
+}
+/**
+ * ← `SqliteKv::ListCursor`.
+ *
+ * Upstream's iterates a live sqlite statement, which is why only one may be
+ * open at a time and why a new `list()` cancels the previous cursor. Our rows
+ * arrive materialised, so nothing forces that constraint — it is kept because
+ * `wasCanceled()` is part of the contract above this layer, and a cursor whose
+ * cancellation depended on the substrate would make the browser and Node lanes
+ * disagree. What we do lose is streaming: an unbounded `list()` reads the whole
+ * range into memory, where upstream reads a row at a time.
+ */
+export declare class SqliteKvListCursor {
+    #private;
+    constructor(parent: SqliteKv | null, rows: readonly (readonly unknown[])[] | null);
+    next(): KeyValuePair | undefined;
+    forEach(callback: (key: KeyPtr, value: ValuePtr) => void): number;
+    /**
+     * If true, the cursor was canceled due to a new list() operation starting.
+     * Only one list() is allowed at a time.
+     */
+    wasCanceled(): boolean;
+    /** Called by `SqliteKv` only. */
+    cancel(): void;
+}

package/dist/src/util/sqlite-metadata.d.ts

@@ -0,0 +1,46 @@
+/**
+ * ← workerd `src/workerd/util/sqlite-metadata.{h,c++}`
+ *
+ * A simple metadata kv storage and cache on top of SQLite. Currently used to
+ * store:
+ *
+ *  - Durable Object alarm times (hardcoded as key = 1);
+ *  - a local development bookmark used to simulate the getCurrentBookmark API
+ *    used by D1 (hardcoded as key = 2), not used in production.
+ *
+ * The table is named `_cf_METADATA`. The naming is designed so that if the
+ * application is allowed to perform direct SQL queries, we can block it from
+ * accessing any table prefixed with `_cf_`.
+ *
+ * Times are milliseconds, not nanoseconds. Upstream stores
+ * `(t - UNIX_EPOCH) / kj::NANOSECONDS` as an int64. A JS number runs out of
+ * integer precision 104 days into the epoch at nanosecond scale, so storing
+ * what upstream stores would silently round every alarm. Milliseconds are also
+ * what every caller above this already uses.
+ *
+ * The local-development bookmark IS ported, which the package's bookmark
+ * substrate boundary might seem to rule out. It does not: that boundary is
+ * `getCurrentBookmark` / `getBookmarkForTime` / `onNextSessionRestoreBookmark`,
+ * which need point-in-time recovery from the storage engine. Key 2 is an
+ * integer in a row, and D1 uses it locally precisely because it needs nothing.
+ *
+ * Spec: §1.8, §2.6 in docs/decisions.md.
+ */
+import { type ResetListener, type SqliteDatabase } from "./sqlite.js";
+export declare class SqliteMetadata implements ResetListener {
+    #private;
+    constructor(db: SqliteDatabase);
+    /** Return currently set alarm time, or null. */
+    getAlarm(): number | null;
+    /**
+     * Sets current alarm time, or null. Returns true if the value changed, false
+     * if it was already set to the same value.
+     */
+    setAlarm(currentTime: number | null, allowUnconfirmed: boolean): boolean;
+    /** Return the current local development bookmark, or null if none has been set. */
+    getLocalDevelopmentBookmark(): number | null;
+    /** Set the current ersatz bookmark. */
+    setLocalDevelopmentBookmark(bookmark: number): void;
+    /** ResetListener interface: we'll need to recreate the table on the next operation. */
+    beforeSqliteReset(): void;
+}