@lunora/platform-node 1.0.0-alpha.16 → 1.0.0-alpha.160

package/dist/index.d.ts

@@ -1,9 +1,43 @@
 import { SchemaLike } from '@lunora/shard-engine';
 import { SqlCtxDbOptions, SqlCtxExec, createSqlCtxDb } from '@lunora/sql-store';
 import Database from 'better-sqlite3';
-import { ShardKvStore, QueueBindingLike, MessageBatchLike, SchedulerHost, ShardHost, SocketHost, DirectShardDirectory, PlatformCapabilities, ShardDirectory, R2BucketLike, SocketHandle } from '@lunora/platform';
+import { ShardKvStore, QueueBindingLike, MessageBatchLike, SchedulerHost, ShardHost, SocketHandle, SocketHost, DirectShardDirectory, PlatformCapabilities, ShardDirectory, R2BucketLike } from '@lunora/platform';
 import { WorkflowBindingLike } from '@lunora/workflow';
 import { WorkflowRuntime, WorkflowStore } from '@visulima/workflow';
+import { ShardNamespaceLike } from '@lunora/runtime';
+/** One function call the route has authenticated and parsed. */
+interface NodeDispatchInvocation {
+  args: Record<string, unknown>;
+  functionPath: string;
+  /** The scheduler record or delivery id, used as the shard's idempotency key. */
+  id: string | undefined;
+  /** Identity the trusted caller forwarded, if any. */
+  identity: {
+    identity?: string;
+    userId?: string;
+  } | undefined;
+  shardKey: string;
+  traceparent: string | undefined;
+}
+interface NodeDispatchRouteOptions {
+  /** `LUNORA_ADMIN_TOKEN`. Used as the bearer when no HMAC signature is presented. */
+  adminToken?: string;
+  /** The shard a body without `shardKey` is sent to. */
+  defaultShardKey: string;
+  /** Runs the call in-process and returns the shard's response, unchanged. */
+  invoke: (call: NodeDispatchInvocation) => Promise<Response>;
+  /** `LUNORA_SCHEDULER_SECRET`. When set, a signed request is verified against it. */
+  schedulerSecret?: string;
+}
+/**
+ * Build the dispatch route. The returned function answers any request it is
+ * handed; mounting it at {@link NODE_SCHEDULER_DISPATCH_PATH} is the caller's job.
+ * With neither secret configured every request is refused, so an unconfigured
+ * route fails closed.
+ */
+declare const createNodeDispatchRoute: (options: NodeDispatchRouteOptions) => ((request: Request) => Promise<Response>);
+/** The path `@lunora/dispatch` and `@lunora/scheduler` POST to. */
+declare const NODE_SCHEDULER_DISPATCH_PATH: "/_lunora/scheduler/dispatch";
 /**
  * The Node store options — the shared store options minus the two this binding
  * owns. `dialect` is fixed (SQLite) and `exec` is the store's own connection;
@@ -14,13 +48,14 @@ type NodeGlobalContextDatabaseOptions = Omit<SqlCtxDbOptions, "dialect" | "exec"
 /**
  * Wrap a `better-sqlite3` connection as the async exec the store core consumes.
  *
- * `batch` is deliberately **not** implemented. The contract lets an exec that
- * omits it fall back to a sequential `run()` loop, and that fallback is already
- * optimal here: `batch` exists to collapse network round trips (D1 does it
- * atomically in one request; the Hyperdrive adapters dispatch concurrently over
- * a pool), and an embedded database has no round trip to collapse. Declaring it
- * would buy nothing and would opt this exec into the "MAY reorder or
- * parallelize" licence for no reason.
+ * `batch` runs the statements in order inside one `better-sqlite3`
+ * transaction, which is synchronous, so nothing else runs between them. There is
+ * no round trip to save; atomicity is the point. The store core's FTS5 search
+ * companion writes each document as an ordered list of statements, and without
+ * this two async writers interleaved at every `await` between them: one could
+ * move a document's mapping while the other's entry was mid-write, leaving an
+ * entry no later write or purge could reach. The `sqlite` dialect's contract
+ * requires an ordered, atomic `batch` for exactly that reason.
  */
 declare const createNodeSqlExec: (database: Database.Database) => SqlCtxExec;
 /** Options for {@link createNodeGlobalStore}. */
