@camstack/system 1.2.443 → 1.2.445

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

@@ -3,9 +3,9 @@ Object.defineProperties(exports, {
 	[Symbol.toStringTag]: { value: "Module" }
 });
 const require_chunk = require("../../chunk-Cek0wNdY.js");
-const require_dist = require("../../dist-D9qT3jHr.js");
+const require_dist = require("../../dist-DgOG8flk.js");
 const require_retired_settings_keys = require("../../retired-settings-keys-D_VwZiDt.js");
-const require_wal_maintenance = require("../../wal-maintenance-cRHR4rUY.js");
+const require_wal_maintenance = require("../../wal-maintenance-CODGqhKY.js");
 const require_sqlite_snapshot_protocol = require("../../sqlite-snapshot-protocol-B9OndqZv.js");
 const require_wal_checkpoint_policy = require("../../wal-checkpoint-policy-d2z2qPqx.js");
 let node_fs_promises = require("node:fs/promises");
@@ -107,6 +107,13 @@ var FileHostClient = class {
 			input
 		});
 	}
+	records(op, input) {
+		return this.request({
+			kind: "records",
+			op,
+			input
+		});
+	}
 	control(op, input) {
 		return this.request({
 			kind: "control",
@@ -869,6 +876,7 @@ var InlineOwnedFile = class extends OwnedFileBase {
 	vectorIndex = null;
 	vectorProvider = null;
 	maintenance = null;
+	recordsEngine = null;
 	constructor(spec, deps) {
 		super(spec, deps);
 		this.backend = new require_wal_maintenance.SqliteSettingsBackend(spec.livePath, deps.runtimeDefaults === void 0 ? {} : { ...deps.runtimeDefaults }, this.log("Query"), {
@@ -886,6 +894,11 @@ var InlineOwnedFile = class extends OwnedFileBase {
 			this.vectorIndex = vectorIndex;
 			this.vectorProvider = require_wal_maintenance.vectorProviderOf(vectorIndex);
 		}
+		const handle = this.backend.getDatabase();
+		if (handle !== null) this.recordsEngine = new require_wal_maintenance.RecordsEngine(handle, {
+			databaseId: this.spec.databaseId,
+			logger: this.log("Records")
+		});
 		await this.deps.afterOpen?.(this);
 		const db = this.backend.getDatabase();
 		if (db !== null) {
@@ -907,6 +920,10 @@ var InlineOwnedFile = class extends OwnedFileBase {
 		if (op === "declareCollection") this.declared = this.backend.declaredCollectionNames();
 		return result;
 	}
+	async records(op, input) {
+		if (this.recordsEngine === null) throw new Error(`database "${this.databaseId}" is not open`);
+		return require_wal_maintenance.callRecords(this.recordsEngine, op, input);
+	}
 	async vector(op, input) {
 		if (this.vectorProvider === null) throw new Error(`database "${this.databaseId}" does not serve vector calls`);
 		return require_wal_maintenance.callVector(this.vectorProvider, op, input);
@@ -962,6 +979,9 @@ var WorkerOwnedFile = class extends OwnedFileBase {
 	vector(op, input) {
 		return this.client.vector(op, input);
 	}
+	records(op, input) {
+		return this.client.records(op, input);
+	}
 	declaredCollections() {
 		return this.client.declaredCollections();
 	}
@@ -1094,6 +1114,14 @@ var PlacementRouter = class {
 	databaseOf(table) {
 		return this.placement.get(table) ?? "settings";
 	}
+	/**
+	* The file that hosts records of `databaseId`, created by the first
+	* declaration that names it (`events`). `history` never hosts records.
+	*/
+	async recordsFileFor(databaseId) {
+		if (databaseId === "history") throw new Error("placement: history.db is device-history's and never hosts records");
+		return this.openFile(databaseId);
+	}
 	/** The files currently open, settings first. */
 	openFiles() {
 		return require_dist.DATA_STORE_DATABASES.flatMap((id) => {
@@ -1204,6 +1232,368 @@ var PlacementRouter = class {
 	}
 };
 //#endregion
+//#region src/builtins/sqlite-storage/records/count-settings-array-legacy.ts
+function isRecord$1(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function unwrapValue$1(raw) {
+	if (isRecord$1(raw) && "value" in raw) return raw["value"];
+	return raw;
+}
+function legacyRowId(item) {
+	const id = item["id"];
+	if (typeof id === "string" && id.length > 0) return id;
+	const username = item["username"];
+	if (typeof username === "string" && username.length > 0) return username;
+	return null;
+}
+async function countSettingsArrayLegacy(router, addonId, settingsKey) {
+	const list = unwrapValue$1(await router.get({
+		collection: "addon-settings",
+		key: `${addonId}.${settingsKey}`
+	}));
+	if (!Array.isArray(list)) return 0;
+	let n = 0;
+	for (const item of list) {
+		if (!isRecord$1(item)) continue;
+		if (legacyRowId(item) !== null) n += 1;
+	}
+	return n;
+}
+//#endregion
+//#region src/builtins/sqlite-storage/records/count-settings-brokers-legacy.ts
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function unwrapValue(raw) {
+	if (isRecord(raw) && "value" in raw) return raw["value"];
+	return raw;
+}
+async function countSettingsBrokersLegacy(router, addonId) {
+	const list = unwrapValue(await router.get({
+		collection: "addon-settings",
+		key: `${addonId}.brokers`
+	}));
+	if (!Array.isArray(list)) return 0;
+	let n = 0;
+	for (const item of list) if (isRecord(item) && typeof item["id"] === "string") n += 1;
+	return n;
+}
+//#endregion
+//#region src/builtins/sqlite-storage/records/records-provider.ts
+/**
+* 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.
+*/
+/** The caller the transport stamped, or a refusal. */
+function recordsCallerOf(input) {
+	const raw = input !== null && typeof input === "object" ? Reflect.get(input, "callerAddonId") : void 0;
+	if (typeof raw !== "string" || raw.length === 0) throw new require_dist.NoCallerError("the call carries no caller identity; records are reached through ctx.records");
+	return require_dist.normalizeSecretOwner(raw);
+}
+function keyOf(owner, kind) {
+	return `${owner}\u0000${kind}`;
+}
+var RecordsProvider = class {
+	router;
+	logger;
+	placement = /* @__PURE__ */ new Map();
+	constructor(router, logger) {
+		this.router = router;
+		this.logger = logger;
+	}
+	/** Rebuild the placement map from every open file's catalog. Call once, after the files are open. */
+	async init() {
+		this.placement.clear();
+		for (const file of this.router.openFiles()) {
+			if (file.databaseId === "history") continue;
+			const kinds = await file.records("listKinds", {});
+			for (const k of kinds) {
+				if (k.state === "dropped") continue;
+				const key = keyOf(k.owner, k.kind);
+				const other = this.placement.get(key);
+				if (other !== void 0 && other !== file.databaseId) throw new require_dist.DeclarationRefusedError(`kind "${k.kind}" of "${k.owner}" is in both "${other}" and "${file.databaseId}"; the layout is corrupt and is not served`);
+				this.placement.set(key, file.databaseId);
+			}
+		}
+		this.logger.info("records: catalog loaded", { meta: { kinds: this.placement.size } });
+	}
+	fileOf(owner, kind) {
+		const database = this.placement.get(keyOf(owner, kind));
+		if (database === void 0) return Promise.reject(new require_dist.UnknownRecordKindError(`"${owner}" declared no kind "${kind}"`));
+		return this.router.recordsFileFor(database);
+	}
+	async declareKinds(input) {
+		const owner = recordsCallerOf(input);
+		const byDatabase = /* @__PURE__ */ new Map();
+		for (const [kind, raw] of Object.entries(input.kinds)) {
+			const declaration = require_dist.RecordKindDeclarationSchema.parse(raw);
+			const known = this.placement.get(keyOf(owner, kind));
+			if (known !== void 0 && known !== declaration.database) throw new require_dist.DeclarationRefusedError(`kind "${kind}" of "${owner}" lives in "${known}", declared for "${declaration.database}" - the engine never moves data`);
+			const group = byDatabase.get(declaration.database) ?? {};
+			byDatabase.set(declaration.database, {
+				...group,
+				[kind]: declaration
+			});
+		}
+		const merged = {};
+		for (const [database, kinds] of byDatabase) {
+			const { kinds: results } = await (await this.router.recordsFileFor(database)).records("declareKinds", {
+				owner,
+				kinds
+			});
+			for (const [kind, result] of Object.entries(results)) {
+				this.placement.set(keyOf(owner, kind), database);
+				merged[kind] = result;
+			}
+		}
+		return { kinds: await this.withAdoption(owner, input.kinds, merged) };
+	}
+	/** The boot guard: empty kind + a legacy table that still has rows = adoption pending. */
+	async withAdoption(owner, declared, results) {
+		const out = { ...results };
+		for (const [kind, raw] of Object.entries(declared)) {
+			const legacy = raw.adoptsFrom;
+			const result = results[kind];
+			if (legacy === void 0 || result === void 0) continue;
+			if ((await (await this.fileOf(owner, kind)).records("adoptionState", {
+				owner,
+				kind
+			})).adoptedAt !== null) continue;
+			const settingsBrokersAddon = require_dist.parseSettingsBrokersAdoptsFrom(legacy);
+			if (settingsBrokersAddon !== null) {
+				const legacyRows = await countSettingsBrokersLegacy(this.router, settingsBrokersAddon);
+				if (legacyRows > 0) out[kind] = {
+					...result,
+					adoptionPending: {
+						legacyTable: legacy,
+						legacyRows
+					}
+				};
+				continue;
+			}
+			const settingsArray = require_dist.parseSettingsArrayAdoptsFrom(legacy);
+			if (settingsArray !== null) {
+				const legacyRows = await countSettingsArrayLegacy(this.router, settingsArray.addonId, settingsArray.settingsKey);
+				if (legacyRows > 0) out[kind] = {
+					...result,
+					adoptionPending: {
+						legacyTable: legacy,
+						legacyRows
+					}
+				};
+				continue;
+			}
+			const legacyRows = await (await this.router.recordsFileFor("settings")).records("legacyRowCount", { table: legacy });
+			if (legacyRows !== null && legacyRows > 0) out[kind] = {
+				...result,
+				adoptionPending: {
+					legacyTable: legacy,
+					legacyRows
+				}
+			};
+		}
+		return out;
+	}
+	async get(input) {
+		const owner = recordsCallerOf(input);
+		return (await this.fileOf(owner, input.kind)).records("get", {
+			...input,
+			owner
+		});
+	}
+	async getMany(input) {
+		const owner = recordsCallerOf(input);
+		return (await this.fileOf(owner, input.kind)).records("getMany", {
+			...input,
+			owner
+		});
+	}
+	async secretRefs(input) {
+		const owner = recordsCallerOf(input);
+		return (await this.fileOf(owner, input.kind)).records("secretRefs", {
+			...input,
+			owner
+		});
+	}
+	async put(input) {
+		const owner = recordsCallerOf(input);
+		return (await this.fileOf(owner, input.kind)).records("put", {
+			...input,
+			owner
+		});
+	}
+	async putMany(input) {
+		const owner = recordsCallerOf(input);
+		return (await this.fileOf(owner, input.kind)).records("putMany", {
+			...input,
+			owner
+		});
+	}
+	async patch(input) {
+		const owner = recordsCallerOf(input);
+		return (await this.fileOf(owner, input.kind)).records("patch", {
+			...input,
+			owner
+		});
+	}
+	async delete(input) {
+		const owner = recordsCallerOf(input);
+		return (await this.fileOf(owner, input.kind)).records("delete", {
+			...input,
+			owner
+		});
+	}
+	async deleteMany(input) {
+		const owner = recordsCallerOf(input);
+		return (await this.fileOf(owner, input.kind)).records("deleteMany", {
+			...input,
+			owner
+		});
+	}
+	async query(input) {
+		const owner = recordsCallerOf(input);
+		return (await this.fileOf(owner, input.kind)).records("query", {
+			...input,
+			owner
+		});
+	}
+	async count(input) {
+		const owner = recordsCallerOf(input);
+		return (await this.fileOf(owner, input.kind)).records("count", {
+			...input,
+			owner
+		});
+	}
+	async histogram(input) {
+		const owner = recordsCallerOf(input);
+		return (await this.fileOf(owner, input.kind)).records("histogram", {
+			...input,
+			owner
+		});
+	}
+	async aggregate(input) {
+		const owner = recordsCallerOf(input);
+		return (await this.fileOf(owner, input.kind)).records("aggregate", {
+			...input,
+			owner
+		});
+	}
+	async deleteWhere(input) {
+		const owner = recordsCallerOf(input);
+		return (await this.fileOf(owner, input.kind)).records("deleteWhere", {
+			...input,
+			owner
+		});
+	}
+	async allocateId(input) {
+		const owner = recordsCallerOf(input);
+		return (await this.fileOf(owner, input.kind)).records("allocateId", {
+			...input,
+			owner
+		});
+	}
+	/** The D865 hook body: every file that holds kinds of this owner. */
+	async deleteDevice(input) {
+		const owner = recordsCallerOf(input);
+		const deleted = {};
+		const secretRefs = [];
+		const databases = new Set([...this.placement.entries()].filter(([key]) => key.startsWith(`${owner}\u0000`)).map(([, database]) => database));
+		for (const database of databases) {
+			const result = await (await this.router.recordsFileFor(database)).records("deleteDevice", {
+				...input,
+				owner
+			});
+			Object.assign(deleted, result.deleted);
+			secretRefs.push(...result.secretRefs);
+		}
+		return {
+			deleted,
+			secretRefs
+		};
+	}
+	async listKinds(input) {
+		const kinds = [];
+		for (const file of this.router.openFiles()) {
+			if (file.databaseId === "history") continue;
+			kinds.push(...await file.records("listKinds", input));
+		}
+		return { kinds };
+	}
+	async readRecords(input) {
+		this.logger.info("records: admin read", { meta: {
+			owner: input.owner,
+			kind: input.kind,
+			limit: input.limit
+		} });
+		return (await this.fileOf(input.owner, input.kind)).records("query", input);
+	}
+	/** True when a declared kind lists `collection` as `adoptsFrom` and adoption finished. */
+	async isAdoptedLegacyTable(collection) {
+		const { kinds } = await this.listKinds({ counts: false });
+		for (const k of kinds) {
+			if (k.state === "dropped") continue;
+			if (k.declaration.adoptsFrom !== collection) continue;
+			const { adoptedAt } = await (await this.fileOf(k.owner, k.kind)).records("adoptionState", {
+				owner: k.owner,
+				kind: k.kind
+			});
+			if (adoptedAt !== null) return true;
+		}
+		return false;
+	}
+	async adoptRecords(input) {
+		const file = await this.fileOf(input.owner, input.kind);
+		if (input.records.length > 0) {
+			const { adoptedAt } = await file.records("adoptionState", {
+				owner: input.owner,
+				kind: input.kind
+			});
+			if (adoptedAt !== null) {
+				if ((await file.records("count", {
+					owner: input.owner,
+					kind: input.kind
+				})).count === 0) await file.records("revokeAdopted", {
+					owner: input.owner,
+					kind: input.kind
+				});
+			}
+		}
+		const result = await file.records("putMany", input);
+		if (input.complete === true) await file.records("markAdopted", {
+			owner: input.owner,
+			kind: input.kind
+		});
+		this.logger.warn("records: ADOPTED rows as their declared owner", { meta: {
+			owner: input.owner,
+			kind: input.kind,
+			count: result.count,
+			complete: input.complete === true
+		} });
+		return { adopted: result.count };
+	}
+	/** Housekeeping: delete rows past `expires_at` in every file that hosts kinds. */
+	async sweepExpired() {
+		let deleted = 0;
+		for (const file of this.router.openFiles()) {
+			if (file.databaseId === "history") continue;
+			deleted += (await file.records("sweepExpired", {})).deleted;
+		}
+		return deleted;
+	}
+};
+//#endregion
 //#region src/builtins/sqlite-storage/storage-admin-provider.ts
 /**
 * The `storage-admin` provider of the SQLite engine (D870): the operator's
@@ -1217,10 +1607,27 @@ var StorageAdminProvider = class {
 	backend;
 	logger;
 	installedOwners;
-	constructor(backend, logger, installedOwners) {
+	records;
+	constructor(backend, logger, installedOwners, records) {
 		this.backend = backend;
 		this.logger = logger;
 		this.installedOwners = installedOwners;
+		this.records = records;
+	}
+	listKinds(input) {
+		return this.records.listKinds(input);
+	}
+	readRecords(input) {
+		return this.records.readRecords(input);
+	}
+	adoptRecords(input) {
+		return this.records.adoptRecords(input);
+	}
+	isAdoptedLegacyTable(input) {
+		return this.records.isAdoptedLegacyTable(input.collection).then((adopted) => ({ adopted }));
+	}
+	readLegacyCollection(input) {
+		return Promise.resolve(this.backend.readLegacyCollection(input));
 	}
 	/** May this table be dropped AT ALL? Throws with the reason when not. */
 	async assertDroppable(collection) {
@@ -1233,7 +1640,7 @@ var StorageAdminProvider = class {
 			throw new Error(`drop refused: the installed addons could not be read (${err instanceof Error ? err.message : String(err)})`);
 		});
 		const owner = collection.slice(0, colon);
-		if (installed.has(owner)) throw new Error(`drop refused: "${collection}" belongs to the installed addon "${owner}"`);
+		if (installed.has(owner) && !await this.records.isAdoptedLegacyTable(collection)) throw new Error(`drop refused: "${collection}" belongs to the installed addon "${owner}"`);
 	}
 	async listTables(input) {
 		const tables = this.backend.listTables(input.ownerPrefix);
@@ -1246,6 +1653,7 @@ var StorageAdminProvider = class {
 	async dropCollection(input) {
 		try {
 			await this.assertDroppable(input.collection);
+			if (await this.records.isAdoptedLegacyTable(input.collection)) this.backend.forgetDeclaredThisBoot(input.collection);
 			const rows = this.backend.dropTable(input.collection, input.expectRows);
 			this.logger.warn("storage-admin: DROPPED a table", { meta: {
 				collection: input.collection,
@@ -1413,6 +1821,8 @@ var DATABASE_FILE_NAMES = {
 var SqliteSettingsAddon = class extends require_dist.BaseAddon {
 	settingsFile = null;
 	router = null;
+	sweepTimer = null;
+	sweepStart = null;
 	constructor() {
 		super({});
 	}
@@ -1469,12 +1879,19 @@ var SqliteSettingsAddon = class extends require_dist.BaseAddon {
 		this.router = router;
 		const vectorIndex = settings.getVectorIndex();
 		if (vectorIndex === null) throw new Error("vector-store: the settings file has no vector index");
+		const records = new RecordsProvider(router, this.ctx.logger.child("Records"));
+		await records.init();
+		this.startRecordsSweep(records);
 		this.ctx.logger.info("Initialized successfully");
 		return [
 			{
 				capability: require_dist.dataStoreProviderCapability,
 				provider: router
 			},
+			{
+				capability: require_dist.recordsCapability,
+				provider: records
+			},
 			{
 				capability: require_dist.vectorStoreCapability,
 				provider: require_wal_maintenance.vectorProviderOf(vectorIndex)
@@ -1485,7 +1902,7 @@ var SqliteSettingsAddon = class extends require_dist.BaseAddon {
 			},
 			{
 				capability: require_dist.storageAdminCapability,
-				provider: new StorageAdminProvider(settings.backend, this.ctx.logger.child("StorageAdmin"), async () => new Set((await this.ctx.api.addons.list.query()).map((addon) => addon.manifest.id)))
+				provider: new StorageAdminProvider(settings.backend, this.ctx.logger.child("StorageAdmin"), async () => new Set((await this.ctx.api.addons.list.query()).map((addon) => addon.manifest.id)), records)
 			}
 		];
 	}
@@ -1502,7 +1919,31 @@ var SqliteSettingsAddon = class extends require_dist.BaseAddon {
 		}
 		await purgeRetiredCollections(retiredCollectionStoreOfFile(file), this.ctx.logger.child("RetiredCollections").withTags({ database: file.databaseId }));
 	}
+	/**
+	* 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.
+	*/
+	startRecordsSweep(records) {
+		const run = () => {
+			records.sweepExpired().then((deleted) => {
+				if (deleted > 0) this.ctx.logger.info("records: expired rows swept", { meta: { deleted } });
+			}).catch((err) => {
+				this.ctx.logger.warn("records: expiry sweep failed", { meta: { error: require_dist.errMsg(err) } });
+			});
+		};
+		this.sweepStart = setTimeout(() => {
+			run();
+			this.sweepTimer = setInterval(run, require_dist.RECORD_SWEEP_INTERVAL_MS);
+			this.sweepTimer.unref();
+		}, 6e4);
+		this.sweepStart.unref();
+	}
 	async onShutdown() {
+		if (this.sweepStart !== null) clearTimeout(this.sweepStart);
+		if (this.sweepTimer !== null) clearInterval(this.sweepTimer);
+		this.sweepStart = null;
+		this.sweepTimer = null;
 		const files = this.router?.openFiles() ?? [];
 		for (const file of files.toReversed()) try {
 			await file.stop();