lemon-model 1.2.2 → 1.2.4

package/dist/esm/sync/network.js

@@ -0,0 +1,273 @@
+/**
+ * `sync/network.ts`
+ * - L1 network decorators: reconnect-on-death wrapper and raw wire translator.
+ * - additive to `src/socket`; free to compose with `createFilteredNetwork` (translated -> filtered -> L3).
+ *
+ * @copyright (C) 2026 LemonCloud Co Ltd. - All Rights Reserved.
+ */
+import { WEBSOCKET_NETWORK_SCOPE, } from '../socket/index.js';
+/**
+ * default watchdog cadence for readyState-based death detection.
+ * needed because an in-memory `Network.close()` notifies no one (see `socket/socket.ts`); only a
+ * real `OwnedWebSocketNetwork`/`BrowserWebSocketNetwork` close notifies via `onError` (see below),
+ * so the watchdog is a fallback and can stay slow — 1s keeps idle browser cost negligible.
+ */
+const DEFAULT_WATCHDOG_MS = 1000;
+/** create the L1 reconnect decorator: swaps the internal network on death, keeping instance identity for L3 */
+export const createReconnectingNetwork = (factory, options) => new ReconnectingNetwork(factory, options);
+/** `NetworkSupportable` decorator that transparently swaps its internal network on death */
+class ReconnectingNetwork {
+    constructor(factory, options) {
+        var _a, _b, _c, _d;
+        this.factory = factory;
+        this._generation = 0;
+        /** connected: 정상 감시 | connecting: 후보 open 대기 | backoff: 재시도 대기 | closed: 영구 종료 */
+        this.phase = 'connected';
+        this.retryCount = 0;
+        this.lastMessageAt = Date.now();
+        this.messageHandlers = new Set();
+        this.errorHandlers = new Set();
+        this.reconnectHandlers = new Set();
+        this.baseMs = (_a = options === null || options === void 0 ? void 0 : options.baseMs) !== null && _a !== void 0 ? _a : 1000;
+        this.factor = (_b = options === null || options === void 0 ? void 0 : options.factor) !== null && _b !== void 0 ? _b : 2;
+        this.maxMs = (_c = options === null || options === void 0 ? void 0 : options.maxMs) !== null && _c !== void 0 ? _c : 30000;
+        this.maxRetries = options === null || options === void 0 ? void 0 : options.maxRetries;
+        this.idleTimeoutMs = options === null || options === void 0 ? void 0 : options.idleTimeoutMs;
+        this.delayMs = this.baseMs;
+        this.current = factory();
+        this.attach(this.current);
+        this.watchdogTimer = setInterval(() => this.watch(), (_d = options === null || options === void 0 ? void 0 : options.watchdogMs) !== null && _d !== void 0 ? _d : DEFAULT_WATCHDOG_MS);
+    }
+    /** internal network generation (0 initially, +1 per reconnect) */
+    get generation() {
+        return this._generation;
+    }
+    get readyState() {
+        return this.phase === 'closed' ? 'closed' : this.current.readyState;
+    }
+    ready() {
+        var _a, _b, _c;
+        return (_c = (_b = (_a = this.current).ready) === null || _b === void 0 ? void 0 : _b.call(_a)) !== null && _c !== void 0 ? _c : Promise.resolve();
+    }
+    onOpen(handler) {
+        var _a, _b, _c;
+        return (_c = (_b = (_a = this.current).onOpen) === null || _b === void 0 ? void 0 : _b.call(_a, handler)) !== null && _c !== void 0 ? _c : (() => undefined);
+    }
+    /** while disconnected (mid-reconnect or permanently closed) this throws synchronously; no send queuing */
+    send(data) {
+        if (this.phase === 'closed')
+            throw new Error(`@network is closed - reconnectingNetwork.send`);
+        if (this.current.readyState !== 'open') {
+            throw new Error(`@network is not connected - reconnectingNetwork.send`);
+        }
+        this.current.send(data);
+    }
+    onMessage(handler) {
+        this.messageHandlers.add(handler);
+        return () => this.messageHandlers.delete(handler);
+    }
+    onError(handler) {
+        this.errorHandlers.add(handler);
+        return () => this.errorHandlers.delete(handler);
+    }
+    onReconnect(handler) {
+        this.reconnectHandlers.add(handler);
+        return () => this.reconnectHandlers.delete(handler);
+    }
+    /** options are remembered and re-applied to every reconnected generation */
+    configure(options) {
+        var _a, _b;
+        this.configured = Object.assign(Object.assign({}, this.configured), options);
+        (_b = (_a = this.current).configure) === null || _b === void 0 ? void 0 : _b.call(_a, this.configured);
+    }
+    /** stop reconnecting and close the internal network for good */
+    close(code, reason) {
+        if (this.phase === 'closed')
+            return;
+        this.phase = 'closed';
+        clearInterval(this.watchdogTimer);
+        if (this.reconnectTimer)
+            clearTimeout(this.reconnectTimer);
+        this.detach();
+        this.current.close(code, reason);
+        this.messageHandlers.clear();
+        this.errorHandlers.clear();
+        this.reconnectHandlers.clear();
+    }
+    attach(network) {
+        this.unsubscribeMessage = network.onMessage(raw => {
+            this.lastMessageAt = Date.now();
+            for (const handler of [...this.messageHandlers])
+                handler(raw);
+        });
+        this.unsubscribeError = network.onError((error, context) => {
+            for (const handler of [...this.errorHandlers])
+                handler(error, Object.assign(Object.assign({}, context), { network: this }));
+            //! `OwnedWebSocketNetwork`/`BrowserWebSocketNetwork` notify a close via onError with this scope
+            //! (see `WEBSOCKET_NETWORK_SCOPE` in `socket/websocket.ts`). other onError calls (e.g. delivery
+            //! errors) are forwarded above but do not by themselves mean the network died.
+            if (context.scope === WEBSOCKET_NETWORK_SCOPE.ownedClose ||
+                context.scope === WEBSOCKET_NETWORK_SCOPE.browserClose) {
+                this.onInnerDeath();
+            }
+        });
+    }
+    detach() {
+        var _a, _b, _c;
+        (_a = this.unsubscribeMessage) === null || _a === void 0 ? void 0 : _a.call(this);
+        (_b = this.unsubscribeError) === null || _b === void 0 ? void 0 : _b.call(this);
+        (_c = this.unsubscribeCandidateOpen) === null || _c === void 0 ? void 0 : _c.call(this);
+    }
+    onInnerDeath() {
+        if (this.phase === 'connected')
+            this.beginBackoff();
+        else if (this.phase === 'connecting')
+            this.failAttempt(new Error(`@candidate network died before open - reconnectingNetwork`), 'reconnectingNetwork.connect');
+    }
+    /** watchdog fallback for networks that close without notifying (e.g. in-memory `Network.close()`) */
+    watch() {
+        const state = this.current.readyState;
+        if (this.phase === 'connected') {
+            if (state === 'closing' || state === 'closed')
+                return this.beginBackoff();
+            if (this.idleTimeoutMs && Date.now() - this.lastMessageAt > this.idleTimeoutMs)
+                this.beginBackoff();
+            return;
+        }
+        if (this.phase === 'connecting') {
+            if (state === 'open')
+                return this.settleReconnected(); // onOpen 없는 network용 fallback
+            if (state === 'closing' || state === 'closed')
+                this.onInnerDeath();
+        }
+    }
+    beginBackoff() {
+        this.detach();
+        this.phase = 'backoff';
+        this.reconnectTimer = setTimeout(() => this.attemptReconnect(), this.delayMs);
+    }
+    attemptReconnect() {
+        var _a, _b;
+        if (this.phase === 'closed')
+            return;
+        if (this.maxRetries != null && this.retryCount >= this.maxRetries) {
+            this.phase = 'closed';
+            clearInterval(this.watchdogTimer);
+            const error = new Error(`@network exceeded maxRetries[${this.maxRetries}] - reconnectingNetwork`);
+            for (const handler of [...this.errorHandlers])
+                handler(error, { scope: 'reconnectingNetwork.maxRetries', network: this });
+            this.messageHandlers.clear();
+            this.errorHandlers.clear();
+            this.reconnectHandlers.clear();
+            return;
+        }
+        let next;
+        try {
+            next = this.factory();
+        }
+        catch (e) {
+            this.failAttempt(e, 'reconnectingNetwork.factory');
+            return;
+        }
+        this.current = next;
+        this.attach(next);
+        if (this.configured)
+            (_a = next.configure) === null || _a === void 0 ? void 0 : _a.call(next, this.configured);
+        this.phase = 'connecting';
+        //! success is declared only once the candidate actually OPENS. a factory return alone is not a
+        //! connection (a real WebSocket constructs fine while the server is down), so resetting backoff
+        //! here would degrade to a constant-rate reconnect storm with an onReconnect/tick per attempt.
+        const state = next.readyState;
+        if (state === 'open')
+            return this.settleReconnected();
+        if (state === 'closing' || state === 'closed')
+            return this.onInnerDeath();
+        this.unsubscribeCandidateOpen = (_b = next.onOpen) === null || _b === void 0 ? void 0 : _b.call(next, () => {
+            if (this.phase === 'connecting' && this.current === next)
+                this.settleReconnected();
+        });
+        //! a candidate stuck in 'connecting' is bounded by the inner network's own connect timeout
+        //! (e.g. `OwnedWebSocketNetwork.connectTimeoutMs`), which actual-closes and lands in onInnerDeath.
+    }
+    /** a reconnect attempt failed (factory throw, or candidate died before open): keep growing the backoff */
+    failAttempt(error, scope) {
+        this.detach();
+        this.retryCount++;
+        this.delayMs = Math.min(this.delayMs * this.factor, this.maxMs);
+        for (const handler of [...this.errorHandlers])
+            handler(error, { scope, network: this });
+        this.phase = 'backoff';
+        this.reconnectTimer = setTimeout(() => this.attemptReconnect(), this.delayMs);
+    }
+    /** the candidate opened: only now reset the backoff/retry budget and notify onReconnect */
+    settleReconnected() {
+        var _a;
+        (_a = this.unsubscribeCandidateOpen) === null || _a === void 0 ? void 0 : _a.call(this);
+        this.unsubscribeCandidateOpen = undefined;
+        this.phase = 'connected';
+        this._generation++;
+        this.retryCount = 0;
+        this.delayMs = this.baseMs;
+        this.lastMessageAt = Date.now();
+        for (const handler of [...this.reconnectHandlers])
+            handler();
+    }
+}
+/** create the L1 wire translator decorator over a raw string, same slot as `createFilteredNetwork` */
+export const createTranslatedNetwork = (source, translator) => new TranslatedNetwork(source, translator);
+/** `NetworkSupportable` decorator that translates raw strings at the wire boundary */
+class TranslatedNetwork {
+    constructor(source, translator) {
+        this.source = source;
+        this.translator = translator;
+        this.errorHandlers = new Set();
+        this.unsubscribeSourceError = source.onError((error, context) => this.emitError(error, context));
+    }
+    get readyState() {
+        return this.source.readyState;
+    }
+    ready() {
+        var _a, _b, _c;
+        return (_c = (_b = (_a = this.source).ready) === null || _b === void 0 ? void 0 : _b.call(_a)) !== null && _c !== void 0 ? _c : Promise.resolve();
+    }
+    onOpen(handler) {
+        var _a, _b, _c;
+        return (_c = (_b = (_a = this.source).onOpen) === null || _b === void 0 ? void 0 : _b.call(_a, handler)) !== null && _c !== void 0 ? _c : (() => undefined);
+    }
+    send(data) {
+        this.source.send(this.translator.outbound ? this.translator.outbound(data) : data);
+    }
+    onMessage(handler) {
+        return this.source.onMessage(raw => {
+            let translated;
+            try {
+                translated = this.translator.inbound ? this.translator.inbound(raw) : raw;
+            }
+            catch (e) {
+                this.emitError(e, { scope: 'translatedNetwork.inbound' });
+                return;
+            }
+            if (translated === undefined)
+                return; // dropped by translator
+            handler(translated);
+        });
+    }
+    configure(options) {
+        var _a, _b;
+        (_b = (_a = this.source).configure) === null || _b === void 0 ? void 0 : _b.call(_a, options);
+    }
+    onError(handler) {
+        this.errorHandlers.add(handler);
+        return () => this.errorHandlers.delete(handler);
+    }
+    close(code, reason) {
+        this.unsubscribeSourceError();
+        this.errorHandlers.clear();
+        this.source.close(code, reason);
+    }
+    emitError(error, context) {
+        for (const handler of [...this.errorHandlers])
+            handler(error, Object.assign(Object.assign({}, context), { network: this }));
+    }
+}
+//# sourceMappingURL=network.js.map

