lemon-model 1.2.1 → 1.2.3

package/dist/logtrace/testing.js

@@ -0,0 +1,81 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runLogTraceLoop = void 0;
+/**
+ * `logtrace/testing.ts`
+ * - isolated entry for the logtrace verification loop harness.
+ * - kept OUT of the package root barrel so production bundles do not include the in-memory socket simulator.
+ *
+ * Usage (tests / dev only):
+ *   import { runLogTraceLoop } from 'lemon-model/logtrace/testing';
+ *
+ * @copyright (C) 2026 LemonCloud Co Ltd. - All Rights Reserved.
+ */
+const socket_1 = require("../socket/socket");
+const logtrace_1 = require("./logtrace");
+/**
+ * Run an end-to-end verification loop:
+ * entries -> LogTraceReporter (batching) -> NetworkSupportable -> LogTraceConsumer (ring buffer).
+ *
+ * Metrics-based assertions belong in specs; this helper only records numbers.
+ */
+const runLogTraceLoop = (options) => __awaiter(void 0, void 0, void 0, function* () {
+    const startedAt = Date.now();
+    const network = (0, socket_1.createNetwork)(options.networkOptions);
+    // Raw packets measure batching and packet budgets, separate from delivery.
+    const rawPackets = [];
+    const unsubscribeRaw = network.onMessage(packet => rawPackets.push(packet));
+    const consumer = (0, logtrace_1.createLogTraceConsumer)(network, options.consumerOptions);
+    let delivered = 0;
+    let truncated = 0;
+    // Consumer callbacks are the source of delivered/truncated metrics.
+    const unsubscribeEntry = consumer.onEntry(entry => {
+        delivered += 1;
+        if (entry.truncated)
+            truncated += 1;
+    });
+    let batches = 0;
+    const reporter = (0, logtrace_1.createLogTraceReporter)(message => {
+        batches += 1;
+        network.send(JSON.stringify(message));
+    }, options.reporterOptions);
+    try {
+        // Replay input synchronously; reporter options decide when batches flush.
+        for (const record of options.entries)
+            reporter.log(record.level, record.message, record.json);
+        reporter.close();
+        yield new Promise(resolve => { var _a; return setTimeout(resolve, (_a = options.settleMs) !== null && _a !== void 0 ? _a : 50); });
+        const packetBytes = rawPackets.reduce((sum, packet) => sum + byteLength(packet), 0);
+        const maxPacketBytes = rawPackets.reduce((max, packet) => Math.max(max, byteLength(packet)), 0);
+        return {
+            elapsedMs: Date.now() - startedAt,
+            packets: rawPackets.length,
+            packetBytes,
+            maxPacketBytes,
+            batches,
+            delivered,
+            truncated,
+            gapCount: consumer.gapCount,
+            finalEntries: consumer.list(),
+        };
+    }
+    finally {
+        unsubscribeRaw();
+        unsubscribeEntry();
+        consumer.close();
+        network.close();
+    }
+});
+exports.runLogTraceLoop = runLogTraceLoop;
+const textEncoder = new TextEncoder();
+const byteLength = (value) => textEncoder.encode(value).length;
+//# sourceMappingURL=testing.js.map

