logroller 2.0.1 → 2.1.0

package/dist/index.esm.js

@@ -1,4 +1,4 @@
-/*! logroller v2.0.0 | MIT License */
+/*! logroller v2.1.0 | MIT License */
 import { randomUUID } from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
@@ -24,13 +24,13 @@ const existsSafe = (p) => {
     }
 };
 /**
- * Compress `src` → `dst`, deleting `src` ONLY on verified success.
- * On failure removes the partial `dst` and reports via callback —
+ * Compress `src` → `dst` at gzip `level`, 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) {
+async function gzipMove(src, dst, onWarn, level = 6) {
     try {
-        await pipeline(fs.createReadStream(src), zlib.createGzip({ level: 6 }), fs.createWriteStream(dst));
+        await pipeline(fs.createReadStream(src), zlib.createGzip({ level }), fs.createWriteStream(dst));
         await fs.promises.unlink(src);
         return true;
     }
@@ -43,19 +43,54 @@ async function gzipMove(src, dst, onWarn) {
 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,
+    b: 1,
+    k: 1024,
+    kb: 1024,
+    m: 1048576,
+    mb: 1048576,
+    g: 1073741824,
+    gb: 1073741824,
 };
-const FREQ_MULT = {
-    ms: 1, s: 1000, m: 60_000, h: 3_600_000,
+/**
+ * Every unit token the duration regex can capture MUST have an entry here —
+ * a captured-but-unmapped unit would otherwise surface as a NaN that
+ * detonates later (e.g. `RangeError: Invalid time value` from Intl),
+ * far away from the actual misconfiguration.
+ */
+const DURATION_ALIASES = {
+    ms: 1,
+    s: 1_000,
+    m: 60_000,
+    h: 3_600_000,
+    hour: 3_600_000,
+    hours: 3_600_000,
 };
+/**
+ * Parse `"<n><unit?>"` or a bare number into milliseconds.
+ * Bare numbers are interpreted in `defaultUnit`.
+ *
+ * Accepted unit spellings: ms, s, m, h, hour, hours (case-insensitive).
+ */
+function parseDuration(value, defaultUnit, fieldName) {
+    if (typeof value === "number") {
+        return Math.round(value * DURATION_ALIASES[defaultUnit]);
+    }
+    const m = /^\s*(-?\d+(?:\.\d+)?)\s*(h(?:our)?s?|ms|s|m)?\s*$/i.exec(value);
+    if (!m)
+        throw new Error(`Invalid ${fieldName} "${value}"`);
+    const unit = (m[2] ?? defaultUnit).toLowerCase();
+    const mult = DURATION_ALIASES[unit];
+    if (mult === undefined) {
+        throw new Error(`Invalid ${fieldName} unit "${m[2]}" in "${value}"`);
+    }
+    return Math.round(Number.parseFloat(m[1]) * mult);
+}
 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));
@@ -63,8 +98,11 @@ function parseSize(v) {
 function parseMaxFiles(v) {
     if (v === undefined || v === null || v === "" || v === 0)
         return null;
-    if (typeof v === "number")
+    if (typeof v === "number") {
+        if (v < 0)
+            throw new Error(`Invalid maxFiles "${v}"`);
         return { count: v };
+    }
     const m = /^\s*(\d+)\s*d\s*$/i.exec(v);
     if (m)
         return { days: Number.parseInt(m[1], 10) };
@@ -79,7 +117,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 };
     }
@@ -88,25 +126,23 @@ function parseFrequency(v) {
         throw new Error(`Invalid frequency "${v}"`);
     return { type: "interval", ms: Number.parseInt(m[1], 10) * FREQ_MULT[m[2].toLowerCase()] };
 }
+const FREQ_MULT = {
+    ms: 1,
+    s: 1_000,
+    m: 60_000,
+    h: 3_600_000,
+};
+/** Static virtual-clock shift. Accepts hours by default; h/hours/m/s/ms. */
 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");
 }
