@camstack/system 1.2.127 → 1.2.129

package/dist/builtins/sqlite-storage/sqlite-pragmas.d.ts

@@ -116,3 +116,29 @@ export declare const SQLITE_PAGE_CACHE_CEILING_KIB = -262144;
 export declare function sqliteMmapSizeFor(fileSizeBytes: number): number;
 /** The `cache_size` to apply for a database of this size, in KiB (negative). */
 export declare function sqlitePageCacheKibFor(fileSizeBytes: number): number;
+/** Page counters read straight off the connection, in the units SQLite reports. */
+export interface SqlitePageCounters {
+    readonly pageCount: number;
+    readonly freelistCount: number;
+    readonly pageSizeBytes: number;
+}
+/** How much of the file holds rows, and how much is free pages awaiting reuse. */
+export interface SqliteOccupancy {
+    readonly liveMb: number;
+    readonly freeMb: number;
+    readonly freePct: number;
+}
+/**
+ * Split a database file into live bytes and free bytes.
+ *
+ * A file that stopped growing is not the same as a file that is full. SQLite
+ * reuses freed pages but never returns them to the filesystem without a
+ * `VACUUM`, so a database sitting at its high-water mark looks — from `stat`,
+ * from `df`, from any measurement outside the connection — exactly like one
+ * genuinely packed with rows. The two call for opposite actions: the first is
+ * reclaimed by a VACUUM, the second means retention is not keeping up.
+ *
+ * `dbSizeMb` on the boot line could not tell them apart. This can, and it costs
+ * three header reads on a connection that is already open.
+ */
+export declare function sqliteOccupancy(counters: SqlitePageCounters): SqliteOccupancy;

package/dist/builtins/sqlite-storage/sqlite-settings-backend.d.ts

@@ -218,6 +218,23 @@ export declare class SqliteSettingsBackend implements ISettingsBackend {
      * unreadable `stat`, and both callers treat it as "unknown" and fall back to
      * the floor — never to a smaller setting than the one already argued for.
      */
+    /**
+     * One numeric PRAGMA off the open connection. A pragma that does not answer
+     * with a number yields 0, which `sqliteOccupancy` reads as "unknown" and
+     * reports as an empty file rather than inventing a ratio.
+     */
+    /**
+     * Name the biggest tables, once, a minute after the connection opens.
+     *
+     * `dbSizeMb` says how big the file is and `freePct` says how much of it is
+     * live; neither says WHOSE. Per-addon scoped collections are created on first
+     * write and declared nowhere, so this is the only place the real set can be
+     * enumerated. `unref` so it can never hold the process open, and
+     * `CAMSTACK_SQLITE_STORAGE_REPORT=off` turns it off without a rebuild.
+     */
+    private scheduleStorageReport;
+    private logStorageReport;
+    private readPragmaNumber;
     private measureDbSizeBytes;
     private getDb;
     /**

package/dist/builtins/sqlite-storage/table-sizes.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Which collection IS the database.
+ *
+ * ## Why this exists
+ *
+ * The boot line already says how big the file is (`dbSizeMb`) and how much of
+ * it is real (`freePct`). Measured on the live hub 2026-08-25 those read
+ * `dbSizeMb=858 liveMb=840 freeMb=18 freePct=2` — so the growth from 153 MB
+ * (08-08) is not a high-water mark waiting for a VACUUM, it is live rows. That
+ * turned "should we VACUUM" into "which table", and nothing in this system
+ * could answer it.
+ *
+ * Nothing could, structurally: per-addon scoped collections
+ * (`<addonId>:<canonical>`) are created on the first write and declared in no
+ * source file, so the real set only exists on the running node. A reference
+ * page cannot list them and a grep cannot find them.
+ *
+ * ## Why `dbstat` and not `COUNT(*)`
+ *
+ * `dbstat` reports the pages a table actually occupies, which is the question —
+ * a table with few enormous rows and a table with many small ones are the same
+ * problem when the file is the thing that grew. It walks the b-tree structure
+ * without decoding row payloads, so it costs a page traversal rather than a
+ * full table scan. It is still real work on an 840 MB file, which is why the
+ * caller runs it ONCE, well after boot, off the critical path — never on the
+ * path a config read waits behind.
+ */
+/** One `dbstat` group: a table (or index) and the space it occupies. */
+export interface TableSizeRow {
+    readonly name: string;
+    readonly bytes: number;
+    readonly pages: number;
+}
+/** One line of the report. */
+export interface TableSizeEntry {
+    readonly name: string;
+    readonly sizeMb: number;
+    readonly pages: number;
+    /** Share of the whole file, percent. 0 when the file size is unknown. */
+    readonly pct: number;
+}
+export interface TableSizeReport {
+    readonly tables: readonly TableSizeEntry[];
+    /** Megabytes held by everything below the cut. */
+    readonly otherMb: number;
+    /** How many tables are behind `otherMb`. */
+    readonly otherTables: number;
+}
+/**
+ * Rank tables by the space they hold and keep the top `limit`.
+ *
+ * The tail is REPORTED, never dropped: a top-N that silently discards the rest
+ * reads as "these N are the database", which is exactly the wrong conclusion
+ * when the remainder is a third of the file.
+ */
+export declare function summariseTableSizes(rows: readonly TableSizeRow[], totalBytes: number, limit: number): TableSizeReport;
+/**
+ * How long after opening the connection the report runs.
+ *
+ * Not zero and not "on every boot forever at startup": boot is already the
+ * busiest window this engine sees (`ensureTable` x9, the retired-key purge, the
+ * vector registry), and a page traversal of an 840 MB file placed there would
+ * be indistinguishable from the stall this whole subsystem was just fixed for.
+ * Sixty seconds puts it after the storm, once per process.
+ */
+export declare const STORAGE_REPORT_DELAY_MS = 60000;
+/** Top-N tables named individually; the remainder is reported as a tail. */
+export declare const STORAGE_REPORT_TOP_N = 10;
+/** `dbstat` shape, narrowed without a cast. */
+export declare function toTableSizeRow(value: unknown): TableSizeRow | null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@camstack/system",
-  "version": "1.2.127",
+  "version": "1.2.129",
   "description": "Core addon for CamStack — builtins, pipeline, process management, auth, logging, events",
   "keywords": [
     "camstack",