@camstack/system 1.2.133 → 1.2.134

package/dist/builtins/sqlite-storage/analyze-stats.d.ts

@@ -0,0 +1,41 @@
+import { Database } from 'better-sqlite3';
+/**
+ * Delay before the one-shot `ANALYZE`, in ms.
+ *
+ * Boot is itself the busiest window this runner has (`ensureTable` ×9, the
+ * retired-key purge, the vector registry), and adding a 14 s statement to it
+ * would turn a slow boot into one an operator reads as a hang. Long enough that
+ * the cluster is serving before the engine goes quiet.
+ */
+export declare const ANALYZE_DELAY_MS = 120000;
+/** Env var that disables the one-shot analysis. `off` is the only value read. */
+export declare const ANALYZE_ENV_VAR = "CAMSTACK_SQLITE_ANALYZE";
+/** What {@link runAnalyzeIfMissing} did, for the caller to log. */
+export type AnalyzeOutcome = {
+    readonly kind: 'already-present';
+} | {
+    readonly kind: 'analyzed';
+    readonly tookMs: number;
+    readonly indexesAnalyzed: number;
+} | {
+    readonly kind: 'failed';
+    readonly tookMs: number;
+    readonly error: string;
+};
+/**
+ * True when the database has no `sqlite_stat1` at all.
+ *
+ * Deliberately "none", not "old": a stale row still tells the planner the
+ * relative selectivity of two indexes, which is the entire question being
+ * asked. Re-analysis on a staleness heuristic would put a 14 s statement on a
+ * timer, and this runner cannot afford one.
+ */
+export declare function hasIndexStatistics(db: Database): boolean;
+/**
+ * `ANALYZE` the database, but only if it has never been analysed.
+ *
+ * Synchronous and long — see the module doc. Never throws: a database that
+ * refuses to be analysed is a missing optimisation, not a reason to take the
+ * settings engine down, and the outcome says so rather than going quiet.
+ */
+export declare function runAnalyzeIfMissing(db: Database, now?: () => number): AnalyzeOutcome;

package/dist/builtins/sqlite-storage/query-profiler.d.ts

@@ -35,6 +35,23 @@ import { IScopedLogger } from '@camstack/types';
  * statement that really does take seconds. Both are needed; neither is
  * sufficient.
  *
+ * ## Why the SQL shape, and why the plan
+ *
+ * `(op, collection)` names a TABLE, not a call site. On 2026-08-25 the busiest
+ * line of a 90 s operator stall was `query pipeline-analytics:tracks — 1005
+ * calls, max 1615 ms` and eleven different reads in one addon are spelled
+ * exactly that way; the aggregate accused all of them and cleared none. So the
+ * shape of the prepared statement (`statement-shape.ts`) is part of the
+ * aggregate KEY, and the report prints it.
+ *
+ * A shape says WHICH query. It does not say why it is slow — "1.6 s for 501
+ * rows" is a full scan and "1.6 s for 501 rows" is also a cold disk, and those
+ * are the same line. `EXPLAIN QUERY PLAN` is the only thing that separates
+ * them, and it is attached to the slow-call WARN because that is where the
+ * question is asked. It is asked ONCE PER SHAPE PER WINDOW: a scan that fires
+ * the WARN fires it repeatedly, and a plan re-printed forty times is how the
+ * one line that mattered stops being read.
+ *
  * ## Cost
  *
  * Two `Date.now()` calls and one `Map` lookup per statement. At the measured
@@ -64,17 +81,37 @@ export interface SqliteOpSample {
     readonly deviceId?: number;
     /** See {@link SqliteOpLabel.owner}. */
     readonly owner?: string;
+    /** See {@link SqliteOpLabel.sql}. */
+    readonly sql?: string;
+    /** See {@link SqliteOpLabel.params}. */
+    readonly params?: readonly unknown[];
 }
-/** One `(op, collection, owner)` triple's totals over a report window. */
+/** One `(op, collection, owner, shape)` tuple's totals over a report window. */
 export interface SqliteOpStat {
     readonly op: string;
     readonly collection: string;
     readonly owner?: string;
+    /** `statement-shape.ts` fingerprint; absent for a fixed-shape statement the
+     *  engine did not hand to the profiler. */
+    readonly shape?: string;
     readonly calls: number;
     readonly totalMs: number;
     readonly maxMs: number;
     readonly rows: number;
 }
