@camstack/system 1.2.443 → 1.2.444

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

@@ -1,5 +1,5 @@
 import { FilesystemStorageAddon, t as FilesystemStorageProvider } from "./filesystem-storage.addon.mjs";
-import { A as SQLITE_PAGE_CACHE_FLOOR_KIB, D as SQLITE_MMAP_CEILING_BYTES, E as SQLITE_JOURNAL_SIZE_LIMIT_BYTES, F as SQLITE_PROFILE_REPORT_INTERVAL_MS, I as SQLITE_PROFILE_TOP_N, L as SQLITE_SLOW_CALL_MS, M as sqlitePageCacheKibFor, N as SQLITE_ENGINE_STORM_WALL_SHARE, O as SQLITE_MMAP_FLOOR_BYTES, P as SQLITE_PROFILE_REPORT_FLOOR_MS, R as SqliteOpProfiler, a as WalMaintenance, c as SqliteSettingsBackend, i as WAL_MAINTENANCE_INTERVAL_MS, j as sqliteMmapSizeFor, k as SQLITE_PAGE_CACHE_CEILING_KIB, n as WAL_HIGH_WATER_BYTES, r as WAL_IDLE_QUIET_MS, t as WAL_CHECKPOINT_BUSY_TIMEOUT_MS, z as sqliteEngineStorm } from "../../wal-maintenance-sIB32ONp.mjs";
+import { A as SQLITE_MMAP_FLOOR_BYTES, B as SqliteOpProfiler, F as SQLITE_ENGINE_STORM_WALL_SHARE, I as SQLITE_PROFILE_REPORT_FLOOR_MS, L as SQLITE_PROFILE_REPORT_INTERVAL_MS, M as SQLITE_PAGE_CACHE_FLOOR_KIB, N as sqliteMmapSizeFor, O as SQLITE_JOURNAL_SIZE_LIMIT_BYTES, P as sqlitePageCacheKibFor, R as SQLITE_PROFILE_TOP_N, V as sqliteEngineStorm, a as WalMaintenance, c as SqliteSettingsBackend, i as WAL_MAINTENANCE_INTERVAL_MS, j as SQLITE_PAGE_CACHE_CEILING_KIB, k as SQLITE_MMAP_CEILING_BYTES, n as WAL_HIGH_WATER_BYTES, r as WAL_IDLE_QUIET_MS, t as WAL_CHECKPOINT_BUSY_TIMEOUT_MS, z as SQLITE_SLOW_CALL_MS } from "../../wal-maintenance-zRc24mOC.mjs";
 import { SqliteSettingsAddon } from "./sqlite-settings.addon.mjs";
 //#region src/builtins/sqlite-storage/config-store.ts
 var ConfigStore = class {

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

@@ -13,6 +13,7 @@
 * package knows a file path.
 */
 import type { DatabaseSnapshotResult, DataStoreDatabase, IScopedLogger } from "@camstack/types";
+import type { RecordsInput, RecordsOp, RecordsOutput } from "./records/records-engine-types.js";
 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";
@@ -26,6 +27,8 @@ export interface OwnedSqliteFile {
 	readonly databaseId: DataStoreDatabase;
 	readonly livePath: string;
 	call<K extends DataStoreOp>(op: K, input: DataStoreInput<K>): Promise<DataStoreOutput<K>>;
+	/** `records` calls (D881). */
+	records<K extends RecordsOp>(op: K, input: RecordsInput<K>): Promise<RecordsOutput<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. */
@@ -85,6 +88,7 @@ declare abstract class OwnedFileBase implements OwnedSqliteFile {
 	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 records<K extends RecordsOp>(op: K, input: RecordsInput<K>): Promise<RecordsOutput<K>>;
 	abstract declaredCollections(): ReadonlySet<string>;
 	abstract hasTable(name: string): Promise<boolean>;
 	abstract dropRetiredTable(name: string): Promise<DroppedRetiredTable | null>;
@@ -106,10 +110,12 @@ export declare class InlineOwnedFile extends OwnedFileBase {
 	private vectorIndex;
 	private vectorProvider;
 	private maintenance;
+	private recordsEngine;
 	constructor(spec: OwnedSqliteFileSpec, deps: OwnedFileDeps);
 	open(): Promise<void>;
 	getVectorIndex(): SqliteVecVectorIndex | null;
 	call<K extends DataStoreOp>(op: K, input: DataStoreInput<K>): Promise<DataStoreOutput<K>>;
+	records<K extends RecordsOp>(op: K, input: RecordsInput<K>): Promise<RecordsOutput<K>>;
 	vector<K extends VectorOp>(op: K, input: VectorInput<K>): Promise<VectorOutput<K>>;
 	declaredCollections(): ReadonlySet<string>;
 	hasTable(name: string): Promise<boolean>;
@@ -125,6 +131,7 @@ export declare class WorkerOwnedFile extends OwnedFileBase {
 	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>>;
+	records<K extends RecordsOp>(op: K, input: RecordsInput<K>): Promise<RecordsOutput<K>>;
 	declaredCollections(): ReadonlySet<string>;
 	hasTable(name: string): Promise<boolean>;
 	dropRetiredTable(name: string): Promise<DroppedRetiredTable | null>;

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

@@ -55,6 +55,11 @@ export declare class PlacementRouter implements IDataStoreProvider {
 	private fileOf;
 	/** The database a table is served from. */
 	databaseOf(table: string): DataStoreDatabase;
+	/**
+	* The file that hosts records of `databaseId`, created by the first
+	* declaration that names it (`events`). `history` never hosts records.
+	*/
+	recordsFileFor(databaseId: DataStoreDatabase): Promise<OwnedSqliteFile>;
 	/** The files currently open, settings first. */
 	openFiles(): readonly OwnedSqliteFile[];
 	private openFile;

package/dist/builtins/sqlite-storage/records/records-catalog.d.ts

@@ -0,0 +1,29 @@
+import type Database from "better-sqlite3";
+import { type DeclareKindResult, type RecordKindDeclaration } from "@camstack/types";
+/** One kind as the engine holds it. */
+export interface KindRow {
+	readonly kindId: number;
+	readonly owner: string;
+	readonly kind: string;
+	readonly database: "settings" | "events";
+	readonly hash: string;
+	readonly state: "declared" | "orphaned" | "dropped";
+	readonly declaration: RecordKindDeclaration;
+	/** When `adoptRecords` finished copying the legacy table into this kind; the boot guard reads it. */
+	readonly adoptedAt: number | null;
+}
+/** The hash a declaration is known by; two spellings of the same declaration agree. */
+export declare function declarationHash(decl: RecordKindDeclaration): string;
+/** Create the shared tables of a file. Idempotent. */
+export declare function ensureRecordsSchema(db: Database.Database): void;
+/** Every kind this file's catalog holds. */
+export declare function loadKinds(db: Database.Database): readonly KindRow[];
+export interface DeclareOutcome {
+	readonly row: KindRow;
+	readonly result: DeclareKindResult;
+}
+/**
+* Reconcile one kind: insert its catalog row and create the declared indexes,
+* or confirm it is unchanged, or apply an additive change. One transaction.
+*/
+export declare function declareKind(db: Database.Database, owner: string, kind: string, declaration: RecordKindDeclaration, prior: KindRow | undefined): DeclareOutcome;

package/dist/builtins/sqlite-storage/records/records-engine-types.d.ts

@@ -0,0 +1,46 @@
+/**
+* The ops one database file serves for `records` (D881): the `records` cap's
+* methods with an explicit `owner` (the transport-stamped caller, decided by
+* the router) plus the engine's own housekeeping. Pure types: the worker bundle
+* and the main thread both import this.
+*/
+import type { IRecordsProvider, StorageKind } from "@camstack/types";
+/** A `records` cap method's input with the owner the router resolved. */
+export type OwnedInput<M extends keyof IRecordsProvider> = Parameters<IRecordsProvider[M]>[0] & {
+	readonly owner: string;
+};
+type OwnedOps = { readonly [M in keyof IRecordsProvider]: (input: OwnedInput<M>) => Promise<Awaited<ReturnType<IRecordsProvider[M]>>> };
+export interface RecordsEngineOps extends OwnedOps {
+	/** Every kind this file holds, with rows and a size estimate (System -> Data). */
+	listKinds(input: {
+		readonly owner?: string | undefined;
+	}): Promise<readonly StorageKind[]>;
+	/** Delete rows past `expires_at`, in batches. */
+	sweepExpired(input: {
+		readonly batch?: number;
+	}): Promise<{
+		readonly deleted: number;
+	}>;
+	/** Rows of a legacy table in THIS file; `null` when the table is not there. */
+	legacyRowCount(input: {
+		readonly table: string;
+	}): Promise<number | null>;
+	/** Has `adoptRecords` finished copying the legacy table into this kind? (the boot guard) */
+	adoptionState(input: {
+		readonly owner: string;
+		readonly kind: string;
+	}): Promise<{
+		readonly adoptedAt: number | null;
+	}>;
+	/** Record that the copy is complete. Idempotent. */
+	markAdopted(input: {
+		readonly owner: string;
+		readonly kind: string;
+	}): Promise<void>;
+}
+export type RecordsOp = keyof RecordsEngineOps;
+export type RecordsInput<K extends RecordsOp> = Parameters<RecordsEngineOps[K]>[0];
+export type RecordsOutput<K extends RecordsOp> = Awaited<ReturnType<RecordsEngineOps[K]>>;
+export declare const RECORDS_OPS: readonly RecordsOp[];
+export declare function isRecordsOp(op: string): op is RecordsOp;
+export {};

package/dist/builtins/sqlite-storage/records/records-engine.d.ts

@@ -0,0 +1,90 @@
+/**
+* The records engine of ONE database file (D881): the operations behind
+* `ctx.records`, over the same connection the file's collections use.
+*
+* Everything here is synchronous SQLite inside a method that returns a promise,
+* so a big delete can YIELD between batches and the serving thread is not held.
+* One thread per file (D851) serialises every statement, so each op is atomic
+* and a read-modify-write goes through `ifRev`.
+*
+* Every statement is compiled with `kind_id = <literal>` first (records-sql.ts),
+* no op exists without an (owner, kind), and an owner reaches only its own
+* kinds: another addon's kind is indistinguishable from one that does not exist.
+*/
+import type Database from "better-sqlite3";
+import { type DataStoreDatabase, type IScopedLogger, type StorageKind } from "@camstack/types";
+import { type KindRow } from "./records-catalog.js";
+import type { OwnedInput, RecordsEngineOps, RecordsOutput } from "./records-engine-types.js";
+export interface RecordsEngineOptions {
+	readonly databaseId: DataStoreDatabase;
+	readonly logger: IScopedLogger;
+	readonly now?: () => number;
+}
+export declare class RecordsEngine implements RecordsEngineOps {
+	private readonly db;
+	private readonly options;
+	private readonly kinds;
+	private readonly now;
+	private readonly writesSinceTrim;
+	constructor(db: Database.Database, options: RecordsEngineOptions);
+	private schemaReady;
+	private kindOf;
+	declareKinds(input: OwnedInput<"declareKinds">): Promise<RecordsOutput<"declareKinds">>;
+	private timed;
+	private static readonly ROW_SELECT;
+	get(input: OwnedInput<"get">): Promise<RecordsOutput<"get">>;
+	getMany(input: OwnedInput<"getMany">): Promise<RecordsOutput<"getMany">>;
+	secretRefs(input: OwnedInput<"secretRefs">): Promise<RecordsOutput<"secretRefs">>;
+	query(input: OwnedInput<"query">): Promise<RecordsOutput<"query">>;
+	count(input: OwnedInput<"count">): Promise<RecordsOutput<"count">>;
+	histogram(input: OwnedInput<"histogram">): Promise<RecordsOutput<"histogram">>;
+	aggregate(input: OwnedInput<"aggregate">): Promise<RecordsOutput<"aggregate">>;
+	private storedRow;
+	private upsertSql;
+	private wrapWrite;
+	/** One row, inside the caller's transaction. */
+	private writeRecord;
+	put(input: OwnedInput<"put">): Promise<RecordsOutput<"put">>;
+	putMany(input: OwnedInput<"putMany">): Promise<RecordsOutput<"putMany">>;
+	patch(input: OwnedInput<"patch">): Promise<RecordsOutput<"patch">>;
+	private refsOfRows;
+	delete(input: OwnedInput<"delete">): Promise<RecordsOutput<"delete">>;
+	deleteMany(input: OwnedInput<"deleteMany">): Promise<RecordsOutput<"deleteMany">>;
+	/** Delete the rows `selectSql` names, in batches, yielding between them. */
+	private deleteBatched;
+	deleteWhere(input: OwnedInput<"deleteWhere">): Promise<RecordsOutput<"deleteWhere">>;
+	deleteDevice(input: OwnedInput<"deleteDevice">): Promise<RecordsOutput<"deleteDevice">>;
+	allocateId(input: OwnedInput<"allocateId">): Promise<RecordsOutput<"allocateId">>;
+	/**
+	* Trim a ring after a write. Counting a big ring on every write would be the
+	* cost the bound exists to avoid, so a ring of more than TRIM_SLACK rows is
+	* trimmed once per (bound / TRIM_SLACK) writes: the bound holds within 1 %.
+	*/
+	private afterWrite;
+	private trimScope;
+	sweepExpired(input: {
+		readonly batch?: number;
+	}): Promise<{
+		readonly deleted: number;
+	}>;
+	listKinds(input: {
+		readonly owner?: string | undefined;
+		readonly counts?: boolean | undefined;
+	}): Promise<readonly StorageKind[]>;
+	private countRows;
+	/** The declarations this file holds, for the router's placement map and the entries service. */
+	declarations(): readonly KindRow[];
+	legacyRowCount(input: {
+		readonly table: string;
+	}): Promise<number | null>;
+	adoptionState(input: {
+		readonly owner: string;
+		readonly kind: string;
+	}): Promise<{
+		readonly adoptedAt: number | null;
+	}>;
+	markAdopted(input: {
+		readonly owner: string;
+		readonly kind: string;
+	}): Promise<void>;
+}

package/dist/builtins/sqlite-storage/records/records-explain.d.ts

@@ -0,0 +1,18 @@
+/**
+* Reading a SQLite plan for the D447 proof (D881).
+*
+* `EXPLAIN QUERY PLAN` prints `USING INDEX` whether or not the table row is
+* read behind that index entry, so it cannot prove an aggregate is served from
+* the index alone. The VDBE program can: a statement that never reads the
+* table has no `Column` opcode on the table's cursor. Both readers live here
+* because the specs and the `check-records-index-served` guard must agree.
+*/
+import type Database from "better-sqlite3";
+export interface ExplainedStatement {
+	readonly sql: string;
+	readonly params: readonly unknown[];
+}
+/** The `EXPLAIN QUERY PLAN` detail lines of a statement. */
+export declare function planOf(db: Database.Database, s: ExplainedStatement): readonly string[];
+/** How many `Column` opcodes read the `records` TABLE (not an index) in this statement. */
+export declare function tableColumnReads(db: Database.Database, s: ExplainedStatement): number;

package/dist/builtins/sqlite-storage/records/records-plan.d.ts

@@ -0,0 +1,90 @@
+/**
+* Statement planning for `records` (D881): turn a request into SQL that is
+* served by an index BY CONSTRUCTION, or refuse it.
+*
+* - `where` accepts declared index fields only: the equality fields must be the
+*   LEADING fields of one declared index (any order), with at most one range on
+*   the field right after them. Anything else throws {@link UnindexedFilterError}
+*   - an unindexed filter does not compile.
+* - Every index path is named with `INDEXED BY`: if SQLite cannot use that index
+*   for the statement it ERRORS instead of quietly scanning.
+* - Pagination is keyset (`(key..., rid) > cursor`); there is no offset.
+*
+* Pure: no database in here, so the statements are testable (and EXPLAINed) on
+* their own.
+*/
+import { type RecordKindDeclaration, type RecordWhere } from "@camstack/types";
+type Bindable = string | number | null;
+/** A declared index and what a `where` leaves for ordering. */
+export interface WherePlan {
+	readonly index: RecordKindDeclaration["indexes"][number];
+	readonly clauses: readonly string[];
+	readonly params: readonly Bindable[];
+	/** The index fields after the equality prefix: the order a `where` query returns in. */
+	readonly orderFields: readonly string[];
+}
+/**
+* Find the declared index that serves `where` (plus any `extraFields` the
+* statement reads: an aggregate's value and group columns), or throw.
+*/
+export declare function planWhere(kind: string, decl: RecordKindDeclaration, where: RecordWhere | undefined, opts: {
+	readonly allowIn: boolean;
+	readonly extraFields?: readonly string[];
+}): WherePlan | null;
+/** The built-in filters shared by every statement. */
+export interface WindowFilter {
+	readonly deviceId?: number | undefined;
+	readonly atFrom?: number | undefined;
+	readonly atTo?: number | undefined;
+}
+/** The built-in index that serves a device/time window. */
+export declare function windowIndex(w: WindowFilter): string;
+export interface PlannedStatement {
+	readonly sql: string;
+	readonly params: readonly Bindable[];
+}
+export interface PlannedQuery extends PlannedStatement {
+	/** Names the access path; a cursor is valid only for the plan that issued it. */
+	readonly tag: string;
+	/** How many `_k<i>` cursor-key columns the statement selects (before `rid`). */
+	readonly keyCount: number;
+}
+export interface QueryRequest extends WindowFilter {
+	readonly where?: RecordWhere | undefined;
+	readonly order?: "at" | "id" | undefined;
+	readonly desc?: boolean | undefined;
+	readonly limit: number;
+	/** A decoded cursor: the tag of the plan that issued it, and its key values. */
+	readonly cursor?: {
+		readonly tag: string;
+		readonly values: readonly Bindable[];
+	} | undefined;
+}
+export declare function planQuery(kind: string, kindId: number, decl: RecordKindDeclaration, q: QueryRequest): PlannedQuery;
+export interface CountRequest extends WindowFilter {
+	readonly where?: RecordWhere | undefined;
+}
+export declare function planCount(kind: string, kindId: number, decl: RecordKindDeclaration, q: CountRequest): PlannedStatement;
+export interface HistogramRequest {
+	readonly deviceId?: number | undefined;
+	readonly from: number;
+	readonly to: number;
+	readonly bucketMs: number;
+}
+/** Buckets one answer may carry: a histogram is a chart, not an export. */
+export declare const HISTOGRAM_MAX_BUCKETS = 1e4;
+export declare function planHistogram(kind: string, kindId: number, decl: RecordKindDeclaration, q: HistogramRequest): PlannedStatement;
+export interface AggregateRequest {
+	readonly op: "sum" | "min" | "max" | "count";
+	readonly field?: string | undefined;
+	readonly groupBy?: string | undefined;
+	readonly where?: RecordWhere | undefined;
+}
+export declare function planAggregate(kind: string, kindId: number, decl: RecordKindDeclaration, q: AggregateRequest): PlannedStatement;
+export interface DeleteWhereRequest extends WindowFilter {
+	readonly atBefore?: number | undefined;
+	readonly where?: RecordWhere | undefined;
+}
+/** The subselect that names up to `limit` rows to delete. */
+export declare function planDeleteWhere(kind: string, kindId: number, decl: RecordKindDeclaration, q: DeleteWhereRequest, limit: number): PlannedStatement;
+export {};

package/dist/builtins/sqlite-storage/records/records-probe.d.ts

@@ -0,0 +1,33 @@
+/**
+* The index-served proof of a record kind (D881, D447), run on the statements
+* the engine REALLY prepares.
+*
+* A kind is declared with its indexes; this builds an in-memory engine, declares
+* the kind, runs every operation the kind's declaration promises (by device and
+* time, by id, by each declared index at each prefix length, the counts, the
+* histogram, the aggregates over indexed fields, the bounded deletes) with a
+* spy on `prepare`, and then EXPLAINs each captured statement:
+*
+*  - no plan may be a table SCAN, and none may sort (`TEMP B-TREE FOR ORDER BY`);
+*  - every statement names `kind_id` as a literal (the partial indexes need it);
+*  - a count and an aggregate must not read the table row - checked on the
+*    opcodes, because `EXPLAIN QUERY PLAN` says `USING INDEX` either way.
+*
+* It is what `scripts/check-records-index-served.ts` runs over every declared
+* kind, and what its spec runs over a deliberately broken one.
+*/
+import Database from "better-sqlite3";
+import type { DefinedRecordKind } from "@camstack/types";
+export interface ProbeProblem {
+	readonly kind: string;
+	readonly op: string;
+	readonly problem: string;
+}
+export interface Captured {
+	readonly sql: string;
+	readonly params: readonly unknown[];
+}
+/** Judge one prepared statement. Exported so a spec can plant a bad one and watch it fail. */
+export declare function judgeStatement(db: Database.Database, kind: string, op: string, statement: Captured): readonly ProbeProblem[];
+/** Probe one kind. An empty answer means every promised operation is served from an index. */
+export declare function probeKind(def: DefinedRecordKind): Promise<readonly ProbeProblem[]>;

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

@@ -0,0 +1,59 @@
+/**
+* The `records` capability of the engine (D881): resolves WHO is calling and
+* WHICH file a kind lives in, then hands the call to that file's records engine.
+*
+* - **Owner** = the transport-stamped `callerAddonId` (as device-history's
+*   `not-owner` and the keychain). It is never a field of any input; a call with
+*   no stamp is refused `records/no-caller`.
+* - **Placement**: a kind's file is its declaration's `database`. The map is
+*   rebuilt from each open file's own `_record_kinds` at boot and updated on
+*   declaration. A kind declared for another file than the one it lives in is
+*   refused (the engine never moves data, D853).
+* - **The boot guard**: after a declaration, a kind with `adoptsFrom` that is
+*   EMPTY while its legacy table still holds rows is reported `adoptionPending`;
+*   `ctx.records.declare` turns that into a refusal to start.
+*/
+import { type IRecordsProvider, type IScopedLogger, type IStorageAdminProvider, type StorageKind } from "@camstack/types";
+import type { PlacementRouter } from "../placement-router.js";
+/** The caller the transport stamped, or a refusal. */
+export declare function recordsCallerOf(input: unknown): string;
+type AdminRecords = Pick<IStorageAdminProvider, "listKinds" | "readRecords" | "adoptRecords">;
+export declare class RecordsProvider implements IRecordsProvider, AdminRecords {
+	private readonly router;
+	private readonly logger;
+	private readonly placement;
+	constructor(router: PlacementRouter, logger: IScopedLogger);
+	/** Rebuild the placement map from every open file's catalog. Call once, after the files are open. */
+	init(): Promise<void>;
+	private fileOf;
+	declareKinds(input: Parameters<IRecordsProvider["declareKinds"]>[0]): ReturnType<IRecordsProvider["declareKinds"]>;
+	/** The boot guard: empty kind + a legacy table that still has rows = adoption pending. */
+	private withAdoption;
+	get(input: Parameters<IRecordsProvider["get"]>[0]): ReturnType<IRecordsProvider["get"]>;
+	getMany(input: Parameters<IRecordsProvider["getMany"]>[0]): ReturnType<IRecordsProvider["getMany"]>;
+	secretRefs(input: Parameters<IRecordsProvider["secretRefs"]>[0]): ReturnType<IRecordsProvider["secretRefs"]>;
+	put(input: Parameters<IRecordsProvider["put"]>[0]): ReturnType<IRecordsProvider["put"]>;
+	putMany(input: Parameters<IRecordsProvider["putMany"]>[0]): ReturnType<IRecordsProvider["putMany"]>;
+	patch(input: Parameters<IRecordsProvider["patch"]>[0]): ReturnType<IRecordsProvider["patch"]>;
+	delete(input: Parameters<IRecordsProvider["delete"]>[0]): ReturnType<IRecordsProvider["delete"]>;
+	deleteMany(input: Parameters<IRecordsProvider["deleteMany"]>[0]): ReturnType<IRecordsProvider["deleteMany"]>;
+	query(input: Parameters<IRecordsProvider["query"]>[0]): ReturnType<IRecordsProvider["query"]>;
+	count(input: Parameters<IRecordsProvider["count"]>[0]): ReturnType<IRecordsProvider["count"]>;
+	histogram(input: Parameters<IRecordsProvider["histogram"]>[0]): ReturnType<IRecordsProvider["histogram"]>;
+	aggregate(input: Parameters<IRecordsProvider["aggregate"]>[0]): ReturnType<IRecordsProvider["aggregate"]>;
+	deleteWhere(input: Parameters<IRecordsProvider["deleteWhere"]>[0]): ReturnType<IRecordsProvider["deleteWhere"]>;
+	allocateId(input: Parameters<IRecordsProvider["allocateId"]>[0]): ReturnType<IRecordsProvider["allocateId"]>;
+	/** The D865 hook body: every file that holds kinds of this owner. */
+	deleteDevice(input: Parameters<IRecordsProvider["deleteDevice"]>[0]): ReturnType<IRecordsProvider["deleteDevice"]>;
+	listKinds(input: {
+		readonly owner?: string | undefined;
+		readonly counts?: boolean | undefined;
+	}): Promise<{
+		kinds: StorageKind[];
+	}>;
+	readRecords(input: Parameters<IStorageAdminProvider["readRecords"]>[0]): ReturnType<IStorageAdminProvider["readRecords"]>;
+	adoptRecords(input: Parameters<IStorageAdminProvider["adoptRecords"]>[0]): ReturnType<IStorageAdminProvider["adoptRecords"]>;
+	/** Housekeeping: delete rows past `expires_at` in every file that hosts kinds. */
+	sweepExpired(): Promise<number>;
+}
+export {};

package/dist/builtins/sqlite-storage/records/records-rows.d.ts

@@ -0,0 +1,46 @@
+/**
+* Row-level helpers of the records engine (D881): validating a write against
+* its kind, enforcing the secret-field rules, and shaping what a read returns.
+* Pure - no database here.
+*/
+import { type RecordInput, type RecordKindDeclaration, type RecordView } from "@camstack/types";
+/** A row as `SELECT` returns it (the `data` column is `json(data)`). */
+export interface StoredRow {
+	readonly rid: number;
+	readonly id: string;
+	readonly deviceId: number | null;
+	readonly at: number | null;
+	readonly expiresAt: number | null;
+	readonly rev: number;
+	readonly updatedAt: number;
+	readonly data: string;
+}
+export declare function parseBody(text: string): Record<string, unknown>;
+/** What a write is allowed to say about a row, after the kind's rules. */
+export interface WriteHeader {
+	readonly id: string;
+	readonly deviceId: number | null;
+	readonly at: number | null;
+	readonly expiresAt: number | null;
+}
+export declare function validateHeader(kind: string, decl: RecordKindDeclaration, rec: Pick<RecordInput, "id" | "deviceId" | "at" | "expiresAt">, nowMs: number): WriteHeader;
+/** Serialize the body and enforce `maxDataBytes`; `onTooLarge` is called (rate-limited) before throwing. */
+export declare function serializeBody(kind: string, decl: RecordKindDeclaration, id: string, body: Record<string, unknown>, onTooLarge: (kind: string, bytes: number) => void, nowMs: number): string;
+/** Markers found in a stored body, by concrete path. */
+export declare function markersOf(decl: RecordKindDeclaration, body: unknown): ReadonlyMap<string, string>;
+/** Show a stored body: every set secret field becomes the redaction token. */
+export declare function redactBody(decl: RecordKindDeclaration, body: Record<string, unknown>): Record<string, unknown>;
+/**
+* The secret rule of a write (D878, once, in the store): a secret field may
+* hold ONLY a keychain marker bound to this row's own ref. The redaction token
+* keeps the stored marker (or leaves the field absent when nothing is stored);
+* `null` removes; a plain string is refused - plaintext is never stored.
+*
+* `stored` is the row's current body (null for a new row). Returns the body to
+* write and the refs the write RELEASES (markers that were stored and are gone).
+*/
+export declare function enforceSecrets(owner: string, kind: string, decl: RecordKindDeclaration, id: string, body: Record<string, unknown>, stored: Record<string, unknown> | null, mode: "put" | "patch"): {
+	readonly body: Record<string, unknown>;
+	readonly releasedRefs: readonly string[];
+};
+export declare function toView(row: StoredRow, decl: RecordKindDeclaration): RecordView;

package/dist/builtins/sqlite-storage/records/records-sql.d.ts

@@ -0,0 +1,41 @@
+/**
+* @durable class=ledger owner=records
+*   write="every ctx.records write of an owning addon: one row per record of any declared kind, keyed (kind_id, id)"
+*   retention="per kind, declared with the kind: an engine ttl, a row bound, the owner's own sweep, or none - the reason is shown in System -> Data"
+*/
+export declare const RECORDS_TABLE = "records";
+/**
+* @durable class=config owner=records
+*   write="an owner declares its kinds when its addon boots (declareKinds): one row per (owner, kind)"
+*   retention="none - a kind row is never removed by this release; a kind no installed package declares is only marked orphaned"
+*/
+export declare const RECORD_KINDS_TABLE = "_record_kinds";
+/**
+* @durable class=config owner=records
+*   write="allocateId on a kind: one counter row per kind"
+*   retention="none - the counter must never go back, so it is never pruned"
+*/
+export declare const RECORD_SEQUENCES_TABLE = "_record_sequences";
+/** The statements that create the shared tables. Idempotent. */
+export declare const RECORDS_SCHEMA_SQL = "\nCREATE TABLE IF NOT EXISTS records (\n  rid        INTEGER PRIMARY KEY,\n  kind_id    INTEGER NOT NULL,\n  id         TEXT    NOT NULL,\n  device_id  INTEGER,\n  at         INTEGER,\n  expires_at INTEGER,\n  rev        INTEGER NOT NULL DEFAULT 1,\n  updated_at INTEGER NOT NULL,\n  data       BLOB    NOT NULL,\n  UNIQUE (kind_id, id)\n);\nCREATE INDEX IF NOT EXISTS records_kind_device_at ON records(kind_id, device_id, at);\nCREATE INDEX IF NOT EXISTS records_kind_at ON records(kind_id, at);\nCREATE INDEX IF NOT EXISTS records_expires ON records(expires_at) WHERE expires_at IS NOT NULL;\nCREATE TABLE IF NOT EXISTS _record_kinds (\n  kind_id       INTEGER PRIMARY KEY AUTOINCREMENT,\n  owner         TEXT NOT NULL,\n  kind          TEXT NOT NULL,\n  database      TEXT NOT NULL,\n  manifest_hash TEXT NOT NULL,\n  declaration   TEXT NOT NULL,\n  state         TEXT NOT NULL,\n  orphaned_at   INTEGER,\n  adopted_at    INTEGER,\n  UNIQUE (owner, kind)\n);\nCREATE TABLE IF NOT EXISTS _record_sequences (\n  kind_id INTEGER PRIMARY KEY,\n  next    INTEGER NOT NULL\n);\n";
+/** The tables the records engine owns: never droppable through `dropCollection`. */
+export declare const RECORDS_ENGINE_TABLES: readonly string[];
+/** The built-in indexes. */
+export declare const INDEX_KIND_DEVICE_AT = "records_kind_device_at";
+export declare const INDEX_KIND_AT = "records_kind_at";
+export declare const INDEX_EXPIRES = "records_expires";
+/**
+* The expression of a record field: `json_extract("data", '$.a.b')`. THE one
+* renderer. Throws on a path outside the safe charset (it lands in DDL).
+*/
+export declare function recordFieldExpr(field: string): string;
+/** `kind_id = 17` as text; the argument must be a safe integer from the catalog. */
+export declare function kindClause(kindId: number): string;
+/** The physical name of a declared index. */
+export declare function indexName(kindId: number, name: string): string;
+/** The exact DDL of one declared index. Compared character for character when it already exists. */
+export declare function indexDdl(kindId: number, index: {
+	readonly name: string;
+	readonly fields: readonly string[];
+	readonly unique?: boolean | undefined;
+}): string;

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

@@ -403,14 +403,6 @@ export declare class SqliteSettingsBackend implements ISettingsBackend {
 	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;
 	/**
 	* The device's whole cap-slice map. `{}` — never null — when the device has never persisted a slice,
 	* because every caller treats the result as a cap map to iterate.
@@ -556,8 +548,6 @@ export declare class SqliteSettingsBackend implements ISettingsBackend {
 	* function refuses degrades in speed and never in correctness.
 	*/
 	private prefixWhere;
-	private getAllScoped;
-	private setScopedKey;
 	private scopedName;
 	/**
 	* Project a declared collection onto what {@link compileFilter} needs. A

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

@@ -32,6 +32,8 @@ import type { SqliteVecVectorIndex } from "./vector-index-vec.js";
 export declare class SqliteSettingsAddon extends BaseAddon {
 	private settingsFile;
 	private router;
+	private sweepTimer;
+	private sweepStart;
 	constructor();
 	/**
 	* The engine behind `settings-store` cannot read that door during
@@ -50,6 +52,12 @@ export declare class SqliteSettingsAddon extends BaseAddon {
 	* open file).
 	*/
 	private purgeBeforeServing;
+	/**
+	* The engine's TTL sweep (D881): every 10 minutes, off the boot path (the
+	* first run a minute after boot), batched and yielding. A failed pass is
+	* warned about and the next one retries; it never blocks anything.
+	*/
+	private startRecordsSweep;
 	protected onShutdown(): Promise<void>;
 	getBackend(): SqliteSettingsBackend | null;
 	/** The placement router; null before `onInitialize`. */