@camstack/system 1.2.56 → 1.2.58

package/dist/builtins/sqlite-storage/wal-maintenance.d.ts

@@ -0,0 +1,113 @@
+import { IScopedLogger } from '@camstack/types';
+import { default as Database } from 'better-sqlite3';
+/**
+ * Size at or above which the WAL is a candidate for a truncating checkpoint,
+ * in bytes. 67108864 = **64 MiB**.
+ *
+ * Matched to `SQLITE_JOURNAL_SIZE_LIMIT_BYTES`: below this, the passive
+ * mechanism (autocheckpoint + `journal_size_limit`) is doing its job and there
+ * is nothing to reclaim. The live hub's WAL had reached 248,955,152 bytes —
+ * roughly 2x the 130 MB database — which is what says the passive path alone
+ * had stopped keeping up.
+ */
+export declare const WAL_HIGH_WATER_BYTES = 67108864;
+/**
+ * How long the WAL must have gone UNWRITTEN before a truncating checkpoint is
+ * allowed, in ms.
+ *
+ * This is the stall guard and the reason this file exists. `wal_checkpoint
+ * (TRUNCATE)` takes the writer lock, waits for readers, and copies the whole
+ * WAL back into the database — synchronously, on the thread that serves every
+ * request. An unconditional periodic one on a busy NVR would be the disease
+ * (hub-main already spends 42 s per 2 minutes inside uninterrupted blocks),
+ * not the cure.
+ *
+ * The idle signal is the WAL file's own mtime. It is one `stat`, and unlike a
+ * write counter maintained in this class it covers EVERY writer on the file —
+ * the settings backend, the sqlite-vec index sharing the handle, and the
+ * short-lived second connection system-backup opens. On a genuinely busy NVR
+ * this gate simply never opens, and `journal_size_limit` remains the only
+ * thing bounding the file. That is the intended failure mode: doing nothing is
+ * strictly better than a 249 MB copy in the middle of a live request.
+ */
+export declare const WAL_IDLE_QUIET_MS = 30000;
+/**
+ * Ceiling on how long the checkpoint may wait for a lock, in ms.
+ *
+ * better-sqlite3 defaults `busy_timeout` to 5000. A checkpoint invokes the
+ * busy handler while waiting for readers, so without this a "quiet" moment
+ * that turns out not to be quiet could park the main thread for 5 s. 250 ms
+ * means the checkpoint gives up and we try again on the next tick — the WAL
+ * staying big for another minute costs nothing.
+ */
+export declare const WAL_CHECKPOINT_BUSY_TIMEOUT_MS = 250;
+/** How often the gate is evaluated, in ms. Cheap: a `stat` unless it fires. */
+export declare const WAL_MAINTENANCE_INTERVAL_MS = 60000;
+/** What a single maintenance tick did. Every branch is named. */
+export type WalMaintenanceOutcome = {
+    readonly kind: 'no-wal';
+} | {
+    readonly kind: 'below-high-water';
+    readonly walBytes: number;
+} | {
+    readonly kind: 'deferred-not-idle';
+    readonly walBytes: number;
+    readonly quietForMs: number;
+} | {
+    readonly kind: 'checkpointed';
+    readonly beforeBytes: number;
+    readonly afterBytes: number;
+    readonly busy: boolean;
+    readonly walFrames: number;
+    readonly checkpointedFrames: number;
+} | {
+    readonly kind: 'failed';
+    readonly error: string;
+};
+/** Construction inputs for {@link WalMaintenance}. */
+export interface WalMaintenanceOptions {
+    readonly db: Database.Database;
+    /** Path to the main database file; the WAL is `${dbPath}-wal`. */
+    readonly dbPath: string;
+    readonly logger: IScopedLogger;
+    readonly highWaterBytes?: number;
+    readonly idleQuietMs?: number;
+    readonly intervalMs?: number;
+    readonly busyTimeoutMs?: number;
+}
+/**
+ * Periodic, heavily gated `wal_checkpoint(TRUNCATE)`.
+ *
+ * The interesting behaviour is all refusal. A tick costs one `stat` in the
+ * common case; it escalates to a lock-taking checkpoint only when the WAL is
+ * over the high-water mark AND nothing has written to it for
+ * {@link WAL_IDLE_QUIET_MS}, and even then the wait is bounded to
+ * {@link WAL_CHECKPOINT_BUSY_TIMEOUT_MS}.
+ */
+export declare class WalMaintenance {
+    private readonly db;
+    private readonly walPath;
+    private readonly logger;
+    private readonly highWaterBytes;
+    private readonly idleQuietMs;
+    private readonly intervalMs;
+    private readonly busyTimeoutMs;
+    private timer;
+    constructor(options: WalMaintenanceOptions);
+    start(): void;
+    stop(): void;
+    isRunning(): boolean;
+    /** Evaluate the gate once and act. Never throws. */
+    runOnce(): WalMaintenanceOutcome;
+    private evaluate;
+    /**
+     * Take the writer lock and fold the WAL back, with the wait bounded.
+     *
+     * The original `busy_timeout` is restored in a `finally`: this connection is
+     * shared with the settings backend and the vector index, and leaving them on
+     * a 250 ms timeout would turn an ordinary contended write into a spurious
+     * SQLITE_BUSY.
+     */
+    private checkpoint;
+    private statWal;
+}

