logroller 1.0.0 → 2.0.0

package/dist/index.esm.js

@@ -1,20 +1,55 @@
 /*! logroller v1.0.0 | MIT License */
+import { randomUUID } from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
-import zlib from 'node:zlib';
 import { Writable } from 'node:stream';
+import zlib from 'node:zlib';
 import { pipeline } from 'node:stream/promises';
-import { randomUUID } from 'node:crypto';
 
-/* ================================================================
- * Option parsers
- * ================================================================ */
+/** `stat().size` guarded to 0; string paths only. */
+const statSizeSafe = (p) => {
+    try {
+        return typeof p === "string" ? fs.statSync(p).size : 0;
+    }
+    catch {
+        return 0;
+    }
+};
+const existsSafe = (p) => {
+    try {
+        return fs.existsSync(p);
+    }
+    catch {
+        return false;
+    }
+};
+/**
+ * Compress `src` → `dst`, deleting `src` ONLY on verified success.
+ * On failure removes the partial `dst` and reports via callback —
+ * logs degrade to uncompressed rather than losing data.
+ */
+async function gzipMove(src, dst, onWarn) {
+    try {
+        await pipeline(fs.createReadStream(src), zlib.createGzip({ level: 6 }), fs.createWriteStream(dst));
+        await fs.promises.unlink(src);
+        return true;
+    }
+    catch (err) {
+        await fs.promises.unlink(dst).catch(() => { });
+        onWarn?.(err);
+        return false;
+    }
+}
+const endStream = (ws) => ws ? new Promise((resolve) => ws.end(() => resolve())) : Promise.resolve();
+
 const UNITS = {
     b: 1, k: 1024, kb: 1024,
     m: 1048576, mb: 1048576,
     g: 1073741824, gb: 1073741824,
 };