+/**
+ * Runs `EXPLAIN QUERY PLAN` for a statement on the connection that executed it.
+ *
+ * Injected rather than reached for: the profiler must not own a database
+ * handle, and the plan is only trustworthy from the SAME connection — a second
+ * handle can differ in `sqlite_stat1` visibility and in temp-schema state, and
+ * a plan taken from a connection that is not the one that stalled describes a
+ * query nobody ran.
+ *
+ * Returns one string per plan row (SQLite's `detail` column). Must not throw —
+ * an unexplainable statement yields `[]`.
+ */
+export type SqlExplainer = (sql: string, params: readonly unknown[]) => readonly string[];
 /**
  * Duration at which one statement is worth a WARN on its own, in ms.
  *
@@ -104,6 +141,8 @@ export interface SqliteOpProfilerOptions {
     readonly reportIntervalMs?: number;
     readonly reportFloorMs?: number;
     readonly topN?: number;
+    /** Absent ⇒ slow-call WARNs carry no plan. See {@link SqlExplainer}. */
+    readonly explain?: SqlExplainer;
 }
 /** Identity of a measured call, without the numbers `measure` supplies itself. */
 export interface SqliteOpLabel {
@@ -117,6 +156,27 @@ export interface SqliteOpLabel {
      * exactly where the 67 660-call storm of 2026-08-25 stopped.
      */
     readonly owner?: string;
+    /**
+     * The statement the engine prepared, verbatim.
+     *
+     * Supplied only by the ops that BUILD their SQL from a filter — those are the
+     * ones whose cost varies by call site. A fixed-shape statement (`get`, `set`)
+     * is already fully described by `(op, collection)`.
+     *
+     * Used for two things and nothing else: the shape that becomes part of the
+     * aggregate key, and the `EXPLAIN QUERY PLAN` on a slow call. Never logged
+     * raw — see `statement-shape.ts` for what is dropped.
+     */
+    readonly sql?: string;
+    /**
+     * The values bound to {@link sql}.
+     *
+     * Needed because `EXPLAIN QUERY PLAN` on a statement with unbound parameters
+     * is not the plan that ran: SQLite's planner reads bound values for `LIKE`
+     * prefixes and for index-selection on `IN`. Never logged, in whole or in
+     * part — they carry device ids, keys and user data.
+     */
+    readonly params?: readonly unknown[];
 }
 export declare class SqliteOpProfiler {
     private readonly logger;
@@ -125,7 +185,11 @@ export declare class SqliteOpProfiler {
     private readonly reportIntervalMs;
     private readonly reportFloorMs;
     private readonly topN;
+    private readonly explain;
     private readonly stats;
+    /** Shapes already explained in this window — see the class doc on why the
+     *  plan is printed once and not on every WARN. Cleared by `drain`. */
+    private readonly explainedShapes;
     private windowStartedAt;
     private timer;
     constructor(options: SqliteOpProfilerOptions);
@@ -139,6 +203,15 @@ export declare class SqliteOpProfiler {
      */
     measure<T>(label: SqliteOpLabel, run: () => T): T;
     record(sample: SqliteOpSample): void;
+    /**
+     * `EXPLAIN QUERY PLAN` for a statement that just held the loop, or nothing.
+     *
+     * Nothing when: no explainer was injected, the op carries no SQL, or this
+     * shape has already been explained in this window. The explainer is
+     * contracted not to throw and is guarded anyway — a profiler that can turn a
+     * slow query into a crash is worse than one that cannot explain it.
+     */
+    private planFor;
     /** Totals for the window, busiest first, and reset. */
     drain(): readonly SqliteOpStat[];
     /** Emit one aggregate line for the window, unless the engine was idle. */

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

@@ -221,6 +221,24 @@ export declare class SqliteSettingsBackend implements ISettingsBackend {
      * Returns null if the backend has not been initialized yet.
      */
     getDatabase(): Database.Database | null;
+    /**
+     * `EXPLAIN QUERY PLAN` for a statement, as one string per plan row.
+     *
+     * Answers the question the timing alone cannot: "1.6 s for 501 rows" is a
+     * full scan and is also a cold disk, and only the plan tells them apart. It
+     * runs on the SAME connection as the statement, because that is the only
+     * connection whose `sqlite_stat1` visibility and temp schema match.
+     *
+     * `EXPLAIN QUERY PLAN` prepares and plans; it does not execute the statement,
+     * so it costs no page reads of its own. It is still called only from the
+     * slow-call path, once per shape per window.
+     *
+     * Never throws. A plan that cannot be taken (a statement the engine will no
+     * longer prepare, a closed handle mid-shutdown) is a missing ANSWER, not a
+     * failure worth turning a slow query into a crash — the profiler falls back
+     * to the line it would have printed anyway.
+     */
+    private explainQueryPlan;
     /**
      * Run one synchronous statement under the profiler.
      *
@@ -265,6 +283,16 @@ export declare class SqliteSettingsBackend implements ISettingsBackend {
      * storage report turns it off without a rebuild.
      */
     private scheduleMapGrowthCheck;
+    /**
+     * One-shot `ANALYZE`, long after boot, only if the database has none.
+     *
+     * `analyze-stats.ts` has the measurement that justifies it: without
+     * `sqlite_stat1` the planner walked 150 133 media rows to return six, and one
+     * `ANALYZE` took that same query from 727 ms to 3.2 ms. It is scheduled
+     * rather than run inline because it is a 14 s synchronous statement on the
+     * one thread the cluster reads configuration through.
+     */
+    private scheduleIndexAnalysis;
     private scheduleStorageReport;
     private logStorageReport;
     private readPragmaNumber;

package/dist/builtins/sqlite-storage/statement-shape.d.ts

@@ -0,0 +1,64 @@
+/**
+ * A stable, low-cardinality name for the SHAPE of a SQL statement.
+ *
+ * ## Why the profiler needs this
+ *
+ * `SqliteOpProfiler` aggregated on `(op, collection)`, and that pair is not an
+ * identity — it is a table. On 2026-08-25 the busiest line of a 90 s operator
+ * stall read `query pipeline-analytics:tracks — 1005 calls, 2694 ms,
+ * max 1615 ms, 17981 rows`, and there was no way to tell from it WHICH of the
+ * eleven distinct reads that addon issues against that one table had spent the
+ * second and a half. Every one of them was equally accused; the aggregate could
+ * not clear a single one.
+ *
+ * The shape is the missing half. It is derived from the statement the engine
+ * actually prepared, so it cannot drift from the code the way a hand-passed
+ * label would, and it collapses to exactly one string per call site — which is
+ * what makes it safe as part of an aggregate key.
+ *
+ * ## What is thrown away, and why
+ *
+ * - **The projection.** `queryDeclared` always selects every column, so the
+ *   `SELECT` list is the table's schema restated — pure noise, and the single
+ *   longest part of the statement.
+ * - **The table name.** It is already the `collection` field of the report.
+ * - **The width of an `IN` list.** `IN (?, ?, … ×500)` and `IN (?)` are the
+ *   same call site; keeping the literal placeholders would make every page of
+ *   a chunked read its own aggregate row. The COUNT is kept (`IN (?×500)`)
+ *   because it is the difference between "reads one row" and "reads five
+ *   hundred", which is the whole question being asked.
+ *
+ * Bound values are never included. They are not needed to name a call site, and
+ * a statement's parameters routinely carry device ids, keys and user data — a
+ * profiler line is not a place to put them.
+ */
+/**
+ * Longest fingerprint kept, in characters.
+ *
+ * A shape is a log field printed five to a line; past this it stops being
+ * readable and starts pushing the numbers off the end. Every real statement in
+ * this engine fits well inside it — the cap exists for the pathological
+ * `whereIn` with forty distinct fields, not for the normal case.
+ */
+export declare const SQL_SHAPE_MAX_LENGTH = 220;
+/** Appended when a shape is cut at {@link SQL_SHAPE_MAX_LENGTH}. */
+export declare const SQL_SHAPE_ELLIPSIS = "\u2026";
+/**
+ * How many distinct raw statements the memo holds before it is dropped.
+ *
+ * The engine prepares its SQL fresh on every call, so without a memo this runs
+ * a handful of regexes per statement at a few hundred statements a second.
+ * With one, it runs them once per call site. The bound exists because the raw
+ * key is unbounded in principle (an `IN` list of a new width mints a new
+ * entry): at the cap the memo is cleared rather than grown, which costs one
+ * re-derivation per shape and cannot leak.
+ */
+export declare const SQL_SHAPE_MEMO_MAX_ENTRIES = 512;
+/**
+ * Name the shape of `sql`, whose table is `collection`.
+ *
+ * Memoised on the raw statement — see {@link SQL_SHAPE_MEMO_MAX_ENTRIES}.
+ */
+export declare function sqlShape(sql: string, collection: string): string;
+/** Test seam: forget every memoised shape. */
+export declare function resetSqlShapeMemo(): void;

package/package.json

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