@camstack/system 1.0.2

package/dist/builtins/sqlite-storage/filesystem-storage.addon.mjs

@@ -0,0 +1,388 @@
+import * as fs from "node:fs";
+import * as path$1 from "node:path";
+import { basename, dirname, join, resolve, sep } from "node:path";
+import { BaseAddon, filesystemBrowseCapability, storageProviderCapability } from "@camstack/types";
+import { randomUUID } from "node:crypto";
+import { homedir } from "node:os";
+import { mkdir, readdir, realpath, statfs } from "node:fs/promises";
+//#region src/builtins/sqlite-storage/filesystem-storage-provider.ts
+/**
+* Filesystem `storage-provider` (Task 7).
+*
+* Implements the `storage-provider` collection cap. Replaces the legacy
+* sync `IStorageProvider` shape — every method now takes the live
+* `StorageLocation` inline (no per-provider location state) and works
+* off `location.config.basePath`.
+*
+* Adds chunked upload (`.partial` rename trick) + chunked download
+* sessions for moving multi-GB archives without buffering the whole
+* archive in memory. Sessions auto-expire after 5 minutes idle.
+*
+* The legacy `FilesystemStorageProvider` in `@camstack/types/node` is
+* deliberately untouched — it still backs the sync `ctx.kernel.storage`
+* helper that addons like `pipeline-analytics` use to derive paths
+* synchronously. That sync API will be retired in a later refactor;
+* Task 7 is scoped to the cap surface only.
+*/
+/** Idle TTL for upload + download sessions. */
+var SESSION_IDLE_TTL_MS = 300 * 1e3;
+/**
+* Resolve `location.config.basePath` into a string. Throws an actionable
+* error when the field is missing or wrong-typed — every primitive
+* funnels through here, so a missing field surfaces as a single clear
+* message instead of a downstream `path.join` TypeError.
+*/
+function getBasePath(location) {
+	const basePath = location.config["basePath"];
+	if (typeof basePath !== "string" || basePath.length === 0) throw new Error(`filesystem-storage: location "${location.id}" missing string config.basePath`);
+	return basePath;
+}
+/**
+* Resolve a relative path against the location's base, rejecting any
+* traversal that escapes the base directory. Mirrors the
+* `addon-asset` endpoint security check in `main.ts`: normalize both
+* the base + the joined target, then enforce `target.startsWith(base + sep)`
+* (with the `+ sep` guard so `/data` doesn't accidentally allow
+* `/datasecret`).
+*/
+function safeResolve(base, relativePath) {
+	const normalizedBase = path$1.resolve(base);
+	const target = path$1.resolve(normalizedBase, relativePath);
+	if (target !== normalizedBase && !target.startsWith(normalizedBase + path$1.sep)) throw new Error(`filesystem-storage: relativePath "${relativePath}" escapes basePath "${normalizedBase}"`);
+	return target;
+}
+var FilesystemStorageProvider = class FilesystemStorageProvider {
+	static providerId = "filesystem-storage";
+	static displayName = "Filesystem";
+	uploads = /* @__PURE__ */ new Map();
+	downloads = /* @__PURE__ */ new Map();
+	async getProviderInfo() {
+		return {
+			providerId: FilesystemStorageProvider.providerId,
+			displayName: FilesystemStorageProvider.displayName,
+			shouldSaveDiskSpace: true,
+			minFreePercent: 10,
+			nodeLocal: true,
+			configSchema: { sections: [{
+				id: "filesystem-storage",
+				title: "Filesystem",
+				fields: [{
+					type: "text",
+					key: "basePath",
+					label: "Base path",
+					description: "Absolute directory path where files are stored.",
+					required: true
+				}]
+			}] }
+		};
+	}
+	async testLocation({ config }) {
+		const basePath = config["basePath"];
+		if (typeof basePath !== "string" || basePath.length === 0) return {
+			ok: false,
+			error: "config.basePath must be a non-empty string"
+		};
+		try {
+			const stat = await fs.promises.stat(basePath).catch(() => null);
+			if (stat) {
+				if (!stat.isDirectory()) return {
+					ok: false,
+					error: `Path "${basePath}" exists but is not a directory`
+				};
+				await fs.promises.access(basePath, fs.constants.W_OK);
+				return { ok: true };
+			}
+			await fs.promises.mkdir(basePath, { recursive: true });
+			return { ok: true };
+		} catch (err) {
+			return {
+				ok: false,
+				error: err instanceof Error ? err.message : String(err)
+			};
+		}
+	}
+	async resolve({ location, relativePath }) {
+		return safeResolve(getBasePath(location), relativePath);
+	}
+	async write({ location, relativePath, data }) {
+		const filePath = safeResolve(getBasePath(location), relativePath);
+		await fs.promises.mkdir(path$1.dirname(filePath), { recursive: true });
+		await fs.promises.writeFile(filePath, data);
+	}
+	async read({ location, relativePath }) {
+		const filePath = safeResolve(getBasePath(location), relativePath);
+		const buf = await fs.promises.readFile(filePath);
+		const out = new Uint8Array(new ArrayBuffer(buf.byteLength));
+		out.set(buf);
+		return out;
+	}
+	async exists({ location, relativePath }) {
+		const filePath = safeResolve(getBasePath(location), relativePath);
+		try {
+			await fs.promises.access(filePath);
+			return true;
+		} catch {
+			return false;
+		}
+	}
+	async list({ location, prefix }) {
+		const base = getBasePath(location);
+		const dir = prefix ? safeResolve(base, prefix) : path$1.resolve(base);
+		try {
+			return (await fs.promises.readdir(dir, { withFileTypes: true })).map((e) => prefix ? `${prefix}/${e.name}` : e.name);
+		} catch {
+			return [];
+		}
+	}
+	async delete({ location, relativePath }) {
+		const filePath = safeResolve(getBasePath(location), relativePath);
+		await fs.promises.rm(filePath, { force: true });
+	}
+	async getAvailableSpace({ location }) {
+		const base = path$1.resolve(getBasePath(location));
+		try {
+			let target = base;
+			while (!fs.existsSync(target)) {
+				const parent = path$1.dirname(target);
+				if (!parent || parent === target) return null;
+				target = parent;
+			}
+			const stats = await fs.promises.statfs(target);
+			return stats.bavail * stats.bsize;
+		} catch {
+			return null;
+		}
+	}
+	async beginUpload({ location, relativePath }) {
+		const target = safeResolve(getBasePath(location), relativePath);
+		const partial = `${target}.partial`;
+		await fs.promises.mkdir(path$1.dirname(target), { recursive: true });
+		await fs.promises.unlink(partial).catch(() => {});
+		const stream = fs.createWriteStream(partial);
+		const uploadId = randomUUID();
+		const session = {
+			stream,
+			target,
+			partial,
+			bytesWritten: 0,
+			timer: setTimeout(() => {
+				this.abortUpload({ uploadId }).catch(() => {});
+			}, SESSION_IDLE_TTL_MS)
+		};
+		this.uploads.set(uploadId, session);
+		return { uploadId };
+	}
+	async writeChunk({ uploadId, offset, data }) {
+		const session = this.uploads.get(uploadId);
+		if (!session) throw new Error(`filesystem-storage: upload session "${uploadId}" not found`);
+		if (offset !== session.bytesWritten) throw new Error(`filesystem-storage: chunk offset mismatch (expected ${session.bytesWritten}, got ${offset})`);
+		await new Promise((resolve, reject) => {
+			session.stream.write(data, (err) => {
+				if (err) reject(err);
+				else resolve();
+			});
+		});
+		clearTimeout(session.timer);
+		const nextBytesWritten = session.bytesWritten + data.length;
+		this.uploads.set(uploadId, {
+			...session,
+			bytesWritten: nextBytesWritten,
+			timer: setTimeout(() => {
+				this.abortUpload({ uploadId }).catch(() => {});
+			}, SESSION_IDLE_TTL_MS)
+		});
+	}
+	async finalizeUpload({ uploadId }) {
+		const session = this.uploads.get(uploadId);
+		if (!session) throw new Error(`filesystem-storage: upload session "${uploadId}" not found`);
+		await new Promise((resolve, reject) => {
+			session.stream.end(() => resolve());
+			session.stream.on("error", reject);
+		});
+		await fs.promises.rename(session.partial, session.target);
+		clearTimeout(session.timer);
+		this.uploads.delete(uploadId);
+	}
+	async abortUpload({ uploadId }) {
+		const session = this.uploads.get(uploadId);
+		if (!session) return;
+		try {
+			session.stream.destroy();
+		} catch {}
+		await fs.promises.unlink(session.partial).catch(() => {});
+		clearTimeout(session.timer);
+		this.uploads.delete(uploadId);
+	}
+	async beginDownload({ location, relativePath }) {
+		const target = safeResolve(getBasePath(location), relativePath);
+		const stat = await fs.promises.stat(target);
+		const fd = await fs.promises.open(target, "r");
+		const downloadId = randomUUID();
+		const session = {
+			fd,
+			sizeBytes: stat.size,
+			timer: setTimeout(() => {
+				this.endDownload({ downloadId }).catch(() => {});
+			}, SESSION_IDLE_TTL_MS)
+		};
+		this.downloads.set(downloadId, session);
+		return {
+			downloadId,
+			sizeBytes: stat.size
+		};
+	}
+	async readChunk({ downloadId, offset, length }) {
+		const session = this.downloads.get(downloadId);
+		if (!session) throw new Error(`filesystem-storage: download session "${downloadId}" not found`);
+		const out = new Uint8Array(new ArrayBuffer(length));
+		const { bytesRead } = await session.fd.read(out, 0, length, offset);
+		clearTimeout(session.timer);
+		this.downloads.set(downloadId, {
+			...session,
+			timer: setTimeout(() => {
+				this.endDownload({ downloadId }).catch(() => {});
+			}, SESSION_IDLE_TTL_MS)
+		});
+		return out.subarray(0, bytesRead);
+	}
+	async endDownload({ downloadId }) {
+		const session = this.downloads.get(downloadId);
+		if (!session) return;
+		try {
+			await session.fd.close();
+		} catch {}
+		clearTimeout(session.timer);
+		this.downloads.delete(downloadId);
+	}
+	/**
+	* Abort all outstanding sessions. Called on addon shutdown so timers
+	* don't leak across hot-reload cycles.
+	*/
+	async dispose() {
+		const uploadIds = [...this.uploads.keys()];
+		const downloadIds = [...this.downloads.keys()];
+		await Promise.all(uploadIds.map((uploadId) => this.abortUpload({ uploadId })));
+		await Promise.all(downloadIds.map((downloadId) => this.endDownload({ downloadId })));
+	}
+};
+//#endregion
+//#region src/builtins/sqlite-storage/path-guard.ts
+/**
+* Allowed-root containment guard for the filesystem-browse cap. Pure +
+* synchronous so it is trivially unit-testable; the provider applies it AFTER
+* resolving the real path (so symlink escapes are also caught upstream).
+*/
+/** True iff `candidate` is one of, or nested under, an allowed root. */
+function isWithinAllowedRoots(candidate, allowedRoots) {
+	const norm = resolve(candidate);
+	return allowedRoots.some((root) => {
+		const r = resolve(root);
+		return norm === r || norm.startsWith(r.endsWith(sep) ? r : r + sep);
+	});
+}
+/** Throws unless `candidate` is within an allowed root. */
+function assertWithinAllowedRoots(candidate, allowedRoots) {
+	if (!isWithinAllowedRoots(candidate, allowedRoots)) throw new Error(`path "${candidate}" is not within an allowed root`);
+}
+//#endregion
+//#region src/builtins/sqlite-storage/filesystem-browse-provider.ts
+/**
+* Per-node filesystem-browse provider. Lists/creates directories under
+* operator-configured allowed roots only (sandboxed by `path-guard`). Backs the
+* `filesystem-browse` cap so the admin UI can pick a node + path for a
+* node-local storage location.
+*/
+var FilesystemBrowseProvider = class {
+	allowedRoots;
+	/** allowedRoots is injected (read from addon config) so it stays per-node + testable. */
+	constructor(allowedRoots) {
+		this.allowedRoots = allowedRoots;
+	}
+	async listAllowedRoots() {
+		return [...this.allowedRoots()];
+	}
+	async browse({ path }) {
+		const real = await realpath(path).catch(() => path);
+		assertWithinAllowedRoots(real, await this.resolvedRoots());
+		const entries = (await readdir(real, { withFileTypes: true })).filter((d) => d.isDirectory()).map((d) => ({
+			name: d.name,
+			path: join(real, d.name)
+		}));
+		const fs = await statfs(real);
+		const totalBytes = fs.blocks * fs.bsize;
+		return {
+			path: real,
+			entries,
+			freeBytes: fs.bavail * fs.bsize,
+			totalBytes
+		};
+	}
+	async createDir({ path }) {
+		const parent = dirname(path);
+		assertWithinAllowedRoots(join(await realpath(parent).catch(() => parent), basename(path)), await this.resolvedRoots());
+		await mkdir(path, { recursive: true });
+		return { path };
+	}
+	/** Allowed roots with symlinks resolved (falls back to the raw root if it does not exist). */
+	async resolvedRoots() {
+		return Promise.all(this.allowedRoots().map((r) => realpath(r).catch(() => r)));
+	}
+};
+//#endregion
+//#region src/builtins/sqlite-storage/filesystem-storage.addon.ts
+function defaultAllowedRoots() {
+	return [
+		"/mnt",
+		"/Volumes",
+		"/media",
+		homedir()
+	];
+}
+/**
+* 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.
+*/
+var FilesystemStorageAddon = class extends BaseAddon {
+	provider = null;
+	constructor() {
+		super({
+			rootPath: "camstack-data",
+			storageAllowedRoots: defaultAllowedRoots()
+		});
+	}
+	async onInitialize() {
+		this.provider = new FilesystemStorageProvider();
+		const browse = new FilesystemBrowseProvider(() => this.config.storageAllowedRoots);
+		this.ctx.logger.info("Filesystem storage-provider initialized");
+		return [{
+			capability: storageProviderCapability,
+			provider: this.provider
+		}, {
+			capability: filesystemBrowseCapability,
+			provider: browse
+		}];
+	}
+	async onShutdown() {
+		await this.provider?.dispose();
+		this.provider = null;
+	}
+	getProvider() {
+		return this.provider;
+	}
+};
+//#endregion
+export { FilesystemStorageAddon, FilesystemStorageAddon as default, FilesystemStorageProvider as t };

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