package/dist/esm/sync/network.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"network.js","sourceRoot":"","sources":["../../../src/sync/network.ts"],"names":[],"mappings":"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"}

package/dist/esm/sync/testing.js

@@ -0,0 +1,44 @@
+/**
+ * `sync/testing.ts`
+ * - bridges the in-memory `Peer` simulator into a single `NetworkSupportable` for L3/L4 specs.
+ * - test/dev only; kept OUT of `sync/index.ts` so production bundles never pull in the simulator runtime.
+ *
+ * @copyright (C) 2026 LemonCloud Co Ltd. - All Rights Reserved.
+ */
+//! simulator runtime lives in the isolated `../socket/testing` module (kept out of the root barrel).
+import { createNetwork, createPeer } from '../socket/testing.js';
+/**
+ * create a connected client/server `Peer` pair and expose the client side as one `NetworkSupportable`.
+ *
+ * `Peer.dispatch` settles an envelope against its own pending map, and otherwise fans every remaining
+ * envelope out to `Peer.onMessage()` listeners whose return value becomes an automatic `result` reply
+ * (regardless of whether the listener actually returns anything). A client-side bridge built on
+ * `clientPeer.post()` + `clientPeer.onMessage()` therefore echoes every pull result and every server
+ * event straight back to the server as an empty `result`, and — since the server has no pending for
+ * that mid either — the server echoes it right back, forever. `send()` and `onMessage()` below instead
+ * talk to the raw uplink/downlink `Network` instances directly, bypassing `Peer` dispatch on the client
+ * side entirely, so no such reply is ever produced. The `server` `Peer` itself is untouched and keeps
+ * its normal `onMessage()`/`post()` contract for the simulated server band.
+ */
+export const createPeerBridge = (options) => {
+    let serverNetwork;
+    const server = createPeer(Object.assign(Object.assign({}, options === null || options === void 0 ? void 0 : options.server), { networkFactory: context => (serverNetwork = createNetwork(Object.assign({ id: context.id, fromPeerId: context.fromPeerId, toPeerId: context.toPeerId, logger: context.logger }, context.options))) }));
+    const client = createPeer(options === null || options === void 0 ? void 0 : options.client);
+    const clientId = client.connect(server);
+    const clientNetwork = client.network;
+    if (!clientNetwork || !serverNetwork) {
+        throw new Error(`@peer bridge network capture failed - sync.testing.createPeerBridge`);
+    }
+    const network = {
+        get readyState() {
+            return client.readyState;
+        },
+        ready: () => client.ready(),
+        send: (data) => clientNetwork.send(data),
+        onMessage: handler => serverNetwork.onMessage(handler),
+        onError: handler => client.onError(handler),
+        close: () => client.close(),
+    };
+    return { network, server, serverNetwork, clientId };
+};
+//# sourceMappingURL=testing.js.map

