wenay-common2 1.0.69 → 1.0.70

package/oracle/fixes-primitives.spec.ts

@@ -0,0 +1,90 @@
+// DISPOSABLE ORACLE — verifies the primitive bug-fixes found while reviewing:
+//   #1 promiseProgress  — .all()/.allSettled() must actually RUN factory tasks (not leave thunks)
+//   #2 joinListens.destroy — present + actually unsubscribes (type fix; runtime sanity here)
+//   #3 joinListens         — no empty-bucket leak in `pending` after a group fires
+//   #5 createIterableObject — delete on a read-only proxy must NOT throw (consistent with set())
+// Run: node node_modules/ts-node/dist/bin.js --transpile-only oracle/fixes-primitives.spec.ts
+import {promiseProgress} from '../src/Common/async/promiseProgress'
+import {joinListens} from '../src/Common/events/joinListens'
+import {listen as createListenPair} from '../src/Common/events/Listen'
+import {createIterableObject} from '../src/Common/async/createIterableObject'
+import {StructMap} from '../src/Common/core/common'
+
+let fails = 0
+function assert(cond: any, msg: string) {
+    if (cond) console.log('  ok  :', msg)
+    else { fails++; console.log('  FAIL:', msg) }
+}
+
+async function main() {
+    // ===== #1 — factories must actually run via .all() =====
+    {
+        let ran = 0
+        const okSeen: number[] = []
+        const p = promiseProgress<number>([
+            () => { ran++; return 10 },          // sync factory
+            async () => { ran++; return 20 },    // async factory
+            Promise.resolve(30),                 // already-a-promise
+        ])
+        p.onOk((data) => okSeen.push(data))
+        const res = await p.all()
+        assert(ran === 2, '#1 both factories were invoked by .all() (ran=' + ran + ')')
+        assert(p.stats().ok === 3, '#1 status.ok counts all 3 tasks (ok=' + p.stats().ok + ')')
+        assert(okSeen.length === 3, '#1 listenOk fired for all 3 (got ' + okSeen.length + ')')
+        assert(res.every(v => typeof v !== 'function'), '#1 .all() resolves values, not un-run thunks')
+    }
+
+    // ===== #1b — factory runs once across .all()+.allSettled() (memoized, no double-run) =====
+    {
+        let ran = 0
+        const p = promiseProgress<number>([() => { ran++; return 1 }])
+        await p.all()
+        await p.allSettled()
+        assert(ran === 1, '#1b factory runs once across .all()+.allSettled() (ran=' + ran + ')')
+    }
+
+    // ===== #3 — pending must not retain an empty bucket after a group fires =====
+    {
+        const [emitA, listenA] = createListenPair<[string]>()
+        const [emitB, listenB] = createListenPair<[string]>()
+        const joined = joinListens([listenA, listenB], (d: any) => d)   // key = the value itself
+        emitA('x'); emitB('x')                  // completes group "x" → fires
+        assert(!joined.pending.has('x'), '#3 pending has no leftover empty bucket for fired tid')
+        assert(joined.pending.size === 0, '#3 pending empty after the only group fired (size=' + joined.pending.size + ')')
+    }
+
+    // ===== #2 — destroy() present + actually unsubscribes (runtime sanity; type checked by tsc) =====
+    {
+        const [, listenA] = createListenPair<[string]>()
+        const joined = joinListens([listenA])
+        assert(typeof joined.destroy === 'function', '#2 destroy() is present on the result')
+        assert(listenA.count() === 1, '#2 join subscribed to the source')
+        joined.destroy()
+        assert(listenA.count() === 0, '#2 destroy() unsubscribed from the source')
+    }
+
+    // ===== #5 — delete on a read-only proxy must not throw =====
+    {
+        const store = new Map<string, number>([['a', 1]])
+        const ro = createIterableObject<number>({ resolve: () => store })
+        let threw = false
+        try { delete (ro as any)['a'] } catch { threw = true }
+        assert(!threw, '#5 delete on read-only proxy does not throw')
+        assert(store.has('a'), '#5 read-only delete is a no-op (key still present)')
+    }
+
+    // ===== #6 — StructMap.has prefix miss against primitive leaf returns false =====
+    {
+        const m = new StructMap<readonly number[], number>()
+        m.set([1], 42)
+        let threw = false
+        let has = true
+        try { has = m.has([1, 2]) } catch { threw = true }
+        assert(!threw, '#6 StructMap.has([1, 2]) does not throw when [1] stores a primitive')
+        assert(has === false, '#6 StructMap.has([1, 2]) returns false for a missing composite key')
+    }
+
+    console.log(`\n${fails === 0 ? 'ALL GREEN' : fails + ' FAILURE(S)'}`)
+    process.exit(fails === 0 ? 0 : 1)
+}
+main()