@@ -0,0 +1,8 @@
+export { FilesystemStorageProvider } from './filesystem-storage-provider.js';
+export { FilesystemStorageAddon } from './filesystem-storage.addon.js';
+export { SqliteSettingsBackend } from './sqlite-settings-backend.js';
+export { SqliteSettingsAddon } from './sqlite-settings.addon.js';
+export { DeviceStore } from './device-store.js';
+export type { DeviceRow } from './device-store.js';
+export { ConfigStore } from './config-store.js';
+export { FilesystemStorageAddon as default } from './filesystem-storage.addon.js';

package/dist/builtins/sqlite-storage/index.js

@@ -0,0 +1,62 @@
+Object.defineProperties(exports, {
+	__esModule: { value: true },
+	[Symbol.toStringTag]: { value: "Module" }
+});
+require("../../chunk-Cek0wNdY.js");
+const require_builtins_sqlite_storage_filesystem_storage_addon = require("./filesystem-storage.addon.js");
+const require_builtins_sqlite_storage_sqlite_settings_addon = require("./sqlite-settings.addon.js");
+//#region src/builtins/sqlite-storage/device-store.ts
+var DeviceStore = class {
+	db;
+	constructor(db) {
+		this.db = db;
+	}
+	insert(addonId, device) {
+		this.db.prepare(`INSERT INTO devices (addon_id, stable_id, type, name, parent_stable_id) VALUES (?, ?, ?, ?, ?)`).run(addonId, device.stableId, device.type, device.name, device.parentStableId);
+	}
+	listByAddon(addonId) {
+		return this.db.prepare(`SELECT stable_id as stableId, type, name, parent_stable_id as parentStableId, enabled FROM devices WHERE addon_id = ?`).all(addonId);
+	}
+	listChildren(addonId, parentStableId) {
+		return this.db.prepare(`SELECT stable_id as stableId, type, name, parent_stable_id as parentStableId, enabled FROM devices WHERE addon_id = ? AND parent_stable_id = ?`).all(addonId, parentStableId);
+	}
+	remove(addonId, stableId) {
+		this.db.prepare(`DELETE FROM devices WHERE addon_id = ? AND stable_id = ?`).run(addonId, stableId);
+	}
+};
+//#endregion
+//#region src/builtins/sqlite-storage/config-store.ts
+var ConfigStore = class {
+	db;
+	constructor(db) {
+		this.db = db;
+	}
+	save(addonId, stableId, data) {
+		if (stableId === null) this.db.prepare(`INSERT INTO addon_config (addon_id, stable_id, data, updated_at)
+           VALUES (?, NULL, ?, datetime('now'))
+           ON CONFLICT(addon_id) WHERE stable_id IS NULL
+           DO UPDATE SET data = excluded.data, updated_at = excluded.updated_at`).run(addonId, JSON.stringify(data));
+		else this.db.prepare(`INSERT INTO addon_config (addon_id, stable_id, data, updated_at)
+           VALUES (?, ?, ?, datetime('now'))
+           ON CONFLICT(addon_id, stable_id) WHERE stable_id IS NOT NULL
+           DO UPDATE SET data = excluded.data, updated_at = excluded.updated_at`).run(addonId, stableId, JSON.stringify(data));
+	}
+	load(addonId, stableId) {
+		const row = stableId === null ? this.db.prepare(`SELECT data FROM addon_config WHERE addon_id = ? AND stable_id IS NULL`).get(addonId) : this.db.prepare(`SELECT data FROM addon_config WHERE addon_id = ? AND stable_id = ?`).get(addonId, stableId);
+		return row ? JSON.parse(row.data) : {};
+	}
+	remove(addonId, stableId) {
+		if (stableId === null) this.db.prepare(`DELETE FROM addon_config WHERE addon_id = ? AND stable_id IS NULL`).run(addonId);
+		else this.db.prepare(`DELETE FROM addon_config WHERE addon_id = ? AND stable_id = ?`).run(addonId, stableId);
+	}
+};
+//#endregion
+exports.ConfigStore = ConfigStore;
+exports.ConfigStore$1 = ConfigStore;
+exports.DeviceStore = DeviceStore;
+exports.DeviceStore$1 = DeviceStore;
+exports.FilesystemStorageAddon = require_builtins_sqlite_storage_filesystem_storage_addon.FilesystemStorageAddon;
+exports.FilesystemStorageProvider = require_builtins_sqlite_storage_filesystem_storage_addon.FilesystemStorageProvider;
+exports.SqliteSettingsAddon = require_builtins_sqlite_storage_sqlite_settings_addon.SqliteSettingsAddon;
+exports.SqliteSettingsBackend = require_builtins_sqlite_storage_sqlite_settings_addon.SqliteSettingsBackend;
+exports.default = require_builtins_sqlite_storage_filesystem_storage_addon.FilesystemStorageAddon;