package/dist/esm/sync/testing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"testing.js","sourceRoot":"","sources":["../../../src/sync/testing.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,qGAAqG;AACrG,OAAO,EAAE,aAAa,EAAE,UAAU,EAAe,MAAM,mBAAmB,CAAC;AAoB3E;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,OAA2B,EAAc,EAAE;IACxE,IAAI,aAA6C,CAAC;IAClD,MAAM,MAAM,GAAoB,UAAU,iCACnC,OAAO,aAAP,OAAO,uBAAP,OAAO,CAAE,MAAM,KAClB,cAAc,EAAE,OAAO,CAAC,EAAE,CACtB,CAAC,aAAa,GAAG,aAAa,iBAC1B,EAAE,EAAE,OAAO,CAAC,EAAE,EACd,UAAU,EAAE,OAAO,CAAC,UAAU,EAC9B,QAAQ,EAAE,OAAO,CAAC,QAAQ,EAC1B,MAAM,EAAE,OAAO,CAAC,MAAM,IACnB,OAAO,CAAC,OAAO,EACpB,CAAC,IACT,CAAC;IACH,MAAM,MAAM,GAAoB,UAAU,CAAC,OAAO,aAAP,OAAO,uBAAP,OAAO,CAAE,MAAM,CAAC,CAAC;IAC5D,MAAM,QAAQ,GAAG,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IACxC,MAAM,aAAa,GAAG,MAAM,CAAC,OAAO,CAAC;IACrC,IAAI,CAAC,aAAa,IAAI,CAAC,aAAa,EAAE;QAClC,MAAM,IAAI,KAAK,CAAC,qEAAqE,CAAC,CAAC;KAC1F;IAED,MAAM,OAAO,GAAuB;QAChC,IAAI,UAAU;YACV,OAAO,MAAM,CAAC,UAAU,CAAC;QAC7B,CAAC;QACD,KAAK,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,KAAK,EAAE;QAC3B,IAAI,EAAE,CAAC,IAAY,EAAE,EAAE,CAAC,aAAc,CAAC,IAAI,CAAC,IAAI,CAAC;QACjD,SAAS,EAAE,OAAO,CAAC,EAAE,CAAC,aAAc,CAAC,SAAS,CAAC,OAAO,CAAC;QACvD,OAAO,EAAE,OAAO,CAAC,EAAE,CAAC,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC;QAC3C,KAAK,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,KAAK,EAAE;KAC9B,CAAC;IAEF,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,aAAa,EAAE,QAAQ,EAAE,CAAC;AACxD,CAAC,CAAC"}