package/oracle/realsocket/_rs.ts

@@ -0,0 +1,106 @@
+// ============================================================
+//  oracle/realsocket/_rs.ts — DISPOSABLE shared harness for REAL-SOCKET mass tests
+//
+//  Boots a genuine socket.io server (express + http) on a TCP port and a real
+//  socket.io-client hub — the SAME transport pattern as src/Common/rcp/test.ts.
+//  Not the in-memory loopback: messages cross a real WebSocket. Each spec uses
+//  its OWN port so specs run concurrently without clashing.
+//
+//  Disposable oracle (project rule: no standing test suite; real harness is the
+//  one in src/Common/rcp/rpc.harness.spec.ts). Delete this dir after the pass.
+// ============================================================
+import express from 'express'
+import {createServer} from 'http'
+import {Server as SocketIOServer} from 'socket.io'
+import {io} from 'socket.io-client'
+import {createRpcServerAuto} from '../../src/Common/rcp/rpc-server-auto'
+import {createRpcClientHub} from '../../src/Common/rcp/rpc-clientHub'
+import {listen as createListenPair} from '../../src/Common/events/Listen'
+
+export const delay = (ms: number) => new Promise(r => setTimeout(r, ms))
+
+// ===== real socket.io server =====
+type ServerOpts = {
+    port: number
+    // фабрика объекта-фасада на КАЖДОЕ подключение (как в реальном сервере)
+    makeObject: () => any
+    // прокидывается в createRpcServerAuto (auth / limits / maxPerListen / throttle / debug)
+    serverOpts?: Record<string, any>
+    socketKey?: string
+    // доступ к per-connection серверным api (subscriptions stats и т.п.)
+    onServer?: (api: any, socket: any) => void
+}
+
+export async function startRealServer(opts: ServerOpts) {
+    const {port, makeObject, serverOpts = {}, socketKey = 'rpc', onServer} = opts
+    const app = express()
+    const httpServer = createServer(app)
+    const ioServer = new SocketIOServer(httpServer, {maxHttpBufferSize: 1e8})
+
+    ioServer.on('connection', socket => {
+        const [disconnect, disconnectListen] = createListenPair()
+        socket.on('disconnect', () => disconnect())
+        const adapter = {
+            emit: (key: string, data: any) => socket.emit(key, data),
+            on: (key: string, cb: any) => socket.on(key, cb),
+        }
+        const server = createRpcServerAuto({socket: adapter, socketKey, object: makeObject(), disconnectListen, ...serverOpts})
+        onServer?.(server.api, socket)
+    })
+
+    await new Promise<void>(resolve => httpServer.listen(port, resolve))
+    return {
+        httpServer, ioServer,
+        close: () => new Promise<void>(resolve => { ioServer.close(); httpServer.close(() => resolve()) }),
+    }
+}
+
+// ===== real socket.io client (via hub) =====
+type ClientOpts = {port: number, token?: string | null, socketKey?: string, opt?: {compact?: boolean}}
+
+export async function startRealClient<T extends object = any>(opts: ClientOpts) {
+    const {port, token = null, socketKey = 'rpc', opt} = opts
+    const hub = createRpcClientHub(
+        () => io(`http://localhost:${port}`, {transports: ['websocket'], forceNew: true}),
+        (r) => ({api: r<T>(socketKey)}) as const,
+        { opt },
+    )
+    const clients = await hub.setToken(token)
+    await clients.api.readyStrict()
+    return {
+        hub,
+        client: clients.api,                 // createRpcClient surface (auth/reauth/dispose/onDisconnect/subscriptions/schema)
+        api: clients.api.func as any,         // transparent proxy — call site
+        close: () => hub.socket?.disconnect?.(),
+    }
+}
+
+// ===== assertions =====
+export type Failure = {name: string, got?: any, expected?: any, error?: string}
+
+function eq(a: any, b: any) {
+    // нормализуем Date → ISO для сравнения round-trip rich-типов
+    const norm = (v: any) => JSON.stringify(v, (_k, val) => val instanceof Date ? ['__date', val.toISOString()]
+        : val instanceof Map ? ['__map', [...val]] : val instanceof Set ? ['__set', [...val]]
+        : typeof val === 'bigint' ? ['__big', val.toString()] : val)
+    return norm(a) === norm(b)
+}
+
+export function makeChecker(label: string) {
+    let pass = 0, fail = 0
+    const failures: Failure[] = []
+    async function check(name: string, fn: () => any, expected: any) {
+        try {
+            const got = await fn()
+            if (eq(got, expected)) { pass++; console.log(`PASS  [${label}] ${name}`) }
+            else { fail++; failures.push({name, got, expected}); console.log(`FAIL  [${label}] ${name}  got=${JSON.stringify(got)}  exp=${JSON.stringify(expected)}`) }
+        } catch (e: any) {
+            fail++; failures.push({name, error: String(e?.stack ?? e)}); console.log(`FAIL  [${label}] ${name}  ERROR=${String(e?.message ?? e)}`)
+        }
+    }
+    return {
+        check,
+        summary: () => ({label, total: pass + fail, passed: pass, failed: fail, failures}),
+        done: () => { console.log(`\n##RESULT## ${JSON.stringify({label, total: pass + fail, passed: pass, failed: fail, failures})}`); return fail },
+    }
+}

