lemon-model 1.2.3 → 1.4.0

package/dist/sync/network.js

@@ -0,0 +1,278 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createTranslatedNetwork = exports.createReconnectingNetwork = void 0;
+/**
+ * `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.
+ */
+const socket_1 = require("../socket");
+/**
+ * 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 */
+const createReconnectingNetwork = (factory, options) => new ReconnectingNetwork(factory, options);
+exports.createReconnectingNetwork = createReconnectingNetwork;
+/** `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 === socket_1.WEBSOCKET_NETWORK_SCOPE.ownedClose ||
+                context.scope === socket_1.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` */
+const createTranslatedNetwork = (source, translator) => new TranslatedNetwork(source, translator);
+exports.createTranslatedNetwork = createTranslatedNetwork;
+/** `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/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/sync/testing.d.ts

@@ -0,0 +1,38 @@
+/**
+ * `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.
+ */
+import { PeerOptions } from '../socket/testing';
+import { NetworkSupportable, PeerSupportable } from '../socket/types';
+/** server-side pieces of a bridged peer link */
+export interface PeerBridge {
+    /** bridged client-side network. wire this into `createSocketClient()` */
+    network: NetworkSupportable;
+    /** plain server `Peer`. register `onMessage()`/`post()` on it as the simulated server band */
+    server: PeerSupportable;
+    /** raw downlink (server -> client). for JSONTransport/progress producers simulating server pushes that are not sync envelopes */
+    serverNetwork: NetworkSupportable;
+    /** assigned client id, usable with `server.post(message, { clientId })` */
+    clientId: string;
+}
+export interface PeerBridgeOptions {
+    server?: PeerOptions;
+    client?: PeerOptions;
+}
+/**
+ * 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 declare const createPeerBridge: (options?: PeerBridgeOptions) => PeerBridge;

package/dist/sync/testing.js

@@ -0,0 +1,48 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createPeerBridge = void 0;
+/**
+ * `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).
+const testing_1 = require("../socket/testing");
+/**
+ * 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.
+ */
+const createPeerBridge = (options) => {
+    let serverNetwork;
+    const server = (0, testing_1.createPeer)(Object.assign(Object.assign({}, options === null || options === void 0 ? void 0 : options.server), { networkFactory: context => (serverNetwork = (0, testing_1.createNetwork)(Object.assign({ id: context.id, fromPeerId: context.fromPeerId, toPeerId: context.toPeerId, logger: context.logger }, context.options))) }));
+    const client = (0, testing_1.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 };
+};
+exports.createPeerBridge = createPeerBridge;
+//# sourceMappingURL=testing.js.map

package/dist/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,+CAA2E;AAoB3E;;;;;;;;;;;;GAYG;AACI,MAAM,gBAAgB,GAAG,CAAC,OAA2B,EAAc,EAAE;IACxE,IAAI,aAA6C,CAAC;IAClD,MAAM,MAAM,GAAoB,IAAA,oBAAU,kCACnC,OAAO,aAAP,OAAO,uBAAP,OAAO,CAAE,MAAM,KAClB,cAAc,EAAE,OAAO,CAAC,EAAE,CACtB,CAAC,aAAa,GAAG,IAAA,uBAAa,kBAC1B,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,IAAA,oBAAU,EAAC,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;AAhCW,QAAA,gBAAgB,oBAgC3B"}

package/dist/sync/ticker.d.ts

@@ -0,0 +1,21 @@
+/**
+ * `sync/ticker.ts`
+ * - opt-in tick utility for the service-side tick-owning point. works over any `() => Promise` (machine-agnostic).
+ *
+ * @copyright (C) 2026 LemonCloud Co Ltd. - All Rights Reserved.
+ */
+export interface SyncTickerOptions {
+    /** steady-state period */
+    intervalMs: number;
+    /** exponential backoff multiplier on failure (default 2) */
+    factor?: number;
+    /** backoff delay cap (default 60_000ms) */
+    maxMs?: number;
+}
+export interface SyncTickerSupportable {
+    start(): void;
+    stop(): void;
+    readonly running: boolean;
+}
+/** create a self-rescheduling ticker: no overlap, backoff on failure, restore on success */
+export declare const createSyncTicker: (tick: () => Promise<unknown>, options: SyncTickerOptions) => SyncTickerSupportable;

package/dist/sync/ticker.js

