@camstack/system 1.2.423 → 1.2.425

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.

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

@@ -1,7 +1,25 @@
-import type { BulkRecord, CollectionColumn, CollectionIndex, DataStoreEngineInfo, HistogramBucket, IScopedLogger, ISettingsBackend, QueryFilter, SettingsAggregateInput, SettingsAggregateResult, SettingsCountInput, SettingsDeleteInput, SettingsGetInput, SettingsHistogramInput, SettingsInsertInput, SettingsIsEmptyInput, SettingsQueryInput, SettingsRecord, SettingsSetInput, SettingsUpdateInput, SettingsUpsertInput } from "@camstack/types";
+import type { BulkRecord, DataStoreDatabase, DataStoreEngineInfo, DeclareCollectionInput, HistogramBucket, IScopedLogger, ISettingsBackend, QueryFilter, SettingsAggregateInput, SettingsAggregateResult, SettingsCountInput, SettingsDeleteInput, SettingsGetInput, SettingsHistogramInput, SettingsInsertInput, SettingsIsEmptyInput, SettingsQueryInput, SettingsRecord, SettingsSetInput, SettingsUpdateInput, SettingsUpsertInput } from "@camstack/types";
 import Database from "better-sqlite3";
 import { type MutationFilterInput } from "./filter-compiler.js";
 import { SqliteOpProfiler } from "./query-profiler.js";
