lemon-model 1.2.2 → 1.2.3

package/dist/logtrace/logtrace.js

@@ -0,0 +1,256 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createLogTraceConsumer = exports.createLogTraceReporter = void 0;
+const websocket_1 = require("../socket/websocket");
+const DEFAULT_TYPE = 'log:trace';
+const DEFAULT_TYPE_PREFIX = 'log:';
+const DEFAULT_MIN_LEVEL = 'debug';
+const DEFAULT_FLUSH_COUNT = 20;
+const DEFAULT_FLUSH_INTERVAL_MS = 250;
+const DEFAULT_MAX_PACKET_BYTES = 64 * 1024;
+const DEFAULT_MAX_ENTRIES = 1000;
+const LEVEL_WEIGHT = { debug: 0, info: 1, warn: 2, error: 3 };
+/** create a batching log reporter over an injected send path */
+const createLogTraceReporter = (sink, options) => new LogTraceReporter(sink, options);
+exports.createLogTraceReporter = createLogTraceReporter;
+/** create a log consumer over a shared raw string network */
+const createLogTraceConsumer = (network, options) => new LogTraceConsumer(network, options);
+exports.createLogTraceConsumer = createLogTraceConsumer;
+/** server-side log reporter - batches entries and emits SocketMessage<LogTraceBatch> via the sink */
+class LogTraceReporter {
+    constructor(sink, options) {
+        var _a, _b, _c, _d, _e, _f, _g;
+        this.buffer = [];
+        this.bufferBytes = 0;
+        this.seqNo = 0;
+        this.midNo = 0;
+        this.sentOnce = false;
+        this.closed = false;
+        const maxPacketBytes = (_a = options === null || options === void 0 ? void 0 : options.maxPacketBytes) !== null && _a !== void 0 ? _a : DEFAULT_MAX_PACKET_BYTES;
+        this.sink = sink;
+        this.type = (_b = options === null || options === void 0 ? void 0 : options.type) !== null && _b !== void 0 ? _b : DEFAULT_TYPE;
+        this.source = (_c = options === null || options === void 0 ? void 0 : options.source) !== null && _c !== void 0 ? _c : nextRandomSource();
+        this.minLevel = LEVEL_WEIGHT[(_d = options === null || options === void 0 ? void 0 : options.minLevel) !== null && _d !== void 0 ? _d : DEFAULT_MIN_LEVEL];
+        this.flushCount = (_e = options === null || options === void 0 ? void 0 : options.flushCount) !== null && _e !== void 0 ? _e : DEFAULT_FLUSH_COUNT;
+        this.flushIntervalMs = (_f = options === null || options === void 0 ? void 0 : options.flushIntervalMs) !== null && _f !== void 0 ? _f : DEFAULT_FLUSH_INTERVAL_MS;
+        this.maxBatchBytes = (_g = options === null || options === void 0 ? void 0 : options.maxBatchBytes) !== null && _g !== void 0 ? _g : Math.floor((maxPacketBytes * 3) / 4);
+        this.onError = options === null || options === void 0 ? void 0 : options.onError;
+    }
+    /** record one log entry. auto-flushes when a flush condition is reached */
+    log(level, message, json) {
+        if (this.closed)
+            return;
+        //! seq is issued only past this gate so a raised minLevel never creates seq gaps.
+        if (LEVEL_WEIGHT[level] < this.minLevel)
+            return;
+        const entry = { level, ts: Date.now(), message, seq: ++this.seqNo };
+        if (json !== undefined)
+            entry.json = json;
+        let bytes = byteLength(JSON.stringify(entry));
+        if (bytes > this.maxBatchBytes)
+            bytes = this.truncate(entry, bytes);
+        //! adding this entry would exceed the batch budget: flush the current buffer, start a new batch.
+        if (this.buffer.length > 0 && this.bufferBytes + bytes + 1 > this.maxBatchBytes)
+            this.flush();
+        this.buffer.push(entry);
+        this.bufferBytes += bytes + 1;
+        if (level === 'error' || this.buffer.length >= this.flushCount)
+            return this.flush();
+        if (this.flushIntervalMs <= 0)
+            return;
+        //! leading edge: the first batch of this reporter flushes immediately so the viewer never waits a window.
+        if (!this.sentOnce)
+            return this.flush();
+        if (!this.timer)
+            this.timer = setTimeout(() => this.flush(), this.flushIntervalMs);
+    }
+    debug(message, json) {
+        this.log('debug', message, json);
+    }
+    info(message, json) {
+        this.log('info', message, json);
+    }
+    warn(message, json) {
+        this.log('warn', message, json);
+    }
+    error(message, json) {
+        this.log('error', message, json);
+    }
+    /** send the buffered entries now */
+    flush() {
+        this.clearTimer();
+        if (this.buffer.length <= 0)
+            return;
+        const entries = this.buffer;
+        this.buffer = [];
+        this.bufferBytes = 0;
+        this.sentOnce = true;
+        const message = {
+            type: this.type,
+            data: { entries, source: this.source },
+            mid: `l${++this.midNo}`,
+        };
+        //! at-most-once: a failed batch is reported to onError and dropped. never breaks the caller.
+        try {
+            const result = this.sink(message);
+            if (result && typeof result.then === 'function')
+                result.catch(e => this.emitError(e, entries));
+        }
+        catch (e) {
+            this.emitError(e, entries);
+        }
+    }
+    /** flush + release the timer. later log calls are ignored */
+    close() {
+        this.flush();
+        this.closed = true;
+    }
+    /** fit an oversized entry into the batch budget: drop json first, then cut the message */
+    truncate(entry, bytes) {
+        const error = new Error(`@entry[${entry.seq}] exceeds batch budget(${this.maxBatchBytes}) - logtrace.truncate`);
+        entry.truncated = true;
+        if (entry.json !== undefined) {
+            delete entry.json;
+            bytes = byteLength(JSON.stringify(entry));
+        }
+        //! every removed character frees at least 1 byte, so this loop converges quickly.
+        while (bytes > this.maxBatchBytes && entry.message.length > 0) {
+            entry.message = entry.message.slice(0, Math.max(0, entry.message.length - (bytes - this.maxBatchBytes)));
+            bytes = byteLength(JSON.stringify(entry));
+        }
+        this.emitError(error, [entry]);
+        return bytes;
+    }
+    emitError(error, entries) {
+        var _a;
+        try {
+            (_a = this.onError) === null || _a === void 0 ? void 0 : _a.call(this, error, entries);
+        }
+        catch (_b) {
+            // The error observer must never break the reporter.
+        }
+    }
+    clearTimer() {
+        if (!this.timer)
+            return;
+        clearTimeout(this.timer);
+        this.timer = undefined;
+    }
+}
+/** client-side log consumer - unpacks batches into a (ts, seq)-sorted ring buffer */
+class LogTraceConsumer {
+    constructor(network, options) {
+        var _a, _b, _c;
+        this.handlers = new Set();
+        this.sources = new Map();
+        this.entries = [];
+        this.typePrefix = (_a = options === null || options === void 0 ? void 0 : options.typePrefix) !== null && _a !== void 0 ? _a : DEFAULT_TYPE_PREFIX;
+        this.minLevel = LEVEL_WEIGHT[(_b = options === null || options === void 0 ? void 0 : options.minLevel) !== null && _b !== void 0 ? _b : DEFAULT_MIN_LEVEL];
+        this.maxEntries = (_c = options === null || options === void 0 ? void 0 : options.maxEntries) !== null && _c !== void 0 ? _c : DEFAULT_MAX_ENTRIES;
+        //! raw stage of the 2-stage filter: substring check without parsing.
+        const marker = `"type":"${this.typePrefix}`;
+        const filtered = (0, websocket_1.createFilteredNetwork)(network, raw => raw.includes(marker));
+        this.unsubscribe = filtered.onMessage(raw => this.receive(raw));
+    }
+    /** subscribe to received entries */
+    onEntry(handler) {
+        this.handlers.add(handler);
+        return () => {
+            this.handlers.delete(handler);
+        };
+    }
+    /** list retained entries in (ts, seq) ascending order */
+    list(query) {
+        var _a;
+        const min = LEVEL_WEIGHT[(_a = query === null || query === void 0 ? void 0 : query.minLevel) !== null && _a !== void 0 ? _a : DEFAULT_MIN_LEVEL];
+        let listed = min > 0 ? this.entries.filter(entry => LEVEL_WEIGHT[entry.level] >= min) : [...this.entries];
+        const limit = query === null || query === void 0 ? void 0 : query.limit;
+        if (limit !== undefined && limit >= 0 && listed.length > limit)
+            listed = listed.slice(listed.length - limit);
+        return listed;
+    }
+    /** observed wire loss - sum of (max seq - received count) per source */
+    get gapCount() {
+        let gaps = 0;
+        for (const state of this.sources.values())
+            gaps += Math.max(0, state.maxSeq - state.seen.size);
+        return gaps;
+    }
+    /** drop retained entries (subscriptions and loss accounting stay) */
+    clear() {
+        this.entries = [];
+    }
+    /** unsubscribe from the network. does NOT close the network (shared socket) */
+    close() {
+        this.unsubscribe();
+        this.handlers.clear();
+    }
+    receive(raw) {
+        let message;
+        try {
+            message = JSON.parse(raw);
+        }
+        catch (_a) {
+            return; // the raw substring filter is best-effort; a non-JSON hit is simply not ours.
+        }
+        if (!message || typeof message.type !== 'string' || !message.type.startsWith(this.typePrefix))
+            return;
+        const batch = message.data;
+        if (!batch || typeof batch.source !== 'string' || !Array.isArray(batch.entries))
+            return;
+        const state = this.stateOf(batch.source);
+        for (const entry of batch.entries) {
+            if (!isLogTraceEntry(entry))
+                continue;
+            //! dedup + loss accounting happen BEFORE the minLevel gate so gapCount stays a pure wire-loss metric.
+            if (state.seen.has(entry.seq))
+                continue;
+            state.seen.add(entry.seq);
+            if (entry.seq > state.maxSeq)
+                state.maxSeq = entry.seq;
+            if (LEVEL_WEIGHT[entry.level] < this.minLevel)
+                continue;
+            const accepted = Object.assign(Object.assign({}, entry), { source: batch.source });
+            this.store(accepted);
+            for (const handler of [...this.handlers])
+                handler(accepted);
+        }
+    }
+    /** binary-insert by (ts, seq) so list() never re-sorts; evict the oldest on overflow */
+    store(entry) {
+        let lo = 0;
+        let hi = this.entries.length;
+        while (lo < hi) {
+            const mid = (lo + hi) >> 1;
+            if (compareEntry(this.entries[mid], entry) <= 0)
+                lo = mid + 1;
+            else
+                hi = mid;
+        }
+        this.entries.splice(lo, 0, entry);
+        if (this.entries.length > this.maxEntries)
+            this.entries.shift();
+    }
+    stateOf(source) {
+        let state = this.sources.get(source);
+        if (!state) {
+            // ponytail: the per-source seen Set grows with log volume; swap to seq-range tracking if sessions get huge.
+            state = { maxSeq: 0, seen: new Set() };
+            this.sources.set(source, state);
+        }
+        return state;
+    }
+}
+let sourceNo = 0;
+const nextRandomSource = () => `src-${Math.random().toString(36).slice(2, 8)}${++sourceNo}`;
+const compareEntry = (a, b) => a.ts - b.ts || a.seq - b.seq;
+const isLogTraceEntry = (entry) => !!entry &&
+    typeof entry === 'object' &&
+    LEVEL_WEIGHT[entry.level] !== undefined &&
+    typeof entry.ts === 'number' &&
+    typeof entry.message === 'string' &&
+    Number.isInteger(entry.seq) &&
+    entry.seq > 0;
+const textEncoder = new TextEncoder();
+const byteLength = (value) => textEncoder.encode(value).length;
+//# sourceMappingURL=logtrace.js.map

