@lunora/platform 0.0.0 → 1.0.0-alpha.10

package/dist/packem_shared/socket-host.d-Dy2QiVn6.d.mts

@@ -0,0 +1,642 @@
+/**
+ * `ShardKvStore` — the provider-neutral contract for durable key-value storage
+ * scoped to one shard. On Cloudflare this is backed by `state.storage`'s
+ * key-value surface (`get`/`put`/`delete`/`list`); on another provider it may
+ * be a DynamoDB item collection, a Redis keyspace, or a table in the shard's
+ * local SQL store.
+ *
+ * This is the surface `ShardHost` deliberately does not cover. `ShardHost`
+ * models the reactive engine's needs — single-writer serialization, local SQL,
+ * transactions, alarms. A Durable Object that keeps plain records rather than
+ * running the engine (`SessionDO` is the canonical one) needs ordered key
+ * lookup and prefix scans instead, and forcing it through `ShardHost.sql`
+ * would give it a SQL dialect it does not want. Kept a separate contract so a
+ * host can implement one, the other, or both.
+ *
+ * The engine relies on three guarantees:
+ * 1. **Durability** — a written value survives host recycling and is readable
+ * on the next wake, exactly like a `SocketHost` attachment.
+ * 2. **Read-your-writes** — a `get` after a `put` in the same wake observes the
+ * written value.
+ * 3. **Prefix enumeration** — `list({ prefix })` returns every live key under
+ * the prefix and nothing outside it, so a keyspace can be swept (TTL GC) or
+ * migrated without a separate index.
+ *
+ * This is an internal contract. User code never sees it; only DOs that keep
+ * durable records and their host adapters consume it.
+ */
+/** Options accepted by {@link ShardKvStore.list}. */
+interface ShardKvListOptions {
+  /**
+   * Restrict the scan to keys beginning with this string. Omitted means every
+   * key in the shard's keyspace — hosts should treat a very large keyspace as
+   * the caller's responsibility to bound, exactly as `state.storage.list`
+   * does.
+   */
+  prefix?: string;
+}
+/**
+ * The durable key-value contract for one shard. One instance per shard key.
+ */
+interface ShardKvStore {
+  /**
+   * Delete `key`. Resolves `true` when a value was removed, `false` when the
+   * key was already absent. Idempotent: deleting a missing key is not an
+   * error.
+   */
+  delete: (key: string) => Promise<boolean>;
+  /**
+   * Read the value stored under `key`, or `undefined` when absent. The type
+   * parameter is a caller-side assertion about the stored shape; the host
+   * does not validate it.
+   */
+  get: <T = unknown>(key: string) => Promise<T | undefined>;
+  /**
+   * Enumerate live keys, optionally restricted to a prefix. The result MUST
+   * contain exactly the keys under the prefix — never a superset — so a
+   * prefix sweep cannot touch unrelated keys.
+   */
+  list: <T = unknown>(options?: ShardKvListOptions) => Promise<Map<string, T>>;
+  /**
+   * Write `value` under `key`, replacing any existing value. The value must
+   * be structured-clonable; hosts serialize it durably.
+   */
+  put: (key: string, value: unknown) => Promise<void>;
+}
+/**
+ * `SchedulerHost` — the provider-neutral contract for durable scheduling
+ * (delayed jobs, cron triggers, at-least-once dispatch). On Cloudflare this is
+ * backed by `SchedulerDO` (a Durable Object with alarms) plus Cron Triggers.
+ * On another provider it may be a job scheduler (SQS + EventBridge, Temporal,
+ * a database-backed polling loop, or a managed cron service).
+ *
+ * The contract encodes the guarantees Lunora's `runAfter` / `runAt` / cron
+ * features rely on:
+ * 1. **At-least-once delivery** — a scheduled job is dispatched at least once;
+ * retries and dead-lettering are host-managed.
+ * 2. **Durable persistence** — scheduled jobs survive host recycling.
+ * 3. **Time-based dispatch** — jobs can be scheduled for an absolute time or
+ * after a delay.
+ */
+/** Options accepted when scheduling a job. */
+interface ScheduleOptions {
+  /** Run the job at this absolute timestamp (ms since epoch). Overrides `delayMs`. */
+  at?: number | Date;
+  /** Run the job no sooner than this delay (ms) from now. */
+  delayMs?: number;
+  /** Per-job retry policy. Falls back to the host's defaults when omitted. */
+  retry?: {
+    /** Backoff multiplier. */
+    backoffMultiplier?: number;
+    /** Initial backoff delay (ms). */
+    initialDelayMs?: number;
+    /** Maximum number of delivery attempts. */
+    maxAttempts?: number;
+    /** Maximum backoff delay (ms). */
+    maxDelayMs?: number;
+  };
+  /** Routing hint forwarded to the worker so the call lands on the right shard. */
+  shardKey?: string;
+}
+/** A scheduled job descriptor returned by the host. */
+interface ScheduledJob {
+  /** Unique job identifier. */
+  id: string;
+  /** Timestamp (ms since epoch) the job is scheduled for. */
+  scheduledFor: number;
+}
+/**
+ * A scheduled job as the host currently sees it — {@link ScheduledJob} plus the
+ * delivery state that only the host knows.
+ *
+ * `attempts` is what makes at-least-once observable rather than merely
+ * promised: a job that failed to deliver and is waiting to be retried is still
+ * pending, with a higher count. A host reporting `0` forever is either not
+ * retrying or not counting, and both are worth knowing.
+ */
+interface ScheduledJobStatus extends ScheduledJob {
+  /** Delivery attempts made so far. `0` for a job that has not been dispatched yet. */
+  attempts: number;
+  /** The function path the job dispatches to. */
+  functionPath: string;
+}
+/**
+ * The scheduler host contract. One instance per scheduler namespace.
+ */
+interface SchedulerHost {
+  /**
+   * Cancel a previously scheduled job. Returns `true` if the job was found
+   * and cancelled; `false` if it was already dispatched or never existed.
+   */
+  cancel: (id: string) => Promise<boolean>;
+  /**
+   * Register a cron schedule at runtime. The `cron` expression uses standard
+   * cron syntax; the `functionPath` is dispatched on each tick.
+   *
+   * **Optional, and omitted by hosts whose crons are declared rather than
+   * registered.** Cloudflare is one: `triggers.crons` lives in
+   * `wrangler.jsonc` and is reconciled at build time by the config layer, so
+   * there is no runtime call that could add one. Such a host omits this
+   * method rather than supplying one that throws or silently no-ops —
+   * presence is the host's declaration that dynamic cron works, exactly as
+   * with `SocketHost.setTag`. A caller that finds it absent must fall
+   * back to the target's declarative configuration.
+   */
+  cron?: (cron: string, functionPath: string, args?: Record<string, unknown>) => Promise<void>;
+  /**
+   * List jobs that exhausted their retry budget and were parked instead of
+   * dropped, plus return one to the pending set.
+   *
+   * **Optional, and its absence is a real statement:** a host without it
+   * cannot promise at-least-once, only at-most-once. Once retries are
+   * exhausted the job either survives somewhere an operator can find it, or
+   * it is gone — and "gone" is indistinguishable from "delivered" to every
+   * caller. Guarantee 1 in this module's header is exactly what this member
+   * makes checkable.
+   *
+   * `list` MUST be disjoint from {@link SchedulerHost.list}: a parked job is
+   * no longer scheduled, and a host reporting it in both shows a permanently
+   * failed job as still on its way.
+   *
+   * `requeue` returns `false` for an id that is not parked, and on `true`
+   * returns the job to the pending set with a fresh attempt budget.
+   */
+  deadLetter?: {
+    list: () => Promise<ScheduledJobStatus[]>;
+    requeue: (id: string) => Promise<boolean>;
+  };
+  /**
+   * List the jobs currently pending — scheduled and not yet delivered,
+   * including those waiting between retries.
+   *
+   * Optional: a fire-and-forget host with no queryable queue omits it, and
+   * the suite reports the gap rather than asserting against a stub.
+   */
+  list?: () => Promise<ScheduledJobStatus[]>;
+  /**
+   * Schedule a function call for later execution. The `functionPath` and
+   * `args` are serialized and delivered back to the worker at dispatch time.
+   */
+  schedule: (functionPath: string, args: Record<string, unknown>, options?: ScheduleOptions) => Promise<ScheduledJob>;
+}
+/**
+ * Edge geography → placement region, shared by `@lunora/runtime` (which reads
+ * `request.cf` to pick where a shard, replica, or region-local socket should
+ * live) and `@lunora/do` (which parses a region out of its own DO name). Kept
+ * here — inlined into each consumer's bundle — so the two sides can never drift
+ * on the region vocabulary without creating a runtime dependency edge between
+ * the packages.
+ *
+ * The values are Cloudflare's Durable Object location hints, which is also the
+ * only vocabulary a Lunora deployment needs today: a region is *only* ever used
+ * as a placement hint and as a name segment, never as data. Wrong-but-close is
+ * fine by construction — a misrouted read is one longer hop, never a wrong
+ * answer — so this maps coarsely and returns `undefined` rather than guessing
+ * when the request carries no usable geography.
+ *
+ * Zero-dependency by design (see the repo's `shared/` rules): only relative /
+ * builtin imports, named exports, no `.js` extensions.
+ */
+/**
+ * The placement regions a name may carry and a hint may request — Cloudflare's
+ * `DurableObjectLocationHint` values, listed so the set can be validated at a
+ * trust boundary (a region parsed out of a DO name is attacker-influenced input
+ * on any route that mints names from a client-supplied shard key).
+ */
+declare const REGION_HINTS: readonly ["wnam", "enam", "sam", "weur", "eeur", "apac", "apac-ne", "apac-se", "oc", "afr", "me"];
+/** One placement region. Structurally identical to Cloudflare's `DurableObjectLocationHint`. */
+type RegionHint = (typeof REGION_HINTS)[number];
+/**
+ * Cloudflare Durable Object jurisdictions restrict where a DO runs and
+ * persists data, for data-residency / compliance regimes (GDPR, FedRAMP, US
+ * data residency). The set is open — Cloudflare adds values over time — so
+ * this is a widening union rather than a closed enum: the three literals are
+ * the values we know about (and the ones editors autocomplete), but any other
+ * string a provider introduces is accepted without a release of this package.
+ *
+ * Other providers may map these to their own region/placement concepts or
+ * leave them unsupported.
+ */
+type ShardJurisdiction = "eu" | "fedramp" | "us" | (Record<never, never> & string);
+/**
+ * A geographic placement region — where a shard should be created, when the
+ * caller has an opinion.
+ *
+ * One vocabulary, defined once: `shared/region-hint.ts` owns the region list
+ * (it is also what derives a region from edge geography), and this contract
+ * re-exports it rather than restating the strings. A second list is how the two
+ * ends of a placement request drift apart.
+ *
+ * Unlike a jurisdiction — a hard constraint the caller must fail closed on — a
+ * region is **best effort and advisory**: a provider may ignore it, and on
+ * Cloudflare it is honoured only by the call that first creates the object.
+ * Everything downstream must work identically whether the hint was honoured,
+ * ignored, or never supplied, and no caller may treat a resolved stub's
+ * location as known.
+ */
+type ShardRegionHint = RegionHint;
+/**
+ * A resolved shard stub. The engine calls `fetch` (or an equivalent RPC
+ * method) to dispatch work to the shard.
+ */
+interface ShardStub {
+  /** Dispatch a request to the shard. */
+  fetch: (request: Request) => Promise<Response>;
+}
+/**
+ * A directory that resolves a shard key straight to a stub in one step. The
+ * two-step `idForName` + `get` pair stays available for providers that expose
+ * an addressable id (Cloudflare's `DurableObjectNamespace` does both), but a
+ * provider whose registry only understands names implements `getByName` alone.
+ */
+interface DirectShardDirectory {
+  /** Resolve an opaque id (from `idForName`) to a stub, when the provider has ids. */
+  get?: (id: unknown, locationHint?: ShardRegionHint) => ShardStub;
+  /** Resolve a shard key to a stub. */
+  getByName: (name: string, locationHint?: ShardRegionHint) => ShardStub;
+  /** Derive a stable, opaque shard id from a shard key, when the provider has ids. */
+  idForName?: (name: string) => unknown;
+  /** See {@link ShardDirectory}. */
+  jurisdiction?: (jurisdiction: ShardJurisdiction) => ShardDirectory;
+}
+/**
+ * A directory that resolves a shard key in two steps: derive an opaque id with
+ * `idForName`, then materialize a stub for it with `get`. This is the shape of
+ * an id-addressed registry that has no name-based lookup of its own.
+ */
+interface TwoStepShardDirectory {
+  /** Resolve an opaque id (from `idForName`) to a stub. */
+  get: (id: unknown, locationHint?: ShardRegionHint) => ShardStub;
+  /**
+   * Absent — the discriminant that selects the two-step branch.
+   */
+  getByName?: undefined;
+  /** Derive a stable, opaque shard id from a human-readable key. */
+  idForName: (name: string) => unknown;
+  /** See {@link ShardDirectory}. */
+  jurisdiction?: (jurisdiction: ShardJurisdiction) => ShardDirectory;
+}
+/**
+ * The shard directory contract. One instance per shard namespace.
+ *
+ * A provider satisfies this with *either* direct name lookup
+ * ({@link DirectShardDirectory}) *or* the two-step id dance
+ * ({@link TwoStepShardDirectory}) — it is a union, not one interface with
+ * optional halves, so a name-only registry never has to stub out `idForName`
+ * and `get` to type-check. Providers that support both (Cloudflare) simply
+ * populate all three and land on the direct branch.
+ *
+ * Prefer {@link resolveShard} over reaching into either branch by hand.
+ *
+ * `jurisdiction` derives a placement-restricted view of the directory: every
+ * stub created from the returned directory is pinned to that jurisdiction. It
+ * is optional because some providers have no placement hints; callers must fail
+ * closed when a jurisdiction is requested but the method is absent.
+ */
+type ShardDirectory = DirectShardDirectory | TwoStepShardDirectory;
+/**
+ * Resolve a shard key to a stub against either directory shape. Uses direct
+ * name lookup when the provider has it, and falls back to the two-step
+ * `idForName` + `get` dance otherwise.
+ *
+ * `locationHint` is forwarded to whichever branch runs. It is advisory in
+ * both: a provider with no placement concept ignores the extra argument, which
+ * is exactly what an implementation written against the pre-placement
+ * signature does.
+ */
+declare const resolveShard: (directory: ShardDirectory, name: string, locationHint?: ShardRegionHint) => ShardStub;
+/**
+ * `ShardHost` — the provider-neutral contract for a single-writer, durable
+ * shard execution slot. On Cloudflare this is backed by one Durable Object
+ * instance (`state.storage` + `state.blockConcurrencyWhile`); on another
+ * provider it may be an actor, a container, or a single-node process.
+ *
+ * The contract encodes the guarantees the Lunora reactive engine relies on:
+ * 1. **Single-writer serialization** — mutations for one shard key never
+ * interleave; they are serialized through {@link ShardHost.runSerialized}.
+ * 2. **Transactional durability** — a mutation either commits fully or rolls
+ * back; no partial writes are observable.
+ * 3. **Local SQL execution** — the shard can run synchronous-ish SQL against
+ * co-located storage (SQLite on Cloudflare; another embedded or local DB
+ * elsewhere). Reads must observe the current transaction's writes.
+ * 4. **Alarms / scheduled wakeup** — the shard can schedule a future wakeup
+ * for background work (timers, retries, TTL cleanup).
+ * 5. **Background continuation** — `waitUntil` lets work outlive the request
+ * without blocking the response.
+ *
+ * This is an internal contract. User code never sees it; only the runtime,
+ * the shard engine, and host adapters consume it.
+ */
+/**
+ * Minimal SQL cursor/row shape returned by the local SQL executor. Kept
+ * generic so a host can wrap SQLite, libSQL, or another embedded store.
+ */
+type SqlRow = Record<string, unknown>;
+/**
+ * The result of one statement: a cursor over its rows.
+ *
+ * Every member here is required, because the engine uses all three and a host
+ * that omits one fails at runtime rather than at compile time. That is not
+ * hypothetical — an earlier revision of this contract made `toArray` optional
+ * and offered a `rowsAffected` nothing reads, which meant a host could satisfy
+ * the type and still be unusable.
+ *
+ * Iteration is part of the contract because read paths stream cursors directly
+ * rather than buffering; `toArray` is the buffered form, and `one` is the
+ * exactly-one-row form used by lookups and aggregates.
+ */
+interface ShardSqlCursor<Row = SqlRow> extends Iterable<Row> {
+  /**
+   * The single row this statement produced.
+   * @throws when the result does not hold exactly one row.
+   */
+  one: () => Row;
+  /** Buffer every row. */
+  toArray: () => Row[];
+}
+/**
+ * The local, synchronous-ish SQL executor available inside a shard — the
+ * engine's hot path. Mirrors the shape the DO's `state.storage.sql` exposes.
+ *
+ * Implementations may be sync (Cloudflare `SqlStorage`) or async-backed with
+ * a sync facade; the engine treats it as fire-and-forget within a
+ * {@link ShardHost.transaction} closure.
+ */
+interface ShardSqlExec {
+  /**
+   * Size of the shard's local database in bytes, when the host can report it
+   * cheaply. Optional: it is used for storage telemetry and quota warnings,
+   * never for correctness, so a host without the number simply omits it.
+   *
+   * Read as a live getter where the host provides one — do not cache it.
+   */
+  readonly databaseSize?: number;
+  /** Execute a SQL statement with optional bound parameters. */
+  exec: <Row = SqlRow>(query: string, ...bindings: ReadonlyArray<unknown>) => ShardSqlCursor<Row>;
+}
+/**
+ * Async SQL executor used by the engine's higher-level paths (global tables,
+ * metrics, auth). Already defined in `@lunora/sql-store` as `SqlExec`; this
+ * alias keeps the platform contract self-contained.
+ */
+interface ShardAsyncSqlExec {
+  all: (sql: string, params: ReadonlyArray<unknown>) => Promise<SqlRow[]>;
+  run: (sql: string, params: ReadonlyArray<unknown>) => Promise<{
+    rowsAffected: number;
+  }>;
+}
+/**
+ * Alarm scheduling for a shard. Alarms are durable: they survive host
+ * recycling and fire at the requested timestamp.
+ */
+interface ShardAlarms {
+  /** Delete any pending alarm. */
+  delete: () => Promise<void> | void;
+  /** Read the currently scheduled alarm timestamp, if any. */
+  get: () => Promise<number | null> | number | null;
+  /**
+   * Schedule the next alarm. Call {@link ShardAlarms.delete} to clear a
+   * pending alarm — `set` always schedules and never clears.
+   */
+  set: (timestamp: number | Date) => Promise<void> | void;
+}
+/**
+ * The core shard host contract. One instance per shard key.
+ */
+interface ShardHost {
+  /** Durable alarm scheduling for the shard. */
+  alarms: ShardAlarms;
+  /**
+   * Async SQL executor for engine paths that need promise-based row access
+   * (global tables, metrics, auth). Hosts may implement this over the same
+   * underlying storage as `sql`.
+   */
+  asyncSql?: ShardAsyncSqlExec;
+  /**
+   * Run `fn` with exclusive ownership of the shard. Concurrent calls are
+   * queued; no two closures run at once for the same shard key. On
+   * Cloudflare this maps to `state.blockConcurrencyWhile`.
+   *
+   * A closure that throws must reject with **the value it threw**, and must
+   * leave the host usable for the next call. Engine errors carry a `code` and
+   * `status` the RPC edge renders from, so a host that lets its platform
+   * substitute a copy silently downgrades every coded error to an internal
+   * fault — and a host that tears itself down on a throw makes an ordinary
+   * application error cost every other caller on that shard.
+   */
+  runSerialized: <T>(function_: () => Promise<T>) => Promise<T>;
+  /**
+   * The shard key this host serves — the name the directory resolved to reach
+   * it. Used for telemetry attribution and log correlation ("which shard
+   * emitted this?"), never for routing: the host is already the shard.
+   *
+   * Optional because a host may address a shard by an opaque id with no
+   * human-readable name (Cloudflare's `newUniqueId()` objects have none).
+   * Callers must tolerate `undefined` rather than assume a key exists.
+   */
+  readonly shardKey?: string;
+  /**
+   * The shard's local SQL executor. Reads and writes inside a `transaction`
+   * closure observe the transaction's isolation.
+   */
+  sql: ShardSqlExec;
+  /**
+   * Run `fn` inside a durable transaction. If `fn` throws, all writes roll
+   * back and the call rejects with **the value `fn` threw** — see
+   * {@link ShardHost.runSerialized} for why the identity matters. Raw
+   * `BEGIN`/`COMMIT`/`ROLLBACK` are forbidden inside the closure; the host
+   * manages the transaction boundary.
+   */
+  transaction: <T>(function_: () => Promise<T>) => Promise<T>;
+  /**
+   * Extend the lifetime of background work past the response. Optional on
+   * hosts that don't distinguish request/background lifetimes.
+   */
+  waitUntil?: (promise: Promise<unknown>) => void;
+}
+/**
+ * `SocketHost` — the provider-neutral contract for hibernated WebSocket
+ * subscriptions inside a shard. On Cloudflare this is backed by the Durable
+ * Object WebSocket hibernation API (`state.acceptWebSocket`,
+ * `ws.serializeAttachment`, `state.getWebSockets`).
+ *
+ * The engine relies on three guarantees:
+ * 1. **Hibernation** — a socket can be evicted from memory and rehydrated
+ * later without losing its subscription state.
+ * 2. **Attachment round-trip** — arbitrary JSON state serialized with the
+ * socket must survive recycling and be readable on wake.
+ * 3. **Tagged fan-out** — the host can enumerate live sockets (optionally by
+ * tag) to broadcast query invalidations and shape updates.
+ *
+ * A non-Cloudflare host may keep sockets in memory or in a process-local
+ * registry; the contract requires that attachments are durable, that
+ * `getSockets()` returns the currently-live set, and that `getSockets(tag)`
+ * returns *only* the sockets carrying that tag.
+ *
+ * Tagging comes in two tiers, because hosts differ on when a tag can be set:
+ *
+ * - **Accept-time tags** (`accept(socket, attachment, tags)`) — mandatory.
+ * Every host must accept them and must honour them in `getSockets(tag)`.
+ * They are durable: a tag survives hibernation exactly like an attachment.
+ * Cloudflare's `state.acceptWebSocket(ws, tags)` is this tier, and it is the
+ * only tier Cloudflare supports — DO tags are immutable once accepted.
+ * - **Mutable tags** ({@link SocketHost.setTag} / {@link SocketHost.removeTag})
+ * — optional. Presence declares that the host can retag a live socket. Hosts
+ * that cannot (Cloudflare) omit both methods, and callers that need to
+ * retag must instead close and re-accept the socket with new tags.
+ *
+ * **Reserved-slot budget.** A host may reserve some of its accept-time tag
+ * slots for its own bookkeeping — Cloudflare's adapter prepends one identity
+ * tag (so `idFor` survives hibernation) before every `acceptWebSocket` call.
+ * Cloudflare's own cap is 10 tags per socket, 256 characters each
+ * (developers.cloudflare.com/durable-objects/api/state/), so with one slot
+ * reserved a portable caller should assume **at most 9 usable tags, each
+ * bounded to at most 256 characters** — a budget-exceeding `accept` call
+ * fails loudly on the host that enforces it (see
+ * {@link SocketHost.accept}) rather than passing silently on hosts with no
+ * cap and only failing, opaquely, on Cloudflare.
+ */
+/**
+ * The socket the engine sends through.
+ *
+ * Deliberately **not** a wrapper object. A host is expected to return its own
+ * transport socket here, unchanged — which is why identity lives out-of-band on
+ * {@link SocketHost.idFor} rather than as an `id` property on this interface.
+ *
+ * Two reasons, one measured and one structural:
+ *
+ * 1. **Fan-out is O(subscribers) and this interface is on that loop.** Whisper
+ * delivery, shape pokes and delta delivery all walk every socket calling
+ * `deserializeAttachment` then `send`. When those forwarded through a wrapper,
+ * the two extra call frames per socket cost +1.11 ns/socket — +11% to +13% on
+ * whisper fan-out at 128 and 1024 subscribers, against a per-socket body of
+ * only ~6-7 ns. An `id` property is the only thing a wrapper was needed for,
+ * and it is read a handful of times outside the hot loops.
+ * 2. **A wrapper creates two identities for one socket.** Enumeration would
+ * yield handles while the runtime's own message/close callbacks yield the
+ * transport socket, so every per-socket `WeakMap` memo could key on either and
+ * diverge. Returning the transport socket collapses that: there is one object,
+ * so {@link SocketHost.handleFor} is an ownership test rather than a
+ * translation, and the memos cannot disagree.
+ *
+ * A host whose transport genuinely cannot satisfy this shape may still wrap —
+ * nothing here forbids it — but it pays the per-socket cost itself instead of
+ * charging every other host for it.
+ */
+interface SocketHandle {
+  /**
+   * Bytes queued for send but not yet flushed, when the transport reports it.
+   *
+   * The engine polls this to apply backpressure before pushing another batch
+   * at a slow subscriber. Optional because not every transport exposes a
+   * queue depth — absent means "assume drained", which degrades to the
+   * pre-backpressure behavior rather than stalling.
+   */
+  readonly bufferedAmount?: number;
+  /** Close the socket with an optional code and reason. */
+  close: (code?: number, reason?: string) => void;
+  /** Read the attachment previously stored with `serializeAttachment`. */
+  deserializeAttachment: () => unknown;
+  /** Send a text or binary frame. */
+  send: (data: string | ArrayBufferLike | Blob | ArrayBufferView) => void;
+  /** Persist attachment state for this socket. */
+  serializeAttachment: (value: unknown) => void;
+}
+/**
+ * The socket host contract. One instance per shard.
+ */
+interface SocketHost {
+  /**
+   * Accept a new WebSocket connection into the shard. `attachment` is
+   * serialized immediately and must survive host recycling. `tags` are the
+   * socket's durable fan-out labels, fixed for its lifetime — they must
+   * survive recycling too and must be honoured by
+   * {@link SocketHost.getSockets}. Returns a handle the engine can
+   * send/close through.
+   *
+   * Portable callers should assume a budget of **at most 9 usable tags, each
+   * at most 256 characters** — some hosts (Cloudflare) reserve one tag slot
+   * of their own 10-tag cap for bookkeeping; see this file's module-header
+   * "Reserved-slot budget" note. A host that enforces a cap rejects an
+   * over-budget call rather than accepting it and silently dropping or
+   * truncating tags, which would break {@link SocketHost.getSockets}'s
+   * exactness requirement.
+   */
+  accept: (socket: unknown, attachment?: unknown, tags?: ReadonlyArray<string>) => SocketHandle;
+  /**
+   * Enumerate currently-live sockets. When `tag` is supplied the result MUST
+   * contain exactly the sockets carrying that tag — never a superset.
+   *
+   * Exactness is a correctness requirement, not a performance one: returning
+   * every socket for a tagged call would fan a shape update out to unrelated
+   * subscriptions, which across tenants is a data leak. A host without
+   * native tagging must therefore filter in userland over the tags it was
+   * handed at {@link SocketHost.accept}.
+   */
+  getSockets: (tag?: string) => SocketHandle[];
+  /**
+   * Resolve a raw socket the runtime handed back — to a message or close
+   * callback, which carry the transport's own object rather than a handle —
+   * to the handle the host issued for it at {@link SocketHost.accept}.
+   *
+   * Without this the two worlds never meet: enumeration yields handles while
+   * event callbacks yield raw sockets, and code that has to compare the two
+   * (excluding a sender from its own broadcast, say) is forced back onto the
+   * provider type. Returns `undefined` for a socket this host never accepted.
+   */
+  handleFor: (socket: unknown) => SocketHandle | undefined;
+  /**
+   * The socket's unique identifier, stable across hibernation.
+   *
+   * Out-of-band rather than a property on {@link SocketHandle} so a host can
+   * return its transport socket unchanged — see the note there for why that
+   * matters on the fan-out path. A host supplies identity however it can: a
+   * durable tag minted at accept (Cloudflare), a registry key, a `WeakMap`.
+   *
+   * Must answer consistently for the same socket within a wake AND across a
+   * recycle, since the engine uses it to reassociate a rehydrated socket with
+   * its subscription state. Callers outside the O(subscribers) loops are the
+   * intended consumers; do not reach for this per socket per frame.
+   *
+   * **A socket this host never {@link SocketHost.accept}ed** (a foreign socket
+   * the runtime hands back — a whisper sender in another pool, a relay peer)
+   * is outside that "own socket" contract, but a host must still pick ONE
+   * consistent answer for it, never a fresh value per call:
+   *
+   * - Throw, when a `SocketHandle` from this host can *only* ever originate
+   * from this host's own `accept`/`recycle` — an unrecognized handle then
+   * means caller error (a handle crossed from a different host instance),
+   * and failing loud beats returning a plausible-looking wrong id. This is
+   * the reference host's choice, since its `SocketHandle` is an opaque
+   * object it mints itself.
+   * - Mint and cache a read-only fallback id, when `SocketHandle` doubles as
+   * the provider's own transport socket (see {@link SocketHandle}'s "not a
+   * wrapper" rationale) — a foreign-but-genuine socket then structurally
+   * satisfies the type without ever going through `accept`, so throwing
+   * would fire on legitimate traffic, not just caller error. This is the
+   * Cloudflare host's choice: it caches into a separate map from its
+   * accept-time ownership evidence, so an `idFor` lookup can never promote
+   * a socket into "ours" for {@link SocketHost.handleFor}.
+   *
+   * Either is a valid implementation as long as it is consistent: what is not
+   * valid is minting a new id on every call for a socket the host does not
+   * recognize, which defeats the "same string for the same socket" property
+   * every caller of `idFor` — owned or not — depends on.
+   */
+  idFor: (socket: SocketHandle) => string;
+  /**
+   * Remove a tag from a live socket — all of them when `tag` is omitted.
+   * Optional, and only meaningful alongside {@link SocketHost.setTag}: a
+   * host that cannot retag a live socket must omit both.
+   */
+  removeTag?: (socket: SocketHandle, tag?: string) => void;
+  /**
+   * Tag a live socket after it was accepted. Presence of this method is the
+   * host's declaration that tags are *mutable*; it is not what makes tagged
+   * fan-out work, since accept-time tags are mandatory for every host. Omit
+   * it (rather than supplying a no-op) when the host's tags are frozen at
+   * accept, so callers re-accept instead of silently losing the retag.
+   */
+  setTag?: (socket: SocketHandle, tag: string) => void;
+}
+export { DirectShardDirectory as D, ScheduleOptions as S, TwoStepShardDirectory as T, ScheduledJob as a, ScheduledJobStatus as b, SchedulerHost as c, ShardAlarms as d, ShardAsyncSqlExec as e, ShardDirectory as f, ShardHost as g, ShardJurisdiction as h, ShardKvListOptions as i, ShardKvStore as j, ShardRegionHint as k, ShardSqlCursor as l, ShardSqlExec as m, ShardStub as n, SocketHandle as o, SocketHost as p, SqlRow as q, resolveShard as r };