@camstack/system 1.2.443 → 1.2.445

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

@@ -1,6 +1,6 @@
-import { Ar as errMsg, At as databaseSnapshotCapability, Ir as RUNTIME_DEFAULTS, J as STORAGE_ADMIN_SCOPED_BASES, S as DATA_STORE_DATABASES, b as DATABASE_SNAPSHOT_SUFFIX, er as storageAdminCapability, jr as BaseAddon, kt as dataStoreProviderCapability, pr as vectorStoreCapability, q as STORAGE_ADMIN_MOVED_COLLECTIONS, ut as bareAddonId, x as DATABASE_SNAPSHOT_TIMEOUT_MS, y as DATABASE_SNAPSHOT_PARTIAL_SUFFIX } from "../../dist-Bxt_S-9a.mjs";
+import { $r as RECORD_SWEEP_INTERVAL_MS, Ft as databaseSnapshotCapability, Ji as parseSettingsArrayAdoptsFrom, Jr as NoCallerError, Lr as errMsg, Pt as dataStoreProviderCapability, Q as STORAGE_ADMIN_SCOPED_BASES, Rr as BaseAddon, S as DATA_STORE_DATABASES, Vn as recordsCapability, Wi as normalizeSecretOwner, Wr as DeclarationRefusedError, Yi as parseSettingsBrokersAdoptsFrom, Z as STORAGE_ADMIN_MOVED_COLLECTIONS, ai as RecordKindDeclarationSchema, b as DATABASE_SNAPSHOT_SUFFIX, br as vectorStoreCapability, fi as UnknownRecordKindError, ht as bareAddonId, ni as RUNTIME_DEFAULTS, sr as storageAdminCapability, x as DATABASE_SNAPSHOT_TIMEOUT_MS, y as DATABASE_SNAPSHOT_PARTIAL_SUFFIX } from "../../dist-BNunRyXT.mjs";
 import { i as retiredKeyStoreOf, n as purgeRetiredSettingsKeys } from "../../retired-settings-keys-Bhwe4ymb.mjs";
-import { C as callData, S as callControl, T as controlTargetOf, _ as isFileHostMessage, a as WalMaintenance, c as SqliteSettingsBackend, d as DatabaseBusyError, f as DuplicatePlacementError, g as collectTransferables, l as CollectionPlacementError, o as createVectorIndex, p as rehydrateError, s as vectorProviderOf, u as CrossDatabaseTransactError, w as callVector, x as trustResult } from "../../wal-maintenance-sIB32ONp.mjs";
+import { C as callControl, D as controlTargetOf, E as callVector, S as RecordsEngine, T as callRecords, _ as isFileHostMessage, a as WalMaintenance, c as SqliteSettingsBackend, d as DatabaseBusyError, f as DuplicatePlacementError, g as collectTransferables, l as CollectionPlacementError, o as createVectorIndex, p as rehydrateError, s as vectorProviderOf, u as CrossDatabaseTransactError, w as callData, x as trustResult } from "../../wal-maintenance-CfvgtQ7C.mjs";
 import { r as isSnapshotWorkerMessage } from "../../sqlite-snapshot-protocol-2QaTouWV.mjs";
 import { a as isWorkerMessage, t as WAL_CHECKPOINT_LARGE_PASS_FRAMES } from "../../wal-checkpoint-policy-BahrTtyD.mjs";
 import { createRequire } from "node:module";
@@ -101,6 +101,13 @@ var FileHostClient = class {
 			input
 		});
 	}
