@ultimat3/realtime 29.3.2 → 30.0.0

package/src/device-wire.ts

@@ -0,0 +1,155 @@
+// The device socket's wire, both hops: the frames a device and its node exchange, and the envelopes
+// nodes exchange over the bus to address one device from anywhere. JSON text only, and a size
+// limit the framework owns — the one number no declaration can widen.
+
+import { isJsonObject } from '@ultimat3/core';
+import type { JsonValue } from './json';
+import type { ReconnectFrame } from './sync-protocol';
+
+/**
+ * The largest frame either side may send, in UTF-8 bytes: 256 KiB. Bun's `maxPayloadLength` on the
+ * mount enforces it before a byte is buffered, and `decodeDeviceFrame` again for a host that did
+ * not apply it. Work that is bigger is a key into storage, not a frame.
+ */
+export const DEVICE_FRAME_MAX_BYTES = 256 * 1024;
+
+/** What a device sends: a beat, a frame for `onFrame`, or the answer to a `request` by its id. */
+export type DeviceInbound =
+  | { readonly type: 'beat' }
+  | { readonly type: 'frame'; readonly frame: JsonValue }
+  | { readonly type: 'response'; readonly id: string; readonly frame: JsonValue };
+
+/** What a node sends a device. `reconnect` is the sync protocol's own frame, unchanged. */
+export type DeviceOutbound =
+  | { readonly type: 'hello'; readonly heartbeatMs: number; readonly maxFrameBytes: number }
+  | { readonly type: 'request'; readonly id: string; readonly frame: JsonValue }
+  | { readonly type: 'frame'; readonly frame: JsonValue }
+  | { readonly type: 'error'; readonly code: string }
+  | ReconnectFrame;
+
+const encoder = new TextEncoder();
+
+/**
+ * The frame's UTF-8 length when it is past the limit, else `null`. A UTF-16 unit is 1-3 UTF-8
+ * bytes, so a string short enough cannot be over it and is never encoded just to be measured.
+ */
+export function bytesOverLimit(text: string): number | null {
+  if (text.length * 3 <= DEVICE_FRAME_MAX_BYTES) return null;
+  const bytes = encoder.encode(text).length;
+  return bytes > DEVICE_FRAME_MAX_BYTES ? bytes : null;
+}
+
+/** `JSON.parse` that answers `undefined` instead of throwing — the input is a device's bytes. */
+export function parseJson(text: string): unknown {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return undefined;
+  }
+}
+
+/** A request/response id: what this node minted, so short and token-safe, never a device's prose. */
+const isId = (value: unknown): value is string =>
+  typeof value === 'string' && /^[A-Za-z0-9_-]{1,64}$/.test(value);
+
+/** A device frame, or `undefined` for anything this protocol does not speak. */
+export function decodeDeviceFrame(text: string): DeviceInbound | undefined {
+  const raw = parseJson(text);
+  if (!isJsonObject(raw)) return undefined;
+  if (raw['type'] === 'beat') return { type: 'beat' };
+  if (!Object.hasOwn(raw, 'frame')) return undefined;
+  const frame = raw['frame'] as JsonValue;
+  if (raw['type'] === 'frame') return { type: 'frame', frame };
+  if (raw['type'] === 'response' && isId(raw['id']))
+    return { type: 'response', id: raw['id'], frame };
+  return undefined;
+}
+
+/** A node's frame to a device, or `undefined` — the device agent's half of the same whitelist. */
+export function decodeNodeFrame(text: string): DeviceOutbound | undefined {
+  const raw = parseJson(text);
+  if (!isJsonObject(raw)) return undefined;
+  switch (raw['type']) {
+    case 'hello': {
+      const { heartbeatMs, maxFrameBytes } = raw;
+      if (typeof heartbeatMs !== 'number' || typeof maxFrameBytes !== 'number') return undefined;
+      return { type: 'hello', heartbeatMs, maxFrameBytes };
+    }
+    case 'request':
+      return isId(raw['id']) && Object.hasOwn(raw, 'frame')
+        ? { type: 'request', id: raw['id'], frame: raw['frame'] as JsonValue }
+        : undefined;
+    case 'frame':
+      return Object.hasOwn(raw, 'frame')
+        ? { type: 'frame', frame: raw['frame'] as JsonValue }
+        : undefined;
+    case 'error':
+      return typeof raw['code'] === 'string' ? { type: 'error', code: raw['code'] } : undefined;
+    case 'reconnect': {
+      const { afterMs, reason, v } = raw;
+      if (typeof afterMs !== 'number' || typeof v !== 'number') return undefined;
+      if (reason !== 'drain' && reason !== 'overload' && reason !== 'rebalance') return undefined;
+      return { type: 'reconnect', v, afterMs, reason };
+    }
+    default:
+      return undefined;
+  }
+}
+
+/** A request on its way to the node that holds the device. */
+export interface BusRequest {
+  readonly kind: 'request';
+  readonly id: string;
+  /** The requesting node: its reply subject is derived from this, never taken as a subject. */
+  readonly from: string;
+  readonly tenant: string;
+  readonly deviceId: string;
+  /** How long the requester waits — the holder forgets the request after it, answered or not. */
+  readonly deadlineMs: number;
+  readonly frame: JsonValue;
+}
+
+/** The holder's answer: the device's frame, or "it is not here". */
+export type BusReply =
+  | { readonly kind: 'response'; readonly id: string; readonly frame: JsonValue }
+  | { readonly kind: 'offline'; readonly id: string; readonly reason: string };
+
+/** A newer socket for one device opened somewhere: every other holder closes its own. */
+export interface BusClaim {
+  readonly kind: 'claim';
+  readonly tenant: string;
+  readonly deviceId: string;
+  readonly node: string;
+  readonly socketId: string;
+}
+
+export type BusMessage = BusRequest | BusReply | BusClaim;
+
+const isText = (value: unknown): value is string => typeof value === 'string';
+
+/** A bus payload, rebuilt field by field — another node's bytes are still bytes. */
+export function decodeBusMessage(text: string): BusMessage | undefined {
+  const raw = parseJson(text);
+  if (!isJsonObject(raw)) return undefined;
+  const { kind, id, tenant, deviceId } = raw;
+  if (kind === 'request') {
+    const { from, deadlineMs } = raw;
+    if (!isId(id) || !isId(from) || !isText(tenant) || !isText(deviceId)) return undefined;
+    if (typeof deadlineMs !== 'number' || !(deadlineMs > 0) || !Object.hasOwn(raw, 'frame')) {
+      return undefined;
+    }
+    return { kind, id, from, tenant, deviceId, deadlineMs, frame: raw['frame'] as JsonValue };
+  }
+  if (kind === 'response' && isId(id) && Object.hasOwn(raw, 'frame')) {
+    return { kind, id, frame: raw['frame'] as JsonValue };
+  }
+  if (kind === 'offline' && isId(id) && isText(raw['reason'])) {
+    return { kind, id, reason: raw['reason'] };
+  }
+  if (kind === 'claim') {
+    const { node, socketId } = raw;
+    if (!isText(tenant) || !isText(deviceId) || !isId(node) || !isText(socketId)) return undefined;
+    return { kind, tenant, deviceId, node, socketId };
+  }
+  return undefined;
+}

