@helipod/runtime-embedded 0.1.0

package/dist/index.js

@@ -0,0 +1,1143 @@
+// src/runtime.ts
+import { namespaceForPath } from "@helipod/component";
+import { FunctionNotFoundError } from "@helipod/errors";
+import { decodeStorageTableId, decodeDocumentId, encodeInternalDocumentId, shardIdForKeyValue, DEFAULT_SHARD } from "@helipod/id-codec";
+import { writtenTablesFromRanges, serializeKeyRange } from "@helipod/index-key-codec";
+import { jsonToConvex, convexToJson as convexToJson2 } from "@helipod/values";
+import { MonotonicTimestampOracle } from "@helipod/docstore";
+import { SingleWriterTransactor, ShardedTransactor } from "@helipod/transactor";
+import { QueryRuntime } from "@helipod/query-engine";
+import { InlineUdfExecutor, mutation } from "@helipod/executor";
+import { SyncProtocolHandler } from "@helipod/sync";
+
+// src/write-fanout.ts
+var InMemoryWriteFanoutAdapter = class {
+  listeners = /* @__PURE__ */ new Set();
+  published = [];
+  publish(payload) {
+    this.published.push(payload);
+    for (const listener of this.listeners) listener(payload);
+  }
+  subscribe(listener) {
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  }
+};
+var EmbeddedWriteFanout = class {
+  constructor(adapter, originId) {
+    this.adapter = adapter;
+    this.originId = originId;
+  }
+  adapter;
+  originId;
+  publish(delta) {
+    this.adapter.publish({
+      commitTs: Number(delta.commitTs),
+      tables: delta.writtenTables,
+      ranges: delta.writtenRanges,
+      originId: this.originId,
+      origin: delta.origin,
+      shardId: delta.shardId,
+      writtenDocs: delta.writtenDocs
+    });
+  }
+  /** Subscribe to deltas from OTHER origins (ignores our own — the Tier 2 self-loop guard). */
+  subscribe(listener) {
+    return this.adapter.subscribe((payload) => {
+      if (payload.originId !== this.originId) listener(payload);
+    });
+  }
+};
+
+// src/loopback.ts
+import { parseClientMessage } from "@helipod/sync";
+var LoopbackServerSocket = class {
+  bufferedAmount = 0;
+  listeners = /* @__PURE__ */ new Set();
+  open = true;
+  send(data) {
+    if (!this.open) return;
+    const msg = JSON.parse(data);
+    for (const listener of this.listeners) listener(msg);
+  }
+  close() {
+    this.open = false;
+  }
+  addListener(listener) {
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  }
+};
+function createLoopbackConnection(handler, sessionId) {
+  const socket = new LoopbackServerSocket();
+  handler.connect(sessionId, socket);
+  return {
+    sessionId,
+    async send(message) {
+      const raw = typeof message === "string" ? message : JSON.stringify(message);
+      parseClientMessage(raw);
+      await handler.handleMessage(sessionId, raw);
+    },
+    onMessage(listener) {
+      return socket.addListener(listener);
+    },
+    close() {
+      socket.close();
+      handler.disconnect(sessionId);
+    }
+  };
+}
+
+// src/client-dedup.ts
+import {
+  CommitGuardRejection,
+  isRetryableError,
+  isHelipodError
+} from "@helipod/errors";
+import { convexToJson } from "@helipod/values";
+var DEDUP_META_CLIENT_ID = "clientId";
+var DEDUP_META_SEQ = "seq";
+var DEDUP_META_IDENTITY = "identity";
+function identityKey(identity) {
+  return identity ?? "";
+}
+function replayFromRecord(rec) {
+  if (rec.verdict === "applied") {
+    return {
+      verdict: "applied",
+      commitTs: Number(rec.commitTs),
+      ...rec.hasValue ? { value: rec.value } : { valueMissing: true }
+    };
+  }
+  return { verdict: "failed", commitTs: Number(rec.commitTs), code: rec.errorCode ?? "MUTATION_FAILED" };
+}
+async function classifyDedup(store, identity, dedup) {
+  const id = identityKey(identity);
+  const rec = await store.getClientVerdict(id, dedup.clientId, dedup.seq);
+  if (rec) return replayFromRecord(rec);
+  const floor = await store.getClientFloor(id, dedup.clientId);
+  if (floor !== null && dedup.seq <= floor) return { verdict: "stale", code: "STALE_CLIENT" };
+  return null;
+}
+async function classifyForConnect(store, identity, clientId, seq) {
+  const replay = await classifyDedup(store, identity, { clientId, seq });
+  if (replay === null) return { clientId, seq, verdict: "unknown" };
+  return { clientId, seq, ...replay };
+}
+function dedupCommitMeta(identity, dedup, base) {
+  return {
+    ...base ?? {},
+    [DEDUP_META_IDENTITY]: identityKey(identity),
+    [DEDUP_META_CLIENT_ID]: dedup.clientId,
+    [DEDUP_META_SEQ]: String(dedup.seq)
+  };
+}
+async function handleDedupError(store, identity, dedup, e) {
+  const id = identityKey(identity);
+  if (e instanceof CommitGuardRejection && e.rejectionCode === "CLIENT_MUTATION_DUP") {
+    const rec = await store.getClientVerdict(id, dedup.clientId, dedup.seq);
+    return rec ? replayFromRecord(rec) : null;
+  }
+  if (!isRetryableError(e)) {
+    const code = isHelipodError(e) ? e.code : "MUTATION_FAILED";
+    await store.recordClientVerdict(id, dedup.clientId, dedup.seq, { verdict: "failed", commitTs: 0n, errorCode: code });
+  }
+  return null;
+}
+async function recordZeroWriteApplied(store, identity, dedup, commitTs, value) {
+  await store.recordClientVerdict(identityKey(identity), dedup.clientId, dedup.seq, {
+    verdict: "applied",
+    commitTs,
+    value: convexToJson(value)
+  });
+}
+async function fillWriteMutationValue(store, identity, dedup, value) {
+  try {
+    await store.updateClientVerdictValue(identityKey(identity), dedup.clientId, dedup.seq, convexToJson(value));
+  } catch {
+  }
+}
+function clientReceiptsGuard() {
+  const INSERT = `INSERT INTO client_mutations (identity, client_id, seq, verdict, commit_ts, value_json, error_code, created_at)`;
+  return (q, units) => {
+    const pg = q;
+    if (typeof pg.query === "function") {
+      return (async () => {
+        for (let i = 0; i < units.length; i++) {
+          const dedup = readUnitDedup(units[i]);
+          if (!dedup) continue;
+          try {
+            await pg.query(
+              `${INSERT} VALUES ($1, $2, $3, 'applied', $4, NULL, NULL, $5)`,
+              [dedup.identity, dedup.clientId, BigInt(dedup.seq), units[i].ts, BigInt(Date.now())]
+            );
+          } catch (e) {
+            throw toDupOrRethrow(e, i, dedup);
+          }
+        }
+      })();
+    }
+    const sq = q;
+    for (let i = 0; i < units.length; i++) {
+      const dedup = readUnitDedup(units[i]);
+      if (!dedup) continue;
+      try {
+        sq.run(
+          `${INSERT} VALUES (?, ?, ?, 'applied', ?, NULL, NULL, ?)`,
+          dedup.identity,
+          dedup.clientId,
+          dedup.seq,
+          units[i].ts,
+          Date.now()
+        );
+      } catch (e) {
+        throw toDupOrRethrow(e, i, dedup);
+      }
+    }
+    return void 0;
+  };
+}
+function readUnitDedup(unit) {
+  const meta = unit.meta;
+  const clientId = meta?.[DEDUP_META_CLIENT_ID];
+  const seqStr = meta?.[DEDUP_META_SEQ];
+  if (clientId === void 0 || seqStr === void 0) return null;
+  return { identity: meta[DEDUP_META_IDENTITY] ?? "", clientId, seq: Number(seqStr) };
+}
+function toDupOrRethrow(e, unitIndex, dedup) {
+  const code = String(e.code ?? "");
+  const message = String(e?.message ?? "");
+  const isUniqueViolation = code === "23505" || code.startsWith("SQLITE_CONSTRAINT") || /unique constraint failed/i.test(message);
+  if (isUniqueViolation) {
+    return new CommitGuardRejection(unitIndex, "CLIENT_MUTATION_DUP", `client=${dedup.clientId} seq=${dedup.seq}`, {
+      cause: e
+    });
+  }
+  return e;
+}
+
+// src/runtime.ts
+var DEPLOYMENT_ID_GLOBAL_KEY = "fleet:deploymentId";
+function isInternalPath(path) {
+  return path.split(":").some((seg) => seg.startsWith("_"));
+}
+function rebuildTableNumberToName(map, tableNumbers) {
+  map.clear();
+  for (const [name, num] of Object.entries(tableNumbers)) map.set(num, name);
+}
+function replayToRunResult(replay) {
+  const out = { replayed: true, verdict: replay.verdict };
+  if (replay.commitTs !== void 0) out.commitTs = replay.commitTs;
+  if (replay.value !== void 0) out.value = jsonToConvex(replay.value);
+  if (replay.valueMissing) out.valueMissing = true;
+  if (replay.code !== void 0) out.code = replay.code;
+  return out;
+}
+function translateTableIds(tableIds, tableNumberToName) {
+  return tableIds.map((id) => {
+    try {
+      return tableNumberToName.get(decodeStorageTableId(id)) ?? id;
+    } catch {
+      return id;
+    }
+  });
+}
+function fireCommitSubs(commitSubs, inv) {
+  for (const cb of commitSubs) {
+    try {
+      cb(inv);
+    } catch (e) {
+      console.error("[runtime] driver onCommit callback threw:", e);
+    }
+  }
+}
+var EmbeddedRuntime = class _EmbeddedRuntime {
+  constructor(store, executor, handler, writeFanoutAdapter, modules, systemModules, adminModules, componentNames, contextProviders, policyRegistry, policyProviders, relationRegistry, drivers, timers, fireDue, tableNumberToName, oracle, queryOracle, transactor, driverCtx, driversStarted, writeRouter, numShards, catalog, commitSubs) {
+    this.store = store;
+    this.executor = executor;
+    this.handler = handler;
+    this.writeFanoutAdapter = writeFanoutAdapter;
+    this.modules = modules;
+    this.systemModules = systemModules;
+    this.adminModules = adminModules;
+    this.componentNames = componentNames;
+    this.contextProviders = contextProviders;
+    this.policyRegistry = policyRegistry;
+    this.policyProviders = policyProviders;
+    this.relationRegistry = relationRegistry;
+    this.drivers = drivers;
+    this.timers = timers;
+    this.fireDue = fireDue;
+    this.tableNumberToName = tableNumberToName;
+    this.oracle = oracle;
+    this.queryOracle = queryOracle;
+    this.transactor = transactor;
+    this.driverCtx = driverCtx;
+    this.driversStarted = driversStarted;
+    this.writeRouter = writeRouter;
+    this.numShards = numShards;
+    this.catalog = catalog;
+    this.commitSubs = commitSubs;
+  }
+  store;
+  executor;
+  handler;
+  writeFanoutAdapter;
+  modules;
+  systemModules;
+  adminModules;
+  componentNames;
+  contextProviders;
+  policyRegistry;
+  policyProviders;
+  relationRegistry;
+  drivers;
+  timers;
+  fireDue;
+  tableNumberToName;
+  oracle;
+  queryOracle;
+  transactor;
+  driverCtx;
+  driversStarted;
+  writeRouter;
+  numShards;
+  catalog;
+  commitSubs;
+  sessionCounter = 0;
+  static async create(options) {
+    await options.store.setupSchema();
+    if (!options.externalReceiptsGuard) options.store.addCommitGuard(clientReceiptsGuard());
+    let deploymentId = await options.store.getGlobal(DEPLOYMENT_ID_GLOBAL_KEY);
+    if (deploymentId === null) {
+      try {
+        await options.store.writeGlobalIfAbsent(DEPLOYMENT_ID_GLOBAL_KEY, crypto.randomUUID());
+        deploymentId = await options.store.getGlobal(DEPLOYMENT_ID_GLOBAL_KEY);
+      } catch {
+        deploymentId = null;
+      }
+    }
+    const resolvedDeploymentId = deploymentId ?? "";
+    if (options.queryStore) await options.queryStore.setupSchema();
+    const adapter = options.fanoutAdapter ?? new InMemoryWriteFanoutAdapter();
+    const fanout = new EmbeddedWriteFanout(adapter, options.originId ?? "embedded");
+    const startTs = await options.store.maxTimestamp();
+    let transactor;
+    let oracle;
+    if ((options.numShards ?? 1) > 1) {
+      const sharded = new ShardedTransactor(options.store, { fanout, groupCommit: options.groupCommit ?? false });
+      sharded.observeTimestamp(startTs);
+      transactor = sharded;
+      oracle = sharded;
+    } else {
+      const singleOracle = new MonotonicTimestampOracle(startTs);
+      transactor = new SingleWriterTransactor(options.store, singleOracle, { fanout, groupCommit: options.groupCommit ?? false });
+      oracle = singleOracle;
+    }
+    const queryRuntime = new QueryRuntime(options.store);
+    let queryPath;
+    let queryOracle;
+    if (options.queryStore) {
+      const queryStartTs = await options.queryStore.maxTimestamp();
+      const qOracle = new MonotonicTimestampOracle(queryStartTs);
+      const queryTransactor = new SingleWriterTransactor(options.queryStore, qOracle);
+      queryPath = { transactor: queryTransactor, queryRuntime: new QueryRuntime(options.queryStore) };
+      queryOracle = qOracle;
+    }
+    const numShards = options.numShards ?? 1;
+    let executorRef;
+    const invoke = async (path, args, opts) => {
+      const fn = modules[path];
+      if (!fn) throw new FunctionNotFoundError(`unknown function: ${path}`);
+      return executorRef.run(fn, jsonToConvex(args), {
+        path,
+        namespace: namespaceForPath(path, componentNames),
+        contextProviders,
+        policyRegistry,
+        policyProviders,
+        relationRegistry,
+        functionKind,
+        identity: opts?.identity ?? null,
+        numShards
+      });
+    };
+    const executor = new InlineUdfExecutor({ transactor, queryRuntime, catalog: options.catalog, logSink: options.logSink, now: options.now, invoke, writeRouter: options.writeRouter, queryPath, globalStore: options.globalStore });
+    executorRef = executor;
+    for (const step of options.bootSteps ?? []) {
+      const bootFn = mutation(async (ctx) => {
+        await step.run({ db: ctx.db, now: ctx.now() });
+        return null;
+      });
+      await executor.run(bootFn, {}, { path: `_boot:${step.name}`, namespace: step.name, identity: null, numShards, localOnly: true });
+    }
+    const componentNames = options.componentNames ?? /* @__PURE__ */ new Set();
+    const contextProviders = options.contextProviders ?? [];
+    const policyRegistry = options.policyRegistry ?? /* @__PURE__ */ new Map();
+    const policyProviders = options.policyProviders ?? [];
+    const relationRegistry = options.relationRegistry;
+    const modules = { ...options.modules };
+    const systemModules = { ...options.systemModules ?? {} };
+    const adminModules = { ...options.adminModules ?? {} };
+    const functionKind = (path) => modules[path]?.type;
+    const resolve = (path) => {
+      if (isInternalPath(path)) throw new FunctionNotFoundError(`unknown function: ${path}`);
+      const fn = modules[path];
+      if (!fn) throw new FunctionNotFoundError(`unknown function: ${path}`);
+      return fn;
+    };
+    const syncExecutor = {
+      async runQuery(path, args, identity) {
+        const r = await executor.run(resolve(path), jsonToConvex(args), { path, namespace: namespaceForPath(path, componentNames), contextProviders, policyRegistry, policyProviders, relationRegistry, functionKind, identity: identity ?? null, numShards });
+        return {
+          value: r.value,
+          tables: writtenTablesFromRanges(r.readRanges),
+          readRanges: r.readRanges.map(serializeKeyRange),
+          globalTables: r.globalTables ?? [],
+          ...r.diffableRange ? { diffableRange: r.diffableRange } : {},
+          ...r.diffablePage ? { diffablePage: r.diffablePage } : {}
+        };
+      },
+      async runMutation(path, args, identity, origin, dedup) {
+        const fn = resolve(path);
+        const willForward = dedup !== void 0 && !!options.writeRouter && !options.writeRouter.isLocalWriter(DEFAULT_SHARD);
+        const classifyLocally = dedup !== void 0 && !willForward;
+        if (classifyLocally) {
+          const pre = await classifyDedup(options.store, identity ?? null, dedup);
+          if (pre) return replayToRunResult(pre);
+        }
+        const runOpts = {
+          path,
+          namespace: namespaceForPath(path, componentNames),
+          contextProviders,
+          policyRegistry,
+          policyProviders,
+          relationRegistry,
+          functionKind,
+          identity: identity ?? null,
+          numShards,
+          origin,
+          dedup,
+          commitMeta: classifyLocally ? dedupCommitMeta(identity ?? null, dedup) : void 0
+        };
+        let r;
+        try {
+          r = await executor.run(fn, jsonToConvex(args), runOpts);
+        } catch (e) {
+          if (classifyLocally) {
+            const replay = await handleDedupError(options.store, identity ?? null, dedup, e);
+            if (replay) return replayToRunResult(replay);
+          }
+          throw e;
+        }
+        if (r.clientReplay) return replayToRunResult(r.clientReplay);
+        if (classifyLocally && !r.committed) {
+          await recordZeroWriteApplied(options.store, identity ?? null, dedup, r.commitTs, r.value);
+        } else if (classifyLocally && r.oplog !== null) {
+          await fillWriteMutationValue(options.store, identity ?? null, dedup, r.value);
+        }
+        return {
+          replayed: false,
+          value: r.value,
+          tables: r.oplog?.writtenTables ?? [],
+          writeRanges: r.oplog?.writtenRanges ?? [],
+          // `commitTs` (B2b, T2): a LOCAL commit reports it via `r.oplog.commitTs`; a FORWARDED
+          // mutation has no local oplog (null), but the executor's forward branch already threads
+          // the owner's real commitTs onto `r.commitTs` itself — fall back to that.
+          commitTs: Number(r.oplog?.commitTs ?? r.commitTs ?? 0n),
+          // G4 fleet fallback signal: a committed write with NO local oplog was forwarded to another
+          // shard's owner — its origin tag can't reach this node's `doNotifyWrites`.
+          forwarded: r.committed && r.oplog === null
+        };
+      },
+      async runAdminQuery(path, args) {
+        const fn = adminModules[path];
+        if (!fn) throw new Error(`unknown admin function: ${path}`);
+        const r = await executor.run(fn, jsonToConvex(args), { path, privileged: true, numShards });
+        return {
+          value: r.value,
+          tables: writtenTablesFromRanges(r.readRanges),
+          readRanges: r.readRanges.map(serializeKeyRange),
+          globalTables: r.globalTables ?? [],
+          ...r.diffableRange ? { diffableRange: r.diffableRange } : {},
+          ...r.diffablePage ? { diffablePage: r.diffablePage } : {}
+        };
+      },
+      async runAction(path, args, identity) {
+        const fn = resolve(path);
+        if (fn.type !== "action") throw new Error(`${path} is not an action`);
+        if (options.writeRouter && !options.writeRouter.isLocalWriter(DEFAULT_SHARD)) {
+          const res = await options.writeRouter.forward("action", path, args, identity ?? null, DEFAULT_SHARD);
+          return { value: jsonToConvex(res.value) };
+        }
+        const r = await executor.run(fn, jsonToConvex(args), { path, namespace: namespaceForPath(path, componentNames), contextProviders, policyRegistry, policyProviders, relationRegistry, functionKind, identity: identity ?? null, numShards });
+        return { value: r.value };
+      },
+      // ── Receipted Outbox resume-handshake support (verdict §(e)) ──────────────────────────────
+      // Both reads/writes go to the AUTHORITATIVE receipts store (the primary), NOT `options.store`:
+      // on a fleet sync node the latter is the replica, which carries no receipts (see
+      // `receiptsStore`'s doc comment). Unset → `options.store`, byte-identical off the fleet.
+      async classifyClientMutation(identity, clientId, seq) {
+        return classifyForConnect(options.receiptsStore ?? options.store, identity ?? null, clientId, seq);
+      },
+      async pruneClientMutations(identity, clientId, ackedThrough) {
+        await (options.receiptsStore ?? options.store).pruneClientMutations(identity ?? "", clientId, { ackedThrough });
+      },
+      deploymentId() {
+        return resolvedDeploymentId;
+      }
+    };
+    const handler = new SyncProtocolHandler(syncExecutor, {
+      autoNotifyOnMutation: false,
+      verifyAdmin: options.verifyAdmin,
+      // The DO host (Slice 3) sets this so the handler arms no `setInterval` sweep / ping heartbeat;
+      // unset everywhere else (byte-identical to before this option existed).
+      disableBackgroundTimers: options.disableSyncBackgroundTimers
+    });
+    const queue = [];
+    let draining = false;
+    const drain = async () => {
+      if (draining) return;
+      draining = true;
+      try {
+        while (queue.length > 0) {
+          const inv = queue.shift();
+          if (options.beforeNotify) {
+            try {
+              await options.beforeNotify(BigInt(inv.commitTs));
+            } catch (e) {
+              console.error("[runtime] beforeNotify hook threw:", e);
+            }
+          }
+          await handler.notifyWrites(inv, inv.origin);
+        }
+      } finally {
+        draining = false;
+      }
+    };
+    const commitSubs = /* @__PURE__ */ new Set();
+    const timers = /* @__PURE__ */ new Map();
+    let timerSeq = 0;
+    const wakeHost = options.wakeHost;
+    let armedAt = null;
+    const rearm = () => {
+      if (!wakeHost) return;
+      let min = null;
+      for (const t of timers.values()) if (min === null || t.atMs < min) min = t.atMs;
+      if (min === armedAt) return;
+      armedAt = min;
+      wakeHost.armWake(min);
+    };
+    const fireDueTimers = () => {
+      const t0 = options.now?.() ?? Date.now();
+      armedAt = null;
+      const due = [];
+      for (const [h, t] of timers) {
+        if (t.atMs <= t0) {
+          due.push(t);
+          timers.delete(h);
+        }
+      }
+      try {
+        for (const t of due) {
+          try {
+            t.cb();
+          } catch (e) {
+            console.error("[runtime] driver timer callback threw:", e);
+          }
+        }
+      } finally {
+        rearm();
+      }
+    };
+    const backstopMs = options.backstopMs ?? ((d) => d);
+    const driverCtx = {
+      runFunction: async (path, args) => {
+        const fn = modules[path];
+        if (!fn) throw new Error(`driver: unknown function ${path}`);
+        const ns = namespaceForPath(path, componentNames);
+        const res = await executor.run(fn, jsonToConvex(args), {
+          path,
+          namespace: ns,
+          contextProviders,
+          policyRegistry,
+          policyProviders,
+          relationRegistry,
+          functionKind,
+          identity: null,
+          privileged: true,
+          numShards,
+          // A driver runs on the writer that owns its control tables and must read-its-own-writes:
+          // force its queries onto the PRIMARY, never a hybrid node's lagging replica queryPath, so
+          // a just-enqueued scheduler job is visible on the very next peek. No-op off a hybrid.
+          primaryRead: true
+        });
+        return res.value;
+      },
+      onCommit: (cb) => {
+        commitSubs.add(cb);
+        return () => commitSubs.delete(cb);
+      },
+      setTimer: (atMs, cb) => {
+        const h = ++timerSeq;
+        const t = { atMs, cb };
+        if (!wakeHost) {
+          t.timeout = setTimeout(() => {
+            timers.delete(h);
+            cb();
+          }, Math.max(0, atMs - (options.now?.() ?? Date.now())));
+        }
+        timers.set(h, t);
+        rearm();
+        return h;
+      },
+      clearTimer: (h) => {
+        const t = timers.get(h);
+        if (t) {
+          if (t.timeout !== void 0) clearTimeout(t.timeout);
+          timers.delete(h);
+          rearm();
+        }
+      },
+      now: () => options.now?.() ?? Date.now(),
+      backstopMs,
+      // Same resolver as `create()`'s local `functionKind` closure (used elsewhere for
+      // `ComponentContext.functionKind`) — reused here, not recomputed, so a driver's path
+      // validation (e.g. `@helipod/triggers`' boot-time handler check) and every other kind
+      // lookup in this runtime always agree.
+      functionKind,
+      readLog: async (opts) => {
+        const store = options.store;
+        const afterTs = BigInt(Math.trunc(opts.afterTs));
+        const stable = options.stablePrefix ? await options.stablePrefix() : null;
+        const bound = stable ?? await store.maxTimestamp();
+        if (bound <= afterTs) return { changes: [], maxScannedTs: Number(afterTs) };
+        if (opts.limit === 0) return { changes: [], maxScannedTs: Number(bound) };
+        const limit = opts.limit;
+        const scanned = [];
+        for await (const e of store.load_documents(
+          { minInclusive: afterTs + 1n, maxExclusive: bound + 1n },
+          "asc",
+          limit
+        )) {
+          scanned.push(e);
+        }
+        let maxScannedTs;
+        let rows;
+        const limitHit = limit !== void 0 && scanned.length === limit;
+        if (!limitHit) {
+          maxScannedTs = bound;
+          rows = scanned;
+        } else {
+          const lastTs = scanned[scanned.length - 1].ts;
+          if (lastTs > afterTs + 1n) {
+            maxScannedTs = lastTs - 1n;
+            rows = scanned.filter((e) => e.ts < lastTs);
+          } else {
+            maxScannedTs = lastTs;
+            rows = [];
+            for await (const e of store.load_documents(
+              { minInclusive: lastTs, maxExclusive: lastTs + 1n },
+              "asc"
+            )) {
+              rows.push(e);
+            }
+          }
+        }
+        const tableFilter = opts.tables ? new Set(opts.tables) : null;
+        const changes = [];
+        for (const e of rows) {
+          const name = tableNumberToName.get(e.id.tableNumber);
+          if (name === void 0 || name.includes("/") || name.startsWith("_")) continue;
+          if (tableFilter && !tableFilter.has(name)) continue;
+          const op = e.value === null ? "delete" : e.prev_ts === null ? "insert" : "update";
+          const newDoc = e.value === null ? null : convexToJson2(e.value.value);
+          let oldDoc = null;
+          if (e.prev_ts !== null) {
+            const prev = await store.get(e.id, e.prev_ts);
+            oldDoc = prev === null ? null : convexToJson2(prev.value.value);
+          }
+          const idStr = encodeInternalDocumentId(e.id);
+          const tsNum = Number(e.ts);
+          changes.push({
+            table: name,
+            id: idStr,
+            op,
+            newDoc,
+            oldDoc,
+            ts: tsNum,
+            changeId: `${name}:${idStr}:${tsNum}`
+          });
+        }
+        return { changes, maxScannedTs: Number(maxScannedTs) };
+      },
+      // M2c Task 6: `handler` (the `SyncProtocolHandler` instance) is already constructed above
+      // (`const handler = new SyncProtocolHandler(...)`) by the time this `driverCtx` object is
+      // built, so both hooks are plain delegations — no chicken-and-egg problem the way a
+      // boot-layer-constructed poller would have (`runtime.handler` doesn't exist until
+      // `createEmbeddedRuntime` RETURNS; this closure runs before that, with `handler` already live).
+      notifyWrites: (inv) => handler.notifyWrites(inv),
+      subscribedGlobalTables: () => handler.subscribedGlobalTables(),
+      // M2c fix: plain delegation, same reasoning as the two hooks above — `handler` is already
+      // constructed by the time this `driverCtx` object is built.
+      onGlobalSubscribe: (cb) => handler.onGlobalSubscribe(cb)
+    };
+    const tableNumberToName = /* @__PURE__ */ new Map();
+    rebuildTableNumberToName(tableNumberToName, options.tableNumbers ?? {});
+    const namesForCommit = (tableIds) => translateTableIds(tableIds, tableNumberToName);
+    adapter.subscribe((payload) => {
+      handler.registerOriginResponseGate(payload.commitTs, payload.origin);
+      queue.push({
+        tables: payload.tables,
+        ranges: payload.ranges,
+        commitTs: payload.commitTs,
+        origin: payload.origin,
+        writtenDocs: payload.writtenDocs
+      });
+      void drain();
+      if (commitSubs.size > 0) {
+        fireCommitSubs(commitSubs, { tables: namesForCommit(payload.tables), ranges: payload.ranges, commitTs: payload.commitTs });
+      }
+    });
+    if ((options.drivers?.length ?? 0) > 0 && !options.tableNumbers) {
+      console.warn(
+        "[runtime] drivers registered but no `tableNumbers` provided \u2014 driver reactive wake (onCommit) will not match table-name filters; drivers will fall back to their own timers only."
+      );
+    }
+    const drivers = options.drivers ?? [];
+    let driversStarted = false;
+    if (!options.deferDrivers) {
+      for (const d of drivers) await d.start(driverCtx);
+      driversStarted = true;
+    }
+    return new _EmbeddedRuntime(
+      options.store,
+      executor,
+      handler,
+      adapter,
+      modules,
+      systemModules,
+      adminModules,
+      componentNames,
+      contextProviders,
+      policyRegistry,
+      policyProviders,
+      relationRegistry,
+      drivers,
+      timers,
+      fireDueTimers,
+      tableNumberToName,
+      oracle,
+      queryOracle,
+      transactor,
+      driverCtx,
+      driversStarted,
+      options.writeRouter,
+      numShards,
+      options.catalog,
+      commitSubs
+    );
+  }
+  /**
+   * 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).
+   */
+  functionKind = (path) => this.modules[path]?.type;
+  /** Hot-swap the function map (dev reload) without disturbing the store/transactor. */
+  setModules(modules) {
+    for (const key of Object.keys(this.modules)) delete this.modules[key];
+    Object.assign(this.modules, modules);
+  }
+  /**
+   * 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) {
+    rebuildTableNumberToName(this.tableNumberToName, tableNumbers);
+  }
+  /**
+   * 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) {
+    if (this.commitSubs.size === 0) return;
+    fireCommitSubs(this.commitSubs, { tables: translateTableIds(inv.tables, this.tableNumberToName), ranges: inv.ranges, commitTs: inv.commitTs });
+  }
+  /**
+   * 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() {
+    return Object.keys(this.modules);
+  }
+  /** Live view of the registered table names (mirrors `functionPaths`, reads the live map). */
+  tableNames() {
+    return [...this.tableNumberToName.values()];
+  }
+  /** Open an in-process connection an unmodified client can talk to. */
+  connect(sessionId) {
+    return createLoopbackConnection(this.handler, sessionId ?? `session-${++this.sessionCounter}`);
+  }
+  /**
+   * 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`.
+   */
+  forwardedResult(value) {
+    return { value: jsonToConvex(value), logs: [], committed: true, commitTs: 0n, readRanges: [], oplog: null };
+  }
+  /** 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. */
+  async run(path, args, opts) {
+    if (isInternalPath(path)) throw new FunctionNotFoundError(`unknown function: ${path}`);
+    const fn = this.modules[path];
+    if (!fn) throw new FunctionNotFoundError(`unknown function: ${path}`);
+    if (fn.type === "action" && this.writeRouter && !this.writeRouter.isLocalWriter(DEFAULT_SHARD)) {
+      const res = await this.writeRouter.forward("action", path, args, opts?.identity ?? null, DEFAULT_SHARD);
+      return this.forwardedResult(res.value);
+    }
+    if (fn.type === "mutation" && opts?.dedup) {
+      return this.runMutationClassified(fn, path, args, opts.identity ?? null, opts.dedup, opts.commitMeta);
+    }
+    return this.executor.run(fn, jsonToConvex(args), {
+      path,
+      namespace: namespaceForPath(path, this.componentNames),
+      contextProviders: this.contextProviders,
+      policyRegistry: this.policyRegistry,
+      policyProviders: this.policyProviders,
+      relationRegistry: this.relationRegistry,
+      functionKind: this.functionKind,
+      identity: opts?.identity ?? null,
+      numShards: this.numShards,
+      // Fleet B3, D3 (effectively-once forwarding): opaque commit metadata threaded straight through
+      // to `Transactor.runInTransaction`'s `commitMeta` — meaningful only for a mutation that
+      // actually commits (see `RunOptions.commitMeta`'s doc comment). `packages/cli`'s `/_fleet/run`
+      // handler is the one caller that sets this, carrying a forwarded write's idempotency key.
+      commitMeta: opts?.commitMeta
+    });
+  }
+  /**
+   * 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).
+   */
+  async runMutationClassified(fn, path, args, identity, dedup, base) {
+    const pre = await classifyDedup(this.store, identity, dedup);
+    if (pre) return this.replayResult(pre);
+    const commitMeta = dedupCommitMeta(identity, dedup, base);
+    let r;
+    try {
+      r = await this.executor.run(fn, jsonToConvex(args), {
+        path,
+        namespace: namespaceForPath(path, this.componentNames),
+        contextProviders: this.contextProviders,
+        policyRegistry: this.policyRegistry,
+        policyProviders: this.policyProviders,
+        relationRegistry: this.relationRegistry,
+        functionKind: this.functionKind,
+        identity,
+        numShards: this.numShards,
+        commitMeta
+      });
+    } catch (e) {
+      const replay = await handleDedupError(this.store, identity, dedup, e);
+      if (replay) return this.replayResult(replay);
+      throw e;
+    }
+    if (!r.committed) {
+      await recordZeroWriteApplied(this.store, identity, dedup, r.commitTs, r.value);
+    } else if (r.oplog !== null) {
+      await fillWriteMutationValue(this.store, identity, dedup, r.value);
+    }
+    return r;
+  }
+  /** Wrap a {@link ClientReplay} as a `UdfResult` carrying `clientReplay` — no commit happened. */
+  replayResult(replay) {
+    return {
+      value: jsonToConvex(replay.value ?? null),
+      logs: [],
+      committed: false,
+      commitTs: replay.commitTs !== void 0 ? BigInt(replay.commitTs) : 0n,
+      readRanges: [],
+      oplog: null,
+      clientReplay: replay
+    };
+  }
+  /** 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. */
+  async runAction(path, args, opts) {
+    if (isInternalPath(path)) throw new FunctionNotFoundError(`unknown function: ${path}`);
+    const fn = this.modules[path];
+    if (!fn) throw new FunctionNotFoundError(`unknown function: ${path}`);
+    if (fn.type !== "action") throw new Error(`${path} is not an action`);
+    if (this.writeRouter && !this.writeRouter.isLocalWriter(DEFAULT_SHARD)) {
+      const res = await this.writeRouter.forward("action", path, args, opts?.identity ?? null, DEFAULT_SHARD);
+      return this.forwardedResult(res.value);
+    }
+    return this.executor.run(fn, jsonToConvex(args), {
+      path,
+      namespace: namespaceForPath(path, this.componentNames),
+      contextProviders: this.contextProviders,
+      policyRegistry: this.policyRegistry,
+      policyProviders: this.policyProviders,
+      relationRegistry: this.relationRegistry,
+      functionKind: this.functionKind,
+      identity: opts?.identity ?? null,
+      numShards: this.numShards
+    });
+  }
+  /** 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. */
+  async runHttpAction(path, request, opts) {
+    if (isInternalPath(path)) throw new FunctionNotFoundError(`unknown function: ${path}`);
+    const fn = this.modules[path];
+    if (!fn) throw new FunctionNotFoundError(`unknown function: ${path}`);
+    if (fn.type !== "httpAction") throw new Error(`${path} is not an httpAction`);
+    const result = await this.executor.run(fn, request, {
+      path,
+      namespace: namespaceForPath(path, this.componentNames),
+      contextProviders: this.contextProviders,
+      policyRegistry: this.policyRegistry,
+      policyProviders: this.policyProviders,
+      relationRegistry: this.relationRegistry,
+      functionKind: this.functionKind,
+      identity: opts?.identity ?? null,
+      numShards: this.numShards
+    });
+    return result.value;
+  }
+  /**
+   * 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.
+   */
+  static DOC_MUTATION_PATHS = /* @__PURE__ */ new Set([
+    "_system:patchDocument",
+    "_system:deleteDocument",
+    "_system:insertDocument"
+  ]);
+  /** 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. */
+  async runSystem(path, args, opts) {
+    const fn = this.systemModules[path];
+    if (!fn) throw new FunctionNotFoundError(`unknown system function: ${path}`);
+    let shardId = opts?.shardId;
+    if (shardId === void 0 && this.numShards > 1 && _EmbeddedRuntime.DOC_MUTATION_PATHS.has(path)) {
+      shardId = await this.resolveDocMutationShard(path, args);
+    }
+    return this.executor.run(fn, jsonToConvex(args), {
+      path,
+      privileged: true,
+      numShards: this.numShards,
+      shardId,
+      // Fleet B3, D3: see `run()`'s doc comment above — the forwarded-`_system:*`-doc-mutation path
+      // (an admin dashboard edit landing on a non-owner) threads the same idempotency key through.
+      commitMeta: opts?.commitMeta
+    });
+  }
+  /**
+   * 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`.
+   */
+  async resolveDocMutationShard(path, args) {
+    const a = args;
+    if (path === "_system:insertDocument") {
+      const meta2 = this.catalog.getTable(a.table);
+      if (!meta2?.shardKey) return DEFAULT_SHARD;
+      const fields = a.fields;
+      return shardIdForKeyValue(fields?.[meta2.shardKey], this.numShards);
+    }
+    const internalId = decodeDocumentId(a.id);
+    const meta = this.catalog.getTableByNumber(internalId.tableNumber);
+    if (!meta?.shardKey) return DEFAULT_SHARD;
+    const latest = await this.store.get(internalId);
+    if (!latest) return DEFAULT_SHARD;
+    const doc = latest.value.value;
+    return shardIdForKeyValue(doc[meta.shardKey], this.numShards);
+  }
+  /** Run a privileged admin built-in (`_admin:*`) once (e.g. for the HTTP fallback). Trusted callers only. */
+  async runAdmin(path, args) {
+    const fn = this.adminModules[path];
+    if (!fn) throw new FunctionNotFoundError(`unknown admin function: ${path}`);
+    return this.executor.run(fn, jsonToConvex(args), { path, privileged: true, numShards: this.numShards });
+  }
+  /**
+   * 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() {
+    this.fireDue();
+  }
+  /**
+   * 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.
+   */
+  async stopDriversInternal() {
+    for (const t of this.timers.values()) if (t.timeout !== void 0) clearTimeout(t.timeout);
+    this.timers.clear();
+    for (const d of this.drivers) await d.stop?.();
+    this.driversStarted = false;
+  }
+  /**
+   * 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.
+   */
+  async stopDrivers() {
+    await this.stopDriversInternal();
+    this.handler.dispose();
+  }
+  /**
+   * 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).
+   */
+  async stopDriversOnly() {
+    await this.stopDriversInternal();
+  }
+  /**
+   * 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).
+   */
+  async startDrivers() {
+    if (this.driversStarted) return;
+    this.driversStarted = true;
+    for (const d of this.drivers) await d.start(this.driverCtx);
+  }
+  /**
+   * 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) {
+    (this.queryOracle ?? this.oracle).observeTimestamp(ts);
+  }
+  /**
+   * 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) {
+    this.oracle.observeTimestamp(ts);
+  }
+  /**
+   * 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, fn) {
+    return this.transactor.tryRunExclusiveOnShard(shardId, fn);
+  }
+  /**
+   * 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() {
+    return this.transactor.groupCommitStats();
+  }
+};
+function createEmbeddedRuntime(options) {
+  return EmbeddedRuntime.create(options);
+}
+export {
+  EmbeddedRuntime,
+  EmbeddedWriteFanout,
+  InMemoryWriteFanoutAdapter,
+  clientReceiptsGuard,
+  createEmbeddedRuntime,
+  createLoopbackConnection
+};
+//# sourceMappingURL=index.js.map