-const FREQ_MULT = { ms: 1, s: 1000, m: 60000, h: 3600000 };
+const FREQ_MULT = {
+    ms: 1, s: 1000, m: 60_000, h: 3_600_000,
+};
 function parseSize(v) {
     if (v === undefined || v === null || v === 0)
         return 0;
@@ -30,57 +65,58 @@ function parseMaxFiles(v) {
         return null;
     if (typeof v === "number")
         return { count: v };
-    let m = /^\s*(\d+)\s*d\s*$/i.exec(v);
+    const m = /^\s*(\d+)\s*d\s*$/i.exec(v);
     if (m)
         return { days: Number.parseInt(m[1], 10) };
-    m = /^\s*(\d+)\s*$/.exec(v);
-    if (m)
-        return { count: Number.parseInt(m[1], 10) };
+    const n = /^\s*(\d+)\s*$/.exec(v);
+    if (n)
+        return { count: Number.parseInt(n[1], 10) };
     throw new Error(`Invalid maxFiles "${v}"`);
 }
 function parseFrequency(v) {
     if (v === undefined || v === null)
-        v = "daily";
+        return { type: "daily" };
     if (v === "daily")
         return { type: "daily" };
-    if (typeof v === "number" && v > 0)
+    if (typeof v === "number") {
+        if (!(v > 0))
+            throw new Error(`Invalid frequency "${v}"`);
         return { type: "interval", ms: v };
-    const m = /^\s*(\d+)\s*(ms|s|m|h)\s*$/i.exec(String(v));
+    }
+    const m = /^\s*(\d+)\s*(ms|s|m|h)\s*$/i.exec(v);
     if (!m)
         throw new Error(`Invalid frequency "${v}"`);
-    const mult = FREQ_MULT[m[2].toLowerCase()] ?? 1; // ◀ TS FIX
-    return { type: "interval", ms: Number.parseInt(m[1], 10) * mult };
+    return { type: "interval", ms: Number.parseInt(m[1], 10) * FREQ_MULT[m[2].toLowerCase()] };
 }
 function parseClockOffset(v) {
     if (v === undefined || v === null || v === "")
         return 0;
     if (typeof v === "number")
-        return Math.round(v * 3600000);
+        return Math.round(v * 3_600_000);
     const m = /^\s*(-?\d+(?:\.\d+)?)\s*h(?:our)?s?\s*$/i.exec(v);
     if (!m)
         throw new Error(`Invalid addHours "${v}"`);
-    return Math.round(Number.parseFloat(m[1]) * 3600000);
+    return Math.round(Number.parseFloat(m[1]) * 3_600_000);
 }
 function parseClockStep(v) {
     if (v === undefined || v === null || v === "" || v === 0)
         return 0;
     if (typeof v === "number")
-        return Math.round(v * 3600000);
+        return Math.round(v * 3_600_000);
     const m = /^\s*(-?\d+(?:\.\d+)?)\s*(ms|s|m|h)?\s*$/i.exec(v);
     if (!m)
         throw new Error(`Invalid addHoursEveryMin "${v}"`);
-    const mult = FREQ_MULT[(m[2] || "h").toLowerCase()] ?? 1; // ◀ TS FIX
-    return Math.round(Number.parseFloat(m[1]) * mult);
+    return Math.round(Number.parseFloat(m[1]) * FREQ_MULT[(m[2] ?? "h").toLowerCase()]);
 }
-/* ================================================================
- * Timezone helpers
- * ================================================================ */
+
+/* Timezone-aware helpers built exclusively on Intl (zero deps). */
 const _dtfCache = new Map();
+/** Cached `Intl.DateTimeFormat`; throws synchronously for invalid zones. */
 function getDtf(tz) {
-    let d = _dtfCache.get(tz);
-    if (!d) {
+    let dtf = _dtfCache.get(tz);
+    if (!dtf) {
         try {
-            d = new Intl.DateTimeFormat("en-US", {
+            dtf = new Intl.DateTimeFormat("en-US", {
                 timeZone: tz,
                 hourCycle: "h23",
                 year: "numeric",
@@ -94,9 +130,9 @@ function getDtf(tz) {
         catch {
             throw new Error(`Invalid timeZone "${tz}"`);
         }
-        _dtfCache.set(tz, d);
+        _dtfCache.set(tz, dtf);
     }
-    return d;
+    return dtf;
 }
 function partsIn(tz, date) {
     const o = {};
@@ -105,21 +141,21 @@ function partsIn(tz, date) {
     return o;
 }
 const pad2 = (n) => n.padStart(2, "0");
-const escRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+/** Escape a literal string for embedding inside a RegExp. */
+function escRe(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+/** Substitute YYYY|YY|MM|DD|HH|mm|ss tokens in `pattern`. */
 function formatStamp(pattern, parts) {
-    return pattern.replace(/YYYY|YY|MM|DD|HH|mm|ss/g, (t) => t === "YYYY" ? parts.year :
-        t === "YY" ? parts.year.slice(-2) :
-            t === "MM" ? pad2(parts.month) :
-                t === "DD" ? pad2(parts.day) :
-                    t === "HH" ? pad2(parts.hour) :
-                        t === "mm" ? pad2(parts.minute) :
-                            t === "ss" ? pad2(parts.second) : t);
+    return pattern.replace(/YYYY|YY|MM|DD|HH|mm|ss/g, (t) => t === "YYYY" ? parts.year : t === "YY" ? parts.year.slice(-2) : t === "MM" ? pad2(parts.month) : t === "DD" ? pad2(parts.day) : t === "HH" ? pad2(parts.hour) : t === "mm" ? pad2(parts.minute) : t === "ss" ? pad2(parts.second) : t);
 }
+/** Offset of `tz` vs UTC at instant `date`, milliseconds. */
 function tzOffsetMs(tz, date) {
     const p = partsIn(tz, date);
     return (Date.UTC(+p.year, +p.month - 1, +p.day, +p.hour, +p.minute, +p.second) -
         (date.getTime() - (date.getTime() % 1000)));
 }
+/** Next local midnight in `tz`, DST-corrected by fixed-point iteration. */
 function nextMidnight(tz, fromMs) {
     const p = partsIn(tz, new Date(fromMs));
     const localNext = Date.UTC(+p.year, +p.month - 1, +p.day + 1);
@@ -131,50 +167,47 @@ function nextMidnight(tz, fromMs) {
         inst = cand;
     }
     if (inst <= fromMs)
-        inst += 86400000;
+        inst += 86_400_000;
     return inst;
 }
+/** Next epoch-aligned boundary (e.g. hh:00 for step = 1h). */
 const nextAligned = (from, step) => Math.floor(from / step) * step + step;
-/* ================================================================
- * Utilities
- * ================================================================ */
-const statSizeSafe = (p) => {
-    try {
-        return typeof p === "string" ? fs.statSync(p).size : 0;
-    }
-    catch {
-        return 0;
-    }
-};
-const existsSafe = (p) => {
-    try {
-        return fs.existsSync(p);
-    }
-    catch {
-        return false;
-    }
-};
-/** ◀ TS FIX: takes an onWarn CALLBACK instead of an emitter object,
- *  so the strictly-typed `emit` can be passed without casts. */
-async function gzipMove(src, dst, onWarn) {
-    try {
-        await pipeline(fs.createReadStream(src), zlib.createGzip({ level: 6 }), fs.createWriteStream(dst));
-        await fs.promises.unlink(src);
-        return true;
-    }
-    catch (err) {
-        await fs.promises.unlink(dst).catch(() => { });
-        onWarn?.(err);
-        return false;
-    }
-}
-const endStream = (ws) => ws ? new Promise((r) => ws.end(() => r())) : Promise.resolve();
+
 const BUMP_DEFAULT_MS = 60_000;
 const AUDIT_MAX_FILES = 600;
+const AUDIT_MAX_EVENTS = 200;
 const HEARTBEAT_STALE_MS = 30_000;
-/* ================================================================
- * Main class
- * ================================================================ */
+const emptyAudit = (prefix, ext, datePattern, tz) => ({
+    version: 1,
+    prefix,
+    ext,
+    datePattern,
+    tz,
+    createdAt: null,
+    updatedAt: null,
+    activeStamp: null,
+    activeIndex: null,
+    writer: null,
+    files: {},
+    events: [],
+});
+/**
+ * A `Writable` that appends to dated log files, rolling segments on time
+ * and/or size, optionally gzipping sealed segments, enforcing retention,
+ * and resuming an unbroken series across restarts via disk scan + audit
+ * manifest.
+ *
+ * @example
+ * ```ts
+ * const log = createStream({
+ *   filename: "logs/app-%DATE%.log",
+ *   maxSize: "20m",
+ *   maxFiles: "90d",
+ *   zippedArchive: true,
+ * });
+ * log.write("hello\n");          // or: readable.pipe(log)
+ * ```
+ */
 class RotateFileStream extends Writable {
     tz;
     template;
@@ -185,17 +218,21 @@ class RotateFileStream extends Writable {
     maxFiles;
     freq;
     unrefTimers;
+    /* ---- filename-template pieces ---- */
     _tL;
     _tMid;
     _tExt;
     _rxFor;
     _rxActive;
+    /* ---- audit manifest ---- */
     _auditEnabled;
     _auditPath;
     _bootId = randomUUID();
+    /* ---- virtual test clock ---- */
     _offsetMs;
     _stepMs;
     _bumpEvery;
+    /* ---- live state ---- */
     _curStamp;
     _index;
     _ws = null;
@@ -206,15 +243,16 @@ class RotateFileStream extends Writable {
     _ended = false;
     _tail = Promise.resolve();
     _audit;
-    // ◀ TS FIX: Partial<> + runtime validation (default {} is legal now)
     constructor(opts = {}) {
         super(opts.highWaterMark ? { highWaterMark: opts.highWaterMark } : {});
-        if (typeof opts.filename !== "string" || !opts.filename.includes("%DATE%"))
-            throw new Error("opts.filename must contain '%DATE%'");
+        const filename = opts.filename;
+        if (typeof filename !== "string" || !filename.includes("%DATE%")) {
+            throw new Error("opts.filename must contain '%DATE%' (e.g. 'logs/app-%DATE%.log')");
+        }
         this.tz = opts.tz || "UTC";
-        getDtf(this.tz);
-        this.template = path.basename(opts.filename);
-        this.dir = path.dirname(opts.filename);
+        getDtf(this.tz); // validate early, fail fast
+        this.template = path.basename(filename);
+        this.dir = path.dirname(filename);
         this.datePattern = opts.datePattern || "YYYY-MM-DD";
         this.zippedArchive = !!opts.zippedArchive;
         this.maxSize = parseSize(opts.maxSize ?? 0);
@@ -224,38 +262,41 @@ class RotateFileStream extends Writable {
         this._offsetMs = parseClockOffset(opts.addHours);
         this._stepMs = parseClockStep(opts.addHoursEveryMin);
         this._bumpEvery = Math.max(50, opts.clockStepIntervalMs ?? BUMP_DEFAULT_MS);
+        /* Split "prefix-%DATE%mid.ext" → pieces so indices land BETWEEN the
+           stamp and the extension: prefix-STAMP.N.ext                       */
         const li = this.template.indexOf("%DATE%");
-        const rest = this.template.slice(li + 6);
+        const rest = this.template.slice(li + "%DATE%".length);
         const dot = rest.lastIndexOf(".");
         this._tL = this.template.slice(0, li);
         this._tMid = dot >= 0 ? rest.slice(0, dot) : "";
         this._tExt = dot >= 0 ? rest.slice(dot) : "";
-        this._rxFor = (stampSrc) => new RegExp("^" + escRe(this._tL) + stampSrc + escRe(this._tMid) +
+        this._rxFor = (stampSrc) => new RegExp("^" +
+            escRe(this._tL) + stampSrc + escRe(this._tMid) +
             "(?:\\.(\\d+))?" + escRe(this._tExt) + "(?:\\.gz)?$");
         this._rxActive = this._rxFor("[^.]+");
         this._auditEnabled = opts.audit !== false;
-        const stem = (this._tL.replace(/[^\w.-]+/g, "") || "log").replace(/^[-.]+|[-.]+$/, "");
+        const stem = (this._tL.replace(/[^\w.-]+/g, "") || "log")
+            .replace(/^[-.]+|[-.]+$/g, "");
         this._auditPath = path.join(this.dir, opts.auditFile || `${stem}_audit.json`);
         fs.mkdirSync(this.dir, { recursive: true });
         this._curStamp = this._stampNow();
-        this._resetAuditObject();
+        this._audit = emptyAudit(this._tL, this._tExt, this.datePattern, this.tz);
         const hadAudit = this._auditEnabled && this._loadAudit();
         this._index = this._recoverIndexFor(this._curStamp);
-        // ◀ TS FIX: local const narrows away null (Number.isInteger doesn't)
-        const ai = this._audit.activeIndex;
-        if (hadAudit && ai !== null && this._audit.activeStamp === this._curStamp) {
-            this._index = Math.max(this._index, ai);
+        const aiBoot = this._audit.activeIndex;
+        if (hadAudit && aiBoot !== null && this._audit.activeStamp === this._curStamp) {
+            this._index = Math.max(this._index, aiBoot);
         }
-        if (this._offsetMs !== 0 || this._stepMs !== 0)
+        if (this._offsetMs !== 0 || this._stepMs !== 0) {
             process.nextTick(() => this.emit("clock", {
                 addHours: opts.addHours ?? undefined,
                 addHoursEveryMin: opts.addHoursEveryMin ?? undefined,
                 offsetMs: this._offsetMs,
             }));
-        /* boot audit pass = job #1 in the serial queue.
-       Chained HERE (not nextTick) so it always runs before any write job:
-       zombie demotion sees _path === null, and gzip-repair can never race
-       with a write reopening a pending file.                        */
+        }
+        /* Boot housekeeping is job #1 of the serial queue — chained HERE in the
+           constructor so it deterministically precedes any write job: zombie
+           demotion sees `_path === null`, gzip repair cannot race a reopen.  */
         this._job(async () => {
             if (this._auditEnabled) {
                 this._demoteZombieActives();
@@ -274,250 +315,53 @@ class RotateFileStream extends Writable {
             this._stopBump();
         });
     }
-    /* ---------------- public ---------------- */
+    on(event, listener) {
+        return super.on(event, listener);
+    }
+    once(event, listener) {
+        return super.once(event, listener);
+    }
+    emit(event, ...args) {
+        return super.emit(event, ...args);
+    }
+    /* ==================================================================
+     * Public API
+     * ================================================================ */
+    /** Absolute path of the segment currently written; `null` until first write. */
     get filename() {
         return this._path;
     }
+    /** Index of the active segment within the current period. */
     get currentIndex() {
         return this._index;
     }
-    _now() {
-        return Date.now() + this._offsetMs;
-    }
+    /**
+     * Force an immediate rotation and resolve when the next slot is staged.
+     */
     rotateNow() {
         return this._job(() => this._rotate("manual"));
     }
-    /** Apply one virtual-clock step immediately (test helper). */
+    /**
+     * Apply ONE virtual-clock tick immediately (bypasses the interval timer
+     * for deterministic tests). Crossing into a new period triggers the same
+     * archive flow as a real midnight roll.
+     */
     advanceClock() {
         return this._job(() => this._applyBump());
     }
-    /* ---------------- audit internals ---------------- */
-    _resetAuditObject() {
-        this._audit = {
-            version: 1,
-            prefix: this._tL,
-            ext: this._tExt,
-            datePattern: this.datePattern,
-            tz: this.tz,
-            createdAt: null,
-            updatedAt: null,
-            activeStamp: null,
-            activeIndex: null,
-            writer: null,
-            files: {},
-            events: [],
-        };
-    }
-    _loadAudit() {
-        try {
-            let raw;
-            try {
-                raw = JSON.parse(fs.readFileSync(this._auditPath, "utf8"));
-            }
-            catch {
-                return false;
-            }
-            const j = raw;
-            if (j && j.version === 1 && j.prefix === this._tL && j.ext === this._tExt) {
-                this._audit.createdAt = j.createdAt || new Date().toISOString();
-                this._audit.updatedAt = null;
-                this._audit.activeStamp =
-                    typeof j.activeStamp === "string" ? j.activeStamp : null;
-                this._audit.activeIndex =
-                    Number.isInteger(j.activeIndex) ? j.activeIndex : null;
-                this._audit.files =
-                    j.files && typeof j.files === "object"
-                        ? j.files
-                        : {};
-                this._audit.events = Array.isArray(j.events)
-                    ? j.events.slice(-200)
-                    : [];
-                const w = j.writer;
-                if (w && w.bootId && w.bootId !== this._bootId &&
-                    typeof w.heartbeat === "number" &&
-                    Date.now() - w.heartbeat < HEARTBEAT_STALE_MS) {
-                    const err = new Error(`concurrent writer detected (pid ${w.pid}, boot ${w.bootId}). ` +
-                        `Two processes are sharing this log family — results will race. ` +
-                        `If using 'node --watch', add --watch-path to exclude the logs dir.`);
-                    this.emit("warn", err);
-                    this._audit.events.push({
-                        id: randomUUID(),
-                        t: new Date().toISOString(),
-                        type: "concurrent-writer",
-                        otherPid: w.pid,
-                        otherBoot: w.bootId,
-                    });
-                }
-                return true;
-            }
-            try {
-                fs.renameSync(this._auditPath, this._auditPath + ".corrupt");
-            }
-            catch {
-                /* ignore */
-            }
-        }
-        catch {
-            /* fallthrough */
-        }
-        return false;
-    }
-    _saveAudit() {
-        if (!this._auditEnabled)
-            return;
-        try {
-            this._pruneAuditFiles();
-            this._audit.updatedAt = new Date().toISOString();
-            this._audit.writer = {
-                pid: process.pid,
-                bootId: this._bootId,
-                heartbeat: Date.now(),
-            };
-            const tmp = this._auditPath + ".tmp";
-            fs.writeFileSync(tmp, JSON.stringify(this._audit, null, 1));
-            fs.renameSync(tmp, this._auditPath);
-        }
-        catch (e) {
-            this.emit("warn", e);
-        }
-    }
-    _pruneAuditFiles() {
-        const f = this._audit.files;
-        const keys = Object.keys(f);
-        if (keys.length <= AUDIT_MAX_FILES)
-            return;
-        const activeBase = this._path && path.basename(this._path);
-        const dated = (r) => r.archivedAt || r.closedAt || r.abandonedAt || r.openedAt || "";
-        const stale = keys
-            .filter((k) => k !== activeBase && f[k].state !== "active")
-            .sort((a, b) => dated(f[a]).localeCompare(dated(f[b])));
-        for (const k of stale.slice(0, keys.length - AUDIT_MAX_FILES + 50))
-            delete f[k];
-    }
-    _aevent(type, extra = {}) {
-        if (!this._auditEnabled)
-            return;
-        this._audit.events.push({
-            id: randomUUID(),
-            t: new Date().toISOString(),
-            type,
-            ...extra,
-        });
-        if (this._audit.events.length > 200)
-            this._audit.events.splice(0, this._audit.events.length - 200);
-    }
-    _setActivePointer(index) {
-        this._audit.activeStamp = this._curStamp;
-        this._audit.activeIndex = index;
-    }
-    _demoteZombieActives() {
-        const activeBase = this._path && path.basename(this._path);
-        for (const [name, rec] of Object.entries(this._audit.files)) {
-            if (rec.state === "active" && name !== activeBase) {
-                rec.state = "abandoned";
-                rec.abandonedAt = new Date().toISOString();
-                this._aevent("abandon", { file: name });
-            }
-        }
-    }
-    _reconcileWithDisk() {
-        for (const name of Object.keys(this._audit.files)) {
-            const rec = this._audit.files[name];
-            if (rec.gzipPending)
-                continue;
-            if (name.endsWith(".gz")) {
-                const gzExists = existsSafe(path.join(this.dir, name));
-                const rawName = name.slice(0, -3);
-                const rawExists = existsSafe(path.join(this.dir, rawName));
-                if (gzExists)
-                    continue;
-                if (rawExists) {
-                    delete this._audit.files[name];
-                    this._audit.files[rawName] = { ...rec, state: "sealed" };
-                    this._aevent("archive-regressed", { file: name, backTo: rawName });
-                    this.emit("warn", new Error(`archive ${name} missing but raw ${rawName} exists — record reverted`));
-                    continue;
-                }
-                this._aevent("vanished", { file: name });
-                delete this._audit.files[name];
-                continue;
-            }
-            const rawExists = existsSafe(path.join(this.dir, name));
-            const gzExists = existsSafe(path.join(this.dir, name + ".gz"));
-            if (rawExists)
-                continue;
-            if (gzExists) {
-                this._finishArchivedRecord(name, true);
-                continue;
-            }
-            this._aevent("vanished", { file: name });
-            delete this._audit.files[name];
-        }
-    }
-    async _repairInterruptedGzips() {
-        for (const [name, rec] of Object.entries(this._audit.files)) {
-            if (!rec.gzipPending)
-                continue;
-            const src = path.join(this.dir, name);
-            const dst = src + ".gz";
-            if (!existsSafe(src)) {
-                rec.gzipPending = false;
-                rec.state = "lost";
-                this._aevent("gzip-lost", { file: name });
-                continue;
-            }
-            if (existsSafe(dst)) {
-                try {
-                    fs.unlinkSync(src);
-                }
-                catch {
-                    /* ignore */
-                }
-                this._finishArchivedRecord(name, true);
-                continue;
-            }
-            // ◀ TS FIX: callback instead of emitter object
-            const ok = await gzipMove(src, dst, (e) => this.emit("warn", e));
-            if (ok) {
-                this._finishArchivedRecord(name, true);
-            }
-            else {
-                rec.gzipPending = false;
-                rec.state = "kept-raw";
-                this._aevent("gzip-failed", { file: name });
-            }
-        }
-    }
-    _finishArchivedRecord(rawName, repaired = false) {
-        const rec = this._audit.files[rawName];
-        if (!rec)
-            return;
-        rec.gzipPending = false;
-        rec.state = "archived";
-        rec.archivedAt = new Date().toISOString();
-        if (rawName.endsWith(".gz")) {
-            this.emit("archive", path.join(this.dir, rawName));
-            this._aevent("archive", { file: rawName, ...(repaired && { repaired }) });
-        }
-        else {
-            const gzName = rawName + ".gz";
-            delete this._audit.files[rawName];
-            this._audit.files[gzName] = rec;
-            this.emit("archive", path.join(this.dir, gzName));
-            this._aevent("archive", { file: gzName, ...(repaired && { repaired }) });
-        }
-    }
-    /* ---------------- Writable ---------------- */
-    _write(chunk, encoding, cb) {
+    /* ==================================================================
+     * Writable contract
+     * ================================================================ */
+    _write(chunk, encoding, callback) {
         if (this._ended) {
-            process.nextTick(cb, new Error("write after end"));
+            process.nextTick(callback, new Error("write after end"));
             return;
         }
         const len = chunk.length;
         this._job(async () => {
             try {
-                const s = this._stampNow();
-                if (s !== this._curStamp)
+                const stamp = this._stampNow();
+                if (stamp !== this._curStamp)
                     await this._rotate("time");
                 await this._ensureOpen();
                 if (this.maxSize > 0 &&
@@ -526,50 +370,56 @@ class RotateFileStream extends Writable {
                     await this._rotate("size");
                     await this._ensureOpen();
                 }
-                // ◀ TS FIX: narrow instead of `this._ws!`
                 const ws = this._ws;
                 if (!ws)
-                    throw new Error("write stream not open");
-                await new Promise((res, rej) => ws.write(chunk, encoding, (e) => (e ? rej(e) : res())));
+                    throw new Error("segment write stream not open");
+                await new Promise((resolve, reject) => ws.write(chunk, encoding, (e) => (e ? reject(e) : resolve())));
                 this._bytes += len;
-                cb();
+                callback();
             }
             catch (err) {
-                this.emit("error", err); // ok now: "error" in the events map
-                cb(err);
+                this.emit("error", err);
+                callback(err);
             }
         }).catch(() => { });
     }
-    _final(cb) {
+    _final(callback) {
         this._ended = true;
         this._stopTimer();
         this._stopBump();
         this._job(async () => {
             await endStream(this._ws);
-            const b = this._path && path.basename(this._path);
-            if (b && this._audit.files[b]) {
-                this._audit.files[b].state = "closed";
-                this._audit.files[b].closedAt = new Date().toISOString();
-                this._audit.files[b].bytes = statSizeSafe(this._path);
-                this._aevent("close", { file: b });
+            const base = this._path && path.basename(this._path);
+            if (base && this._audit.files[base]) {
+                const rec = this._audit.files[base];
+                rec.state = "closed";
+                rec.closedAt = new Date().toISOString();
+                rec.bytes = statSizeSafe(this._path);
+                this._aevent("close", { file: base });
                 this._saveAudit();
             }
             this._ws = null;
             this._path = null;
         })
             .catch(() => { })
-            .finally(() => cb());
+            .finally(() => callback());
     }
     destroy(...args) {
         this._stopTimer();
         this._stopBump();
         return super.destroy(...args);
     }
-    /* ---------------- core ---------------- */
+    /* ==================================================================
+     * Serialisation — every mutating operation funnels through one queue
+     * so rotations/gzips/writes never interleave.
+     * ================================================================ */
     _job(fn) {
-        const p = this._tail.then(fn, fn);
-        this._tail = p.catch(() => { });
-        return p;
+        const run = this._tail.then(fn, fn);
+        this._tail = run.catch(() => { });
+        return run;
+    }
+    _now() {
+        return Date.now() + this._offsetMs;
     }
     _stampNow(d = new Date(this._now())) {
         return formatStamp(this.datePattern, partsIn(this.tz, d));
@@ -582,6 +432,11 @@ class RotateFileStream extends Writable {
             ? base.replace(/\.[^.]+$/, `.${index}$&`)
             : `${base}.${index}`;
     }
+    /**
+     * Highest viable segment index for `stamp`.
+     * Disk is truth: resume a raw tail; start after sealed ones.
+     * The audit pointer (same stamp only) may only RAISE the result.
+     */
     _recoverIndexFor(stamp) {
         const rx = this._rxFor(escRe(stamp));
         let maxAny = -1;
@@ -591,7 +446,7 @@ class RotateFileStream extends Writable {
             names = fs.readdirSync(this.dir);
         }
         catch {
-            /* ignore */
+            /* unreadable dir → fresh series */
         }
         for (const n of names) {
             const m = rx.exec(n);
@@ -604,11 +459,8 @@ class RotateFileStream extends Writable {
                 maxRaw = idx;
         }
         let idx = maxRaw >= 0 ? maxRaw : maxAny >= 0 ? maxAny + 1 : 0;
-        // ◀ TS FIX: local const narrows away null
         const ai = this._audit.activeIndex;
-        if (this._auditEnabled &&
-            ai !== null &&
-            this._audit.activeStamp === stamp) {
+        if (this._auditEnabled && ai !== null && this._audit.activeStamp === stamp) {
             idx = Math.max(idx, ai);
         }
         return idx;
@@ -623,9 +475,9 @@ class RotateFileStream extends Writable {
         this._ws = ws;
         this._path = p;
         if (this._auditEnabled) {
-            const b = path.basename(p);
-            const prev = this._audit.files[b];
-            this._audit.files[b] = {
+            const base = path.basename(p);
+            const prev = this._audit.files[base];
+            this._audit.files[base] = {
                 ...(prev && prev.state === "archived" ? {} : prev),
                 index: this._index,
                 state: "active",
@@ -634,7 +486,7 @@ class RotateFileStream extends Writable {
             };
             this._setActivePointer(this._index);
             this._aevent("open", {
-                file: b,
+                file: base,
                 index: this._index,
                 resumedBytes: this._bytes,
             });
@@ -649,75 +501,78 @@ class RotateFileStream extends Writable {
         this._path = null;
         this._bytes = 0;
         let archive = null;
-        // ◀ TS FIX: guard on oldPath too — narrows string|null for the whole block,
-        // removing every `!` and the null-concatenation risk
         if (oldWs && oldPath) {
             await endStream(oldWs);
-            const real = statSizeSafe(oldPath);
-            const abase = path.basename(oldPath);
-            const arec = this._auditEnabled ? this._audit.files[abase] : null;
-            if (this.zippedArchive && real > 0) {
-                archive = oldPath + ".gz";
-                if (arec) {
-                    arec.gzipPending = true;
-                    arec.bytes = real;
+            const realBytes = statSizeSafe(oldPath);
+            const oldBase = path.basename(oldPath);
+            const rec = this._auditEnabled ? this._audit.files[oldBase] : undefined;
+            if (this.zippedArchive && realBytes > 0) {
+                archive = `${oldPath}.gz`;
+                /* Mark intent BEFORE compressing: crash mid-gzip becomes a
+                   repairable `gzipPending` flag instead of silent divergence.  */
+                if (rec) {
+                    rec.gzipPending = true;
+                    rec.bytes = realBytes;
                     this._saveAudit();
                 }
                 const ok = await gzipMove(oldPath, archive, (e) => this.emit("warn", e));
                 if (ok) {
-                    this._finishArchivedRecord(abase);
+                    this._finishArchivedRecord(oldBase);
                 }
                 else {
-                    if (arec) {
-                        arec.gzipPending = false;
-                        arec.state = "kept-raw";
+                    if (rec) {
+                        rec.gzipPending = false;
+                        rec.state = "kept-raw";
                     }
-                    this._aevent("gzip-failed", { file: abase });
+                    this._aevent("gzip-failed", { file: oldBase });
                     archive = null;
                 }
             }
-            else if (real === 0) {
+            else if (realBytes === 0) {
                 try {
                     fs.unlinkSync(oldPath);
                 }
                 catch {
-                    /* ignore */
+                    /* already gone */
                 }
-                if (arec)
-                    delete this._audit.files[abase];
-                this._aevent("drop-empty", { file: abase });
+                if (rec)
+                    delete this._audit.files[oldBase];
+                this._aevent("drop-empty", { file: oldBase });
             }
-            else if (arec) {
-                arec.state = "sealed";
-                arec.bytes = real;
+            else if (rec) {
+                rec.state = "sealed";
+                rec.bytes = realBytes;
             }
         }
-        const s = this._stampNow();
-        const newPeriod = s !== this._curStamp;
-        this._curStamp = s;
-        this._index = newPeriod
-            ? this._recoverIndexFor(s)
-            : kind === "time"
-                ? this._recoverIndexFor(s)
+        const stamp = this._stampNow();
+        const newPeriod = stamp !== this._curStamp;
+        this._curStamp = stamp;
+        /* Never blind-reset to 0 — recover what THIS stamp already owns. */
+        this._index =
+            newPeriod || kind === "time"
+                ? this._recoverIndexFor(stamp)
                 : this._index + 1;
         this._bytes = 0;
         if (this._auditEnabled) {
             this._setActivePointer(this._index);
-            this._aevent("rotate", { reason: kind, nextIndex: this._index, stamp: s });
+            this._aevent("rotate", { reason: kind, nextIndex: this._index, stamp });
             this._saveAudit();
         }
         if (kind === "time" || kind === "manual")
             this._armTimer();
-        if (oldPath)
+        if (oldPath) {
             this.emit("rotated", {
                 reason: kind,
                 oldFile: oldPath,
                 archive,
-                newFile: this._resolveName(s, this._index),
+                newFile: this._resolveName(stamp, this._index),
             });
+        }
         this._retire();
     }
-    /* ---------------- timers ---------------- */
+    /* ==================================================================
+     * Timers
+     * ================================================================ */
     _hasContent() {
         return this._ws
             ? this._bytes > 0 || statSizeSafe(this._path) > 0
@@ -733,21 +588,22 @@ class RotateFileStream extends Writable {
             : nextAligned(now, this.freq.ms);
         this._timer = setTimeout(() => {
             this._job(async () => {
-                const s = this._stampNow();
-                if ((this.freq.type === "daily" && s !== this._curStamp) ||
-                    this.freq.type !== "daily") {
+                const stamp = this._stampNow();
+                const dueDaily = this.freq.type === "daily" && stamp !== this._curStamp;
+                const dueInterval = this.freq.type !== "daily";
+                if (dueDaily || dueInterval) {
                     if (this._hasContent()) {
                         await this._rotate("time");
                     }
-                    else if (s !== this._curStamp) {
-                        this._curStamp = s;
-                        this._index = this._recoverIndexFor(s);
+                    else if (stamp !== this._curStamp) {
+                        this._curStamp = stamp;
+                        this._index = this._recoverIndexFor(stamp);
                         if (this._auditEnabled) {
                             this._setActivePointer(this._index);
-                            this._aevent("period", { stamp: s });
+                            this._aevent("period", { stamp });
                             this._saveAudit();
                         }
-                        this.emit("period", s);
+                        this.emit("period", stamp);
                     }
                 }
                 this._armTimer();
@@ -775,26 +631,26 @@ class RotateFileStream extends Writable {
             return;
         this._offsetMs += this._stepMs;
         this._armTimer();
-        const s = this._stampNow();
-        if (s !== this._curStamp) {
+        const stamp = this._stampNow();
+        if (stamp !== this._curStamp) {
             if (this._hasContent()) {
                 await this._rotate("time");
             }
             else {
-                this._curStamp = s;
-                this._index = this._recoverIndexFor(s);
+                this._curStamp = stamp;
+                this._index = this._recoverIndexFor(stamp);
                 if (this._auditEnabled) {
                     this._setActivePointer(this._index);
-                    this._aevent("period", { stamp: s, virtual: true });
+                    this._aevent("period", { stamp, virtual: true });
                 }
-                this.emit("period", s);
+                this.emit("period", stamp);
             }
         }
         if (this._auditEnabled) {
             this._aevent("clock-step", {
                 addedMsPerMin: this._stepMs,
                 offsetMs: this._offsetMs,
-                stamp: s,
+                stamp,
             });
             this._saveAudit();
         }
@@ -805,66 +661,271 @@ class RotateFileStream extends Writable {
             this._timer = null;
         }
     }
-    /* ---------------- retention ---------------- */
+    /* ==================================================================
+     * Audit manifest
+     * ================================================================ */
+    _loadAudit() {
+        let parsed;
+        try {
+            parsed = JSON.parse(fs.readFileSync(this._auditPath, "utf8"));
+        }
+        catch {
+            return false; // missing/unreadable → fresh start
+        }
+        const j = parsed;
+        if (!j || j.version !== 1 || j.prefix !== this._tL || j.ext !== this._tExt) {
+            try {
+                fs.renameSync(this._auditPath, `${this._auditPath}.corrupt`);
+            }
+            catch {
+                /* ignore */
+            }
+            return false;
+        }
+        this._audit.createdAt = j.createdAt ?? new Date().toISOString();
+        this._audit.activeStamp =
+            typeof j.activeStamp === "string" ? j.activeStamp : null;
+        this._audit.activeIndex =
+            Number.isInteger(j.activeIndex) ? j.activeIndex : null;
+        this._audit.files =
+            j.files && typeof j.files === "object"
+                ? j.files
+                : {};
+        this._audit.events = Array.isArray(j.events)
+            ? j.events.slice(-AUDIT_MAX_EVENTS)
+            : [];
+        /* Detect another LIVE process on this family before clobbering it. */
+        const w = j.writer;
+        if (w &&
+            typeof w.bootId === "string" &&
+            w.bootId !== this._bootId &&
+            typeof w.heartbeat === "number" &&
+            Date.now() - w.heartbeat < HEARTBEAT_STALE_MS) {
+            const err = new Error(`concurrent writer detected (pid ${w.pid}, boot ${w.bootId}); ` +
+                "two processes share this log family and will race. " +
+                "If running 'node --watch', exclude the logs dir via --watch-path.");
+            this.emit("warn", err);
+            this._audit.events.push({
+                id: randomUUID(),
+                t: new Date().toISOString(),
+                type: "concurrent-writer",
+                otherPid: w.pid,
+                otherBoot: w.bootId,
+            });
+        }
+        return true;
+    }
+    _saveAudit() {
+        if (!this._auditEnabled)
+            return;
+        try {
+            this._pruneAuditFiles();
+            this._audit.updatedAt = new Date().toISOString();
+            this._audit.writer = {
+                pid: process.pid,
+                bootId: this._bootId,
+                heartbeat: Date.now(),
+            };
+            const tmp = `${this._auditPath}.tmp`;
+            fs.writeFileSync(tmp, JSON.stringify(this._audit, null, 1));
+            fs.renameSync(tmp, this._auditPath);
+        }
+        catch (e) {
+            this.emit("warn", e);
+        }
+    }
+    _pruneAuditFiles() {
+        const files = this._audit.files;
+        const keys = Object.keys(files);
+        if (keys.length <= AUDIT_MAX_FILES)
+            return;
+        const activeBase = this._path && path.basename(this._path);
+        const lastTouch = (r) => r.archivedAt ?? r.closedAt ?? r.abandonedAt ?? r.openedAt ?? "";
+        const stale = keys
+            .filter((k) => k !== activeBase && files[k].state !== "active")
+            .sort((a, b) => lastTouch(files[a]).localeCompare(lastTouch(files[b])));
+        const excess = keys.length - AUDIT_MAX_FILES + 50;
+        for (const key of stale.slice(0, excess))
+            delete files[key];
+    }
+    _aevent(type, extra = {}) {
+        if (!this._auditEnabled)
+            return;
+        const events = this._audit.events;
+        events.push({ id: randomUUID(), t: new Date().toISOString(), type, ...extra });
+        if (events.length > AUDIT_MAX_EVENTS) {
+            events.splice(0, events.length - AUDIT_MAX_EVENTS);
+        }
+    }
+    _setActivePointer(index) {
+        this._audit.activeStamp = this._curStamp;
+        this._audit.activeIndex = index;
+    }
+    /** Records left `active` by dead processes → `abandoned`. */
+    _demoteZombieActives() {
+        const activeBase = this._path && path.basename(this._path);
+        for (const [name, rec] of Object.entries(this._audit.files)) {
+            if (rec.state === "active" && name !== activeBase) {
+                rec.state = "abandoned";
+                rec.abandonedAt = new Date().toISOString();
+                this._aevent("abandon", { file: name });
+            }
+        }
+    }
+    /** Heal audit-vs-disk divergence after crashes / external tampering. */
+    _reconcileWithDisk() {
+        for (const name of Object.keys(this._audit.files)) {
+            const rec = this._audit.files[name];
+            if (rec.gzipPending)
+                continue; // handled by the repair pass
+            if (name.endsWith(".gz")) {
+                const gzExists = existsSafe(path.join(this.dir, name));
+                const rawName = name.slice(0, -3);
+                const rawExists = existsSafe(path.join(this.dir, rawName));
+                if (gzExists)
+                    continue;
+                if (rawExists) {
+                    delete this._audit.files[name];
+                    this._audit.files[rawName] = { ...rec, state: "sealed" };
+                    this._aevent("archive-regressed", { file: name, backTo: rawName });
+                    this.emit("warn", new Error(`archive ${name} missing but raw ${rawName} exists`));
+                    continue;
+                }
+                this._aevent("vanished", { file: name });
+                delete this._audit.files[name];
+                continue;
+            }
+            const rawExists = existsSafe(path.join(this.dir, name));
+            const gzExists = existsSafe(path.join(this.dir, `${name}.gz`));
+            if (rawExists)
+                continue;
+            if (gzExists) {
+                this._finishArchivedRecord(name, true); // unlink was interrupted
+                continue;
+            }
+            this._aevent("vanished", { file: name });
+            delete this._audit.files[name];
+        }
+    }
+    async _repairInterruptedGzips() {
+        for (const [name, rec] of Object.entries(this._audit.files)) {
+            if (!rec.gzipPending)
+                continue;
+            const src = path.join(this.dir, name);
+            const dst = `${src}.gz`;
+            if (!existsSafe(src)) {
+                rec.gzipPending = false;
+                rec.state = "lost";
+                this._aevent("gzip-lost", { file: name });
+                continue;
+            }
+            if (existsSafe(dst)) {
+                try {
+                    fs.unlinkSync(src);
+                }
+                catch {
+                    /* ignore */
+                }
+                this._finishArchivedRecord(name, true);
+                continue;
+            }
+            const ok = await gzipMove(src, dst, (e) => this.emit("warn", e));
+            if (ok) {
+                this._finishArchivedRecord(name, true);
+            }
+            else {
+                rec.gzipPending = false;
+                rec.state = "kept-raw";
+                this._aevent("gzip-failed", { file: name });
+            }
+        }
+    }
+    /** Seal a record; re-key `name` → `name.gz` so scans stop ghosting. */
+    _finishArchivedRecord(rawName, repaired = false) {
+        const rec = this._audit.files[rawName];
+        if (!rec)
+            return;
+        rec.gzipPending = false;
+        rec.state = "archived";
+        rec.archivedAt = new Date().toISOString();
+        if (rawName.endsWith(".gz")) {
+            this.emit("archive", path.join(this.dir, rawName));
+            this._aevent("archive", { file: rawName, ...(repaired && { repaired }) });
+            return;
+        }
+        const gzName = `${rawName}.gz`;
+        delete this._audit.files[rawName];
+        this._audit.files[gzName] = rec;
+        this.emit("archive", path.join(this.dir, gzName));
+        this._aevent("archive", { file: gzName, ...(repaired && { repaired }) });
+    }
+    /* ==================================================================
+     * Retention
+     * ================================================================ */
     async _retire() {
-        if (!this.maxFiles)
+        const policy = this.maxFiles;
+        if (!policy)
             return;
         const activeBase = this._path && path.basename(this._path);
-        const activeStem = activeBase && activeBase.replace(/(?:\.\d+)?(?:\.log|)(?:\.gz)?$/, "");
-        const auditNames = [
+        const activeStem = activeBase?.replace(/(?:\.\d+)?(?:\.log|)(?:\.gz)?$/, "");
+        const reserved = [
             path.basename(this._auditPath),
-            path.basename(this._auditPath) + ".tmp",
-            path.basename(this._auditPath) + ".corrupt",
+            `${path.basename(this._auditPath)}.tmp`,
+            `${path.basename(this._auditPath)}.corrupt`,
         ];
         try {
-            const names = (await fs.promises.readdir(this.dir)).filter((n) => this._rxActive.test(n) &&
+            const dirEntries = await fs.promises.readdir(this.dir);
+            const candidates = dirEntries.filter((n) => this._rxActive.test(n) &&
                 n !== activeBase &&
                 !(activeStem && n.startsWith(activeStem)) &&
-                !auditNames.includes(n));
-            const info = [];
-            for (const n of names) {
-                const full = path.join(this.dir, n);
+                !reserved.includes(n));
+            const stats = [];
+            for (const name of candidates) {
+                const full = path.join(this.dir, name);
                 try {
-                    info.push({ full, mt: (await fs.promises.stat(full)).mtimeMs });
+                    stats.push({ full, mtimeMs: (await fs.promises.stat(full)).mtimeMs });
                 }
                 catch {
-                    /* ignore */
+                    /* raced deletion */
                 }
             }
-            info.sort((a, b) => a.mt - b.mt);
+            stats.sort((a, b) => a.mtimeMs - b.mtimeMs); // oldest first
             const kill = new Set();
-            if (this.maxFiles.days != null) {
-                const cut = this._now() - this.maxFiles.days * 86400000;
-                for (const f of info)
-                    if (f.mt < cut)
+            if (policy.days != null) {
+                const cutoff = this._now() - policy.days * 86_400_000;
+                for (const f of stats)
+                    if (f.mtimeMs < cutoff)
                         kill.add(f.full);
             }
-            if (this.maxFiles.count != null) {
-                const rest = info.filter((f) => !kill.has(f.full));
-                for (const f of rest.slice(0, Math.max(0, rest.length - this.maxFiles.count)))
-                    kill.add(f.full);
+            if (policy.count != null) {
+                const survivors = stats.filter((f) => !kill.has(f.full));
+                const excessCount = survivors.length - policy.count;
+                for (let i = 0; i < excessCount; i++)
+                    kill.add(survivors[i].full);
             }
-            let removed = false;
-            for (const f of kill) {
-                await fs.promises.unlink(f).catch(() => { });
+            if (kill.size === 0)
+                return;
+            for (const file of kill) {
+                await fs.promises.unlink(file).catch(() => { });
                 if (this._auditEnabled) {
-                    delete this._audit.files[path.basename(f)];
-                    this._aevent("deleted", { file: path.basename(f) });
+                    delete this._audit.files[path.basename(file)];
+                    this._aevent("deleted", { file: path.basename(file) });
                 }
-                this.emit("deleted", f);
-                removed = true;
+                this.emit("deleted", file);
             }
-            if (removed)
-                this._saveAudit();
+            this._saveAudit();
         }
         catch (e) {
             this.emit("warn", e);
         }
     }
 }
-/* ================================================================
- * Factory
- * ================================================================ */
+/**
+ * Convenience factory mirroring common rotator APIs.
+ *
+ * @example
+ * const log = createStream({ filename: "logs/app-%DATE%.log" });
+ */
 function createStream(options) {
     return new RotateFileStream(options);
 }