@camstack/system 1.2.423 → 1.2.424

package/dist/builtins/sqlite-storage/file-host-protocol.d.ts

@@ -0,0 +1,151 @@
+/**
+* The vocabulary between the engine's main thread and the thread that serves
+* one database file (D851). Pure: no driver, no kernel — the worker bundle
+* imports it, and so does the main thread.
+*
+* ## The shape
+*
+* A request is `{ id, kind, op, input }`; the answer is `{ id, ok: true,
+* result }` or `{ id, ok: false, error }`. `kind` is `data` (the
+* `data-store-provider` surface), `vector` (the `vector-store` surface) or
+* `control` (what the placement router needs to ask a file that no cap
+* method covers). Errors cross by NAME (`placement-errors.ts`).
+*
+* ## The type boundary
+*
+* A message is `unknown` the moment it crosses `postMessage`. `trustInput` and
+* `trustResult` are the only two places the engine asserts a type it cannot
+* prove: the message was built by {@link OwnedSqliteFile.call} /
+* {@link OwnedSqliteFile.vector}, whose signature IS the typing. Everything
+* else on either side of the boundary is typed.
+*/
+import type { IDataStoreProvider, IVectorStoreProvider } from "@camstack/types";
+import type { DataStoreDatabase, LogTags } from "@camstack/types";
+import type { SerializedError } from "./placement-errors.js";
+/** Every `data-store-provider` method a file serves (all but self-description). */
+export type DataStoreMethods = Omit<IDataStoreProvider, "getEngineInfo">;
+export type DataStoreOp = keyof DataStoreMethods;
+export type DataStoreInput<K extends DataStoreOp> = Parameters<DataStoreMethods[K]>[0];
+export type DataStoreOutput<K extends DataStoreOp> = Awaited<ReturnType<DataStoreMethods[K]>>;
+export type VectorOp = keyof IVectorStoreProvider;
+export type VectorInput<K extends VectorOp> = Parameters<IVectorStoreProvider[K]>[0];
+export type VectorOutput<K extends VectorOp> = Awaited<ReturnType<IVectorStoreProvider[K]>>;
+/** Questions about a file that are not cap methods. */
+export interface ControlOps {
+	/** Does a table of this name exist in the file? */
+	readonly hasTable: {
+		readonly input: {
+			readonly name: string;
+		};
+		readonly output: boolean;
+	};
+	/** Drop a retired table, reporting the rows that went with it (`null`: not there). */
+	readonly dropRetiredTable: {
+		readonly input: {
+			readonly name: string;
+		};
+		readonly output: {
+			readonly rows: number;
+		} | null;
+	};
+	/** Which thread serves this file. */
+	readonly threadId: {
+		readonly input: Record<string, never>;
+		readonly output: number;
+	};
+}
+export type ControlOp = keyof ControlOps;
+/** At most this many calls in flight per worker; beyond it a call is refused, never queued. */
+export declare const FILE_HOST_MAX_IN_FLIGHT = 512;
+/** A refusal for being busy is logged at most once per this many ms. */
+export declare const FILE_HOST_BUSY_LOG_INTERVAL_MS = 6e4;
+/** How one file is opened. */
+export interface OwnedSqliteFileSpec {
+	readonly databaseId: DataStoreDatabase;
+	/** `<dataDir>/<file>`, absolute. */
+	readonly livePath: string;
+	/** `settings` is served on the engine's main thread; `events`, `history` each on a worker. */
+	readonly thread: "main" | "worker";
+	/** `incremental` only takes effect on a file this open CREATES. */
+	readonly autoVacuum: "none" | "incremental";
+	/** Load sqlite-vec and serve `vector` calls (`events` only). */
+	readonly loadVectorExtension: boolean;
+}
+/** `workerData` of one file-host thread. */
+export interface FileHostWorkerData {
+	readonly kind: "file-host";
+	readonly spec: OwnedSqliteFileSpec;
+}
+export type FileHostRequest = {
+	readonly id: number;
+	readonly kind: "data";
+	readonly op: DataStoreOp;
+	readonly input: unknown;
+} | {
+	readonly id: number;
+	readonly kind: "vector";
+	readonly op: VectorOp;
+	readonly input: unknown;
+} | {
+	readonly id: number;
+	readonly kind: "control";
+	readonly op: ControlOp;
+	readonly input: unknown;
+} | {
+	readonly id: number;
+	readonly kind: "stop";
+};
+export type FileHostLogLevel = "debug" | "info" | "warn" | "error";
+export type FileHostMessage = {
+	readonly kind: "ready";
+	readonly declared: readonly string[];
+} | {
+	readonly kind: "log";
+	readonly level: FileHostLogLevel;
+	readonly message: string;
+	readonly scope: string;
+	readonly tags?: LogTags;
+	readonly meta?: Record<string, unknown>;
+} | {
+	readonly kind: "result";
+	readonly id: number;
+	readonly ok: true;
+	readonly result: unknown;
+} | {
+	readonly kind: "result";
+	readonly id: number;
+	readonly ok: false;
+	readonly error: SerializedError;
+} | {
+	readonly kind: "boot-failed";
+	readonly error: SerializedError;
+};
+export declare const DATA_STORE_OPS: readonly DataStoreOp[];
+export declare const VECTOR_OPS: readonly VectorOp[];
+export declare const CONTROL_OPS: readonly ControlOp[];
+export declare function isDataStoreOp(op: string): op is DataStoreOp;
+export declare function isVectorOp(op: string): op is VectorOp;
+export declare function isControlOp(op: string): op is ControlOp;
+/** Narrow an incoming worker message. */
+export declare function isFileHostMessage(value: unknown): value is FileHostMessage;
+/** Narrow an incoming request on the worker side. */
+export declare function isFileHostRequest(value: unknown): value is FileHostRequest;
+export declare function isFileHostWorkerData(value: unknown): value is FileHostWorkerData;
+/**
+* Type boundary (see the file header): the request was built by a typed
+* `call`/`vector`, so its `input` is the op's input.
+*/
+export declare function trustInput<T>(input: unknown): T;
+/** Type boundary (see the file header): the answer was produced by the op's handler. */
+export declare function trustResult<T>(result: unknown): T;
+/**
+* The `ArrayBuffer`s a payload carries within three levels (a typed array,
+* a `Buffer`, or an array/record of them, e.g. `{ items: [{ vector }] }`) — what `postMessage` should TRANSFER
+* rather than clone. A transferred buffer is detached on the sender: ownership
+* passes with the message, and a caller must not reuse a buffer it sent.
+*
+* Only plain, non-shared `ArrayBuffer`s qualify; a view over a pooled
+* `Buffer` slab is cloned instead, because transferring the slab would detach
+* every other `Buffer` carved from it.
+*/
+export declare function collectTransferables(payload: unknown): readonly ArrayBuffer[];