package/dist/logtrace/testing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"testing.js","sourceRoot":"","sources":["../../src/logtrace/testing.ts"],"names":[],"mappings":";;;;;;;;;;;;AAAA;;;;;;;;;GASG;AACH,6CAAiD;AAEjD,yCAOoB;AA6BpB;;;;;GAKG;AACI,MAAM,eAAe,GAAG,CAAO,OAA4B,EAAgC,EAAE;IAChG,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IAC7B,MAAM,OAAO,GAAG,IAAA,sBAAa,EAAC,OAAO,CAAC,cAAc,CAAC,CAAC;IACtD,2EAA2E;IAC3E,MAAM,UAAU,GAAa,EAAE,CAAC;IAChC,MAAM,cAAc,GAAG,OAAO,CAAC,SAAS,CAAC,MAAM,CAAC,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC;IAC5E,MAAM,QAAQ,GAAG,IAAA,iCAAsB,EAAC,OAAO,EAAE,OAAO,CAAC,eAAe,CAAC,CAAC;IAC1E,IAAI,SAAS,GAAG,CAAC,CAAC;IAClB,IAAI,SAAS,GAAG,CAAC,CAAC;IAClB,oEAAoE;IACpE,MAAM,gBAAgB,GAAG,QAAQ,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE;QAC9C,SAAS,IAAI,CAAC,CAAC;QACf,IAAI,KAAK,CAAC,SAAS;YAAE,SAAS,IAAI,CAAC,CAAC;IACxC,CAAC,CAAC,CAAC;IACH,IAAI,OAAO,GAAG,CAAC,CAAC;IAChB,MAAM,QAAQ,GAAG,IAAA,iCAAsB,EAAC,OAAO,CAAC,EAAE;QAC9C,OAAO,IAAI,CAAC,CAAC;QACb,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC,CAAC;IAC1C,CAAC,EAAE,OAAO,CAAC,eAAe,CAAC,CAAC;IAE5B,IAAI;QACA,0EAA0E;QAC1E,KAAK,MAAM,MAAM,IAAI,OAAO,CAAC,OAAO;YAAE,QAAQ,CAAC,GAAG,CAAC,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC,OAAO,EAAE,MAAM,CAAC,IAAI,CAAC,CAAC;QAC9F,QAAQ,CAAC,KAAK,EAAE,CAAC;QACjB,MAAM,IAAI,OAAO,CAAC,OAAO,CAAC,EAAE,WAAC,OAAA,UAAU,CAAC,OAAO,EAAE,MAAA,OAAO,CAAC,QAAQ,mCAAI,EAAE,CAAC,CAAA,EAAA,CAAC,CAAC;QAE1E,MAAM,WAAW,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,MAAM,EAAE,EAAE,CAAC,GAAG,GAAG,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC;QACpF,MAAM,cAAc,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,MAAM,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,UAAU,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;QAChG,OAAO;YACH,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS;YACjC,OAAO,EAAE,UAAU,CAAC,MAAM;YAC1B,WAAW;YACX,cAAc;YACd,OAAO;YACP,SAAS;YACT,SAAS;YACT,QAAQ,EAAE,QAAQ,CAAC,QAAQ;YAC3B,YAAY,EAAE,QAAQ,CAAC,IAAI,EAAE;SAChC,CAAC;KACL;YAAS;QACN,cAAc,EAAE,CAAC;QACjB,gBAAgB,EAAE,CAAC;QACnB,QAAQ,CAAC,KAAK,EAAE,CAAC;QACjB,OAAO,CAAC,KAAK,EAAE,CAAC;KACnB;AACL,CAAC,CAAA,CAAC;AA7CW,QAAA,eAAe,mBA6C1B;AAEF,MAAM,WAAW,GAAG,IAAI,WAAW,EAAE,CAAC;AACtC,MAAM,UAAU,GAAG,CAAC,KAAa,EAAU,EAAE,CAAC,WAAW,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC"}

package/dist/progress/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * `progress/index.ts`
+ * - public re-export for the progress module.
+ * - `./testing` is intentionally excluded from this barrel (subpath-only, see SPEC.md).
+ *
+ * @copyright (C) 2026 LemonCloud Co Ltd. - All Rights Reserved.
+ */
+export * from './progress';

package/dist/progress/index.js

@@ -0,0 +1,25 @@
+"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 });
+/**
+ * `progress/index.ts`
+ * - public re-export for the progress module.
+ * - `./testing` is intentionally excluded from this barrel (subpath-only, see SPEC.md).
+ *
+ * @copyright (C) 2026 LemonCloud Co Ltd. - All Rights Reserved.
+ */
+__exportStar(require("./progress"), exports);
+//# sourceMappingURL=index.js.map

package/dist/progress/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/progress/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA;;;;;;GAMG;AACH,6CAA2B"}

package/dist/progress/progress.d.ts

