@mcp-b/do-runtime 0.1.0

package/dist/src/io/actor-cache.d.ts

@@ -0,0 +1,203 @@
+/**
+ * ← workerd `src/workerd/io/actor-cache.h` — INTERFACE ONLY.
+ *
+ * The `actor-cache.c++` LRU implementation is ABSENT rather than skipped: it
+ * caches a remote storage service that none of our substrates have. Upstream
+ * does not use it in SQLite mode either — `ActorSqlite` is the sole
+ * `ActorCacheInterface` implementation there, and the same is true here.
+ *
+ * The two behaviours decision 5 names live in `io/actor-sqlite.ts`, which is
+ * where workerd's SQLite path exhibits them: `allowUnconfirmed` skips the
+ * output-gate lock but STILL breaks the gate on error, and a batch started as
+ * unconfirmed is retroactively upgraded when a must-confirm write joins it.
+ *
+ * Ordering guarantee, upstream's words (`actor-cache.h:334-340`): writes are
+ * never committed out-of-order, by brute force — one transaction commits all
+ * dirty keys at once.
+ *
+ * This file carries only what `ActorSqlite` genuinely implements. Everything in
+ * `ActorCacheInterface` that exists solely for the LRU — `evictStale`'s
+ * backpressure, the RPC storage client, the shared LRU and its hooks — is
+ * absent with it.
+ *
+ * The one shape that is ours rather than upstream's: **every read and write is
+ * synchronous.** Upstream returns `kj::OneOf<T, kj::Promise<T>>` so a cache miss
+ * can go to the network; §1.4 measures that a SQLite-backed actor never does,
+ * and the SQLite arm of every one of those `OneOf`s is the immediate value. A
+ * `OneOf` with one reachable arm is a promise nobody can observe, and keeping it
+ * would make `api/actor-state.ts` unwrap something that is never a promise.
+ * `onNoPendingFlush` and `abandonAlarm` stay asynchronous because upstream's
+ * SQLite arm is genuinely asynchronous there.
+ *
+ * Spec: §1.7, decisions 2 and 5.
+ */
+/** ← `ActorCacheOps::Key`. "Keys are text for now." */
+export type Key = string;
+/** ← `ActorCacheOps::Value`. Values are raw bytes; the value encoding is `api/`'s. */
+export type Value = Uint8Array;
+/** ← `ActorCacheOps::KeyValuePair`. */
+export type KeyValuePair = {
+    readonly key: Key;
+    readonly value: Value;
+};
+/**
+ * ← `ActorCacheOps::GetResultList`, which upstream makes a class so it can
+ * iterate pointers into the cache's own storage. Ours has already copied.
+ */
+export type GetResultList = readonly KeyValuePair[];
+/**
+ * The option bags. Per §1.2 `allowConcurrency` is precisely the input-gate
+ * opt-out: it selects `awaitIo` over `awaitIoWithInputLock`, which per §1.7.1
+ * also ends the implicit transaction.
+ *
+ * Nothing passes any of these today — not upstream, not this repo, not the
+ * vendored tests. They are built anyway; building half of the
+ * `awaitIoWithInputLock` branch is the feature-subset failure the porting
+ * philosophy rejects. The conformance suite exercises them deliberately.
+ *
+ * Placement note: upstream's `ActorCacheReadOptions` holds only `noCache`, and
+ * `allowConcurrency` is read one layer up, in `DurableObjectStorageOperations`
+ * (`actor-state.c++:68-79`) — `ActorCacheOps` never sees it. Part 4's table puts
+ * decision 2 in this file, so it is declared here and consumed by `api/`;
+ * `ActorSqlite` itself reads neither `allowConcurrency` nor `noCache`, exactly
+ * as upstream's does not.
+ */
+export type ReadOptions = {
+    /** Release the input gate across the await. Ends the implicit transaction. */
+    allowConcurrency?: boolean;
+    /** Do not retain the value in cache. */
+    noCache?: boolean;
+};
+export type WriteOptions = ReadOptions & {
+    /** Skip the output-gate lock. Never skips break-on-error. */
+    allowUnconfirmed?: boolean;
+};
+/** ← `DeleteAllOptions`. */
+export type DeleteAllOptions = {
+    /**
+     * When true, deleteAll() will also delete any scheduled alarm. The alarm
+     * deletion is guaranteed to take effect only after the deleteAll() itself
+     * succeeds, so that we never end up in a state where the alarm is deleted but
+     * KV data remains.
+     */
+    deleteAlarm?: boolean;
+};
+/**
+ * ← `ActorCacheInterface::DeleteAllResults`.
+ *
+ * Upstream splits these "so client code that doesn't need the count doesn't have
+ * to wait for it just to account for backpressure". Both arms are immediate for
+ * SQLite: `backpressure` is always `kj::none` and `count` is a ready promise.
+ */
+export type DeleteAllResults = {
+    readonly backpressure: Promise<void> | undefined;
+    readonly count: number;
+};
+/**
+ * ← `ActorCacheInterface::CancelAlarmHandler`. Alarm should be canceled without
+ * retry, because alarm state has changed such that the requested alarm time is
+ * no longer valid.
+ */
+export type CancelAlarmHandler = {
+    /** Caller should wait for this promise to complete before canceling. */
+    readonly waitBeforeCancel: Promise<void>;
+};
+/**
+ * ← the `kj::Own<void>` that `RunAlarmHandler` carries, whose disposer runs
+ * `maybeDeleteDeferredAlarm()`. Section 1's rule applies: a kj destructor
+ * becomes an explicit call, so the caller attaches `drop()` to the promise
+ * representing the handler's execution rather than a scope exit.
+ */
+export interface DeferredAlarmDeleter {
+    drop(): void;
+}
+/** ← `ActorCacheInterface::RunAlarmHandler`. Alarm should be run. */
+export type RunAlarmHandler = {
+    readonly deferredDelete: DeferredAlarmDeleter;
+};
+/** ← `kj::OneOf<CancelAlarmHandler, RunAlarmHandler>`. */
+export type ArmAlarmResult = {
+    readonly kind: "cancel";
+    readonly cancel: CancelAlarmHandler;
+} | {
+    readonly kind: "run";
+    readonly run: RunAlarmHandler;
+};
+/** ← `ActorCache::SHUTDOWN_ERROR_MESSAGE`, which `ActorSqlite::shutdown` reuses. */
+export declare const SHUTDOWN_ERROR_MESSAGE = "broken.ignored; jsg.Error: Durable Object storage is no longer accessible.";
+/**
+ * ← the message every unimplemented `ActorCacheInterface` PITR method throws.
+ * `ActorSqlite` overrides two of the four; the other two keep this.
+ */
+export declare const PITR_UNIMPLEMENTED_MESSAGE = "This Durable Object's storage back-end does not implement point-in-time recovery.";
+/** ← the message the three replication methods throw. */
+export declare const REPLICATION_UNIMPLEMENTED_MESSAGE = "This Durable Object's storage back-end does not support replication.";
+/**
+ * Common interface between the storage engine and a transaction on it.
+ *
+ * ← `ActorCacheOps`. Upstream's `list`/`listReverse` split exists because the
+ * two directions "require a subtly different implementation of pretty much the
+ * entire algorithm" in the cache; both are kept, because both are separate
+ * entry points a caller reaches.
+ */
+export interface ActorCacheOps {
+    get(key: Key, options: ReadOptions): Value | undefined;
+    getMultiple(keys: readonly Key[], options: ReadOptions): GetResultList;
+    getAlarm(options: ReadOptions): number | null;
+    list(begin: Key, end: Key | undefined, limit: number | undefined, options: ReadOptions): GetResultList;
+    listReverse(begin: Key, end: Key | undefined, limit: number | undefined, options: ReadOptions): GetResultList;
+    put(key: Key, value: Value, options: WriteOptions): void;
+    putMultiple(pairs: readonly KeyValuePair[], options: WriteOptions): void;
+    /** Returns whether the key was present. */
+    delete(key: Key, options: WriteOptions): boolean;
+    /** Returns how many of the keys were present. */
+    deleteMultiple(keys: readonly Key[], options: WriteOptions): number;
+    setAlarm(newAlarmTime: number | null, options: WriteOptions): void;
+}
+/**
+ * ← `ActorCacheInterface::Transaction`.
+ *
+ * "If commit() is not called before the Transaction is destroyed, nothing is
+ * written." JS has no destruction, so `drop()` is that moment and exactly one of
+ * `commit()`/`rollback()`+`drop()` has to run — the same contract Section 1
+ * established for `Lock` and `CriticalSection`.
+ */
+export interface ActorCacheTransaction extends ActorCacheOps {
+    /**
+     * Write all changes to the underlying storage.
+     *
+     * "This will NOT detect conflicts, it will always just write blindly, because
+     * conflicts inherently cannot happen."
+     */
+    commit(): void;
+    rollback(): void;
+    /** ← `~ExplicitTxn`: roll back if not committed, then leave the txn stack. */
+    drop(): void;
+}
+/**
+ * Abstract interface that upstream implements twice, and that this package
+ * implements once — `ActorSqlite` is the sole implementation, exactly as on
+ * workerd-with-SQLite.
+ */
+export interface ActorCacheInterface extends ActorCacheOps {
+    startTransaction(): ActorCacheTransaction;
+    deleteAll(options: WriteOptions, deleteAllOptions?: DeleteAllOptions): DeleteAllResults;
+    /**
+     * "Call each time the isolate lock is taken to evict stale entries." There is
+     * no cache to evict from and never any backpressure to apply.
+     */
+    evictStale(now: number): undefined;
+    shutdown(exception?: unknown): void;
+    armAlarmHandler(scheduledTime: number, currentTime: number): ArmAlarmResult;
+    cancelDeferredAlarmDeletion(): void;
+    abandonAlarm(scheduledTime: number): Promise<number | null>;
+    /** Implements `sync()`. */
+    onNoPendingFlush(): Promise<void>;
+    getCurrentBookmark(): Promise<string>;
+    getBookmarkForTime(timestamp: number): Promise<string>;
+    onNextSessionRestoreBookmark(bookmark: string): Promise<string>;
+    waitForBookmark(bookmark: string): Promise<void>;
+    ensureReplicas(): void;
+    disableReplicas(): void;
+    configureReadReplication(enabled: boolean): Promise<void>;
+}