package/dist/builtins/sqlite-storage/index.mjs

@@ -0,0 +1,49 @@
+import { FilesystemStorageAddon, t as FilesystemStorageProvider } from "./filesystem-storage.addon.mjs";
+import { SqliteSettingsAddon, t as SqliteSettingsBackend } from "./sqlite-settings.addon.mjs";
+//#region src/builtins/sqlite-storage/device-store.ts
+var DeviceStore = class {
+	db;
+	constructor(db) {
+		this.db = db;
+	}
+	insert(addonId, device) {
+		this.db.prepare(`INSERT INTO devices (addon_id, stable_id, type, name, parent_stable_id) VALUES (?, ?, ?, ?, ?)`).run(addonId, device.stableId, device.type, device.name, device.parentStableId);
+	}
+	listByAddon(addonId) {
+		return this.db.prepare(`SELECT stable_id as stableId, type, name, parent_stable_id as parentStableId, enabled FROM devices WHERE addon_id = ?`).all(addonId);
+	}
+	listChildren(addonId, parentStableId) {
+		return this.db.prepare(`SELECT stable_id as stableId, type, name, parent_stable_id as parentStableId, enabled FROM devices WHERE addon_id = ? AND parent_stable_id = ?`).all(addonId, parentStableId);
+	}
+	remove(addonId, stableId) {
+		this.db.prepare(`DELETE FROM devices WHERE addon_id = ? AND stable_id = ?`).run(addonId, stableId);
+	}
+};
+//#endregion
+//#region src/builtins/sqlite-storage/config-store.ts
+var ConfigStore = class {
+	db;
+	constructor(db) {
+		this.db = db;
+	}
+	save(addonId, stableId, data) {
+		if (stableId === null) this.db.prepare(`INSERT INTO addon_config (addon_id, stable_id, data, updated_at)
+           VALUES (?, NULL, ?, datetime('now'))
+           ON CONFLICT(addon_id) WHERE stable_id IS NULL
+           DO UPDATE SET data = excluded.data, updated_at = excluded.updated_at`).run(addonId, JSON.stringify(data));
+		else this.db.prepare(`INSERT INTO addon_config (addon_id, stable_id, data, updated_at)
+           VALUES (?, ?, ?, datetime('now'))
+           ON CONFLICT(addon_id, stable_id) WHERE stable_id IS NOT NULL
+           DO UPDATE SET data = excluded.data, updated_at = excluded.updated_at`).run(addonId, stableId, JSON.stringify(data));
+	}
+	load(addonId, stableId) {
+		const row = stableId === null ? this.db.prepare(`SELECT data FROM addon_config WHERE addon_id = ? AND stable_id IS NULL`).get(addonId) : this.db.prepare(`SELECT data FROM addon_config WHERE addon_id = ? AND stable_id = ?`).get(addonId, stableId);
+		return row ? JSON.parse(row.data) : {};
+	}
+	remove(addonId, stableId) {
+		if (stableId === null) this.db.prepare(`DELETE FROM addon_config WHERE addon_id = ? AND stable_id IS NULL`).run(addonId);
+		else this.db.prepare(`DELETE FROM addon_config WHERE addon_id = ? AND stable_id = ?`).run(addonId, stableId);
+	}
+};
+//#endregion
+export { ConfigStore, DeviceStore, FilesystemStorageAddon, FilesystemStorageAddon as default, FilesystemStorageProvider, SqliteSettingsAddon, SqliteSettingsBackend };