@@ -0,0 +1,112 @@
+/**
+ * `progress/progress.ts`
+ * - one-way (server -> client) task progress reporting over a shared WebSocket.
+ * - contract + reporter + gauges + consumer in one file (see SPEC.md - SSOT).
+ *
+ * @copyright (C) 2026 LemonCloud Co Ltd. - All Rights Reserved.
+ */
+import { NetworkSupportable, SocketMessage, SocketUnsubscribe } from '../socket/types';
+/** default serialized packet size limit (same family as `src/socket`) */
+export declare const DEFAULT_MAX_PACKET_BYTES: number;
+/** task execution status */
+export declare type ProgressStatus = 'pending' | 'running' | 'done' | 'error';
+/** progress snapshot of one task - the unit that travels the wire */
+export interface ProgressState {
+    /** task id (assigned by the service) */
+    id: string;
+    /** execution status */
+    status: ProgressStatus;
+    /** 0~100 progress ratio (omitted when not measurable) */
+    percent?: number;
+    /** current step / total steps */
+    step?: number;
+    totalSteps?: number;
+    /** human-readable current step description */
+    label?: string;
+    /** error summary when status is error */
+    error?: string;
+    /** emitted timestamp (epoch ms) - display only */
+    ts: number;
+    /** reporter-wide monotonic sequence - latest-wins judgement */
+    seq: number;
+    /** service-defined extra info. keep it small (see packet limit) */
+    meta?: Record<string, any>;
+}
+/** measurement produced by a gauge - subset merged into snapshots */
+export declare type ProgressMeasure = Partial<Pick<ProgressState, 'percent' | 'step' | 'totalSteps' | 'label'>>;
+/**
+ * progress measurement strategy - separates "how" percent is computed from the reporter.
+ * must be a pure read with no side effects. one function fits every strategy.
+ */
+export declare type ProgressGauge = () => ProgressMeasure;
+/** time-flow gauge - elapsed ratio against expectedMs, capped at 99% (only done() declares completion) */
+export declare const createTimeProgressGauge: (expectedMs: number, now?: () => number) => ProgressGauge;
+/** buffer-fill gauge - reads percent/bufferPercent from a GenAIStreamProgress-compatible source (structural type, no src/buffer dependency) */
+export declare const createBufferProgressGauge: (source: () => {
+    percent?: number;
+    bufferPercent?: number;
+} | undefined) => ProgressGauge;
+/** server-side send path injection (Ports & Adapters). a rejected Promise is wired to onError */
+export declare type ProgressSink = (message: SocketMessage<ProgressState>) => void | Promise<void>;
+export interface ProgressReporterOptions {
+    /** envelope type (default 'progress:update') */
+    type?: string;
+    /** update() emit coalescing window. 0 emits every update immediately (default 0) */
+    throttleMs?: number;
+    /** re-emit interval for running snapshots. 0 disables (default 0) */
+    heartbeatMs?: number;
+    /** serialized size limit. an oversized snapshot is emitted without meta and reported via onError (default DEFAULT_MAX_PACKET_BYTES = 64kb) */
+    maxPacketBytes?: number;
+    /** observe emit failures / size overruns */
+    onError?: (error: any, state: ProgressState) => void;
+}
+/** reporting handle for one task */
+export interface ProgressTaskSupportable {
+    readonly id: string;
+    /** current local snapshot */
+    readonly state: ProgressState;
+    /** patch then emit (throttled). ignored after done/error. status regression (running -> pending) drops status only, rest of the patch applies */
+    update(patch: Partial<Omit<ProgressState, 'id' | 'ts' | 'seq' | 'status'>> & {
+        status?: 'pending' | 'running';
+    }): void;
+    /** transition to a terminal status and emit immediately (throttle bypassed). later update is ignored */
+    done(patch?: Partial<Pick<ProgressState, 'label' | 'meta'>>): void;
+    error(error: string | Error, patch?: Partial<Pick<ProgressState, 'label' | 'meta'>>): void;
+}
+/** start options for one task */
+export interface ProgressTaskOptions {
+    /** percent auto-measurement strategy. gauge() is merged into the snapshot right before update/heartbeat emits. explicit update values win over gauge */
+    gauge?: ProgressGauge;
+}
+export interface ProgressReporterSupportable {
+    /** declare a task start and get its handle. calling again with the same id returns the existing handle */
+    start(id: string, initial?: Partial<Pick<ProgressState, 'label' | 'percent' | 'step' | 'totalSteps' | 'meta'>>, options?: ProgressTaskOptions): ProgressTaskSupportable;
+    /** flush unemitted snapshots + release timers. must be called before the lambda invocation ends */
+    close(): void;
+}
+/** change notification */
+export interface ProgressChangeEvent {
+    state: ProgressState;
+    /** true when this consumer sees the task for the first time */
+    created: boolean;
+}
+export interface ProgressConsumerOptions {
+    /** inbound type prefix (default 'progress:') */
+    typePrefix?: string;
+    /** retained task count limit. evicts oldest terminal (done/error) tasks first (default 100) */
+    maxTasks?: number;
+}
+export interface ProgressConsumerSupportable {
+    /** latest snapshot by task id */
+    get(id: string): ProgressState | undefined;
+    /** every retained snapshot - in first-applied order (seq is per-reporter, not a cross-task sort key) */
+    list(): ProgressState[];
+    /** subscribe to applied changes (stale drops are not notified) */
+    onChange(handler: (event: ProgressChangeEvent) => void): SocketUnsubscribe;
+    /** unsubscribe. the network stays open (shared socket) */
+    close(): void;
+}
+/** create a server-side progress reporter over an injected sink */
+export declare const createProgressReporter: (sink: ProgressSink, options?: ProgressReporterOptions) => ProgressReporterSupportable;
+/** create a client-side progress consumer on a shared network */
+export declare const createProgressConsumer: (network: NetworkSupportable, options?: ProgressConsumerOptions) => ProgressConsumerSupportable;

