logroller 2.0.1 → 2.0.2

package/CHANGELOG.md

@@ -5,7 +5,39 @@ All notable changes to this project are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [2.0.1] — 2026-09-0X
+## [2.0.2] — 2026-08-28
+
+### Fixed
+
+- **Corrupt audit manifest quarantine**: an unparseable `<stem>_audit.json`
+  (partial write, bad edit) is now renamed to `.corrupt` and preserved,
+  matching existing behaviour for version/family mismatches. Previously it
+  was silently overwritten by the first manifest save, destroying the
+  event journal.
+- **Backward-clock safety**: a clock moving backward (NTP correction,
+  manual change) no longer reopens a past log family or forks the segment
+  series. The stream keeps the current segment, warns once, and resumes
+  normal rotation when the clock catches up.
+- **Timer anti-spin**: with the rotation boundary in the past (backward
+  clock), the timer now polls at 1 s instead of firing every 100 ms,
+  which previously could keep processes from exiting cleanly.
+
+### Added
+
+- **Construction-time pattern warning**: warns when `frequency` is finer
+  than the `datePattern` tokens allow (`daily`→`DD`, sub-daily→`HH`,
+  sub-minute→`mm`), preventing silent filename collisions where many
+  rotations overwrite a single file.
+
+### Tests
+
+- Suite expanded to 23 tests: interrupted-gzip repair, manifest divergence
+  healing (`archive-regressed`, `vanished`), manifest quarantine,
+  concurrent-writer detection, IST-midnight boundary, idle `period` slide,
+  `rotateNow()`, over-max resume, backward-clock guard, and coarse-pattern
+  warning.
+
+## [2.0.1] — 2026-08-27
 
 ### Fixed
 
@@ -42,7 +74,7 @@ TypeScript consumers gain full type coverage.
 - Modular source layout (`src/types.ts`, `parsers.ts`, `time.ts`, `fsio.ts`,
   `rotate-file-stream.ts`) with `.js` extension imports so emitted
   declarations resolve under `nodenext` consumers.
-- Developer toolchain:  Prettier, `npm run verify` gate (typecheck + build + tests).
+- Developer toolchain: Prettier, `npm run verify` gate (typecheck + build + tests).
 - GitHub Actions: CI matrix on Node 18/20/22, release-triggered publish with
   npm provenance (`id-token: write`, `--provenance`).
 - Expanded README: comparison table, FAQ, restart-resume matrix, pino recipe.

package/dist/index.cjs

@@ -1,4 +1,4 @@
-/*! logroller v2.0.0 | MIT License */
+/*! logroller v2.0.1 | MIT License */
 'use strict';
 
 var node_crypto = require('node:crypto');
@@ -52,12 +52,21 @@ const UNITS = {
 const FREQ_MULT = {
     ms: 1, s: 1000, m: 60_000, h: 3_600_000,
 };
+function parseDuration(value, defaultUnit, fieldName) {
+    if (typeof value === "number") {
+        return Math.round(value * FREQ_MULT[defaultUnit]);
+    }
+    const m = /^\s*(-?\d+(?:\.\d+)?)\s*(ms|s|m|h)?\s*$/i.exec(value);
+    if (!m)
+        throw new Error(`Invalid ${fieldName} "${value}"`);
+    return Math.round(Number.parseFloat(m[1]) * FREQ_MULT[(m[2] ?? defaultUnit).toLowerCase()]);
+}
 function parseSize(v) {
     if (v === undefined || v === null || v === 0)
         return 0;
     if (typeof v === "number")
         return v;
-    const m = /^\s*(\d+(?:\.\d+)?)\s*(b|k|kb|m|mb|g|gb)?\s*$/i.exec(v);
+    const m = /^\s*(\d+(?:\.\d+)?)\s*(b|kb|k|mb|m|gb|g)?\s*$/i.exec(v);
     if (!m)
         throw new Error(`Invalid maxSize "${v}"`);
     return Math.round(Number.parseFloat(m[1]) * (UNITS[m[2]?.toLowerCase()] ?? 1));
@@ -81,7 +90,7 @@ function parseFrequency(v) {
     if (v === "daily")
         return { type: "daily" };
     if (typeof v === "number") {
-        if (!(v > 0))
+        if (v <= 0)
             throw new Error(`Invalid frequency "${v}"`);
         return { type: "interval", ms: v };
     }
@@ -93,22 +102,12 @@ function parseFrequency(v) {
 function parseClockOffset(v) {
     if (v === undefined || v === null || v === "")
         return 0;
-    if (typeof v === "number")
-        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]) * 3_600_000);
+    return parseDuration(v, "h", "addHours");
 }
 function parseClockStep(v) {
-    if (v === undefined || v === null || v === "" || v === 0)
+    if (v === undefined || v === null || v === "")
         return 0;
-    if (typeof v === "number")
-        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}"`);
-    return Math.round(Number.parseFloat(m[1]) * FREQ_MULT[(m[2] ?? "h").toLowerCase()]);
+    return parseDuration(v, "h", "addHours");
 }
 
 /* Timezone-aware helpers built exclusively on Intl (zero deps). */
