wenay-common2 1.0.69 → 1.0.73

package/oracle/realsocket/dedupe.spec.ts

@@ -0,0 +1,142 @@
+// REAL-SOCKET dedupe: subscription dedupe + refcount + server stats + cap. Port 4106.
+import {startRealServer, startRealClient, makeChecker, delay} from './_rs'
+import {listen as createListenPair} from '../../src/Common/events/Listen'
+
+const PORT = 4106
+
+// One stream node per facade; emit pushes a value to whoever subscribed.
+// `feed` is a server-side method the client can call to drive an emission.
+function makeObject() {
+    const [emitA, listenA] = createListenPair<number>()
+    const [emitB, listenB] = createListenPair<number>()
+    return {
+        // The Listen handle itself IS the node; resolveTransform turns it into
+        // {callback, removeCallback}, so the wire path is `streamA.callback`.
+        streamA: listenA,
+        streamB: listenB,
+        // server-side drivers: tell the server to fire an event into a stream.
+        feedA: async (v: number) => { emitA(v); return v },
+        feedB: async (v: number) => { emitB(v); return v },
+    }
+}
+
+async function main() {
+    const {check, done} = makeChecker('dedupe')
+    const watchdog = setTimeout(() => { console.error('WATCHDOG timeout'); process.exit(3) }, 40000)
+
+    // capture per-connection server api for subscription stats
+    let serverApi: any = null
+    const srv = await startRealServer({port: PORT, makeObject, onServer: (api) => { serverApi = api }})
+    const cli = await startRealClient<ReturnType<typeof makeObject>>({port: PORT})
+    const api = cli.api
+
+    await delay(50) // let handshake (MAP / declared listens) settle
+
+    // =====================================================================
+    // Part 1: two local consumers, SAME address → ONE wire subscription.
+    // =====================================================================
+    const gotC1: number[] = []
+    const gotC2: number[] = []
+    const off1 = api.streamA.callback((v: number) => gotC1.push(v))
+    const off2 = api.streamA.callback((v: number) => gotC2.push(v))
+    await delay(80) // subscription round-trip
+
+    // Client side: ONE wire sub, with TWO local consumers.
+    await check('client wireSubs count == 1 (deduped)',
+        () => cli.client.api.subscriptions().length, 1)
+    await check('client consumers == 2 (two local on same address)',
+        () => cli.client.api.subscriptions()[0].consumers, 2)
+
+    // Server side: ONE Listen node, ONE wire subscriber (dedupe collapsed the two).
+    await check('server subscriptions: 1 node',
+        () => serverApi.subscriptions().length, 1)
+    await check('server consumers == 1 (single shared wire sub)',
+        () => serverApi.subscriptions()[0].consumers, 1)
+
+    // Fan-out: one server emit reaches BOTH local consumers.
+    await api.feedA(7)
+    await delay(80)
+    await check('fan-out: consumer1 received [7]', () => gotC1, [7])
+    await check('fan-out: consumer2 received [7]', () => gotC2, [7])
+
+    // =====================================================================
+    // Part 2: refcount — wire stop only when the LAST consumer leaves.
+    // =====================================================================
+    off1() // first consumer leaves
+    await delay(80)
+    await check('after off1: still 1 wire sub (refcount > 0)',
+        () => cli.client.api.subscriptions().length, 1)
+    await check('after off1: consumers dropped to 1',
+        () => cli.client.api.subscriptions()[0]?.consumers, 1)
+    await check('after off1: server STILL has the node (wire alive)',
+        () => serverApi.subscriptions().length, 1)
+
+    // Surviving consumer still receives events.
+    await api.feedA(11)
+    await delay(80)
+    await check('after off1: consumer2 still gets events [7,11]', () => gotC2, [7, 11])
+    await check('after off1: consumer1 stopped getting events [7]', () => gotC1, [7])
+
+    off2() // LAST consumer leaves → wire stop fires
+    await delay(120) // removeCallback is fire-and-forget; give it round-trip time
+    await check('after last off: client wireSubs empty',
+        () => cli.client.api.subscriptions().length, 0)
+    await check('after last off: server node removed (wire stop fired)',
+        () => serverApi.subscriptions().length, 0)
+
+    // =====================================================================
+    // Part 3: maxPerListen cap — over-cap subscriptions silently ignored.
+    // Distinct addresses (different non-cb args) on the SAME Listen node each
+    // create a wire sub; the cap is per Listen node on the server.
+    // =====================================================================
+    cli.close()
+    await srv.close()
+    await delay(50)
+
+    const CAP = 2
+    let serverApi2: any = null
+    const srv2 = await startRealServer({
+        port: PORT, makeObject,
+        serverOpts: {maxPerListen: CAP},
+        onServer: (api) => { serverApi2 = api },
+    })
+    const cli2 = await startRealClient<ReturnType<typeof makeObject>>({port: PORT})
+    const api2 = cli2.api
+    await delay(50)
+
+    // Three DISTINCT-address subscriptions on streamA: the callback comes FIRST
+    // (so server-side listenSocket.callback(z) still gets the fn), a trailing tag
+    // arg makes each dedupe address unique → three independent wire subs. Cap is 2.
+    const recv: Record<string, number[]> = {s0: [], s1: [], s2: []}
+    api2.streamA.callback((v: number) => recv.s0.push(v), 0)
+    api2.streamA.callback((v: number) => recv.s1.push(v), 1)
+    api2.streamA.callback((v: number) => recv.s2.push(v), 2)
+    await delay(120)
+
+    // The client issues three distinct-address wire subs, but the over-cap one is
+    // silently resolved by the server (subscribe returns Promise.resolve()), which
+    // fires the client's .then(finish) and tears that wire entry down locally — so
+    // the client settles back to CAP live wire subs. (Server-side cap below is the
+    // load-bearing assertion; this documents the client-side consequence.)
+    await check('client settles to CAP live wire subs (over-cap torn down)',
+        () => cli2.client.api.subscriptions().length, CAP)
+
+    // Server accepted only CAP subscribers on the node; over-cap silently ignored.
+    await check('server node consumers capped at maxPerListen',
+        () => serverApi2.subscriptions()[0]?.consumers, CAP)
+
+    // Emit reaches exactly the accepted subscribers (first CAP), not the dropped one.
+    await api2.feedA(99)
+    await delay(100)
+    await check('capped: accepted sub s0 got [99]', () => recv.s0, [99])
+    await check('capped: accepted sub s1 got [99]', () => recv.s1, [99])
+    await check('capped: over-cap sub s2 got nothing []', () => recv.s2, [])
+
+    clearTimeout(watchdog)
+    cli2.close()
+    await srv2.close()
+
+    process.exit(done() === 0 ? 0 : 1)
+}
+
+main().catch(e => { console.error(e); process.exit(2) })

