wenay-common2 1.0.70 → 1.0.73

package/lib/Common/peer/peer-relay.js

@@ -16,37 +16,51 @@ function condensePatchTail(tail) {
     return Array.from(held.values());
 }
 function createPatchRelayJournal(opts = {}) {
-    const { history = 1024 } = opts;
+    const { history = 1024, gap = 'resume' } = opts;
+    const folding = gap != 'sacred';
     const [emitLine, line] = (0, Listen_1.listen)();
-    const fold = (0, store_1.createStore)({}, { drain: 'micro' });
+    const fold = folding ? (0, store_1.createStore)({}, { drain: 'micro' }) : null;
     let ring = [];
     let last = -1;
     let lastTs = 0;
     let hasState = false;
-    function push(env) {
-        if (env == null || typeof env.seq != 'number')
-            return false;
-        const patch = env.event?.[0];
-        if (patch == null || !Array.isArray(patch.path))
-            return false;
-        const isRoot = patch.path.length == 0;
-        if (env.seq <= last) {
-            if (!isRoot || env.seq == last)
-                return false;
+    function accept(env, reset) {
+        if (reset)
             ring = [];
-        }
         last = env.seq;
         lastTs = env.ts ?? lastTs;
         hasState = true;
-        (0, store_1.applyStorePatch)(fold, patch);
+        if (fold)
+            (0, store_1.applyStorePatch)(fold, env.event[0]);
         ring.push(env);
         if (ring.length > history)
             ring.splice(0, ring.length - history);
         emitLine(env);
         return true;
     }
+    function push(env) {
+        if (env == null || typeof env.seq != 'number')
+            return false;
+        const patch = env.event?.[0];
+        if (patch == null || !Array.isArray(patch.path))
+            return false;
+        const isRoot = patch.path.length == 0;
+        if (env.seq <= last) {
+            if (folding && isRoot && env.seq < last)
+                return accept(env, true);
+            return true;
+        }
+        if (hasState && env.seq > last + 1) {
+            if (folding && isRoot)
+                return accept(env, true);
+            return { seq: last };
+        }
+        if (folding && !hasState && !isRoot)
+            return { seq: -1 };
+        return accept(env, false);
+    }
     function keyframe() {
-        if (!hasState)
+        if (!fold || !hasState)
             return null;
         return { seq: last, ts: lastTs, event: [{ path: [], exists: true, value: fold.snapshot() }] };
     }
@@ -64,14 +78,22 @@ function createPatchRelayJournal(opts = {}) {
         if (tail)
             return condensePatchTail(tail);
         const kf = keyframe();
-        return kf ? [kf] : null;
+        if (kf)
+            return [kf];
+        if (!folding && hasState)
+            throw new Error('sacred relay journal: tail evicted, no keyframe to invent');
+        return null;
     }
-    const remote = { line, since, keyframe, frame };
+    const remote = {
+        line, since, keyframe, frame,
+        seq: () => last,
+    };
     return {
         push,
         remote,
+        gap,
         seq: () => last,
-        snapshot: () => fold.snapshot(),
+        snapshot: () => fold?.snapshot(),
         close: () => { line.close(); },
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wenay-common2",
-  "version": "1.0.70",
+  "version": "1.0.73",
   "description": "Common library",
   "strict": true,
   "main": "lib/index.js",

package/replay/media-view.test.ts

@@ -0,0 +1,164 @@
+// ============================================================
+//  replay/media-view.test.ts
+//
+//  Media viewer helpers oracle (Node, no browser):
+//  - attachAudioPlayer: PCM decode, sequential playhead, live
+//    backlog drop, enable/disable, non-audio frames ignored
+//  - attachVideoCanvas: injected bitmap decoder, sizing follows
+//    frames, busy-skip keeps latest, stats
+//  - pipeMediaPublish: sentAt stamp, onError on rejection
+// ============================================================
+
+import {listen} from '../src/Common/events/Listen'
+import {
+    attachAudioPlayer,
+    attachVideoCanvas,
+    encodeMediaFrame,
+    pipeMediaPublish,
+} from '../src/Common/media/media-index'
+
+let fails = 0
+const ok = (condition: any, message: string) => {
+    if (!condition) { fails++; console.log('  FAIL', message) }
+    else console.log('  OK  ', message)
+}
+const delay = (ms: number) => new Promise<void>(r => setTimeout(r, ms))
+
+function pcmFrame(seq: number, nSamples = 480, sampleRate = 48000) {
+    const pcm = new Int16Array(nSamples)
+    for (let i = 0; i < nSamples; i++) pcm[i] = (i % 2 ? 1 : -1) * 1000
+    return encodeMediaFrame({kind: 'audio-pcm', codec: 'pcm16', seq, tMono: seq, sampleRate, channels: 1, nSamples}, new Uint8Array(pcm.buffer))
+}
+
+function videoFrame(seq: number, width: number, height: number) {
+    return encodeMediaFrame({kind: 'video-frame', codec: 'jpeg', seq, tMono: seq, width, height}, new Uint8Array([1, 2, 3]))
+}
+
+function createFakeAudioContext() {
+    const scheduled: {at: number, frames: number}[] = []
+    const ctx = {
+        currentTime: 0,
+        destination: {},
+        resumed: 0,
+        closed: 0,
+        resume() { ctx.resumed++ },
+        close() { ctx.closed++ },
+        createBuffer: (_ch: number, frames: number, _rate: number) => ({
+            frames,
+            getChannelData: () => new Float32Array(frames),
+        }),
+        createBufferSource: () => {
+            const node: any = {connect: () => {}, start: (at: number) => scheduled.push({at, frames: node.buffer.frames})}
+            return node
+        },
+        scheduled,
+    }
+    return ctx
+}
+
+async function main() {
+    console.log('\n[media-view] audio player: sequential playhead + live backlog drop')
+    {
+        const [emit, line] = listen<[Uint8Array, number]>()
+        const ctx = createFakeAudioContext()
+        const player = attachAudioPlayer(line as any, {audioContext: () => ctx as any})
+
+        emit(pcmFrame(1), Date.now())
+        ok(player.stats().frames == 1 && player.stats().played == 0, 'disabled player counts frames but schedules nothing')
+
+        player.enable()
+        ok(player.enabled && ctx.resumed == 1, 'enable() builds the injected context and resumes it')
+
+        emit(pcmFrame(2), Date.now() - 40)
+        ok(player.stats().played == 1 && ctx.scheduled.length == 1, 'enabled player schedules a decoded pcm16 buffer')
+        ok(ctx.scheduled[0].frames == 480, 'sample count survives decode (480 frames)')
+        ok(player.stats().ageMs >= 40, 'sentAt stamp turns into a real age measurement')
+
+        const before = ctx.scheduled.length
+        emit(videoFrame(3, 320, 240), Date.now())
+        ok(ctx.scheduled.length == before && player.stats().frames == 3, 'video frames on an audio player are counted, not scheduled')
+
+        // 40 x 10ms chunks pushed instantly = 0.4s of queued audio while currentTime stays 0
+        for (let i = 0; i < 40; i++) emit(pcmFrame(10 + i), Date.now())
+        ok(player.stats().dropped > 0, 'backlog past maxBacklogSec is dropped (live policy), not queued forever')
+        const last = ctx.scheduled[ctx.scheduled.length - 1]
+        ok(last.at <= 0.45, `playhead rebased near "now" after the drop (last at=${last.at.toFixed(2)}s)`)
+
+        player.disable()
+        ok(!player.enabled && ctx.closed == 1, 'disable() closes the context')
+        player.off()
+    }
+
+    console.log('\n[media-view] video canvas: sizing follows frames, busy-skip keeps latest')
+    {
+        const [emit, line] = listen<[Uint8Array, number]>()
+        const drawnImages: any[] = []
+        const canvas: any = {
+            width: 0,
+            height: 0,
+            getContext: () => ({drawImage: (img: any) => drawnImages.push(img)}),
+        }
+        let decodeDelay = 0
+        const view = attachVideoCanvas(line as any, canvas, {
+            createBitmap: async blob => {
+                if (decodeDelay) await delay(decodeDelay)
+                return {size: blob.size, close: () => {}}
+            },
+        })
+
+        emit(videoFrame(1, 640, 480), Date.now() - 25)
+        await delay(10)
+        ok(view.stats().drawn == 1 && drawnImages.length == 1, 'video frame decoded via injected bitmap factory and drawn')
+        ok(canvas.width == 640 && canvas.height == 480, 'canvas takes the frame size')
+        ok(view.stats().width == 640 && view.stats().ageMs >= 25, 'stats expose frame size and age')
+
+        emit(pcmFrame(2), Date.now())
+        await delay(10)
+        ok(view.stats().drawn == 1 && view.stats().frames == 2, 'audio frame on a video canvas is counted, not drawn')
+
+        decodeDelay = 30
+        emit(videoFrame(3, 1280, 720), Date.now())
+        emit(videoFrame(4, 1280, 720), Date.now())   // arrives while frame 3 decodes -> skipped
+        await delay(60)
+        ok(view.stats().frames == 4 && view.stats().drawn == 2, 'busy-skip: overlapping frame dropped, not queued')
+        ok(canvas.width == 1280 && canvas.height == 720, 'canvas resized to the new resolution')
+
+        view.off()
+        emit(videoFrame(5, 320, 240), Date.now())
+        await delay(10)
+        ok(view.stats().frames == 4, 'off() unsubscribes the line')
+    }
+
+    console.log('\n[media-view] publish pipe: stamp + onError')
+    {
+        const [emit, line] = listen<[Uint8Array]>()
+        const sent: {frame: Uint8Array, sentAt?: number}[] = []
+        const errors: unknown[] = []
+        const off = pipeMediaPublish(line as any, (frame, sentAt) => {
+            sent.push({frame, sentAt})
+            return frame.byteLength == 0 ? Promise.reject(new Error('boom')) : Promise.resolve(true)
+        }, {onError: e => errors.push(e)})
+
+        emit(pcmFrame(1))
+        ok(sent.length == 1 && typeof sent[0].sentAt == 'number', 'frames are published with a wall-clock stamp by default')
+
+        emit(new Uint8Array(0))
+        await delay(10)
+        ok(errors.length == 1, 'publish rejection lands in onError, capture loop survives')
+
+        off()
+        emit(pcmFrame(2))
+        ok(sent.length == 2, 'off() stops publishing')
+
+        const noStamp: (number | undefined)[] = []
+        const [emit2, line2] = listen<[Uint8Array]>()
+        pipeMediaPublish(line2 as any, (_f, sentAt) => { noStamp.push(sentAt) }, {stamp: false})
+        emit2(pcmFrame(3))
+        ok(noStamp.length == 1 && noStamp[0] == undefined, 'stamp:false publishes without a timestamp')
+    }
+
+    console.log(fails ? `\n${fails} FAILED` : '\nall passed')
+    if (fails) process.exit(1)
+}
+
+main().catch(e => { console.error(e); process.exit(1) })

package/replay/peer-repair.test.ts

@@ -0,0 +1,184 @@
+// Publish-path reconnect correctness (peer SDK): the relay journal never lies
+// after a publisher gap. Gap matrix on createPatchRelayJournal + rejection-driven
+// repair in createPeerClient ('tail' | 'keyframe'), sacred eviction, resync().
+import {flushReactive} from '../src/Common/Observe/reactive'
+import {applyStorePatch, createStore, StorePatch} from '../src/Common/Observe/store'
+import {syncStoreReplay} from '../src/Common/Observe/store-replay'
+import {createPatchRelayJournal, createPeerClient, PatchEnvelope, PeerRemote} from '../src/Common/peer/peer-index'
+
+let fails = 0
+const ok = (condition: any, message: string) => {
+    if (!condition) { fails++; console.log('  FAIL', message) }
+    else console.log('  OK  ', message)
+}
+const delay = (ms: number) => new Promise<void>(r => setTimeout(r, ms))
+const json = (v: any) => JSON.stringify(v)
+
+async function waitFor(label: string, cond: () => boolean) {
+    for (let i = 0; i < 100; i++) {
+        if (cond()) return
+        await delay(10)
+    }
+    throw new Error(`timeout: ${label}`)
+}
+
+const env = (seq: number, path: PropertyKey[], value: any): PatchEnvelope =>
+    ({seq, ts: seq, event: [{path, value, exists: value !== undefined}]})
+const root = (seq: number, value: any) => env(seq, [], value)
+
+type World = {n: number, tag?: string}
+
+// lossy transport wrapper: drops pushes while `offline` is true — the client's
+// next successful delivery gets the {seq} verdict and repairs the gap
+function makeLossyRemote(journal: ReturnType<typeof createPatchRelayJournal>, account: string) {
+    const state = {offline: false, dropped: 0}
+    const remote: PeerRemote = {
+        signal: {send: async () => false, signals: {on: () => () => {}}},
+        publish: (e: PatchEnvelope) => {
+            if (state.offline) { state.dropped++; return true }
+            return journal.push(e)
+        },
+        peers: {[account]: journal.remote as any},
+    }
+    return {remote, state}
+}
+
+async function main() {
+    console.log('\n[peer-repair] gap matrix on the relay journal')
+    {
+        const j = createPatchRelayJournal({history: 16})
+        ok(j.push(env(0, ['n'], 1)) != true && json(j.push(env(0, ['n'], 1))) == json({seq: -1}),
+            'folding journal refuses a non-root FIRST envelope (partial-state lie) with repair coord -1')
+        ok(j.push(root(0, {n: 1})) == true, 'root first envelope accepted')
+        ok(j.push(env(1, ['n'], 2)) == true && j.push(env(2, ['n'], 3)) == true, 'contiguous envelopes accepted')
+        ok(j.push(env(2, ['n'], 99)) == true && j.seq() == 2 && j.snapshot().n == 3,
+            'duplicate is an idempotent no-op (reconnect overlap)')
+        ok(json(j.push(env(5, ['n'], 6))) == json({seq: 2}), 'non-root gap rejected WITH the repair coordinate')
+        ok(j.seq() == 2 && j.snapshot().n == 3, 'rejected gap does not corrupt the fold')
+        ok(j.push(root(7, {n: 7})) == true && j.seq() == 7 && j.snapshot().n == 7,
+            'root patch with a gap = legitimate reset point (keyframe repair / owner restart)')
+        ok(j.push(root(3, {n: 3})) == true && j.seq() == 3,
+            'root patch with a LOWER seq = owner restart reset')
+        ok(json(j.remote.keyframe()?.event[0].value) == json({n: 3}), 'folded keyframe stays truthful throughout')
+    }
+
+    console.log('\n[peer-repair] sacred journal: never invents, strict contiguity')
+    {
+        const j = createPatchRelayJournal({history: 2, gap: 'sacred'})
+        ok(j.push(root(0, {n: 0})) == true && j.push(env(1, ['n'], 1)) == true, 'sacred accepts a contiguous line')
+        ok(json(j.push(root(5, {n: 5}))) == json({seq: 1}), 'sacred rejects even a ROOT patch with a gap (no reset semantics)')
+        ok(j.remote.keyframe() == null, 'sacred never folds a keyframe')
+        j.push(env(2, ['n'], 2)); j.push(env(3, ['n'], 3)) // history 2 -> seq 0,1 evicted
+        let threw = false
+        try { j.remote.frame!(0) } catch { threw = true }
+        ok(threw, 'sacred frame() on an evicted tail THROWS (loud, never a silent seq jump)')
+        ok(json(j.remote.since(1)?.map(e => e.seq)) == json([2, 3]), 'covered tail is still served exactly')
+    }
+
+    console.log('\n[peer-repair] tail repair: lossless catch-up after an offline window')
+    {
+        const j = createPatchRelayJournal({history: 64})
+        const net = makeLossyRemote(j, 'a')
+        const errors: unknown[] = []
+        const a = createPeerClient<World>({
+            remote: net.remote, account: 'a', initial: {n: 0},
+            repair: 'tail', drain: 'micro', onPublishError: e => errors.push(e),
+        })
+        await waitFor('warmup', () => j.seq() >= 0)
+
+        a.store.state.n = 1
+        await flushReactive(a.store.state)
+        await waitFor('live publish', () => j.snapshot().n == 1)
+
+        net.state.offline = true
+        a.store.state.n = 2
+        a.store.state.tag = 'missed'
+        await flushReactive(a.store.state)
+        a.store.state.n = 3
+        await flushReactive(a.store.state)
+        await delay(20)
+        net.state.offline = false
+        ok(net.state.dropped >= 2 && j.snapshot().n == 1, 'offline window: relay is behind, fold untouched')
+
+        a.store.state.n = 4
+        await flushReactive(a.store.state)
+        await waitFor('tail repair', () => j.snapshot().n == 4)
+        ok(j.snapshot().tag == 'missed', 'tail repair delivered the MISSED envelopes verbatim (lossless)')
+        ok(json(j.snapshot()) == json(a.store.snapshot()), 'relay converged with the owner')
+        // ring integrity: a late joiner can fold the line from any covered coordinate
+        const late = createStore<World>({n: -1}, {drain: 'micro'})
+        const sub = syncStoreReplay(late, j.remote)
+        await sub.ready
+        ok(json(late.state) == json(a.store.snapshot()), 'late joiner folds a truthful state after repair')
+        ok(errors.length == 0, 'no publish errors on the happy repair path')
+        sub(); a.close()
+    }
+
+    console.log('\n[peer-repair] keyframe repair: cheap reset for ephemeral state')
+    {
+        const j = createPatchRelayJournal({history: 64})
+        const net = makeLossyRemote(j, 'a')
+        const a = createPeerClient<World>({
+            remote: net.remote, account: 'a', initial: {n: 0},
+            repair: 'keyframe', drain: 'micro',
+        })
+        await waitFor('warmup', () => j.seq() >= 0)
+        net.state.offline = true
+        a.store.state.n = 100
+        await flushReactive(a.store.state)
+        await delay(20)
+        net.state.offline = false
+        a.store.state.n = 101
+        await flushReactive(a.store.state)
+        await waitFor('keyframe repair', () => j.snapshot().n == 101)
+        ok(json(j.snapshot()) == json(a.store.snapshot()), 'keyframe repair resets the relay to current state')
+        a.close()
+    }
+
+    console.log('\n[peer-repair] sacred + local eviction: loud publisher fault, journal stays truthful')
+    {
+        const j = createPatchRelayJournal({history: 64, gap: 'sacred'})
+        const net = makeLossyRemote(j, 'a')
+        const errors: unknown[] = []
+        const a = createPeerClient<World, 'sacred'>({
+            remote: net.remote, account: 'a', initial: {n: 0},
+            journal: 'sacred', repair: 'tail', history: 2, // tiny local journal -> eviction
+            drain: 'micro', onPublishError: e => errors.push(e),
+        })
+        await waitFor('warmup', () => j.seq() >= 0)
+        const seqBefore = j.seq()
+        net.state.offline = true
+        for (let i = 1; i <= 6; i++) { a.store.state.n = i; await flushReactive(a.store.state) }
+        net.state.offline = false
+        a.store.state.n = 7
+        await flushReactive(a.store.state)
+        await waitFor('sacred repair failure surfaces', () => errors.length > 0)
+        ok(String(errors[0]).includes('unrepairable'), `publisher fault is loud: ${String(errors[0]).slice(0, 90)}`)
+        ok(j.seq() == seqBefore, 'sacred journal stayed truthful (nothing invented, nothing gapped)')
+        a.close()
+    }
+
+    console.log('\n[peer-repair] resync(): repair without waiting for the next write')
+    {
+        const j = createPatchRelayJournal({history: 64})
+        const net = makeLossyRemote(j, 'a')
+        const a = createPeerClient<World>({remote: net.remote, account: 'a', initial: {n: 0}, drain: 'micro'})
+        await waitFor('warmup', () => j.seq() >= 0)
+        net.state.offline = true
+        a.store.state.n = 5
+        a.store.state.tag = 'silent'
+        await flushReactive(a.store.state)
+        await delay(20)
+        net.state.offline = false
+        ok(j.snapshot().n == 0, 'relay is behind and no further writes are coming')
+        await a.resync()
+        ok(json(j.snapshot()) == json(a.store.snapshot()) && j.snapshot().tag == 'silent',
+            'resync() repaired the journal without a new write')
+        a.close()
+    }
+
+    console.log(fails ? `\n${fails} FAILED` : '\nall passed')
+    if (fails) process.exit(1)
+}
+
+main().catch(e => { console.error(e); process.exit(1) })

package/doc/changes/1.0.63.md

@@ -1,8 +0,0 @@
-# 1.0.63
-
-- Add `Observe.createStoreManager` and `Observe.managedStore` resource builders for declarative mirror/replay/offline store startup.
-- Add manager planning with priority, tags, usage scoring, `large`, and `explicitOnly` gates.
-- Add manager lifecycle helpers: `start`, `startPlanned`, `stop`, `stopAll`, `get`, `touch`, `usage`, `statusListen`, and typed `handles`.
-- Rename public-facing Observe oracle folder from `observable2` to `observe` and make `Listen.ts` / `reactive.ts` the canonical source files, leaving numbered files as compatibility shims.
-- Update brief and extended API docs for the store manager and current naming.
-- Publish package `wenay-common2@1.0.63`.