+/** Per-tick virtual-clock step. Accepts hours by default; h/hours/m/s/ms. */
 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", "addHoursEveryMin");
 }
 
 /* Timezone-aware helpers built exclusively on Intl (zero deps). */
@@ -143,11 +179,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 +232,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,
@@ -193,17 +249,22 @@ const emptyAudit = (prefix, ext, datePattern, tz) => ({
 });
 /**
  * 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.
+ * and/or size, optionally gzipping sealed segments, enforcing retention
+ * (count, age, and total-byte budget), maintaining a stable "current"
+ * symlink for log collectors, running an awaited seal hook (upload
+ * pipeline), and resuming an unbroken series across restarts via disk
+ * scan + audit manifest.
  *
  * @example
  * ```ts
  * const log = createStream({
  *   filename: "logs/app-%DATE%.log",
  *   maxSize: "20m",
+ *   maxTotalSize: "5g",
  *   maxFiles: "90d",
  *   zippedArchive: true,
+ *   symlink: true,
+ *   onSeal: async ({ gz }) => uploadToS3(gz),
  * });
  * log.write("hello\n");          // or: readable.pipe(log)
  * ```
@@ -218,6 +279,7 @@ class RotateFileStream extends Writable {
     maxFiles;
     freq;
     unrefTimers;
+    maxTotalSize;
     /* ---- filename-template pieces ---- */
     _tL;
     _tMid;