@@ -0,0 +1,57 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createSyncTicker = void 0;
+/** create a self-rescheduling ticker: no overlap, backoff on failure, restore on success */
+const createSyncTicker = (tick, options) => new SyncTicker(tick, options);
+exports.createSyncTicker = createSyncTicker;
+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/sync/ticker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ticker.js","sourceRoot":"","sources":["../../src/sync/ticker.ts"],"names":[],"mappings":";;;AAqBA,4FAA4F;AACrF,MAAM,gBAAgB,GAAG,CAAC,IAA4B,EAAE,OAA0B,EAAyB,EAAE,CAChH,IAAI,UAAU,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;AADrB,QAAA,gBAAgB,oBACK;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/sync/types.d.ts

@@ -0,0 +1,115 @@
+/**
+ * `sync/types.ts`
+ * - public contracts for the model sync client: L3 socket client runtime + L4 sync machine.
+ *
+ * @copyright (C) 2026 LemonCloud Co Ltd. - All Rights Reserved.
+ */
+import { NetworkSupportable, RawOwnershipPredicate, SocketErrorHandler, SocketMessage, SocketUnsubscribe } from '../socket';
+/**
+ * minimal contract a sync target must satisfy — the machine only ever reads these three fields.
+ * `CoreModel` satisfies this automatically; any external model with id/updatedAt qualifies too.
+ */
+export interface SyncTarget {
+    /** unique id */
+    id?: string;
+    /** last-modified timestamp (ms) — the field the default versionOf reads */
+    updatedAt?: number;
+    /** deleted timestamp (ms) — presence removes the model from the store */
+    deletedAt?: number;
+}
+/** mid generator */
+export interface SocketClientIdentityProvider {
+    nextMid(): string;
+}
+export interface SocketClientOptions {
+    /** request-response wait limit (default 15_000ms) */
+    timeoutMs?: number;
+    /** concurrent pending cap. request() beyond this rejects immediately (default unlimited) */
+    maxPending?: number;
+    /** ownership decision over raw strings this runtime handles. wrapped internally with createFilteredNetwork */
+    filter?: RawOwnershipPredicate;
+    /** mid generator (default provided) */
+    identity?: SocketClientIdentityProvider;
+}
+export interface SocketRequestOptions {
+    /** timeout override for this request only */
+    timeoutMs?: number;
+}
+export interface SocketClientSupportable {
+    /** underlying network (shared socket) */
+    readonly network: NetworkSupportable;
+    /** number of requests awaiting a response */
+    readonly pendingCount: number;
+    /** delegate network ready */
+    ready(): Promise<void>;
+    /** send a request and wait for the result/error of the same mid */
+    request<T = any, R = any>(type: string, data: T, options?: SocketRequestOptions): Promise<R>;
+    /** one-way send without waiting for a response */
+    post<T = any>(type: string, data: T): void;
+    /** subscribe to events of a specific type */
+    onType<T = any>(type: string, handler: (data: T, message: SocketMessage<T>) => void): SocketUnsubscribe;
+    /** subscribe to inbound envelopes not matched to a pending request. unmatched result/error is treated as a late response and quietly dropped */
+    onMessage(handler: (message: SocketMessage) => void): SocketUnsubscribe;
+    /** observe asynchronous errors (timeout, send failure, network error) */
+    onError(handler: SocketErrorHandler): SocketUnsubscribe;
+    /** reject all pending + detach listeners. does not close network (socket is shared) */
+    close(): void;
+}
+/** change notification */
+export interface SyncChangeEvent<M extends SyncTarget> {
+    /** cause of the change */
+    cause: 'pull' | 'event';
+    /** models applied or removed by this change */
+    models: M[];
+}
+/** server-confirmed page extracted from a pull reply */
+export interface SyncReplyPage<M extends SyncTarget> {
+    /** server-confirmed models */
+    models: M[];
+    /** cursor for the next page. absent means pull is done */
+    next?: any;
+}
+/**
+ * protocol adapter — injected by the service.
+ * the machine does not know the wire protocol, and the adapter does not know local state.
+ */
+export interface SyncProtocolAdapter<M extends SyncTarget> {
+    /** shared version axis for freshness judgement and the watermark. undefined skips the model (default m => m.updatedAt).
+     *  pure/total like parseEvent — never throw; return a positive finite number or undefined */
+    versionOf?: (model: M) => number | undefined;
+    /** build a pull request from since(versionOf-axis watermark) and cursor. omitted since means full pull */
+    buildPull(since?: number, cursor?: any): {
+        type: string;
+        data: any;
+    };
+    /** extract server-confirmed models and the next cursor from pull reply data */
+    parseReply(data: any): SyncReplyPage<M>;
+    /** extract this type's models from a server-sent event. undefined if not owned. must be a pure predicate/extractor with no side effects */
+    parseEvent(message: SocketMessage): M[] | undefined;
+}
+export interface ModelSyncOptions<M extends SyncTarget> {
+    adapter: SyncProtocolAdapter<M>;
+    /** run an initial pull right after register (default true). failure still leaves register valid; the next pull/tick pulls from scratch. set false and call pull() directly to observe failures */
+    initialPull?: boolean;
+}
+/** sync handle for a single model type */
+export interface ModelSyncSupportable<M extends SyncTarget> {
+    readonly type: string;
+    /** read-only local state lookup */
+    get(id: string): M | undefined;
+    list(): M[];
+    /** pull changes since the watermark and apply them. loops the cursor until parseReply.next is absent */
+    pull(): Promise<M[]>;
+    /** subscribe to change notifications */
+    onChange(handler: (event: SyncChangeEvent<M>) => void): SocketUnsubscribe;
+    /** detach this type's subscriptions/listeners */
+    close(): void;
+}
+export interface SyncMachineSupportable {
+    /** register a domain model type. re-registering the same type returns the existing handle and ignores the new options */
+    register<M extends SyncTarget>(type: string, options: ModelSyncOptions<M>): ModelSyncSupportable<M>;
+    /** pull every registered type once. the service calls this at whatever cadence it wants. a type whose pull is already in flight is skipped, not nested */
+    tick(): Promise<void>;
+    /** detach everything */
+    close(): void;
+}