@@ -145,11 +144,30 @@ function partsIn(tz, date) {
 const pad2 = (n) => n.padStart(2, "0");
 /** Escape a literal string for embedding inside a RegExp. */
 function escRe(s) {
-    return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    return s.replace(/[.*+?^${}()|[\]\\]/g, String.raw `\$&`);
 }
 /** 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, (token) => {
+        switch (token) {
+            case "YYYY":
+                return parts.year;
+            case "YY":
+                return parts.year.slice(-2);
+            case "MM":
+                return pad2(parts.month);
+            case "DD":
+                return pad2(parts.day);
+            case "HH":
+                return pad2(parts.hour);
+            case "mm":
+                return pad2(parts.minute);
+            case "ss":
+                return pad2(parts.second);
+            default:
+                return token;
+        }
+    });
 }
 /** Offset of `tz` vs UTC at instant `date`, milliseconds. */
 function tzOffsetMs(tz, date) {
@@ -179,6 +197,7 @@ const BUMP_DEFAULT_MS = 60_000;
 const AUDIT_MAX_FILES = 600;
 const AUDIT_MAX_EVENTS = 200;
 const HEARTBEAT_STALE_MS = 30_000;
+const TIMER_POLL_MS = 1_000;
 const emptyAudit = (prefix, ext, datePattern, tz) => ({
     version: 1,
     prefix,
@@ -244,6 +263,7 @@ class RotateFileStream extends node_stream.Writable {
     _bumpTimer = null;
     _ended = false;
     _tail = Promise.resolve();
+    _warnedBackward = false;
     _audit;
     constructor(opts = {}) {
         super(opts.highWaterMark ? { highWaterMark: opts.highWaterMark } : {});
@@ -296,14 +316,29 @@ class RotateFileStream extends node_stream.Writable {
                 offsetMs: this._offsetMs,
             }));
         }
+        process.nextTick(() => {
+            const warn = (m) => this.emit("warn", new Error(m));
+            if (this.freq.type === "interval") {
+                if (this.freq.ms < 86_400_000 && !this.datePattern.includes("HH")) {
+                    warn(`frequency "${opts.frequency}" needs HH in datePattern — ` +
+                        "segments would collapse onto one filename");
+                }
+                if (this.freq.ms < 60_000 && !this.datePattern.includes("mm")) {
+                    warn(`frequency "${opts.frequency}" needs mm in datePattern`);
+                }
+            }
+            else if (!this.datePattern.includes("DD")) {
+                warn("daily frequency needs DD in datePattern");
+            }
+        });
         /* 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 () => {
+            await this._sealOrphanedPastStamps();
             if (this._auditEnabled) {
                 this._demoteZombieActives();
                 this._reconcileWithDisk();
-                await this._sealOrphanedPastStamps();
                 await this._repairInterruptedGzips();
                 this._aevent("boot", { stamp: this._curStamp, index: this._index });
                 this._saveAudit();
@@ -338,9 +373,7 @@ class RotateFileStream extends node_stream.Writable {
     get currentIndex() {
         return this._index;
     }
-    /**
-     * Force an immediate rotation and resolve when the next slot is staged.
-     */
+    /** Force an immediate rotation and resolve when the next slot is staged. */
     rotateNow() {
         return this._job(() => this._rotate("manual"));
     }
@@ -363,8 +396,8 @@ class RotateFileStream extends node_stream.Writable {
         const len = chunk.length;
         this._job(async () => {
             try {
-                const stamp = this._stampNow();
-                if (stamp !== this._curStamp)
+                // guarded roll (never rotates into a regressed stamp)
+                if (this._stampAdvanced(this._stampNow()))
                     await this._rotate("time");
                 await this._ensureOpen();
                 if (this.maxSize > 0 &&
@@ -435,6 +468,22 @@ class RotateFileStream extends node_stream.Writable {
             ? base.replace(/\.[^.]+$/, `.${index}$&`)
             : `${base}.${index}`;
     }
+    /**
+     * true only when the period legally advanced. A regressed
+     * clock (NTP correction, manual change) never reopens a past family:
+     * writes continue in the current segment until real time catches up.
+     * Requires zero-padded datePattern tokens (documented assumption).
+     */
+    _stampAdvanced(stamp) {
+        if (stamp > this._curStamp)
+            return true;
+        if (stamp < this._curStamp && !this._warnedBackward) {
+            this._warnedBackward = true;
+            this.emit("warn", new Error(`clock moved backward (stamp ${stamp} < ${this._curStamp}); ` +
+                "keeping current segment until the clock catches up"));
+        }
+        return false;
+    }
     /**
      * Highest viable segment index for `stamp`.
      * Disk is truth: resume a raw tail; start after sealed ones.
@@ -479,6 +528,9 @@ class RotateFileStream extends node_stream.Writable {
         this._path = p;
         if (this._auditEnabled) {
             const base = path.basename(p);
+            // reopen = NEW incarnation. Never inherit lifecycle
+            // fields from the previous record (observed in the wild as
+            // abandonedAt < openedAt on reactivated segments).
             this._audit.files[base] = {
                 index: this._index,
                 state: "active",
@@ -530,10 +582,11 @@ class RotateFileStream extends node_stream.Writable {
                 }
             }
             else if (realBytes === 0) {
+                // a concurrent writer may have archived this segment
+                // between our last stat and now — adopt its artifact instead of
+                // recording a false `drop-empty` that orphans the .gz.
                 const adoptedGz = `${oldPath}.gz`;
                 if (existsSafe(adoptedGz)) {
-                    // A concurrent writer archived this segment between our last stat
-                    // and now — adopt its artifact instead of dropping the record.
                     this._finishArchivedRecord(oldBase);
                     archive = adoptedGz;
                 }
@@ -541,38 +594,54 @@ class RotateFileStream extends node_stream.Writable {
                     try {
                         fs.unlinkSync(oldPath);
                     }
-                    catch { /* already gone */ }
+                    catch {
+                        /* already gone */
+                    }
                     if (rec)
                         delete this._audit.files[oldBase];
                     this._aevent("drop-empty", { file: oldBase });
                 }
             }
-            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 });
-                this._saveAudit();
+            else if (rec) {
+                rec.state = "sealed";
+                rec.bytes = realBytes;
             }
-            if (kind === "time" || kind === "manual")
-                this._armTimer();
-            if (oldPath) {
-                this.emit("rotated", {
-                    reason: kind,
-                    oldFile: oldPath,
-                    archive,
-                    newFile: this._resolveName(stamp, this._index),
-                });
+        }
+        let stamp = this._stampNow();
+        // a rotation itself must never move the series backward
+        // (covers rotateNow()/interval/size paths the upstream guards miss)
+        if (stamp < this._curStamp) {
+            if (!this._warnedBackward) {
+                this._warnedBackward = true;
+                this.emit("warn", new Error(`clock moved backward (stamp ${stamp} < ${this._curStamp}); ` +
+                    "rotation clamped to the current period"));
             }
-            this._retire();
+            stamp = this._curStamp;
+        }
+        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 });
+            this._saveAudit();
+        }
+        if (kind === "time" || kind === "manual")
+            this._armTimer();
+        if (oldPath) {
+            this.emit("rotated", {
+                reason: kind,
+                oldFile: oldPath,
+                archive,
+                newFile: this._resolveName(stamp, this._index),
+            });
         }