package/dist/progress/progress.js

@@ -0,0 +1,263 @@
+"use strict";
+var __rest = (this && this.__rest) || function (s, e) {
+    var t = {};
+    for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p) && e.indexOf(p) < 0)
+        t[p] = s[p];
+    if (s != null && typeof Object.getOwnPropertySymbols === "function")
+        for (var i = 0, p = Object.getOwnPropertySymbols(s); i < p.length; i++) {
+            if (e.indexOf(p[i]) < 0 && Object.prototype.propertyIsEnumerable.call(s, p[i]))
+                t[p[i]] = s[p[i]];
+        }
+    return t;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createProgressConsumer = exports.createProgressReporter = exports.createBufferProgressGauge = exports.createTimeProgressGauge = exports.DEFAULT_MAX_PACKET_BYTES = void 0;
+const websocket_1 = require("../socket/websocket");
+/** default serialized packet size limit (same family as `src/socket`) */
+exports.DEFAULT_MAX_PACKET_BYTES = 64 * 1024;
+/** time-flow gauge - elapsed ratio against expectedMs, capped at 99% (only done() declares completion) */
+const createTimeProgressGauge = (expectedMs, now = Date.now) => {
+    const startedAt = now();
+    return () => {
+        if (!(expectedMs > 0))
+            return { percent: 99 };
+        const percent = Math.floor(((now() - startedAt) / expectedMs) * 100);
+        return { percent: Math.min(99, Math.max(0, percent)) };
+    };
+};
+exports.createTimeProgressGauge = createTimeProgressGauge;
+/** buffer-fill gauge - reads percent/bufferPercent from a GenAIStreamProgress-compatible source (structural type, no src/buffer dependency) */
+const createBufferProgressGauge = (source) => {
+    return () => {
+        var _a;
+        const snapshot = source();
+        const percent = (_a = snapshot === null || snapshot === void 0 ? void 0 : snapshot.percent) !== null && _a !== void 0 ? _a : snapshot === null || snapshot === void 0 ? void 0 : snapshot.bufferPercent;
+        return percent === undefined ? {} : { percent };
+    };
+};
+exports.createBufferProgressGauge = createBufferProgressGauge;
+const GAUGE_KEYS = ['percent', 'step', 'totalSteps', 'label'];
+const textEncoder = new TextEncoder();
+const byteLength = (value) => textEncoder.encode(value).length;
+/** assign only defined values so a partial patch never erases fields */
+const assignDefined = (target, patch) => {
+    if (!patch)
+        return;
+    for (const key of Object.keys(patch)) {
+        if (patch[key] !== undefined)
+            target[key] = patch[key];
+    }
+};
+/** create a server-side progress reporter over an injected sink */
+const createProgressReporter = (sink, options) => {
+    var _a, _b, _c, _d;
+    const type = (_a = options === null || options === void 0 ? void 0 : options.type) !== null && _a !== void 0 ? _a : 'progress:update';
+    const throttleMs = (_b = options === null || options === void 0 ? void 0 : options.throttleMs) !== null && _b !== void 0 ? _b : 0;
+    const heartbeatMs = (_c = options === null || options === void 0 ? void 0 : options.heartbeatMs) !== null && _c !== void 0 ? _c : 0;
+    const maxPacketBytes = (_d = options === null || options === void 0 ? void 0 : options.maxPacketBytes) !== null && _d !== void 0 ? _d : exports.DEFAULT_MAX_PACKET_BYTES;
+    const tasks = new Map();
+    let seq = 0;
+    let mid = 0;
+    const notifyError = (error, state) => { var _a; return (_a = options === null || options === void 0 ? void 0 : options.onError) === null || _a === void 0 ? void 0 : _a.call(options, error, state); };
+    /** the reporter never interrupts task code: sink throw/reject only reaches onError */
+    const dispatch = (message) => {
+        try {
+            const result = sink(message);
+            if (result && typeof result.then === 'function') {
+                result.then(undefined, error => notifyError(error, message.data));
+            }
+        }
+        catch (error) {
+            notifyError(error, message.data);
+        }
+    };
+    const emit = (task) => {
+        task.dirty = false;
+        const snapshot = Object.assign(Object.assign({}, task.local), { ts: Date.now(), seq: ++seq });
+        if (task.gauge) {
+            try {
+                const measure = task.gauge();
+                for (const key of GAUGE_KEYS) {
+                    if (snapshot[key] === undefined && measure[key] !== undefined)
+                        snapshot[key] = measure[key];
+                }
+            }
+            catch (error) {
+                notifyError(error, snapshot);
+            }
+        }
+        let message = { type, data: snapshot, mid: `p${++mid}` };
+        if (snapshot.meta !== undefined && byteLength(JSON.stringify(message)) > maxPacketBytes) {
+            const { meta: _meta } = snapshot, stripped = __rest(snapshot, ["meta"]);
+            message = Object.assign(Object.assign({}, message), { data: stripped });
+            notifyError(new Error(`progress packet exceeds maxPacketBytes:${maxPacketBytes}`), snapshot);
+        }
+        task.last = message.data;
+        dispatch(message);
+    };
+    /** trailing edge: emit the latest snapshot once per window while updates keep arriving */
+    const openWindow = (task) => {
+        task.timer = setTimeout(() => {
+            task.timer = undefined;
+            if (!task.dirty || task.closed)
+                return;
+            emit(task);
+            openWindow(task);
+        }, throttleMs);
+    };
+    const cancelWindow = (task) => {
+        if (!task.timer)
+            return;
+        clearTimeout(task.timer);
+        task.timer = undefined;
+    };
+    const finish = (task, status, patch) => {
+        if (task.closed)
+            return;
+        task.closed = true;
+        cancelWindow(task);
+        assignDefined(task.local, patch);
+        task.local.status = status;
+        emit(task);
+    };
+    const heartbeatTimer = heartbeatMs > 0
+        ? setInterval(() => {
+            tasks.forEach(task => {
+                if (!task.closed && task.local.status === 'running')
+                    emit(task);
+            });
+        }, heartbeatMs)
+        : undefined;
+    return {
+        start: (id, initial, taskOptions) => {
+            const existing = tasks.get(id);
+            if (existing)
+                return existing.handle;
+            const local = { id, status: 'pending', ts: 0, seq: 0 };
+            assignDefined(local, initial);
+            const task = {
+                local,
+                last: local,
+                gauge: taskOptions === null || taskOptions === void 0 ? void 0 : taskOptions.gauge,
+                dirty: false,
+                closed: false,
+                handle: {
+                    id,
+                    get state() {
+                        return task.last;
+                    },
+                    update: patch => {
+                        if (task.closed)
+                            return;
+                        const _a = patch !== null && patch !== void 0 ? patch : {}, { status } = _a, rest = __rest(_a, ["status"]);
+                        if (status && !(status === 'pending' && task.local.status === 'running')) {
+                            task.local.status = status;
+                        }
+                        assignDefined(task.local, rest);
+                        if (throttleMs <= 0)
+                            return emit(task);
+                        if (task.timer) {
+                            task.dirty = true;
+                            return;
+                        }
+                        emit(task);
+                        openWindow(task);
+                    },
+                    done: patch => finish(task, 'done', patch),
+                    error: (error, patch) => {
+                        var _a;
+                        task.local.error = typeof error === 'string' ? error : `${(_a = error === null || error === void 0 ? void 0 : error.message) !== null && _a !== void 0 ? _a : error}`;
+                        finish(task, 'error', patch);
+                    },
+                },
+            };
+            tasks.set(id, task);
+            emit(task);
+            return task.handle;
+        },
+        close: () => {
+            if (heartbeatTimer)
+                clearInterval(heartbeatTimer);
+            tasks.forEach(task => {
+                cancelWindow(task);
+                if (task.dirty && !task.closed)
+                    emit(task);
+            });
+        },
+    };
+};
+exports.createProgressReporter = createProgressReporter;
+/** create a client-side progress consumer on a shared network */
+const createProgressConsumer = (network, options) => {
+    var _a, _b;
+    const typePrefix = (_a = options === null || options === void 0 ? void 0 : options.typePrefix) !== null && _a !== void 0 ? _a : 'progress:';
+    const maxTasks = Math.max(1, (_b = options === null || options === void 0 ? void 0 : options.maxTasks) !== null && _b !== void 0 ? _b : 100);
+    const rawKey = `"type":"${typePrefix}`;
+    /** two-stage filter: raw substring check (no parse) then parsed type re-check */
+    const filtered = (0, websocket_1.createFilteredNetwork)(network, raw => raw.includes(rawKey));
+    const store = new Map();
+    const handlers = new Set();
+    const evict = (keepId) => {
+        if (store.size <= maxTasks)
+            return;
+        let evictId;
+        for (const [id, state] of store) {
+            if (id !== keepId && (state.status === 'done' || state.status === 'error')) {
+                evictId = id;
+                break;
+            }
+        }
+        if (evictId === undefined) {
+            for (const id of store.keys()) {
+                if (id !== keepId) {
+                    evictId = id;
+                    break;
+                }
+            }
+        }
+        if (evictId !== undefined)
+            store.delete(evictId);
+    };
+    const unsubscribe = filtered.onMessage(raw => {
+        let message;
+        try {
+            message = JSON.parse(raw);
+        }
+        catch (_a) {
+            return;
+        }
+        if (typeof (message === null || message === void 0 ? void 0 : message.type) !== 'string' || !message.type.startsWith(typePrefix))
+            return;
+        const state = message.data;
+        if (!state || typeof state.id !== 'string' || typeof state.seq !== 'number')
+            return;
+        const existing = store.get(state.id);
+        if (existing && state.seq <= existing.seq)
+            return;
+        store.set(state.id, state);
+        if (!existing)
+            evict(state.id);
+        for (const handler of [...handlers]) {
+            try {
+                handler({ state, created: !existing });
+            }
+            catch (_b) {
+                // a subscriber error must not break other subscribers or the shared network
+            }
+        }
+    });
+    return {
+        get: id => store.get(id),
+        list: () => [...store.values()],
+        onChange: handler => {
+            handlers.add(handler);
+            return () => handlers.delete(handler);
+        },
+        close: () => {
+            unsubscribe();
+            handlers.clear();
+        },
+    };
+};
+exports.createProgressConsumer = createProgressConsumer;
+//# sourceMappingURL=progress.js.map

