@camstack/system 1.2.390 → 1.2.391

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

@@ -1,39 +1,83 @@
-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;
+* `sqlite_stat1` — the index statistics the planner needs to choose between
+* two indexes that both fit.
+*
+* ## The failure this exists for
+*
+* The live hub's 900 MB database had NEVER been `ANALYZE`d — `sqlite_stat1` did
+* not exist. Without it SQLite falls back to fixed guesses, and on
+* `pipeline-analytics:media` (860 065 rows, two candidate indexes) the guess
+* was wrong in the most expensive possible direction:
+*
+* ```
+* SELECT … FROM media WHERE ownerKind=? AND ownerId=? AND deviceId=?
+*                     ORDER BY timestamp ASC
+* ```
+*
+* `idx_media_owner (ownerKind, ownerId)` finds the answer in ~2 rows but leaves
+* a sort. `idx_media_device_ts (deviceId, timestamp)` returns rows already in
+* `timestamp` order — so with no statistics the planner took the one that
+* avoided the sort, and walked all 150 133 media rows of one camera to return
+* SIX. Measured on a copy of the live database, warm cache, same four rows:
+*
+* | plan                        | time    |
+* | --------------------------- | ------- |
+* | `idx_media_device_ts` (chosen)  | 727 ms  |
+* | `idx_media_owner` (correct)     | 0.3 ms  |
+*
+* `ANALYZE` records `860065 143345 2` for `idx_media_owner` — two rows per
+* `(ownerKind, ownerId)` pair — against `860065 31855 1` for the device index,
+* and the planner flips. Same query, same rows, **727 ms → 3.2 ms**.
+*
+* ## Why it is one-shot, and scheduled
+*
+* A full `ANALYZE` of that database took **14.0 s**, and this engine is a
+* forked runner with a synchronous binding: those 14 s are 14 s in which every
+* configuration read in the cluster queues. That is affordable exactly once,
+* off the boot path, and never on a schedule — which is what the marker below
+* enforces. `sqlite_stat1` is a real table in the database, so the check
+* survives a restart with no state of its own to keep.
+*
+* Statistics go stale as a table grows, but stale statistics are not the
+* failure here: the failure is having NONE. Re-analysis is deliberately left as
+* a separate decision rather than smuggled in behind a timer.
+*/
+import type { 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 = 12e4;
 /** What {@link runAnalyzeIfMissing} did, for the caller to log. */
 export type AnalyzeOutcome = {
-    readonly kind: 'already-present';
+	readonly kind: "already-present";
 } | {
-    readonly kind: 'analyzed';
-    readonly tookMs: number;
-    readonly indexesAnalyzed: number;
+	readonly kind: "analyzed";
+	readonly tookMs: number;
+	readonly indexesAnalyzed: number;
 } | {
-    readonly kind: 'failed';
-    readonly tookMs: number;
-    readonly error: string;
+	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.
- */
+* 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.
- */
+* `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/config-store.d.ts

@@ -1,8 +1,8 @@
-import { default as Database } from 'better-sqlite3';
+import type Database from "better-sqlite3";
 export declare class ConfigStore {
-    private readonly db;
-    constructor(db: Database.Database);
-    save(addonId: string, stableId: string | null, data: Record<string, unknown>): void;
-    load(addonId: string, stableId: string | null): Record<string, unknown>;
-    remove(addonId: string, stableId: string | null): void;
+	private readonly db;
+	constructor(db: Database.Database);
+	save(addonId: string, stableId: string | null, data: Record<string, unknown>): void;
+	load(addonId: string, stableId: string | null): Record<string, unknown>;
+	remove(addonId: string, stableId: string | null): void;
 }

package/dist/builtins/sqlite-storage/device-store.d.ts

@@ -1,23 +1,23 @@
-import { default as Database } from 'better-sqlite3';
+import type Database from "better-sqlite3";
 export interface DeviceRow {
-    readonly stableId: string;
-    readonly type: string;
-    readonly name: string;
-    readonly parentStableId: string | null;
-    readonly enabled: boolean;
+	readonly stableId: string;
+	readonly type: string;
+	readonly name: string;
+	readonly parentStableId: string | null;
+	readonly enabled: boolean;
 }
 interface InsertInput {
-    readonly stableId: string;
-    readonly type: string;
-    readonly name: string;
-    readonly parentStableId: string | null;
+	readonly stableId: string;
+	readonly type: string;
+	readonly name: string;
+	readonly parentStableId: string | null;
 }
 export declare class DeviceStore {
-    private readonly db;
-    constructor(db: Database.Database);
-    insert(addonId: string, device: InsertInput): void;
-    listByAddon(addonId: string): readonly DeviceRow[];
-    listChildren(addonId: string, parentStableId: string): readonly DeviceRow[];
-    remove(addonId: string, stableId: string): void;
+	private readonly db;
+	constructor(db: Database.Database);
+	insert(addonId: string, device: InsertInput): void;
+	listByAddon(addonId: string): readonly DeviceRow[];
+	listChildren(addonId: string, parentStableId: string): readonly DeviceRow[];
+	remove(addonId: string, stableId: string): void;
 }
 export {};

package/dist/builtins/sqlite-storage/filesystem-browse-provider.d.ts

@@ -1,25 +1,25 @@
-import { IFilesystemBrowseProvider } from '@camstack/types';
+import type { IFilesystemBrowseProvider } from "@camstack/types";
 export declare class FilesystemBrowseProvider implements IFilesystemBrowseProvider {
-    private readonly allowedRoots;
-    /** allowedRoots is injected (read from addon config) so it stays per-node + testable. */
-    constructor(allowedRoots: () => readonly string[]);
-    listAllowedRoots(): Promise<readonly string[]>;
-    browse({ path }: {
-        path: string;
-    }): Promise<{
-        path: string;
-        entries: readonly {
-            name: string;
-            path: string;
-        }[];
-        freeBytes: number;
-        totalBytes: number;
-    }>;
-    createDir({ path }: {
-        path: string;
-    }): Promise<{
-        path: string;
-    }>;
-    /** Allowed roots with symlinks resolved (falls back to the raw root if it does not exist). */
-    private resolvedRoots;
+	private readonly allowedRoots;
+	/** allowedRoots is injected (read from addon config) so it stays per-node + testable. */
+	constructor(allowedRoots: () => readonly string[]);
+	listAllowedRoots(): Promise<readonly string[]>;
+	browse({ path }: {
+		path: string;
+	}): Promise<{
+		path: string;
+		entries: readonly {
+			name: string;
+			path: string;
+		}[];
+		freeBytes: number;
+		totalBytes: number;
+	}>;
+	createDir({ path }: {
+		path: string;
+	}): Promise<{
+		path: string;
+	}>;
+	/** Allowed roots with symlinks resolved (falls back to the raw root if it does not exist). */
+	private resolvedRoots;
 }

package/dist/builtins/sqlite-storage/filesystem-storage-provider.d.ts

@@ -1,83 +1,83 @@
-import { IStorageProviderImpl, StorageLocation, StorageProviderInfoSchema } from '@camstack/types';
-import { z } from 'zod';
+import type { IStorageProviderImpl, StorageLocation, StorageProviderInfoSchema } from "@camstack/types";
+import type { z } from "zod";
 type StorageProviderInfo = z.infer<typeof StorageProviderInfoSchema>;
 export declare class FilesystemStorageProvider implements IStorageProviderImpl {
-    static readonly providerId = "filesystem-storage";
-    static readonly displayName = "Filesystem";
-    private readonly uploads;
-    private readonly downloads;
-    getProviderInfo(): Promise<StorageProviderInfo>;
-    testLocation({ config }: {
-        readonly config: Record<string, unknown>;
-    }): Promise<{
-        readonly ok: boolean;
-        readonly error?: string;
-    }>;
-    resolve({ location, relativePath, }: {
-        readonly location: StorageLocation;
-        readonly relativePath: string;
-    }): Promise<string>;
-    write({ location, relativePath, data, }: {
-        readonly location: StorageLocation;
-        readonly relativePath: string;
-        readonly data: Uint8Array;
-    }): Promise<void>;
-    read({ location, relativePath, }: {
-        readonly location: StorageLocation;
-        readonly relativePath: string;
-    }): Promise<Uint8Array<ArrayBuffer>>;
-    exists({ location, relativePath, }: {
-        readonly location: StorageLocation;
-        readonly relativePath: string;
-    }): Promise<boolean>;
-    list({ location, prefix, }: {
-        readonly location: StorageLocation;
-        readonly prefix?: string;
-    }): Promise<readonly string[]>;
-    delete({ location, relativePath, }: {
-        readonly location: StorageLocation;
-        readonly relativePath: string;
-    }): Promise<void>;
-    getAvailableSpace({ location, }: {
-        readonly location: StorageLocation;
-    }): Promise<number | null>;
-    beginUpload({ location, relativePath, }: {
-        readonly location: StorageLocation;
-        readonly relativePath: string;
-        readonly sizeBytes?: number;
-    }): Promise<{
-        readonly uploadId: string;
-    }>;
-    writeChunk({ uploadId, offset, data, }: {
-        readonly uploadId: string;
-        readonly offset: number;
-        readonly data: Uint8Array;
-    }): Promise<void>;
-    finalizeUpload({ uploadId }: {
-        readonly uploadId: string;
-    }): Promise<void>;
-    abortUpload({ uploadId }: {
-        readonly uploadId: string;
-    }): Promise<void>;
-    beginDownload({ location, relativePath, }: {
-        readonly location: StorageLocation;
-        readonly relativePath: string;
-    }): Promise<{
-        readonly downloadId: string;
-        readonly sizeBytes: number;
-    }>;
-    readChunk({ downloadId, offset, length, }: {
-        readonly downloadId: string;
-        readonly offset: number;
-        readonly length: number;
-    }): Promise<Uint8Array<ArrayBuffer>>;
-    endDownload({ downloadId }: {
-        readonly downloadId: string;
-    }): Promise<void>;
-    /**
-     * Abort all outstanding sessions. Called on addon shutdown so timers
-     * don't leak across hot-reload cycles.
-     */
-    dispose(): Promise<void>;
+	static readonly providerId = "filesystem-storage";
+	static readonly displayName = "Filesystem";
+	private readonly uploads;
+	private readonly downloads;
+	getProviderInfo(): Promise<StorageProviderInfo>;
+	testLocation({ config }: {
+		readonly config: Record<string, unknown>;
+	}): Promise<{
+		readonly ok: boolean;
+		readonly error?: string;
+	}>;
+	resolve({ location, relativePath }: {
+		readonly location: StorageLocation;
+		readonly relativePath: string;
+	}): Promise<string>;
+	write({ location, relativePath, data }: {
+		readonly location: StorageLocation;
+		readonly relativePath: string;
+		readonly data: Uint8Array;
+	}): Promise<void>;
+	read({ location, relativePath }: {
+		readonly location: StorageLocation;
+		readonly relativePath: string;
+	}): Promise<Uint8Array<ArrayBuffer>>;
+	exists({ location, relativePath }: {
+		readonly location: StorageLocation;
+		readonly relativePath: string;
+	}): Promise<boolean>;
+	list({ location, prefix }: {
+		readonly location: StorageLocation;
+		readonly prefix?: string;
+	}): Promise<readonly string[]>;
+	delete({ location, relativePath }: {
+		readonly location: StorageLocation;
+		readonly relativePath: string;
+	}): Promise<void>;
+	getAvailableSpace({ location }: {
+		readonly location: StorageLocation;
+	}): Promise<number | null>;
+	beginUpload({ location, relativePath }: {
+		readonly location: StorageLocation;
+		readonly relativePath: string;
+		readonly sizeBytes?: number;
+	}): Promise<{
+		readonly uploadId: string;
+	}>;
+	writeChunk({ uploadId, offset, data }: {
+		readonly uploadId: string;
+		readonly offset: number;
+		readonly data: Uint8Array;
+	}): Promise<void>;
+	finalizeUpload({ uploadId }: {
+		readonly uploadId: string;
+	}): Promise<void>;
+	abortUpload({ uploadId }: {
+		readonly uploadId: string;
+	}): Promise<void>;
+	beginDownload({ location, relativePath }: {
+		readonly location: StorageLocation;
+		readonly relativePath: string;
+	}): Promise<{
+		readonly downloadId: string;
+		readonly sizeBytes: number;
+	}>;
+	readChunk({ downloadId, offset, length }: {
+		readonly downloadId: string;
+		readonly offset: number;
+		readonly length: number;
+	}): Promise<Uint8Array<ArrayBuffer>>;
+	endDownload({ downloadId }: {
+		readonly downloadId: string;
+	}): Promise<void>;
+	/**
+	* Abort all outstanding sessions. Called on addon shutdown so timers
+	* don't leak across hot-reload cycles.
+	*/
+	dispose(): Promise<void>;
 }
 export default FilesystemStorageProvider;

package/dist/builtins/sqlite-storage/filesystem-storage.addon.d.ts

@@ -1,32 +1,33 @@
-import { ProviderRegistration, BaseAddon } from '@camstack/types';
-import { FilesystemStorageProvider } from './filesystem-storage-provider.js';
+import type { ProviderRegistration } from "@camstack/types";
+import { BaseAddon } from "@camstack/types";
+import { FilesystemStorageProvider } from "./filesystem-storage-provider.js";
 interface FilesystemStorageConfig {
-    readonly rootPath: string;
-    readonly storageAllowedRoots: readonly string[];
+	readonly rootPath: string;
+	readonly storageAllowedRoots: readonly string[];
 }
 /**
- * Filesystem Storage addon — registers a filesystem-backed
- * `storage-provider` (Task 7).
- *
- * Pre-Task 7 this addon registered against the (then-collection)
- * `storage` cap. After Tasks 2/3/4 the consumer-facing `storage` cap is
- * a singleton owned by `storage-orchestrator`; the orchestrator
- * dispatches each call to whichever `storage-provider` matches
- * `location.providerId`.
- *
- * The OLD `rootPath` config field is preserved for back-compat: the
- * orchestrator's first-boot seeding step still uses the same env-var
- * resolution chain (operator override → `CAMSTACK_DATA` → fallback) to
- * derive the base path of every default location, then writes
- * `config.basePath` into each persisted `StorageLocation` row. The
- * provider itself is now stateless — every call carries the live
- * `StorageLocation` inline.
- */
+* Filesystem Storage addon — registers a filesystem-backed
+* `storage-provider` (Task 7).
+*
+* Pre-Task 7 this addon registered against the (then-collection)
+* `storage` cap. After Tasks 2/3/4 the consumer-facing `storage` cap is
+* a singleton owned by `storage-orchestrator`; the orchestrator
+* dispatches each call to whichever `storage-provider` matches
+* `location.providerId`.
+*
+* The OLD `rootPath` config field is preserved for back-compat: the
+* orchestrator's first-boot seeding step still uses the same env-var
+* resolution chain (operator override → `CAMSTACK_DATA` → fallback) to
+* derive the base path of every default location, then writes
+* `config.basePath` into each persisted `StorageLocation` row. The
+* provider itself is now stateless — every call carries the live
+* `StorageLocation` inline.
+*/
 export declare class FilesystemStorageAddon extends BaseAddon<FilesystemStorageConfig> {
-    private provider;
-    constructor();
-    protected onInitialize(): Promise<ProviderRegistration[]>;
-    protected onShutdown(): Promise<void>;
-    getProvider(): FilesystemStorageProvider | null;
+	private provider;
+	constructor();
+	protected onInitialize(): Promise<ProviderRegistration[]>;
+	protected onShutdown(): Promise<void>;
+	getProvider(): FilesystemStorageProvider | null;
 }
 export default FilesystemStorageAddon;