wenay-common2 1.0.63 → 1.0.64

package/doc/wenay-common2.md

@@ -0,0 +1,334 @@
+# wenay-common2 — BRIEF cheat sheet (notation)
+
+> Root import: `import { ... } from "wenay-common2"`.
+> Notation: `name(args: types) -> ret  // note`. Types are shown where they decide a correct call (callback shape,
+> overloads, return). Short names are **canonical**; removed old names are listed in `NAMING_RENAMES.md`.
+> Full surface → **`wenay-common2-rare.md`**. Code style → `CLAUDE.md`. Full RPC guide → `rpc.md`.
+
+## ⭐ events — `listen` / `listenStore`
+```
+import { listen, listenStore, mapListen } from "wenay-common2"
+
+listen<T>(opts?) -> [emit, listen]                   // pure event list: no local value storage, no current replay
+emit(...args: T)                                     // dispatch event only
+listen.on(cb: (...args: T) => void, {key?, cbClose?}) -> off
+listen.once(cb, {key?}) -> off                       // one future event
+listen.onClose(cb: () => void) -> off
+listen.close()                                       // clear listeners + fire close hooks + teardown producer
+listen.count() -> number
+
+listenStore<T>({current, ...opts}) -> [emit, listen]
+  // store wrapper: current() reads external store by reference; the listener does not keep its own value copy
+listen.on(cb, {current: true}) -> off                // current store value first, then future events
+listen.on(cb) -> off                                 // future events only
+listen.once(cb, {current: true}) -> off              // one value from current store, if present; otherwise waits future event
+listen.once(cb) -> off                               // one future event
+listen.on(cb, {current: () => argsOrUndefined}) -> off
+
+opts: { fast? = true, event?(t: 'add'|'remove', count, api), closeOn? }
+```
+```
+mapListen<TIn, TOut>(src, map: (...a: TIn) => TOut | null, opts?) -> [emit, listen]   // map+filter (null skips); lazy subscribe
+joinListens(listens | ports, keyExtractor?) -> { listen, add(port, key?), pending: number, clear(tid?) }   // zip by key
+```
+## ⭐ sleep
+```
+sleepAsync(ms = 0) -> Promise<void>
+```
+
+## ⏱️ async
+```
+createThrottle() -> { throttle(ms: number, fn: () => void) -> void,
+                      debounce(ms: number, fn: () => void) -> Promise<void> }
+  // fn is a ZERO-ARG thunk the scheduler runs itself; NOT a lodash-style wrapper that returns a callable
+  // ONE createThrottle() = ONE shared limiter (shared busy/pending) — use a SEPARATE instance per operation;
+  //   throttle + debounce on the SAME instance contend (a busy throttle silently drops the debounce's trailing run)
+createAsyncQueue(concurrency = 1) -> { add<R>(task: () => Promise<R>) -> Promise<R>, onIdle() -> Promise<void>, size: number }   // p-queue
+createReadyGate() -> { add(fn: () => void), ready() }                  // buffer fns until ready(), then run them in order
+promiseProgress<T>(arr: (Promise<T> | (() => Promise<T>))[]) -> {
+  onOk(cb), onError(cb), all() -> Promise<any[]>, allSettled(), items(), stats() -> { ok: number, error: number, count: number } }
+  // factory entries start on .all()/.allSettled()/items() (once); .all() rejects like Promise.all — read aggregate progress via stats()
+// alias: enhancedWaitRun->createThrottle · createTaskQueue->createReadyGate(.setReady->.ready) · createAsyncQueue.enqueue->add · .getQueueSize->size
+```
+
+## 🧰 core — clone / compare
+```
+clone<T>(v: T) -> T            // deep: cycles + Map/Set/Date, rebinds functions      (alias: deepClone)
+shallowClone<T>(v: T) -> T
+isEqual(a, b) -> boolean       // PLAIN object/array trees ONLY; on Map/Set/Date it returns a vacuous `true` — don't use it on them   (alias: deepEqual)
+shallowEqual(a, b) · arrayShallowEqual(a, b) -> boolean      // strict-by-key vs loose-by-index — both kept on purpose
+toImmutable<T>(o: T) -> T      // deep-frozen clone + Mutable:false marker
+JSON_clone<T>(o: T) -> T       // JSON round-trip; DROPS Map/Set (-> {}) and turns Date -> string. NOT a rich clone — use clone() for those
+```
+
+## 🧰 core — binary search / maps / mutex / memo
+```
+BSearch<T>(arr: ArrayLike<T>, value: T | comparer, match?: 'equal'|'lessOrEqual'|'greatOrEqual', sort?: SortMode) -> number
+  // comparer is (item: T) => number  OR  (a: T, b) => number; without it, T must have valueOf():number
+BSearchNearest<T>(arr: ArrayLike<T>, value: number, getter?: (el: T) => number, maxDelta?: number) -> number
+new MapExt<K,V>() / new WeakMapExt<K,V>():  .getOrSet(k, () => v) -> V          // lazy insert (a plain value is also accepted)
+new Mutex():  .runExclusive<T>(fn: () => T | Promise<T>) -> Promise<T>   |   .lock() -> Promise<release: () => void>   // runExclusive: was dispatch
+MemoFunc<A extends any[], R>(opts?: { timeDelta?: number, maxLimits?: number }) -> { func(...a: A) -> R, cleanAll(), memo }   // TTL + LRU; per-call {timeDelta, reSave}
+```
+
+## 🔢 core — number (frequent)
+```
+round(value: number, digits = 0) -> number                  // round to N decimals          (alias: NormalizeDouble)
+roundSig(value: number, { digitsR?: number /*total significant digits*/, digitsPoint? = 4, type?: 'max'|'min' }) -> number
+  // round to N significant digits — roundSig(1234.5678, {digitsR: 3}) -> 1230     (alias: NormalizeDoubleAnd)
+gcd(a: number, b: number, digits = 8) -> number   |   gcd(values: Iterable<number>, digits = 8) -> number
+  // floats ok; in the ITERABLE overload the 2nd arg is PRECISION digits, not an operand   (alias: MaxCommonDivisor[OnArray])
+formatAuto(value: number, maxDigits = 8) -> string          // shortest decimal string      (alias: DblToStrAuto)
+decimals(value: number, maxDigits = 8, minDigits = 0) -> number   // count of meaningful decimals (alias: GetDblPrecision)
+```
+
+## ⏰ time
+```
+format(date: Date, pattern, { utc? = true }) -> string     // (alias of 11 timeToStr_*/timeLocalToStr_*)
+  pattern: 'HH:mm:ss' | 'HH:mm:ss.SSS' | 'yyyy-MM-dd'
+         | 'yyyy-MM-dd HH:mm' | 'yyyy-MM-dd HH:mm:ss' | 'yyyy-MM-dd HH:mm:ss.SSS'
+         | 'yyyy-MM-dd HH:mm O' | 'yyyy-MM-dd HH:mm:ss O'   // O = GMT offset (local)
+  { utc: false } -> local variants
+formatDuration(ms: number, pattern?: 'H:mm:ss' | 'H:mm:ss.SSS') -> string   // clock; hours unbounded
+durationToStr(ms: number) -> string                        // humanized
+minDate(a: Date | null, b: Date | null) / maxDate(a, b) -> Date | null      // null-tolerant   (alias: MinTime/MaxTime)
+convertDatesToStrings(obj)                                 // Date -> strings, recursively (logs)
+const:  H1_S D1_S W1_S · M1_MS H1_MS D1_MS W1_MS
+```
+
+## 🌐 rpc (brief) — transport is ALWAYS caller-supplied (`{emit,on}`); there is NO url / built-in socket
+```
+// SERVER: `object` is the impl tree, `socket` is a {emit,on} transport adapter
+createRpcServerAuto({ socket: {emit, on}, object, socketKey: string, auth?, limits?, maxPerListen?, throttle?, opt?, replay?, replayOpts? }) -> { api, ... }
+  // replay: false|'auto' (default)|'force' — facade members that are replay lines (replayListen) are exposed
+  //   with BOTH surfaces under the SAME key: legacy plain-Listen path byte-for-byte + line/frameLine/since/keyframe/frame.
+  //   Upgrading listen -> replayListen is a declaration-site-only change; the facade and clients don't move.
+  // replayOpts: {pending?, highWater?, lowWater?, pollMs?} — per-connection lag gate for 'frame'-policy subscribers
+  //   (pending defaults to socket.io writeBuffer; gates close on disconnect automatically). Replay lines are never throttled.
+createRpcServer(opts)        // lower-level core (same { socket, object, socketKey })
+noStrict(obj)                // mark a dynamic subtree (no schema)
+endCallback(fn)              // mark an RPC stream-callback's end   (alias: rpcEndCallback)
+
+// CLIENT hub: takes TWO functions — a socket factory + a schema builder; it is NOT an {url} or an options bag
+createRpcClientHub(
+  createSocket: (token: string | null) => socket,             // YOU build the socket, e.g. socket.io io(url, {auth:{token}})
+  schemaBuilder: (rpc) => ({ key: rpc<Api>('socketKey') }),   // declare each socketKey's typed API
+  hubOpts?: { opt? },
+) -> hub
+hub:     connect(token) -> Promise<clients>  ·  reauth(token)  ·  facade  ·  promise  ·  socket  ·  onConnect/onDisconnect   // connect: was setToken
+         // connect()'s promise resolves on the socket's 'connect' event; for in-proc/loopback (no 'connect') use hub.facade + await hub.promise
+client (on clients[key], NOT on the hub):  func (proxy) · strict (schema-safe) · close() · ready() · init() · subscriptions()
+         // pipe = batch a server chain in one packet · space = fire-and-forget
+
+// minimal wiring (the part no signature can show):
+const [tick, ticks] = listen<[number]>()
+createRpcServerAuto({ socket, object: { math: { add: (a, b) => a + b, ticks } }, socketKey: 'math' })
+const hub = createRpcClientHub((t) => io(url, { auth: { t } }), (rpc) => ({ math: rpc<Api>('math') }))
+const c = await hub.connect(token)               // c = facade of per-socketKey clients
+await c.math.ready();  await c.math.func.add(2, 3)
+const l = c.math.func as unknown as DeepSocketListen<Api>  // typed Listen projection; wrap as webListen(c.math) in app code
+const off = l.ticks.on(v => console.log(v))                // canonical stream subscribe; off is callable and awaitable
+off()                                                     // unsubscribe; .callback/.removeCallback are legacy compat, don't teach them
+l.ticks.once(v => console.log(v))                         // one event, then auto-off
+
+// replay upgrade — ONE WORD at the declaration site, everything below follows automatically:
+// const [tick, ticks] = listen<[number]>()                                       // before
+const [tick, ticks] = replayListen<[number]>({history: 1024, current: 'last'})    // after — same facade, same key
+// legacy subscribers unchanged (byte-for-byte). Replay consumers now also get:
+const sub = replaySubscribe(l.ticks, v => {}, {since: saved, onSeq: s => saved = s})  // catch-up + live, no gaps/dups
+const sub2 = replaySubscribe(c.math.func.ticks, v => {})  // replay members project on func/strict directly — no cast needed
+await l.ticks.frame(mySeq)                                // pull at YOUR pace (50ms timer etc.) — server condenses via the line's frame lambda
+// full guide + examples → rpc.md; frame model / lag policies → 🎞️ recipe below and rare docs
+```
+
+## 🔁 Observe — reactive state + store/mirror API
+> `import { Observe } from "wenay-common2"` or `import * as Observe from "wenay-common2/observe"`.
+> This is the documented v2 reactive/store surface.
+```
+// coarse reactive object: subscribe to the fact that a subtree changed, then re-read current state
+Observe.reactive<T extends object>(obj, opts?) -> T
+Observe.onUpdate(node, cb: () => void) -> off
+Observe.onUpdatePaths(node, cb: ({paths}) => void) -> off   // optional dirty paths, relative to node
+Observe.flushReactive(node) -> Promise<void>
+Observe.toRaw(node) -> raw value behind the proxy              // snapshots/serialization without touching lazy nodes
+Observe.listenUpdate(node) -> Listen<void>                  // RPC bridge for coarse change notifications
+Observe.listenUpdatePaths(node) -> Listen<{paths: PropertyKey[][]}>
+opts: { drain?: "immediate"|"micro"|number|((flush)=>void), depth?, eager? }
+
+// path-addressed store facade over reactive()
+Observe.createStore<T extends object>(initial, opts?) -> Store<T>
+store.state                                                   // reactive data object; write normally
+store.node.path.to.leaf.get()/snapshot()/replace(v)           // set(v) is a deprecated alias of replace(v)
+store.node.path.to.leaf.on((value, ctx) => {}, {current?, drain?, key?}) -> off
+store.node.path.to.leaf.once(cb, opts?) -> off
+store.update(mask, opts?) -> selection                         // typed selected snapshot
+selection.get() · selection.on((snap, ctx)=>{}, opts?) -> off · selection.onEach((value, ctx)=>{}, opts?) -> off
+store.each(opts?) -> Listen<[key, value, ctx]>                 // changed TOP-LEVEL keys as a plain Listen — THE per-key feed
+  // one call per CHANGED key per drain window: value = current store.state[key] at flush time; undefined = key deleted;
+  //   two writes to one key in a window = ONE call (last value); deeper dirt (state.a.b = ...) reports 'a' once
+  // root replace (store.replace / mirror keyframe) EXPANDS: one call per key of the new state + (key, undefined)
+  //   per key the replace removed — cold start / reconnect are NOT special cases for per-key consumers
+  // plain Listen shape (on(cb) -> off · once · count); zero cost while it has no subscribers
+  // NOT update(true).onEach: onEach fires per SELECTED path, and mask true selects the root —
+  //   ONE call per window with the whole dict (a dev warn points to each())
+store.count() -> number
+
+// network shape: backend exposes snapshots + changed Listen; frontend mirrors selected masks locally
+Observe.exposeStore(store, opts?) -> { get(mask?), set(path,value), replace(path,value), changed, changedPaths, patches?, changedData? }
+Observe.createStoreMirror(remote, initial, opts?) -> store & { sync(mask, opts?) -> Promise<off>; syncPatches(mask, opts?) -> Promise<off>; syncChangedData(mask, opts?) -> Promise<off> }
+// changedPaths is optional optimization: mirror pulls mask ∩ dirty paths; fallback is changed -> get(mask).
+// Optional push-data mode: exposeStore(store,{push:true}) + syncPatches/syncChangedData; details in rare docs.
+
+// Sequenced sync (replay line): seq-numbered patch stream — keyframe catch-up, reconnect by seq (tail, not snapshot)
+Observe.exposeStoreReplay(store, {history? = 1024}) -> { api /* spread into the RPC server object */, replay, close }
+  // the patch line declares its condensing `frame` itself (last patch per exact path) — reconnect tails and
+  //   lag recovery arrive as a mini-frame (changed paths only), zero config
+Observe.syncStoreReplay(mirror, remote /*{line, since, keyframe, frame?} of api.replay*/, {since?, onSeq?}) -> off
+  // off.ready (catch-up done) · off.seq() (save for reconnect: syncStoreReplay(..., {since: prev.seq()}))
+  // lagging/late client NEVER gets a backlog: evicted seq -> ONE fresh keyframe + live
+  // freshness is an option, not consumer boilerplate: {staleMs, onStale} flags a silent line / stale keyframe (edge-triggered both ways; 🎞️ in rare docs)
+Observe.syncStoreReplayEach<T>(remote, (key, value, ctx) => {}, opts?) -> off & {store, ready, seq(), isStale(), lastTs()}
+  // one-call remote fold: mirror store + syncStoreReplay + store.each() — the callback fires per CHANGED
+  //   top-level key; first delivery = keyframe EXPANDED per key; (key, undefined) = key deleted
+  // opts = all replaySubscribe opts (since/onSeq/policy/staleMs/onStale/onError...) + {drain?, initial?}
+  // off() tears down BOTH the store sub and the wire sub; direct reads via off.store.state.KEY
+  // reconnect: syncStoreReplayEach(remote, cb, {since: prev.seq(), initial: prev.store.snapshot()})
+  //   — the tail lands ON TOP of the previous state (a fresh empty mirror would not converge)
+// Offline persisted mirror (snapshot mode): local cache first, then replay catch-up by seq
+Observe.createOfflineStore({key, remote?, initial, storage, version?, debounceMs?, syncOpts?}) -> Promise<store & {ready, flush(), close(), status(), statusListen, reconnect(remote)}>
+Observe.persistStore(store, {key, storage, seq?, debounceMs?}) -> {flush, forceFlush, close, setSeq, seq, status, statusListen}
+Observe.createMemoryOfflineStorage(initial?) -> OfflineStorage
+  // persists {version, seq, snapshot, savedAt}; seq is the correctness coordinate, timestamps are UX/freshness only
+  // mode:'topLevel' is reserved; first implemented mode is snapshot
+
+// Declarative resource manager above mirror/replay/offline: app chooses what to start, not the store core
+Observe.managedStore.mirror({remote, initial, mask, tags?, priority?, explicitOnly?, large?, sync?})
+Observe.managedStore.replay({remote, initial, tags?, priority?, explicitOnly?, large?, syncOpts?})
+Observe.managedStore.offline({remote?, initial, storage, storageKey?, tags?, priority?, explicitOnly?, large?, syncOpts?})
+Observe.createStoreManager(resources) -> {plan(opts?), start(key, opts?), startPlanned(opts?), stop(key), stopAll(), get(key), touch(key, weight?), usage(), statusListen, handles}
+  // plan excludes explicitOnly/large by default; {includeExplicit, includeLarge} opts opt them in
+// Slow-client conflation: recipe section 🎞️ below. Full generic surface (any event line, history/time-travel) -> Replay namespace, 🎞️ in rare docs.
+// Object add/delete/deep set are paths. Array mutation dirties the whole array branch, not splice internals.
+```
+```
+type Market = {data: {BTC?: number; ETH?: number}; meta: {status?: string}}
+const market = Observe.createStore<Market>({data: {BTC: 1, ETH: 2}, meta: {status: "ok"}})
+
+market.state.data.BTC = 3                                      // plain local mutation
+market.node.data.BTC.on((v, ctx) => {}, {current: true})        // ctx.path = ["data", "BTC"]
+market.node.data.on(data => {}, {current: true, drain: 50})     // branch snapshot, per-sub drain
+market.update({data: {BTC: true, ETH: true}}, {current: true}).on(snap => {})
+
+// backend facade over RPC
+const api = Observe.exposeStore(market)
+
+// frontend mirror: UI subscribes to local mirror, not RPC directly
+const mirror = Observe.createStoreMirror<Market>(api, {data: {}, meta: {}})
+const stop = await mirror.sync({data: {BTC: true}, meta: {status: true}}, {current: true, drain: 250})  // uses changedPaths when available
+mirror.node.data.BTC.on(v => {}, {current: true})
+stop()
+
+// per-key feed — dict store -> grid rows; keyframe / reconnect are just expansion, not special cases
+type Rows = Record<string, {qty: number}>
+const rows = Observe.createStore<Rows>({})
+const offRows = rows.each().on((key, row) => { /* row === undefined ? removeRow(key) : upsertRow(key, row) */ })
+
+// the same per-key contract over the wire — ONE call (mirror store + syncStoreReplay + each)
+const exposed = Observe.exposeStoreReplay(rows, {history: 1024})   // server side: spread exposed.api into the RPC object
+const feed = Observe.syncStoreReplayEach<Rows>(exposed.api.replay, (key, row) => {}, {drain: "micro"})
+await feed.ready                                   // catch-up done: keyframe arrived expanded per key
+feed.store.state                                   // the mirror — direct reads / extra subscriptions
+feed()                                             // tears down the store sub AND the wire sub
+// reconnect later: syncStoreReplayEach(remote, cb, {since: feed.seq(), initial: feed.store.snapshot()})
+// offline persisted mirror — cached snapshot first, then replay catch-up over the same remote
+const offline = await Observe.createOfflineStore<Rows>({
+    key: "rows",
+    remote: exposed.api.replay,
+    initial: {},
+    storage: Observe.createMemoryOfflineStorage(), // use IndexedDB/SQLite adapter in an app
+    debounceMs: 250,
+})
+offline.each().on((key, row) => {})
+await offline.ready
+await offline.flush()
+offline.close()
+
+// configurable app-level resource plan
+const manager = Observe.createStoreManager({
+    market: Observe.managedStore.mirror({remote: api.market, initial: {data: {}, meta: {}}, mask: {data: {BTC: true}}, tags: ['bootstrap'], priority: 10}),
+    rows: Observe.managedStore.offline({remote: exposed.api.replay, initial: {}, storage: Observe.createMemoryOfflineStorage(), tags: ['grid']}),
+    video: Observe.managedStore.replay({remote: videoReplay, initial: {}, explicitOnly: true, large: true}),
+})
+await manager.startPlanned({tags: ['bootstrap']})
+manager.touch('rows', 3)               // usage can raise future plan score
+await manager.start('video', {explicit: true})
+```
+Runnable example: `npx tsx observe/store-mirror.example.ts`.
+Offline oracles: `npx tsx replay/offline-store.test.ts`; real Socket.IO/RPC wire: `npx tsx replay/offline-store-socket.test.ts`.
+
+## 🎞️ Fast ticks vs slow client — replay lines + server-owned lag gate (recipe)
+> The problem: the producer emits faster than a bad link drains. Naive streaming grows an unbounded
+> outgoing queue per slow client. The replay stack solves it with ONE mental model — the FRAME:
+> `frame(sinceSeq, hint?)` on the line returns envelopes bringing a consumer from `sinceSeq` to now,
+> as compact as the line allows (exact tail -> condensed mini-frame -> keyframe fallback). The same
+> method serves reconnect (`since`), client pull (own pace) and lag recovery. The transport sees only
+> `seq`; ALL event semantics live in two lambdas declared on the line: `current` (keyframe = pointer
+> to truth) and `frame` (condenser — may honor a client-supplied `hint`, see below).
+```ts
+import { Observe, Replay } from 'wenay-common2'
+
+// ---- producer: declare what the line HAS (its class follows — no mode flags) ----
+const [emitQuote, quotes] = Replay.replayListen<[string, number]>({
+    history: 4096,
+    frame: (tail, hint) => lastPerSymbol(tail, hint),  // mini-frame; hint = client's pick of the condensation rule
+})   // current+frame = condensable · current only = keyframe recovery · neither = sacred queue (never skipped, loud on eviction)
+// store lines: exposeStoreReplay already declares current + frame (last patch per path) — zero config
+const store = Observe.createStore<World>(initial, { drain: 'micro' })
+const exposed = Observe.exposeStoreReplay(store, { history: 1024 })
+
+// ---- per CONNECTION: the rpc server owns the gate; the facade does NOT change ----
+io.on('connection', socket => {
+    const [disconnect, disconnectListen] = listen<[]>()
+    socket.on('disconnect', () => disconnect())
+    createRpcServerAuto({
+        socket: { emit: (k, d) => socket.emit(k, d), on: (k, cb) => socket.on(k, cb) },
+        socketKey: 'world',
+        object: { ...exposed.api, quotes },       // replay lines auto-exposed: both surfaces, same key
+        disconnectListen,                          // gates close on disconnect automatically
+        replayOpts: { highWater: 64, lowWater: 8 },// arms frameLine; pending defaults to socket.io writeBuffer
+    })
+})
+
+// ---- client: picks its LAG POLICY per subscription; no conflation logic anywhere ----
+const sub = Replay.replaySubscribe(deep.quotes, cb, {since: saved, policy: 'frame'}) // server may skip; drain -> mini-frame
+const sub2 = Replay.replaySubscribe(deep.quotes, cb2, {since: saved})                // 'queue' (default): nothing ever skipped
+// own pace (e.g. 50ms skips + condensation): pull on YOUR timer — hint picks the rule, server condenses:
+//   every(50, async () => { for (const ev of await deep.quotes.frame(mySeq, hint)) apply(ev); })
+// store mirror: Observe.syncStoreReplay(mirror, deep.replay, {since: prev.seq()}) — same contract
+// delivery contract: FIRST delivery = snapshot/tail start (same event type), then strictly-newer,
+// seq-ascending, deduped; reconnect via {since} = mini-frame/tail, not a full snapshot
+```
+Rules that make it correct (violating any of these silently breaks convergence):
+- **The line declares its recovery sources.** `current` (keyframe: SAMPLED from truth, never computed
+  from deltas; `'last'` = last envelope for single-entity lines) and/or `frame` (condenser). A line
+  with neither is a sacred queue: full tails only, evicted journal -> `frame()` THROWS (loud) — a
+  lagging `'frame'`-policy subscriber gets a stream end, never silent loss.
+- **A `frame` result must be state-equivalent to the tail it replaces** (per the line's own semantics).
+  "Can't condense THIS tail" is legal and simple: return the tail as-is. Refuse-loudly is `throw`.
+  Multiple condensation standards live INSIDE the lambda, dispatched by the client-supplied `hint`
+  (opaque to the transport): `frame(tail, hint)`.
+- **Events must be ABSOLUTE per their entity** for last-per-entity condensing (store patches are).
+- Gate drops never hole the journal — it is written BEFORE any gate. Reconnect via `{since}` still
+  gets everything; only an evicted `history` window degrades to keyframe (visible as a seq jump).
+- `pending()` and the watermarks share units (bytes, packets, frames — anything, but the same).
+
+Manual path (pre-rev2, still works, `keyOf` @deprecated): build the gate yourself with
+`Replay.conflateReplay(exposed.replay, {pending, highWater, keyOf})` and spread `gated.api` into the
+facade — details in rare docs. New code should declare `frame` on the line instead.
+
+Wire-level proof/oracles: `npx ts-node replay/rpc-auto.test.ts` (real Socket.IO: auto-exposure, legacy
+parity, frame equivalence, gate lag sim), plus `replay/conflate-socket.test.ts`, `replay/conflate.test.ts`,
+`replay/coalesce.test.ts`. Full generic surface (history/time-travel, archive) → 🎞️ in rare docs.
+
+
+

package/package.json

@@ -1,12 +1,16 @@
 {
   "name": "wenay-common2",
-  "version": "1.0.63",
+  "version": "1.0.64",
   "description": "Common library",
   "strict": true,
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
   "files": [
     "lib/**/*",
+    "doc/**/*",
+    "CLAUDE.md",
+    "rpc.md",
+    "!doc/target/**/*",
     "!**/*.tsbuildinfo"
   ],
   "author": "wenay",
@@ -16,7 +20,7 @@
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/wenayr/wenay-common2.git"
+    "url": "git+https://github.com/wenayr/wenay-common2.git"
   },
   "optionalDependencies": {
     "utf-8-validate": "^6.0.6"

package/rpc.md

@@ -0,0 +1,293 @@
+
+Here is a comprehensive guide in a concise style. I've taken into account the architecture, backend, frontend (with the new `Hub` pattern), serialization nuances, limits, and hooks.
+
+# wenay-common2 RPC: Complete Guide
+
+Bidirectional, strongly-typed RPC protocol over sockets (Socket.IO or similar).
+**Essence:** Server exposes a nested JS object $\to$ Client receives a typed proxy.
+
+---
+
+## 1. Architecture and Limitations
+
+*   **Multiplexing:** A single physical socket hosts independent channels (`socketKey`), each with its own API object.
+*   **Data Types:** Works with JSON-compatible data plus `Date`, `Map`, `Set`, `RegExp`, and `BigInt`. Class instances are sent as plain enumerable object data; methods/prototypes are not preserved.
+*   **Security (RpcLimits):** Server is protected from DDoS attacks. Strict limits on: `maxDepth`, `maxKeys`, `maxArrayLen`, `maxStringLen`, `maxCallbacks`. Exceeding throws `PayloadLimitError`.
+
+---
+
+## 2. Server (Backend)
+
+### 2.1 Socket Connection
+```typescript
+import { createRpcServerAuto, listen } from "wenay-common2";
+
+io.sockets.on('connection', (socket) => {
+  // 1. Create unsubscribe trigger for memory cleanup
+  const [stop, listenStop] = listen<[]>();
+  socket.on('disconnect', stop);
+
+  // 2. Initialize RPC channel on this socket
+  createRpcServerAuto({
+    socket,
+    socketKey: "mainAPI",         // Channel identifier
+    object: buildFacade(client),  // Target API object
+    disconnectListen: listenStop, // Auto-unsubscribe from Listen on disconnect
+    debug: process.env.DEV,       // Packet logging
+  });
+});
+```
+
+### 2.2 Building API Object (Facade)
+The object is traversed by the server to build a "Schema" that is sent to the client.
+```typescript
+import { noStrict, listen } from "wenay-common2";
+
+// Create pub/sub event system
+const [sendEvent, listenEvent] = listen<[string]>();
+
+export function buildFacade(client) {
+  const role = (...roles) => hasRole(client, roles) ? true : null;
+
+  return {
+    // 1. Regular method
+    ping: () => "pong",
+
+    // 2. Nested namespaces + Role model
+    // If role() returns null, the method won't be sent to the client (returns null in schema)
+    admin: {
+      deleteUser: role("admin") && ((id) => db.delete(id)),
+    },
+
+    // 3. Dynamic objects (Proxy, ORM)
+    // Wrap in noStrict so the server doesn't try to read keys.
+    // Client will work with it in "blind" mode (without schema).
+    dbRef: noStrict(getProxyDb()),
+
+    // 4. Events
+    // Client will receive a Listen surface: .on(cb), .once(cb), .close()
+    events: { listenEvent },
+
+    // 5. Method with callback in arguments
+    // Callback lives ONLY while await is executing! After return, client deletes it.
+    stream: async (cb: (chunk: number) => void) => {
+      for(let i=0; i<10; i++) { cb(i); await sleep(50); }
+      return "done";
+    }
+  };
+}
+```
+
+### 2.3 Server Hooks (Interceptors)
+Use hooks to validate incoming packets.
+```typescript
+createRpcServerAuto({
+  /*...*/
+  hooks: {
+    onRequest: async ({ key, request, fnName, fn }) => {
+      // Return false to block the call
+      return true;
+    },
+    onInvalid: ({ reason, key, request }) => {
+      console.warn(`RPC Attack/Error [${reason}]:`, key);
+    }
+  }
+})
+```
+
+---
+
+## 3. Client (Frontend)
+
+**Hub Pattern:** The frontend library doesn't depend on `socket.io-client`. Developer injects the socket factory into `createRpcClientHub`.
+
+### 3.1 Hub Initialization
+```typescript
+import { io } from "socket.io-client";
+import { createRpcClientHub, rpc } from "wenay-common2";
+import type { MainFacade } from "../server/facade";
+
+export const Api = createRpcClientHub(
+  // 1. Socket factory (DI)
+  (token) => io("http://localhost:4021", {
+    transports: ["websocket"],
+    query: token ? { token } : {}
+  }),
+
+  // 2. Channel registration
+  // rpc() accepts Facade type. Property name ("mainAPI") becomes socketKey.
+  (rpc) => ({
+    mainAPI: rpc<MainFacade>(),
+  })
+);
+```
+
+### 3.2 Connection Lifecycle
+```typescript
+// Listen to statuses
+Api.onConnect((count) => console.log(`Socket connected (attempt ${count})`));
+
+// Initiate connect. Creates socket, all channels automatically start.
+await Api.connect("USER_SECRET_TOKEN");
+
+// Disconnect
+// await Api.connect(null);
+```
+
+### 3.3 Call Modes
+Access API channel: `Api.facade.mainAPI`. Hub initializes all channels, so schema loads automatically.
+
+```typescript
+const api = Api.facade.mainAPI;
+
+// Wait for schema (REQUIRED before UI render)
+await api.ready();
+
+// --- 1. STRICT (Recommended) ---
+// Safe call. Use `?.` since method may be `null` (closed by roles).
+// If method is closed, returns `undefined` without sending network request.
+const res = await api.strict.admin?.deleteUser?.(5);
+
+// **TIP:** You can save .strict reference to avoid repetitive code:
+// Works in ALL modes (strict, func, pipe, space, all)
+const orchestrator = Api.facade.orchestrator?.strict;
+await orchestrator?.repositories?.getAll?.();
+
+// **IMPORTANT: Optional chaining for methods**
+// - Use `?.` ONLY if method can be filtered by roles on backend
+// - If backend has NO role filtering, method is ALWAYS available - skip `?.`
+// Example: if backend has no roles, use .all mode instead:
+const orchestrator = Api.facade.orchestrator?.all;
+await orchestrator.repositories.getAll();  // No `?.` needed!
+await orchestrator.deployments.getAll();   // Cleaner code!
+
+// --- 2. FUNC (Standard) ---
+const res2 = await api.func.ping();
+
+// --- 3. PIPE (Pipeline) ---
+// Entire chain goes to server in ONE network packet.
+const data = await api.pipe.dbRef.users.find(1).getName();
+
+// --- 4. SPACE (Fire-and-Forget) ---
+// Doesn't wait for response, Promise resolves immediately.
+api.space.admin.logAction("clicked");
+```
+
+### 3.4 Client Subscriptions (Listen)
+`createRpcServerAuto` exposes server `listen` / `createListen` values as RPC Listen nodes. New code uses `on`/`once` and keeps the returned `off` handle. For TypeScript, project `client.func` to `DeepSocketListen<ServerFacade>`; this mirrors the runtime shape and keeps event argument types.
+```typescript
+import type { DeepSocketListen } from "wenay-common2";
+
+function webListen<T extends object>(client: { func: unknown }) {
+  return client.func as DeepSocketListen<T>;
+}
+
+const events = webListen<MainFacade>(api).events;
+
+// Subscribe
+const off = events.listenEvent.on((msg) => {
+  console.log("Push from server:", msg);
+});
+
+// Unsubscribe. The handle is callable and also thenable.
+off();
+// await off; // waits until the stream ends
+
+// One event, then automatic unsubscribe
+const done = events.listenEvent.once((msg) => {
+  console.log("First push:", msg);
+});
+await done;
+```
+
+Compatibility names `.callback(cb)`, `.removeCallback()`, and `.unsubscribe()` still exist for old clients, but they are not the recommended API.
+
+
+### 3.5 Request Management and Debug
+Each facade has a system object `api` for low-level control, as well as a couple of methods in the root:
+
+```typescript
+const { api, abortAll, schema } = Api.facade.mainAPI;
+
+// --- 1. Monitoring and Debug ---
+api.pending();          // Current number of pending responses (Promises)
+api.callbacks();        // Current number of live callback ids in memory
+api.log(true);          // Enable logging of all incoming/outgoing packets to console
+
+// --- 2. Targeted cleanup (inside .api) ---
+api.clearPromises(true); // Reject (cancel) all current requests
+api.clearCallbacks();    // Force clear all callbacks
+api.remove(myFunc);      // Force-release a specific callback id (alias: .end)
+
+// --- 3. Global facade methods ---
+abortAll("User logout"); // Hard reset: reject all promises with RPC_ABORT error + clear all callback ids
+const map = schema();    // Get raw schema tree (MAP) sent by server
+```
+
+
+---
+
+## 4. Advanced Features
+
+### 4.1 Listen Argument Interception Modes
+When using events, the client auto-handler (`mode: "smart"`) by default flexibly adapts arguments. If server sends one argument — it comes as a value, if multiple — as an array.
+If you create a client manually without Hub, you can set a strict mode:
+```typescript
+// "first" — listener always receives only the first argument
+// "all" — listener always receives all arguments
+// "smart" — (default) auto-detection
+const autoApi = createRpcClientAuto(api.func, { mode: "first" });
+```
+
+
+### 4.2 Manual Callback Termination from Server
+This is a low-level escape hatch for callbacks passed as ordinary function arguments. For Listen subscriptions prefer `off()`/`.once()`.
+```typescript
+import { endCallback } from "wenay-common2";
+
+async function myMethod(cb: (data: any) => void) {
+  cb("chunk 1");
+  endCallback(cb); // Alias: rpcEndCallback. Sends "___STOP" to client.
+  // Client callback id is deleted, subsequent cb() calls won't go anywhere.
+}
+```
+
+### 4.3 Call / Apply Support on Client
+The client proxy can transparently handle standard JS `call` and `apply` calls. Server correctly normalizes them ("collapses" the path):
+```typescript
+// Both variants correctly call `api.users.create("Ivan")` on server
+await api.func.users.create.call(null, "Ivan");
+await api.func.users.create.apply(null, ["Ivan"]);
+```
+
+
+### 4.4 Transparent PIPE Request Transit
+For microservice architecture. If your Node server itself is a client of another RPC node (via `pipe`), it can "pass through" the remainder of the pipe chain further using `__executeRemainingPipe`, without waiting for an intermediate response.
+This covers the important RPC mechanics (Listen `on/once/off`, `endCallback`, `call/apply`, `pipe-transit`) while maintaining readability.
+```typescript
+
+/**
+ * Extract orchestrator type from Api facade
+ */
+export type OrchestratorFacade = NonNullable<typeof Api.facade.orchestrator>['strict'];
+
+/**
+ * Hook for RPC initialization and facade access
+ */
+export function useOrchestrator() {
+    const [rpcInitialized, setRpcInitialized] = useState(false);
+
+    useEffect(() => {
+        Api.connect(null); // Connect without token
+        Api.facade.orchestrator?.ready().then(() => {
+            setRpcInitialized(true);
+        });
+    }, []);
+
+    // Use .all mode for simpler code without optional chaining when no role filtering
+    const orchestrator = Api.facade.orchestrator?.all;
+
+    return { orchestrator, rpcInitialized };
+}
+
+```