package/dist/progress/progress.js.map

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

package/dist/progress/testing.d.ts

@@ -0,0 +1,33 @@
+import { SocketNetworkOptions } from '../socket/types';
+import { ProgressConsumerOptions, ProgressReporterOptions, ProgressState } from './progress';
+export interface ProgressLoopOptions {
+    /** update patch sequence to replay (start -> patches -> done/error). patch.id selects the task (default 'task') */
+    script: Array<Partial<ProgressState>>;
+    reporterOptions?: ProgressReporterOptions;
+    consumerOptions?: ProgressConsumerOptions;
+    /** in-memory network conditions (unordered, jitterMs, maxPacketBytes, ...) */
+    networkOptions?: SocketNetworkOptions & {
+        id?: string;
+    };
+    /** wait time for async packet delivery */
+    settleMs?: number;
+}
+export interface ProgressLoopMetrics {
+    elapsedMs: number;
+    /** raw packet count / total bytes / largest packet bytes (throttle / packet-limit checks) */
+    packets: number;
+    packetBytes: number;
+    maxPacketBytes: number;
+    /** snapshots emitted by the reporter (throttle suppression check) */
+    emitted: number;
+    /** applied by the consumer / dropped by seq judgement */
+    applied: number;
+    staleDropped: number;
+    /** final consumer states at loop end */
+    finalStates: ProgressState[];
+}
+/**
+ * Run an end-to-end loop: script -> ProgressReporter -> NetworkSupportable -> ProgressConsumer,
+ * and return numeric metrics for assertion (same pattern as `buffer/testing.runGenAIStreamNetworkLoop`).
+ */
+export declare const runProgressLoop: (options: ProgressLoopOptions) => Promise<ProgressLoopMetrics>;

