@camstack/system 1.2.443 → 1.2.445

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

@@ -0,0 +1,63 @@
+/**
+* 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"> & {
+	isAdoptedLegacyTable(collection: string): Promise<boolean>;
+};
+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"]>;
+	/** True when a declared kind lists `collection` as `adoptsFrom` and adoption finished. */
+	isAdoptedLegacyTable(collection: string): Promise<boolean>;
+	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.
@@ -445,6 +437,23 @@ export declare class SqliteSettingsBackend implements ISettingsBackend {
 		bytes: number | null;
 		declaredThisBoot: boolean;
 	}[];
+	/** Storage-admin only: adopted legacy may still be in `declaredThisBoot` from vestigial declares. */
+	forgetDeclaredThisBoot(name: string): void;
+	/**
+	* Paginated `(id, data)` read of a physical table. Does not consult
+	* `declareCollection` — for migration scripts only.
+	*/
+	readLegacyCollection(input: {
+		readonly collection: string;
+		readonly cursor?: string | undefined;
+		readonly limit?: number | undefined;
+	}): {
+		rows: {
+			id: string;
+			data: Record<string, unknown>;
+		}[];
+		nextCursor: string | null;
+	};
 	/**
 	* Drop one table nobody owns (D870 migration, one-shot). Refuses a canonical
 	* or engine table, one a running addon declared since boot, a table that is
@@ -556,8 +565,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`. */