package/dist/esm/sync/ticker.js

@@ -0,0 +1,53 @@
+/** create a self-rescheduling ticker: no overlap, backoff on failure, restore on success */
+export const createSyncTicker = (tick, options) => new SyncTicker(tick, options);
+class SyncTicker {
+    constructor(tick, options) {
+        var _a, _b;
+        this.tick = tick;
+        this.options = options;
+        this._running = false;
+        /** bumped on every start()/stop(): an in-flight tick from an old epoch must not reschedule a second chain */
+        this.epoch = 0;
+        this.factor = (_a = options.factor) !== null && _a !== void 0 ? _a : 2;
+        this.maxMs = (_b = options.maxMs) !== null && _b !== void 0 ? _b : 60000;
+        this.delayMs = options.intervalMs;
+    }
+    get running() {
+        return this._running;
+    }
+    start() {
+        if (this._running)
+            return; // re-entrant start() is a no-op
+        this._running = true;
+        this.epoch++;
+        this.delayMs = this.options.intervalMs;
+        this.schedule(this.epoch);
+    }
+    stop() {
+        this._running = false;
+        this.epoch++;
+        if (this.timer)
+            clearTimeout(this.timer);
+        this.timer = undefined;
+    }
+    schedule(epoch) {
+        if (!this._running || epoch !== this.epoch)
+            return;
+        this.timer = setTimeout(() => this.run(epoch), this.delayMs);
+    }
+    /** the next tick is scheduled only after this one settles (setTimeout chain) - no overlap */
+    run(epoch) {
+        this.tick().then(() => {
+            if (epoch !== this.epoch)
+                return; // stale chain (stopped/restarted while in flight)
+            this.delayMs = this.options.intervalMs;
+            this.schedule(epoch);
+        }, () => {
+            if (epoch !== this.epoch)
+                return; // stale chain (stopped/restarted while in flight)
+            this.delayMs = Math.min(this.delayMs * this.factor, this.maxMs);
+            this.schedule(epoch);
+        });
+    }
+}
+//# sourceMappingURL=ticker.js.map