package/dist/progress/testing.js

@@ -0,0 +1,102 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __rest = (this && this.__rest) || function (s, e) {
+    var t = {};
+    for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p) && e.indexOf(p) < 0)
+        t[p] = s[p];
+    if (s != null && typeof Object.getOwnPropertySymbols === "function")
+        for (var i = 0, p = Object.getOwnPropertySymbols(s); i < p.length; i++) {
+            if (e.indexOf(p[i]) < 0 && Object.prototype.propertyIsEnumerable.call(s, p[i]))
+                t[p[i]] = s[p[i]];
+        }
+    return t;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runProgressLoop = void 0;
+/**
+ * `progress/testing.ts`
+ * - isolated entry for the progress end-to-end loop harness.
+ * - kept OUT of the package root barrel so production bundles do not include the in-memory socket simulator.
+ *
+ * Usage (tests / dev only):
+ *   import { runProgressLoop } from 'lemon-model/progress/testing';
+ *
+ * @copyright (C) 2026 LemonCloud Co Ltd. - All Rights Reserved.
+ */
+const socket_1 = require("../socket/socket");
+const progress_1 = require("./progress");
+/**
+ * Run an end-to-end loop: script -> ProgressReporter -> NetworkSupportable -> ProgressConsumer,
+ * and return numeric metrics for assertion (same pattern as `buffer/testing.runGenAIStreamNetworkLoop`).
+ */
+const runProgressLoop = (options) => __awaiter(void 0, void 0, void 0, function* () {
+    var _a, _b;
+    const startedAt = Date.now();
+    const network = (0, socket_1.createNetwork)(Object.assign({}, options.networkOptions));
+    const typePrefix = (_b = (_a = options.consumerOptions) === null || _a === void 0 ? void 0 : _a.typePrefix) !== null && _b !== void 0 ? _b : 'progress:';
+    // Keep wire packets so specs can compare emitted, applied, and stale counts.
+    const rawPackets = [];
+    const unsubscribeRaw = network.onMessage(raw => rawPackets.push(raw));
+    const consumer = (0, progress_1.createProgressConsumer)(network, options.consumerOptions);
+    let applied = 0;
+    const unsubscribeChange = consumer.onChange(() => (applied += 1));
+    let emitted = 0;
+    const reporter = (0, progress_1.createProgressReporter)(message => {
+        emitted += 1;
+        network.send(JSON.stringify(message));
+    }, options.reporterOptions);
+    try {
+        const tasks = new Map();
+        // Reuse task handles by id so each script patch models a real task update.
+        const taskOf = (id) => {
+            const existing = tasks.get(id);
+            if (existing)
+                return existing;
+            const started = reporter.start(id);
+            tasks.set(id, started);
+            return started;
+        };
+        for (const patch of options.script) {
+            const { id, ts: _ts, seq: _seq, status, error } = patch, rest = __rest(patch, ["id", "ts", "seq", "status", "error"]);
+            const task = taskOf(id !== null && id !== void 0 ? id : 'task');
+            if (status === 'done')
+                task.done(rest);
+            else if (status === 'error')
+                task.error(error !== null && error !== void 0 ? error : 'error', rest);
+            else
+                task.update(Object.assign(Object.assign({}, rest), { error, status }));
+        }
+        reporter.close();
+        yield new Promise(resolve => { var _a; return setTimeout(resolve, (_a = options.settleMs) !== null && _a !== void 0 ? _a : 50); });
+        // Only matching progress envelopes can become stale drops on a shared network.
+        const arrived = rawPackets.filter(raw => raw.includes(`"type":"${typePrefix}`)).length;
+        return {
+            elapsedMs: Date.now() - startedAt,
+            packets: rawPackets.length,
+            packetBytes: rawPackets.reduce((sum, raw) => sum + byteLength(raw), 0),
+            maxPacketBytes: rawPackets.reduce((max, raw) => Math.max(max, byteLength(raw)), 0),
+            emitted,
+            applied,
+            staleDropped: arrived - applied,
+            finalStates: consumer.list(),
+        };
+    }
+    finally {
+        unsubscribeRaw();
+        unsubscribeChange();
+        consumer.close();
+        network.close();
+    }
+});
+exports.runProgressLoop = runProgressLoop;
+const textEncoder = new TextEncoder();
+const byteLength = (value) => textEncoder.encode(value).length;
+//# sourceMappingURL=testing.js.map