@wrongstack/core 0.306.4 → 0.307.0

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

@@ -0,0 +1,39 @@
+import type { DatabaseSync } from 'node:sqlite';
+export declare const SQLITE_FIXED_OVERHEAD_BYTES: number;
+export declare const MIN_SQLITE_PAGE_BUDGET_BYTES: number;
+export declare const MAX_WAL_RESERVE_BYTES: number;
+export declare const WAL_AUTOCHECKPOINT_PAGES = 2000;
+export declare const WAL_SIZE_LIMIT_BYTES: number;
+export declare class ChronicleStorageQuotaError extends Error {
+    readonly currentBytes: number;
+    readonly batchBytes: number;
+    readonly maxBytes: number;
+    readonly path: string;
+    constructor(details: {
+        currentBytes: number;
+        batchBytes: number;
+        maxBytes: number;
+        path: string;
+    });
+}
+export declare class ChronicleQuotaManager {
+    private readonly db;
+    private readonly dbPath;
+    private readonly maxBytes;
+    private cachedPageSize;
+    private quotaHeadroomBytes;
+    private bytesSinceQuotaCheck;
+    constructor(db: DatabaseSync, dbPath: string, maxBytes: number | undefined);
+    configure(): void;
+    pageSizeBytes(): number;
+    aggregateLiveBytes(): number;
+    mainDatabaseLiveBytes(): number;
+    invalidateEstimate(): void;
+    recordAppendedBytes(bytes: number): void;
+    assertWithinByteQuota(batchBytes: number): void;
+    assertActualAllocationWithinQuota(): void;
+    normalizeQuotaError(error: unknown): unknown;
+    private shouldMeasureQuota;
+    private recordQuotaHeadroom;
+}
+//# sourceMappingURL=sqlite-journal-quota.d.ts.map

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

@@ -0,0 +1,25 @@
+import type { DatabaseSync } from 'node:sqlite';
+import type { ChronicleEvent } from './types.js';
+export declare const CHRONICLE_SQLITE_FILE = "chronicle.sqlite";
+export declare const LEGACY_JSONL_MIGRATION_KEY = "legacy-jsonl-v1";
+export declare const LEGACY_JSONL_QUARANTINE_KEY = "legacy-jsonl-v1:quarantine";
+export declare const LEGACY_JSONL_BOUNDARY_KEY = "legacy-jsonl-v1:boundary";
+export declare const SCHEMA_VERSION = 2;
+export declare function loadDatabaseSync(): typeof DatabaseSync;
+export interface ProjectedRow {
+    occurredAt: string;
+    outcome: string | null;
+    projectId: string | null;
+    sessionId: string | null;
+    agentId: string | null;
+    taskId: string | null;
+    traceId: string | null;
+    logicalRequestId: string | null;
+    resourceKind: string | null;
+    resourceId: string | null;
+    resourcePath: string | null;
+    durationNs: string | null;
+}
+export declare function projectEvent(event: ChronicleEvent): ProjectedRow;
+export declare function ensureChronicleSchema(db: DatabaseSync): void;
+//# sourceMappingURL=sqlite-journal-schema.d.ts.map

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

@@ -1,23 +1,9 @@
 import type { ChronicleJournalStats, ChroniclePurgeResult } from './journal.js';
+import { ChronicleStorageQuotaError } from './sqlite-journal-quota.js';
+import { CHRONICLE_SQLITE_FILE, LEGACY_JSONL_BOUNDARY_KEY, LEGACY_JSONL_MIGRATION_KEY, LEGACY_JSONL_QUARANTINE_KEY } from './sqlite-journal-schema.js';
 import { ChronicleSqliteQueryEngine, type ChronicleSqliteQueryEngineOptions } from './sqlite-query.js';
 import { type ChronicleEvent, type ChronicleEventInput, type ChronicleVerifyResult } from './types.js';