package/oracle/realsocket/errors.spec.ts

@@ -0,0 +1,121 @@
+// ============================================================
+//  oracle/realsocket/errors.spec.ts — DISPOSABLE real-socket oracle
+//  CATEGORY "errors": error propagation across a real WebSocket.
+//   - plain Error -> client rejects with the message
+//   - MyError with code+data -> code + data preserved over the wire
+//   - a rejected CALL does not kill the connection (next call still works)
+// ============================================================
+import {startRealServer, startRealClient, makeChecker, delay} from './_rs'
+import {MyError} from '../../src/toError/myThrow'
+
+const PORT = 4104
+
+function makeObject() {
+    return {
+        // happy path — used to prove the socket survives rejections
+        add: (a: number, b: number) => a + b,
+        ping: () => 'pong',
+
+        // ===== error-throwing handlers =====
+        throwPlain: () => { throw new Error('boom-plain') },
+        throwMyErr: () => { throw new MyError('payload-msg', 'E_TEST', {x: 1, tag: 'rich'}) },
+        // MyError carrying structured (wire-safe) data — verify nested data survives
+        throwNested: () => {
+            throw new MyError('nested-data', 'E_NESTED', {list: [1, 2, 3], meta: {ok: true, deep: {y: 9}}})
+        },
+        // async rejection
+        rejectAsync: async () => { await delay(5); throw new MyError('async-fail', 'E_ASYNC', {k: 'v'}) },
+        // MyError whose data carries a BigInt — probes errToObj pack behavior.
+        // FINDING: errToObj copies e.data RAW (no pack walk), so a BigInt here is
+        // handed to socket.io's JSON.stringify and throws server-side, killing
+        // the connection. Rich types round-trip in normal RESULTS but NOT in errors.
+        throwBigErr: () => { throw new MyError('big-fail', 'E_BIG', {n: 42n}) },
+    }
+}
+
+// The server runs in THIS same process. The BigInt-in-error-data probe makes the
+// server's socket emit throw synchronously OUTSIDE the rpc try/catch, which would
+// otherwise crash the whole process before ##RESULT## prints. Swallow it so the
+// finding is recorded as a FAIL by the client-side race below, not a hard crash.
+let sawSerializeCrash = false
+process.on('uncaughtException', (e: any) => {
+    if (String(e?.message ?? e).includes('BigInt')) { sawSerializeCrash = true; return }
+    console.error('UNEXPECTED uncaughtException', e); process.exit(2)
+})
+
+async function main() {
+    const {check, done} = makeChecker('errors')
+    const watchdog = setTimeout(() => { console.error('WATCHDOG timeout'); process.exit(3) }, 40000)
+
+    const srv = await startRealServer({port: PORT, makeObject})
+    const cli = await startRealClient({port: PORT})
+    const api = cli.api
+
+    await delay(20)
+
+    // sanity: happy call works before we start throwing
+    await check('sanity: add(2,3)=5', () => api.add(2, 3), 5)
+
+    // plain Error -> client rejects with the same message
+    await check('plain Error -> message',
+        () => api.throwPlain().then(() => '__no_throw__', (e: any) => e?.message), 'boom-plain')
+
+    // connection survives a rejected call: a subsequent call still works
+    await check('socket alive after plain reject', () => api.ping(), 'pong')
+
+    // MyError -> revived as a real Error instance on the client
+    await check('MyError -> instanceof Error',
+        () => api.throwMyErr().then(() => false, (e: any) => e instanceof Error), true)
+
+    // MyError -> name preserved
+    await check('MyError -> name',
+        () => api.throwMyErr().then(() => '', (e: any) => e?.name), 'MyError')
+
+    // MyError -> message preserved
+    await check('MyError -> message',
+        () => api.throwMyErr().then(() => '', (e: any) => e?.message), 'payload-msg')
+
+    // MyError -> machine code preserved across the wire
+    await check('MyError -> code',
+        () => api.throwMyErr().then(() => '', (e: any) => e?.code), 'E_TEST')
+
+    // MyError -> arbitrary data payload preserved across the wire
+    await check('MyError -> data',
+        () => api.throwMyErr().then(() => null, (e: any) => e?.data), {x: 1, tag: 'rich'})
+
+    // socket still alive after the MyError reject
+    await check('socket alive after MyError reject', () => api.add(10, 20), 30)
+
+    // nested/structured (wire-safe) data inside MyError.data survives intact
+    await check('MyError -> nested data',
+        () => api.throwNested().then(() => null, (e: any) => e?.data),
+        {list: [1, 2, 3], meta: {ok: true, deep: {y: 9}}})
+
+    // async rejection: code + data preserved
+    await check('async MyError -> [code, data]',
+        () => api.rejectAsync().then(() => null, (e: any) => [e?.code, e?.data]),
+        ['E_ASYNC', {k: 'v'}])
+
+    // final liveness BEFORE probing the BigInt-in-error crash
+    await check('socket alive before big-err probe', () => api.ping(), 'pong')
+
+    // FINDING probe: BigInt inside MyError.data. errToObj copies data raw, so the
+    // server's socket emit throws "Do not know how to serialize a BigInt" and the
+    // connection dies. We RACE the call against a short timeout so a server-side
+    // crash surfaces here as a recorded FAIL instead of taking down the process
+    // before ##RESULT## prints. Expected (correct) behavior would be a clean
+    // rejection with code E_BIG; anything else is the bug.
+    await check('MyError BigInt data -> clean reject (FINDING)',
+        () => Promise.race([
+            api.throwBigErr().then(() => 'resolved', (e: any) => 'rejected:' + e?.code),
+            delay(800).then(() => 'no-response(connection-killed)'),
+        ]),
+        'rejected:E_BIG')
+
+    clearTimeout(watchdog)
+    cli.close()
+    await srv.close()
+    process.exit(done() === 0 ? 0 : 1)
+}
+
+main().catch(e => { console.error(e); process.exit(2) })