package/dist/builtins/sqlite-storage/file-host-worker.d.ts

@@ -0,0 +1 @@
+export {};

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

@@ -3,7 +3,7 @@ Object.defineProperties(exports, {
 	[Symbol.toStringTag]: { value: "Module" }
 });
 const require_chunk = require("../../chunk-Cek0wNdY.js");
-const require_dist = require("../../dist-VIIxVsBW.js");
+const require_dist = require("../../dist-CiUKtVkX.js");
 let node_crypto = require("node:crypto");
 let node_fs_promises = require("node:fs/promises");
 let node_path = require("node:path");

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

@@ -1,4 +1,4 @@
-import { Fn as storageProviderCapability, cr as BaseAddon, jt as filesystemBrowseCapability } from "../../dist-DimotS8e.mjs";
+import { In as storageProviderCapability, Mt as filesystemBrowseCapability, lr as BaseAddon } from "../../dist-B-NmfvVC.mjs";
 import { randomUUID } from "node:crypto";
 import { mkdir, readdir, realpath, statfs } from "node:fs/promises";
 import * as path$1 from "node:path";

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

@@ -4,6 +4,7 @@ Object.defineProperties(exports, {
 });
 require("../../chunk-Cek0wNdY.js");
 const require_builtins_sqlite_storage_filesystem_storage_addon = require("./filesystem-storage.addon.js");