package/dist/logtrace/logtrace.js.map

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

package/dist/logtrace/testing.d.ts

@@ -0,0 +1,40 @@
+import { SocketNetworkOptions } from '../socket/types';
+import { LogTraceConsumerOptions, LogTraceEntry, LogTraceLevel, LogTraceReporterOptions } from './logtrace';
+export interface LogTraceLoopOptions {
+    /** log sequence to replay */
+    entries: Array<{
+        level: LogTraceLevel;
+        message: string;
+        json?: Record<string, any>;
+    }>;
+    reporterOptions?: LogTraceReporterOptions;
+    consumerOptions?: LogTraceConsumerOptions;
+    /** in-memory network conditions (unordered, jitterMs, maxPacketBytes, ...) */
+    networkOptions?: SocketNetworkOptions & {
+        id?: string;
+    };
+    /** wait time for async delivery */
+    settleMs?: number;
+}
+export interface LogTraceLoopMetrics {
+    elapsedMs: number;
+    /** raw packet count / total bytes / largest packet bytes (batching efficiency + packet limit checks) */
+    packets: number;
+    packetBytes: number;
+    maxPacketBytes: number;
+    /** emitted batch count (flush 3-axis checks) */
+    batches: number;
+    /** entries reaching the consumer / truncated entries / observed seq gaps */
+    delivered: number;
+    truncated: number;
+    gapCount: number;
+    /** consumer retention at the end ((ts, seq) sorted) */
+    finalEntries: LogTraceEntry[];
+}
+/**
+ * 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.
+ */
+export declare const runLogTraceLoop: (options: LogTraceLoopOptions) => Promise<LogTraceLoopMetrics>;

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;