package/dist/esm/sync/ticker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ticker.js","sourceRoot":"","sources":["../../../src/sync/ticker.ts"],"names":[],"mappings":"AAqBA,4FAA4F;AAC5F,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,IAA4B,EAAE,OAA0B,EAAyB,EAAE,CAChH,IAAI,UAAU,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;AAElC,MAAM,UAAU;IASZ,YAAoC,IAA4B,EAAmB,OAA0B;;QAAzE,SAAI,GAAJ,IAAI,CAAwB;QAAmB,YAAO,GAAP,OAAO,CAAmB;QAJrG,aAAQ,GAAG,KAAK,CAAC;QACzB,6GAA6G;QACrG,UAAK,GAAG,CAAC,CAAC;QAGd,IAAI,CAAC,MAAM,GAAG,MAAA,OAAO,CAAC,MAAM,mCAAI,CAAC,CAAC;QAClC,IAAI,CAAC,KAAK,GAAG,MAAA,OAAO,CAAC,KAAK,mCAAI,KAAM,CAAC;QACrC,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC,UAAU,CAAC;IACtC,CAAC;IAED,IAAW,OAAO;QACd,OAAO,IAAI,CAAC,QAAQ,CAAC;IACzB,CAAC;IAEM,KAAK;QACR,IAAI,IAAI,CAAC,QAAQ;YAAE,OAAO,CAAC,gCAAgC;QAC3D,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC;QACrB,IAAI,CAAC,KAAK,EAAE,CAAC;QACb,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC;QACvC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAC9B,CAAC;IAEM,IAAI;QACP,IAAI,CAAC,QAAQ,GAAG,KAAK,CAAC;QACtB,IAAI,CAAC,KAAK,EAAE,CAAC;QACb,IAAI,IAAI,CAAC,KAAK;YAAE,YAAY,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACzC,IAAI,CAAC,KAAK,GAAG,SAAS,CAAC;IAC3B,CAAC;IAEO,QAAQ,CAAC,KAAa;QAC1B,IAAI,CAAC,IAAI,CAAC,QAAQ,IAAI,KAAK,KAAK,IAAI,CAAC,KAAK;YAAE,OAAO;QACnD,IAAI,CAAC,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC;IACjE,CAAC;IAED,6FAA6F;IACrF,GAAG,CAAC,KAAa;QACrB,IAAI,CAAC,IAAI,EAAE,CAAC,IAAI,CACZ,GAAG,EAAE;YACD,IAAI,KAAK,KAAK,IAAI,CAAC,KAAK;gBAAE,OAAO,CAAC,kDAAkD;YACpF,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC;YACvC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;QACzB,CAAC,EACD,GAAG,EAAE;YACD,IAAI,KAAK,KAAK,IAAI,CAAC,KAAK;gBAAE,OAAO,CAAC,kDAAkD;YACpF,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC;YAChE,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;QACzB,CAAC,CACJ,CAAC;IACN,CAAC;CACJ"}