+const require_wal_maintenance = require("../../wal-maintenance-BzdCQGjH.js");
 const require_builtins_sqlite_storage_sqlite_settings_addon = require("./sqlite-settings.addon.js");
 //#region src/builtins/sqlite-storage/config-store.ts
 var ConfigStore = class {
@@ -57,25 +58,25 @@ 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.SQLITE_ENGINE_STORM_WALL_SHARE = require_builtins_sqlite_storage_sqlite_settings_addon.SQLITE_ENGINE_STORM_WALL_SHARE;
-exports.SQLITE_JOURNAL_SIZE_LIMIT_BYTES = require_builtins_sqlite_storage_sqlite_settings_addon.SQLITE_JOURNAL_SIZE_LIMIT_BYTES;
-exports.SQLITE_MMAP_CEILING_BYTES = require_builtins_sqlite_storage_sqlite_settings_addon.SQLITE_MMAP_CEILING_BYTES;
-exports.SQLITE_MMAP_FLOOR_BYTES = require_builtins_sqlite_storage_sqlite_settings_addon.SQLITE_MMAP_FLOOR_BYTES;
-exports.SQLITE_PAGE_CACHE_CEILING_KIB = require_builtins_sqlite_storage_sqlite_settings_addon.SQLITE_PAGE_CACHE_CEILING_KIB;
-exports.SQLITE_PAGE_CACHE_FLOOR_KIB = require_builtins_sqlite_storage_sqlite_settings_addon.SQLITE_PAGE_CACHE_FLOOR_KIB;
-exports.SQLITE_PROFILE_REPORT_FLOOR_MS = require_builtins_sqlite_storage_sqlite_settings_addon.SQLITE_PROFILE_REPORT_FLOOR_MS;
-exports.SQLITE_PROFILE_REPORT_INTERVAL_MS = require_builtins_sqlite_storage_sqlite_settings_addon.SQLITE_PROFILE_REPORT_INTERVAL_MS;
-exports.SQLITE_PROFILE_TOP_N = require_builtins_sqlite_storage_sqlite_settings_addon.SQLITE_PROFILE_TOP_N;
-exports.SQLITE_SLOW_CALL_MS = require_builtins_sqlite_storage_sqlite_settings_addon.SQLITE_SLOW_CALL_MS;
-exports.SqliteOpProfiler = require_builtins_sqlite_storage_sqlite_settings_addon.SqliteOpProfiler;
+exports.SQLITE_ENGINE_STORM_WALL_SHARE = require_wal_maintenance.SQLITE_ENGINE_STORM_WALL_SHARE;
+exports.SQLITE_JOURNAL_SIZE_LIMIT_BYTES = require_wal_maintenance.SQLITE_JOURNAL_SIZE_LIMIT_BYTES;
+exports.SQLITE_MMAP_CEILING_BYTES = require_wal_maintenance.SQLITE_MMAP_CEILING_BYTES;
+exports.SQLITE_MMAP_FLOOR_BYTES = require_wal_maintenance.SQLITE_MMAP_FLOOR_BYTES;
+exports.SQLITE_PAGE_CACHE_CEILING_KIB = require_wal_maintenance.SQLITE_PAGE_CACHE_CEILING_KIB;
+exports.SQLITE_PAGE_CACHE_FLOOR_KIB = require_wal_maintenance.SQLITE_PAGE_CACHE_FLOOR_KIB;
+exports.SQLITE_PROFILE_REPORT_FLOOR_MS = require_wal_maintenance.SQLITE_PROFILE_REPORT_FLOOR_MS;
+exports.SQLITE_PROFILE_REPORT_INTERVAL_MS = require_wal_maintenance.SQLITE_PROFILE_REPORT_INTERVAL_MS;
+exports.SQLITE_PROFILE_TOP_N = require_wal_maintenance.SQLITE_PROFILE_TOP_N;
+exports.SQLITE_SLOW_CALL_MS = require_wal_maintenance.SQLITE_SLOW_CALL_MS;
+exports.SqliteOpProfiler = require_wal_maintenance.SqliteOpProfiler;
 exports.SqliteSettingsAddon = require_builtins_sqlite_storage_sqlite_settings_addon.SqliteSettingsAddon;
-exports.SqliteSettingsBackend = require_builtins_sqlite_storage_sqlite_settings_addon.SqliteSettingsBackend;
-exports.WAL_CHECKPOINT_BUSY_TIMEOUT_MS = require_builtins_sqlite_storage_sqlite_settings_addon.WAL_CHECKPOINT_BUSY_TIMEOUT_MS;
-exports.WAL_HIGH_WATER_BYTES = require_builtins_sqlite_storage_sqlite_settings_addon.WAL_HIGH_WATER_BYTES;
-exports.WAL_IDLE_QUIET_MS = require_builtins_sqlite_storage_sqlite_settings_addon.WAL_IDLE_QUIET_MS;
-exports.WAL_MAINTENANCE_INTERVAL_MS = require_builtins_sqlite_storage_sqlite_settings_addon.WAL_MAINTENANCE_INTERVAL_MS;
-exports.WalMaintenance = require_builtins_sqlite_storage_sqlite_settings_addon.WalMaintenance;
+exports.SqliteSettingsBackend = require_wal_maintenance.SqliteSettingsBackend;
+exports.WAL_CHECKPOINT_BUSY_TIMEOUT_MS = require_wal_maintenance.WAL_CHECKPOINT_BUSY_TIMEOUT_MS;
+exports.WAL_HIGH_WATER_BYTES = require_wal_maintenance.WAL_HIGH_WATER_BYTES;
+exports.WAL_IDLE_QUIET_MS = require_wal_maintenance.WAL_IDLE_QUIET_MS;
+exports.WAL_MAINTENANCE_INTERVAL_MS = require_wal_maintenance.WAL_MAINTENANCE_INTERVAL_MS;
+exports.WalMaintenance = require_wal_maintenance.WalMaintenance;
 exports.default = require_builtins_sqlite_storage_filesystem_storage_addon.FilesystemStorageAddon;
-exports.sqliteEngineStorm = require_builtins_sqlite_storage_sqlite_settings_addon.sqliteEngineStorm;
-exports.sqliteMmapSizeFor = require_builtins_sqlite_storage_sqlite_settings_addon.sqliteMmapSizeFor;
-exports.sqlitePageCacheKibFor = require_builtins_sqlite_storage_sqlite_settings_addon.sqlitePageCacheKibFor;
+exports.sqliteEngineStorm = require_wal_maintenance.sqliteEngineStorm;
+exports.sqliteMmapSizeFor = require_wal_maintenance.sqliteMmapSizeFor;
+exports.sqlitePageCacheKibFor = require_wal_maintenance.sqlitePageCacheKibFor;

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

@@ -1,5 +1,6 @@
 import { FilesystemStorageAddon, t as FilesystemStorageProvider } from "./filesystem-storage.addon.mjs";
-import { SqliteSettingsAddon, _ as SQLITE_PROFILE_REPORT_INTERVAL_MS, a as WalMaintenance, b as SqliteOpProfiler, c as SQLITE_JOURNAL_SIZE_LIMIT_BYTES, d as SQLITE_PAGE_CACHE_CEILING_KIB, f as SQLITE_PAGE_CACHE_FLOOR_KIB, g as SQLITE_PROFILE_REPORT_FLOOR_MS, h as SQLITE_ENGINE_STORM_WALL_SHARE, i as WAL_MAINTENANCE_INTERVAL_MS, l as SQLITE_MMAP_CEILING_BYTES, m as sqlitePageCacheKibFor, n as WAL_HIGH_WATER_BYTES, o as SqliteSettingsBackend, p as sqliteMmapSizeFor, r as WAL_IDLE_QUIET_MS, t as WAL_CHECKPOINT_BUSY_TIMEOUT_MS, u as SQLITE_MMAP_FLOOR_BYTES, v as SQLITE_PROFILE_TOP_N, x as sqliteEngineStorm, y as SQLITE_SLOW_CALL_MS } from "./sqlite-settings.addon.mjs";
+import { A as SQLITE_PAGE_CACHE_CEILING_KIB, B as sqliteEngineStorm, D as SQLITE_JOURNAL_SIZE_LIMIT_BYTES, F as SQLITE_PROFILE_REPORT_FLOOR_MS, I as SQLITE_PROFILE_REPORT_INTERVAL_MS, L as SQLITE_PROFILE_TOP_N, M as sqliteMmapSizeFor, N as sqlitePageCacheKibFor, O as SQLITE_MMAP_CEILING_BYTES, P as SQLITE_ENGINE_STORM_WALL_SHARE, R as SQLITE_SLOW_CALL_MS, a as WalMaintenance, c as SqliteSettingsBackend, i as WAL_MAINTENANCE_INTERVAL_MS, j as SQLITE_PAGE_CACHE_FLOOR_KIB, k as SQLITE_MMAP_FLOOR_BYTES, n as WAL_HIGH_WATER_BYTES, r as WAL_IDLE_QUIET_MS, t as WAL_CHECKPOINT_BUSY_TIMEOUT_MS, z as SqliteOpProfiler } from "../../wal-maintenance-BlqNqaQ3.mjs";
+import { SqliteSettingsAddon } from "./sqlite-settings.addon.mjs";
 //#region src/builtins/sqlite-storage/config-store.ts
 var ConfigStore = class {
 	db;

package/dist/builtins/sqlite-storage/owned-sqlite-file.d.ts

@@ -0,0 +1,136 @@
+/**
+* One database FILE of the `sqlite-settings` engine, with everything D447,
+* D452, D679 and D693 already require per file (D851):
+*
+* - a serving thread — the engine's main thread for `settings`, a dedicated
+*   worker for `events` and `history`;
+* - a WAL checkpointer, a `-shm` lock canary and the idle-gated WAL
+*   maintenance;
+* - a verified snapshot written by the owner, never a file copy.
+*
+* The router (`placement-router.ts`) holds one of these per open file and
+* sends each call to the file its collection lives in. Nothing outside this
+* package knows a file path.
+*/
+import type { DatabaseSnapshotResult, DataStoreDatabase, IScopedLogger } from "@camstack/types";
+import { type FileHostThreadFactory } from "./file-host-client.js";
+import type { DataStoreInput, DataStoreOp, DataStoreOutput, OwnedSqliteFileSpec, VectorInput, VectorOp, VectorOutput } from "./file-host-protocol.js";
+import { SqliteSettingsBackend } from "./sqlite-settings-backend.js";
+import type { SqliteVecVectorIndex } from "./vector-index-vec.js";
+export type { OwnedSqliteFileSpec } from "./file-host-protocol.js";
+/** A table a retired-collection purge dropped, and the rows that went with it. */
+export interface DroppedRetiredTable {
+	readonly rows: number;
+}
+export interface OwnedSqliteFile {
+	readonly databaseId: DataStoreDatabase;
+	readonly livePath: string;
+	call<K extends DataStoreOp>(op: K, input: DataStoreInput<K>): Promise<DataStoreOutput<K>>;
+	/** `vector-store` calls; refused on a file that does not load sqlite-vec. */
+	vector<K extends VectorOp>(op: K, input: VectorInput<K>): Promise<VectorOutput<K>>;
+	/** The collections this file's own `_collection_declarations` names. */
+	declaredCollections(): ReadonlySet<string>;
+	/** Does a table of this name exist in this file (declared or not)? */
+	hasTable(name: string): Promise<boolean>;
+	dropRetiredTable(name: string): Promise<DroppedRetiredTable | null>;
+	/** Which thread serves this file: 0 is the engine's main thread. */
+	servingThreadId(): Promise<number>;
+	/** The owner's verified copy of this file (D693). */
+	snapshot(): Promise<DatabaseSnapshotResult>;
+	/** Checkpointer, canary, maintenance, then the connection. */
+	stop(): Promise<void>;
+}
+/** What the per-file lifecycle needs, injectable so a spec can count and substitute. */
+export interface FileLifecycle {
+	readonly checkpointer: {
+		start(): void;
+		stop(): Promise<void>;
+	};
+	readonly canary: {
+		start(): void;
+		stop(): void;
+	};
+	readonly snapshotter: {
+		sweep(): Promise<unknown>;
+		write(): Promise<DatabaseSnapshotResult>;
+	};
+}
+export interface OwnedFileDeps {
+	/** The runner's logger; per-file loggers are derived from it. */
+	readonly logger: IScopedLogger;
+	/** The runner is respawned on a serving thread's death (D5/D6). Production: `process.exit(1)`. */
+	readonly onFatal: (reason: string) => void;
+	/** Runtime defaults seeded into a fresh `settings` file. */
+	readonly runtimeDefaults?: Record<string, unknown>;
+	readonly workerPath?: string;
+	readonly workerExecArgv?: readonly string[];
+	readonly threadFactory?: FileHostThreadFactory;
+	readonly maxInFlight?: number;
+	/** Replaces the real checkpointer / canary / snapshotter (specs). */
+	readonly lifecycle?: (spec: OwnedSqliteFileSpec, logger: (scope: string) => IScopedLogger) => FileLifecycle;
+	/**
+	* Runs once the file is open and BEFORE its lifecycle is armed — the slot
+	* for the boot-time purges, which must happen before anything can read.
+	*/
+	readonly afterOpen?: (file: OwnedSqliteFile) => Promise<void>;
+}
+/** Shared by both thread flavours: the per-file lifecycle. */
+declare abstract class OwnedFileBase implements OwnedSqliteFile {
+	protected readonly spec: OwnedSqliteFileSpec;
+	protected readonly deps: OwnedFileDeps;
+	readonly databaseId: DataStoreDatabase;
+	readonly livePath: string;
+	protected readonly log: (scope: string) => IScopedLogger;
+	protected lifecycle: FileLifecycle | null;
+	constructor(spec: OwnedSqliteFileSpec, deps: OwnedFileDeps);
+	abstract call<K extends DataStoreOp>(op: K, input: DataStoreInput<K>): Promise<DataStoreOutput<K>>;
+	abstract vector<K extends VectorOp>(op: K, input: VectorInput<K>): Promise<VectorOutput<K>>;
+	abstract declaredCollections(): ReadonlySet<string>;
+	abstract hasTable(name: string): Promise<boolean>;
+	abstract dropRetiredTable(name: string): Promise<DroppedRetiredTable | null>;
+	abstract servingThreadId(): Promise<number>;
+	protected abstract stopConnection(): Promise<void>;
+	protected abstract stopMaintenance(): void;
+	/**
+	* Arm the checkpointer, the canary and the snapshotter. Called after the
+	* connection is open and the boot purges have run.
+	*/
+	protected armLifecycle(): Promise<void>;
+	snapshot(): Promise<DatabaseSnapshotResult>;
+	stop(): Promise<void>;
+}
+/** `camstack.db`: served in place on the engine's main thread. */
+export declare class InlineOwnedFile extends OwnedFileBase {
+	readonly backend: SqliteSettingsBackend;
+	private declared;
+	private vectorIndex;
+	private vectorProvider;
+	private maintenance;
+	constructor(spec: OwnedSqliteFileSpec, deps: OwnedFileDeps);
+	open(): Promise<void>;
+	getVectorIndex(): SqliteVecVectorIndex | null;
+	call<K extends DataStoreOp>(op: K, input: DataStoreInput<K>): Promise<DataStoreOutput<K>>;
+	vector<K extends VectorOp>(op: K, input: VectorInput<K>): Promise<VectorOutput<K>>;
+	declaredCollections(): ReadonlySet<string>;
+	hasTable(name: string): Promise<boolean>;
+	dropRetiredTable(name: string): Promise<DroppedRetiredTable | null>;
+	servingThreadId(): Promise<number>;
+	protected stopMaintenance(): void;
+	protected stopConnection(): Promise<void>;
+}
+/** `events.db`, `history.db`: served by a dedicated worker thread. */
+export declare class WorkerOwnedFile extends OwnedFileBase {
+	private readonly client;
+	constructor(spec: OwnedSqliteFileSpec, deps: OwnedFileDeps);
+	open(): Promise<void>;
+	call<K extends DataStoreOp>(op: K, input: DataStoreInput<K>): Promise<DataStoreOutput<K>>;
+	vector<K extends VectorOp>(op: K, input: VectorInput<K>): Promise<VectorOutput<K>>;
+	declaredCollections(): ReadonlySet<string>;
+	hasTable(name: string): Promise<boolean>;
+	dropRetiredTable(name: string): Promise<DroppedRetiredTable | null>;
+	servingThreadId(): Promise<number>;
+	protected stopMaintenance(): void;
+	protected stopConnection(): Promise<void>;
+}
+/** Open a file on the thread its spec names. */
+export declare function openOwnedSqliteFile(spec: OwnedSqliteFileSpec, deps: OwnedFileDeps): Promise<InlineOwnedFile | WorkerOwnedFile>;

package/dist/builtins/sqlite-storage/placement-errors.d.ts

@@ -0,0 +1,60 @@
+/**
+* The typed errors of the owned-file layer (D851).
+*
+* They cross a thread boundary by NAME: a worker serialises `{ name, message,
+* code? }` and the main thread rebuilds the class with {@link rehydrateError},
+* so a caller's `instanceof CollectionPlacementError` survives the hop.
+*/
+import type { DataStoreDatabase } from "@camstack/types";
+/**
+* A collection was declared for one file while its table already lives in
+* another. The engine never moves a table: moving is the offline split
+* script's job (D853). This is the safety net that turns an accidental deploy
+* to an unconverted hub into a loud failure of ONE addon instead of a silent
+* empty file beside the real rows.
+*/
+export declare class CollectionPlacementError extends Error {
+	readonly table: string;
+	readonly livesIn: DataStoreDatabase;
+	readonly declaredFor: DataStoreDatabase;
+	constructor(table: string, livesIn: DataStoreDatabase, declaredFor: DataStoreDatabase);
+}
+/** A collection declared in two files at boot: the layout is corrupt and is not served. */
+export declare class DuplicatePlacementError extends Error {
+	readonly table: string;
+	readonly first: DataStoreDatabase;
+	readonly second: DataStoreDatabase;
+	constructor(table: string, first: DataStoreDatabase, second: DataStoreDatabase);
+}
+/** A `transact` whose ops resolve to more than one database file. */
+export declare class CrossDatabaseTransactError extends Error {
+	readonly databases: readonly DataStoreDatabase[];
+	constructor(databases: readonly DataStoreDatabase[]);
+}
+/** A worker already has its in-flight bound of calls queued; the call is refused, never queued. */
+export declare class DatabaseBusyError extends Error {
+	readonly databaseId: DataStoreDatabase;
+	readonly inFlight: number;
+	constructor(databaseId: DataStoreDatabase, inFlight: number);
+}
+/** An id-addressed call (get/set/update/delete/insert/upsert/guard) on a composite-keyed collection. */
+export declare class CompositeKeyError extends Error {
+	readonly table: string;
+	readonly op: string;
+	readonly keyColumns: readonly string[];
+	constructor(table: string, op: string, keyColumns: readonly string[]);
+}
+/** The wire form of an error that crossed the worker boundary. */
+export interface SerializedError {
+	readonly name: string;
+	readonly message: string;
+	readonly code?: string;
+}
+/** Flatten any thrown value for `postMessage`. */
+export declare function serializeError(err: unknown): SerializedError;
+/**
+* Rebuild an error on the main thread. A name this module knows comes back as
+* an instance of its class (`instanceof` works); anything else comes back as a
+* plain Error with the name and code preserved.
+*/
+export declare function rehydrateError(serialized: SerializedError): Error;

package/dist/builtins/sqlite-storage/placement-router.d.ts

@@ -0,0 +1,80 @@
+/**
+* PLACEMENT (D851): which database file serves a collection.
+*
+* The router IS the engine's `data-store-provider`: the storage orchestrator
+* dispatches to one engine, and this engine fans out to the files it owns.
+* The rule it enforces is small and absolute:
+*
+*  - a collection's file is declared by its owner on `declareCollection`
+*    (`database`, absent = `settings`) and persisted in THAT file's own
+*    `_collection_declarations`;
+*  - at boot the router rebuilds `collection → file` from those tables, and a
+*    collection declared in two files is a boot ERROR naming both — a corrupt
+*    layout is not served;
+*  - a declaration for a file other than the one the table already lives in is
+*    REFUSED ({@link CollectionPlacementError}), never moved. Moving is the
+*    offline split script's job, once (D853). This is the safety net that turns
+*    an accidental deploy to an unconverted hub into a loud failure of ONE
+*    addon instead of a silent empty file beside the real rows;
+*  - every other op resolves its file from the map; an undeclared collection
+*    (the canonical KV set and its `<addonId>:<canonical>` variants) is
+*    `settings`;
+*  - a `transact` spans ONE file ({@link CrossDatabaseTransactError}).
+*
+* A file other than `settings` is created on the FIRST declaration that names
+* it, so an installation where nothing names `events` / `history` grows no new
+* file.
+*/
+import type { DataStoreDatabase, DataStoreEngineInfo, IDataStoreProvider, IScopedLogger } from "@camstack/types";
+import type { DataStoreInput, DataStoreOutput } from "./file-host-protocol.js";
+import type { OwnedSqliteFile } from "./owned-sqlite-file.js";
+/** Opens (creating it if needed) the file for a database id. Called at most once per id. */
+export type OpenDatabaseFile = (databaseId: DataStoreDatabase) => Promise<OwnedSqliteFile>;
+export interface PlacementRouterOptions {
+	/** Files already open at boot — `settings` always, `events` / `history` if they exist on disk. */
+	readonly files: readonly OwnedSqliteFile[];
+	/** How a not-yet-open file is created on first declaration. */
+	readonly open: OpenDatabaseFile;
+	readonly logger: IScopedLogger;
+}
+export declare class PlacementRouter implements IDataStoreProvider {
+	private readonly files;
+	private readonly opening;
+	/** `events` / `history` collections only; absence means `settings`. */
+	private readonly placement;
+	private readonly open;
+	private readonly logger;
+	constructor(options: PlacementRouterOptions);
+	/**
+	* Rebuild `collection → file` from each file's own declarations. A table
+	* declared in two files is refused: nothing downstream could tell which is
+	* the real one.
+	*/
+	private rebuildPlacement;
+	/** The open file of an id; `settings` is always there. */
+	private fileOf;
+	/** The database a table is served from. */
+	databaseOf(table: string): DataStoreDatabase;
+	/** The files currently open, settings first. */
+	openFiles(): readonly OwnedSqliteFile[];
+	private openFile;
+	private route;
+	declareCollection(input: DataStoreInput<"declareCollection">): Promise<void>;
+	transact(input: DataStoreInput<"transact">): Promise<DataStoreOutput<"transact">>;
+	getEngineInfo(): Promise<DataStoreEngineInfo>;
+	get(input: DataStoreInput<"get">): Promise<DataStoreOutput<"get">>;
+	set(input: DataStoreInput<"set">): Promise<DataStoreOutput<"set">>;
+	query(input: DataStoreInput<"query">): Promise<DataStoreOutput<"query">>;
+	insert(input: DataStoreInput<"insert">): Promise<DataStoreOutput<"insert">>;
+	upsert(input: DataStoreInput<"upsert">): Promise<DataStoreOutput<"upsert">>;
+	insertMany(input: DataStoreInput<"insertMany">): Promise<DataStoreOutput<"insertMany">>;
+	upsertMany(input: DataStoreInput<"upsertMany">): Promise<DataStoreOutput<"upsertMany">>;
+	update(input: DataStoreInput<"update">): Promise<DataStoreOutput<"update">>;
+	delete(input: DataStoreInput<"delete">): Promise<DataStoreOutput<"delete">>;
+	deleteWhere(input: DataStoreInput<"deleteWhere">): Promise<DataStoreOutput<"deleteWhere">>;
+	updateWhere(input: DataStoreInput<"updateWhere">): Promise<DataStoreOutput<"updateWhere">>;
+	count(input: DataStoreInput<"count">): Promise<DataStoreOutput<"count">>;
+	aggregate(input: DataStoreInput<"aggregate">): Promise<DataStoreOutput<"aggregate">>;
+	histogram(input: DataStoreInput<"histogram">): Promise<DataStoreOutput<"histogram">>;
+	isEmpty(input: DataStoreInput<"isEmpty">): Promise<DataStoreOutput<"isEmpty">>;
+}

package/dist/builtins/sqlite-storage/retired-collections.d.ts

@@ -67,6 +67,7 @@
 * here — this module drops TABLES, and deleting somebody's database file is a
 * different kind of act.
 */
+import type { OwnedSqliteFile } from "./owned-sqlite-file.js";
 import type { RetiredKeyLogger } from "./retired-settings-keys.js";
 import type { DroppedTable, SqliteSettingsBackend } from "./sqlite-settings-backend.js";
 /** One retired-table declaration. */
@@ -132,6 +133,12 @@ export declare const RETIRED_COLLECTIONS: readonly RetiredCollectionSpec[];
 */
 export declare function retiredCollectionStoreOf(backend: SqliteSettingsBackend): RetiredCollectionStore;
 /**
+* The same adapter over an {@link OwnedSqliteFile} — the purge runs against
+* EVERY open database file (D851), and a file served by a worker answers the
+* drop through its thread.
+*/
+export declare function retiredCollectionStoreOfFile(file: OwnedSqliteFile): RetiredCollectionStore;
+/**
 * Drop every retired table that is still present. Returns one entry per table
 * actually dropped — empty when the schema is already clean, which is the
 * steady state after the first boot that ran it.