@camstack/system 1.2.127 → 1.2.128

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,12 @@ 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.
+     */
+    private readPragmaNumber;
     private measureDbSizeBytes;
     private getDb;
     /**

package/package.json

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