package/dist/builtins/sqlite-storage/integration-registry.d.ts

@@ -0,0 +1,27 @@
+import { Integration, PersistedDevice, CreateIntegrationInput, CreateDeviceInput, IIntegrationRegistry, ISettingsBackend } from '@camstack/types';
+export declare class IntegrationRegistry implements IIntegrationRegistry {
+    private readonly backend;
+    constructor(backend: ISettingsBackend);
+    initialize(): Promise<void>;
+    createIntegration(input: CreateIntegrationInput): Promise<Integration>;
+    getIntegration(id: string): Promise<Integration | null>;
+    getIntegrationByAddonId(addonId: string): Promise<Integration | null>;
+    listIntegrations(): Promise<readonly Integration[]>;
+    updateIntegration(id: string, updates: Partial<Pick<Integration, 'name' | 'enabled' | 'info'>>): Promise<Integration | null>;
+    deleteIntegration(id: string): Promise<boolean>;
+    getIntegrationSettings(integrationId: string): Promise<Record<string, unknown>>;
+    setIntegrationSetting(integrationId: string, key: string, value: unknown): Promise<void>;
+    setIntegrationSettings(integrationId: string, settings: Record<string, unknown>): Promise<void>;
+    createDevice(input: CreateDeviceInput): Promise<PersistedDevice>;
+    getDevice(id: string): Promise<PersistedDevice | null>;
+    getDeviceByStableId(stableId: string): Promise<PersistedDevice | null>;
+    listDevices(integrationId?: string): Promise<readonly PersistedDevice[]>;
+    listCameras(): Promise<readonly PersistedDevice[]>;
+    updateDevice(id: string, updates: Partial<Pick<PersistedDevice, 'name' | 'enabled' | 'info'>>): Promise<PersistedDevice | null>;
+    deleteDevice(id: string): Promise<boolean>;
+    getDeviceSettings(deviceId: string): Promise<Record<string, unknown>>;
+    setDeviceSetting(deviceId: string, key: string, value: unknown): Promise<void>;
+    setDeviceSettings(deviceId: string, settings: Record<string, unknown>): Promise<void>;
+    private mapIntegration;
+    private mapDevice;
+}

