@spooky-sync/core 0.0.1-canary.355 → 0.0.1-canary.356

package/dist/otel/index.d.ts

@@ -1,4 +1,4 @@
-import { m as PinoTransmit } from "../types.js";
+import { h as PinoTransmit } from "../types.js";
 import { Level } from "pino";
 
 //#region src/otel/index.d.ts

package/dist/types.d.ts

@@ -1,9 +1,218 @@
-import { AccessDefinition, ColumnSchema, QueryPlan, QueryPlan as QueryPlan$1, RecordId, SchemaStructure, TypeNameToTypeMap, WhereNode } from "@spooky-sync/query-builder";
+import { AccessDefinition, ColumnSchema, FinalQuery, GetTable, QueryBuilder, QueryPlan, QueryPlan as QueryPlan$1, RecordId, SchemaStructure, TableModel, TableNames, TypeNameToTypeMap, WhereNode, WhereNode as WhereNode$1 } from "@spooky-sync/query-builder";
 import { RecordId as RecordId$1, Surreal, SurrealEvents, SurrealTransaction } from "surrealdb";
 import { Level, Level as Level$1, Logger, LoggerOptions } from "pino";
 
-//#region src/modules/auth/impersonation.d.ts
+//#region src/services/logger/index.d.ts
+type Logger$1 = Logger;
+/** One line the logger wrote, as the DevTools Logs tab and the MCP read it. */
+interface CapturedLog {
+  /** Monotonic for the page's lifetime; a reader resumes after the last one it holds. */
+  seq: number;
+  time: number;
+  /** Pino's numeric level: 10 trace … 60 fatal. */
+  level: number;
+  msg: string;
+  /** The whole log object as JSON (what the console printed), capped at {@link LogTap.LINE_MAX}. */
+  line: string;
+}
+interface LogRead {
+  entries: CapturedLog[];
+  /** `seq` of the newest captured line; pass it back as `after` to resume. */
+  head: number;
+  /** Lines after `after` the ring overwrote before they were read (cleared ones excluded). */
+  dropped: number;
+  consoleLevel: Level;
+  captureLevel: Level;
+}
+/**
+ * JSON for a log object that can never throw into the call site: Errors keep
+ * their message and stack (plain `JSON.stringify` prints `{}`), bigints become
+ * strings, and a cycle prints `[Circular]` instead of throwing.
+ */
+
+/**
+ * The page-side log buffer behind the DevTools Logs tab. Always on and
+ * bounded: a line costs the JSON the console write produces anyway, and a
+ * panel opened after boot still sees the boot.
+ *
+ * It also owns the logger's level. The console prints at the configured level
+ * only; `setCaptureLevel` changes what is RECORDED (debug without flooding the
+ * console), live on every child logger, and keeps it for this tab's session so
+ * a reload captures its boot at that level too.
+ */
+declare class LogTap {
+  readonly consoleLevel: Level;
+  static readonly CAPACITY = 500;
+  static readonly LINE_MAX = 4000;
+  private readonly ring;
+  private seq;
+  /** `seq` at the last `clear()`: lines up to here are gone on purpose, not dropped. */
+  private clearedThrough;
+  private readonly listeners;
+  private readonly loggers;
+  private captureLevelValue;
+  constructor(consoleLevel: Level);
+  /** `seq` of the newest captured line. */
+  get head(): number;
+  get captureLevel(): Level;
+  /** What pino has to produce for both the console and the buffer. */
+  get effectiveLevel(): Level;
+  /** Whether the console prints a line at this numeric level. */
+  printsToConsole(level: number): boolean;
+  /** Remember a logger (the root and every child) so a level change reaches it. */
+  track(logger: Logger$1): void;
+  setCaptureLevel(level: Level): void;
+  record(o: Record<string, unknown>, line: string): void;
+  /** Lines after `after` (0 = everything still buffered), oldest first. */
+  read(after?: number, limit?: number): LogRead;
+  clear(): void;
+  /** Called synchronously inside the log call: keep it cheap, never log from it. */
+  subscribe(cb: () => void): () => void;
+}
+//#endregion
+//#region src/modules/channel/index.d.ts
+/**
+ * Peer to peer channels (`-- @channel` tables, `client.channel(query, peers)`).
+ *
+ * A channel is a filter (the `where` of one or more queries on `@channel`
+ * tables) plus the users it connects to. Writes to rows that match the
+ * filter reach the users' tabs straight over the transport (WebRTC by
+ * default), and their tabs fold them in before the database has seen them.
+ * The filter is evaluated here, in plain JS, against the row; the query is
+ * never registered. Optimistic writes, distributed:
+ *
+ * - Updates: persistent fields still go through the normal outbox. A peer
+ *   shows the sent value until its own synced row catches up to it, or for
+ *   `confirmTimeoutMs` at most, so a value the server rejected (or that a
+ *   peer made up) falls back to the server's on its own.
+ * - `-- @ephemeral` fields never reach the database. They live in memory,
+ *   last writer wins, and a peer's values vanish when it disconnects.
+ * - Creates go into the peer's store and circuit like its own optimistic
+ *   create (minus the outbox); deletes hide the row. Both are undone unless
+ *   the server confirms them (see the peer sagas in `mutation/write.saga.ts`).
+ *
+ * Nothing here enforces permissions beyond identity: the transport proves
+ * which user a peer is (the database stamps the signaling rows), a message
+ * is only taken from a user listed by an open channel whose filter the row
+ * matches, and fields must exist and fit their column type. Everything else
+ * is the app's call, through `channels.accept`.
+ *
+ * Update and ephemeral values are folded into subscription output only,
+ * never into the local store.
+ */
+type Row$1 = Record<string, unknown>;
+/** Hybrid logical clock: wall ms, counter, tab peer id. Orders every write. */
+type Hlc = readonly [ms: number, counter: number, peer: string];
+/** One tab of one user. */
+interface PeerRef {
+  readonly user: string;
+  readonly peer: string;
+}
+/** What a message does to its row. */
+type ChannelOpKind = 'update' | 'create' | 'delete';
+/** The one message channels exchange: a write to one row. */
+interface ChannelMessage {
+  readonly t: 'op';
+  /** Absent means `update` (a field patch). */
+  readonly kind?: ChannelOpKind;
+  readonly table: string;
+  readonly id: string;
+  /** Wire-encoded values (see `encodeValue`): the patch, the whole row for a create, `{}` for a delete. */
+  readonly patch: Record<string, unknown>;
+  readonly hlc: Hlc;
+}
+/** How a channel is doing, as `useChannel(...).status()` shows it. */
+type ChannelStatus = 'idle' | 'connecting' | 'connected' | 'failed' | 'unsupported';
+interface ChannelState {
+  readonly status: ChannelStatus;
+  /** Users with at least one tab connected. */
+  readonly peers: ReadonlyArray<string>;
+}
+/** What an `accept` rule decides on. */
+interface ChannelOp {
+  readonly kind: ChannelOpKind;
+  /** The sending user, as the database proved it. */
+  readonly from: string;
+  readonly table: string;
+  readonly id: string;
+  /** The row as this client currently shows it, overlay included; undefined for a create. */
+  readonly row: Row$1 | undefined;
+  /** Decoded field values: the patch, the new row for a create, `{}` for a delete. */
+  readonly patch: Readonly<Row$1>;
+}
+type ChannelAcceptRule = (op: ChannelOp) => boolean;
+interface TransportHooks {
+  /** This tab, or null while signed out. */
+  self(): PeerRef | null;
+  onMessage(from: PeerRef, message: unknown): void;
+  onPeer(peer: PeerRef, up: boolean): void;
+  /** Per user: an attempt is running, a tab is connected, or attempts failed. */
+  onStatus(user: string, status: 'connecting' | 'connected' | 'failed'): void;
+}
+/**
+ * Moves messages between tabs. WebRTC by default; an app that already has a
+ * room (LiveKit, its own relay) can plug that in. `send` is fire and forget.
+ */
+interface ChannelTransport {
+  readonly supported: boolean;
+  /** Users this tab wants connections to: the union over open channels. */
+  want(users: ReadonlySet<string>): void;
+  send(to: PeerRef, message: ChannelMessage): void;
+  close(): void;
+}
+type ChannelTransportFactory = (hooks: TransportHooks) => ChannelTransport;
+interface ChannelsConfig {
+  /**
+   * Per table: decide whether to apply a peer's update. Runs after the
+   * built-in checks (sender listed by an open channel carrying the table,
+   * fields exist and fit).
+   * Without a rule every such update is applied.
+   */
+  accept?: Record<string, ChannelAcceptRule>;
+  /** STUN/TURN servers for the default WebRTC transport. */
+  iceServers?: RTCIceServer[];
+  /** Replace the WebRTC transport. */
+  transport?: ChannelTransportFactory;
+  /** How long a peer's persistent value shows without the server confirming it. Default 5000. */
+  confirmTimeoutMs?: number;
+}
+/** `table:id` for a record id in any spelling, or null. */
 