+        this._retire();
     }
     /* ==================================================================
      * Timers
@@ -590,16 +659,26 @@ class RotateFileStream extends node_stream.Writable {
         const next = this.freq.type === "daily"
             ? nextMidnight(this.tz, now)
             : nextAligned(now, this.freq.ms);
+        // anti-spin. A backward clock can put the computed
+        // boundary in the past; poll gently instead of firing every 100 ms.
+        const delta = next - this._now();
+        const delay = delta < 0 ? TIMER_POLL_MS : Math.max(100, delta);
         this._timer = setTimeout(() => {
             this._job(async () => {
                 const stamp = this._stampNow();
-                const dueDaily = this.freq.type === "daily" && stamp !== this._curStamp;
-                const dueInterval = this.freq.type !== "daily";
-                if (dueDaily || dueInterval) {
+                if (this.freq.type !== "daily") {
+                    /* interval rotation is schedule-based; runs regardless of
+                       stamp movement */
+                    if (this._hasContent())
+                        await this._rotate("time");
+                }
+                else if (this._stampAdvanced(stamp)) {
+                    // guarded daily branch
                     if (this._hasContent()) {
                         await this._rotate("time");
                     }
-                    else if (stamp !== this._curStamp) {
+                    else {
+                        /* idle boundary slide — no file created for empty days */
                         this._curStamp = stamp;
                         this._index = this._recoverIndexFor(stamp);
                         if (this._auditEnabled) {
@@ -610,9 +689,10 @@ class RotateFileStream extends node_stream.Writable {
                         this.emit("period", stamp);
                     }
                 }
+                /* stamp regressed or unchanged → keep current segment, re-arm */
                 this._armTimer();
             }).catch(() => { });
-        }, Math.max(100, next - this._now()));
+        }, delay);
         if (this.unrefTimers)
             this._timer.unref();
     }
