@wrongstack/core 0.301.0 → 0.302.2

package/dist/chronicle/rollup-adapter.d.ts

@@ -7,6 +7,8 @@ export interface ChronicleRollupAdapterOptions {
     journal: ChronicleEventSink;
     context: ChronicleContext | (() => ChronicleContext);
     windowMs?: number;
+    /** Aggregation window for periodic gauges; see {@link DEFAULT_GAUGE_WINDOW_MS}. */
+    gaugeWindowMs?: number;
     onPersistError?: ((error: unknown, event: ChronicleEventInput) => void) | undefined;
 }
 /** Converts high-frequency ephemeral signals into bounded window aggregates before persistence. */

package/dist/chronicle/sqlite-journal.d.ts

@@ -66,10 +66,27 @@ export declare class ChronicleSqliteJournal {
     private readonly maxEvents;
     private readonly maxBytes;
     private readonly retentionCheckIntervalMs;
+    /** Overshoot allowed above `maxEvents` before eviction runs; see TRIM_SLACK_RATIO. */
+    private readonly trimSlack;
     private nextRetentionCheckAt;
     private retainedEventCount;
     /** Resolved lazily by `pageSizeBytes()`; constant for an open database. */
     private cachedPageSize;
+    /**
+     * Bytes the quota is known to have had spare at the last real measurement,
+     * and the bytes appended since. `assertWithinByteQuota` re-measures only once
+     * the second could plausibly have consumed the first — see its comment.
+     */
+    private quotaHeadroomBytes;
+    private bytesSinceQuotaCheck;
+    /**
+     * Statements reused across appends.
+     *
+     * `db.prepare` re-parses the SQL every call, and the append path used to
+     * prepare five statements per batch. They are held rather than re-prepared
+     * because the schema cannot change under an open journal.
+     */
+    private statements;
     /**
      * Cached chain head per day. Cleared wholesale on any write failure so the
      * next append rebuilds from the database rather than trusting a counter that
@@ -136,8 +153,47 @@ export declare class ChronicleSqliteJournal {
     /** Page size never changes for an open database; resolve it once. */
     private pageSizeBytes;
     private normalizeQuotaError;
+    /** Drop the cached headroom so the next quota check measures for real. */
+    private invalidateQuotaEstimate;
     private assertActualAllocationWithinQuota;
+    /**
+     * Refuse a batch that would take the journal past its byte quota.
+     *
+     * This is the *courteous* bound, not the enforced one: `max_page_count` makes
+     * SQLite itself fail the write with `SQLITE_FULL`, which `normalizeQuotaError`
+     * turns into the same {@link ChronicleStorageQuotaError}. Its only job is to
+     * produce that error before a doomed batch has been written, so it does not
+     * have to run on every append — and it should not, because measuring costs two
+     * PRAGMA round trips and three `statSync` calls, twice per transaction.
+     *
+     * So it measures adaptively instead of on a fixed cadence: after a real
+     * measurement it knows the spare bytes, and it may skip until the bytes
+     * appended since then could plausibly have consumed half of them. Far from the
+     * ceiling that is thousands of appends; close to it, every one. The bound
+     * tightens exactly where being wrong would matter.
+     */
     private assertWithinByteQuota;
+    /**
+     * Is the cached headroom still large enough to vouch for this batch?
+     *
+     * Half the headroom is the budget deliberately: rows carry index and page
+     * overhead beyond their payload bytes, so `bytesSinceQuotaCheck` understates
+     * real growth, and the factor absorbs that without needing to model it.
+     */
+    private shouldMeasureQuota;
+    private recordQuotaHeadroom;
+    /**
+     * Evict the oldest events once the row ceiling has been overshot by `trimSlack`.
+     *
+     * @param count Rows now in the table. The caller tracks this rather than the
+     * method querying it: `SELECT COUNT(*)` walks the whole table, and at the
+     * ceiling — where every long-lived journal lives — that was a full scan of
+     * `maxEvents` rows on every append, to learn a number the append path already
+     * knew. The count is re-derived from the database whenever it could have
+     * drifted (open, import, purge), never accumulated blindly across those.
+     * @param slack Overshoot tolerated before evicting; callers that run once,
+     * rather than per append, pass 0 to land on the exact ceiling.
+     */
     private enforceEventLimitWithinTransaction;
     private enforceEventLimitAtStartup;
     /**
@@ -200,6 +256,9 @@ export declare class ChronicleSqliteJournal {
     hasImportedDay(day: string): boolean;
     /** Day families the legacy import refused to move, oldest first. */
     quarantinedFamilies(): ChronicleQuarantinedFamily[];
+    private preparedStatements;
+    /** Rows currently in the table, straight from the database. */
+    private countRows;
     private readMeta;
     private readCheckpoint;
     /** Days that currently hold at least one event, oldest first. */