+/** How one file of the engine is opened. All optional: the defaults are `camstack.db`'s. */
+export interface SqliteSettingsBackendOptions {
+	/** Which file this is — names it in log lines. Default `settings`. */
+	readonly databaseId?: DataStoreDatabase;
+	/**
+	* `incremental` sets `auto_vacuum = INCREMENTAL` — but ONLY on a file this
+	* open CREATES: the mode is fixed when the first table is written, and
+	* changing it on an existing file means a full `VACUUM`, which is the ops
+	* script's job (D853), never a boot step. Default `none`.
+	*/
+	readonly autoVacuum?: "none" | "incremental";
+	/**
+	* Declare the canonical key/value collections and seed the defaults. True
+	* only for `settings`: canonical KV collections are settings by definition,
+	* and a second copy of them in `events.db` would be a table nobody reads.
+	*/
+	readonly canonicalKv?: boolean;
+}
 /** Input for {@link SqliteSettingsBackend.insertMany}. */
 interface SettingsInsertManyInput {
 	readonly namespace?: string;
@@ -11,6 +29,16 @@ interface SettingsInsertManyInput {
 interface SettingsInsertManyResult {
 	readonly inserted: number;
 }
+/** Input for {@link SqliteSettingsBackend.upsertMany}. */
+interface SettingsUpsertManyInput {
+	readonly namespace?: string;
+	readonly collection: string;
+	readonly conflict: readonly string[];
+	readonly records: readonly BulkRecord[];
+}
+interface SettingsUpsertManyResult {
+	readonly upserted: number;
+}
 /** Input for {@link SqliteSettingsBackend.transact}. */
 interface SettingsTransactInput {
 	readonly namespace?: string;
@@ -33,6 +61,11 @@ interface SettingsTransactInput {
 		readonly collection: string;
 		readonly id: string;
 		readonly data: Record<string, unknown>;
+	} | {
+		readonly op: "upsertMany";
+		readonly collection: string;
+		readonly conflict: readonly string[];
+		readonly records: readonly BulkRecord[];
 	})[];
 }
 interface SettingsTransactResult {
@@ -157,7 +190,8 @@ export declare class SqliteSettingsBackend implements ISettingsBackend {
 	* is the failure this was built for (`query-profiler.ts`).
 	*/
 	private readonly profiler;
-	constructor(dbPath: string, runtimeDefaults?: Record<string, unknown>, logger?: IScopedLogger);
+	private readonly options;
+	constructor(dbPath: string, runtimeDefaults?: Record<string, unknown>, logger?: IScopedLogger, options?: SqliteSettingsBackendOptions);
 	initialize(): Promise<void>;
 	private requireDeclared;
 	/**
@@ -229,6 +263,18 @@ export declare class SqliteSettingsBackend implements ISettingsBackend {
 	/** The synchronous body of {@link insertMany}, shared with {@link transact}. */
 	private insertManySync;
 	/**
+	* Upsert a batch in ONE transaction, on ONE prepared statement.
+	*
+	* {@link upsert}'s batch twin: `INSERT … ON CONFLICT(<slot>) DO UPDATE`. One
+	* statement shape means every record must name the SAME declared columns and
+	* every `conflict` column — a record that mentioned fewer would otherwise
+	* bind NULL over a value the caller never meant to touch, so a heterogeneous
+	* batch is refused whole, before any SQL runs.
+	*/
+	upsertMany({ namespace, collection, conflict, records }: SettingsUpsertManyInput): Promise<SettingsUpsertManyResult>;
+	/** The synchronous body of {@link upsertMany}, shared with {@link transact}. */
+	private upsertManySync;
+	/**
 	* Several writes, one transaction, behind an optional guard.
 	*
 	* `better-sqlite3`'s `transaction()` is synchronous and rolls the whole call
@@ -372,6 +418,25 @@ export declare class SqliteSettingsBackend implements ISettingsBackend {
 	* Returns null if the backend has not been initialized yet.
 	*/
 	getDatabase(): Database.Database | null;
+	/** Which file this backend serves. */
+	getDatabaseId(): DataStoreDatabase;
+	/**
+	* The tables this file's own `_collection_declarations` names — the
+	* placement authority (D851). Read from DISK, not from memory, so a table
+	* created and declared by an earlier life of the process still counts.
+	*/
+	declaredCollectionNames(): ReadonlySet<string>;
+	/** Does a table of this name exist in THIS file? */
+	hasTable(name: string): boolean;
+	/** Refuse an id-addressed call on a composite-keyed collection. */
+	private requireSingleKey;
+	/**
+	* The composite key of a declaration, validated: every name is a declared
+	* column, no column also claims `primaryKey: true`, and `withoutRowid` has a
+	* key to be keyed by. A single-name `primaryKey` is the single-column key it
+	* always was and returns empty.
+	*/
+	private resolveKeyColumns;
 	/**
 	* `EXPLAIN QUERY PLAN` for a statement, as one string per plan row.
 	*
@@ -494,12 +559,7 @@ export declare class SqliteSettingsBackend implements ISettingsBackend {
 	* had the chance to re-declare — which on a respawn none of them will.
 	*/
 	private restorePersistedDeclarations;
-	declareCollection(input: {
-		namespace?: string;
-		collection: string;
-		columns: readonly CollectionColumn[];
-		indexes?: readonly CollectionIndex[];
-	}): Promise<void>;
+	declareCollection(declared: DeclareCollectionInput): Promise<void>;
 	/** Serialise per-column values for SQL binding: objects → JSON, booleans → 0/1. */
 	private serializeColumnValue;
 	private ensureTable;

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

@@ -1,7 +1,8 @@
 import type { ProviderRegistration } from "@camstack/types";
 import { BaseAddon } from "@camstack/types";
-import { SqliteSettingsBackend } from "./sqlite-settings-backend.js";
-import { SqliteVecVectorIndex } from "./vector-index-vec.js";
+import { PlacementRouter } from "./placement-router.js";
+import type { SqliteSettingsBackend } from "./sqlite-settings-backend.js";
+import type { SqliteVecVectorIndex } from "./vector-index-vec.js";
 /**
 * SQLite Settings addon — the relational ENGINE behind the data door.
 *
@@ -12,22 +13,25 @@ import { SqliteVecVectorIndex } from "./vector-index-vec.js";
 * engine only through the door — which is the point, because it is what
 * makes the engine replaceable.
 *
+* ONE engine process, SEVERAL owned files ([D851](../../../../../docs/decisions/adr-0851-one-sqlite-engine-serves-several-owned-files-one-thread-per-file.md)):
+* `camstack.db` (settings) is served on this thread exactly as it always was;
+* `events.db` and `history.db`, when a collection names them, are each served
+* by a worker thread. A {@link PlacementRouter} is the provider the door sees.
+* The layout of the files is documented in `docs/architecture/storage-files.md`.
+*
 * It also serves `database-snapshot` (singleton, internal): the verified copy
 * of its database that the nightly backup archives in place of the live files
 * (D693).
 *
-* It ALSO serves `vector-store` (singleton, internal), from the same database
-* file and the same open handle. That capability first shipped as its own addon
-* and the separation cost two round trips per write — caller → door → engine —
-* plus a runner process, to reach a database this addon already has open. The
+* It ALSO serves `vector-store` (singleton, internal), from the settings file's
+* open handle. That capability first shipped as its own addon and the
+* separation cost two round trips per write — caller → door → engine — plus a
+* runner process, to reach a database this addon already has open. The
 * capability is what keeps the backend swappable; the package never was.
 */
 export declare class SqliteSettingsAddon extends BaseAddon {
-	private backend;
-	private vectorIndex;
-	private walMaintenance;
-	private walCheckpointer;
-	private shmLockCanary;
+	private settingsFile;
+	private router;
 	constructor();
 	/**
 	* The engine behind `settings-store` cannot read that door during
@@ -40,23 +44,16 @@ export declare class SqliteSettingsAddon extends BaseAddon {
 	*/
 	protected override resolveConfig(): Promise<void>;
 	protected onInitialize(): Promise<ProviderRegistration[]>;
-	protected onShutdown(): Promise<void>;
-	getBackend(): SqliteSettingsBackend | null;
 	/**
-	* Build the vector index.
-	*
-	* ONE implementation, deliberately. A second backend behind a flag means two
-	* code paths that can disagree, two sets of gotchas, and a silent fallback
-	* that turns "the extension is missing" into "search is mysteriously slow" —
-	* the failure this codebase keeps paying for. The capability is the swap
-	* point: another provider replaces this one wholesale, it does not hide
-	* inside it.
-	*
-	* So a failed extension load THROWS. A node without the native binary must
-	* fail at boot with a message naming sqlite-vec, not serve degraded results
-	* nobody knows are degraded.
+	* Housekeeping that must happen BEFORE anything can read a file: the
+	* retired-key purge (settings only) and the retired-table purge (every
+	* open file).
 	*/
-	private createVectorIndex;
+	private purgeBeforeServing;
+	protected onShutdown(): Promise<void>;
+	getBackend(): SqliteSettingsBackend | null;
+	/** The placement router; null before `onInitialize`. */
+	getRouter(): PlacementRouter | null;
 	/** Exposed for tests; null before `onInitialize`. */
 	getVectorIndex(): SqliteVecVectorIndex | null;
 }

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

@@ -0,0 +1,24 @@
+import type { IScopedLogger, IVectorStoreProvider } from "@camstack/types";
+import type { SqliteSettingsBackend } from "./sqlite-settings-backend.js";
+import { SqliteVecVectorIndex } from "./vector-index-vec.js";
+/**
+* Build the vector index over a backend's connection.
+*
+* ONE implementation, deliberately. A second backend behind a flag means two
+* code paths that can disagree, two sets of gotchas, and a silent fallback
+* that turns "the extension is missing" into "search is mysteriously slow" —
+* the failure this codebase keeps paying for. The capability is the swap
+* point: another provider replaces this one wholesale, it does not hide
+* inside it.
+*
+* So a failed extension load THROWS. A node without the native binary must
+* fail at boot with a message naming sqlite-vec, not serve degraded results
+* nobody knows are degraded.
+*/
+export declare function createVectorIndex(backend: SqliteSettingsBackend, logger: IScopedLogger): SqliteVecVectorIndex;
+/**
+* The `vector-store` provider surface over one sqlite-vec index. Extracted
+* from the addon so the main thread (settings) and the file-host worker
+* (events) serve the SAME mapping.
+*/
+export declare function vectorProviderOf(vectorIndex: SqliteVecVectorIndex): IVectorStoreProvider;

package/dist/builtins/sqlite-storage/wal-maintenance.d.ts

@@ -74,6 +74,14 @@ export interface WalMaintenanceOptions {
 	readonly idleQuietMs?: number;
 	readonly intervalMs?: number;
 	readonly busyTimeoutMs?: number;
+	/**
+	* Pages to hand back to the filesystem per idle tick with
+	* `PRAGMA incremental_vacuum(N)`. Absent or 0 = never. Only a file created
+	* with `auto_vacuum = INCREMENTAL` (D851) has a freelist this can shrink; on
+	* any other the pragma is a no-op, and the tick checks the mode first so it
+	* does not even try.
+	*/
+	readonly incrementalVacuumPages?: number;
 }
 /**
 * Periodic, heavily gated `wal_checkpoint(TRUNCATE)`.
@@ -92,11 +100,20 @@ export declare class WalMaintenance {
 	private readonly idleQuietMs;
 	private readonly intervalMs;
 	private readonly busyTimeoutMs;
+	private readonly incrementalVacuumPages;
 	private timer;
 	constructor(options: WalMaintenanceOptions);
 	start(): void;
 	stop(): void;
 	isRunning(): boolean;
+	/**
+	* Give up to `incrementalVacuumPages` free pages back, when the file is in
+	* incremental auto-vacuum mode, has a freelist, and nothing has written for
+	* the idle window (the same gate the checkpoint uses — reclaiming pages
+	* takes the writer lock). Returns the pages released; 0 when it did nothing.
+	* Never throws.
+	*/
+	vacuumOnce(): number;
 	/** Evaluate the gate once and act. Never throws. */
 	runOnce(): WalMaintenanceOutcome;
 	private evaluate;

package/dist/builtins/storage-orchestrator/storage-orchestrator.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-DnALrQF-.js");
 let zod = require("zod");
 let node_crypto = require("node:crypto");
 let _camstack_types_node = require("@camstack/types/node");
@@ -1237,6 +1237,7 @@ function createDataStoreDispatch(getEngines, getRemote) {
 		insert: async (input) => (await engine()).insert(input),
 		upsert: async (input) => (await engine()).upsert(input),
 		insertMany: async (input) => (await engine()).insertMany(input),
+		upsertMany: async (input) => (await engine()).upsertMany(input),
 		transact: async (input) => (await engine()).transact(input),
 		update: async (input) => (await engine()).update(input),
 		delete: async (input) => (await engine()).delete(input),
@@ -1554,6 +1555,7 @@ function createHubSettingsForward(forward) {
 		insert: (input) => send("insert", input),
 		upsert: (input) => send("upsert", input),
 		insertMany: (input) => send("insertMany", input),
+		upsertMany: (input) => send("upsertMany", input),
 		transact: (input) => send("transact", input),
 		update: (input) => send("update", input),
 		delete: (input) => send("delete", input),

package/dist/builtins/storage-orchestrator/storage-orchestrator.addon.mjs

@@ -1,4 +1,4 @@
-import { $r as transformSecretWrite, $t as mayReadLocation, B as StorageLocationModeSchema, Dt as evictionPolicyOfLocation, Gn as withLocationMode, H as StorageMigrationJobSchema, Ir as isSecretMarker, Jr as secretTreeFromPaths, Kr as resolveSecretMarkers, Kt as legacyModeOf, Mn as storageCapability, Nn as storageMigrationCapability, Pt as gbToBytes, Sn as resolveLocationMode, Sr as collectSecretConfigKeys, V as StorageLocationTypeSchema, Vr as parseJsonObject, cr as BaseAddon, ei as EventCategory, en as mayWriteToLocation, fr as REDACTED_SECRET, k as LegacyStorageLocationDefaultSchema, kn as settingsStoreCapability, rn as modeMayWrite, z as StorageCleanupJobSchema, zt as isLocationEnabled } from "../../dist-DimotS8e.mjs";
+import { A as LegacyStorageLocationDefaultSchema, An as settingsStoreCapability, B as StorageCleanupJobSchema, Bt as isLocationEnabled, Cn as resolveLocationMode, Cr as collectSecretConfigKeys, Ft as gbToBytes, H as StorageLocationTypeSchema, Hr as parseJsonObject, Kn as withLocationMode, Lr as isSecretMarker, Nn as storageCapability, Ot as evictionPolicyOfLocation, Pn as storageMigrationCapability, U as StorageMigrationJobSchema, V as StorageLocationModeSchema, Yr as secretTreeFromPaths, ei as transformSecretWrite, en as mayReadLocation, in as modeMayWrite, lr as BaseAddon, pr as REDACTED_SECRET, qr as resolveSecretMarkers, qt as legacyModeOf, ti as EventCategory, tn as mayWriteToLocation } from "../../dist-DMWeqeTF.mjs";
 import { z } from "zod";
 import { randomUUID } from "node:crypto";
 import { containsOrEquals, physicalRootOf } from "@camstack/types/node";
@@ -1232,6 +1232,7 @@ function createDataStoreDispatch(getEngines, getRemote) {
 		insert: async (input) => (await engine()).insert(input),
 		upsert: async (input) => (await engine()).upsert(input),
 		insertMany: async (input) => (await engine()).insertMany(input),
+		upsertMany: async (input) => (await engine()).upsertMany(input),
 		transact: async (input) => (await engine()).transact(input),
 		update: async (input) => (await engine()).update(input),
 		delete: async (input) => (await engine()).delete(input),
@@ -1549,6 +1550,7 @@ function createHubSettingsForward(forward) {
 		insert: (input) => send("insert", input),
 		upsert: (input) => send("upsert", input),
 		insertMany: (input) => send("insertMany", input),
+		upsertMany: (input) => send("upsertMany", input),
 		transact: (input) => send("transact", input),
 		update: (input) => send("update", input),
 		delete: (input) => send("delete", input),