package/src/error-titles.ts

@@ -45,6 +45,10 @@ export const REALTIME_OWNED_ERROR_CODES = [
   'X_OFFLINE_QUEUE_ABANDONED',
   'X_SOCKET_LIMIT',
   'X_REALTIME_PRODUCER_CONFLICT',
+  'X_MUTATION_PATH_UNFILLED',
+  'X_DEVICE_OFFLINE',
+  'X_DEVICE_REQUEST_TIMEOUT',
+  'X_DEVICE_FRAME_TOO_LARGE',
 ] as const;
 
 export type RealtimeOwnedErrorCode = (typeof REALTIME_OWNED_ERROR_CODES)[number];
@@ -83,6 +87,10 @@ export const REALTIME_ERROR_TITLES: Readonly<Record<RealtimeOwnedErrorCode, stri
   X_OFFLINE_QUEUE_ABANDONED: 'a write was queued after its page changed principal',
   X_SOCKET_LIMIT: 'one principal holds too many sockets on this node',
   X_REALTIME_PRODUCER_CONFLICT: 'two kinds of producer carry one table on the change bus',
+  X_MUTATION_PATH_UNFILLED: "a pinned action's :param had no value in the write's input",
+  X_DEVICE_OFFLINE: 'no socket is open for the device a request addressed',
+  X_DEVICE_REQUEST_TIMEOUT: 'a device did not answer a request before its deadline',
+  X_DEVICE_FRAME_TOO_LARGE: 'a device socket frame is over the framework frame limit',
 };
 
 // One unconditional call, so a second package claiming one of realtime's codes throws