package/dist/esm/sync/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/{proxy → esm/sync}/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/proxy/types.ts"],"names":[],"mappings":";AAAA;;;;;;;;GAQG"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/sync/types.ts"],"names":[],"mappings":""}

package/dist/index.d.ts

@@ -13,3 +13,6 @@ export * from './cores';
 export * from './socket';
 export * from './genai';
 export * from './buffer';
+export * from './sync';
+export * from './progress';
+export * from './logtrace';

package/dist/index.js

@@ -29,4 +29,7 @@ __exportStar(require("./cores"), exports);
 __exportStar(require("./socket"), exports);
 __exportStar(require("./genai"), exports);
 __exportStar(require("./buffer"), exports);
+__exportStar(require("./sync"), exports);
+__exportStar(require("./progress"), exports);
+__exportStar(require("./logtrace"), exports);
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA;;;;;;;;;GASG;AACH,0CAAwB;AACxB,0CAAwB;AACxB,2CAAyB;AACzB,0CAAwB;AACxB,2CAAyB"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA;;;;;;;;;GASG;AACH,0CAAwB;AACxB,0CAAwB;AACxB,2CAAyB;AACzB,0CAAwB;AACxB,2CAAyB;AACzB,yCAAuB;AACvB,6CAA2B;AAC3B,6CAA2B"}

package/dist/logtrace/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * `logtrace/index.ts`
+ * - one-way realtime log stream (reporter/consumer) over a shared socket.
+ *
+ * @copyright (C) 2026 LemonCloud Co Ltd. - All Rights Reserved.
+ */
+export * from './logtrace';

package/dist/logtrace/index.js

@@ -0,0 +1,27 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * `logtrace/index.ts`
+ * - one-way realtime log stream (reporter/consumer) over a shared socket.
+ *
+ * @copyright (C) 2026 LemonCloud Co Ltd. - All Rights Reserved.
+ */
+__exportStar(require("./logtrace"), exports);
+//! NOTE: the verification loop harness (`./testing`) is intentionally NOT re-exported here.
+//! It pulls in the in-memory socket simulator — import it via the isolated
+//! `lemon-model/logtrace/testing` entry so production bundles stay clean.
+//# sourceMappingURL=index.js.map

package/dist/logtrace/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/logtrace/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA;;;;;GAKG;AACH,6CAA2B;AAE3B,4FAA4F;AAC5F,2EAA2E;AAC3E,0EAA0E"}

package/dist/logtrace/logtrace.d.ts

