apm-optima 1.0.4 → 2.0.0

package/dist/core/storage/utility/common.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.tryOrDefault = tryOrDefault;
+async function tryOrDefault(fn, fallback) {
+    try {
+        return await fn();
+    }
+    catch {
+        return fallback;
+    }
+}

package/dist/core/storage/utility/file-buffer.d.ts

@@ -0,0 +1,31 @@
+export interface StoredRecord<T = unknown> {
+    id: string;
+    createdAt: string;
+    schemaVersion: number;
+    category: string;
+    payload: T;
+}
+export interface WriteOptions {
+    schemaVersion?: number;
+    id?: string;
+}
+export interface PathAttrs {
+    baseDir: string;
+    category: string;
+    date?: Date;
+}
+export declare function constructFilePath(attrs: PathAttrs): string;
+export declare function dataToBuffer(data: unknown): Buffer;
+export declare function writeToFileBuffer(filePath: string, data: Buffer): void;
+export declare function wrapRecord<T>(category: string, payload: T, options?: WriteOptions): StoredRecord<T>;
+export declare function appendRecords<T>(filePath: string, category: string, payloads: T[], options?: WriteOptions): StoredRecord<T>[];
+export declare function appendRecordsAsync<T>(filePath: string, category: string, payloads: T[], options?: WriteOptions): Promise<StoredRecord<T>[]>;
+export declare function readRecords<T = unknown>(filePath: string): AsyncGenerator<StoredRecord<T>>;
+export declare function readAllRecords<T = unknown>(filePath: string): Promise<StoredRecord<T>[]>;
+export declare function writeNDJSONAtomic<T>(filePath: string, records: StoredRecord<T>[]): Promise<void>;
+export declare function writeJSONAtomic<T>(filePath: string, data: unknown): Promise<void>;
+export declare function readJSON<T>(filePath: string): Promise<T>;
+export declare function writeChecksum(filePath: string): Promise<string>;
+export declare function verifyChecksum(filePath: string): Promise<boolean>;
+export declare function archiveFile(filePath: string, deleteOriginal?: boolean): Promise<string>;
+export declare function cleanupOrphanedTempFiles(baseDir: string): Promise<number>;

package/dist/core/storage/utility/file-buffer.js