package/src/index.ts

@@ -136,6 +136,7 @@ export {
   pageOutbox,
 } from './page-outbox';
 export { hasPageSocket, type SyncTarget } from './page-store';
+export { pollEvery, type QueryPoll } from './query-poll';
 export { installRealtime, type RealtimeInstall } from './reactivity';
 export { persistedTypes, type RecordPersister, recordPersister } from './record-persister';
 export {
@@ -195,7 +196,13 @@ export {
   useMutationQueue,
 } from './use-mutation';
 export { type OutboxView, useOutbox } from './use-outbox';
-export { type QueryAccessor, type QueryOptions, type QueryRef, useQuery } from './use-query';
+export {
+  type LiveQueryOptions,
+  type QueryAccessor,
+  type QueryOptions,
+  type QueryRef,
+  useQuery,
+} from './use-query';
 export {
   type RecordAccessor,
   type RecordSelection,

package/src/live-contract.ts

@@ -10,6 +10,7 @@
 // decision and every window lookup keyed differently.
 
 import type { Actor } from '@ultimat3/core';
+import type { LiveReadPhase } from '@ultimat3/query';
 import type { LiveCursor } from './cursor';
 import type { JsonValue, Row } from './json';
 import type { IncrementalMatcher } from './matcher-bridge';
@@ -20,6 +21,19 @@ export interface SnapshotResult<R extends Row = Row> {
   readonly lsn: string;
 }
 
+/**
+ * One shared read's arguments. `traceparent` is the value a subscriber put on its `subscribe`
+ * frame — raw, so an invalid one is ignored where it is parsed (`@ultimat3/query`'s
+ * `traceLiveRead`), never refused. `phase` says why the read runs: a subscribe asked for it, or a
+ * change made the window re-read. Both optional: a definition that traces nothing ignores them.
+ */
+export interface SnapshotArgs {
+  readonly input: JsonValue;
+  readonly tenant: string | null;
+  readonly traceparent?: string | null | undefined;
+  readonly phase?: LiveReadPhase | undefined;
+}
+
 export interface LiveQueryDefinition<R extends Row = Row> {
   readonly name: string;
   /** Dependency set for the pre-filter. `x verify` rejects a `live: true` query without one. */
@@ -31,7 +45,7 @@ export interface LiveQueryDefinition<R extends Row = Row> {
    * FOR `tenant`: the org of the subscribers this window serves, `null` for subscribers that carry
    * none. A window is keyed by it (`live-tenant.ts`), so one read is never two orgs' rows.
    */
-  snapshot(args: { input: JsonValue; tenant: string | null }): Promise<SnapshotResult<R>>;
+  snapshot(args: SnapshotArgs): Promise<SnapshotResult<R>>;
   /** Subscribe-time gate. Throws to deny — the same `policy` used by HTTP, jobs, and MCP. */
   authorize?(args: { actor: Actor | null; input: JsonValue }): void | Promise<void>;
   /**

package/src/live-definition.ts

@@ -16,7 +16,13 @@ import {
   serviceActor,
   withChildContext,
 } from '@ultimat3/core';
-import { type AnyQuery, queryHash, queryName, spendQueryLimit } from '@ultimat3/query';
+import {
+  type AnyQuery,
+  queryHash,
+  queryName,
+  spendQueryLimit,
+  traceLiveRead,
+} from '@ultimat3/query';
 import { LiveRowUnidentifiedError } from './errors';
 import { isRow, type JsonValue, type Row } from './json';
 import type { LiveQueryDefinition, SnapshotResult } from './live-contract';
@@ -172,7 +178,7 @@ export function liveQueryDefinition(
     prepare: async (input) => {
       await resolve(input);
     },
-    snapshot: async ({ input, tenant }): Promise<SnapshotResult> => {
+    snapshot: async ({ input, tenant, traceparent, phase }): Promise<SnapshotResult> => {
       const window = await resolve(input);
       // The position is taken BEFORE the rows: the rows are then at least that new, so the claim
       // is true. Taken after, a commit landing mid-read was claimed and missing — and every change
@@ -181,7 +187,13 @@ export function liveQueryDefinition(
       // a made-up one: a position the node never held becomes a ring floor every foreign cursor
       // is "inside", and the client that resumed there kept rows this node never patched.
       const lsn = options.lsn?.() ?? '';
-      return { rows: await readFor(options.ctx, tenant, () => window.read()), lsn };
+      // In a span joined to the subscriber's trace: the snapshot a subscribe asked for is its
+      // child, a re-run a change forced links to it (`traceLiveRead`). Inside the tenant's child
+      // context, so the span is the read's and nothing else's.
+      const rows = await readFor(options.ctx, tenant, () =>
+        traceLiveRead(name, phase ?? 'snapshot', traceparent, () => window.read()),
+      );
+      return { rows, lsn };
     },
     matcher: (input) => windows.get(queryHash(name, input))?.matcher ?? UNRESOLVED,
     // Read off the same resolved window as the matcher, so the scope the client keys rows under and

package/src/live-fanout.ts

@@ -11,6 +11,7 @@ import type { LiveSubscription } from './live-contract';
 import { applyToWindow, bridgeChange, type Projection, projectionOf } from './matcher-bridge';
 import { type QueryEntry, refillWindowInLane } from './query-window';
 import { type Subscriber, type SubscriberGate, windowIndex } from './subscriber-gate';
+import { subscriptionKey } from './subscription-book';
 import { type Frame, PROTOCOL_VERSION } from './sync-protocol';
 import { FRAME_LIMITS } from './wire-version';
 
@@ -259,6 +260,45 @@ async function resnapshot(
   return true;
 }
 
+/**
+ * The repair when no change is coming: the socket drained, and a query nobody writes to has no next
+ * fanout to read the mark. Run in the entry's lane, and the mark asked inside it, so two drains
+ * landing together send one snapshot. Named nothing: this window was not read for any write.
+ *
+ * A window nothing trusts stays marked, for the reason `fanoutChange` checks a guess before the
+ * mark: a repair clears it, so one served out of these rows is recorded as healed against rows known
+ * to be wrong. `generation` covers the read in flight: `startRead` has already cleared `stale`.
+ */
+export async function repairSubscriber(
+  deps: FanoutDeps,
+  entry: QueryEntry,
+  subscription: LiveSubscription,
+): Promise<boolean> {
+  if (entry.stale || entry.applied !== entry.generation) return false;
+  if (!subscription.socket.desynced.has(subscription.sid)) return false;
+  const held = entry.subscribers.get(subscriptionKey(subscription.socket.id, subscription.sid));
+  if (held !== subscription) return false;
+  return await resnapshot(deps, entry, subscription, []);
+}
+
+/**
+ * Every mark on one window answered, in its lane: a read just landed, or the node's sweep came round
+ * (a mark's other readers are a change or a drain, and a quiet query may never see either). A stale
+ * window is re-read first, as a fanout would, once a pass however many subscribers it owes. A read
+ * still out is left alone: its landing runs this. Frames that left.
+ */
+export async function repairWindow(deps: FanoutDeps, entry: QueryEntry): Promise<number> {
+  const subscribers = [...entry.subscribers.values()];
+  if (!subscribers.some((held) => held.socket.desynced.has(held.sid))) return 0;
+  if (entry.stale) {
+    await refillWindowInLane(entry);
+    deps.source.floorAt?.(entry.qid, entry.lsn, { exclusive: true });
+    for (const held of subscribers) held.socket.markDesynced(held.sid);
+  }
+  if (entry.applied !== entry.generation) return 0;
+  return await resnapshotAll(deps, entry);
+}
+
 /** A write this truth may hold, and the RECORD key of the row it made — what it is shown by. */
 export interface NamedWrite {
   readonly write: string;

package/src/live-query.ts

@@ -14,14 +14,14 @@ import { LiveQueryUnknownError, SubscriptionLimitError } from './errors';
 import type { JsonValue } from './json';
 import type { LiveQueryDefinition, LiveSubscription, SnapshotResult } from './live-contract';
 import { deliverChange } from './live-deliver';
-import { type FanoutDeps, snapshotFrame } from './live-fanout';
+import { type FanoutDeps, repairSubscriber, repairWindow, snapshotFrame } from './live-fanout';
 import { floorAfterRead } from './live-floor';
 import { DEFAULT_MAX_ENTRIES, type LiveQueryRegistryOptions } from './live-query-options';
 import { reauthorizeSocket } from './live-reauth';
 import { resumeOnto } from './live-resume';
 import { type Charge, type SubscribeArgs, spendOnce } from './live-spend';
 import { liveTenantOf, windowId } from './live-tenant';
-import { fillWindow, type QueryEntry, queryEntry } from './query-window';
+import { fillWindow, noteTraceparent, type QueryEntry, queryEntry } from './query-window';
 import type { SyncSocket } from './socket';
 import { type Subscriber, SubscriberGate } from './subscriber-gate';
 import { SubscriptionBook, subscriptionKey } from './subscription-book';
@@ -171,6 +171,7 @@ export class LiveQueryRegistry {
       name: string;
       input: JsonValue;
       cursor?: LiveCursor | null;
+      traceparent?: string | undefined;
     },
     charge: Charge,
   ): Promise<{ subscription: LiveSubscription; frame: Frame }> {
@@ -184,6 +185,7 @@ export class LiveQueryRegistry {
     await definition.prepare?.(args.input);
 
     const entry = this.#entryFor(qid, definition, args.input, tenant);
+    noteTraceparent(entry, args.traceparent);
     try {
       // Charged where a read happens, never from the cursor's say-so (`live-spend.ts`).
       const pay = () => spendOnce(definition, args.socket, charge, this.#clock);
@@ -336,6 +338,39 @@ export class LiveQueryRegistry {
     });
   }
 
+  /**
+   * This socket's marked subscriptions, repaired now it can take a frame: Bun's `drain`. Frames that
+   * left. Every lane is entered before any is awaited, as `deliverChange` does, so one slow policy
+   * pass holds up its own query id and nothing else.
+   */
+  async repair(socket: SyncSocket): Promise<number> {
+    const repairs = [...socket.desynced].map(async (sid) => {
+      const subscription = this.#book.get(socket.id, sid);
+      const entry = subscription && this.#entries.get(subscription.qid);
+      if (!subscription || !entry) return false;
+      // Its rows are about to be replaced, so wait: this drain is the only one coming. Bounded by
+      // the read's own deadline, and a read that failed staled the window, which refuses below.
+      await entry.reading?.result.catch(() => undefined);
+      return await entry.lock.run(() => repairSubscriber(this.#fanout, entry, subscription));
+    });
+    return (await Promise.all(repairs)).filter(Boolean).length;
+  }
+
+  /** The node's sweep: every window owing a mark, each in its lane, one read a window at most. */
+  async repairMarked(): Promise<number> {
+    const lanes = [...this.#entries.values()].map((entry) =>
+      entry.lock.run(() => repairWindow(this.#fanout, entry)),
+    );
+    let sent = 0;
+    let failure: { readonly error: unknown } | null = null;
+    for (const lane of await Promise.allSettled(lanes)) {
+      if (lane.status === 'fulfilled') sent += lane.value;
+      else failure ??= { error: lane.reason };
+    }
+    if (failure !== null) throw failure.error;
+    return sent;
+  }
+
   #attachUnlessGone(
     entry: QueryEntry,
     socket: SyncSocket,
@@ -416,6 +451,11 @@ export class LiveQueryRegistry {
       lastLsn: this.#lastLsn,
       origin: this.#origin,
     });
+    // A mark refused while this read was out has no other reader on a quiet query. Still stale: the
+    // sweep's, because re-reading here would charge this subscribe for a read it did not ask for.
+    if (window.landed !== null && !entry.stale) {
+      await entry.lock.run(() => repairWindow(this.#fanout, entry));
+    }
     return { rows: await this.#gate.filterRows(entry, who, window.rows), lsn };
   }
 }

package/src/live-spend.ts

@@ -14,6 +14,8 @@ export interface SubscribeArgs {
   readonly input: JsonValue;
   readonly sid?: string;
   readonly cursor?: LiveCursor | null;
+  /** The subscribe frame's `traceparent`, raw: the window's read joins that trace (`query-window`). */
+  readonly traceparent?: string | undefined;
 }
 
 /**

package/src/offline-queue.ts

@@ -9,6 +9,7 @@
 //      to a socket and nothing more, so a drained mutation is `inflight` — not `acked` — until an
 //      `ack`/`fail` frame settles it, or a lost connection returns it to the queue.
 
+import type { ActionPin } from '@ultimat3/core/page';
 import { renderThrowable, stringField } from '@ultimat3/core/page';
 import type { JsonValue } from './json';
 import { OfflineQueueAbandonedError } from './page-errors';
@@ -23,6 +24,8 @@ export interface QueuedMutation {
   readonly seq: number;
   readonly name: string;
   readonly input: JsonValue;
+  /** The action's `http` pin, when the write was made against one (`pinned-wire.ts`). */
+  readonly http?: ActionPin | undefined;
   readonly enqueuedAt: number;
   attempts: number;
   status: MutationStatus;
@@ -215,6 +218,7 @@ export class OfflineQueue {
     key: string;
     name: string;
     input: JsonValue;
+    http?: ActionPin | undefined;
     at?: number;
   }): Promise<QueuedMutation> {
     // Read BEFORE the key is looked up, never between the lookup and the push: with the await in
@@ -244,6 +248,7 @@ export class OfflineQueue {
       seq: this.#nextSeq,
       name: args.name,
       input: args.input,
+      ...(args.http === undefined ? {} : { http: args.http }),
       enqueuedAt: args.at ?? 0,
       attempts: 0,
       status: 'pending',

package/src/outbox-slot.ts

@@ -2,14 +2,20 @@
 // (`boot.ts`) is the one module that constructs it — IndexedDB, the queue, the drain listeners —
 // so a writing island ships this reader and none of that (~7.5 kB it would otherwise carry).
 
+import type { ActionPin } from '@ultimat3/core/page';
 import type { JsonValue } from './json';
 
 export interface OutboxEntry {
   /** The idempotency key the write was first attempted under — the SAME key on every replay. */
   readonly key: string;
-  /** The mutator's action name; the replay POSTs to `actionPath(name)`. */
+  /** The mutator's action name; the replay POSTs to `actionPath(name)` unless `http` pins it. */
   readonly name: string;
   readonly input: JsonValue;
+  /**
+   * The action's pin, as the document stamped it when the write was made — persisted, so a reload
+   * replays it there.
+   */
+  readonly http?: ActionPin | undefined;
 }
 
 /** What a hook asks of the outbox the boot opened: queue a write, list them, replay them. */

package/src/page-errors.ts

@@ -138,3 +138,18 @@ export class CursorStaleError extends RealtimeError {
     });
   }
 }
+
+/**
+ * A write to an action pinned at a `:param` template (`http: { path: '/orders/:id/refund' }`) whose
+ * input could not fill it: no URL exists to send it to, so it is refused before anything is sent
+ * or queued. `name` and `path` are the mutator's declared strings; the input is not rendered.
+ */
+export class MutationPathUnfilledError extends RealtimeError {
+  constructor(args: { name: string; path: string; param: string; reason: string }) {
+    super({
+      code: 'X_MUTATION_PATH_UNFILLED',
+      cause: `the write "${args.name}" is pinned at ${args.path}, and its :${args.param} ${args.reason} — it was not sent; the input must carry the URL's :${args.param} as a non-empty string`,
+      fix: `mutate({ ${args.param}: '<value>', ... })`,
+    });
+  }
+}

package/src/page-outbox.ts

@@ -6,7 +6,6 @@
 
 import type { ClientScope, UltimateError } from '@ultimat3/core/page';
 import {
-  actionPath,
   classifyThrown,
   clientTransport,
   OUTBOX_DRAIN_MESSAGE,
@@ -28,6 +27,7 @@ import {
 import { type OutboxTabs, type OutboxTabsWindow, outboxTabs } from './outbox-tabs';
 import { LocalStoreUnavailableError, OfflineQueueAbandonedError } from './page-errors';
 import { peekPageRealtime } from './page-store';
+import { mutationWire } from './pinned-wire';
 import { carriedBy } from './record-store';
 
 export type { OutboxEntry } from './outbox-slot';
@@ -55,7 +55,7 @@ export interface OutboxOptions {
   readonly local: LocalStore | Promise<LocalStore>;
   readonly principal?: (() => ClientScope['principal']) | undefined;
   /**
-   * One write, over HTTP. Default: `clientTransport` POST to `actionPath(entry.name)`, adding every
+   * One write, over HTTP. Default: `clientTransport` to the entry's pin or `actionPath(entry.name)` (`pinned-wire.ts`), adding every
    * record the answer carried (`type:key`) to `carried` — what its overlay settles against.
    */
   readonly send?: ((entry: OutboxEntry, carried: Set<string>) => Promise<unknown>) | undefined;
@@ -175,7 +175,8 @@ export function localOutbox(options: OutboxOptions): PageOutbox {
     async (mutation: QueuedMutation): Promise<void> => {
       const carried = new Set<string>();
       try {
-        await send({ key: mutation.key, name: mutation.name, input: mutation.input }, carried);
+        const { key, name, input, http } = mutation;
+        await send({ key, name, input, ...(http === undefined ? {} : { http }) }, carried);
       } catch (error) {
         const kind = classifyThrown(error);
         // The network, or a server asking to be asked again: stays queued, and the pass stops so
@@ -297,7 +298,12 @@ export function localOutbox(options: OutboxOptions): PageOutbox {
       return held?.queue.pending().length ?? 0;
     },
     pending: () =>
-      (held?.queue.pending() ?? []).map(({ key, name, input }) => ({ key, name, input })),
+      (held?.queue.pending() ?? []).map(({ key, name, input, http }) => ({
+        key,
+        name,
+        input,
+        ...(http === undefined ? {} : { http }),
+      })),
     refresh: async () => {
       await current();
       await refreshHeld();
@@ -369,11 +375,12 @@ function exclusive<T>(name: string, work: () => Promise<T>): Promise<T> {
 
 const LOCAL_LOCKS: unique symbol = Symbol.for('ultimate.outbox-locks');
 type LockHost = { [LOCAL_LOCKS]?: Map<string, Promise<unknown>> };
-function sendOverHttp(entry: OutboxEntry, carried: Set<string>): Promise<unknown> {
-  return clientTransport({
-    method: 'POST',
-    url: actionPath(entry.name),
-    body: entry.input,
+async function sendOverHttp(entry: OutboxEntry, carried: Set<string>): Promise<unknown> {
+  const wire = mutationWire(entry.name, entry.input, entry.http);
+  return await clientTransport({
+    method: wire.method,
+    url: wire.url,
+    body: wire.body,
     idempotencyKey: entry.key,
     onEnvelope: (envelope) => carriedBy(envelope, carried),
   });

package/src/pinned-wire.ts

@@ -0,0 +1,64 @@
+// Where a page's write is sent: the action's pin — resolved off the document the server stamped
+// (`renderedActionPin`) — with `:param`s filled and dropped from the body by core's `fillWire`, the
+// request `action.client()` makes; else `POST actionPath(name)` with the whole input, as always.
+
+import type { ActionPin, PinnedActionMethod } from '@ultimat3/core/page';
+import { actionPath, fillWire } from '@ultimat3/core/page';
+import type { JsonValue } from './json';
+import { MutationPathUnfilledError } from './page-errors';
+
+export interface MutationWire {
+  readonly method: PinnedActionMethod;
+  readonly url: string;
+  readonly body: JsonValue;
+}
+
+const METHODS: readonly unknown[] = ['POST', 'PUT', 'PATCH', 'DELETE'];
+
+/**
+ * One leading `/` and no second, then printable ASCII only (`!`–`~`, the backslash cut out): no
+ * scheme can open it, and no whitespace, control or `\` survives — a URL parser drops a tab or
+ * newline (`/\t/host` reads as `//host`) and reads `\` as `/`. A stamped pin is plain ASCII.
+ */
+const SAME_ORIGIN_PATH = /^\/(?!\/)[!-[\]-~]*$/;
+
+/**
+ * The pin, when it is one this build would have stamped. Checked HERE, the one door every write
+ * reaches the wire through — fresh off the document or replayed off disk — because the outbox's
+ * entries come back from IndexedDB, which anything on the origin can rewrite: one check at the
+ * wire covers every store a pin can rest in, where a check at each load would be one per store.
+ */
+function trustedPin(pin: unknown): ActionPin | undefined {
+  if (typeof pin !== 'object' || pin === null) return undefined;
+  const path: unknown = Reflect.get(pin, 'path');
+  const method: unknown = Reflect.get(pin, 'method');
+  if (typeof path !== 'string' || !SAME_ORIGIN_PATH.test(path) || !METHODS.includes(method)) {
+    return undefined;
+  }
+  return pin as ActionPin;
+}
+
+/**
+ * Refuses (`X_MUTATION_PATH_UNFILLED`) an input that leaves a `:param` of the pin unfilled. A pin
+ * that is not a same-origin path and a known verb is dropped for `POST actionPath(name)`: the
+ * server answers that URL or refuses it, and nothing leaves the origin.
+ */
+export function mutationWire(
+  name: string,
+  input: JsonValue,
+  stored: ActionPin | undefined,
+): MutationWire {
+  const pin = trustedPin(stored);
+  if (pin === undefined) return { method: 'POST', url: actionPath(name), body: input };
+  const filled = fillWire(pin.path, input);
+  if (!filled.ok) {
+    throw new MutationPathUnfilledError({
+      name,
+      path: pin.path,
+      param: filled.missing,
+      reason: filled.reason,
+    });
+  }
+  // The input's own keys, minus the URL's: still JSON.
+  return { method: pin.method, url: filled.url, body: filled.rest as JsonValue };
+}

package/src/query-poll.ts

@@ -0,0 +1,19 @@
+// `useQuery`'s timed re-read, as a VALUE the caller imports: `{ poll: pollEvery(ms) }`. Its own
+// module so the timer (core's `visibleInterval`) is in an island's bundle only when the island
+// polls — `useQuery` itself never references it, and a live-only island stays its old size.
+
+import { type VisibleIntervalOptions, visibleInterval } from '@ultimat3/core/page';
+
+/** What `useQuery` starts with its `refetch`; the disposer is called by `release()`. */
+export interface QueryPoll {
+  start(run: () => Promise<void>): () => void;
+}
+
+/**
+ * Re-read every `ms` through `visibleInterval`: no read while the tab is hidden, one make-up read
+ * when it shows, none after a lost session. `maxMs` backs the period off toward it. A non-finite
+ * value is `visibleInterval`'s refusal (`finiteOption`), raised when the read starts.
+ */
+export function pollEvery(ms: number, options: VisibleIntervalOptions = {}): QueryPoll {
+  return { start: (run) => visibleInterval(run, ms, options) };
+}