+/** What a channel carries: the rows of one `@channel` table its filter matches. */
+interface ChannelScope {
+  readonly table: string;
+  readonly where: ReadonlyArray<WhereNode>;
+}
+/** Whether `row` passes a query's `where` (a conjunction of comparisons and `_or` groups). */
+declare function matchesWhere(where: ReadonlyArray<WhereNode>, row: Row$1): boolean;
+/**
+ * The parts of a channel query that do nothing there (a channel only reads
+ * the `where`). Not an error, worth a warning unless `.ignoreUnusedArgs()`.
+ */
+declare function unusedArgs(plan: QueryPlan, isOne?: boolean): string[];
+/**
+ * A query plan as a channel scope, or an error saying why it cannot be one:
+ * the table must be `@channel`, and the filter must be decidable from the
+ * row alone (its own fields, literal values, supported operators). Order,
+ * limit and projection do not matter to a channel and are ignored.
+ */
+
+/** An open channel. `client.channel(...)` wraps it with scoped writes. */
+interface ChannelHandle {
+  /** The tables its queries read. */
+  tables(): ReadonlyArray<string>;
+  state(): ChannelState;
+  /** Called at once with the current state, then on every change. */
+  subscribe(cb: (s: ChannelState) => void): () => void;
+  /** Replace who it connects to (your own id is skipped). */
+  setPeers(peers: Iterable<unknown>): void;
+  /** Replace what it carries (the queries' filters changed). */
+  setScopes(scopes: ReadonlyArray<ChannelScope>): void;
+  close(): void;
+}
+/** How peers' creates and deletes reach the store (the runtime's peer sagas). */
+//#endregion
+//#region src/modules/auth/impersonation.d.ts
 /**
  * Admin impersonation, client side.
  *
@@ -334,7 +543,7 @@ interface RelationFetch {
   table: string;
   matchField: string;
   keys: Id[];
-  where?: WhereNode[];
+  where?: WhereNode$1[];
   orderBy?: OrderBy;
   select?: string[];
 }
@@ -491,74 +700,6 @@ type LocalEngineChoice = 'surrealdb' | 'sqlite' | LocalStore;
 /** Thrown when relation decomposition nests past {@link MAX_RELATION_DEPTH} —
  *  a guard against a cyclic schema producing unbounded fan-out. */
 //#endregion