package/dist/src/io/actor-id.d.ts

@@ -0,0 +1,74 @@
+/**
+ * ← workerd `src/workerd/io/actor-id.h` (74 lines, header-only — there is no
+ * `actor-id.c++`).
+ *
+ * `api/actor.h` includes this file directly, and every type in it is named by
+ * `api/actor.{h,c++}`: `ActorIdFactory` is `DurableObjectNamespace`'s member,
+ * `ActorIdFactory::ActorId` is what a `DurableObjectId` wraps, and
+ * `ActorGetMode` / `ActorRoutingMode` / `ActorVersion` are the three parameters
+ * `getImpl` computes before handing them to an outgoing factory. Per the
+ * package README's rule for a legitimate upstream include crossing a wall, the
+ * reference widens to match upstream rather than the declarations being
+ * relocated into `api/`.
+ *
+ * The whole file is ported. What is NOT here is the **implementation** —
+ * upstream's is `server/actor-id-impl.{h,c++}`, a keyed SHA-256 construction —
+ * because it is `server/`'s and because a faithful port of it needs a
+ * synchronous digest, which the browser does not expose (`crypto.subtle` is
+ * asynchronous and every method below is synchronous). That is Section 6's
+ * problem to solve, and this interface is the seam it fills.
+ *
+ * Spec: §1.10 in docs/decisions.md.
+ */
+/**
+ * ← `ActorGetMode`. "Behavior mode for getting an actor."
+ *
+ * A union of the upstream enumerator names rather than a TypeScript `enum`,
+ * which is the shape every other discriminant in this package already takes.
+ */
+export type ActorGetMode = "GET_OR_CREATE" | "GET_EXISTING";
+/** ← `ActorRoutingMode`. "Routing mode for actor requests when replicas are available." */
+export type ActorRoutingMode = "DEFAULT" | "PRIMARY_ONLY";
+/** ← `ActorVersion`. "Version information for an actor. Used to specify cohort." */
+export type ActorVersion = {
+    readonly cohort?: string;
+};
+/**
+ * ← `ActorIdFactory::ActorId`. "Abstract actor ID."
+ *
+ * Upstream's comment, kept because it is the reason this is an interface rather
+ * than a class: "This is NOT an I/O type. An ActorId created in one IoContext
+ * can be used in other IoContexts."
+ *
+ * `clone()` is dropped: it exists so a `kj::Own<ActorId>` can be copied out of a
+ * borrowed reference, and a JS value needs no such thing. Every upstream call
+ * site (`DurableObjectId`'s constructor, `cloneId()`, the facet start info) is
+ * satisfied by passing the same object.
+ */
+export interface ActorId {
+    /** "Get the string that could be passed to `idFromString()` to recreate this ID." */
+    toString(): string;
+    /**
+     * "If the ActorId was created using `idFromName()`, return a copy of the name
+     * that was passed to it. Otherwise, returns null."
+     */
+    getName(): string | undefined;
+    /** "Get the jurisdiction that was used when creating this ID." */
+    getJurisdiction(): string | undefined;
+    /**
+     * "Compare with another ID. This is allowed to assume the other ID was created
+     * by some other ActorIdFactory passed to one of the worker's other bindings."
+     */
+    equals(other: ActorId): boolean;
+}
+/**
+ * ← `ActorIdFactory`. "An abstract class that implements generation of global
+ * actor IDs in a particular namespace."
+ */
+export interface ActorIdFactory {
+    newUniqueId(jurisdiction: string | undefined): ActorId;
+    idFromName(name: string): ActorId;
+    idFromString(str: string): ActorId;
+    matchesJurisdiction(id: ActorId): boolean;
+    cloneWithJurisdiction(maybeJurisdiction: string | undefined): ActorIdFactory;
+}