package/oracle/realsocket/lifecycle.spec.ts

@@ -0,0 +1,128 @@
+// REAL-SOCKET lifecycle: disconnect teardown drains live subscriptions, fires
+// onDisconnect (client + hub), and hard setToken rotation tears down old subs then
+// reconnects (connectCount++). Default = teardown, NO auto-resubscribe. Port 4108.
+import {startRealServer, startRealClient, makeChecker, delay} from './_rs'
+import {listen as createListenPair} from '../../src/Common/events/Listen'
+
+const PORT = 4108
+
+// ===== facade: a method + two listen stream nodes =====
+// The server fabricates a fresh facade per connection (see _rs.startRealServer),
+// so each connection gets its own emit handle. We stash the latest emit on a
+// module-level ref so the test body can push ticks into the live stream.
+let emitTicks: ((n: number) => void) | null = null
+let emitClock: ((s: string) => void) | null = null
+
+function makeObject() {
+    const [tick, tickListen] = createListenPair<number>()
+    const [clock, clockListen] = createListenPair<string>()
+    emitTicks = tick
+    emitClock = clock
+    return {
+        ping: async () => 'pong',
+        // Listen nodes: client subscribes via api.<node>.callback(fn)
+        ticks: tickListen,
+        clock: clockListen,
+    }
+}
+
+async function main() {
+    const {check, done} = makeChecker('lifecycle')
+    const watchdog = setTimeout(() => { console.error('WATCHDOG timeout'); process.exit(3) }, 40000)
+
+    const srv = await startRealServer({port: PORT, makeObject})
+
+    // ============================================================
+    // PART 1 — client.dispose() drains a live subscription
+    // ============================================================
+    const cli = await startRealClient({port: PORT})
+    const api = cli.api
+
+    // sanity: a plain call round-trips over the real socket
+    await check('CALL ping', () => api.ping(), 'pong')
+
+    // subscribe to the `ticks` stream; collect ticks; the off-handle is a
+    // callable thenable that RESOLVES when the stream ends (teardown/drain).
+    const got1: number[] = []
+    let drained1 = false
+    const off1 = api.ticks.callback((n: number) => got1.push(n))
+    off1.then(() => { drained1 = true }) // settle on stream end
+
+    await delay(60) // let the subscription round-trip to the server
+    emitTicks?.(1)
+    emitTicks?.(2)
+    await delay(60) // ticks travel back over the wire
+
+    await check('subscription receives live ticks', () => got1.slice(), [1, 2])
+    await check('1 live wire subscription before dispose', () => cli.client.api.subscriptions().length, 1)
+
+    // dispose drains: the consumer promise settles, NO auto-resubscribe
+    let cliDisconnectReason: string | null = null
+    cli.client.onDisconnect((r: string) => { cliDisconnectReason = r })
+    cli.client.dispose('test dispose')
+
+    await delay(60)
+    await check('client.onDisconnect fires with reason', () => cliDisconnectReason, 'test dispose')
+    await check('dispose drained the consumer promise (resolved)', () => drained1, true)
+    await check('no live subscriptions after dispose', () => cli.client.api.subscriptions().length, 0)
+
+    // post-dispose ticks must NOT reach the (drained) consumer — honest teardown
+    emitTicks?.(99)
+    await delay(40)
+    await check('no auto-resubscribe: stale ticks ignored after dispose', () => got1.slice(), [1, 2])
+
+    cli.close()
+
+    // ============================================================
+    // PART 2 — hub.setToken hard rotation: teardown old subs, then reconnect
+    // ============================================================
+    const cli2 = await startRealClient({port: PORT})
+
+    let hubDisconnectReason: string | null = null
+    let connectFiredCount = 0
+    cli2.hub.onDisconnect((r: string) => { hubDisconnectReason = r })
+    cli2.hub.onConnect((count: number) => { connectFiredCount = count })
+
+    await check('connectCount after initial connect', () => cli2.hub.connectCount(), 1)
+
+    // subscribe on the clock stream of the FIRST connection
+    const got2: string[] = []
+    let drained2 = false
+    const off2 = cli2.api.clock.callback((s: string) => got2.push(s))
+    off2.then(() => { drained2 = true })
+
+    await delay(60)
+    emitClock?.('a')
+    await delay(60)
+    await check('rotation: sub receives tick on old connection', () => got2.slice(), ['a'])
+    await check('1 live subscription before rotation', () => cli2.client.api.subscriptions().length, 1)
+
+    // capture the OLD per-connection client surface (the facade swaps on rotation)
+    const oldClient = cli2.client
+
+    // HARD rotation: setToken tears down old subs (socketAlive:false), fires hub
+    // onDisconnect, opens a fresh socket and fires onConnect again (connectCount++).
+    await cli2.hub.setToken('rotated-token')
+    await delay(120) // let the fresh socket connect + reconnect handshake
+
+    await check('hub.onDisconnect fired on rotation', () => hubDisconnectReason, 'token rotated')
+    await check('old subscription drained on rotation (no auto-resubscribe)', () => drained2, true)
+    await check('old client has 0 live subscriptions after rotation', () => oldClient.api.subscriptions().length, 0)
+    await check('connectCount incremented to 2 on rotation', () => cli2.hub.connectCount(), 2)
+    await check('hub.onConnect fired again with fresh count', () => connectFiredCount, 2)
+
+    // the NEW connection has NO carried-over subscription (default = teardown)
+    await check('fresh connection starts with 0 subscriptions', () => {
+        // facade[key] is the new per-connection client after rotation
+        const fresh = (cli2.hub.facade as any).api
+        return cli2.hub.connectCount() == 2 && fresh.api.subscriptions().length == 0
+    }, true)
+
+    cli2.close()
+
+    clearTimeout(watchdog)
+    await srv.close()
+    process.exit(done() === 0 ? 0 : 1)
+}
+
+main().catch(e => { console.error(e); process.exit(2) })