package/dist/sync/types.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/sync/types.js.map

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

package/dist/upload/engine/engine.d.ts

@@ -0,0 +1,52 @@
+/**
+ * `upload/engine/engine.ts`
+ * - the one upload flow every shell shares: `start` -> run executors -> `complete`.
+ * - swapping the server's transfer method never touches this file; a new `UploadTransfer` kind
+ *   arrives as one more `UploadTransferExecutor` passed to the constructor.
+ * - runtime-neutral like the contract itself: no Node, DOM, or AWS types. the shell injects the
+ *   three things that are shell-specific — reading bytes (`UploadSource`), the HTTP primitives
+ *   (see `./executors`), and hashing.
+ *
+ * @copyright (C) 2026 LemonCloud Co Ltd. - All Rights Reserved.
+ */
+import type { UploadCompleteItem, UploadFailure, UploadService, UploadTransfer, UploadView } from '../types';
+import type { UploadBatchProgressSink, UploadProgressSink } from './progress';
+/** bytes provider; hides DOM `File`, RN uri, Electron path behind one shape */
+export interface UploadSource {
+    name: string;
+    contentType: string;
+    contentSize: number;
+    /** whole send (roadmap 1·2 sizes) */
+    bytes(): Promise<Uint8Array>;
+    /** sha256 hex(64) when this shell chooses to hash at send time; omit to skip */
+    hash?(): Promise<string | undefined>;
+}
+/** moves bytes for one transfer kind and reports the receipt the server expects in `complete` */
+export interface UploadTransferExecutor<T extends UploadTransfer = UploadTransfer> {
+    readonly kind: T['kind'];
+    /** `onProgress` is optional to CALL, not to accept: an executor that cannot observe bytes never calls it */
+    run(id: string, transfer: T, source: UploadSource, onProgress: UploadProgressSink): Promise<UploadCompleteItem>;
+}
+/**
+ * transfers in flight at once.
+ * - a browser queues beyond ~6 per origin, and a queued presigned url burns its `expiresAt` while it waits.
+ * - override per engine when a shell measures something better.
+ */
+export declare const UPLOAD_DEFAULT_CONCURRENCY = 3;
+export declare class UploadEngine {
+    private readonly service;
+    private readonly executors;
+    private readonly options?;
+    private readonly kinds;
+    constructor(service: UploadService, executors: ReadonlyArray<UploadTransferExecutor>, options?: {
+        concurrency?: number;
+    });
+    /** returns one view per source, in order: `stored`, or `failed` with the reason. `onProgress` gets a snapshot per change */
+    upload(sources: ReadonlyArray<UploadSource>, onProgress?: UploadBatchProgressSink): Promise<UploadView[]>;
+    private transferTracked;
+    private transfer;
+}
+/** normalize an error thrown by the API adapter */
+export declare const asApiFailure: (error: unknown) => UploadFailure;
+/** normalize a non-2xx answer from the storage endpoint (status 0 = no response) */
+export declare const asStorageFailure: (status: number, code?: string) => UploadFailure;