@@ -0,0 +1,238 @@
+"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 __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.constructFilePath = constructFilePath;
+exports.dataToBuffer = dataToBuffer;
+exports.writeToFileBuffer = writeToFileBuffer;
+exports.wrapRecord = wrapRecord;
+exports.appendRecords = appendRecords;
+exports.appendRecordsAsync = appendRecordsAsync;
+exports.readRecords = readRecords;
+exports.readAllRecords = readAllRecords;
+exports.writeNDJSONAtomic = writeNDJSONAtomic;
+exports.writeJSONAtomic = writeJSONAtomic;
+exports.readJSON = readJSON;
+exports.writeChecksum = writeChecksum;
+exports.verifyChecksum = verifyChecksum;
+exports.archiveFile = archiveFile;
+exports.cleanupOrphanedTempFiles = cleanupOrphanedTempFiles;
+const fs = __importStar(require("fs"));
+const fsp = __importStar(require("fs/promises"));
+const path = __importStar(require("path"));
+const zlib = __importStar(require("zlib"));
+const crypto = __importStar(require("crypto"));
+const readline = __importStar(require("readline"));
+const crypto_1 = require("crypto");
+const logger_1 = __importDefault(require("../../telemetry/logger"));
+function constructFilePath(attrs) {
+    const { baseDir, category } = attrs;
+    const date = attrs.date ?? new Date();
+    const safeCategory = sanitizeSegment(category);
+    const dateStr = date.toISOString().slice(0, 10);
+    const dir = path.join(baseDir, safeCategory);
+    fs.mkdirSync(dir, { recursive: true });
+    return path.join(dir, `${dateStr}.ndjson`);
+}
+function sanitizeSegment(segment) {
+    const cleaned = segment.trim().replace(/[^a-zA-Z0-9_\-]/g, '_');
+    if (!cleaned)
+        throw new Error(`Invalid path segment: "${segment}"`);
+    return cleaned;
+}
+function dataToBuffer(data) {
+    if (Buffer.isBuffer(data)) {
+        return data;
+    }
+    else if (typeof data === 'string') {
+        return Buffer.from(data, 'utf8');
+    }
+    else if (data !== null && typeof data === 'object') {
+        return Buffer.from(JSON.stringify(data), 'utf8');
+    }
+    else {
+        throw new Error(`Invalid data type: ${typeof data}`);
+    }
+}
+function writeToFileBuffer(filePath, data) {
+    fs.writeFileSync(filePath, data);
+}
+function wrapRecord(category, payload, options = {}) {
+    return {
+        id: options.id ?? (0, crypto_1.randomUUID)(),
+        createdAt: new Date().toISOString(),
+        schemaVersion: options.schemaVersion ?? 1,
+        category,
+        payload,
+    };
+}
+function appendRecords(filePath, category, payloads, options = {}) {
+    const records = payloads.map(p => wrapRecord(category, p, options));
+    const lines = records.map(r => {
+        try {
+            return JSON.stringify(r);
+        }
+        catch (err) {
+            throw new Error(`Failed to serialize record: ${err}`);
+        }
+    });
+    const chunk = lines.join('\n') + '\n';
+    fs.appendFileSync(filePath, chunk, 'utf8');
+    return records;
+}
+async function appendRecordsAsync(filePath, category, payloads, options = {}) {
+    const records = payloads.map(p => wrapRecord(category, p, options));
+    const chunk = records.map(r => JSON.stringify(r)).join('\n') + '\n';
+    await fsp.appendFile(filePath, chunk, 'utf8');
+    return records;
+}
+async function* readRecords(filePath) {
+    const isGz = filePath.endsWith('.gz');
+    const rawStream = fs.createReadStream(filePath);
+    const stream = isGz ? rawStream.pipe(zlib.createGunzip()) : rawStream;
+    const rl = readline.createInterface({ input: stream, crlfDelay: Infinity });
+    let lineNumber = 0;
+    for await (const line of rl) {
+        lineNumber++;
+        if (!line.trim())
+            continue;
+        try {
+            yield JSON.parse(line);
+        }
+        catch (err) {
+            logger_1.default.error('Failed to parse line', lineNumber, 'in file', filePath, ':', err);
+        }
+    }
+}
+async function readAllRecords(filePath) {
+    const out = [];
+    for await (const record of readRecords(filePath)) {
+        out.push(record);
+    }
+    return out;
+}
+async function writeNDJSONAtomic(filePath, records) {
+    const dir = path.dirname(filePath);
+    const tmpPath = path.join(dir, `.${path.basename(filePath)}.${process.pid}.${(0, crypto_1.randomUUID)()}.tmp`);
+    const content = records.map((r) => JSON.stringify(r)).join('\n') + (records.length ? '\n' : '');
+    const handle = await fsp.open(tmpPath, 'w');
+    try {
+        await handle.writeFile(content, 'utf8');
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+    await fsp.rename(tmpPath, filePath);
+}
+async function writeJSONAtomic(filePath, data) {
+    const dir = path.dirname(filePath);
+    const tmpPath = path.join(dir, `.${path.basename(filePath)}.${process.pid}.${(0, crypto_1.randomUUID)()}.tmp`);
+    await fsp.mkdir(dir, { recursive: true });
+    const handle = await fsp.open(tmpPath, "w");
+    try {
+        await handle.writeFile(JSON.stringify(data, null, 2), "utf8");
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+    await fsp.rename(tmpPath, filePath);
+}
+async function readJSON(filePath) {
+    const content = await fsp.readFile(filePath, 'utf8');
+    return JSON.parse(content);
+}
+async function writeChecksum(filePath) {
+    const hash = crypto.createHash('sha256');
+    const stream = fs.createReadStream(filePath);
+    for await (const chunk of stream)
+        hash.update(chunk);
+    const digest = hash.digest('hex');
+    await fsp.writeFile(`${filePath}.sha256`, `${digest}  ${path.basename(filePath)}\n`, 'utf8');
+    return digest;
+}
+async function verifyChecksum(filePath) {
+    const sidecarPath = `${filePath}.sha256`;
+    const expected = (await fsp.readFile(sidecarPath, 'utf8')).split(/\s+/)[0];
+    const hash = crypto.createHash('sha256');
+    const stream = fs.createReadStream(filePath);
+    for await (const chunk of stream)
+        hash.update(chunk);
+    const actual = hash.digest('hex');
+    return actual === expected;
+}
+async function archiveFile(filePath, deleteOriginal = false) {
+    const gzPath = `${filePath}.gz`;
+    await new Promise((resolve, reject) => {
+        const source = fs.createReadStream(filePath);
+        const dest = fs.createWriteStream(gzPath);
+        const gzip = zlib.createGzip({ level: zlib.constants.Z_BEST_COMPRESSION });
+        source.pipe(gzip).pipe(dest);
+        dest.on('finish', () => resolve());
+        dest.on('error', (err) => reject(err));
+        source.on('error', (err) => reject(err));
+    });
+    await writeChecksum(gzPath);
+    if (deleteOriginal) {
+        await fsp.unlink(filePath);
+        await fsp.rm(`${filePath}.sha256`, { force: true });
+    }
+    return gzPath;
+}
+async function cleanupOrphanedTempFiles(baseDir) {
+    if (!fs.existsSync(baseDir)) {
+        logger_1.default.debug(`Base directory does not exist: ${baseDir}`);
+        return 0;
+    }
+    const files = await fsp.readdir(baseDir);
+    let removedCount = 0;
+    for (const file of files) {
+        if (file.startsWith('.') && file.includes('.tmp')) {
+            const fullPath = path.join(baseDir, file);
+            try {
+                await fsp.unlink(fullPath);
+                removedCount++;
+                logger_1.default.debug(`Removed orphaned temp file: ${fullPath}`);
+            }
+            catch (err) {
+                logger_1.default.error(`Failed to remove orphaned temp file: ${fullPath}`, err);
+            }
+        }
+    }
+    return removedCount;
+}

package/dist/core/storage/utility/histogram.d.ts

@@ -19,8 +19,7 @@ export declare class Histogram {
     private totalSum;
     private totalSumOfSquares;
     private anomalyCount;
-    constructor(anomalySampleSize?: number, //! For this use calculation
-    anomalyLowerLimit?: number);
+    constructor(anomalySampleSize?: number, anomalyLowerLimit?: number);
     record(durationMs: number): RecordStatus;
     snapshot(): HistogramSnapshot;
     private percentile;

package/dist/core/storage/utility/histogram.js

@@ -17,8 +17,7 @@ class Histogram {
     totalSum = 0;
     totalSumOfSquares = 0;
     anomalyCount = 0;
-    constructor(anomalySampleSize = 60, //! For this use calculation
-    anomalyLowerLimit = 180) {
+    constructor(anomalySampleSize = 60, anomalyLowerLimit = 180) {
         this.anomalySampleSize = anomalySampleSize;
         this.anomalyLowerLimit = anomalyLowerLimit;
         this.counters = new Uint32Array(this.limits.length);

package/dist/core/storage/utility/index.d.ts

@@ -1,2 +1,4 @@
 export * from './histogram';
 export * from './ring-buffer';
+export * from './common';
+export * from './file-buffer';

package/dist/core/storage/utility/index.js

@@ -16,3 +16,5 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./histogram"), exports);
 __exportStar(require("./ring-buffer"), exports);
+__exportStar(require("./common"), exports);
+__exportStar(require("./file-buffer"), exports);

package/dist/core/storage/utility/persistence-files.d.ts

@@ -0,0 +1,3 @@
+export type PersistenceCategory = 'http_requests' | 'system_health' | 'events' | 'correlation';
+export declare function resolveExistingFile(baseDir: string, category: PersistenceCategory, date: string): Promise<string | null>;
+export declare function archiveOldPersistenceFiles(baseDir: string, category: PersistenceCategory): Promise<void>;

package/dist/core/storage/utility/persistence-files.js

@@ -0,0 +1,34 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveExistingFile = resolveExistingFile;
+exports.archiveOldPersistenceFiles = archiveOldPersistenceFiles;
+const promises_1 = __importDefault(require("fs/promises"));
+const path_1 = __importDefault(require("path"));
+const file_buffer_1 = require("./file-buffer");
+async function resolveExistingFile(baseDir, category, date) {
+    const dir = path_1.default.join(baseDir, category);
+    const plain = path_1.default.join(dir, `${date}.ndjson`);
+    const gz = `${plain}.gz`;
+    if (await promises_1.default.access(plain).then(() => true).catch(() => false))
+        return plain;
+    if (await promises_1.default.access(gz).then(() => true).catch(() => false))
+        return gz;
+    return null;
+}
+async function archiveOldPersistenceFiles(baseDir, category) {
+    const dir = path_1.default.join(baseDir, category);
+    const today = new Date().toISOString().slice(0, 10);
+    const files = await promises_1.default.readdir(dir).catch(() => []);
+    for (const file of files) {
+        if (!file.endsWith('.ndjson'))
+            continue;
+        if (file.startsWith(today))
+            continue;
+        const fullPath = path_1.default.join(dir, file);
+        await (0, file_buffer_1.writeChecksum)(fullPath);
+        await (0, file_buffer_1.archiveFile)(fullPath);
+    }
+}

package/dist/core/storage/utility/persistence-writer.d.ts

@@ -0,0 +1,39 @@
+import { type StoredRecord } from './index';
+import type { PersistenceCategory } from './persistence-files';
+export type StorageStatus = 'OK' | 'DEGRADED';
+export interface WriterOptions {
+    maxQueue?: number;
+    maxRetries?: number;
+    retryDelayMs?: number;
+    onStatusChange?: (status: StorageStatus) => void;
+}
+export interface RecordInput<T> {
+    recordId: string;
+    payload: T;
+}
+export declare class PersistenceWriter {
+    private readonly queue;
+    private runner;
+    private accepting;
+    private readonly maxQueue;
+    private readonly maxRetries;
+    private readonly retryDelayMs;
+    private readonly onStatusChange?;
+    private _status;
+    private _lostRecords;
+    private _commitedSequence;
+    constructor(options?: WriterOptions);
+    get status(): StorageStatus;
+    get lostRecords(): number;
+    get commitedSequence(): number;
+    get pending(): number;
+    enqueueAppend<T>(baseDir: string, category: PersistenceCategory, items: RecordInput<T>[]): Promise<number>;
+    enqueueTask(description: string, task: () => Promise<void>): Promise<number>;
+    whenIdle(): Promise<void>;
+    close(): Promise<void>;
+    private push;
+    private kick;
+    private drain;
+    private markLost;
+}
+export declare function dedupeRecords<T>(source: AsyncIterable<StoredRecord<T>>, onConflict?: (id: string) => void): AsyncGenerator<StoredRecord<T>>;

package/dist/core/storage/utility/persistence-writer.js

@@ -0,0 +1,183 @@
+"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 __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PersistenceWriter = void 0;
+exports.dedupeRecords = dedupeRecords;
+const fsp = __importStar(require("fs/promises"));
+const logger_1 = __importDefault(require("../../telemetry/logger"));
+const index_1 = require("./index");
+const sleep = (ms) => new Promise(r => setTimeout(r, ms));
+class PersistenceWriter {
+    queue = [];
+    runner = null;
+    accepting = true;
+    maxQueue;
+    maxRetries;
+    retryDelayMs;
+    onStatusChange;
+    _status = 'OK';
+    _lostRecords = 0;
+    _commitedSequence = 0;
+    constructor(options = {}) {
+        this.maxQueue = options.maxQueue ?? 1000;
+        this.maxRetries = options.maxRetries ?? 3;
+        this.retryDelayMs = options.retryDelayMs ?? 100;
+        this.onStatusChange = options.onStatusChange;
+    }
+    get status() { return this._status; }
+    get lostRecords() { return this._lostRecords; }
+    get commitedSequence() { return this._commitedSequence; }
+    get pending() { return this.queue.length; }
+    enqueueAppend(baseDir, category, items) {
+        if (items.length === 0)
+            return Promise.resolve(this._commitedSequence);
+        const createdAt = new Date().toISOString();
+        const records = items.map(i => ({
+            id: i.recordId,
+            createdAt,
+            schemaVersion: 1,
+            category,
+            payload: i.payload
+        }));
+        let chunk;
+        try {
+            chunk = records.map(r => JSON.stringify(r)).join('\n') + '\n';
+        }
+        catch (err) {
+            this.markLost(items.length);
+            return Promise.reject(new Error(`Serialization failed for ${category}: ${err}`));
+        }
+        const filePath = (0, index_1.constructFilePath)({ baseDir, category });
+        return this.push({
+            description: `Append ${records.length} records to ${filePath}`,
+            recordCount: items.length,
+            run: async (attempt) => {
+                await fsp.appendFile(filePath, attempt > 0 ? '\n' + chunk : chunk, 'utf-8');
+            },
+        });
+    }
+    enqueueTask(description, task) {
+        return this.push({ description, recordCount: 0, run: () => task() });
+    }
+    async whenIdle() {
+        while (this.runner)
+            await this.runner;
+    }
+    async close() {
+        this.accepting = false;
+        await this.whenIdle();
+    }
+    push(partial) {
+        if (!this.accepting) {
+            this.markLost(partial.recordCount);
+            return Promise.reject(new Error(`Writer closed; rejected: ${partial.description}`));
+        }
+        if (this.queue.length >= this.maxQueue) {
+            this.markLost(partial.recordCount);
+            logger_1.default.error(`PersistenceWriter: queue full (${this.maxQueue}); rejected: ${partial.description}`);
+            return Promise.reject(new Error('Persistence queue full'));
+        }
+        return new Promise((resolve, reject) => {
+            this.queue.push({ ...partial, resolve, reject });
+            this.kick();
+        });
+    }
+    kick() {
+        if (this.runner)
+            return;
+        this.runner = this.drain()
+            .catch(err => logger_1.default.error('PersistenceWriter: unexpected drain error', err))
+            .finally(() => {
+            this.runner = null;
+            if (this.queue.length > 0)
+                this.kick();
+        });
+    }
+    async drain() {
+        while (this.queue.length > 0) {
+            const job = this.queue[0];
+            let lastErr = null;
+            let ok = false;
+            for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
+                try {
+                    await job.run(attempt);
+                    ok = true;
+                    break;
+                }
+                catch (err) {
+                    lastErr = err;
+                    if (attempt < this.maxRetries)
+                        await sleep(this.retryDelayMs * 2 ** attempt);
+                }
+            }
+            this.queue.shift();
+            if (ok) {
+                this._commitedSequence++;
+                job.resolve(this._commitedSequence);
+            }
+            else {
+                this.markLost(job.recordCount);
+                logger_1.default.error(`PersistenceWriter: giving up on "${job.description}":`, lastErr);
+                job.reject(lastErr instanceof Error ? lastErr : new Error(String(lastErr)));
+            }
+        }
+    }
+    markLost(count) {
+        this._lostRecords += count;
+        if (this._status !== 'DEGRADED') {
+            this._status = 'DEGRADED';
+            this.onStatusChange?.(this._status);
+        }
+    }
+}
+exports.PersistenceWriter = PersistenceWriter;
+async function* dedupeRecords(source, onConflict) {
+    const seen = new Map();
+    for await (const record of source) {
+        const fingerprint = JSON.stringify(record.payload);
+        const prev = seen.get(record.id);
+        if (prev === undefined) {
+            seen.set(record.id, fingerprint);
+            yield record;
+        }
+        else if (prev !== fingerprint) {
+            logger_1.default.error(`Record ID conflict: ${record.id}`);
+            onConflict?.(record.id);
+        }
+    }
+}

package/dist/core/storage/utility/session-export.d.ts

@@ -0,0 +1,3 @@
+import { type PersistenceCategory } from "./persistence-files";
+import type { SessionWindow } from "./session-window";
+export declare function streamWriteCategory(out: NodeJS.WritableStream, baseDir: string, category: PersistenceCategory, dates: string[], window: SessionWindow, isLast?: boolean): Promise<void>;

package/dist/core/storage/utility/session-export.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.streamWriteCategory = streamWriteCategory;
+const file_buffer_1 = require("./file-buffer");
+const persistence_files_1 = require("./persistence-files");
+async function streamWriteCategoryRecords(out, baseDir, category, dates, window) {
+    let isFirst = true;
+    const { start: windowStart, end: windowEnd } = window;
+    for (const date of dates) {
+        const filePath = await (0, persistence_files_1.resolveExistingFile)(baseDir, category, date);
+        if (!filePath)
+            continue;
+        for await (const record of (0, file_buffer_1.readRecords)(filePath)) {
+            const ts = new Date(record.createdAt);
+            if (ts < windowStart || ts > windowEnd)
+                continue;
+            if (!isFirst)
+                out.write(',');
+            isFirst = false;
+            const canContinue = out.write(JSON.stringify(record));
+            if (!canContinue) {
+                await new Promise((resolve) => out.once('drain', resolve));
+            }
+        }
+    }
+}
+async function streamWriteCategory(out, baseDir, category, dates, window, isLast = false) {
+    out.write(`"${category}":[`);
+    await streamWriteCategoryRecords(out, baseDir, category, dates, window);
+    out.write(isLast ? ']' : '],');
+}

package/dist/core/storage/utility/session-registry.d.ts

@@ -0,0 +1,21 @@
+import type { SessionRecord } from '../../domain';
+import type { PersistenceWriter } from './persistence-writer';
+export declare class SessionRegistry {
+    private readonly manifestPath;
+    private readonly writer;
+    private manifest;
+    private dirty;
+    private _current;
+    private _recoveredFromCrash;
+    constructor(manifestPath: string, writer: PersistenceWriter);
+    get current(): SessionRecord | null;
+    get all(): readonly SessionRecord[];
+    get recoveredFromCrash(): boolean;
+    start(): Promise<SessionRecord>;
+    notePersisted(): void;
+    heartbeat(): Promise<void>;
+    complete(): Promise<void>;
+    static windowEnd(s: SessionRecord): string | null;
+    private save;
+    private migrate;
+}