package/dist/builtins/sqlite-storage/path-guard.d.ts

@@ -0,0 +1,4 @@
+/** True iff `candidate` is one of, or nested under, an allowed root. */
+export declare function isWithinAllowedRoots(candidate: string, allowedRoots: readonly string[]): boolean;
+/** Throws unless `candidate` is within an allowed root. */
+export declare function assertWithinAllowedRoots(candidate: string, allowedRoots: readonly string[]): void;

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

@@ -0,0 +1,102 @@
+import { default as Database } from 'better-sqlite3';
+import { ISettingsBackend, SettingsRecord, TableSchema, TableQueryOptions, SettingsGetInput, SettingsSetInput, SettingsQueryInput, SettingsInsertInput, SettingsUpdateInput, SettingsDeleteInput, SettingsCountInput, SettingsIsEmptyInput, SettingsHistogramInput, HistogramBucket, CollectionColumn, CollectionIndex } from '@camstack/types';
+/**
+ * SQLite implementation of ISettingsBackend.
+ *
+ * Every collection is structured: declared at boot (canonical KV
+ * collections) or via `declareCollection` (typed schemas like
+ * `pipeline-analytics:tracks`). The legacy auto-create-on-first-access
+ * path was removed — see commit history for the migration. Operations
+ * on undeclared collections throw at runtime so callers fail fast.
+ *
+ * WAL mode for concurrent reads.
+ */
+export declare class SqliteSettingsBackend implements ISettingsBackend {
+    private readonly dbPath;
+    private db;
+    private readonly structuredTables;
+    /** Map from scoped collection name → set of column names (non-id) that
+     *  the structured schema owns. Routes set/get/insert/update/query to
+     *  typed columns. Every collection MUST be declared here before use. */
+    private readonly declaredCollections;
+    private readonly runtimeDefaults;
+    /**
+     * Canonical key/value collections — declared with a `(id TEXT PK,
+     * data TEXT NOT NULL)` schema at boot so existing JSON-blob rows
+     * keep working through the structured path. Generates SQL identical
+     * to the previous legacy path; only the routing is unified.
+     */
+    private static readonly CANONICAL_KV_COLLECTIONS;
+    constructor(dbPath: string, runtimeDefaults?: Record<string, unknown>);
+    initialize(): Promise<void>;
+    private requireDeclared;
+    /**
+     * Decode a single column value off a SQLite row into the JS shape the
+     * caller's schema expects. Handles:
+     *   - BOOLEAN columns: `0|1` → `false|true`
+     *   - JSON columns (TEXT starting with `{` / `[`): parse
+     *   - everything else: pass-through with null coalescing
+     */
+    private decodeColumnValue;
+    shutdown(): Promise<void>;
+    get({ namespace, collection, key }: SettingsGetInput): Promise<unknown>;
+    set({ namespace, collection, key, value }: SettingsSetInput): Promise<void>;
+    query<T extends object = Record<string, unknown>>({ namespace, collection, filter, }: SettingsQueryInput): Promise<readonly SettingsRecord<T>[]>;
+    insert<T extends object = Record<string, unknown>>({ namespace, collection, record, }: SettingsInsertInput<T>): Promise<void>;
+    update({ namespace, collection, id, data }: SettingsUpdateInput): Promise<void>;
+    delete({ namespace, collection, key }: SettingsDeleteInput): Promise<void>;
+    count({ namespace, collection, filter }: SettingsCountInput): Promise<number>;
+    histogram({ namespace, collection, field, bucketSize, origin, filter, }: SettingsHistogramInput): Promise<readonly HistogramBucket[]>;
+    isEmpty({ namespace, collection }: SettingsIsEmptyInput): Promise<boolean>;
+    private queryDeclared;
+    /** Get a system setting by dot-notation key */
+    getSystem(key: string): unknown;
+    /** Set a system setting */
+    setSystem(key: string, value: unknown): void;
+    /** Get all system settings as flat key-value */
+    getAllSystem(): Record<string, unknown>;
+    /** Get all settings for an addon */
+    getAllAddon(addonId: string): Record<string, unknown>;
+    /** Bulk-set all settings for an addon */
+    setAllAddon(addonId: string, config: Record<string, unknown>): void;
+    /** Get all settings for a provider */
+    getAllProvider(providerId: string): Record<string, unknown>;
+    /** Set a provider setting */
+    setProvider(providerId: string, key: string, value: unknown): void;
+    /** Get all settings for a device */
+    getAllDevice(deviceId: string): Record<string, unknown>;
+    /** Set a device setting */
+    setDevice(deviceId: string, key: string, value: unknown): void;
+    getAddonDevice(addonId: string, deviceId: string): Record<string, unknown>;
+    setAddonDevice(addonId: string, deviceId: string, values: Record<string, unknown>): void;
+    clearAddonDevice(addonId: string, deviceId: string): void;
+    /** Seed system-settings with runtime defaults (first boot) */
+    private seedDefaults;
+    /**
+     * Expose the raw better-sqlite3 Database instance for components that
+     * need direct SQL access (e.g. DeviceStore, ConfigStore).
+     * Returns null if the backend has not been initialized yet.
+     */
+    getDatabase(): Database.Database | null;
+    private getDb;
+    private getAllScoped;
+    private setScopedKey;
+    private scopedName;
+    declareCollection(input: {
+        namespace?: string;
+        collection: string;
+        columns: readonly CollectionColumn[];
+        indexes?: readonly CollectionIndex[];
+    }): Promise<void>;
+    /** Serialise per-column values for SQL binding: objects → JSON, booleans → 0/1. */
+    private serializeColumnValue;
+    ensureTable(table: string, schema: TableSchema): Promise<void>;
+    tableInsert(table: string, row: Record<string, unknown>): Promise<void>;
+    tableUpdate(table: string, filter: Record<string, unknown>, updates: Record<string, unknown>): Promise<number>;
+    tableDelete(table: string, filter: Record<string, unknown>): Promise<number>;
+    tableQuery(table: string, options?: TableQueryOptions): Promise<readonly Record<string, unknown>[]>;
+    tableGet(table: string, filter: Record<string, unknown>): Promise<Record<string, unknown> | null>;
+    tableCount(table: string, filter?: Record<string, unknown>): Promise<number>;
+    private buildWhere;
+}
+export default SqliteSettingsBackend;

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

@@ -0,0 +1,14 @@
+import { ProviderRegistration, BaseAddon } from '@camstack/types';
+import { SqliteSettingsBackend } from './sqlite-settings-backend.js';
+/**
+ * SQLite Settings addon — provides persistent settings storage.
+ * Capability: 'settings-store' (singleton)
+ */
+export declare class SqliteSettingsAddon extends BaseAddon {
+    private backend;
+    constructor();
+    protected onInitialize(): Promise<ProviderRegistration[]>;
+    protected onShutdown(): Promise<void>;
+    getBackend(): SqliteSettingsBackend | null;
+}
+export default SqliteSettingsAddon;