@@ -228,6 +290,10 @@ class RotateFileStream extends Writable {
     _auditEnabled;
     _auditPath;
     _bootId = randomUUID();
+    _onSeal;
+    _sealHookTimeoutMs;
+    _compressionLevel;
+    _symlinkPath = null;
     /* ---- virtual test clock ---- */
     _offsetMs;
     _stepMs;
@@ -242,6 +308,7 @@ class RotateFileStream extends Writable {
     _bumpTimer = null;
     _ended = false;
     _tail = Promise.resolve();
+    _warnedBackward = false;
     _audit;
     constructor(opts = {}) {
         super(opts.highWaterMark ? { highWaterMark: opts.highWaterMark } : {});
@@ -257,11 +324,16 @@ class RotateFileStream extends Writable {
         this.zippedArchive = !!opts.zippedArchive;
         this.maxSize = parseSize(opts.maxSize ?? 0);
         this.maxFiles = parseMaxFiles(opts.maxFiles);
+        this.maxTotalSize = parseSize(opts.maxTotalSize ?? 0);
         this.freq = parseFrequency(opts.frequency);
         this.unrefTimers = !!opts.unrefTimers;
         this._offsetMs = parseClockOffset(opts.addHours);
         this._stepMs = parseClockStep(opts.addHoursEveryMin);
         this._bumpEvery = Math.max(50, opts.clockStepIntervalMs ?? BUMP_DEFAULT_MS);
+        // compression + seal hook
+        this._compressionLevel = Math.min(9, Math.max(0, opts.compressionLevel ?? 6));
+        this._onSeal = opts.onSeal;
+        this._sealHookTimeoutMs = Math.max(0, opts.sealHookTimeoutMs ?? 30_000);
         /* 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%");
@@ -278,6 +350,12 @@ class RotateFileStream extends Writable {
         const stem = (this._tL.replace(/[^\w.-]+/g, "") || "log")
             .replace(/^[-.]+|[-.]+$/g, "");
         this._auditPath = path.join(this.dir, opts.auditFile || `${stem}_audit.json`);
+        // stable "current" pointer target
+        this._symlinkPath = opts.symlink
+            ? path.join(this.dir, typeof opts.symlink === "string"
+                ? opts.symlink
+                : `${stem}-current.log`)
+            : null;
         fs.mkdirSync(this.dir, { recursive: true });
         this._curStamp = this._stampNow();
         this._audit = emptyAudit(this._tL, this._tExt, this.datePattern, this.tz);
@@ -294,20 +372,37 @@ class RotateFileStream extends Writable {
                 offsetMs: this._offsetMs,
             }));
         }
+        // warn when frequency is finer than the datePattern tokens
+        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 () => {
+            // disk-driven, audit-independent (runs even with audit:false)
+            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();
             }
-            if (this.maxFiles)
-                this._retire();
+            if (this.maxFiles || this.maxTotalSize > 0)
+                this._retire(); // budget policy also gates
         }).catch(() => { });
         this._armTimer();
         this._armBump();
@@ -336,9 +431,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"));
     }
@@ -350,6 +443,60 @@ class RotateFileStream extends Writable {
     advanceClock() {
         return this._job(() => this._applyBump());
     }
+    /**
+     * Every family file on disk, oldest stamp first.
+     * Disk is truth: untracked files are reported with state "untracked".
+     */
+    listSegments() {
+        const rx = new RegExp("^" + escRe(this._tL) + "(.+?)" + escRe(this._tMid) +
+            "(?:\\.(\\d+))?" + escRe(this._tExt) + "(?:\\.gz)?$");
+        const skip = this._symlinkPath && path.basename(this._symlinkPath);
+        const out = [];
+        let names = [];
+        try {
+            names = fs.readdirSync(this.dir);
+        }
+        catch {
+            return out;
+        }
+        for (const n of names) {
+            if (n === skip)
+                continue;
+            const m = rx.exec(n);
+            if (!m)
+                continue;
+            const rec = this._audit.files[n];
+            out.push({
+                file: path.join(this.dir, n),
+                stamp: m[1],
+                index: m[2] ? Number.parseInt(m[2], 10) : 0,
+                gzipped: n.endsWith(".gz"),
+                bytes: statSizeSafe(path.join(this.dir, n)),
+                state: rec?.state ?? "untracked",
+                openedAt: rec?.openedAt,
+                archivedAt: rec?.archivedAt,
+            });
+        }
+        out.sort((a, b) => a.stamp.localeCompare(b.stamp) || a.index - b.index);
+        return out;
+    }
+    /**
+     * Health-check snapshot for dashboards and support triage.
+     */
+    stats() {
+        const segs = this.listSegments();
+        return {
+            dir: this.dir,
+            currentStamp: this._curStamp,
+            activeFile: this._path,
+            activeIndex: this._index,
+            segments: segs.length,
+            archived: segs.filter((s) => s.gzipped).length,
+            totalBytes: segs.reduce((sum, s) => sum + s.bytes, 0),
+            clockOffsetMs: this._offsetMs,
+            symlink: this._symlinkPath,
+        };
+    }
     /* ==================================================================
      * Writable contract
      * ================================================================ */
@@ -361,8 +508,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 +580,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.
@@ -466,6 +629,57 @@ class RotateFileStream extends Writable {
         }
         return idx;
     }
+    /**
+     * Atomically flip the "current" symlink to the active segment.
+     * tmp + rename so followers (`tail -f`, Filebeat) never observe a gap.
+     * Relative target keeps the link portable. Best-effort: filesystems
+     * denying symlinks warn once and disable the feature permanently.
+     */
+    _updateSymlink() {
+        const link = this._symlinkPath;
+        if (!link || !this._path)
+            return;
+        const tmp = `${link}.tmp`;
+        try {
+            try {
+                fs.unlinkSync(tmp);
+            }
+            catch { /* absent */ }
+            fs.symlinkSync(path.basename(this._path), tmp, "file");
+            fs.renameSync(tmp, link);
+        }
+        catch (e) {
+            this._symlinkPath = null;
+            this.emit("warn", new Error(`symlink unavailable ("${link}"): ${e.message} — continuing without it`));
+        }
+    }
+    /**
+     * Await the user's onSeal hook with a hard timeout. Result or
+     * failure degrades to `warn` — a wedged upload must never stall rotation.
+     * Called BEFORE retention so uploads finish before deletion.
+     */
+    async _runSealHook(raw, gz) {
+        const hook = this._onSeal;
+        if (!hook)
+            return;
+        let timer;
+        try {
+            await Promise.race([
+                Promise.resolve().then(() => hook({ raw, gz })),
+                new Promise((_, reject) => {
+                    timer = setTimeout(() => reject(new Error(`onSeal hook timed out after ${this._sealHookTimeoutMs}ms ` +
+                        `(${path.basename(gz ?? raw)})`)), this._sealHookTimeoutMs);
+                }),
+            ]);
+        }
+        catch (err) {
+            this.emit("warn", err);
+        }
+        finally {
+            if (timer)
+                clearTimeout(timer);
+        }
+    }
     async _ensureOpen() {
         if (this._ws)
             return;
@@ -475,8 +689,12 @@ class RotateFileStream extends Writable {
         ws.on("error", (e) => this.emit("error", e));
         this._ws = ws;
         this._path = p;
+        this._updateSymlink(); // flip pointer on every open
         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",
@@ -514,9 +732,10 @@ class RotateFileStream extends Writable {
                     rec.bytes = realBytes;
                     this._saveAudit();
                 }
-                const ok = await gzipMove(oldPath, archive, (e) => this.emit("warn", e));
+                const ok = await gzipMove(oldPath, archive, (e) => this.emit("warn", e), this._compressionLevel);
                 if (ok) {
                     this._finishArchivedRecord(oldBase);
+                    await this._runSealHook(oldPath, archive);
                 }
                 else {
                     if (rec) {
@@ -525,52 +744,75 @@ class RotateFileStream extends Writable {
                     }
                     this._aevent("gzip-failed", { file: oldBase });
                     archive = null;
+                    await this._runSealHook(oldPath, null);
                 }
             }
             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;
+                    await this._runSealHook(oldPath, adoptedGz);
                 }
                 else {
                     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 (realBytes > 0) {
+                // uncompressed seal (zippedArchive off): still notify sealers
+                if (rec) {
+                    rec.state = "sealed";
+                    rec.bytes = realBytes;
+                }
+                await this._runSealHook(oldPath, null);
             }
-            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 +830,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 +860,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 +887,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 +926,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 +1071,60 @@ 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 gzName = `${full}.gz`;
+            const ok = await gzipMove(full, gzName, (e) => this.emit("warn", e), this._compressionLevel);
+            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
+                if (this._auditEnabled) {
+                    this._audit.files[gzName] = {
+                        state: "archived",
+                        gzipPending: false,
+                        archivedAt: new Date().toISOString(),
+                    };
+                    this._aevent("seal-past", { file: gzName });
+                }
+                this.emit("archive", gzName);
+            }
+            await this._runSealHook(full, gzName);
+        }
+    }
     async _repairInterruptedGzips() {
         for (const [name, rec] of Object.entries(this._audit.files)) {
             if (!rec.gzipPending)
@@ -829,11 +1145,13 @@ class RotateFileStream extends Writable {
                     /* ignore */
                 }
                 this._finishArchivedRecord(name, true);
+                await this._runSealHook(src, dst);
                 continue;
             }
-            const ok = await gzipMove(src, dst, (e) => this.emit("warn", e));
+            const ok = await gzipMove(src, dst, (e) => this.emit("warn", e), this._compressionLevel);
             if (ok) {
                 this._finishArchivedRecord(name, true);
+                await this._runSealHook(src, dst);
             }
             else {
                 rec.gzipPending = false;
@@ -861,72 +1179,24 @@ 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
      * ================================================================ */
     async _retire() {
         const policy = this.maxFiles;
-        if (!policy)
-            return;
+        if (!policy && this.maxTotalSize <= 0)
+            return; // budget gates too
         const activeBase = this._path && path.basename(this._path);
         const activeStem = activeBase?.replace(/(?:\.\d+)?(?:\.log|)(?:\.gz)?$/, "");
         const reserved = [
             path.basename(this._auditPath),
             `${path.basename(this._auditPath)}.tmp`,
             `${path.basename(this._auditPath)}.corrupt`,
+            // never eat the "current" pointer (or its tmp)
+            ...(this._symlinkPath
+                ? [path.basename(this._symlinkPath),
+                    `${path.basename(this._symlinkPath)}.tmp`]
+                : []),
         ];
         try {
             const dirEntries = await fs.promises.readdir(this.dir);
@@ -938,7 +1208,8 @@ class RotateFileStream extends Writable {
             for (const name of candidates) {
                 const full = path.join(this.dir, name);
                 try {
-                    stats.push({ full, mtimeMs: (await fs.promises.stat(full)).mtimeMs });
+                    const st = await fs.promises.stat(full);
+                    stats.push({ full, mtimeMs: st.mtimeMs, size: st.size }); // size
                 }
                 catch {
                     /* raced deletion */
@@ -946,18 +1217,30 @@ class RotateFileStream extends Writable {
             }
             stats.sort((a, b) => a.mtimeMs - b.mtimeMs); // oldest first
             const kill = new Set();
-            if (policy.days != null) {
+            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 (policy.count != null) {
+            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);
             }
+            // byte budget — delete OLDEST until under budget.
+            // The active segment is never a candidate, so only archives count.
+            if (this.maxTotalSize > 0) {
+                const survivors = stats.filter((f) => !kill.has(f.full)); // oldest→newest
+                let total = survivors.reduce((sum, f) => sum + f.size, 0);
+                let i = 0;
+                while (total > this.maxTotalSize && i < survivors.length) {
+                    kill.add(survivors[i].full);
+                    total -= survivors[i].size;
+                    i++;
+                }
+            }
             if (kill.size === 0)
                 return;
             for (const file of kill) {
@@ -985,4 +1268,64 @@ function createStream(options) {
     return new RotateFileStream(options);
 }
 
-export { RotateFileStream, createStream };
+const registry = new Set();
+let installed = false;
+let inProgress = false;
+/**
+ * Register streams for graceful shutdown: on SIGINT/SIGTERM every
+ * registered stream is ended — flushing buffered writes and finishing the
+ * audit manifest — before the process exits, with a hard deadline.
+ *
+ * Safe to call multiple times: process listeners install once, streams
+ * accumulate in the registry.
+ *
+ * Returns `flush()`, the same graceful end WITHOUT exiting — for tests
+ * and custom signal handling.
+ *
+ * @example
+ * const flush = installShutdown(logStream);
+ * process.on("exit", () => { void flush(); });
+ */
+function installShutdown(streams, opts = {}) {
+    const list = Array.isArray(streams) ? streams : [streams];
+    for (const s of list)
+        registry.add(s);
+    if (!installed) {
+        installed = true;
+        const timeoutMs = opts.timeoutMs ?? 5_000;
+        const code = opts.code ?? 0;
+        for (const sig of opts.signals ?? ["SIGINT", "SIGTERM"]) {
+            process.on(sig, () => {
+                void flushAll(timeoutMs).finally(() => process.exit(code));
+            });
+        }
+    }
+    return async () => {
+        // flush FIRST — flushAll() drains the registry, so unregistering
+        // before flushing would flush nothing (caught by the shutdown test)
+        await flushAll(opts.timeoutMs ?? 5_000);
+        for (const s of list)
+            registry.delete(s);
+    };
+}
+/**
+ * End every registered stream (flush buffered writes) with a deadline.
+ * Does NOT exit the process. Double-ending an already-ended stream is
+ * harmless — the error lands in the ignored callback.
+ */
+async function flushAll(timeoutMs = 5_000) {
+    if (inProgress)
+        return;
+    inProgress = true;
+    const deadline = setTimeout(() => process.exit(1), timeoutMs);
+    deadline.unref();
+    try {
+        await Promise.allSettled([...registry].map((s) => new Promise((res) => s.end(() => res()))));
+    }
+    finally {
+        clearTimeout(deadline);
+        inProgress = false;
+    }
+}
+
+export { RotateFileStream, createStream, flushAll, installShutdown };