package/oracle/realsocket/limits.spec.ts

@@ -0,0 +1,98 @@
+// ============================================================
+//  oracle/realsocket/limits.spec.ts — DISPOSABLE real-socket oracle
+//  CATEGORY: limits — server-side incoming payload caps (serverOpts.limits).
+//
+//  The server resolves limits via resolveLimits(serverOpts.limits) and runs
+//  every incoming CALL's args through unpack(..., lim). A violation throws a
+//  PayloadLimitError (rpc-limits.ts), which the CALL try/catch sends back as a
+//  Pkt.RESP error → the client promise rejects with an Error whose name is
+//  "PayloadLimitError" and message "Payload limit exceeded: <reason>".
+//  Under-limit calls of the same method round-trip normally.
+//
+//  Direction note: the configurable cap on a real socket goes through
+//  serverOpts.limits → INCOMING (client→server) only. The client-side response
+//  cap (unpackResult lim) is opt-in via the client `limits` option, which the
+//  shared substrate (startRealClient) does not expose — so we exercise the
+//  incoming direction, covering several distinct limit dimensions.
+// ============================================================
+import {startRealServer, startRealClient, makeChecker, delay} from './_rs'
+
+const PORT = 4109
+
+// echo bounces its single arg straight back; sink takes many args and reports count.
+function makeObject() {
+    return {
+        echo: (x: any) => x,
+        sink: (...xs: any[]) => xs.length,
+    }
+}
+
+// classify a call as 'ok'(+value) / 'limit'(PayloadLimitError) / 'other'(unexpected reject)
+async function verdict(p: Promise<any>) {
+    try {
+        const v = await p
+        return {tag: 'ok', value: v}
+    } catch (e: any) {
+        const name = e?.name
+        const msg = String(e?.message ?? e)
+        if (name == 'PayloadLimitError' || /Payload limit exceeded/.test(msg)) return {tag: 'limit'}
+        return {tag: 'other', error: msg}
+    }
+}
+
+async function main() {
+    const {check, done} = makeChecker('limits')
+    const watchdog = setTimeout(() => { console.error('WATCHDOG timeout'); process.exit(3) }, 40000)
+
+    // Tight incoming caps. Defaults (rpc-limits.ts) are huge; we shrink several
+    // dimensions so each is easy to cross with a deliberately oversized payload.
+    const limits = {
+        maxArgs: 3,
+        maxStringLen: 10,
+        maxDepth: 4,
+        maxKeys: 5,
+        maxArrayLen: 4,
+    }
+
+    const srv = await startRealServer({port: PORT, makeObject, serverOpts: {limits}})
+    const cli = await startRealClient({port: PORT})
+    const api = cli.api
+    await delay(30) // let the strict handshake settle over the real socket
+
+    // ---- sanity: a plainly under-limit call works end-to-end ----
+    await check('under-limit echo round-trips', () => api.echo('short'), 'short')
+
+    // ===== maxArgs (incoming) =====
+    await check('maxArgs: 3 args ok (count)', () => api.sink(1, 2, 3), 3)
+    await check('maxArgs: 4 args -> limit', async () => (await verdict(api.sink(1, 2, 3, 4))).tag, 'limit')
+
+    // ===== maxStringLen (incoming) =====
+    await check('maxStringLen: 10-char ok', () => api.echo('0123456789'), '0123456789')
+    await check('maxStringLen: 11-char -> limit', async () => (await verdict(api.echo('0123456789X'))).tag, 'limit')
+
+    // ===== maxDepth (incoming) =====
+    // depth counted by walk(): each nested object level is +1. {a:{b:{c:{d:1}}}} = depth 4 → ok; +1 level → limit.
+    await check('maxDepth: depth 4 ok', () => api.echo({a: {b: {c: {d: 1}}}}), {a: {b: {c: {d: 1}}}})
+    await check('maxDepth: depth 6 -> limit', async () =>
+        (await verdict(api.echo({a: {b: {c: {d: {e: {f: 1}}}}}}))).tag, 'limit')
+
+    // ===== maxKeys (incoming) =====
+    await check('maxKeys: 5 keys ok', () => api.echo({a: 1, b: 2, c: 3, d: 4, e: 5}), {a: 1, b: 2, c: 3, d: 4, e: 5})
+    await check('maxKeys: 6 keys -> limit', async () =>
+        (await verdict(api.echo({a: 1, b: 2, c: 3, d: 4, e: 5, f: 6}))).tag, 'limit')
+
+    // ===== maxArrayLen (incoming) =====
+    await check('maxArrayLen: len 4 ok', () => api.echo([1, 2, 3, 4]), [1, 2, 3, 4])
+    await check('maxArrayLen: len 5 -> limit', async () => (await verdict(api.echo([1, 2, 3, 4, 5]))).tag, 'limit')
+
+    // ===== rejection carries the typed error shape (name + message) =====
+    await check('over-limit rejects, under-limit still works after', async () => {
+        const over = await verdict(api.echo('this-is-way-too-long'))
+        const under = await api.echo('ok')
+        return [over.tag, under]
+    }, ['limit', 'ok'])
+
+    clearTimeout(watchdog); cli.close(); await srv.close(); process.exit(done() === 0 ? 0 : 1)
+}
+
+main().catch(e => { console.error(e); process.exit(2) })