-export declare const CHRONICLE_SQLITE_FILE = "chronicle.sqlite";
-/** Marker written once the legacy JSONL partitions have been imported. */
-export declare const LEGACY_JSONL_MIGRATION_KEY = "legacy-jsonl-v1";
-/** Day families the import refused to move, recorded so they are never retried silently. */
-export declare const LEGACY_JSONL_QUARANTINE_KEY = "legacy-jsonl-v1:quarantine";
-export declare class ChronicleStorageQuotaError extends Error {
-    readonly currentBytes: number;
-    readonly batchBytes: number;
-    readonly maxBytes: number;
-    readonly path: string;
-    constructor(details: {
-        currentBytes: number;
-        batchBytes: number;
-        maxBytes: number;
-        path: string;
-    });
-}
+export { CHRONICLE_SQLITE_FILE, ChronicleStorageQuotaError, LEGACY_JSONL_BOUNDARY_KEY, LEGACY_JSONL_MIGRATION_KEY, LEGACY_JSONL_QUARANTINE_KEY, };
 export interface ChronicleSqliteJournalOptions {
     /** Directory holding the journal, i.e. `<projectDir>/chronicle`. */
     directory: string;
@@ -64,21 +50,12 @@ export declare class ChronicleSqliteJournal {
     private readonly idFactory;
     private readonly retentionDays;
     private readonly maxEvents;
-    private readonly maxBytes;
     private readonly retentionCheckIntervalMs;
     /** Overshoot allowed above `maxEvents` before eviction runs; see TRIM_SLACK_RATIO. */
     private readonly trimSlack;
+    private readonly quotaManager;
     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.
      *
@@ -98,177 +75,35 @@ export declare class ChronicleSqliteJournal {
     constructor(options: ChronicleSqliteJournalOptions);
     close(): void;
     stats(): ChronicleJournalStats;
-    /**
-     * Writes are synchronous and transactional, so there is nothing buffered to
-     * flush. Kept to satisfy `ChronicleEventSink`.
-     */
     flush(): Promise<void>;
     append(input: ChronicleEventInput): Promise<ChronicleEvent>;
-    /**
-     * Append a batch as one transaction.
-     *
-     * The chain is computed in memory from a single anchor, so a partially
-     * applied batch would leave a hole in `sequence` that verification can never
-     * reconcile. Rollback plus anchor invalidation is what prevents that.
-     */
     appendBatch(inputs: readonly ChronicleEventInput[]): Promise<ChronicleEvent[]>;
     readAll(): Promise<ChronicleEvent[]>;
-    /**
-     * Walk every chain and prove none has been edited.
-     *
-     * Chronicle chains are scoped to a day, not to the journal: the JSONL writer
-     * anchors each `<day>.events.jsonl` family at `GENESIS_HASH` independently,
-     * so `sequence` restarts at 1 every day. Verification mirrors that — each day
-     * is validated on its own, and a break in one does not implicate the others.
-     *
-     * Three independent properties per day, because each catches a different
-     * failure: a dense `sequence` catches deletions from the middle, the
-     * `previousHash` link catches reordering, and re-hashing the payload catches
-     * an in-place edit that left the links intact.
-     */
     verify(): Promise<ChronicleVerifyResult>;
     private enforceRetentionIfDue;
-    private configureByteQuota;
-    /**
-     * Bytes the journal actually occupies: live pages in the main database plus
-     * whatever the rollback/WAL sidecars currently hold.
-     *
-     * The quota MUST be measured this way rather than by `statSync` on the main
-     * database file. SQLite never returns freed pages to the filesystem — it
-     * parks them on the freelist and reuses them — so a database that once grew
-     * large keeps that size forever, even after retention and `maxEvents` have
-     * evicted almost everything. Measuring the file instead wedged the journal
-     * permanently: a 3.9 GB file whose live data was 243 MB failed a 512 MB
-     * quota on EVERY append, and the only escape (`chronicle compact`) refuses
-     * to run while the daemon is up — and the daemon respawns on demand. Live
-     * pages shrink when retention deletes rows, so the quota can recover on its
-     * own; allocated size cannot.
-     *
-     * The sidecars keep their on-disk size: they are transient and genuinely
-     * bounded by `configureByteQuota`'s half-of-budget split.
-     */
-    private aggregateLiveBytes;
-    /** Live (non-freelist) pages of the main database, in bytes. */
-    private mainDatabaseLiveBytes;
-    /** 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;
-    /**
-     * Drop events older than the retention window.
-     *
-     * Retention is day-granular and chains are day-scoped, so a purge removes
-     * whole chains rather than truncating one. That is why nothing needs to be
-     * checkpointed here: there is no surviving suffix left dangling without an
-     * anchor. Any checkpoint imported from a partially-purged legacy day family
-     * is dropped alongside its events.
-     */
     purge(options: ChronicleSqlitePurgeOptions): Promise<ChroniclePurgeResult>;
-    /**
-     * Run one day family's legacy import inside its own transaction.
-     *
-     * Deliberately separate from `appendBatch`: the append path *computes*
-     * `sequence`, `previousHash` and `hash`, while an import must carry them over
-     * untouched. Fusing the two would put a code path one refactor away from
-     * re-hashing historical events, which is the one change that silently
-     * destroys their tamper evidence.
-     *
-     * The transaction is scoped to a single family because chains are: `sequence`
-     * restarts at 1 each day, so one day's break says nothing about the next
-     * day's integrity. A whole-journal transaction made every future day hostage
-     * to the worst day on disk — one corrupt family and the daemon could never
-     * open its store again. The family is still all-or-nothing: a break rolls
-     * back that day entirely, so no partial chain is ever visible.
-     */
     runFamilyImport(load: (sink: ChronicleImportSink) => Promise<void>): Promise<void>;
-    /**
-     * A read engine over this journal's own connection.
-     *
-     * Sharing the connection rather than opening a second one keeps the
-     * single-writer guarantee intact and means a reader can never observe a
-     * half-applied batch: SQLite serialises statements on one handle.
-     */
     queryEngine(options?: ChronicleSqliteQueryEngineOptions): ChronicleSqliteQueryEngine;
-    /** Has the legacy JSONL import already run? */
     hasImportedLegacyJournal(): boolean;
     markLegacyJournalImported(): void;
-    /**
-     * Record the day families the import refused to move.
-     *
-     * Persisted rather than merely logged because the import runs once: after the
-     * marker is set nothing re-reads the JSONL, so this row is the only surviving
-     * evidence that a day was dropped. Health reports read it back to say
-     * "degraded, and here is exactly what is missing" instead of quietly serving
-     * a journal with a hole in it.
-     */
     recordQuarantinedFamilies(families: readonly ChronicleQuarantinedFamily[]): void;
-    /**
-     * Does this day already hold rows?
-     *
-     * Each family commits on its own, so an import interrupted between families
-     * leaves a database that is complete for the days it reached. `(day,
-     * sequence)` is the primary key, so re-inserting one of those days would
-     * abort on a constraint violation rather than start over — this is what lets
-     * the next run resume at the first day it never got to.
-     */
+    /** Record per-partition-file JSONL byte offsets at import time (merged — the
+     *  import persists per family, so a crash mid-run keeps earlier boundaries).
+     *  The metrics ingester folds only bytes beyond these boundaries after the
+     *  migration, so post-migration appends (the jsonl-store fallback) are
+     *  ingested while the migrated bytes are never re-counted. Files absent from
+     *  the map were quarantined (or created post-migration) — their events live
+     *  only in JSONL. */
+    recordLegacyJsonlBoundary(boundary: Record<string, number>): void;
     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. */
     private days;
-    /**
-     * Resolve the chain head, in the same precedence the JSONL journal uses: the
-     * newest event, else the retention checkpoint (every event before it was
-     * purged), else genesis.
-     */
     private readAnchor;
-    private ensureSchema;
 }
 //# sourceMappingURL=sqlite-journal.d.ts.map