package/oracle/realsocket/auth.spec.ts

@@ -0,0 +1,91 @@
+// ============================================================
+//  oracle/realsocket/auth.spec.ts — DISPOSABLE real-socket test
+//  Category "auth": in-band auth over a genuine WebSocket.
+//    (1) valid token  → auth() ok, principal methods callable
+//    (2) bad / gated   → calls rejected with E_UNAUTHORIZED
+//    (3) soft reauth on the LIVE socket → principal swaps (user→admin)
+//        WITHOUT dropping a live subscription.
+// ============================================================
+import {startRealServer, startRealClient, makeChecker, delay} from './_rs'
+import {listen as createListenPair} from '../../src/Common/events/Listen'
+
+const PORT = 4105
+
+// One stream node, shared by BOTH principals → the subscription survives a principal
+// swap (same socket, same Listen handle). Distinct principals: user (read-only) vs
+// admin (read + write) so the swap is observable in method visibility.
+const [emit, listen] = createListenPair<number>()
+const facades: Record<string, any> = {
+    'tok-user': {
+        stream: listen,
+        whoami: () => 'user',
+        read: () => 'public-data',
+        pulse: (n: number) => { emit(n); return n },   // drive the stream over the wire
+    },
+    'tok-admin': {
+        stream: listen,
+        whoami: () => 'admin',
+        read: () => 'public-data',
+        write: (x: number) => x * 10,                   // admin-only method
+        pulse: (n: number) => { emit(n); return n },
+    },
+}
+function resolveAuth(token: any) {
+    const object = facades[token]
+    if (!object) throw new Error('bad token')
+    return {object, ack: {ok: true, who: object.whoami()}}
+}
+
+async function main() {
+    const {check, done} = makeChecker('auth')
+    const watchdog = setTimeout(() => { console.error('WATCHDOG timeout'); process.exit(3) }, 40000)
+
+    // gate=true: the EMPTY initial object is protected; the real principal surface only
+    // appears after a successful HELLO (resolveAuth → principal facade).
+    const srv = await startRealServer({
+        port: PORT,
+        makeObject: () => ({}),                          // empty until HELLO
+        serverOpts: {auth: {resolveAuth, gate: true}},
+    })
+
+    // ---- (1) valid token: auth resolves ok, principal methods callable ----
+    const cliUser = await startRealClient({port: PORT, token: 'tok-user'})
+    const userApi = cliUser.api
+
+    await check('valid token: authAck ok', async () => (await cliUser.client.auth())?.ok, true)
+    await check('valid token: authAck who=user', async () => (await cliUser.client.auth())?.who, 'user')
+    await check('user principal: read() callable', () => userApi.read(), 'public-data')
+    await check('user principal: whoami=user', () => userApi.whoami(), 'user')
+    // user facade has NO write → must reject (method absent in principal routeMap)
+    await check('user principal: write() rejected (not in facade)',
+        () => userApi.write(5).then(() => 'ok', () => 'rejected'), 'rejected')
+
+    // ---- (2) bad token / gated: calls rejected with E_UNAUTHORIZED ----
+    const cliBad = await startRealClient({port: PORT, token: 'tok-nope'})
+    await check('bad token: authAck ok=false', async () => (await cliBad.client.auth())?.ok, false)
+    await check('gated: call rejected code E_UNAUTHORIZED',
+        () => (cliBad.api.read() as Promise<any>).catch((e: any) => e?.code), 'E_UNAUTHORIZED')
+
+    // ---- (3) soft reauth on the LIVE socket: user → admin, subscription survives ----
+    const got: number[] = []
+    const off = cliUser.api.stream.callback((v: number) => got.push(v))
+    await delay(50)                                      // let the subscription round-trip
+    await userApi.pulse(1)                               // emit BEFORE reauth (as user)
+    await delay(50)
+    await check('pre-reauth: stream tick received', async () => got.slice(), [1])
+
+    // swap principal on the SAME live socket (no disconnect) via hub.reauth
+    const acks = await cliUser.hub.reauth('tok-admin')
+    await check('reauth: hub.reauth resolved ok', async () => acks?.[0]?.ok, true)
+    await check('reauth: principal swapped who=admin', async () => (await cliUser.client.auth())?.who, 'admin')
+    await check('reauth: admin sees write() now', () => cliUser.api.write(4), 40)
+    await check('reauth: whoami flipped to admin', () => cliUser.api.whoami(), 'admin')
+
+    await userApi.pulse(2)                               // emit AFTER reauth — same subscription
+    await delay(50)
+    await check('reauth: subscription survived (live tick after swap)', async () => got.slice(), [1, 2])
+
+    off()
+    clearTimeout(watchdog); cliUser.close(); cliBad.close(); await srv.close(); process.exit(done() === 0 ? 0 : 1)
+}
+main().catch(e => { console.error(e); process.exit(2) })