@@ -636,7 +716,8 @@ class RotateFileStream extends node_stream.Writable {
         this._offsetMs += this._stepMs;
         this._armTimer();
         const stamp = this._stampNow();
-        if (stamp !== this._curStamp) {
+        // guarded crossing (virtual clock can't roll backward either)
+        if (this._stampAdvanced(stamp)) {
             if (this._hasContent()) {
                 await this._rotate("time");
             }
@@ -674,7 +755,15 @@ class RotateFileStream extends node_stream.Writable {
             parsed = JSON.parse(fs.readFileSync(this._auditPath, "utf8"));
         }
         catch {
-            return false; // missing/unreadable → fresh start
+            // unparseable manifest is quarantined too (was silently
+            // clobbered by the first save — caught by the quarantine test)
+            try {
+                fs.renameSync(this._auditPath, `${this._auditPath}.corrupt`);
+            }
+            catch {
+                /* ignore */
+            }
+            return false;
         }
         const j = parsed;
         if (!j || j.version !== 1 || j.prefix !== this._tL || j.ext !== this._tExt) {
@@ -811,6 +900,59 @@ class RotateFileStream extends node_stream.Writable {
             delete this._audit.files[name];
         }
     }
+    /**
+     * DISK-DRIVEN seal. Seal raw segments whose period has
+     * already passed (crash near midnight, virtual-clock leftovers,
+     * untracked/pruned files). Iterates the DIRECTORY, not the manifest:
+     * the filesystem is the source of truth; the manifest is an index.
+     */
+    async _sealOrphanedPastStamps() {
+        if (!this.zippedArchive)
+            return;
+        const stampRx = new RegExp("^" + escRe(this._tL) + "(.+?)" + escRe(this._tMid) +
+            "(?:\\.\\d+)?" + escRe(this._tExt) + "(?:\\.gz)?$");
+        let names = [];
+        try {
+            names = fs.readdirSync(this.dir);
+        }
+        catch {
+            return;
+        }
+        for (const name of names) {
+            if (name.endsWith(".gz"))
+                continue;
+            if (name === (this._path && path.basename(this._path)))
+                continue;
+            const stamp = stampRx.exec(name)?.[1];
+            // lexicographic compare is safe for zero-padded patterns (YYYY-MM-DD…);
+            // also guards the current stamp and anything future-dated
+            if (!stamp || stamp >= this._curStamp)
+                continue;
+            const full = path.join(this.dir, name);
+            if (!existsSafe(full) || statSizeSafe(full) === 0)
+                continue;
+            const ok = await gzipMove(full, `${full}.gz`, (e) => this.emit("warn", e));
+            if (!ok)
+                continue;
+            if (this._auditEnabled && this._audit.files[name]) {
+                // tracked → re-key record name → name.gz (emits archive + journal)
+                this._finishArchivedRecord(name, true);
+            }
+            else {
+                // untracked → record it fresh so future reconciles see truth
+                const gzName = `${name}.gz`;
+                if (this._auditEnabled) {
+                    this._audit.files[gzName] = {
+                        state: "archived",
+                        gzipPending: false,
+                        archivedAt: new Date().toISOString(),
+                    };
+                    this._aevent("seal-past", { file: gzName });
+                }
+                this.emit("archive", path.join(this.dir, gzName));
+            }
+        }
+    }
     async _repairInterruptedGzips() {
         for (const [name, rec] of Object.entries(this._audit.files)) {
             if (!rec.gzipPending)
@@ -863,59 +1005,6 @@ class RotateFileStream extends node_stream.Writable {
         this.emit("archive", path.join(this.dir, gzName));
         this._aevent("archive", { file: gzName, ...(repaired && { repaired }) });
     }
-    /**
- * Seal raw segments whose period has already passed (crash near midnight,
- * virtual-clock leftovers, untracked files). Disk is the source of truth —
- * manifest-tracked or not, a raw tail nothing will ever write to again
- * must still honour zippedArchive.
- */
-    async _sealOrphanedPastStamps() {
-        if (!this.zippedArchive)
-            return;
-        const stampRx = new RegExp("^" + escRe(this._tL) + "(.+?)" + escRe(this._tMid) +
-            "(?:\\.\\d+)?" + escRe(this._tExt) + "(?:\\.gz)?$");
-        let names = [];
-        try {
-            names = fs.readdirSync(this.dir);
-        }
-        catch {
-            return;
-        }
-        for (const name of names) {
-            if (name.endsWith(".gz"))
-                continue;
-            if (name === (this._path && path.basename(this._path)))
-                continue;
-            const stamp = stampRx.exec(name)?.[1];
-            // lexicographic compare is safe for zero-padded patterns (YYYY-MM-DD…);
-            // also guards the current stamp and anything future-dated
-            if (!stamp || stamp >= this._curStamp)
-                continue;
-            const full = path.join(this.dir, name);
-            if (!existsSafe(full) || statSizeSafe(full) === 0)
-                continue;
-            const ok = await gzipMove(full, `${full}.gz`, (e) => this.emit("warn", e));
-            if (!ok)
-                continue;
-            if (this._auditEnabled && this._audit.files[name]) {
-                // tracked → re-key record name → name.gz (emits archive + journal)
-                this._finishArchivedRecord(name, true);
-            }
-            else {
-                // untracked → record it fresh so future reconciles see a truthful state
-                const gzName = `${name}.gz`;
-                if (this._auditEnabled) {
-                    this._audit.files[gzName] = {
-                        state: "archived",
-                        gzipPending: false,
-                        archivedAt: new Date().toISOString(),
-                    };
-                    this._aevent("seal-past", { file: gzName });
-                }
-                this.emit("archive", path.join(this.dir, gzName));
-            }
-        }
-    }
     /* ==================================================================
      * Retention
      * ================================================================ */

package/dist/index.esm.js

@@ -1,4 +1,4 @@
-/*! logroller v2.0.0 | MIT License */
+/*! logroller v2.0.1 | MIT License */
 import { randomUUID } from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
@@ -50,12 +50,21 @@ const UNITS = {
 const FREQ_MULT = {
     ms: 1, s: 1000, m: 60_000, h: 3_600_000,
 };
+function parseDuration(value, defaultUnit, fieldName) {
+    if (typeof value === "number") {
+        return Math.round(value * FREQ_MULT[defaultUnit]);
+    }
+    const m = /^\s*(-?\d+(?:\.\d+)?)\s*(ms|s|m|h)?\s*$/i.exec(value);
+    if (!m)
+        throw new Error(`Invalid ${fieldName} "${value}"`);
+    return Math.round(Number.parseFloat(m[1]) * FREQ_MULT[(m[2] ?? defaultUnit).toLowerCase()]);
+}
 function parseSize(v) {
     if (v === undefined || v === null || v === 0)
         return 0;
     if (typeof v === "number")
         return v;
-    const m = /^\s*(\d+(?:\.\d+)?)\s*(b|k|kb|m|mb|g|gb)?\s*$/i.exec(v);
+    const m = /^\s*(\d+(?:\.\d+)?)\s*(b|kb|k|mb|m|gb|g)?\s*$/i.exec(v);
     if (!m)
         throw new Error(`Invalid maxSize "${v}"`);
     return Math.round(Number.parseFloat(m[1]) * (UNITS[m[2]?.toLowerCase()] ?? 1));
@@ -79,7 +88,7 @@ function parseFrequency(v) {
     if (v === "daily")
         return { type: "daily" };
     if (typeof v === "number") {
-        if (!(v > 0))
+        if (v <= 0)
             throw new Error(`Invalid frequency "${v}"`);
         return { type: "interval", ms: v };
     }
@@ -91,22 +100,12 @@ function parseFrequency(v) {
 function parseClockOffset(v) {
     if (v === undefined || v === null || v === "")
         return 0;
-    if (typeof v === "number")
-        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]) * 3_600_000);
+    return parseDuration(v, "h", "addHours");
 }
 function parseClockStep(v) {
-    if (v === undefined || v === null || v === "" || v === 0)
+    if (v === undefined || v === null || v === "")
         return 0;
-    if (typeof v === "number")
-        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}"`);
-    return Math.round(Number.parseFloat(m[1]) * FREQ_MULT[(m[2] ?? "h").toLowerCase()]);
+    return parseDuration(v, "h", "addHours");
 }
 
 /* Timezone-aware helpers built exclusively on Intl (zero deps). */
@@ -143,11 +142,30 @@ function partsIn(tz, date) {
 const pad2 = (n) => n.padStart(2, "0");
 /** Escape a literal string for embedding inside a RegExp. */
 function escRe(s) {
-    return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    return s.replace(/[.*+?^${}()|[\]\\]/g, String.raw `\$&`);
 }
 /** 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, (token) => {
+        switch (token) {
+            case "YYYY":
+                return parts.year;
+            case "YY":
+                return parts.year.slice(-2);
+            case "MM":
+                return pad2(parts.month);
+            case "DD":
+                return pad2(parts.day);
+            case "HH":
+                return pad2(parts.hour);
+            case "mm":
+                return pad2(parts.minute);
+            case "ss":
+                return pad2(parts.second);
+            default:
+                return token;
+        }
+    });
 }
 /** Offset of `tz` vs UTC at instant `date`, milliseconds. */
 function tzOffsetMs(tz, date) {
@@ -177,6 +195,7 @@ const BUMP_DEFAULT_MS = 60_000;
 const AUDIT_MAX_FILES = 600;
 const AUDIT_MAX_EVENTS = 200;
 const HEARTBEAT_STALE_MS = 30_000;
+const TIMER_POLL_MS = 1_000;
 const emptyAudit = (prefix, ext, datePattern, tz) => ({
     version: 1,
     prefix,
@@ -242,6 +261,7 @@ class RotateFileStream extends Writable {
     _bumpTimer = null;
     _ended = false;
     _tail = Promise.resolve();
+    _warnedBackward = false;
     _audit;
     constructor(opts = {}) {
         super(opts.highWaterMark ? { highWaterMark: opts.highWaterMark } : {});
@@ -294,14 +314,29 @@ class RotateFileStream extends Writable {
                 offsetMs: this._offsetMs,
             }));
         }
+        process.nextTick(() => {
+            const warn = (m) => this.emit("warn", new Error(m));
+            if (this.freq.type === "interval") {
+                if (this.freq.ms < 86_400_000 && !this.datePattern.includes("HH")) {
+                    warn(`frequency "${opts.frequency}" needs HH in datePattern — ` +
+                        "segments would collapse onto one filename");
+                }
+                if (this.freq.ms < 60_000 && !this.datePattern.includes("mm")) {
+                    warn(`frequency "${opts.frequency}" needs mm in datePattern`);
+                }
+            }
+            else if (!this.datePattern.includes("DD")) {
+                warn("daily frequency needs DD in datePattern");
+            }
+        });
         /* 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 () => {
+            await this._sealOrphanedPastStamps();
             if (this._auditEnabled) {
                 this._demoteZombieActives();
                 this._reconcileWithDisk();
-                await this._sealOrphanedPastStamps();
                 await this._repairInterruptedGzips();
                 this._aevent("boot", { stamp: this._curStamp, index: this._index });
                 this._saveAudit();
@@ -336,9 +371,7 @@ class RotateFileStream extends Writable {
     get currentIndex() {
         return this._index;
     }
-    /**
-     * Force an immediate rotation and resolve when the next slot is staged.
-     */
+    /** Force an immediate rotation and resolve when the next slot is staged. */
     rotateNow() {
         return this._job(() => this._rotate("manual"));
     }
@@ -361,8 +394,8 @@ class RotateFileStream extends Writable {
         const len = chunk.length;
         this._job(async () => {
             try {
-                const stamp = this._stampNow();
-                if (stamp !== this._curStamp)
+                // guarded roll (never rotates into a regressed stamp)
+                if (this._stampAdvanced(this._stampNow()))
                     await this._rotate("time");
                 await this._ensureOpen();
                 if (this.maxSize > 0 &&
@@ -433,6 +466,22 @@ class RotateFileStream extends Writable {
             ? base.replace(/\.[^.]+$/, `.${index}$&`)
             : `${base}.${index}`;
     }
+    /**
+     * true only when the period legally advanced. A regressed
+     * clock (NTP correction, manual change) never reopens a past family:
+     * writes continue in the current segment until real time catches up.
+     * Requires zero-padded datePattern tokens (documented assumption).
+     */
+    _stampAdvanced(stamp) {
+        if (stamp > this._curStamp)
+            return true;
+        if (stamp < this._curStamp && !this._warnedBackward) {
+            this._warnedBackward = true;
+            this.emit("warn", new Error(`clock moved backward (stamp ${stamp} < ${this._curStamp}); ` +
+                "keeping current segment until the clock catches up"));
+        }
+        return false;
+    }
     /**
      * Highest viable segment index for `stamp`.
      * Disk is truth: resume a raw tail; start after sealed ones.
@@ -477,6 +526,9 @@ class RotateFileStream extends Writable {
         this._path = p;
         if (this._auditEnabled) {
             const base = path.basename(p);
+            // reopen = NEW incarnation. Never inherit lifecycle
+            // fields from the previous record (observed in the wild as
+            // abandonedAt < openedAt on reactivated segments).
             this._audit.files[base] = {
                 index: this._index,
                 state: "active",
@@ -528,10 +580,11 @@ class RotateFileStream extends Writable {
                 }
             }
             else if (realBytes === 0) {
+                // a concurrent writer may have archived this segment
+                // between our last stat and now — adopt its artifact instead of
+                // recording a false `drop-empty` that orphans the .gz.
                 const adoptedGz = `${oldPath}.gz`;
                 if (existsSafe(adoptedGz)) {
-                    // A concurrent writer archived this segment between our last stat
-                    // and now — adopt its artifact instead of dropping the record.
                     this._finishArchivedRecord(oldBase);
                     archive = adoptedGz;
                 }
@@ -539,38 +592,54 @@ class RotateFileStream extends Writable {
                     try {
                         fs.unlinkSync(oldPath);
                     }
-                    catch { /* already gone */ }
+                    catch {
+                        /* already gone */
+                    }
                     if (rec)
                         delete this._audit.files[oldBase];
                     this._aevent("drop-empty", { file: oldBase });
                 }
             }
-            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 });
-                this._saveAudit();
+            else if (rec) {
+                rec.state = "sealed";
+                rec.bytes = realBytes;
             }
-            if (kind === "time" || kind === "manual")
-                this._armTimer();
-            if (oldPath) {
-                this.emit("rotated", {
-                    reason: kind,
-                    oldFile: oldPath,
-                    archive,
-                    newFile: this._resolveName(stamp, this._index),
-                });
+        }
+        let stamp = this._stampNow();
+        // a rotation itself must never move the series backward
+        // (covers rotateNow()/interval/size paths the upstream guards miss)
+        if (stamp < this._curStamp) {
+            if (!this._warnedBackward) {
+                this._warnedBackward = true;
+                this.emit("warn", new Error(`clock moved backward (stamp ${stamp} < ${this._curStamp}); ` +
+                    "rotation clamped to the current period"));
             }
-            this._retire();
+            stamp = this._curStamp;
+        }
+        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 });
+            this._saveAudit();
+        }
+        if (kind === "time" || kind === "manual")
+            this._armTimer();
+        if (oldPath) {
+            this.emit("rotated", {
+                reason: kind,
+                oldFile: oldPath,
+                archive,
+                newFile: this._resolveName(stamp, this._index),
+            });
         }
+        this._retire();
     }
     /* ==================================================================
      * Timers
@@ -588,16 +657,26 @@ class RotateFileStream extends Writable {
         const next = this.freq.type === "daily"
             ? nextMidnight(this.tz, now)
             : nextAligned(now, this.freq.ms);
+        // anti-spin. A backward clock can put the computed
+        // boundary in the past; poll gently instead of firing every 100 ms.
+        const delta = next - this._now();
+        const delay = delta < 0 ? TIMER_POLL_MS : Math.max(100, delta);
         this._timer = setTimeout(() => {
             this._job(async () => {
                 const stamp = this._stampNow();
-                const dueDaily = this.freq.type === "daily" && stamp !== this._curStamp;
-                const dueInterval = this.freq.type !== "daily";
-                if (dueDaily || dueInterval) {
+                if (this.freq.type !== "daily") {
+                    /* interval rotation is schedule-based; runs regardless of
+                       stamp movement */
+                    if (this._hasContent())
+                        await this._rotate("time");
+                }
+                else if (this._stampAdvanced(stamp)) {
+                    // guarded daily branch
                     if (this._hasContent()) {
                         await this._rotate("time");
                     }
-                    else if (stamp !== this._curStamp) {
+                    else {
+                        /* idle boundary slide — no file created for empty days */
                         this._curStamp = stamp;
                         this._index = this._recoverIndexFor(stamp);
                         if (this._auditEnabled) {
@@ -608,9 +687,10 @@ class RotateFileStream extends Writable {
                         this.emit("period", stamp);
                     }
                 }
+                /* stamp regressed or unchanged → keep current segment, re-arm */
                 this._armTimer();
             }).catch(() => { });
-        }, Math.max(100, next - this._now()));
+        }, delay);
         if (this.unrefTimers)
             this._timer.unref();
     }