@@ -63,6 +98,32 @@ interface NodeGlobalStore {
  * which is the whole point of the dialect seam.
  */
 declare const createNodeGlobalStore: (options?: NodeGlobalStoreOptions) => NodeGlobalStore;
+/** Serve `options.fetch` over `node:http`. Resolves once the server is listening. */
+declare const createNodeHttpServer: (options: NodeHttpServerOptions) => Promise<NodeHttpServer>;
+/** Options for {@link createNodeHttpServer}. */
+interface NodeHttpServerOptions {
+  /** The app worker's `fetch`, already bound to its env and context. */
+  fetch: (request: Request) => Promise<Response> | Response;
+  /** Host to bind. Defaults to the loopback interface. */
+  host?: string;
+  /**
+   * The public base URL the app is served at, e.g. `https://app.example`. Every request URL uses its origin, so origin-sensitive
+   * behaviour (CSRF, WebSocket origin checks, cookie rules) sees the public scheme behind a TLS proxy. The client's `Host` header is
+   * never used. Defaults to the bound `http://host:port`, which is only allowed for a loopback `host`: binding a non-loopback address
+   * (e.g. `0.0.0.0` or a LAN IP) without `origin` makes {@link createNodeHttpServer} reject, because browsers would send that address
+   * as `Origin` and fail the CSRF check. Set `origin` to the URL users open.
+   */
+  origin?: string;
+  /** Port to bind. `0` (the default) picks a free ephemeral port. */
+  port?: number;
+}
+/** A listening server. */
+interface NodeHttpServer {
+  /** Stop accepting connections and end every open one, streams included. */
+  close: () => Promise<void>;
+  /** The `http://host:port` origin the server answers on. */
+  origin: string;
+}
 /** Build a `ShardKvStore` over a `better-sqlite3` table in the shard's database. */
 declare const createNodeShardKvStore: (database: Database.Database) => ShardKvStore;
 /** Options for {@link createNodeQueueHost}. */
@@ -197,9 +258,12 @@ interface NodeShardHostOptions {
    * `_lunora_alarm` when the host is constructed over an existing database,
    * including an alarm whose time elapsed while nothing was running.
    *
-   * A handler that throws is isolated to its own delivery; it never reaches
+   * A handler that throws is isolated to its own delivery — it never reaches
    * the caller that set the alarm, because by then that call has long
-   * returned.
+   * returned — and the wakeup is then re-delivered with backoff up to
+   * {@link ALARM_RETRY_LIMIT} times, the way workerd retries a throwing
+   * `alarm()`. Delivery is at-least-once, so the handler must tolerate
+   * running twice for one scheduled timestamp.
    */
   onAlarm?: () => Promise<void> | void;
   /**
@@ -218,25 +282,59 @@ interface NodeShardHostOptions {
 /**
  * Build a `ShardHost` over a real `better-sqlite3` database.
  *
- * `runSerialized` chains onto a single `tail` promise rather than the
- * reference host's explicit job-array-plus-drain-loop: every queued closure
- * runs once `tail` settles, and `tail` is reset to a version that always
- * resolves (never rejects) so one job's failure cannot wedge the queue for
- * every job after it — the same "no two closures interleave" guarantee,
- * fewer moving parts to get wrong.
+ * `runSerialized` and `transaction` share **one** boundary lock, because they
+ * write **one** `better-sqlite3` connection. `transaction` issues raw
+ * `BEGIN`/`COMMIT`/`ROLLBACK` — legal here (unlike inside a Cloudflare Durable
+ * Object, where the runtime forbids it and callers must use
+ * `storage.transaction`) because better-sqlite3 is a plain embedded database
+ * with no platform-level transaction primitive layered over it.
+ *
+ * ## Why one lane and not two
+ *
+ * This host shipped with two private tail chains, one per entry point, so each
+ * serialized against itself and neither against the other. `runSerialized`
+ * issues no `BEGIN` of its own, so one of its closures overlapping a bare
+ * `transaction()` wrote straight into that transaction's span. `assertOwnTurn`
+ * below catches the write — it is the only reason this host never silently lost
+ * one the way an unguarded connection would — but catching it is not the same
+ * as preventing it, and the refusal lands in the wrong place:
  *
- * `transaction` issues raw `BEGIN`/`COMMIT`/`ROLLBACK` — legal here (unlike
- * inside a Cloudflare Durable Object, where the runtime forbids it and
- * callers must use `storage.transaction`) because better-sqlite3 is a plain
- * embedded database with no platform-level transaction primitive layered over
- * it. It runs on its own private `transactionTail` chain, the same shape as
- * `runSerialized`'s but never shared with it: two bare, overlapping
- * `transaction()` calls on this host serialize against each other rather than
- * corrupting each other's commits (raw `BEGIN` on a connection already inside
- * a transaction throws, or worse, interleaves). Routing `transaction` through
- * `runSerialized` itself would deadlock, since the engine already composes
- * `runSerialized(() => transaction(work))` — the inner enqueue would then wait
- * on the outer closure awaiting it.
+ * 1. A `runSerialized` closure writes a row. Nothing is open, so it commits.
+ * 2. It awaits (a scheduler hop, an `onShardInit` read, any real I/O).
+ * 3. A bare `transaction()` runs `BEGIN` while it is parked. `transaction` is
+ * a public contract surface, and `./node-shard-state` re-exports it as the
+ * `storage.transaction` member `ShardDO` documents as "the platform
+ * primitive", so a subclass reaches one without going through the engine.
+ * 4. The closure resumes and its next write is refused with
+ * `SHARD_UNAVAILABLE`, so `runSerialized` **rejects** — with step 1 already
+ * durable.
+ *
+ * The boundary the contract promises is atomic-or-nothing to its caller tore in
+ * half: a rejection the caller will retry, on top of a write the retry now
+ * re-applies. That is `runSerialized`'s "no two closures interleave" guarantee
+ * broken by a `transaction` it was never serialized against.
+ *
+ * ## Why the lock is re-entrant, and why `AsyncLocalStorage` is what makes it so
+ *
+ * The engine composes the two, and stacks them: `ShardRunner.runInTransaction`
+ * is `runSerialized(() => transaction(work))` (`@lunora/shard-engine`), and
+ * `ShardDO.fetch` widens a mutation dispatch carrying `x-lunora-mutation-id`
+ * into a *further* `runSerialized` span around it (`@lunora/do`). Under two
+ * plain FIFO chains that outer span is already fatal on this host — the inner
+ * `runSerialized` waits on a `tail` that only settles when the outer closure it
+ * is running inside resolves, and because nothing ever resets that `tail`, the
+ * shard's write lane is wedged for the life of the process rather than for the
+ * life of the request.
+ *
+ * So the lock is skipped for a boundary opened from inside a boundary, and
+ * `AsyncLocalStorage` is the only thing that can tell that case from the one
+ * that must queue: its store follows a single call's own await chain without
+ * leaking into a sibling chain. A held boolean cannot — it reads `true` for an
+ * unrelated *second top-level* `transaction()` too, which would then nest a raw
+ * `BEGIN` on a connection already inside one. This is the same distinction
+ * workerd's `blockConcurrencyWhile` draws natively with "does not queue events
+ * initiated as part of the callback itself", which is what
+ * `@lunora/platform-cloudflare` leans on for the identical composition.
  *
  * The returned `dispose()` is this host's lifecycle owner: it clears the
  * pending alarm `setTimeout` (so it can never fire against a connection this
@@ -252,8 +350,55 @@ declare const createNodeShardHost: (options?: NodeShardHostOptions) => {
   drain: () => Promise<void>;
   host: ShardHost;
 };
+/** The end a shard accepts. Its `send` and `close` are what the socket host calls through its handle. */
+interface NodeServerEnd {
+  close: (code?: number, reason?: string) => void;
+  send: (data: string | ArrayBuffer) => void;
+}
+/**
+ * The socket-host half of a Node platform instance, plus the test-only hooks
+ * `@lunora/platform/conformance`'s `ConformanceHost` needs to drive a recycle
+ * from inside a test.
+ */
+interface NodeSocketHost {
+  /**
+   * Wait for every close handler still running, including ones they start. `undefined` when none are,
+   * so a caller can dispose synchronously.
+   */
+  drain: () => Promise<void> | undefined;
+  /** Deliver a connection's close to `handler`, which calls `webSocketClose`. One handler per host. */
+  onClose: (handler: (socket: NodeServerEnd, code: number, reason: string, wasClean: boolean) => void | Promise<void>) => void;
+  /**
+   * Deliver a connection's inbound frames to `handler`. The handler is the
+   * shard that accepted the connection, so it calls `webSocketMessage`. One
+   * handler per host: a later call replaces the earlier one.
+   */
+  onMessage: (handler: (socket: NodeServerEnd, data: string | ArrayBuffer) => void) => void;
+  /** Read back the frames sent to a socket, oldest first, text frames only. */
+  readFrames: (handle: SocketHandle) => string[];
+  /**
+   * Re-create a runtime socket from durable state.
+   *
+   * `attachment` is a fallback only: this host restores what it persisted,
+   * because that is what a real wake looks like. The argument covers an id
+   * this host never durably tracked (a synthetic id a test constructs).
+   */
+  restoreSocket: (id: string, attachment: unknown) => SocketHandle;
+  /** Drop the runtime socket map while keeping durable attachments/tags. */
+  simulateRecycle: () => void;
+  /** The `SocketHost` contract implementation. */
+  socket: SocketHost;
+}
+/** Build the socket registry, persisting attachments and tags to `database`. */
+declare const createNodeSocketHost: (database: Database.Database) => NodeSocketHost;
 /** The contracts scoped to one shard key. */
 interface NodeShard {
+  /**
+   * Inbound socket events for this shard's registry. Bind the shard that owns
+   * the sockets here, so a frame or close reaches its `webSocketMessage` and
+   * `webSocketClose`. See `bindShardSockets`.
+   */
+  inbound: Pick<NodeSocketHost, "onClose" | "onMessage">;
   /** Durable key-value storage on this shard's database. */
   kv: ShardKvStore;
   /** Single-writer execution, local SQL, transactions, durable alarms. */
@@ -310,22 +455,65 @@ interface NodeShardRegistry {
 }
 /** Build the in-process shard registry. */
 declare const createNodeShardRegistry: (options?: NodeShardRegistryOptions) => NodeShardRegistry;
+/** Options for {@link createNodeWorkflowHost}. */
+interface NodeWorkflowHostOptions<Workflows extends Record<string, {
+  isLunoraWorkflow: true;
+}>> {
+  /** Base env merged under the derived workflow bindings — surfaced to workflow bodies as `ctx.env` and used to resolve spawned children. */
+  env?: Record<string, unknown>;
+  /** How long (ms) the engine holds a cross-process lease while an activation runs, for stores that implement `acquire`. Defaults to 30000. */
+  leaseTtlMs?: number;
+  /** Where runs are persisted. Required — see the header for why there is no default. `createNodeWorkflowStore(database)` is the durable one. */
+  store: WorkflowStore;
+  /** The declared workflows keyed by their `lunora/workflows.ts` export name (e.g. `{ orderPipeline: orderPipeline }`). Values must be `defineWorkflow` results. */
+  workflows: Workflows;
+}
+/** A fully-wired Node workflow host. */
+interface NodeWorkflowHost<Workflows extends Record<string, {
+  isLunoraWorkflow: true;
+}>> {
+  /** Per-export-name `WorkflowBindingLike` — the map `ctx.workflows` consumes. */
+  readonly bindings: { [K in keyof Workflows]: WorkflowBindingLike; };
+  /**
+   * The caller's `env` plus one binding per workflow under its class name
+   * (`OrderPipelineWorkflow`), the key `ctx.exports` would carry on Cloudflare —
+   * merge this into a worker env so `ctx.spawn`/`ctx.parallel` resolve
+   * children through the same runtime.
+   */
+  readonly env: Record<string, unknown>;
+  /** The underlying visulima runtime — `sweep`/`signal` for a dev loop or tests. */
+  readonly runtime: WorkflowRuntime;
+}
+/**
+ * Create a Node workflow host: compile every declared Lunora workflow onto the
+ * visulima engine, derive the workflow env, and expose the per-workflow
+ * `WorkflowBindingLike` handles.
+ */
+declare const createNodeWorkflowHost: <Workflows extends Record<string, {
+  isLunoraWorkflow: true;
+}>>(options: NodeWorkflowHostOptions<Workflows>) => NodeWorkflowHost<Workflows>;
 /** Every contract this package provides, composed for one Node process. */
 interface NodePlatform<Queues extends Record<string, {
   isLunoraQueue: true;
+}> = Record<string, never>, Workflows extends Record<string, {
+  isLunoraWorkflow: true;
 }> = Record<string, never>> {
   /** `using platform = createNodePlatform(...)` support — delegates to `close()`. */
   [Symbol.dispose]: () => void;
   /** What this target supports — see `NODE_CAPABILITIES` in `@lunora/platform`. */
   capabilities: PlatformCapabilities;
   /**
-   * Tear this platform instance down: clears the shard host's pending alarm
-   * timer and closes its `better-sqlite3` database (and, with it, `kv`'s
-   * table — both live on the same connection), then clears every armed
-   * scheduler job timer. Nothing in this package closes these resources on
-   * its own — a `NodePlatform` a caller stops using without calling `close()`
-   * leaks the open file handle (plus its WAL/SHM sidecar files) and keeps
-   * the process alive on outstanding timers. Safe to call more than once.
+   * Tear this platform instance down: every resource this root built, in
+   * reverse construction order — the global store's own connection, every
+   * armed scheduler job timer, the registry's live shards, and last the shard
+   * host's pending alarm timer and its `better-sqlite3` database (and, with
+   * it, `kv`'s table — both live on the same connection). Nothing in this
+   * package closes these resources on its own — a `NodePlatform` a caller
+   * stops using without calling `close()` leaks the open file handles (plus
+   * their WAL/SHM sidecar files) and keeps the process alive on outstanding
+   * timers. Safe to call more than once. A `createNodePlatform` that throws
+   * unwinds the same list itself, so a failed construction leaks nothing and
+   * leaves nothing to call this on.
    *
    * **`close()` is a terminal state, not merely a cleanup step.** After it
    * runs: `scheduler.schedule()` throws instead of arming a fresh timer
@@ -335,13 +523,25 @@ interface NodePlatform<Queues extends Record<string, {
    * benign); `shard.alarms.set()`/`delete()` throw before mutating any
    * in-memory state (checked against the connection's own open/closed state,
    * the single source of truth); `shard.alarms.get()` keeps answering
-   * whatever it last held. A no-op instead of a throw would be
-   * indistinguishable from a working call — exactly the silent-vanishing
+   * whatever it last held; `sockets.accept()`/`setTag()`/`removeTag()` throw
+   * the same way, checked against the same connection state, before touching
+   * any runtime socket map or durable row. A no-op instead of a throw would
+   * be indistinguishable from a working call — exactly the silent-vanishing
    * this lifecycle exists to end.
    */
   close: () => void;
   /** In-process shard directory (see `createNodeShardRegistry` for what it can and cannot do). */
   directory: ShardDirectory;
+  /**
+   * The scheduler dispatch route, served in-process: `Request` in, shard
+   * response out, no listener. It answers the path `@lunora/dispatch` and
+   * `@lunora/scheduler` POST to. Pass it to `dispatchQueueBatch` as
+   * `queueFetchImpl` on `createWorker` so a queue handler's `message.run` /
+   * `ctx.run` reaches the shard; the env you pass there must carry `LUNORA_ORIGIN_URL` and the same
+   * `LUNORA_ADMIN_TOKEN` as `dispatch.adminToken`. Every request is refused
+   * unless `dispatch` supplies a secret.
+   */
+  dispatch: (request: Request) => Promise<Response>;
   /**
    * Wait for every promise handed to `shard.waitUntil` to settle.
    *
@@ -351,8 +551,28 @@ interface NodePlatform<Queues extends Record<string, {
    * shutdown is `await platform.drain()` then `platform.close()`.
    */
   drain: () => Promise<void>;
+  /**
+   * The `.global()` backend, or `undefined` when the caller named no database
+   * file for it. There is no default path, because a global store silently
+   * rooted at `:memory:` loses every row when the process exits.
+   *
+   * **A building block, not a wiring.** Unlike its three siblings, nothing
+   * downstream of this composition root reads it: a `.global()` read or write
+   * reaches its backend through exactly one seam, `createShardCtxDb({ globalDb
+   * })`, and the only thing that passes `globalDb` is the generated `shard.ts`,
+   * from its `d1` / `hyperdriveGlobal` config thunks. `createNodePlatform`
+   * constructs no shard DO, so it cannot make that hop itself. A caller that
+   * wants `.global()` on this host makes it: after `migrate(schema)` has
+   * provisioned the tables, give the generated `createShardDO` a `d1` thunk
+   * returning `platform.globalTables.writer({ schema, … })` — `writer` builds
+   * the `createSqlCtxDb` facade that seam expects, and `node-platform.test.ts`
+   * round-trips a row through exactly that object.
+   */
+  globalTables?: NodeGlobalStore;
   /** Durable key-value storage backed by the same `better-sqlite3` database as `shard`. */
   kv: ShardKvStore;
+  /** The local-filesystem bucket, or `undefined` when the caller named no bucket directory. */
+  objectStorage?: R2BucketLike;
   /**
    * The declared queues, or `undefined` when the caller declared none.
    *
@@ -367,6 +587,28 @@ interface NodePlatform<Queues extends Record<string, {
   shard: ShardHost;
   /** Socket registry with mutable tags and SQLite-persisted attachments. */
   sockets: SocketHost;
+  /**
+   * The declared workflows, or `undefined` when the caller declared none.
+   * Runs are persisted to the same `better-sqlite3` database as the shard, so
+   * they survive a restart without a second store to configure.
+   */
+  workflows?: NodeWorkflowHost<Workflows>;
+}
+/**
+ * The secrets the dispatch route authenticates with. With neither, the route
+ * refuses everything.
+ *
+ * Queue and topic delivery authenticates with `adminToken` alone:
+ * `@lunora/dispatch` always sends `Bearer <LUNORA_ADMIN_TOKEN>` and never signs,
+ * so the value here must match the token the caller puts on the env it passes
+ * `dispatchQueueBatch`. `schedulerSecret` only verifies a signed body, which the
+ * scheduler's own delivery sends; queue delivery never does.
+ */
+interface NodePlatformDispatchOptions {
+  /** `LUNORA_ADMIN_TOKEN`. The bearer queue and topic delivery sends, so it must match the caller's env. */
+  adminToken?: string;
+  /** `LUNORA_SCHEDULER_SECRET`. When set, a signed body is verified against it. Queue delivery does not sign. */
+  schedulerSecret?: string;
 }
 /**
  * Options for {@link createNodePlatform} — the shard host's (`path`,
@@ -376,23 +618,58 @@ interface NodePlatform<Queues extends Record<string, {
  * or job with nowhere to land is bookkeeping. `directory` makes the shards the
  * directory resolves for fan-out file-backed too, and `onAlarm` gives their
  * durable alarms somewhere to land.
+ *
+ * `queues`, `workflows`, `objectStorageDirectory` and `globalTablesPath` are the
+ * four declarations — each is absent from the returned platform when omitted.
  */
 type NodePlatformOptions<Queues extends Record<string, {
   isLunoraQueue: true;
+}> = Record<string, never>, Workflows extends Record<string, {
+  isLunoraWorkflow: true;
 }> = Record<string, never>> = {
+  /** Secrets for the dispatch route. Omit to leave the route refusing every request. */
+  dispatch?: NodePlatformDispatchOptions;
+  /**
+   * Database file the `.global()` tables live in — its own file, never a
+   * shard's, because a table every shard reads must not be inside any one of
+   * them. Omit when the app declares no `.global()` table; there is no
+   * default, for the same reason the bucket has none.
+   */
+  globalTablesPath?: string;
   /**
-   * Deliver one assembled queue batch — wire this to `dispatchQueueBatch`.
-   * Required alongside `queues`; without it the messages would be stored
-   * and never consumed.
+   * Directory the object-storage bucket keeps its objects in, one file per
+   * key. Omit when the app declares no buckets — there is no default,
+   * because a bucket silently rooted at the process's working directory is
+   * worse than an absent one.
+   */
+  objectStorageDirectory?: string;
+  /**
+   * Deliver one assembled queue batch — wire this to the app worker's `queue`
+   * export from `createWorker`, not to bare `dispatchQueueBatch`. That export
+   * is the only path that hands the consumer `ctx.live`, and it takes
+   * `queueFetchImpl` (this platform's `dispatch`, wrapped as a `fetch`) so
+   * `ctx.run` reaches the shard here rather than `LUNORA_ORIGIN_URL`. Required
+   * alongside `queues`; without it the messages would be stored and never consumed.
    */
   onQueueBatch?: NodeQueueHostOptions<Queues>["onBatch"];
   /** The app's `defineQueue` results, keyed by export name. Omit when the app declares no queues. */
   queues?: Queues;
+  /** The app's `defineWorkflow` results, keyed by export name. Omit when the app declares no workflows. */
+  workflows?: Workflows;
 } & NodeSchedulerHostOptions & NodeShardHostOptions & NodeShardRegistryOptions;
 /** Compose every contract this package provides over one `better-sqlite3` database. */
 declare const createNodePlatform: <Queues extends Record<string, {
   isLunoraQueue: true;
-}> = Record<string, never>>(options?: NodePlatformOptions<Queues>) => NodePlatform<Queues>;
+}> = Record<string, never>, Workflows extends Record<string, {
+  isLunoraWorkflow: true;
+}> = Record<string, never>>(options?: NodePlatformOptions<Queues, Workflows>) => NodePlatform<Queues, Workflows>;
+interface NodeProfileHandlerOptions {
+  /** The bearer a caller must present. Required and non-empty: an empty token would make the endpoint open to anyone. */
+  token: string;
+}
+type NodeProfileHandler = (request: Request) => Promise<Response>;
+/** The public handler: the real profiler, guarded by `token`. */
+declare const createNodeProfileHandler: ({ token }: NodeProfileHandlerOptions) => NodeProfileHandler;
 /** Options for {@link createNodeR2Bucket}. */
 interface NodeR2BucketOptions {
   /** The bucket directory — created on first write. Objects live here, one file per key. */
@@ -400,10 +677,19 @@ interface NodeR2BucketOptions {
 }
 /**
  * Create an `R2BucketLike` over the local filesystem. Any object shape
- * `createStorage({ bucket })` accepts — `put`/`get`/`head`/`delete`/`list` —
+ * `createStorage({ bucket, bucketName })` accepts — `put`/`get`/`head`/`delete`/`list` —
  * maps directly onto a file operation.
  */
 declare const createNodeR2Bucket: (options: NodeR2BucketOptions) => R2BucketLike;
+/**
+ * Present the node shard registry as the `ShardNamespaceLike` a worker is built
+ * over (`createWorker({ shardDO })`).
+ *
+ * The registry names its id derivation `idForName`, which is the
+ * `ShardDirectory` spelling; the worker reads Cloudflare's `idFromName`. Both
+ * return the key itself here, so a stub from either route reaches the same shard.
+ */
+declare const createNodeShardNamespace: (directory: DirectShardDirectory) => ShardNamespaceLike;
 /**
  * The `DurableObjectState` subset `ShardDO` consumes.
  *
@@ -420,6 +706,11 @@ interface NodeShardState {
   id: {
     name?: string;
   };
+  /** Open a connection pair. Read by `@lunora/platform-cloudflare`'s socket host, which has no `WebSocketPair` here. */
+  openSocketPair: () => {
+    client: unknown;
+    server: unknown;
+  };
   storage: {
     delete: (key: string) => Promise<boolean>;
     deleteAlarm: () => Promise<void>;
@@ -436,6 +727,8 @@ interface NodeShardState {
     };
     transaction: <T>(closure: () => Promise<T>) => Promise<T>;
   };
+  /** Build the upgrade response for a pair's client end. A Node `Response` cannot carry status 101, so this is a marker. */
+  upgradeResponse: (client: unknown) => Response;
   waitUntil: (promise: Promise<unknown>) => void;
 }
 /**
@@ -450,71 +743,24 @@ interface NodeShardState {
  * report a point-in-time restore that never happened.
  */
 declare const createNodeShardState: (shard: NodeShard) => NodeShardState;
-/**
- * The socket-host half of a Node platform instance, plus the test-only hooks
- * `@lunora/platform/conformance`'s `ConformanceHost` needs to drive a recycle
- * from inside a test.
- */
-interface NodeSocketHost {
-  /** Read back the frames sent to a socket, oldest first, text frames only. */
-  readFrames: (handle: SocketHandle) => string[];
-  /**
-   * Re-create a runtime socket from durable state.
-   *
-   * `attachment` is a fallback only: this host restores what it persisted,
-   * because that is what a real wake looks like. The argument covers an id
-   * this host never durably tracked (a synthetic id a test constructs).
-   */
-  restoreSocket: (id: string, attachment: unknown) => SocketHandle;
-  /** Drop the runtime socket map while keeping durable attachments/tags. */
-  simulateRecycle: () => void;
-  /** The `SocketHost` contract implementation. */
-  socket: SocketHost;
-}
-/** Build the socket registry, persisting attachments and tags to `database`. */
-declare const createNodeSocketHost: (database: Database.Database) => NodeSocketHost;
-/** Options for {@link createNodeWorkflowHost}. */
-interface NodeWorkflowHostOptions<Workflows extends Record<string, {
-  isLunoraWorkflow: true;
-}>> {
-  /** Base env merged under the derived `WORKFLOW_*` bindings — surfaced to workflow bodies as `ctx.env` and used to resolve spawned children. */
-  env?: Record<string, unknown>;
-  /** How long (ms) the engine holds a cross-process lease while an activation runs, for stores that implement `acquire`. Defaults to 30000. */
-  leaseTtlMs?: number;
-  /** Where runs are persisted. Required — see the header for why there is no default. `createNodeWorkflowStore(database)` is the durable one. */
-  store: WorkflowStore;
-  /** The declared workflows keyed by their `lunora/workflows.ts` export name (e.g. `{ orderPipeline: orderPipeline }`). Values must be `defineWorkflow` results. */
-  workflows: Workflows;
-}
-/** A fully-wired Node workflow host. */
-interface NodeWorkflowHost<Workflows extends Record<string, {
-  isLunoraWorkflow: true;
-}>> {
-  /** Per-export-name `WorkflowBindingLike` — the map `ctx.workflows` consumes. */
-  readonly bindings: { [K in keyof Workflows]: WorkflowBindingLike; };
-  /**
-   * The caller's `env` plus one `WORKFLOW_&lt;EXPORT>` binding per workflow —
-   * merge this into a worker env so `ctx.spawn`/`ctx.parallel` resolve
-   * children through the same runtime.
-   */
-  readonly env: Record<string, unknown>;
-  /** The underlying visulima runtime — `sweep`/`signal` for a dev loop or tests. */
-  readonly runtime: WorkflowRuntime;
+/** The two socket hooks a `ShardDO` runs on the Cloudflare runtime's behalf. */
+interface ShardSocketHooks {
+  webSocketClose(ws: unknown, code: number, reason: string, wasClean: boolean): unknown;
+  webSocketMessage(ws: unknown, message: string | ArrayBuffer): unknown;
 }
 /**
- * Create a Node workflow host: compile every declared Lunora workflow onto the
- * visulima engine, derive the `WORKFLOW_*` env, and expose the per-workflow
- * `WorkflowBindingLike` handles.
+ * Deliver a shard's inbound socket events. The Cloudflare runtime calls
+ * `webSocketMessage` and `webSocketClose` on the Durable Object for a hibernated
+ * socket. On Node nothing does, so the embedder calls this once per shard
+ * instance, at the same point it builds the shard.
  */
-declare const createNodeWorkflowHost: <Workflows extends Record<string, {
-  isLunoraWorkflow: true;
-}>>(options: NodeWorkflowHostOptions<Workflows>) => NodeWorkflowHost<Workflows>;
+declare const bindShardSockets: (shard: ShardSocketHooks, inbound: Pick<NodeShard["inbound"], "onClose" | "onMessage">) => void;
 /**
  * Build a durable {@link WorkflowStore} over a `better-sqlite3` connection.
  * Pass the result as `createNodeWorkflowHost({ store })`.
  */
 declare const createNodeWorkflowStore: (database: Database.Database) => WorkflowStore;
-export {
+export { NODE_SCHEDULER_DISPATCH_PATH,
 /**
  * `@lunora/platform-node` — a Node implementation of the `@lunora/platform`
  * host contracts (`ShardHost`, `SocketHost`, `ShardDirectory`, `ShardKvStore`,
@@ -534,49 +780,33 @@ export {
  * TCK, `@lunora/shard-engine/conformance`'s engine suite, and its own
  * lifecycle/global-store tests.
  *
- * **Still missing**, and rated accordingly in `NODE_CAPABILITIES`
- * (`@lunora/platform`): a dev server — so `lunora dev --target node` does not
- * exist yet — plus most Cloudflare product bindings (Queues, Vectorize, Workers
- * AI, Browser Rendering, Containers, Analytics Engine, Pipelines, Secrets Store,
- * Hyperdrive). R2 buckets are emulated over the local filesystem
- * (`./node-r2-bucket`) and Workflows over the `@visulima/workflow` engine
- * (`./node-workflow-host`). Cross-shard fan-out is emulated via
- * `@lunora/runtime`'s query coordinator over the in-process shard registry, and
- * a `@lunora/config` deploy driver makes `--target node` resolve. See
- * `plans/234-node-host-findings.md`.
- */
-type NodeGlobalContextDatabaseOptions,
-/**
- * `@lunora/platform-node` — a Node implementation of the `@lunora/platform`
- * host contracts (`ShardHost`, `SocketHost`, `ShardDirectory`, `ShardKvStore`,
- * `SchedulerHost`) over `better-sqlite3` and an in-process socket/directory/
- * scheduler registry.
- *
- * Promoted from `@lunora/platform`'s `node:sqlite` reference host
- * (`src/conformance/reference-host.ts`) under plan 234, then hardened until the
- * durability half of each contract actually holds: alarms and scheduler jobs
- * are persisted **and re-armed on construction**, socket attachments and tags
- * live in SQLite rather than a `Map`, and `.global()` tables run the real
- * `@lunora/sql-store` core (`./node-global-store`). Each of those is pinned by
- * a restart test — a second host over the same database file — not only by the
- * TCK's simulated recycle.
+ * **Emulated here**, and rated accordingly in `NODE_CAPABILITIES`
+ * (`@lunora/platform`): queues over a durable table (`./node-queue-host`), R2
+ * buckets over the local filesystem (`./node-r2-bucket`), workflows over the
+ * `@visulima/workflow` engine (`./node-workflow-host`), and cross-shard fan-out
+ * via `@lunora/runtime`'s query coordinator over the in-process shard registry.
+ * `createNodePlatform` binds all three declarations (`queues`, `workflows`,
+ * `objectStorageDirectory`) — a capability rated `emulated` with nothing bound
+ * is the one combination that fails at runtime with no diagnostic before it.
  *
- * Three suites run against this package: `@lunora/platform/conformance`'s host
- * TCK, `@lunora/shard-engine/conformance`'s engine suite, and its own
- * lifecycle/global-store tests.
+ * **Still missing:** a dev server. There is no `lunora dev --target node`, and
+ * nothing here owns a timer, so queue delivery is driven by an explicit
+ * `poll()`. What exists is the listener a dev server would sit on:
+ * `createNodeHttpServer` serves an app worker's `fetch` over `node:http`,
+ * streaming the response body, and `createNodeShardNamespace` presents the
+ * registry as the `shardDO` namespace that worker routes to. Also absent are
+ * the Cloudflare product bindings with no local
+ * equivalent — Vectorize, Workers AI, Browser Rendering, Containers, Analytics
+ * Engine, Pipelines, Secrets Store, Hyperdrive.
  *
- * **Still missing**, and rated accordingly in `NODE_CAPABILITIES`
- * (`@lunora/platform`): a dev server — so `lunora dev --target node` does not
- * exist yet — plus most Cloudflare product bindings (Queues, Vectorize, Workers
- * AI, Browser Rendering, Containers, Analytics Engine, Pipelines, Secrets Store,
- * Hyperdrive). R2 buckets are emulated over the local filesystem
- * (`./node-r2-bucket`) and Workflows over the `@visulima/workflow` engine
- * (`./node-workflow-host`). Cross-shard fan-out is emulated via
- * `@lunora/runtime`'s query coordinator over the in-process shard registry, and
- * a `@lunora/config` deploy driver makes `--target node` resolve. See
+ * `@lunora/config` ships a `node` **deploy** driver, so `--target node` resolves
+ * for `provision` — which reports, once, which declared features this target
+ * cannot serve, and writes nothing: there is no hosted control plane to deploy
+ * to and no `wrangler`-equivalent to shell out to. A deploy driver is not a dev
+ * server, which is why both statements above hold at once. See
  * `plans/234-node-host-findings.md`.
  */
-type NodeGlobalStore,
+type NodeDispatchInvocation,
 /**
  * `@lunora/platform-node` — a Node implementation of the `@lunora/platform`
  * host contracts (`ShardHost`, `SocketHost`, `ShardDirectory`, `ShardKvStore`,
@@ -596,15 +826,30 @@ type NodeGlobalStore,
  * TCK, `@lunora/shard-engine/conformance`'s engine suite, and its own
  * lifecycle/global-store tests.
  *
- * **Still missing**, and rated accordingly in `NODE_CAPABILITIES`
- * (`@lunora/platform`): a dev server — so `lunora dev --target node` does not
- * exist yet — plus most Cloudflare product bindings (Queues, Vectorize, Workers
- * AI, Browser Rendering, Containers, Analytics Engine, Pipelines, Secrets Store,
- * Hyperdrive). R2 buckets are emulated over the local filesystem
- * (`./node-r2-bucket`) and Workflows over the `@visulima/workflow` engine
- * (`./node-workflow-host`). Cross-shard fan-out is emulated via
- * `@lunora/runtime`'s query coordinator over the in-process shard registry, and
- * a `@lunora/config` deploy driver makes `--target node` resolve. See
+ * **Emulated here**, and rated accordingly in `NODE_CAPABILITIES`
+ * (`@lunora/platform`): queues over a durable table (`./node-queue-host`), R2
+ * buckets over the local filesystem (`./node-r2-bucket`), workflows over the
+ * `@visulima/workflow` engine (`./node-workflow-host`), and cross-shard fan-out
+ * via `@lunora/runtime`'s query coordinator over the in-process shard registry.
+ * `createNodePlatform` binds all three declarations (`queues`, `workflows`,
+ * `objectStorageDirectory`) — a capability rated `emulated` with nothing bound
+ * is the one combination that fails at runtime with no diagnostic before it.
+ *
+ * **Still missing:** a dev server. There is no `lunora dev --target node`, and
+ * nothing here owns a timer, so queue delivery is driven by an explicit
+ * `poll()`. What exists is the listener a dev server would sit on:
+ * `createNodeHttpServer` serves an app worker's `fetch` over `node:http`,
+ * streaming the response body, and `createNodeShardNamespace` presents the
+ * registry as the `shardDO` namespace that worker routes to. Also absent are
+ * the Cloudflare product bindings with no local
+ * equivalent — Vectorize, Workers AI, Browser Rendering, Containers, Analytics
+ * Engine, Pipelines, Secrets Store, Hyperdrive.
+ *
+ * `@lunora/config` ships a `node` **deploy** driver, so `--target node` resolves
+ * for `provision` — which reports, once, which declared features this target
+ * cannot serve, and writes nothing: there is no hosted control plane to deploy
+ * to and no `wrangler`-equivalent to shell out to. A deploy driver is not a dev
+ * server, which is why both statements above hold at once. See
  * `plans/234-node-host-findings.md`.
  */
-type NodeGlobalStoreOptions, type NodePlatform, type NodePlatformOptions, type NodeQueueHost, type NodeQueueHostOptions, type NodeR2BucketOptions, type NodeSchedulerHost, type NodeSchedulerHostOptions, type NodeShard, type NodeShardHostOptions, type NodeShardRegistry, type NodeShardRegistryOptions, type NodeShardState, type NodeSocketHost, type NodeWorkflowHost, type NodeWorkflowHostOptions, createNodeGlobalStore, createNodePlatform, createNodeQueueHost, createNodeR2Bucket, createNodeSchedulerHost, createNodeShardHost, createNodeShardKvStore, createNodeShardRegistry, createNodeShardState, createNodeSocketHost, createNodeSqlExec, createNodeWorkflowHost, createNodeWorkflowStore };
+type NodeDispatchRouteOptions, type NodeGlobalContextDatabaseOptions, type NodeGlobalStore, type NodeGlobalStoreOptions, type NodeHttpServer, type NodeHttpServerOptions, type NodePlatform, type NodePlatformDispatchOptions, type NodePlatformOptions, type NodeProfileHandler, type NodeProfileHandlerOptions, type NodeQueueHost, type NodeQueueHostOptions, type NodeR2BucketOptions, type NodeSchedulerHost, type NodeSchedulerHostOptions, type NodeShard, type NodeShardHostOptions, type NodeShardRegistry, type NodeShardRegistryOptions, type NodeShardState, type NodeSocketHost, type NodeWorkflowHost, type NodeWorkflowHostOptions, type ShardSocketHooks, bindShardSockets, createNodeDispatchRoute, createNodeGlobalStore, createNodeHttpServer, createNodePlatform, createNodeProfileHandler, createNodeQueueHost, createNodeR2Bucket, createNodeSchedulerHost, createNodeShardHost, createNodeShardKvStore, createNodeShardNamespace, createNodeShardRegistry, createNodeShardState, createNodeSocketHost, createNodeSqlExec, createNodeWorkflowHost, createNodeWorkflowStore };