@@ -0,0 +1,99 @@
+/**
+ * `logtrace/logtrace.ts`
+ * - one-way (server -> client) realtime log stream over one shared WebSocket.
+ * - contracts + reporter(batching) + consumer(ring buffer) live in one file since
+ *   both ends share the wire envelope/batch codec (see SPEC.md).
+ *
+ * @copyright (C) 2026 LemonCloud Co Ltd. - All Rights Reserved.
+ */
+import { NetworkSupportable, SocketMessage, SocketUnsubscribe } from '../socket/types';
+/** log severity - same 4 levels as SocketLogLevel */
+export declare type LogTraceLevel = 'debug' | 'info' | 'warn' | 'error';
+/** single log entry - the minimal unit crossing the wire */
+export interface LogTraceEntry {
+    /** log severity */
+    level: LogTraceLevel;
+    /** epoch timestamp in milliseconds */
+    ts: number;
+    /** human-readable message */
+    message: string;
+    /** structured extra data (optional) */
+    json?: Record<string, any>;
+    /** monotonic sequence within a source - ordering/loss observation. issued only past the reporter minLevel gate */
+    seq: number;
+    /** sender identity - carried on the batch over the wire; filled by the consumer when storing */
+    source?: string;
+    /** true when json was dropped or message was cut by the size budget */
+    truncated?: boolean;
+}
+/** batch payload carried in SocketMessage.data */
+export interface LogTraceBatch {
+    /** batch entries (reporter emit order) */
+    entries: LogTraceEntry[];
+    /** sender identity - unique per reporter (required). consumer dedup/loss key */
+    source: string;
+}
+/** server-side send path injection (Ports & Adapters). a rejected Promise is wired into onError */
+export declare type LogTraceSink = (message: SocketMessage<LogTraceBatch>) => void | Promise<void>;
+export interface LogTraceReporterOptions {
+    /** envelope type (default 'log:trace') */
+    type?: string;
+    /** sender identity - carried as the batch source. auto random id when omitted (invocation id recommended) */
+    source?: string;
+    /** levels below this are not sent at all (default 'debug' = everything) */
+    minLevel?: LogTraceLevel;
+    /** flush when this many entries are buffered (default 20) */
+    flushCount?: number;
+    /** flush this long after the first buffered entry. 0 disables the timer (default 250) */
+    flushIntervalMs?: number;
+    /** serialized batch byte budget. split-flush right before exceeding (default 3/4 of maxPacketBytes) */
+    maxBatchBytes?: number;
+    /** envelope size cap (default 64kb). a single oversized entry drops json + marks truncated */
+    maxPacketBytes?: number;
+    /** observe send failures and truncations */
+    onError?: (error: any, entries: LogTraceEntry[]) => void;
+}
+export interface LogTraceReporterSupportable {
+    /** record one log entry. auto-flushes when a flush condition is reached */
+    log(level: LogTraceLevel, message: string, json?: Record<string, any>): void;
+    /** level shortcut */
+    debug(message: string, json?: Record<string, any>): void;
+    info(message: string, json?: Record<string, any>): void;
+    warn(message: string, json?: Record<string, any>): void;
+    error(message: string, json?: Record<string, any>): void;
+    /** send the buffered entries now */
+    flush(): void;
+    /** flush + release the timer. must be called before a lambda invocation ends. later log calls are ignored */
+    close(): void;
+}
+/** query condition for consumer.list() */
+export interface LogTraceQuery {
+    /** only this level and above */
+    minLevel?: LogTraceLevel;
+    /** last n entries (default all) */
+    limit?: number;
+}
+export interface LogTraceConsumerOptions {
+    /** inbound envelope type prefix (default 'log:') */
+    typePrefix?: string;
+    /** received entries below this level are discarded (default 'debug' = everything) */
+    minLevel?: LogTraceLevel;
+    /** ring buffer retention cap (default 1000) */
+    maxEntries?: number;
+}
+export interface LogTraceConsumerSupportable {
+    /** subscribe to received entries - batches are unpacked and notified one entry at a time, in batch order */
+    onEntry(handler: (entry: LogTraceEntry) => void): SocketUnsubscribe;
+    /** list retained entries - returned in (ts, seq) ascending order */
+    list(query?: LogTraceQuery): LogTraceEntry[];
+    /** observed wire loss - sum of (max seq - received count) per source. exact regardless of arrival order */
+    readonly gapCount: number;
+    /** drop retained entries (subscriptions stay) */
+    clear(): void;
+    /** unsubscribe from the network. does NOT close the network (shared socket) */
+    close(): void;
+}
+/** create a batching log reporter over an injected send path */
+export declare const createLogTraceReporter: (sink: LogTraceSink, options?: LogTraceReporterOptions) => LogTraceReporterSupportable;
+/** create a log consumer over a shared raw string network */
+export declare const createLogTraceConsumer: (network: NetworkSupportable, options?: LogTraceConsumerOptions) => LogTraceConsumerSupportable;