package/dist/builtins/storage-orchestrator/storage-orchestrator.addon.js

@@ -3,7 +3,7 @@ Object.defineProperties(exports, {
 	[Symbol.toStringTag]: { value: "Module" }
 });
 const require_chunk = require("../../chunk-Cek0wNdY.js");
-const require_dist = require("../../dist-CblJsHb-.js");
+const require_dist = require("../../dist-Chl2MvMd.js");
 let node_path = require("node:path");
 node_path = require_chunk.__toESM(node_path);
 let node_fs_promises = require("node:fs/promises");

package/dist/builtins/storage-orchestrator/storage-orchestrator.addon.mjs

@@ -1,4 +1,4 @@
-import { dt as BaseAddon, et as settingsStoreCapability, f as StorageLocationTypeSchema, jt as parseJsonObject, nt as storageCapability } from "../../dist-BOpRqInW.mjs";
+import { dt as BaseAddon, et as settingsStoreCapability, f as StorageLocationTypeSchema, jt as parseJsonObject, nt as storageCapability } from "../../dist-UrXyJ9Zm.mjs";
 import * as path$1 from "node:path";
 import * as fs from "node:fs/promises";
 import { buildStorageLocationRegistry } from "@camstack/system";

package/dist/builtins/system-config/system-config.addon.js

@@ -3,7 +3,7 @@ Object.defineProperties(exports, {
 	[Symbol.toStringTag]: { value: "Module" }
 });
 require("../../chunk-Cek0wNdY.js");
-const require_dist = require("../../dist-CblJsHb-.js");
+const require_dist = require("../../dist-Chl2MvMd.js");
 //#region src/builtins/system-config/system-config.addon.ts
 /**
 * Built-in `system-config` addon — Phase 4 of the settings redesign.

package/dist/builtins/system-config/system-config.addon.mjs

@@ -1,4 +1,4 @@
-import { Ot as hydrateSchema, dt as BaseAddon, ut as errMsg } from "../../dist-BOpRqInW.mjs";
+import { Ot as hydrateSchema, dt as BaseAddon, ut as errMsg } from "../../dist-UrXyJ9Zm.mjs";
 //#region src/builtins/system-config/system-config.addon.ts
 /**
 * Built-in `system-config` addon — Phase 4 of the settings redesign.

package/dist/builtins/winston-logging/index.js

@@ -3,7 +3,7 @@ Object.defineProperties(exports, {
 	[Symbol.toStringTag]: { value: "Module" }
 });
 const require_chunk = require("../../chunk-Cek0wNdY.js");
-const require_dist = require("../../dist-CblJsHb-.js");
+const require_dist = require("../../dist-Chl2MvMd.js");
 const require_formatter = require("../../formatter-DqAKDlvN.js");
 let node_path = require("node:path");
 node_path = require_chunk.__toESM(node_path);

package/dist/builtins/winston-logging/index.mjs

@@ -1,4 +1,4 @@
-import { U as logDestinationCapability, dt as BaseAddon } from "../../dist-BOpRqInW.mjs";
+import { U as logDestinationCapability, dt as BaseAddon } from "../../dist-UrXyJ9Zm.mjs";
 import { t as formatLogLine } from "../../formatter-B7qW8bPJ.mjs";
 import * as path$1 from "node:path";
 import path from "node:path";