package/oracle/realsocket/pipe.spec.ts

@@ -0,0 +1,101 @@
+// ============================================================
+//  oracle/realsocket/pipe.spec.ts — DISPOSABLE real-socket oracle for PIPE chains
+//
+//  Category "pipe": a method returning a transformation chain that the server
+//  walks step-by-step (get/call) over a real WebSocket. Covers:
+//    • single-stage chain (.value)
+//    • multi-stage chain (>1 call stage: .add().mul().value)
+//    • rich-type values flowing THROUGH the pipe (Date/Map/BigInt as call args
+//      and as final result)
+//    • transparent relay (a pipe method returning another pipe handle —
+//      server detects IS_RPC_PIPE and __executeRemainingPipe-continues)
+// ============================================================
+import {startRealServer, startRealClient, makeChecker, delay} from './_rs'
+
+const PORT = 4103
+
+// ===== facade with pipe-able chain methods =====
+function makeObject() {
+    // makeBox returns a fresh chainable box; every transform returns a new box,
+    // so the server walks `.add(..).mul(..).value` as a real pipe.
+    function makeBox(n: number): any {
+        return {
+            value: n,
+            add: (m: number) => makeBox(n + m),
+            mul: (m: number) => makeBox(n * m),
+        }
+    }
+    return {
+        makeBox,
+        // rich-type pipe: takes a Date arg, returns a chainable carrying rich data
+        makeWhen(d: Date): any {
+            return {
+                date: d,
+                // shift the date forward by ms (rich arg flows through a pipe call stage)
+                shift: (ms: number) => makeWhenInner(new Date(d.valueOf() + ms)),
+                tags: new Map<string, number>([['a', 1], ['b', 2]]),
+                big: 9007199254740993n,
+            }
+        },
+    }
+
+    function makeWhenInner(d: Date): any {
+        return {
+            date: d,
+            shift: (ms: number) => makeWhenInner(new Date(d.valueOf() + ms)),
+            tags: new Map<string, number>([['a', 1], ['b', 2]]),
+            big: 9007199254740993n,
+        }
+    }
+}
+
+async function main() {
+    const {check, done} = makeChecker('pipe')
+    const watchdog = setTimeout(() => { console.error('WATCHDOG timeout'); process.exit(3) }, 40000)
+
+    const srv = await startRealServer({port: PORT, makeObject})
+    const cli = await startRealClient({port: PORT})
+    const P = cli.client.pipe as any // pipe proxy: supports chaining .a().b().value
+
+    await delay(20)
+
+    // --- single-stage chain: method result -> property get ---
+    await check('makeBox(10).value', () => P.makeBox(10).value, 10)
+
+    // --- two-stage chain: one call stage then value ---
+    await check('makeBox(10).add(5).value', () => P.makeBox(10).add(5).value, 15)
+
+    // --- multi-stage chain (>2 call stages): transparent relay across boxes ---
+    await check('makeBox(2).add(3).mul(4).value', () => P.makeBox(2).add(3).mul(4).value, 20)
+
+    // --- order matters: mul before add ---
+    await check('makeBox(2).mul(4).add(3).value', () => P.makeBox(2).mul(4).add(3).value, 11)
+
+    // --- awaiting the chain object itself (no trailing .value): rich object out ---
+    await check('makeBox(7).add(1) -> {value:8}', async () => {
+        const box = await P.makeBox(7).add(1)
+        return box.value
+    }, 8)
+
+    // --- rich type as a Date arg flowing INTO a pipe + Date out ---
+    const base = new Date(1700000000000)
+    await check('makeWhen(date).date round-trips Date', () => P.makeWhen(base).date, base)
+
+    // --- rich Date arg + call-stage transform: shift forward by 1000ms ---
+    await check('makeWhen(date).shift(1000).date', () => P.makeWhen(base).shift(1000).date, new Date(1700000001000))
+
+    // --- chained shifts: two call stages over a Date ---
+    await check('makeWhen(date).shift(1000).shift(500).date',
+        () => P.makeWhen(base).shift(1000).shift(500).date,
+        new Date(1700000001500))
+
+    // --- Map flowing out through a pipe get ---
+    await check('makeWhen(date).tags is Map', () => P.makeWhen(base).tags, new Map([['a', 1], ['b', 2]]))
+
+    // --- BigInt flowing out through a pipe (after a transform stage) ---
+    await check('makeWhen(date).shift(1).big is BigInt', () => P.makeWhen(base).shift(1).big, 9007199254740993n)
+
+    clearTimeout(watchdog); cli.close(); await srv.close(); process.exit(done() === 0 ? 0 : 1)
+}
+
+main().catch(e => { console.error(e); process.exit(2) })