package/oracle/realsocket/callbacks.spec.ts

@@ -0,0 +1,122 @@
+// ============================================================
+//  oracle/realsocket/callbacks.spec.ts — DISPOSABLE real-socket oracle
+//  CATEGORY "callbacks": callbacks-as-args (Pkt.CB) + listen streaming
+//  subscriptions over a genuine WebSocket. Port 4102 (own port, no clash).
+// ============================================================
+import {startRealServer, startRealClient, makeChecker, delay} from './_rs'
+import {listen as createListenPair} from '../../src/Common/events/Listen'
+
+const PORT = 4102
+
+// Stream nodes live in module scope so the facade factory closes over the SAME
+// listen handles every connection — we drive them from the test below.
+const [tick, tickListen] = createListenPair<[{n: number; at: Date; tags: Set<string>}]>()
+const [multiTick, multiListen] = createListenPair<[number, string]>()
+
+function makeObject() {
+    return {
+        // ── callback-as-arg (Pkt.CB): server invokes the passed callback N times ──
+        counter: {
+            run: async (a: {n: number; callback: (i: number, when: Date) => void}) => {
+                // emit `n` ticks in order, each with a rich Date arg; resolve when done
+                for (let i = 0; i < a.n; i++) {
+                    a.callback(i, new Date(Date.UTC(2026, 0, 1) + i * 1000))
+                    await delay(5)
+                }
+                return a.n
+            },
+        },
+        // ── listen stream node: client subscribes via api.stream.callback(fn) ──
+        stream: tickListen,        // single rich object arg
+        multi: multiListen,        // two args (number, string)
+        // ── control surface to end the single-arg stream (→ CB_END / await off) ──
+        endStream: async () => { tickListen.close(); return true },
+    }
+}
+
+async function main() {
+    const {check, done} = makeChecker('callbacks')
+    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
+
+    // ===== 1. Callback-as-arg (Pkt.CB): all ticks arrive in order, rich Date =====
+    {
+        const got: Array<{i: number; when: Date}> = []
+        const ret = await api.counter.run({n: 4, callback: (i: number, when: Date) => { got.push({i, when}) }})
+        await delay(30) // let any trailing CB packets land after RESP
+        await check('cb-arg: return value = n', () => ret, 4)
+        await check('cb-arg: tick count', () => got.length, 4)
+        await check('cb-arg: indices in order', () => got.map(g => g.i), [0, 1, 2, 3])
+        await check('cb-arg: rich Date round-trips',
+            () => got.map(g => g.when),
+            [0, 1, 2, 3].map(i => new Date(Date.UTC(2026, 0, 1) + i * 1000)))
+    }
+
+    // ===== 2. listen stream: ticks arrive with rich values =====
+    {
+        const a: Array<{n: number; at: Date; tags: Set<string>}> = []
+        const off = (api as any).stream.callback((v: any) => a.push(v))
+        await delay(40) // subscription round-trips over the real socket
+        tick({n: 1, at: new Date('2026-03-03T00:00:00.000Z'), tags: new Set(['x', 'y'])})
+        tick({n: 2, at: new Date('2026-03-04T00:00:00.000Z'), tags: new Set(['z'])})
+        await delay(40)
+        await check('stream: tick count', () => a.length, 2)
+        await check('stream: rich values (Date+Set) round-trip',
+            () => a,
+            [
+                {n: 1, at: new Date('2026-03-03T00:00:00.000Z'), tags: new Set(['x', 'y'])},
+                {n: 2, at: new Date('2026-03-04T00:00:00.000Z'), tags: new Set(['z'])},
+            ])
+        // off() stops further ticks
+        off()
+        await delay(20)
+        tick({n: 3, at: new Date('2026-03-05T00:00:00.000Z'), tags: new Set()})
+        await delay(40)
+        await check('stream: off() stops further ticks', () => a.length, 2)
+    }
+
+    // ===== 3. MULTIPLE independent subscribers each get every tick =====
+    {
+        const b: number[] = [], c: number[] = []
+        const offB = (api as any).multi.callback((n: number, _s: string) => b.push(n))
+        await delay(20)
+        const offC = (api as any).multi.callback((n: number, _s: string) => c.push(n))
+        await delay(40)
+        multiTick(10, 'a')
+        multiTick(20, 'b')
+        await delay(40)
+        await check('multi-sub: first subscriber got every tick', () => b, [10, 20])
+        await check('multi-sub: second subscriber got every tick', () => c, [10, 20])
+        // drop one; the other keeps receiving
+        offB()
+        await delay(20)
+        multiTick(30, 'c')
+        await delay(40)
+        await check('multi-sub: dropped subscriber stops', () => b, [10, 20])
+        await check('multi-sub: surviving subscriber continues', () => c, [10, 20, 30])
+        offC()
+        await delay(20)
+    }
+
+    // ===== 4. CB_END / stream end resolves the off-handle (await off) =====
+    {
+        let resolved = false
+        const off = (api as any).stream.callback(() => {})
+        await delay(40)
+        const awaited = (async () => { await off; resolved = true })()
+        // close the server stream → CB_END → off-handle promise resolves
+        await api.endStream()
+        await Promise.race([awaited, delay(500)])
+        await check('stream-end: await off resolved on CB_END', () => resolved, true)
+    }
+
+    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/caps.spec.ts

@@ -0,0 +1,124 @@
+// ============================================================
+//  oracle/realsocket/caps.spec.ts — DISPOSABLE real-socket oracle
+//  CATEGORY "caps": capability NEGOTIATION over a REAL WebSocket.
+//
+//  Verifies the handshake-negotiated optimization switch (opt.compact):
+//    1) default (both new)        → COMPACT negotiated → server uses Pkt.CBV (CBV>0).
+//    2) client opt:{compact:false}→ client advertises NO COMPACT (silent) → server stays
+//                                   on plain Pkt.CB (CBV==0, CB>0). Ticks still intact.
+//    3) server opt:{compact:false}→ server advertises caps without COMPACT → no compaction
+//                                   even though the client supports it (CBV==0, CB>0).
+//  In all cases data round-trips byte-correct (incl. Date), proving the optimization is
+//  purely a wire choice negotiated at handshake — outcome-equivalent either way.
+// ============================================================
+import {startRealServer, startRealClient, makeChecker, delay} from './_rs'
+import {listen as createListenPair} from '../../src/Common/events/Listen'
+
+const PORT = 4120
+
+// one scenario: boot a server (opt = serverOpt) + connect a client (opt = clientOpt),
+// fire N monomorphic ticks, count CBV(9)/CB(2) packets on the real server socket.
+async function scenario(port: number, serverOpt?: {compact?: boolean}, clientOpt?: {compact?: boolean}) {
+    let emit: ((v: any) => void) | null = null
+    function makeObject() {
+        const [e, listen] = createListenPair<any>()
+        emit = e
+        return {stream: listen}
+    }
+    let cbv = 0, cb = 0
+    const srv = await startRealServer({
+        port, makeObject,
+        serverOpts: serverOpt ? {opt: serverOpt} : {},
+        onServer: (_api, socket) => {
+            const orig = socket.emit.bind(socket)
+            socket.emit = (key: string, d: any) => {
+                if (Array.isArray(d)) { if (d[0] === 9) cbv++; else if (d[0] === 2) cb++ }
+                return orig(key, d)
+            }
+        },
+    })
+    const cli = await startRealClient({port, opt: clientOpt})
+    const got: any[] = []
+    const off = cli.api.stream.callback((v: any) => got.push(v))
+    await delay(60) // subscription round-trip + CAPS handshake over the real socket
+    const N = 10
+    for (let i = 0; i < N; i++) { emit!({a: i, when: new Date(i * 1000), tag: 'x'}); await delay(8) }
+    await delay(120)
+    off()
+    await delay(20)
+    cli.close()
+    await srv.close()
+    return {got, cbv, cb, N}
+}
+
+async function main() {
+    const {check, done} = makeChecker('caps')
+    const watchdog = setTimeout(() => { console.error('WATCHDOG timeout'); process.exit(3) }, 60000)
+
+    // ---- 1) default: COMPACT negotiated (both peers new) ----
+    {
+        const r = await scenario(PORT)
+        await check('default: all ticks intact', () => r.got.length, r.N)
+        await check('default: last tick exact (Date)', () => [r.got[r.N - 1].a, r.got[r.N - 1].tag, r.got[r.N - 1].when], [r.N - 1, 'x', new Date((r.N - 1) * 1000)])
+        await check('default: compaction engaged (CBV>0)', () => r.cbv > 0, true)
+    }
+
+    // ---- 2) client opt:{compact:false}: client does NOT advertise → server plain CB ----
+    {
+        const r = await scenario(PORT + 1, undefined, {compact: false})
+        await check('client-off: all ticks intact', () => r.got.length, r.N)
+        await check('client-off: last tick exact (Date)', () => [r.got[r.N - 1].a, r.got[r.N - 1].when], [r.N - 1, new Date((r.N - 1) * 1000)])
+        await check('client-off: NO compaction (CBV==0)', () => r.cbv, 0)
+        await check('client-off: server sent plain CB (CB>0)', () => r.cb > 0, true)
+    }
+
+    // ---- 3) server opt:{compact:false}: server advertises no COMPACT → no compaction ----
+    {
+        const r = await scenario(PORT + 2, {compact: false})
+        await check('server-off: all ticks intact', () => r.got.length, r.N)
+        await check('server-off: last tick exact (Date)', () => [r.got[r.N - 1].a, r.got[r.N - 1].when], [r.N - 1, new Date((r.N - 1) * 1000)])
+        await check('server-off: NO compaction (CBV==0)', () => r.cbv, 0)
+        await check('server-off: server sent plain CB (CB>0)', () => r.cb > 0, true)
+    }
+
+    // ---- 4) subscribe via .on(cb) over the REAL web (idiomatic alias of .callback) ----
+    {
+        let emit: ((v: any) => void) | null = null
+        const srv = await startRealServer({port: PORT + 3, makeObject: () => { const [e, l] = createListenPair<any>(); emit = e; return {stream: l} }})
+        const cli = await startRealClient({port: PORT + 3})
+        const got: any[] = []
+        const off = (cli.api.stream as any).on((v: any) => got.push(v))   // .on вместо .callback — «факт установки колбэка»
+        await delay(60)
+        for (let i = 0; i < 5; i++) { emit!({n: i}); await delay(8) }
+        await delay(100)
+        await check('on-web: .on(cb) subscribed + streamed', () => got.map((v: any) => v.n), [0, 1, 2, 3, 4])
+        if (typeof off === 'function') off()
+        await delay(20)
+        cli.close()
+        await srv.close()
+    }
+
+    // ---- 5) bare-on exposure ({ stream: listen.on }) + once over the REAL web ----
+    {
+        let emit: ((v: any) => void) | null = null
+        const srv = await startRealServer({port: PORT + 4, makeObject: () => { const [e, l] = createListenPair<any>(); emit = e; return {stream: (l as any).on} }})
+        const cli = await startRealClient({port: PORT + 4})
+        const got: any[] = []
+        ;(cli.api.stream as any).on((v: any) => got.push(v))   // exposed ТОЛЬКО listen.on → клиент получил подписку
+        await delay(60)
+        for (let i = 0; i < 4; i++) { emit!({n: i}); await delay(8) }
+        await delay(100)
+        await check('bare-on: { stream: listen.on } streams over real web', () => got.map((v: any) => v.n), [0, 1, 2, 3])
+        const one: any[] = []
+        ;(cli.api.stream as any).once((v: any) => one.push(v))
+        await delay(40); emit!({n: 99}); await delay(8); emit!({n: 100}); await delay(50)
+        await check('once: exactly one event over real web', () => one.map((v: any) => v.n), [99])
+        cli.close()
+        await srv.close()
+    }
+
+    clearTimeout(watchdog)
+    process.exit(done() === 0 ? 0 : 1)
+}
+
+main().catch(e => { console.error(e); process.exit(2) })

package/oracle/realsocket/core.spec.ts

@@ -0,0 +1,49 @@
+// REAL-SOCKET core: CALL + rich-type round-trip both ways. Port 4101.
+import {startRealServer, startRealClient, makeChecker, delay} from './_rs'
+
+const PORT = 4101
+
+function makeObject() {
+    return {
+        math: {
+            add: async (a: number, b: number) => a + b,
+            mul: async (a: number, b: number) => a * b,
+        },
+        echo: async (v: any) => v,
+        rich: async () => ({
+            when: new Date(123456),
+            map: new Map<string, number>([['a', 1], ['b', 2]]),
+            set: new Set([1, 2, 3]),
+            big: 9007199254740993n,
+        }),
+        roundtrip: async (d: Date, m: Map<string, number>) => ({d, m, n: (m.get('x') ?? 0) + 1}),
+    }
+}
+
+async function main() {
+    const {check, done} = makeChecker('core')
+    const srv = await startRealServer({port: PORT, makeObject})
+    const cli = await startRealClient<ReturnType<typeof makeObject>>({port: PORT})
+    const api = cli.api
+
+    await check('CALL math.add', () => api.math.add(5, 7), 12)
+    await check('CALL math.mul', () => api.math.mul(3, 4), 12)
+    await check('CALL echo primitive', () => api.echo('hello'), 'hello')
+    await check('CALL echo nested obj', () => api.echo({a: [1, 2], b: {c: true}}), {a: [1, 2], b: {c: true}})
+
+    await check('rich: Date round-trips', async () => (await api.rich()).when, new Date(123456))
+    await check('rich: Map round-trips', async () => [...(await api.rich()).map], [['a', 1], ['b', 2]])
+    await check('rich: Set round-trips', async () => [...(await api.rich()).set], [1, 2, 3])
+    await check('rich: BigInt round-trips', async () => (await api.rich()).big === 9007199254740993n, true)
+
+    await check('arg→server: Date+Map sent up', async () => {
+        const r = await api.roundtrip(new Date(999), new Map([['x', 41]]))
+        return [r.d, [...r.m], r.n]
+    }, [new Date(999), [['x', 41]], 42])
+
+    cli.close()
+    await srv.close()
+    process.exit(done() === 0 ? 0 : 1)
+}
+
+main().catch(e => { console.error(e); process.exit(2) })