@helipod/runtime-embedded 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,722 @@
+import * as _helipod_docstore_d1 from '@helipod/docstore-d1';
+import { WakeHost, Driver } from '@helipod/component';
+import { ShardId } from '@helipod/id-codec';
+import { SerializedKeyRange } from '@helipod/index-key-codec';
+import { JSONValue } from '@helipod/values';
+import { CommitGuardUnit, DocStore } from '@helipod/docstore';
+import { InlineUdfExecutor, IndexCatalog, RegisteredFunction, LogSink, ContextProvider, TablePolicy, PolicyContextProvider, RelationRegistry, GuestDatabaseWriter, WriteRouter, UdfResult } from '@helipod/executor';
+export { ClientReplay, WriteRouter } from '@helipod/executor';
+import { ClientMessage, ServerMessage, SyncWebSocket, SyncProtocolHandler } from '@helipod/sync';
+import { WrittenDoc, WriteFanout, OplogDelta } from '@helipod/transactor';
+
+/**
+ * The transactor→sync fan-out seam (scale-seam #4). A committed `OplogDelta` is published as
+ * a fully-serializable payload to a swappable `EmbeddedWriteFanoutAdapter`. At Tier 0 the
+ * adapter is in-memory; swap it for BroadcastChannel / Redis / Queues and the SAME fan-out
+ * spans many processes — with no change to app code. Each fan-out tags its `originId` so a
+ * subscriber can ignore its own writes (avoiding a self-loop across processes).
+ */
+
+interface EmbeddedWriteFanoutPayload {
+    commitTs: number;
+    tables: string[];
+    ranges: SerializedKeyRange[];
+    originId: string;
+    /**
+     * G4 origin-frontier tag (client-sync verdict §(d) item 2) — the originating sync SESSION id,
+     * sourced verbatim from `OplogDelta.origin`. Distinct from `originId` (the fleet-node/process
+     * origin used for the cross-process self-loop guard): this is a per-commit ephemeral session tag
+     * the drain hands to `handler.notifyWrites(inv, origin)` so the origin session's `version.ts` is
+     * advanced past its own commit. Undefined for commits with no originating session.
+     */
+    origin?: string;
+    /** The shard this commit landed on (Fenced Frontier B1, D6) — sourced verbatim from
+     *  `OplogDelta.shardId`. Additive: single-shard (Tier 0/B1) deployments always see `"default"`
+     *  (`DEFAULT_SHARD`); a multi-shard fan-out consumer (B2+) can use it to route/filter, but every
+     *  existing consumer today ignores it. */
+    shardId: string;
+    /** Written documents for local row-diffing (§DLR 2a) — sourced verbatim from
+     *  `OplogDelta.writtenDocs`. Present only on the local in-process fan-out (this adapter always
+     *  runs in-process at Tier 0/1); absent if a future cross-process adapter swap doesn't carry it. */
+    writtenDocs?: WrittenDoc[];
+}
+type FanoutListener = (payload: EmbeddedWriteFanoutPayload) => void;
+interface EmbeddedWriteFanoutAdapter {
+    publish(payload: EmbeddedWriteFanoutPayload): void;
+    subscribe(listener: FanoutListener): () => void;
+}
+/** The default Tier 0 adapter: an in-process channel (also records what it published). */
+declare class InMemoryWriteFanoutAdapter implements EmbeddedWriteFanoutAdapter {
+    private readonly listeners;
+    readonly published: EmbeddedWriteFanoutPayload[];
+    publish(payload: EmbeddedWriteFanoutPayload): void;
+    subscribe(listener: FanoutListener): () => void;
+}
+/** Implements the transactor's `WriteFanout` over a swappable adapter. */
+declare class EmbeddedWriteFanout implements WriteFanout {
+    private readonly adapter;
+    private readonly originId;
+    constructor(adapter: EmbeddedWriteFanoutAdapter, originId: string);
+    publish(delta: OplogDelta): void;
+    /** Subscribe to deltas from OTHER origins (ignores our own — the Tier 2 self-loop guard). */
+    subscribe(listener: FanoutListener): () => void;
+}
+
+/**
+ * In-memory loopback transport. A `LoopbackConnection` is the client end of an in-process
+ * "WebSocket": `send` delivers a client message straight to the sync handler, and the
+ * handler's server-side socket delivers messages straight back to the connection's
+ * listeners. No sockets, no serialization-over-the-wire — but the EXACT same `SyncWebSocket`
+ * the handler talks to, so a real WebSocket transport drops in unchanged at Tier 2.
+ */
+
+type ServerMessageListener = (msg: ServerMessage) => void;
+interface LoopbackConnection {
+    readonly sessionId: string;
+    /** Client → server. Resolves once the handler has finished processing (loopback is synchronous). */
+    send(message: ClientMessage | string): Promise<void>;
+    /** Register a server → client listener; returns an unsubscribe. */
+    onMessage(listener: ServerMessageListener): () => void;
+    close(): void;
+}
+interface LoopbackHandler {
+    connect(sessionId: string, socket: SyncWebSocket): void;
+    disconnect(sessionId: string): void;
+    handleMessage(sessionId: string, raw: string): Promise<void>;
+}
+declare function createLoopbackConnection(handler: LoopbackHandler, sessionId: string): LoopbackConnection;
+
+/** The durable per-tab dedup key threaded from the wire (`Mutation.clientId`/`seq`). */
+interface DedupKey {
+    clientId: string;
+    seq: number;
+}
+/**
+ * The `applied`-receipt commit guard (registered ONCE at runtime construction, BEFORE fleet's epoch
+ * fence — verdict §(c) Risk R6). For every unit whose `meta` carries a dedup key, INSERTs the
+ * `client_mutations` receipt at that unit's own `ts`, inside the mutation's commit transaction. The
+ * INSERT is PLAIN (never `ON CONFLICT DO NOTHING`): a PK collision IS the dedup signal — it means a
+ * concurrent duplicate already committed this seq, so we throw a typed {@link CommitGuardRejection}
+ * (`CLIENT_MUTATION_DUP`) carrying this unit's index. On the single-commit path it propagates as this
+ * mutation's own rejection (the caller replay-reads the winner); under group commit the transactor's
+ * split-retry rejects ONLY this unit and re-flushes the innocent remainder. A unit with no dedup key
+ * (every ordinary mutation) is skipped — the whole guard costs a deployment nothing until the outbox
+ * is used.
+ *
+ * Store-agnostic by querier shape (verdict Risk R9 — the guard is ONE closure, not two): a Postgres
+ * `PgQuerier` exposes async `query()`; a `SqliteGuardQuerier` exposes synchronous `run()`. The SQLite
+ * branch runs fully synchronously and returns `undefined` (void) — it MUST, because SQLite's commit
+ * is one synchronous transaction that cannot await a guard (a returned thenable there is a dev-time
+ * error). The Postgres branch returns a Promise the async `commitWriteBatch` awaits.
+ */
+declare function clientReceiptsGuard(): (q: unknown, units: readonly CommitGuardUnit[], shardId: ShardId) => void | Promise<void>;
+
+interface EmbeddedRuntimeOptions {
+    store: DocStore;
+    catalog: IndexCatalog;
+    modules: Record<string, RegisteredFunction>;
+    /** Privileged built-in functions (`_system:*`). Kept off the public run/sync surface. */
+    systemModules?: Record<string, RegisteredFunction>;
+    /** Privileged admin functions (`_admin:*`). Served over the admin sync channel. */
+    adminModules?: Record<string, RegisteredFunction>;
+    /** Validate an admin key presented via `SetAdminAuth`. Defaults to `() => false`. */
+    verifyAdmin?: (key: string) => boolean;
+    /** Set of component names; used to resolve the namespace for each function path. */
+    componentNames?: ReadonlySet<string>;
+    /** Swap the Tier 0 in-memory fan-out for a cross-process adapter (no app-code change). */
+    fanoutAdapter?: EmbeddedWriteFanoutAdapter;
+    originId?: string;
+    logSink?: LogSink;
+    /** Context providers contributed by composed components; attached as ctx[name] on every function call. */
+    contextProviders?: ReadonlyArray<ContextProvider>;
+    /** Row-policy registry contributed by components; enforced on every non-privileged run. */
+    policyRegistry?: ReadonlyMap<string, TablePolicy>;
+    /** Policy context providers contributed by components; used to build rule context for row policies. */
+    policyProviders?: ReadonlyArray<PolicyContextProvider>;
+    /** Declared relations, consulted by the kernel when resolving relation predicates. */
+    relationRegistry?: RelationRegistry;
+    /** Wall-clock source; defaults to `Date.now`. Injected for deterministic testing. */
+    now?: () => number;
+    /**
+     * The host's single alarm, for a host that STOPS THE PROCESS between requests (Cloudflare
+     * Containers: stopped ~5s after the last incoming request; internal timer activity does not keep
+     * it alive, so `setTimeout` silently never fires and every driver goes dead). Set → this runtime
+     * multiplexes every live driver timer down to ONE pending wake and hands the minimum to
+     * `armWake`; the host is then the SOLE thing that fires them, via `fireDueTimers()` (the engine
+     * arms no `setTimeout` of its own — two schedulers would double-fire the same callback).
+     *
+     * UNSET (the default, and every existing deployment — Docker/VPS/Fly/Railway/single-binary): the
+     * plain `setTimeout` path below, byte-for-byte unchanged.
+     */
+    wakeHost?: WakeHost;
+    /**
+     * Answers `DriverContext.backstopMs` — a driver's declared cadence for a PURE BACKSTOP poll
+     * (scheduler lease-reclaim sweep, triggers beat, storage reaper). Defaults to IDENTITY (the
+     * driver's own 30s/60s constants, unchanged). A host where every wake costs a cold start stretches
+     * it: on Cloudflare a 30s backstop is a container boot every 30s forever — a ~15% duty cycle for a
+     * completely idle app, which would destroy scale-to-zero.
+     */
+    backstopMs?: (defaultMs: number) => number;
+    /**
+     * Disarm the sync handler's process-shaped background timers (its `setInterval` flush/resume sweep
+     * and every per-session ping heartbeat). Defaults to `false` — every long-lived process host is
+     * byte-for-byte unchanged. Set ONLY by the Cloudflare Durable Object host (Slice 3), where those
+     * timers are actively harmful (a `setInterval` is lost on hibernation; an app-level ping would wake
+     * the hibernated object every beat, defeating scale-to-zero). Just a boolean — no host type crosses
+     * this seam. See `SyncProtocolHandlerOptions.disableBackgroundTimers`.
+     */
+    disableSyncBackgroundTimers?: boolean;
+    /** Component boot steps to run once at create, namespaced + non-user (before serving traffic). */
+    bootSteps?: {
+        name: string;
+        run: (ctx: {
+            db: GuestDatabaseWriter;
+            now: number;
+        }) => Promise<void>;
+    }[];
+    /** Component drivers to start once at create, after boot steps + the commit fan-out are wired. */
+    drivers?: Driver[];
+    /**
+     * `fullTableName → tableNumber` (the same map `composeComponents`/`loadProject` produce).
+     * Used ONLY to translate the encoded storage-table ids on `adapter.subscribe`'s commit payload
+     * (e.g. `"3"`) back into full names (e.g. `"scheduler/jobs"`) before handing them to driver
+     * `onCommit` callbacks — drivers filter `inv.tables` by name (see `components/scheduler/src/
+     * driver.ts`), and a raw storage id never matches. Optional: a runtime with no components (or
+     * whose drivers don't inspect `inv.tables`) can omit it and driver callbacks just see raw ids.
+     */
+    tableNumbers?: Record<string, number>;
+    /**
+     * Route mutations/actions to another node instead of executing them locally, when
+     * `writeRouter.isLocalWriter()` is false. Applies to EVERY mutation/action entry point (the
+     * WS `syncExecutor.runMutation`/`runAction` and the public `run`/`runAction` methods) —
+     * queries are never routed. See `WriteRouter`.
+     */
+    writeRouter?: WriteRouter;
+    /**
+     * Skip starting component drivers at `create()` time; call the returned instance's
+     * `startDrivers()` later instead. For a fleet node that boots as a non-writer and only
+     * wants drivers running once/if it becomes the writer.
+     */
+    deferDrivers?: boolean;
+    /**
+     * Receipted Outbox — receipts-guard ownership handoff (the promotion-barrier hole). Normally
+     * `create()` registers the `clientReceiptsGuard()` exactly-once barrier on `options.store` here at
+     * construction, because for every non-fleet deployment `options.store` IS the concrete store its
+     * commits land on. A fleet SYNC node is the exception: `options.store` is a `SwitchableDocStore`
+     * over the read-only replica, and on writer promotion the runtime store is swapped to the concrete
+     * Postgres store WITHOUT re-forwarding registered commit guards (by `SwitchableDocStore`'s
+     * documented design) — so a guard registered here would silently vanish on promotion, and a
+     * promoted single-writer node's client mutations would commit with NO receipt (dedup miss → a
+     * resent (clientId, seq) re-executes). When this is set, `create()` SKIPS its own registration and
+     * the caller (fleet's `armWriter`) owns installing the receipts guard on the CONCRETE write store —
+     * BEFORE the epoch fence, with the same release-on-re-arm discipline the fence uses. Ownership rule:
+     * whoever owns the concrete store owns the receipts guard. Unset → the runtime owns it (today's
+     * behavior, byte-identical for every non-fleet deployment). See `ee/fleet`'s `armWriter`.
+     */
+    externalReceiptsGuard?: boolean;
+    /**
+     * Number of shards to run (Shards B2a). When `> 1`, the runtime builds ONE `ShardedTransactor`
+     * (N independent per-shard mutexes + OCC rings + oracles) over the store instead of the
+     * single-shard `SingleWriterTransactor`, so mutations routed to different shards commit in
+     * parallel. Unset / `1` → the single-shard transactor, byte-identical to before (the existing
+     * suites are the proof). The executor resolves each mutation's shard (`shardBy`) and passes it
+     * through `runInTransaction({ shardId })`; a fleet writer pairs this with the per-shard commit
+     * pool so different shards' commits are genuinely concurrent Postgres transactions.
+     */
+    numShards?: number;
+    /**
+     * Fleet B4 (group commit): route commits through the two-buffer stage-then-flush committer loop
+     * instead of the byte-identical single-commit path. Threaded straight into the transactor
+     * (`ShardedTransactor`/`SingleWriterTransactor`) constructed below — every shard batches when this
+     * is set, none do when it's unset/false. The CLI resolves this from `HELIPOD_GROUP_COMMIT`
+     * (default OFF at Fleet B4/T4 — T5 owns flipping the production default); leaving it unset keeps a
+     * non-fleet / flag-off deployment structurally on today's path, byte-identical to before this
+     * option existed. See `ShardedTransactorOptions.groupCommit`'s doc comment for the mechanism.
+     */
+    groupCommit?: boolean;
+    /**
+     * Hybrid-node split-read seam (Fleet B3, D1). When set, `create()` builds a SECOND, separate
+     * query-path transactor (`SingleWriterTransactor` — queries never commit, so no sharding is
+     * needed here regardless of the write side) + `QueryRuntime` over this store, seeded from ITS
+     * OWN `maxTimestamp()` (not the write store's) and wired onto `ExecutorDeps.queryPath`, so
+     * `fn.type === "query"` runs against `queryStore` instead of `store`. Its oracle is advanced
+     * ONLY by `observeTimestamp` (see below) — never by this runtime's own local commits, which
+     * only ever land on the WRITE store. Unset → `queryPath` is never built; every query runs
+     * against `store` through the primary pair, byte-identical to before this option existed.
+     */
+    queryStore?: DocStore;
+    /**
+     * M2b: the D1 store for `.global()` tables, pre-built by the boot layer (which holds
+     * `schemaJson`). Mirrors the `queryStore` precedent above — handed in already-constructed,
+     * not built inside `create()`. Threaded straight into `ExecutorDeps.globalStore`. Absent →
+     * `.global()` ops fail fast in the kernel (`requireGlobalTxn`), byte-identical to before this
+     * option existed. NOT `DocStore`-shaped; it never enters a transactor/`QueryRuntime`.
+     */
+    globalStore?: _helipod_docstore_d1.D1DocStore;
+    /**
+     * The AUTHORITATIVE receipts store for the `Connect` resume handshake — where the outbox verdict
+     * classification (`classifyClientMutation`) and ack-prune (`pruneClientMutations`) reads/writes
+     * land (verdict §(c): "the classification read runs where the commit runs... never against a
+     * follower's embedded replica"). The `client_mutations`/`client_floors` receipts tables are NOT
+     * part of the replicated MVCC document log — they live ONLY on the authoritative primary. On a
+     * fleet SYNC node, `options.store` is a `SwitchableDocStore` over the read-only replica, which
+     * carries NONE of those receipts: classifying a committed seq there returns `unknown` for every
+     * lookup, so the handshake spuriously reports `known:false` (a reset that re-mints the clientId)
+     * and — worse — a kill-after-commit reload via a sync node reports a FALSE failure for a mutation
+     * that actually committed. Set this to the primary Postgres store so the handshake reads/prunes the
+     * real receipts. Safe from a read-only-until-promoted primary: `getClientVerdict` is a pure read
+     * and `pruneClientMutations` is a monotonic (`GREATEST`-floored) direct query on standalone,
+     * unsharded receipt tables — architecturally identical to what the WRITER's own handshake does
+     * outside the OCC transactor, needing no advisory lock or write-forward hop. Unset → the handshake
+     * uses `options.store` (byte-identical for every non-fleet/writer deployment, whose `store` IS the
+     * primary; the mutation-path dedup already places its own classification on the owner via
+     * `writeRouter`, so only the Connect handshake needed this seam). See `ee/fleet`'s sync boot.
+     */
+    receiptsStore?: DocStore;
+    /**
+     * Hybrid-node RYOW gate (Fleet B3, D2). Awaited in the runtime's serial fan-out `drain()`
+     * BEFORE each queued invalidation's `handler.notifyWrites` — e.g. a hybrid node's
+     * `tailer.waitFor(commitTs)`, so a locally-committed mutation's subscription re-runs don't fire
+     * against a replica that hasn't applied that commit yet. A rejection is caught and logged; the
+     * drain loop continues to the next queued invalidation rather than wedging the whole queue on
+     * one bad wait. Unset → `drain()` is byte-identical to before this hook existed.
+     */
+    beforeNotify?: (commitTs: bigint) => Promise<void>;
+    /**
+     * The stable-prefix accessor for `DriverContext.readLog` (triggers D1). Returns the highest log
+     * timestamp below which the log is GAP-FREE — the upper bound `readLog` scans to. Non-null ONLY in
+     * a fleet, where N per-shard commit connections land timestamps out of order (a scan can see ts 10
+     * while ts 9 is still in flight), so the bound must be `min(shard_leases.frontier_ts)` — the fleet
+     * node wires it to exactly that. A `null` return (or an unset accessor) means "no fleet gap": every
+     * non-fleet topology commits over one serialized session (SQLite's single connection; the single
+     * PINNED Postgres connection — the commit pool is fleet-only), so `readLog` falls back to
+     * `store.maxTimestamp()`. Consulted per `readLog` call; only ever invoked on the default-shard
+     * holder by the driver lifecycle.
+     */
+    stablePrefix?: () => Promise<bigint | null>;
+}
+declare class EmbeddedRuntime {
+    readonly store: DocStore;
+    readonly executor: InlineUdfExecutor;
+    readonly handler: SyncProtocolHandler;
+    readonly writeFanoutAdapter: EmbeddedWriteFanoutAdapter;
+    private readonly modules;
+    private readonly systemModules;
+    private readonly adminModules;
+    private readonly componentNames;
+    private readonly contextProviders;
+    private readonly policyRegistry;
+    private readonly policyProviders;
+    private readonly relationRegistry;
+    private readonly drivers;
+    private readonly timers;
+    /** Threaded from `create()` (like `driverCtx`) so the public `fireDueTimers()` below runs against
+     *  the SAME timer map + wake-arming closures the `DriverContext` writes to. */
+    private readonly fireDue;
+    /**
+     * Inverse of `tableNumbers` (tableNumber → fullTableName). Mutable (not `readonly`) so
+     * `setTableNumbers` can rebuild it in place after an additive deploy — the very same `Map`
+     * object `create()`'s `namesForCommit` closure captured, so mutating it here (rather than
+     * reassigning the field) keeps that closure correct without any circular-reference dance.
+     */
+    private tableNumberToName;
+    /** The WRITE transactor's timestamp observer (the single-shard oracle, or the
+     *  `ShardedTransactor` itself). `observeTimestamp` delegates to this UNLESS `queryOracle` is
+     *  set (see it below) — this oracle's own local commits always advance it directly via
+     *  `ShardWriter.commit`'s `oracle.publishCommitted`; `observeTimestamp` is the SEPARATE
+     *  fleet-follower/tailer-observation channel, which a hybrid node must NOT point back at the
+     *  write oracle (D1 — own local commits must never advance the query oracle, and observed
+     *  foreign timestamps must never advance the write oracle either, once a hybrid has a real
+     *  query-path oracle of its own). */
+    private readonly oracle;
+    /** Fleet B3 (D1): the QUERY-path oracle, set only when `EmbeddedRuntimeOptions.queryStore` was
+     *  configured. When set, `observeTimestamp` routes to THIS oracle instead of `oracle` — its
+     *  purpose is tailer post-apply feeding (a hybrid node's replica-backed query snapshot rises
+     *  only as the tailer confirms applied writes), never this runtime's own local commits (those
+     *  land on the write store and advance `oracle` directly, as shipped). Undefined when
+     *  `queryStore` is unset → `observeTimestamp` keeps the exact shipped write-oracle routing. */
+    private readonly queryOracle;
+    /** The write path — retained so a fleet writer can take a shard's commit mutex non-blockingly
+     *  (`tryRunExclusiveOnShard`) to close idle frontiers without racing that shard's own commits. */
+    private readonly transactor;
+    /** Threaded from `create()` so `startDrivers()` can start deferred drivers later. */
+    private readonly driverCtx;
+    /** Mutable: false when `deferDrivers` was set and `startDrivers()` hasn't run yet. */
+    private driversStarted;
+    /** When set and `isLocalWriter()` is false, every mutation/action entry point forwards
+     *  through it instead of executing locally. Queries never consult this. */
+    private readonly writeRouter;
+    /** Shards B2a (T5): the SAME resolved count `create()` used to build the transactor and every
+     *  closure's `RunOptions.numShards` — instance methods (`run`/`runAction`/`runHttpAction`/
+     *  `runSystem`/`runAdmin`) thread it through here so a call made AFTER construction routes
+     *  identically to one made during `create()`. Defaults to 1 (byte-identical to before) when
+     *  `EmbeddedRuntimeOptions.numShards` is unset. */
+    private readonly numShards;
+    /** The SAME catalog the executor/kernel enforce ownership against — so `runSystem`'s privileged
+     *  doc-mutation routing (`resolveDocMutationShard`) reads a table's `shardKey` from the exact
+     *  source of truth the guards use, and can never disagree with them. */
+    private readonly catalog;
+    /** The SAME `commitSubs` set `create()`'s `adapter.subscribe` callback fires on every LOCAL
+     *  commit — also fired by `notifyExternalCommit` (below) for a FOREIGN (fleet) commit, so a
+     *  driver's `onCommit` wakes on both without the two paths ever drifting on which set they
+     *  target. */
+    private readonly commitSubs;
+    private sessionCounter;
+    private constructor();
+    static create(options: EmbeddedRuntimeOptions): Promise<EmbeddedRuntime>;
+    /**
+     * Resolves a target path's REAL registered kind against the live `this.modules` map — same
+     * resolver shape as `create()`'s local `functionKind` closure, but bound to the instance so it
+     * stays correct across `setModules` hot-swaps. See `ComponentContext.functionKind`'s doc
+     * comment (packages/executor/src/executor.ts).
+     */
+    private functionKind;
+    /** Hot-swap the function map (dev reload) without disturbing the store/transactor. */
+    setModules(modules: Record<string, RegisteredFunction>): void;
+    /**
+     * Rebuild the tableNumber→name map after an additive deploy so driver commit fan-out
+     * (`namesForCommit` in `create()`, which closed over this same `Map` instance) keeps
+     * translating newly-added tables' encoded storage ids to their full names correctly.
+     * Additive deploys keep existing numbers, so this only ever adds entries in practice.
+     */
+    setTableNumbers(tableNumbers: Record<string, number>): void;
+    /**
+     * The FOREIGN-COMMIT driver wake for a multi-writer fleet hybrid (Fleet B3, trigger-wake gap
+     * fix). `commitSubs` (driver `onCommit` wakes) normally fires only from `create()`'s
+     * `adapter.subscribe` callback — the LOCAL commit fan-out. In an opt-in multi-writer fleet, a
+     * co-writer's commit reaches THIS node only through the hybrid-tailer `invalidationSink`
+     * (`ee/packages/fleet/src/node.ts`), which calls `handler.notifyWrites` directly — bypassing
+     * `adapter.subscribe` entirely, so a driver here (e.g. `@helipod/triggers`) never woke on a
+     * foreign writer's commit and instead slept up to its own wall-clock beat. Delivery was always
+     * guaranteed (the durable cursor over the log) — this is a LATENCY fix, not a correctness one.
+     *
+     * The caller (the fleet's `invalidationSink`) invokes this after `notifyWrites`, passing the
+     * SAME derived invalidation. Translates `inv.tables` with the identical `translateTableIds`
+     * helper the local path uses, so a driver's `t.startsWith("scheduler/")`-style filter matches
+     * either source the same way. A local commit and a foreign commit that happen to touch the same
+     * table may both wake a driver for what is conceptually "the same" change window — harmless,
+     * since driver wakes are level-triggered (a driver re-checks its own state, it doesn't trust the
+     * wake payload as the sole source of truth).
+     *
+     * A no-op on any node with no registered drivers (`commitSubs` empty) — cheap to call
+     * unconditionally from every fleet node, writer-ish or not.
+     */
+    notifyExternalCommit(inv: {
+        tables: string[];
+        ranges: readonly SerializedKeyRange[];
+        commitTs: number;
+    }): void;
+    /**
+     * Live view of the registered app+component function paths. Reads the same mutable `modules`
+     * map `setModules` hot-swaps in place, so counts stay correct across a dev reload or deploy
+     * (the boot-time snapshot the server used to cache went stale after the first hot-swap).
+     */
+    functionPaths(): string[];
+    /** Live view of the registered table names (mirrors `functionPaths`, reads the live map). */
+    tableNames(): string[];
+    /** Open an in-process connection an unmodified client can talk to. */
+    connect(sessionId?: string): LoopbackConnection;
+    /**
+     * Synthesizes a `UdfResult` for a write forwarded to the writer node: `forward` only returns
+     * the function's JSON result, not read ranges / an oplog, so those come back empty/zero here.
+     * Shared by `run()` and `runAction()` — both route through the same `WriteRouter`.
+     */
+    private forwardedResult;
+    /** Directly invoke a function (for HTTP routes / the CLI `run` command). A MUTATION routes
+     *  per-shard inside the executor (`executor.run` forwards a shard this node doesn't own); an
+     *  ACTION forwards wholesale here to the default-shard holder; queries always run locally. */
+    run<T = unknown>(path: string, args: JSONValue, opts?: {
+        identity?: string | null;
+        commitMeta?: Record<string, string>;
+        dedup?: DedupKey;
+    }): Promise<UdfResult<T>>;
+    /**
+     * The OWNER-side dedup classification for a mutation reaching `run()` with a dedup key (the fleet
+     * `/_fleet/run` forward path). Shares the exact classify → run-with-guard → replay-on-collision
+     * logic the sync `runMutation` uses; a replay is surfaced as a `UdfResult` with `clientReplay` set
+     * (the `/_fleet/run` handler serializes it to a replay body). `base` is any pre-existing commit
+     * meta (e.g. fleet's `idempotencyKey`) — the dedup keys merge onto it (disjoint keys).
+     */
+    private runMutationClassified;
+    /** Wrap a {@link ClientReplay} as a `UdfResult` carrying `clientReplay` — no commit happened. */
+    private replayResult;
+    /** Directly invoke an action (for HTTP routes / the CLI `run` command). Public gate: blocks
+     *  `_`-prefixed paths. Routes through `writeRouter` when set and this node isn't the writer. */
+    runAction<T = unknown>(path: string, args: JSONValue, opts?: {
+        identity?: string | null;
+    }): Promise<UdfResult<T>>;
+    /** Directly invoke an httpAction (for the public HTTP router). Passes the raw `Request` through
+     *  untouched and returns the handler's `Response`. Public gate: blocks `_`-prefixed paths. */
+    runHttpAction(path: string, request: Request, opts?: {
+        identity?: string | null;
+    }): Promise<Response>;
+    /**
+     * The privileged built-in doc mutations whose target is a USER table (and thus may be sharded).
+     * These are the ONLY `runSystem` paths that need shard routing — every other `_system:*`/
+     * `_storage:*`/`_test:*` built-in writes UNSHARDED component-internal tables, which are owned by
+     * the default ring (INSERT from any ring; RMW on default), so they need no override.
+     */
+    private static readonly DOC_MUTATION_PATHS;
+    /** Run a privileged built-in (`_system:*`) function. Trusted callers only (the admin API).
+     *  For a doc mutation on a user table, the target document's OWNING shard is resolved and passed
+     *  through so the privileged write lands on the same ring a user's sharded mutation of that doc
+     *  would — one-doc-one-ring. `opts.shardId` lets a trusted caller override the resolution. */
+    runSystem<T = unknown>(path: string, args: JSONValue, opts?: {
+        shardId?: ShardId;
+        commitMeta?: Record<string, string>;
+    }): Promise<UdfResult<T>>;
+    /**
+     * Resolve the owning shard for a privileged admin doc mutation so the write commits on the SAME
+     * ring a user's sharded mutation of that document would use (the one-doc-one-ring invariant).
+     * Without this, a dashboard edit of a sharded doc runs on the default ring and forks the doc's
+     * prev_ts chain against its home-shard writer — a permanent tailer halt + a silently-lost update.
+     *
+     * The shard-key field is IMMUTABLE after insert, so peeking the current doc's key value BEFORE the
+     * transaction is race-free (its shard can't have changed by the time the txn opens). An unsharded
+     * target (component tables, or app tables with no `.shardKey`) resolves to `"default"` — its RMW
+     * ring per the same invariant. Called only for `DOC_MUTATION_PATHS` when `numShards > 1`.
+     */
+    private resolveDocMutationShard;
+    /** Run a privileged admin built-in (`_admin:*`) once (e.g. for the HTTP fallback). Trusted callers only. */
+    runAdmin<T = unknown>(path: string, args: JSONValue): Promise<UdfResult<T>>;
+    /**
+     * Run every driver timer that is due (`atMs <= now()`), drop it, and re-arm the host to the new
+     * minimum — the firing half of the `EmbeddedRuntimeOptions.wakeHost` seam, called when the host's
+     * alarm goes off (`serve`'s `POST /_admin/wake`). It cannot be a direct call: the alarm lives in
+     * the host (a Durable Object), across a network boundary from this process.
+     *
+     * Safe and cheap on both paths through it, so a host never branches:
+     *  - the process was STOPPED (the common case) — the wake request BOOTS it, the drivers' own
+     *    `start()` re-derives everything from committed state, and this finds nothing due: a no-op.
+     *  - the process was RUNNING — this runs the actual pending callback.
+     *
+     * Also a no-op without a `wakeHost` (nothing arms a wake, and `setTimeout` already fired
+     * everything due), so the route being registered on every deployment costs nothing.
+     */
+    fireDueTimers(): void;
+    /**
+     * Stop the component drivers and clear their pending timers, resetting `driversStarted` so a later
+     * `startDrivers()` can bring them back up. Shared by the driver-only `stopDriversOnly()` (B2b, D5)
+     * and the full-shutdown `stopDrivers()` — the ONLY difference is whether the sync handler is also
+     * disposed, so the two can never drift on how a driver is torn down.
+     */
+    private stopDriversInternal;
+    /**
+     * Stop all component drivers and clear all pending driver timers. Call on runtime shutdown.
+     * ALSO disposes the sync handler's background flush sweep — this is the full-teardown path.
+     */
+    stopDrivers(): Promise<void>;
+    /**
+     * Driver-only stop (B2b, D5 — "drivers follow the default shard"): stop the scheduler/workflow/cron/
+     * reaper drivers and clear their timers, WITHOUT disposing the sync handler. A fleet node that
+     * relinquishes (or gracefully releases) the default shard keeps serving reads, subscriptions, and
+     * mutations for every OTHER shard — only its drivers go quiet, because a different node now owns the
+     * default ring the scheduler tables live on. Symmetric with `startDrivers()` and idempotent both
+     * ways (the reset flag makes a later `startDrivers()` a real restart, and a second stop a no-op),
+     * so callers never need to track whether drivers are currently running. Deliberately NEVER touches
+     * `handler.dispose()` (the shipped `stopDrivers()` did — fatal on a default-relinquish, since the
+     * node stays live).
+     */
+    stopDriversOnly(): Promise<void>;
+    /**
+     * Start component drivers deferred via `EmbeddedRuntimeOptions.deferDrivers`, OR restart them after
+     * a `stopDriversOnly()` (B2b, D5). Idempotent — a second (or later) call is a no-op once drivers are
+     * running, so callers don't need to track whether they've already called it (e.g. a fleet node
+     * calling this on every default-shard acquisition attempt).
+     */
+    startDrivers(): Promise<void>;
+    /**
+     * Lets a non-writer fleet node advance its local timestamp oracle past timestamps it learns
+     * from the writer's change stream, so its own next allocated timestamp (if/when it becomes
+     * the writer) never collides with or precedes one it already observed.
+     *
+     * Fleet B3 (D1) routing: WITHOUT a `queryStore` (`queryOracle` undefined), this is the shipped
+     * behavior — delegates straight to the WRITE oracle (`this.oracle`; a `ShardedTransactor` fans
+     * it to every shard). WITH a `queryStore` configured, a hybrid node has a real query-path oracle
+     * whose sole purpose IS tailer post-apply feeding — so this routes to `queryOracle` INSTEAD, and
+     * the write oracle is left untouched by tailer observations (it advances only via this runtime's
+     * own local commits, through `ShardWriter.commit`'s `oracle.publishCommitted`). Sharing one
+     * oracle between the two would let a query snapshot ABOVE the replica's actual watermark and
+     * read holes (D1's spec-review requirement) — this branch is what keeps them separate.
+     *
+     * This is the READ-PATH observer (tailer/follower freshness → query snapshot). Its write-path
+     * counterpart, `observeWriteTimestamp` (below), always targets the WRITE oracle and exists
+     * precisely because this method stopped feeding the write side once a hybrid has a query oracle.
+     */
+    observeTimestamp(ts: bigint): void;
+    /**
+     * Advance the WRITE transactor's timestamp oracle(s) past `ts` — the write-path counterpart to
+     * `observeTimestamp` above, and the pre-T1 semantics of what `observeTimestamp` used to do before
+     * hybrid routing split the two. ALWAYS targets `this.oracle` (the write side), independent of
+     * `queryStore`/`queryOracle` routing: a `ShardedTransactor` fans `ts` to every existing shard
+     * oracle AND raises its `observedHighWater` floor (so a shard writer CREATED later seeds at-or-past
+     * `ts`); the single-shard `MonotonicTimestampOracle` takes it directly.
+     *
+     * Purpose (distinct from `observeTimestamp`): re-floor the WRITE snapshot on a shard OWNERSHIP
+     * CHANGE. On a hybrid node `observeTimestamp` feeds the QUERY oracle, so nothing feeds the write
+     * oracle from foreign observations anymore. A shard this node held, RELEASED (its `ShardWriter`
+     * stays in the transactor's Map — only the fleet epoch is dropped), and later RE-ACQUIRES would
+     * keep that `ShardWriter`'s oracle frozen at this node's own last commit; the next mutation would
+     * snapshot BELOW an interim owner's commits and an RMW handler would compute on stale state (the
+     * durable chain stays intact via latest-`prev_ts`, but the update is semantically lost). The fleet
+     * calls this on EVERY shard acquisition with the lease row's `frontier_ts` — which is >= every
+     * prior commit on that shard by the fence invariant (the commit guard writes `frontier_ts =
+     * GREATEST(frontier_ts, commitTs)` inside each commit txn) — so it is the exact correct floor.
+     * Idempotent/monotone: a `ts` at or below the oracle's position is a no-op (harmless on a
+     * fresh/never-released shard, and on every non-hybrid node where it is called uniformly too).
+     */
+    observeWriteTimestamp(ts: bigint): void;
+    /**
+     * Run `fn` under shard `shardId`'s commit mutex IFF that shard is idle right now — the seam a fleet
+     * writer's idle-frontier closer uses to publish a shard's frontier atomically with respect to that
+     * shard's own commits (see `ShardedTransactor.tryRunExclusiveOnShard`). A shard is idle only when
+     * the commit mutex is free AND no group-commit batch is staged/flushing (Fleet B4: the flush runs
+     * OFF the mutex, so mutex-freedom alone is not enough — a mid-flush batch has ts's drawn but rows
+     * not yet landed, and must read as busy to keep the closer from publishing a frontier above them).
+     * Returns `true` if `fn` ran, `false` if the shard is busy (skip; retry next beat). Total across
+     * sharded/single-shard runtimes — the single-shard transactor ignores `shardId` and uses its one
+     * writer.
+     */
+    tryRunExclusiveOnShard(shardId: ShardId, fn: () => Promise<void>): Promise<boolean>;
+    /**
+     * Group-commit counters (Fleet B4, T4 health) — total across the transactor, whichever shape it
+     * is: `ShardedTransactor.groupCommitStats()` aggregates over every live shard,
+     * `SingleWriterTransactor.groupCommitStats()` mirrors it for the one writer. Both are
+     * structurally all-zero when `EmbeddedRuntimeOptions.groupCommit` is unset/false (the underlying
+     * `ShardWriter` never touches these fields on the single-commit path) — callers need no separate
+     * on/off branch. The fleet health seam (`@helipod/fleet`'s `node.ts`) reads this to derive
+     * `flushesPerSec` between successive `/api/health` reads.
+     */
+    groupCommitStats(): {
+        lastBatchSize: number;
+        maxBatchSize: number;
+        flushCount: number;
+    };
+}
+declare function createEmbeddedRuntime(options: EmbeddedRuntimeOptions): Promise<EmbeddedRuntime>;
+
+/**
+ * `RuntimeHost` — the neutral seam between the engine and whatever binds it to a transport
+ * (HTTP + WebSocket). It exists so the SAME `EmbeddedRuntime` can run on a long-lived process
+ * (`Bun.serve` / `node:http` + `ws`) AND on a Cloudflare Durable Object (Worker `fetch` +
+ * `WebSocketPair`/hibernation), with each backend implementing this one method.
+ *
+ * NEUTRALITY RULE (a Slice-1 gate — asserted mechanically in
+ * `packages/runtime-embedded/test/host-neutral.test.ts`): this file imports ONLY `@helipod/*`
+ * symbols and TS type-only imports. It contains NO host I/O primitive — no `bun`, `node:*`, `ws`,
+ * no cloudflare type, no `DurableObjectNamespace`. Where a concept cannot be expressed neutrally it
+ * is documented, not papered over (see `ServerHandle.close` and `ServeOptions` below).
+ *
+ * WHY GENERIC: `ServeOptions`/`ServerHandle` are lifted verbatim (no field changes) from the
+ * process host's `DevServerOptions`/`DevServer`. Several of those fields reference types that live
+ * in `@helipod/cli`, `@helipod/admin`, and `@helipod/storage` — all of which depend ON
+ * `@helipod/runtime-embedded`, so importing them here would be a dependency cycle AND would drag
+ * a host I/O concern into the neutral seam. The route/admin/storage/deploy/fleet shapes are
+ * therefore carried as type parameters (defaulting to `unknown`): the neutral seam stays parametric
+ * and each concrete host pins the parameters (`@helipod/cli` re-aliases them as `DevServer`/
+ * `DevServerOptions`). The FIELDS are unchanged; only their concrete types are supplied by the host.
+ */
+
+/**
+ * The handle a host returns from {@link RuntimeHost.serve}. Its `close()`/`setRoutes()` are the ONLY
+ * lifecycle a caller drives post-serve. Lifted verbatim from the process host's `DevServer`.
+ */
+interface ServerHandle<Route = unknown> {
+    url: string;
+    /**
+     * The bound TCP port. A portless host (a Durable Object — the Worker owns ingress, there is no
+     * socket to bind) returns `0` as a sentinel. Do not treat `0` as "unbound/failed".
+     */
+    port: number;
+    /**
+     * Stop serving and release resources. **MAY never be called.** A host with no shutdown moment —
+     * a Durable Object hibernates and is evicted silently, with no `SIGTERM` — is a valid host, and
+     * such a host's `close()` may legitimately be a no-op. Do NOT rely on `close()` (and therefore
+     * on `runtime.stopDrivers()` / `store.close()`) running: durable work must survive without it.
+     * The process host DOES call `close()` on `SIGTERM`/`SIGINT`, exactly as before this seam existed.
+     */
+    close(): Promise<void>;
+    /** Replace the httpAction route table, e.g. after a hot reload re-resolves `http.ts`. */
+    setRoutes(routes: Route[]): void;
+}
+/**
+ * The options a caller passes to {@link RuntimeHost.serve}. Lifted verbatim from the process host's
+ * `DevServerOptions` — no field changes.
+ *
+ * IMPEDANCE CONTRACT (do not design against it): the sync handler's per-session state (each
+ * session's read-set, held behind `runtime.handler.connect`/`handleMessage`) is NOT guaranteed to
+ * survive a single `serve()` lifetime. On a Durable Object, WebSocket hibernation discards
+ * in-memory state; a host may reconstruct a session from its durable attachment and call
+ * `handler.connect` again on revival. A host must therefore treat
+ * `handler.connect(sessionId, socket)` / `handler.disconnect(sessionId)` as the transport boundary
+ * and never assume the handler's in-memory session map persists for the server's lifetime.
+ */
+interface ServeOptions<Route = unknown, Admin = unknown, StorageRt = unknown, Deploy = unknown, Fleet = unknown> {
+    port: number;
+    ip: string;
+    webDir?: string;
+    admin?: {
+        api: Admin;
+        key: string;
+    };
+    /**
+     * The dashboard SPA. Two variants:
+     *  - `dev`/`serve`: `{ distDir, html }` — dist dir (hashed Vite assets) + key-injected index.html.
+     *  - a compiled `helipod build` binary: `{ assets, html }` — a urlPath→embedded-path map.
+     */
+    dashboard?: {
+        distDir: string;
+        html: string;
+    } | {
+        assets: Record<string, string>;
+        html: string;
+    };
+    /** The app's `http.ts` routes, resolved to `path:name` function paths for dispatch. */
+    routes?: Route[];
+    /** Engine-owned `/api/storage/*` handlers (always-on file storage). Reserved — matched before
+     *  user routes; stable across reload/deploy. */
+    storageRoutes?: StorageRt[];
+    /** Reserved routes contributed by composed components (e.g. auth's OAuth callbacks). Matched
+     *  after storage routes, before user routes. Engine-owned `{method,pathPrefix,handler}` closures.
+     *  Shares the `StorageRt` shape (`{method,pathPrefix,handler}`) — the CLI pins both to `StorageRoute`. */
+    componentRoutes?: StorageRt[];
+    /** `POST /_admin/deploy` + `GET /_admin/deploy/modules` handlers — present only when deploy is
+     *  enabled. `apply` accepts a legacy `{files}` OR a delta `{changed, unchanged}` payload; `modules`
+     *  returns the current per-path hashes for the client's delta partition. */
+    deploy?: {
+        apply: (payload: {
+            files: Array<{
+                path: string;
+                code: string;
+            }>;
+        } | {
+            changed: Array<{
+                path: string;
+                code: string;
+            }>;
+            unchanged: Array<{
+                path: string;
+                sha256: string;
+            }>;
+        }) => Promise<Deploy>;
+        modules: () => Record<string, string>;
+    };
+    /** Fleet node handle — present only under `serve --fleet`. Absent → byte-for-byte non-fleet. */
+    fleet?: Fleet;
+    /** Present only when THIS node is a `--replica` configured with `--writer-url` — arms `/api/run`'s
+     *  single-hop defensive guard. Absent → byte-for-byte unchanged behavior. */
+    replicaWriterUrl?: string;
+}
+/**
+ * The seam. A host binds an `EmbeddedRuntime` to a transport and starts serving; the returned
+ * {@link ServerHandle} is the whole post-serve lifecycle surface. Slice 1 ships one implementation
+ * (`@helipod/cli`'s `ProcessRuntimeHost`); a Durable Object host (Slice 3) implements the same
+ * method, wiring Worker `fetch` → the engine's HTTP dispatch and `WebSocketPair`/hibernation →
+ * `runtime.handler.connect`. `serve()` is called once per host instance (one call per process, or
+ * one per DO incarnation) — it must not assume it is the only call in a process's lifetime.
+ */
+interface RuntimeHost<Route = unknown, Admin = unknown, StorageRt = unknown, Deploy = unknown, Fleet = unknown> {
+    serve(runtime: EmbeddedRuntime, options: ServeOptions<Route, Admin, StorageRt, Deploy, Fleet>): Promise<ServerHandle<Route>>;
+}
+
+export { EmbeddedRuntime, type EmbeddedRuntimeOptions, EmbeddedWriteFanout, type EmbeddedWriteFanoutAdapter, type EmbeddedWriteFanoutPayload, type FanoutListener, InMemoryWriteFanoutAdapter, type LoopbackConnection, type LoopbackHandler, type RuntimeHost, type ServeOptions, type ServerHandle, type ServerMessageListener, clientReceiptsGuard, createEmbeddedRuntime, createLoopbackConnection };