package/dist/src/io/actor-sqlite.d.ts

@@ -0,0 +1,298 @@
+/**
+ * ← workerd `src/workerd/io/actor-sqlite.{h,c++}`
+ *
+ * The storage engine. Owns:
+ *  - implicit transactions, bounded by GATE RELEASE rather than by an
+ *    event-loop turn (§1.7.1 — measured; a storage await does not end the
+ *    transaction, a timer or outbound await does);
+ *  - `onWrite` taking the output-gate lock at the first must-confirm write,
+ *    one lock per flush batch;
+ *  - `transactionSync` as SAVEPOINT/RELEASE/ROLLBACK TO with a depth counter,
+ *    plus the async-callback guard today's version lacks;
+ *  - alarm arm/consume/deferred-deletion, and `deleteAll`.
+ *
+ * Sole `ActorCacheInterface` implementation, exactly as on workerd-with-SQLite.
+ *
+ * The single most important constraint in the whole port lives here: the
+ * transaction boundary and the gate boundary are the same line. Implement them
+ * as one mechanism. Release at every await — the naive reading of §1.2 — and
+ * every multi-statement write silently loses atomicity, with nothing failing
+ * until a crash lands between two statements that were meant to be one.
+ *
+ * **How that one line is drawn here, since it is the question the design record
+ * left open.** Upstream needs no gate hook: `startImplicitTxn` wraps the commit
+ * in `kj::evalLater`, which runs it on the next turn of the KJ event loop, and
+ * the next KJ turn is by construction after the isolate run — which is after
+ * `js.runMicrotasks()`, which is after `KJ_DEFER` clears `currentInputLock`.
+ * "Next turn" and "gate release" are one boundary upstream, so `ActorSqlite`
+ * hangs the commit on the cheaper of the two. They are one boundary here for the
+ * same reason, provided the commit rides `atCheckpointEnd` — the primitive
+ * `io-context.ts` releases on. Its comment carries the proof; the short form is
+ * that holding the lock across an await is a pure microtask chain and releasing
+ * it always costs a hand-off, so no write can cross a hand-off inside one
+ * transaction and no two events can share one. `IoContext` therefore grows no
+ * per-invocation exit notification, and the root gate's `inputGateReleased` hook
+ * is *not* the right edge: it fires when `lockCount` hits zero, which never
+ * happens inside a critical section, so decision 4's fifteen boot phases would
+ * become a single transaction nobody chose.
+ *
+ * `onWrite` and `onCriticalError` are `SqliteDatabase`'s, in `util/sqlite.ts`,
+ * exactly as upstream has them, and the constructor binds itself to both the way
+ * `ActorSqlite`'s does. What is ours is only the substitute for the question
+ * upstream answers with `sqlite3_stmt_readonly()` — see `isWrite` there.
+ *
+ * Not ported, because the substrate has no equivalent to port onto: `SpanParent`
+ * tracing, already a Section 1 divergence, so every `traceSpan` parameter and
+ * `currentCommitSpan` with it; `debugAlarmSync` and every `LOG_*`, which are a
+ * logger this package does not have; and `TxnCommitRegulator::onError`, which
+ * re-reports `SQLITE_CONSTRAINT` during commit as a user-visible error — error
+ * codes do not cross the backend seam, the same reason Section 3 dropped
+ * `SqliteKvRegulator::onError`.
+ *
+ * Spec: §1.4, §1.7, §1.7.1, §1.8, §2.4, §2.6, decisions 2, 5, 6 and 7 in
+ * docs/decisions.md.
+ */
+import type { ActorCacheInterface, ActorCacheTransaction, ArmAlarmResult, DeleteAllOptions, DeleteAllResults, GetResultList, Key, KeyValuePair, ReadOptions, Value, WriteOptions } from "./actor-cache.js";
+import type { OutputGate } from "./io-gate.js";
+import { SqliteKv } from "../util/sqlite-kv.js";
+import { SqliteDatabase } from "../util/sqlite.js";
+/**
+ * The alarm port — one outbound method, matching upstream's seam exactly.
+ *
+ * Everything else about alarms is runtime-internal: arm/consume semantics here,
+ * retry ladder and serialised delivery in `server/alarm-scheduler.ts`. Delivery
+ * comes back IN through `ActorContainer.deliverAlarm`, not through this port.
+ */
+export interface AlarmOutlet {
+    /**
+     * Must be durable before the returned promise resolves.
+     *
+     * `priorTask` is upstream's second parameter and is load bearing rather than
+     * decorative: "any work we must wait on prior to scheduling the new request,
+     * as of this writing, this would be the alarmLaterInFlight promise, which
+     * tracks any in-flight request to move the alarm 'later' than is currently
+     * set." An implementation that ignores it can send a move-earlier request
+     * concurrently with a move-later one and lose the ordering invariant that the
+     * scheduled alarm is always at or before the persisted one.
+     *
+     * May throw synchronously; `ActorSqlite` relies on it, because a scheduling
+     * failure has to reach the caller before the local database commits.
+     */
+    scheduleRun(newAlarmTime: number | null, priorTask: Promise<void>): Promise<void>;
+}
+/** ← `ActorSqlite::Hooks::DEFAULT`, whose `scheduleRun` refuses. */
+export declare const DEFAULT_ALARM_OUTLET: AlarmOutlet;
+/**
+ * ← `kj::TaskSet` plus its `ErrorHandler`. `ActorSqlite` owns one of its own,
+ * separate from `IoContext`'s, exactly as upstream does.
+ */
+declare class TaskSet {
+    #private;
+    constructor(taskFailed: (exception: unknown) => void);
+    add(promise: Promise<void>): void;
+}
+/** ← `kj::OneOf<NoTxn, ImplicitTxn*, ExplicitTxn*>`. */
+type CurrentTxn = {
+    readonly kind: "none";
+} | {
+    readonly kind: "implicit";
+    readonly txn: ImplicitTxn;
+} | {
+    readonly kind: "explicit";
+    readonly txn: ExplicitTxn;
+};
+/** ← `ActorSqlite::PrecommitAlarmState`. */
+type PrecommitAlarmState = {
+    /** Promise for the completion of precommit alarm scheduling */
+    schedulingPromise?: Promise<void>;
+};
+/**
+ * An implementation of ActorCacheOps that is backed by SqliteKv.
+ *
+ * Constructing one arranges to honor the output gate, that is, any writes to the
+ * database which occur without any `await`s in between will automatically be
+ * combined into a single atomic write. This is accomplished using transactions.
+ * In addition to ensuring atomicity, this tends to improve performance, as
+ * SQLite is able to coalesce writes across statements that modify the same page.
+ *
+ * `commitCallback` will be invoked after committing a transaction. The output
+ * gate will block on the returned promise. This can be used e.g. when the
+ * database needs to be replicated to other machines before being considered
+ * durable.
+ *
+ * Members upstream marks `private` and reaches through `ImplicitTxn` and
+ * `ExplicitTxn`, which are nested classes with implicit friendship, are ordinary
+ * members here for the reason `io-gate.ts` gives: TypeScript has no friendship,
+ * and the boundary that actually holds is the package facade in `src/index.ts`.
+ */
+export declare class ActorSqlite implements ActorCacheInterface {
+    #private;
+    /** Upstream-private; reached by the two transaction classes. */
+    readonly db: SqliteDatabase;
+    /** Upstream-private; reached by the two transaction classes. */
+    readonly outputGate: OutputGate;
+    /** Upstream-private; reached by the two transaction classes. */
+    readonly commitTasks: TaskSet;
+    /** Upstream-private; the transaction classes read it to skip their rollback. */
+    broken: unknown | undefined;
+    /**
+     * When set to `none`, there is no transaction outstanding.
+     *
+     * When set to an `ImplicitTxn`, an implicit transaction is currently open,
+     * owned by `commitTasks`. If there is a need to commit this early, e.g. to
+     * start an explicit transaction, that can be done through this reference.
+     *
+     * When set to an `ExplicitTxn`, an explicit transaction is currently open, so
+     * no implicit transactions should be used in the meantime.
+     */
+    currentTxn: CurrentTxn;
+    /**
+     * State for tracking completion of all commits (both confirmed and
+     * unconfirmed) for implementing sync() in onNoPendingFlush.
+     *
+     * Upstream-private; `ExplicitTxn::commit` replaces it.
+     */
+    lastCommit: Promise<void>;
+    /**
+     * We need to track some additional alarm state to guarantee at-least-once
+     * alarm delivery: within an alarm handler, we want the observable alarm state
+     * to look like the running alarm was deleted at the start of the handler (when
+     * armAlarmHandler() is called), but we don't actually want to persist that
+     * deletion until after the handler has successfully completed.
+     *
+     * Upstream-private; `ExplicitTxn::commit` clears it when the txn was alarm-dirty.
+     */
+    haveDeferredDelete: boolean;
+    constructor(db: SqliteDatabase, outputGate: OutputGate, commitCallback: () => Promise<void>, hooks?: AlarmOutlet);
+    isCommitScheduled(): boolean;
+    getSqliteDatabase(): SqliteDatabase;
+    getSqliteKv(): SqliteKv;
+    /**
+     * To be called just before committing the local sqlite db, to synchronously
+     * start any necessary alarm scheduling.
+     *
+     * Upstream-private; `ExplicitTxn::commit` calls it for the root transaction.
+     */
+    startPrecommitAlarmScheduling(): PrecommitAlarmState;
+    /**
+     * Performs the rest of the asynchronous commit, to be waited on after
+     * committing the local sqlite db. Should be called in the same turn of the
+     * event loop as startPrecommitAlarmScheduling() and passed the state that it
+     * returned.
+     *
+     * Upstream-private; `ExplicitTxn::commit` calls it for the root transaction.
+     */
+    commitImpl(precommitAlarmState: PrecommitAlarmState): Promise<void>;
+    /** Upstream-private; the transaction classes call it before touching the db. */
+    requireNotBroken(): void;
+    get(key: Key, _options?: ReadOptions): Value | undefined;
+    getMultiple(keys: readonly Key[], _options?: ReadOptions): GetResultList;
+    getAlarm(_options?: ReadOptions): number | null;
+    list(begin: Key, end: Key | undefined, limit: number | undefined, _options?: ReadOptions): GetResultList;
+    listReverse(begin: Key, end: Key | undefined, limit: number | undefined, _options?: ReadOptions): GetResultList;
+    put(key: Key, value: Value, options?: WriteOptions): void;
+    putMultiple(pairs: readonly KeyValuePair[], options?: WriteOptions): void;
+    delete(key: Key, options?: WriteOptions): boolean;
+    deleteMultiple(keys: readonly Key[], options?: WriteOptions): number;
+    setAlarm(newAlarmTime: number | null, options?: WriteOptions): void;
+    startTransaction(): ActorCacheTransaction;
+    deleteAll(options?: WriteOptions, deleteAllOptions?: DeleteAllOptions): DeleteAllResults;
+    evictStale(_now: number): undefined;
+    shutdown(exception?: unknown): void;
+    armAlarmHandler(scheduledTime: number, currentTime: number): ArmAlarmResult;
+    cancelDeferredAlarmDeletion(): void;
+    abandonAlarm(scheduledTime: number): Promise<number | null>;
+    /**
+     * This implements sync().
+     *
+     * sync() should wait for ALL writes (both confirmed and unconfirmed) that are
+     * outstanding at the time sync() is called. We use lastCommit which keeps track
+     * of the most recent commit to be formed. We join with the outputGate because
+     * there are a lot of edge cases where we break the output gate and it's easiest
+     * to catch all of those instances here rather than updating everything to also
+     * break lastCommit.
+     */
+    onNoPendingFlush(): Promise<void>;
+    /**
+     * This is an ersatz implementation that's good enough for local dev with D1's
+     * Session API.
+     *
+     * The returned bookmark satisfies the properties that D1 cares about:
+     *
+     * * Later bookmarks sort after earlier bookmarks. We implement this by
+     *   incrementing the bookmark whenever getCurrentBookmark() is called.
+     *
+     * * Bookmarks from the current session sort after bookmarks from previous
+     *   sessions. We implement this by saving an ersatz bookmark in the metadata
+     *   table.
+     *
+     * This is NOT the point-in-time-recovery bookmark API, which is a substrate
+     * boundary: it needs nothing the substrate lacks, which is exactly why Section
+     * 3 ported `getLocalDevelopmentBookmark`/`setLocalDevelopmentBookmark`.
+     */
+    getCurrentBookmark(): Promise<string>;
+    waitForBookmark(_bookmark: string): Promise<void>;
+    getBookmarkForTime(_timestamp: number): Promise<string>;
+    onNextSessionRestoreBookmark(_bookmark: string): Promise<string>;
+    ensureReplicas(): void;
+    disableReplicas(): void;
+    configureReadReplication(_enabled: boolean): Promise<void>;
+    /**
+     * ← `DurableObjectStorage::transactionSync` (`actor-state.c++:713-753`).
+     *
+     * One layer lower than upstream, which is where `util/sqlite.ts` already
+     * records it belongs: the savepoint depth counter and `notifyWrite` both live
+     * here, and `api/actor-state.ts`'s `transactionSync` becomes a one-line forward
+     * the way `blockConcurrencyWhile` already is.
+     *
+     * The nesting guard §2.4 asks for is upstream's own and is the depth-named
+     * savepoint: a second `BEGIN IMMEDIATE` is a SQLite error, a nested SAVEPOINT
+     * is not, which is why this issues savepoints and lets the implicit transaction
+     * underneath be the only `BEGIN`.
+     *
+     * The async-callback guard is ours and has no upstream twin, because upstream's
+     * `jsg::Function<jsg::JsRef<jsg::JsValue>()>` callback cannot be awaited at
+     * all: it returns a value, and a JS function that returns a promise simply has
+     * its promise ignored. Here the same mistake is silent and corrupting — the
+     * RELEASE fires at the first await and everything after it lands outside the
+     * transaction — so a thenable result is refused and the savepoint rolled back.
+     * Work the callback already started is not cancellable and keeps running; the
+     * throw is what stops it being mistaken for transactional.
+     */
+    transactionSync<T>(callback: () => T): T;
+}
+/** ← `ActorSqlite::ImplicitTxn`. */
+declare class ImplicitTxn {
+    #private;
+    constructor(parent: ActorSqlite);
+    commit(): void;
+    rollback(): void;
+    setSomeWriteConfirmed(someWriteConfirmed: boolean): void;
+    isSomeWriteConfirmed(): boolean;
+    /** ← `~ImplicitTxn`. Idempotent, because the commit path drops before and after the callback. */
+    drop(): void;
+}
+/** ← `ActorSqlite::ExplicitTxn`. */
+declare class ExplicitTxn implements ActorCacheTransaction {
+    #private;
+    constructor(actorSqlite: ActorSqlite);
+    getAlarmDirty(): boolean;
+    setAlarmDirty(): void;
+    setSomeWriteConfirmed(someWriteConfirmed: boolean): void;
+    isSomeWriteConfirmed(): boolean;
+    commit(): void;
+    rollback(): void;
+    /** ← `~ExplicitTxn`. */
+    drop(): void;
+    get(key: Key, options?: ReadOptions): Value | undefined;
+    getMultiple(keys: readonly Key[], options?: ReadOptions): GetResultList;
+    getAlarm(options?: ReadOptions): number | null;
+    list(begin: Key, end: Key | undefined, limit: number | undefined, options?: ReadOptions): GetResultList;
+    listReverse(begin: Key, end: Key | undefined, limit: number | undefined, options?: ReadOptions): GetResultList;
+    put(key: Key, value: Value, options?: WriteOptions): void;
+    putMultiple(pairs: readonly KeyValuePair[], options?: WriteOptions): void;
+    delete(key: Key, options?: WriteOptions): boolean;
+    deleteMultiple(keys: readonly Key[], options?: WriteOptions): number;
+    setAlarm(newAlarmTime: number | null, options?: WriteOptions): void;
+}
+export {};