@@ -634,7 +714,8 @@ class RotateFileStream extends Writable {
         this._offsetMs += this._stepMs;
         this._armTimer();
         const stamp = this._stampNow();
-        if (stamp !== this._curStamp) {
+        // guarded crossing (virtual clock can't roll backward either)
+        if (this._stampAdvanced(stamp)) {
             if (this._hasContent()) {
                 await this._rotate("time");
             }
@@ -672,7 +753,15 @@ class RotateFileStream extends Writable {
             parsed = JSON.parse(fs.readFileSync(this._auditPath, "utf8"));
         }
         catch {
-            return false; // missing/unreadable → fresh start
+            // unparseable manifest is quarantined too (was silently
+            // clobbered by the first save — caught by the quarantine test)
+            try {
+                fs.renameSync(this._auditPath, `${this._auditPath}.corrupt`);
+            }
+            catch {
+                /* ignore */
+            }
+            return false;
         }
         const j = parsed;
         if (!j || j.version !== 1 || j.prefix !== this._tL || j.ext !== this._tExt) {
@@ -809,6 +898,59 @@ class RotateFileStream extends Writable {
             delete this._audit.files[name];
         }
     }
+    /**
+     * DISK-DRIVEN seal. Seal raw segments whose period has
+     * already passed (crash near midnight, virtual-clock leftovers,
+     * untracked/pruned files). Iterates the DIRECTORY, not the manifest:
+     * the filesystem is the source of truth; the manifest is an index.
+     */
+    async _sealOrphanedPastStamps() {
+        if (!this.zippedArchive)
+            return;
+        const stampRx = new RegExp("^" + escRe(this._tL) + "(.+?)" + escRe(this._tMid) +
+            "(?:\\.\\d+)?" + escRe(this._tExt) + "(?:\\.gz)?$");
+        let names = [];
+        try {
+            names = fs.readdirSync(this.dir);
+        }
+        catch {
+            return;
+        }
+        for (const name of names) {
+            if (name.endsWith(".gz"))
+                continue;
+            if (name === (this._path && path.basename(this._path)))
+                continue;
+            const stamp = stampRx.exec(name)?.[1];
+            // lexicographic compare is safe for zero-padded patterns (YYYY-MM-DD…);
+            // also guards the current stamp and anything future-dated
+            if (!stamp || stamp >= this._curStamp)
+                continue;
+            const full = path.join(this.dir, name);
+            if (!existsSafe(full) || statSizeSafe(full) === 0)
+                continue;
+            const ok = await gzipMove(full, `${full}.gz`, (e) => this.emit("warn", e));
+            if (!ok)
+                continue;
+            if (this._auditEnabled && this._audit.files[name]) {
+                // tracked → re-key record name → name.gz (emits archive + journal)
+                this._finishArchivedRecord(name, true);
+            }
+            else {
+                // untracked → record it fresh so future reconciles see truth
+                const gzName = `${name}.gz`;
+                if (this._auditEnabled) {
+                    this._audit.files[gzName] = {
+                        state: "archived",
+                        gzipPending: false,
+                        archivedAt: new Date().toISOString(),
+                    };
+                    this._aevent("seal-past", { file: gzName });
+                }
+                this.emit("archive", path.join(this.dir, gzName));
+            }
+        }
+    }
     async _repairInterruptedGzips() {
         for (const [name, rec] of Object.entries(this._audit.files)) {
             if (!rec.gzipPending)
@@ -861,59 +1003,6 @@ class RotateFileStream extends Writable {
         this.emit("archive", path.join(this.dir, gzName));
         this._aevent("archive", { file: gzName, ...(repaired && { repaired }) });
     }
-    /**
- * Seal raw segments whose period has already passed (crash near midnight,
- * virtual-clock leftovers, untracked files). Disk is the source of truth —
- * manifest-tracked or not, a raw tail nothing will ever write to again
- * must still honour zippedArchive.
- */
-    async _sealOrphanedPastStamps() {
-        if (!this.zippedArchive)
-            return;
-        const stampRx = new RegExp("^" + escRe(this._tL) + "(.+?)" + escRe(this._tMid) +
-            "(?:\\.\\d+)?" + escRe(this._tExt) + "(?:\\.gz)?$");
-        let names = [];
-        try {
-            names = fs.readdirSync(this.dir);
-        }
-        catch {
-            return;
-        }
-        for (const name of names) {
-            if (name.endsWith(".gz"))
-                continue;
-            if (name === (this._path && path.basename(this._path)))
-                continue;
-            const stamp = stampRx.exec(name)?.[1];
-            // lexicographic compare is safe for zero-padded patterns (YYYY-MM-DD…);
-            // also guards the current stamp and anything future-dated
-            if (!stamp || stamp >= this._curStamp)
-                continue;
-            const full = path.join(this.dir, name);
-            if (!existsSafe(full) || statSizeSafe(full) === 0)
-                continue;
-            const ok = await gzipMove(full, `${full}.gz`, (e) => this.emit("warn", e));
-            if (!ok)
-                continue;
-            if (this._auditEnabled && this._audit.files[name]) {
-                // tracked → re-key record name → name.gz (emits archive + journal)
-                this._finishArchivedRecord(name, true);
-            }
-            else {
-                // untracked → record it fresh so future reconciles see a truthful state
-                const gzName = `${name}.gz`;
-                if (this._auditEnabled) {
-                    this._audit.files[gzName] = {
-                        state: "archived",
-                        gzipPending: false,
-                        archivedAt: new Date().toISOString(),
-                    };
-                    this._aevent("seal-past", { file: gzName });
-                }
-                this.emit("archive", path.join(this.dir, gzName));
-            }
-        }
-    }
     /* ==================================================================
      * Retention
      * ================================================================ */

package/dist/rotate-file-stream.d.ts

@@ -1,6 +1,6 @@
 import { Writable } from "node:stream";
 import { type ParsedFrequency, type ParsedMaxFiles } from "./parsers.js";
-import type { RotateFileStreamEventMap, RotateFileStreamOptions } from "./types";
+import type { RotateFileStreamEventMap, RotateFileStreamOptions } from "./types.js";
 /**
  * A `Writable` that appends to dated log files, rolling segments on time
  * and/or size, optionally gzipping sealed segments, enforcing retention,
@@ -37,8 +37,8 @@ export declare class RotateFileStream extends Writable {
     private readonly _auditPath;
     private readonly _bootId;
     private _offsetMs;
-    private readonly _stepMs;
-    private readonly _bumpEvery;
+    private _stepMs;
+    private _bumpEvery;
     private _curStamp;
     private _index;
     private _ws;
@@ -48,6 +48,7 @@ export declare class RotateFileStream extends Writable {
     private _bumpTimer;
     private _ended;
     private _tail;
+    private _warnedBackward;
     private _audit;
     constructor(opts?: Partial<RotateFileStreamOptions>);
     on<E extends keyof RotateFileStreamEventMap>(event: E, listener: (...args: RotateFileStreamEventMap[E]) => void): this;
@@ -60,9 +61,7 @@ export declare class RotateFileStream extends Writable {
     get filename(): string | null;
     /** Index of the active segment within the current period. */
     get currentIndex(): number;
-    /**
-     * Force an immediate rotation and resolve when the next slot is staged.
-     */
+    /** Force an immediate rotation and resolve when the next slot is staged. */
     rotateNow(): Promise<void>;
     /**
      * Apply ONE virtual-clock tick immediately (bypasses the interval timer
@@ -77,6 +76,13 @@ export declare class RotateFileStream extends Writable {
     private _now;
     private _stampNow;
     private _resolveName;
+    /**
+     * true only when the period legally advanced. A regressed
+     * clock (NTP correction, manual change) never reopens a past family:
+     * writes continue in the current segment until real time catches up.
+     * Requires zero-padded datePattern tokens (documented assumption).
+     */
+    private _stampAdvanced;
     /**
      * Highest viable segment index for `stamp`.
      * Disk is truth: resume a raw tail; start after sealed ones.
@@ -100,16 +106,16 @@ export declare class RotateFileStream extends Writable {
     private _demoteZombieActives;
     /** Heal audit-vs-disk divergence after crashes / external tampering. */
     private _reconcileWithDisk;
+    /**
+     * DISK-DRIVEN seal. Seal raw segments whose period has
+     * already passed (crash near midnight, virtual-clock leftovers,
+     * untracked/pruned files). Iterates the DIRECTORY, not the manifest:
+     * the filesystem is the source of truth; the manifest is an index.
+     */
+    private _sealOrphanedPastStamps;
     private _repairInterruptedGzips;
     /** Seal a record; re-key `name` → `name.gz` so scans stop ghosting. */
     private _finishArchivedRecord;
-    /**
- * Seal raw segments whose period has already passed (crash near midnight,
- * virtual-clock leftovers, untracked files). Disk is the source of truth —
- * manifest-tracked or not, a raw tail nothing will ever write to again
- * must still honour zippedArchive.
- */
-    private _sealOrphanedPastStamps;
     private _retire;
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "logroller",
-  "version": "2.0.1",
+  "version": "2.0.2",
   "description": "Zero-dependency rotating file stream for Node.js — daily/interval/size rotation, gzip archives, retention, timezone-aware, crash-safe resume",
   "license": "MIT",
   "author": "Vinau",