+	records(op, input) {
+		return this.request({
+			kind: "records",
+			op,
+			input
+		});
+	}
 	control(op, input) {
 		return this.request({
 			kind: "control",
@@ -863,6 +870,7 @@ var InlineOwnedFile = class extends OwnedFileBase {
 	vectorIndex = null;
 	vectorProvider = null;
 	maintenance = null;
+	recordsEngine = null;
 	constructor(spec, deps) {
 		super(spec, deps);
 		this.backend = new SqliteSettingsBackend(spec.livePath, deps.runtimeDefaults === void 0 ? {} : { ...deps.runtimeDefaults }, this.log("Query"), {
@@ -880,6 +888,11 @@ var InlineOwnedFile = class extends OwnedFileBase {
 			this.vectorIndex = vectorIndex;
 			this.vectorProvider = vectorProviderOf(vectorIndex);
 		}
+		const handle = this.backend.getDatabase();
+		if (handle !== null) this.recordsEngine = new RecordsEngine(handle, {
+			databaseId: this.spec.databaseId,
+			logger: this.log("Records")
+		});
 		await this.deps.afterOpen?.(this);
 		const db = this.backend.getDatabase();
 		if (db !== null) {
@@ -901,6 +914,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 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 callVector(this.vectorProvider, op, input);
@@ -956,6 +973,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();
 	}
@@ -1088,6 +1108,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 DATA_STORE_DATABASES.flatMap((id) => {
@@ -1198,6 +1226,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 NoCallerError("the call carries no caller identity; records are reached through ctx.records");
+	return 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 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 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 = RecordKindDeclarationSchema.parse(raw);
+			const known = this.placement.get(keyOf(owner, kind));
+			if (known !== void 0 && known !== declaration.database) throw new 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 = 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 = 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
@@ -1211,10 +1601,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) {
@@ -1227,7 +1634,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);
@@ -1240,6 +1647,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,
@@ -1407,6 +1815,8 @@ var DATABASE_FILE_NAMES = {
 var SqliteSettingsAddon = class extends BaseAddon {
 	settingsFile = null;
 	router = null;
+	sweepTimer = null;
+	sweepStart = null;
 	constructor() {
 		super({});
 	}
@@ -1463,12 +1873,19 @@ var SqliteSettingsAddon = class extends 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: dataStoreProviderCapability,
 				provider: router
 			},
+			{
+				capability: recordsCapability,
+				provider: records
+			},
 			{
 				capability: vectorStoreCapability,
 				provider: vectorProviderOf(vectorIndex)
@@ -1479,7 +1896,7 @@ var SqliteSettingsAddon = class extends BaseAddon {
 			},
 			{
 				capability: 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)
 			}
 		];
 	}
@@ -1496,7 +1913,31 @@ var SqliteSettingsAddon = class extends 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: errMsg(err) } });
+			});
+		};
+		this.sweepStart = setTimeout(() => {
+			run();
+			this.sweepTimer = setInterval(run, 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();

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

@@ -7,13 +7,27 @@
 * capability's method, once the last hub ran `migrate-device-store.ts --drop`.
 */
 import { type IScopedLogger, type IStorageAdminProvider, type StorageTable } from "@camstack/types";
+import type { RecordsProvider } from "./records/records-provider.js";
 import type { SqliteSettingsBackend } from "./sqlite-settings-backend.js";
 export declare class StorageAdminProvider implements IStorageAdminProvider {
 	private readonly backend;
 	private readonly logger;
 	/** The addon ids installed on this hub; a throw means "cannot tell" and refuses the drop. */
 	private readonly installedOwners;
-	constructor(backend: SqliteSettingsBackend, logger: IScopedLogger, installedOwners: () => Promise<ReadonlySet<string>>);
+	/** The records provider the System -> Data and migration methods delegate to (D881). */
+	private readonly records;
+	constructor(backend: SqliteSettingsBackend, logger: IScopedLogger, installedOwners: () => Promise<ReadonlySet<string>>, records: Pick<RecordsProvider, "listKinds" | "readRecords" | "adoptRecords" | "isAdoptedLegacyTable">);
+	listKinds(input: Parameters<IStorageAdminProvider["listKinds"]>[0]): ReturnType<IStorageAdminProvider["listKinds"]>;
+	readRecords(input: Parameters<IStorageAdminProvider["readRecords"]>[0]): ReturnType<IStorageAdminProvider["readRecords"]>;
+	adoptRecords(input: Parameters<IStorageAdminProvider["adoptRecords"]>[0]): ReturnType<IStorageAdminProvider["adoptRecords"]>;
+	isAdoptedLegacyTable(input: {
+		collection: string;
+	}): ReturnType<IStorageAdminProvider["isAdoptedLegacyTable"]>;
+	readLegacyCollection(input: {
+		collection: string;
+		cursor?: string | undefined;
+		limit?: number | undefined;
+	}): ReturnType<IStorageAdminProvider["readLegacyCollection"]>;
 	/** May this table be dropped AT ALL? Throws with the reason when not. */
 	private assertDroppable;
 	listTables(input: {

package/dist/builtins/storage-orchestrator/drain-state-store.d.ts

@@ -8,14 +8,17 @@
 * on every sweep, through the same `settings-store` door the location table
 * uses.
 */
-import type { ISettingsStoreProvider } from "@camstack/types";
+import type { ISettingsStoreProvider, RecordKindHandle, RecordsAccess } from "@camstack/types";
 import type { DrainState } from "./drain-ratchet.js";
+import { type StorageDrainStateBody } from "./record-kinds.js";
 import type { DrainStateStore } from "./storage-pressure-manager.js";
 /** {@link DrainStateStore} on the `settings-store` collection surface. */
 export declare class SqliteDrainStateStore implements DrainStateStore {
 	private readonly store;
 	private declared;
-	constructor(store: ISettingsStoreProvider);
+	private readonly drainKind;
+	constructor(store: ISettingsStoreProvider, drainKind?: RecordKindHandle<StorageDrainStateBody> | null);
+	static recordStoresOf(records: Pick<RecordsAccess, "kind">): RecordKindHandle<StorageDrainStateBody>;
 	private ensureDeclared;
 	load(): Promise<readonly DrainState[]>;
 	save(state: DrainState): Promise<void>;

package/dist/builtins/storage-orchestrator/location-store.d.ts

@@ -7,7 +7,8 @@
 * tests pass a fake (in-memory `Map`-backed) implementation. Same
 * pattern as `IntegrationRegistry` in `sqlite-storage/`.
 */
-import type { ISettingsStoreProvider, LegacyStorageLocationDefault, StorageLocation } from "@camstack/types";
+import type { ISettingsStoreProvider, LegacyStorageLocationDefault, RecordKindHandle, RecordsAccess, StorageLocation } from "@camstack/types";
+import { type StorageLocationBody } from "./record-kinds.js";
 /**
 * A location as it comes back OFF DISK: the live record plus the retired
 * `isDefault` column, which exists only so the orchestrator's boot migration
@@ -47,7 +48,9 @@ export declare const STORAGE_LOCATIONS = "storage_locations";
 export declare class SqliteLocationStore implements ILocationStore {
 	private readonly store;
 	private declared;
-	constructor(store: ISettingsStoreProvider);
+	private readonly locationsKind;
+	constructor(store: ISettingsStoreProvider, locationsKind?: RecordKindHandle<StorageLocationBody> | null);
+	static recordStoresOf(records: Pick<RecordsAccess, "kind">): RecordKindHandle<StorageLocationBody>;
 	/**
 	* Lazy `declareCollection` — keeps the constructor cheap and async-free.
 	* Called from every mutation/read path; `declareCollection` is idempotent
@@ -64,3 +67,5 @@ export declare class SqliteLocationStore implements ILocationStore {
 	upsert(loc: StorageLocation): Promise<void>;
 	delete(id: string): Promise<void>;
 }
+export declare function locationToBody(loc: StorageLocation): StorageLocationBody;
+export declare function bodyToPersistedLocation(id: string, body: StorageLocationBody): PersistedStorageLocation | null;

package/dist/builtins/storage-orchestrator/record-kinds.d.ts

@@ -0,0 +1,38 @@
+/**
+* Record kinds owned by storage-orchestrator (phase 4 — hub-main).
+*/
+import { StorageLocationModeSchema, StorageLocationTypeSchema, type DefinedRecordKind } from "@camstack/types";
+import { z } from "zod";
+export declare const STORAGE_DRAIN_STATE_LEGACY = "storage_drain_state";
+export type StorageLocationBody = {
+	readonly type: z.infer<typeof StorageLocationTypeSchema>;
+	readonly displayName: string;
+	readonly providerId: string;
+	readonly config: Record<string, unknown>;
+	readonly isSystem: boolean;
+	readonly createdAt: number;
+	readonly updatedAt: number;
+	readonly nodeId?: string;
+	readonly enabled?: boolean;
+	readonly mode?: z.infer<typeof StorageLocationModeSchema>;
+	readonly isDefault?: boolean;
+};
+export declare const StorageLocationBodySchema: z.ZodType<StorageLocationBody>;
+export type StorageDrainStateBody = {
+	readonly locationId: string;
+	readonly startedAtMs: number;
+	readonly startBytes: number;
+	readonly capBytes: number;
+	readonly lastPeerBytes: number | null;
+	readonly lastSweepMs: number;
+	readonly observedGrowthBytes: number;
+	readonly observedElapsedMs: number;
+};
+export declare const StorageDrainStateBodySchema: z.ZodType<StorageDrainStateBody>;
+export type StorageOrchestratorRecordKindsMap = {
+	readonly locations: DefinedRecordKind<z.ZodType<StorageLocationBody>>;
+	readonly "drain-state": DefinedRecordKind<z.ZodType<StorageDrainStateBody>>;
+};
+export declare const storageOrchestratorRecordKinds: StorageOrchestratorRecordKindsMap;
+export declare const storageLocationsRecordKind: DefinedRecordKind<z.ZodType<StorageLocationBody>>;
+export declare const storageDrainStateRecordKind: DefinedRecordKind<z.ZodType<StorageDrainStateBody>>;

package/dist/builtins/storage-orchestrator/storage-orchestrator.addon.d.ts

@@ -2,6 +2,8 @@ import type { ProviderRegistration } from "@camstack/types";
 import { BaseAddon } from "@camstack/types";
 interface StorageOrchestratorConfig extends Record<string, unknown> {}
 export declare class StorageOrchestratorAddon extends BaseAddon<StorageOrchestratorConfig> {
+	private locationsKind;
+	private drainStateKind;
 	private service;
 	private pressureManager;
 	private readonly locationBandMonitor;