-//#region src/services/logger/index.d.ts
-type Logger$1 = Logger;
-/** One line the logger wrote, as the DevTools Logs tab and the MCP read it. */
-interface CapturedLog {
-  /** Monotonic for the page's lifetime; a reader resumes after the last one it holds. */
-  seq: number;
-  time: number;
-  /** Pino's numeric level: 10 trace … 60 fatal. */
-  level: number;
-  msg: string;
-  /** The whole log object as JSON (what the console printed), capped at {@link LogTap.LINE_MAX}. */
-  line: string;
-}
-interface LogRead {
-  entries: CapturedLog[];
-  /** `seq` of the newest captured line; pass it back as `after` to resume. */
-  head: number;
-  /** Lines after `after` the ring overwrote before they were read (cleared ones excluded). */
-  dropped: number;
-  consoleLevel: Level;
-  captureLevel: Level;
-}
-/**
- * JSON for a log object that can never throw into the call site: Errors keep
- * their message and stack (plain `JSON.stringify` prints `{}`), bigints become
- * strings, and a cycle prints `[Circular]` instead of throwing.
- */
-
-/**
- * The page-side log buffer behind the DevTools Logs tab. Always on and
- * bounded: a line costs the JSON the console write produces anyway, and a
- * panel opened after boot still sees the boot.
- *
- * It also owns the logger's level. The console prints at the configured level
- * only; `setCaptureLevel` changes what is RECORDED (debug without flooding the
- * console), live on every child logger, and keeps it for this tab's session so
- * a reload captures its boot at that level too.
- */
-declare class LogTap {
-  readonly consoleLevel: Level;
-  static readonly CAPACITY = 500;
-  static readonly LINE_MAX = 4000;
-  private readonly ring;
-  private seq;
-  /** `seq` at the last `clear()`: lines up to here are gone on purpose, not dropped. */
-  private clearedThrough;
-  private readonly listeners;
-  private readonly loggers;
-  private captureLevelValue;
-  constructor(consoleLevel: Level);
-  /** `seq` of the newest captured line. */
-  get head(): number;
-  get captureLevel(): Level;
-  /** What pino has to produce for both the console and the buffer. */
-  get effectiveLevel(): Level;
-  /** Whether the console prints a line at this numeric level. */
-  printsToConsole(level: number): boolean;
-  /** Remember a logger (the root and every child) so a level change reaches it. */
-  track(logger: Logger$1): void;
-  setCaptureLevel(level: Level): void;
-  record(o: Record<string, unknown>, line: string): void;
-  /** Lines after `after` (0 = everything still buffered), oldest first. */
-  read(after?: number, limit?: number): LogRead;
-  clear(): void;
-  /** Called synchronously inside the log call: keep it cheap, never log from it. */
-  subscribe(cb: () => void): () => void;
-}
-//#endregion
 //#region src/services/database/database.d.ts
 declare abstract class AbstractDatabaseService {
   protected client: Surreal;
@@ -1649,6 +1790,14 @@ interface Sp00kyConfig<S extends SchemaStructure> {
    * out of apps that don't use collaboration. Defaults to `false`.
    */
   crdt?: boolean;
+  /**
+   * Peer to peer channels for `-- @channel` tables (see `.channel(peers)` on
+   * a query). `accept` holds the app's rules per table: which peer updates to
+   * apply. `iceServers` configures the default WebRTC transport (a public
+   * STUN server when omitted; add TURN for networks that block direct
+   * connections), `transport` replaces it.
+   */
+  channels?: ChannelsConfig;
   /**
    * Cadence (ms) for the `_00_list_ref` poll that catches cross-session
    * UPDATEs the SurrealDB v3 LIVE-permission gap drops. Lower = faster
@@ -2234,5 +2383,22 @@ interface DebounceOptions {
    */
   flushOnHide?: boolean;
 }
+/** A query a channel takes its filter from: a builder or a built query, on a `-- @channel` table. */
+type ChannelQuery<S extends SchemaStructure, T extends TableNames<S>> = QueryBuilder<S, T, any, any, any> | FinalQuery<S, T, any, any, any, any>;
+/**
+ * An open peer to peer channel (`client.channel(queries, peers)`): its
+ * state, plus writes that go to ITS peers only (when the row matches its
+ * filter). Plain `create` / `update` / `delete` reach the peers of every
+ * open channel whose filter the row matches.
+ */
+interface Sp00kyChannel<S extends SchemaStructure, T extends string> extends Omit<ChannelHandle, 'tables' | 'setScopes'> {
+  /** The tables its queries read. */
+  tables(): ReadonlyArray<T>;
+  /** Replace the queries (their filters changed). */
+  setQueries(queries: ChannelQuery<S, T & TableNames<S>> | ReadonlyArray<ChannelQuery<S, T & TableNames<S>>>): void;
+  update<N extends T>(table: N, id: string, data: Partial<TableModel<GetTable<S, N & TableNames<S>>>>, options?: UpdateOptions): Promise<Partial<TableModel<GetTable<S, N & TableNames<S>>>>>;
+  create<N extends T>(id: `${N}:${string}`, data: Partial<TableModel<GetTable<S, N & TableNames<S>>>>): Promise<Partial<TableModel<GetTable<S, N & TableNames<S>>>>>;
+  delete<N extends T>(table: N, id: string): Promise<void>;
+}
 //#endregion
-export { WebPushModule as $, RegistrationTimings as A, RemoteDatabaseService as At, SyncHealthConfig as B, ImpersonationTimers as Bt, QueryStatusCallback as C, SIGN_OUT_HOOK_TIMEOUT_MS as Ct, ReconnectConfig as D, AuthEventTypeMap as Dt, QueryUpdateCallback as E, AuthEventSystem as Et, Sp00kyQueryResultPromise as F, EventDefinition as Ft, PushDeviceKind as G, impersonationFromToken as Gt, TimingPhase as H, SESSION_POLL_MS as Ht, StorageHealth as I, EventSystem as It, WebPushError as J, WebPushConfig as K, renewDelayMs as Kt, StorageHealthStatus as L, IMPERSONATION_ACCESS as Lt, ServerViewMeta as M, Logger$1 as Mt, Sp00kyConfig as N, LocalStore as Nt, RecordVersionArray as O, AuthEventTypes as Ot, Sp00kyQueryResult as P, SealedQuery as Pt, WebPushMessageInput as Q, StoreType as R, ImpersonationInfo as Rt, QueryStatus as S, REFUSAL_RECHECK_MIN_MS as St, QueryTimings as T, SignOutHook as Tt, UpdateOptions as U, TokenClaims as Ut, SyncHealthStatus as V, ORIGIN_TOKEN_KEY as Vt, PUSH_ENDPOINT_KEY as W, decodeTokenClaims as Wt, WebPushInfo as X, WebPushErrorCode as Y, WebPushMessage as Z, QueryAuthorityCallback as _, WebPushClientMessage as _t, InlineRow as a, WebPushUnsupportedReason as at, QueryHash as b, AuthService as bt, MembershipOutcome as c, BridgeSignOutMessage as ct, MutationEventType as d, PushNotification as dt, WebPushSubscribeOptions as et, PersistenceClient as f, PushNotificationAction as ft, PreloadRefresh as g, PushUrgency as gt, PreloadOptions as h, PushPayloadKind as ht, EventSubscriptionOptions as i, WebPushUnsubscribeOptions as it, RunOptions as j, LogTap as jt, RecordVersionDiff as k, createAuthEventSystem as kt, MutationCallback as l, BridgeTokenMessage as lt, PinoTransmit as m, PushPayload as mt, DebounceOptions as n, WebPushSyncOptions as nt, Level$1 as o, WebPushUpdateOptions as ot, PhaseStat as p, PushOp as pt, WebPushDevice as q, sameImpersonation as qt, EdgeDelta as r, WebPushSyncStatus as rt, MATERIALIZATION_SAMPLE_WINDOW as s, detectWebPushSupport as st, ConnectionState as t, WebPushSupport as tt, MutationEvent as u, PUSH_PAYLOAD_VERSION as ut, QueryConfig as v, isPushPayload as vt, QueryTimeToLive as w, SignOutContext as wt, QueryState as x, ImpersonationCandidate as xt, QueryConfigRecord as y, ActiveImpersonation as yt, SyncHealth as z, ImpersonationTimerHost as zt };
+export { WebPushMessage as $, ChannelState as $t, RecordVersionDiff as A, AuthEventTypes as At, StoreType as B, ImpersonationTimers as Bt, QueryStatus as C, ImpersonationCandidate as Ct, QueryUpdateCallback as D, SignOutHook as Dt, QueryTimings as E, SignOutContext as Et, Sp00kyConfig as F, EventDefinition as Ft, UpdateOptions as G, impersonationFromToken as Gt, SyncHealthConfig as H, SESSION_POLL_MS as Ht, Sp00kyQueryResult as I, EventSystem as It, WebPushConfig as J, ChannelAcceptRule as Jt, PUSH_ENDPOINT_KEY as K, renewDelayMs as Kt, Sp00kyQueryResultPromise as L, IMPERSONATION_ACCESS as Lt, RunOptions as M, RemoteDatabaseService as Mt, ServerViewMeta as N, LocalStore as Nt, ReconnectConfig as O, AuthEventSystem as Ot, Sp00kyChannel as P, SealedQuery as Pt, WebPushInfo as Q, ChannelScope as Qt, StorageHealth as R, ImpersonationInfo as Rt, QueryState as S, AuthService as St, QueryTimeToLive as T, SIGN_OUT_HOOK_TIMEOUT_MS as Tt, SyncHealthStatus as U, TokenClaims as Ut, SyncHealth as V, ORIGIN_TOKEN_KEY as Vt, TimingPhase as W, decodeTokenClaims as Wt, WebPushError as X, ChannelMessage as Xt, WebPushDevice as Y, ChannelHandle as Yt, WebPushErrorCode as Z, ChannelOp as Zt, PreloadRefresh as _, PushPayloadKind as _t, EventSubscriptionOptions as a, TransportHooks as an, WebPushSyncStatus as at, QueryConfigRecord as b, isPushPayload as bt, MATERIALIZATION_SAMPLE_WINDOW as c, LogTap as cn, WebPushUpdateOptions as ct, MutationEvent as d, BridgeTokenMessage as dt, ChannelStatus as en, WebPushMessageInput as et, MutationEventType as f, PUSH_PAYLOAD_VERSION as ft, PreloadOptions as g, PushPayload as gt, PinoTransmit as h, PushOp as ht, EdgeDelta as i, PeerRef as in, WebPushSyncOptions as it, RegistrationTimings as j, createAuthEventSystem as jt, RecordVersionArray as k, AuthEventTypeMap as kt, MembershipOutcome as l, Logger$1 as ln, detectWebPushSupport as lt, PhaseStat as m, PushNotificationAction as mt, ConnectionState as n, ChannelTransportFactory as nn, WebPushSubscribeOptions as nt, InlineRow as o, matchesWhere as on, WebPushUnsubscribeOptions as ot, PersistenceClient as p, PushNotification as pt, PushDeviceKind as q, sameImpersonation as qt, DebounceOptions as r, ChannelsConfig as rn, WebPushSupport as rt, Level$1 as s, unusedArgs as sn, WebPushUnsupportedReason as st, ChannelQuery as t, ChannelTransport as tn, WebPushModule as tt, MutationCallback as u, BridgeSignOutMessage as ut, QueryAuthorityCallback as v, PushUrgency as vt, QueryStatusCallback as w, REFUSAL_RECHECK_MIN_MS as wt, QueryHash as x, ActiveImpersonation as xt, QueryConfig as y, WebPushClientMessage as yt, StorageHealthStatus as z, ImpersonationTimerHost as zt };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spooky-sync/core",
-  "version": "0.0.1-canary.355",
+  "version": "0.0.1-canary.356",
   "type": "module",
   "sideEffects": false,
   "main": "./dist/index.js",
@@ -75,8 +75,8 @@
     }
   },
   "dependencies": {
-    "@spooky-sync/query-builder": "0.0.1-canary.355",
-    "@spooky-sync/ssp-wasm": "0.0.1-canary.355",
+    "@spooky-sync/query-builder": "0.0.1-canary.356",
+    "@spooky-sync/ssp-wasm": "0.0.1-canary.356",
     "@sqlite.org/sqlite-wasm": "3.53.0-build1",
     "@surrealdb/wasm": "^3.1.0",
     "@surrealdb/wasm-native": "^3.3.4",

package/skills/sp00ky-core/SKILL.md

@@ -139,6 +139,10 @@ act on the tray with `db.failedMutationCount`, `db.subscribeToFailedMutations(cb
 `db.listFailedMutations()`, `db.retryFailedMutation(id)` (a fresh optimistic
 write) and `db.discardFailedMutation(id)`.
 
+## Peer to peer channels (experimental)
+
+On `-- @channel` tables, `client.channel(query, peers)` opens WebRTC channels to the users listed (both sides must list each other) for the rows the query's `where` matches (checked per row, never registered). Plain `client.update` / `create` / `delete` reach the peers of every open channel whose filter the row matches; the handle's own writes limit that to its peers. `-- @ephemeral` fields go only to peers. Order/limit/select/`.one()` warn unless `.ignoreUnusedArgs()`. Follow status with `ch.subscribe(cb)`, close with `ch.close()`. Config: `channels: { accept, iceServers, transport, confirmTimeoutMs }`. Docs: `/docs/client/channels`.
+
 ## Authentication
 
 See [references/auth.md](references/auth.md) for the full auth API.

package/src/client/router.test.ts

@@ -22,6 +22,7 @@ describe('route', () => {
       [{ type: 'GcTick' }, 'dedupe:gc'],
       [{ type: 'Drain' }, 'serial:outbox'],
       [{ type: 'FlushWrite', key: 'k' }, 'serial:outbox-write'],
+      [{ type: 'PeerWriteExpired', id: 'thing:1' }, 'serial:peer:thing:1'],
       [{ type: 'FlushPendingWrites' }, undefined],
       [{ type: 'AdoptPendingWrites' }, 'serial:outbox-write'],
       [{ type: 'PollTick' }, 'dedupe:poll'],

package/src/client/router.ts

@@ -7,7 +7,7 @@ import { fetchRows } from '../query/fetch.saga';
 import { materialize, streamUpdate } from '../query/materialize.saga';
 import { ackPrune, gcTick, lifecycleTick } from '../query/lifecycle.saga';
 import { drain } from '../mutation/push.saga';
-import { adoptPendingWrites, flushPendingWrites, flushWrite } from '../mutation/write.saga';
+import { adoptPendingWrites, flushPendingWrites, flushWrite, peerWriteExpired } from '../mutation/write.saga';
 import { pollTick } from '../sync/poll.saga';
 import { liveChange, liveStart } from '../sync/live.saga';
 import { connectionChanged, selfHealTick, syncOutcome } from '../sync/connection.saga';
@@ -64,6 +64,8 @@ export function route(env: SagaEnv, event: RuntimeEvent): RouteTarget {
       return { saga: drain(env), lane: serial('outbox') };
     case 'FlushWrite':
       return { saga: flushWrite(env, event.key), lane: serial('outbox-write') };
+    case 'PeerWriteExpired':
+      return { saga: peerWriteExpired(event.id), lane: serial(`peer:${event.id}`) };
     case 'FlushPendingWrites':
       return { saga: flushPendingWrites() };
     case 'AdoptPendingWrites':

package/src/client/sp00ky-client.test.ts

@@ -339,3 +339,90 @@ describe('Sp00kyClient facade (builder, devtools source, event fan-out)', () =>
     expect(tuned.tabRole).toBeNull();
   });
 });
+
+describe('Sp00kyClient facade (channels)', () => {
+  const chSchema = {
+    tables: [
+      { name: 'room', columns: { a: { type: 'number', optional: true }, pos: { type: 'string', optional: true, ephemeral: true } }, channel: true },
+    ],
+    backends: {},
+  } as any;
+
+  function channelClient(channels?: unknown) {
+    const services = fakeServiceBundle<any>();
+    const a = fakeAdapters({
+      local: {
+        execute: (async (_q: unknown, vars: any) => ({ id: vars?.id ?? new RecordId('room', '1'), a: 1 })) as any,
+        query: (async () => []) as any,
+      },
+      services: {
+        'hint.read': () => 'u1',
+        'local.usesSurqlSchema': () => false,
+        'auth.restoreSession': async () => null,
+        'auth.sessionAuthId': () => null,
+        'remote.connect': () => new Promise(() => {}),
+      },
+    });
+    const runtime = new Runtime({ env: defaultEnv(chSchema, { materializeDebounceMs: 1 }), adapters: a.adapters, logger: services.logger, tabId: 'tab-test' });
+    const client = new Sp00kyClient<any>({ ...config, schema: chSchema, channels } as any, { services, runtime });
+    return { client, runtime };
+  }
+
+  it('opens a channel, keeps ephemeral fields out of writes, scopes its own writes, and wires peer rows to the runtime', async () => {
+    let wanted: ReadonlySet<string> = new Set();
+    const { client } = channelClient({ transport: () => ({ supported: true, want: (u: ReadonlySet<string>) => (wanted = u), send() {}, close() {} }) });
+    await client.init();
+    (client as any).channels.setUser('user:a');
+    const ch = client.channel((client.query('room', {} as any) as any).where({ a: 1 }), ['user:a', 'user:b']);
+    const states: string[] = [];
+    ch.subscribe((s) => states.push(s.status));
+    expect([...wanted]).toEqual(['user:b']);
+    expect(states).toEqual(['connecting']);
+    expect(ch.tables()).toEqual(['room']);
+    ch.setQueries([(client.query('room', {} as any) as any).limit(3).ignoreUnusedArgs().build()]);
+    expect(() => client.channel([{} as any], [])).toThrow(/pass a query/);
+
+    // Subscriptions see channel values folded in.
+    const { hash } = await (client.query('room', {} as any) as any).build().run();
+    const stop = await client.subscribe(hash, () => {}, { immediate: true });
+
+    // Ephemeral-only: no write at all.
+    expect(await client.update('room', 'room:1', { pos: '3' })).toEqual({ pos: '3' });
+    expect(client.state.outbox).toHaveLength(0);
+    // Mixed create: the database gets the persistent part only.
+    expect(await client.create('room:2', { a: 1, pos: 'x' })).toMatchObject({ a: 1, pos: 'x' });
+    expect(client.state.outbox).toHaveLength(1);
+    await expect(client.delete('', 'room:2')).resolves.toBeUndefined();
+
+    // The channel's own writes.
+    expect(await ch.update('room', 'room:1', { pos: '4' } as never)).toEqual({ pos: '4' });
+    expect(await ch.create('room:4', { a: 2 } as never)).toBeTruthy();
+    await expect(ch.delete('room', 'room:4')).resolves.toBeUndefined();
+    expect(() => ch.update('nope' as never, 'nope:1', {} as never)).toThrow(/no query on 'nope'/);
+    // The filter is checked against the stored row.
+    expect(await (client as any).channels.deps.rows.read('room:1')).toBeNull();
+
+    const deps = (client as any).channels.deps.rows;
+    expect(await deps.create('room', 'room:3', { a: 1 }, 1000)).toBe(true);
+    expect(client.state.peerWrites.get('room:3')).toMatchObject({ kind: 'create' });
+    expect(await deps.delete('room', 'room:3', 1000)).toBe(true);
+    expect(client.state.peerWrites.has('room:3')).toBe(false);
+    ch.setPeers(['user:c']);
+    expect([...wanted]).toEqual(['user:c']);
+    ch.close();
+    expect([...wanted]).toEqual([]);
+    expect(ch.state().status).toBe('connecting');
+    stop();
+    await client.close();
+  });
+
+  it('builds the WebRTC transport by default (unsupported without RTCPeerConnection)', async () => {
+    const { client } = channelClient();
+    await client.init();
+    (client as any).channels.setUser('user:a');
+    const ch = client.channel((client.query('room', {} as any) as any).build(), ['user:b']);
+    expect(ch.state().status).toBe('unsupported');
+    ch.close();
+    await client.close();
+  });
+});