@camstack/system 1.2.106 → 1.2.108

package/dist/builtins/device-manager/device-meta-actions.d.ts

@@ -1,5 +1,5 @@
 import { AddonContext, deviceManagerCapability, InferProvider } from '@camstack/types';
-import { DeviceManagerSettings, DeviceMetaStore } from './device-meta-store.js';
+import { DeviceMetaStore } from './device-meta-store.js';
 import { ProviderContext } from './device-provider-context.js';
 type IDeviceManagerProvider = InferProvider<typeof deviceManagerCapability>;
 /**
@@ -11,7 +11,7 @@ type IDeviceManagerProvider = InferProvider<typeof deviceManagerCapability>;
  * because `ProviderContext.stampIntegrationId` delegates HERE — passing the
  * context would be a capture cycle.
  */
-export declare function stampIntegrationId(metaStore: DeviceMetaStore, settings: DeviceManagerSettings, ctx: AddonContext, deviceId: number, integrationId: string): Promise<void>;
+export declare function stampIntegrationId(metaStore: DeviceMetaStore, ctx: AddonContext, deviceId: number, integrationId: string): Promise<void>;
 export declare function allocateDeviceId(pctx: ProviderContext, input: Parameters<IDeviceManagerProvider['allocateDeviceId']>[0]): ReturnType<IDeviceManagerProvider['allocateDeviceId']>;
 export declare function registerDevice(pctx: ProviderContext, input: Parameters<IDeviceManagerProvider['registerDevice']>[0]): ReturnType<IDeviceManagerProvider['registerDevice']>;
 export declare function removeDevice(pctx: ProviderContext, input: Parameters<IDeviceManagerProvider['removeDevice']>[0]): ReturnType<IDeviceManagerProvider['removeDevice']>;
@@ -106,14 +106,14 @@ export declare function getRoleDisplayDefaults(pctx: ProviderContext, _input: Pa
  * Replace the per-role display defaults whole-record (full replace). Override
  * units are normalized (`normalizeUnit`) at write so the render path always
  * looks up canonical spellings. Single-writer top-level key — no lock, no RMW,
- * no interaction with the `deviceMeta` write lock. Not per-device, so no event
+ * no interaction with the device write lock. Not per-device, so no event
  * is emitted; the UI invalidates its own query on mutate.
  */
 export declare function setRoleDisplayDefaults(pctx: ProviderContext, input: Parameters<IDeviceManagerProvider['setRoleDisplayDefaults']>[0]): ReturnType<IDeviceManagerProvider['setRoleDisplayDefaults']>;
 /**
  * Batched meta pre-seed. Applies every provided field to the
  * device's meta row in ONE read-modify-write under a single
- * `withMetaWriteLock` acquisition (one `deviceMeta` blob write),
+ * `withMetaWriteLock` acquisition (one row write),
  * then emits one `DeviceMetaChanged` event per field that was
  * supplied — preserving the exact semantics of the individual
  * setters (`setName` / `setLocation` / `setType` /

package/dist/builtins/device-manager/device-meta-store.d.ts

@@ -1,38 +1,51 @@
 import { AddonContext, IDeviceRegistry } from '@camstack/types';
 import { AddonStore, PersistedDeviceMeta } from './device-meta-types.js';
+import { DeviceRow, DeviceRowStore } from './device-row-store.js';
 /** The settings surface the meta store uses (`ctx.settings`, narrowed non-null). */
 export type DeviceManagerSettings = NonNullable<AddonContext['settings']>;
 export declare class DeviceMetaStore {
     private readonly settings;
     /** Hub-process device registry (null when this node owns no registry). */
     readonly registry: IDeviceRegistry | null;
+    /** Row access for `device-manager:devices`. */
+    readonly rows: DeviceRowStore;
     /** Synchronous ownership cache, keyed by NUMERIC deviceId → owning addonId.
-     *  The persisted meta store is authoritative but reads are async; hub-side
+     *  The persisted row store is authoritative but reads are async; hub-side
      *  callers (e.g. `CapabilityRegistry.getNativeProvider` fallback) need
      *  ownership without awaiting. Kept in sync with every register/remove and
      *  warmed from persistence on boot. */
     readonly idToAddonId: Map<number, string>;
-    /** Serialises every read-modify-write of the deviceMeta / deviceIndex blob
-     *  through one promise chain (see `withMetaWriteLock`). Per-instance state —
-     *  identical to the former `onInitialize` closure variable. */
+    /** Serialises every read-modify-write of a device row through one promise
+     *  chain (see `withMetaWriteLock`). Per-instance state. */
     private metaWriteChain;
     constructor(settings: DeviceManagerSettings, 
     /** Hub-process device registry (null when this node owns no registry). */
-    registry: IDeviceRegistry | null);
+    registry: IDeviceRegistry | null, 
+    /** Row access for `device-manager:devices`. */
+    rows: DeviceRowStore);
+    /** The read currently in flight, or null. Never a settled value — see
+     *  {@link readStore}. */
+    private inFlightRead;
+    /**
+     * The addon's own settings row set — `nextDeviceId`, `roleDisplayDefaults`,
+     * `locations`. NOT the fleet: no device has lived here since the flatten.
+     *
+     * **Concurrent callers join the read already in flight.** This is not a
+     * cache and nothing survives settlement: a caller that awaited the running
+     * promise could not have observed anything older than its result, so the
+     * only thing that changes is cost.
+     *
+     * A rejection is NOT latched: the slot is cleared before the promise
+     * settles either way, so a failed read costs the joiners that one failure
+     * and the next caller reaches the store again.
+     */
     readStore: () => Promise<AddonStore>;
-    readIndex: () => Promise<Record<string, string[]>>;
-    readMeta: () => Promise<Record<string, PersistedDeviceMeta>>;
-    /** Hardware-identity metadata map. Lives in a sibling key on the
-     *  device-manager addon store so its writers (`setMetadata`) never
-     *  collide with the lifecycle writers on `deviceMeta`
-     *  (`registerDevice` / `setName` / `setLocation` / `setDisabled`).
-     *  Single-writer per row eliminates the "writer X clobbers writer
-     *  Y's field" bug class — `setMetadata` is the only producer. */
-    readMetadataMap: () => Promise<Record<string, Record<string, unknown>>>;
     withMetaWriteLock: <T>(fn: () => Promise<T>) => Promise<T>;
+    /** The whole persisted row for one device, or `null`. */
+    getRow: (deviceId: number) => Promise<DeviceRow | null>;
     /**
      * Resolve a numeric deviceId to the owning `(addonId, stableId)` pair.
-     * Scans persisted meta — live IDevice lookup (hub registry) is handled
+     * Reads the device's own row — live IDevice lookup (hub registry) is handled
      * separately per call site so callers can decide whether to route to
      * an in-process driver or to the cross-process `device-ops` bridge.
      * Returns null when no device with that id is known to the hub.
@@ -42,8 +55,10 @@ export declare class DeviceMetaStore {
         stableId: string;
         meta: PersistedDeviceMeta;
     } | null>;
+    /** The device's hardware-identity metadata blob, or `null`. */
+    readMetadata: (deviceId: number) => Promise<Record<string, unknown> | null>;
     /** Direct children of a device: the union of the live registry's children
-     *  and the persisted-meta scan (`parentDeviceId === parentId`), deduplicated
+     *  and the persisted rows whose `parentDeviceId` is `parentId`, deduplicated
      *  and excluding self. Shared by the `remove` cascade and the `resetToSource`
      *  resync purge (#19). */
     directChildIds: (parentId: number) => Promise<readonly number[]>;

package/dist/builtins/device-manager/device-meta-types.d.ts

@@ -134,23 +134,17 @@ export interface PersistedDeviceMeta {
      *  only — storage stays in source units. */
     display?: DeviceDisplayOverride;
 }
+/**
+ * The device-manager's own `addon-settings` row set — everything that is NOT a
+ * device.
+ *
+ * The three fleet blobs that used to live here (`deviceMeta`, `deviceMetadata`,
+ * `deviceIndex`) are gone: devices are rows in `device-manager:devices`
+ * (`device-row-store.ts`). What is left is four small keys, together under a
+ * kilobyte on the reference hub — which matters because `writeAddonStore` for a
+ * hub builtin is `setAllAddon`, a DELETE + re-INSERT of every key the addon owns.
+ */
 export interface AddonStore {
-    deviceIndex?: Record<string, string[]>;
-    /** Device meta records keyed by the numeric device `id` (`String(id)`).
-     *  `addonId` and `stableId` are FIELDS on each `PersistedDeviceMeta` record
-     *  — the map key is the numeric id, not the former composite
-     *  `${addonId}:${stableId}` string. */
-    deviceMeta?: Record<string, PersistedDeviceMeta>;
-    /** Hardware-identity metadata blob keyed by the numeric device `id`
-     *  (`String(id)`), the same primary key as `deviceMeta`.
-     *  Stored in a separate key from `deviceMeta` so the lifecycle
-     *  writers (registerDevice / setName / setLocation / setDisabled)
-     *  never need to read or preserve the metadata field — single-writer
-     *  per row eliminates the "writer X clobbers writer Y's field" bug
-     *  class. The `metadata` field on `PersistedDeviceMeta` is a legacy
-     *  fallback consulted only at read time during the lazy migration —
-     *  new writes always go to `deviceMetadata`. */
-    deviceMetadata?: Record<string, Record<string, unknown>>;
     /** Monotonic counter that feeds `PersistedDeviceMeta.id` for every
      *  new device. Incremented exactly once per registerDevice; never
      *  decremented. */
@@ -171,6 +165,14 @@ export interface AddonStore {
      *  by `DeviceRole` string. Resolution merges these UNDER any per-device
      *  `display` override. Written whole-record by `setRoleDisplayDefaults`
      *  (full replace — no read-modify-write, single writer, so it never
-     *  interacts with the `deviceMeta` write lock). */
+     *  interacts with the device write lock). */
     roleDisplayDefaults?: Record<string, RoleDisplayDefault>;
 }
+/**
+ * Decode the raw `ctx.settings.readAddonStore()` record into {@link AddonStore}.
+ *
+ * A field of the wrong shape reads as ABSENT rather than being trusted through
+ * a cast: the store is JSON on disk and a hand-edit or a partial restore must
+ * cost the caller its default, never a downstream `TypeError`.
+ */
+export declare function decodeAddonStore(raw: Record<string, unknown>): AddonStore;

package/dist/builtins/device-manager/device-row-store.d.ts

@@ -0,0 +1,229 @@
+import { ChildLayout, CollectionColumn, CollectionIndex, DeviceDisplayOverride, IScopedLogger, MutationFilter, QueryFilter, SettingsRecord, SettingsStoreClient } from '@camstack/types';
+import { RetiredRowStore } from '../sqlite-storage/retired-settings-keys.js';
+import { PersistedDeviceMeta } from './device-meta-types.js';
+/**
+ * @durable class=registry owner=device-manager
+ *   write="one row per device, written by `allocateDeviceId` (identity placeholder),
+ *     `registerDevice` (full reconcile) and every meta setter (single-column patch);
+ *     `setMetadata` patches the `metadata` column of the same row"
+ *   retention="none — a row goes only when the operator removes the device
+ *     (`removeDevice`), or when an integration is deleted and cascades. Bounded by the
+ *     fleet an operator configures (974 rows on the reference hub)."
+ */
+export declare const DEVICE_ROWS_COLLECTION = "device-manager:devices";
+/**
+ * Fleet reads pass this explicitly.
+ *
+ * `settings-store.query` applies a DEFAULT row cap of 2 000 when the caller
+ * names no `limit` (`query-bounds.ts`), and truncation there is silent to the
+ * caller — it warns in the engine's log and returns a short list that looks
+ * complete. The reference hub is already at 974 devices; half the default cap
+ * is not a margin worth betting the fleet listing on. 20 000 is the engine's
+ * hard ceiling, so this asks for everything the engine will ever serve in one
+ * call and any future need to page is a loud failure rather than a quiet one.
+ */
+export declare const DEVICE_ROWS_FLEET_LIMIT = 20000;
+export declare const DEVICE_ROWS_COLUMNS: readonly CollectionColumn[];
+export declare const DEVICE_ROWS_INDEXES: readonly CollectionIndex[];
+/**
+ * The settings-store door this store needs, as a plain object surface.
+ *
+ * The production door is the tRPC client on `ctx.api.settingsStore`
+ * (`client.get.query(…)` / `client.set.mutate(…)`); {@link deviceRowBackendOf}
+ * adapts it. Declaring the port separately is what lets a test hand over an
+ * in-memory table without reconstructing a tRPC router, and it names exactly
+ * the seven methods this store is allowed to reach for.
+ */
+export interface DeviceRowBackend {
+    declareCollection(input: {
+        collection: string;
+        columns: readonly CollectionColumn[];
+        indexes?: readonly CollectionIndex[];
+    }): Promise<void>;
+    get(input: {
+        collection: string;
+        key: string;
+    }): Promise<unknown>;
+    set(input: {
+        collection: string;
+        key: string;
+        value: Record<string, unknown>;
+    }): Promise<void>;
+    query(input: {
+        collection: string;
+        filter?: QueryFilter;
+    }): Promise<readonly SettingsRecord<Record<string, unknown>>[]>;
+    updateWhere(input: {
+        collection: string;
+        filter: MutationFilter;
+        data: Record<string, unknown>;
+    }): Promise<{
+        updated: number;
+    }>;
+    delete(input: {
+        collection: string;
+        key: string;
+    }): Promise<void>;
+    count(input: {
+        collection: string;
+        filter?: QueryFilter;
+    }): Promise<number>;
+}
+/** Adapt `ctx.api.settingsStore` (tRPC namespace) to {@link DeviceRowBackend}. */
+export declare function deviceRowBackendOf(client: SettingsStoreClient): DeviceRowBackend;
+/**
+ * The fields a single-column patch may set.
+ *
+ * Every key is OPTIONAL and only the keys PRESENT reach the `SET` list, so an
+ * omitted key leaves that column exactly as it was. `null` is a real value and
+ * CLEARS the column; it is how `setDisplay(null)` removes an override.
+ *
+ * A patch is an UPDATE, never an insert — see {@link DeviceRowStore.patch}.
+ */
+export interface DeviceRowPatch {
+    readonly type?: string;
+    readonly name?: string;
+    readonly userNamed?: boolean;
+    readonly location?: string | null;
+    readonly disabled?: boolean;
+    readonly parentDeviceId?: number | null;
+    readonly registered?: boolean;
+    readonly features?: readonly string[];
+    readonly exportFingerprint?: string;
+    readonly integrationId?: string | null;
+    readonly linkDeviceId?: number | null;
+    readonly primaryChildEntityId?: string | null;
+    readonly childLayout?: ChildLayout | null;
+    readonly role?: string | null;
+    readonly display?: DeviceDisplayOverride | null;
+    readonly metadata?: Record<string, unknown> | null;
+}
+/**
+ * Every column `registerDevice` writes.
+ *
+ * It is spelled out rather than reusing {@link DeviceRowPatch} because this
+ * statement doubles as the INSERT for a device whose row does not exist yet
+ * (`allocateDeviceId` is not on every path into `registerDevice`), and SQLite
+ * checks `NOT NULL` on the insert attempt BEFORE the upsert clause gets to
+ * intercept the primary-key conflict. Every `NOT NULL` column is therefore
+ * required here, and the type is what keeps it that way.
+ *
+ * Columns NOT listed — `integrationId`, `linkDeviceId`, `primaryChildEntityId`,
+ * `childLayout`, `role`, `display`, `metadata` — are not in the statement at
+ * all, so re-registering preserves them. The blob shape had to re-state each
+ * one to avoid clobbering it, and every field added since has been one more
+ * spread somebody had to remember.
+ */
+export interface DeviceRegistrationRow {
+    readonly deviceId: number;
+    readonly addonId: string;
+    readonly stableId: string;
+    readonly type: string;
+    readonly name: string;
+    readonly userNamed: boolean;
+    readonly location: string | null;
+    readonly disabled: boolean;
+    readonly parentDeviceId: number | null;
+    readonly registered: boolean;
+    readonly features: readonly string[];
+    readonly exportFingerprint: string;
+}
+/** A device row as this store hands it back: the meta record plus its metadata blob. */
+export interface DeviceRow {
+    readonly meta: PersistedDeviceMeta;
+    /** `null` when the device has no hardware-identity metadata. */
+    readonly metadata: Record<string, unknown> | null;
+    /** Has `registerDevice` ever run for this device? (former `deviceIndex` membership) */
+    readonly registered: boolean;
+}
+/**
+ * Decode one stored row.
+ *
+ * Returns `null` for a row missing an identity field the rest of the system
+ * treats as an invariant (`deviceId` / `addonId` / `stableId` / `type` /
+ * `name`). A row like that cannot be projected into a `DeviceInfo` and taking
+ * the whole fleet read down for it would be worse — the caller logs the skip.
+ */
+export declare function decodeDeviceRow(data: Record<string, unknown>): DeviceRow | null;
+/** Full-row value for an upsert: identity + every field of the meta record. */
+export declare function encodeDeviceRow(meta: PersistedDeviceMeta, extra?: {
+    readonly registered?: boolean;
+    readonly metadata?: Record<string, unknown> | null;
+}): Record<string, unknown>;
+/** Column map for a partial write — only the keys the caller actually named. */
+export declare function encodeDeviceRowPatch(patch: DeviceRowPatch): Record<string, unknown>;
+/**
+ * Row access for the device fleet. Every method is a single statement against
+ * `device-manager:devices` — there is no in-memory copy of the fleet here and
+ * no cache: a per-device question is a primary-key lookup, a fleet question is
+ * one indexed scan.
+ */
+export declare class DeviceRowStore {
+    private readonly backend;
+    private readonly logger;
+    private declared;
+    constructor(backend: DeviceRowBackend, logger: IScopedLogger);
+    /**
+     * Lazy, idempotent `declareCollection`, memoised on the PROMISE so N
+     * concurrent first-callers issue one declaration rather than N. A rejection
+     * is not latched — the slot is cleared so the next caller retries instead of
+     * inheriting a dead collection forever.
+     */
+    declare(): Promise<void>;
+    /** One device, by numeric id. `null` when the fleet does not know it. */
+    get(deviceId: number): Promise<DeviceRow | null>;
+    /** Every device, ordered by numeric id. */
+    listAll(): Promise<readonly DeviceRow[]>;
+    /**
+     * The device an addon knows as `stableId`, or `null`.
+     *
+     * `(addonId, stableId)` is the addon-facing identity — unique by
+     * construction, since `allocateDeviceId` is the only thing that mints a row
+     * and it returns the existing id for a pair it already knows. A second row
+     * for the pair would be a corruption, so this takes the LOWEST id and says
+     * so rather than picking arbitrarily.
+     */
+    findByStableId(addonId: string, stableId: string): Promise<DeviceRow | null>;
+    /** Every device owned by one addon, ordered by numeric id. */
+    listByAddon(addonId: string): Promise<readonly DeviceRow[]>;
+    /** Every device an integration owns, ordered by numeric id. */
+    listByIntegration(integrationId: string): Promise<readonly DeviceRow[]>;
+    /** Direct children of one device, ordered by numeric id. */
+    listByParent(parentDeviceId: number): Promise<readonly DeviceRow[]>;
+    /** How many devices the fleet holds. Used to tell "empty store" from "gone device". */
+    count(): Promise<number>;
+    private list;
+    /** Insert or replace the whole identity row. */
+    upsert(meta: PersistedDeviceMeta, extra?: {
+        readonly registered?: boolean;
+        readonly metadata?: Record<string, unknown> | null;
+    }): Promise<void>;
+    /**
+     * Write the named columns of an EXISTING row and nothing else.
+     *
+     * An UPDATE, deliberately not an upsert: a partial upsert would try to INSERT
+     * a row carrying only the patched columns, and SQLite rejects that on the
+     * `NOT NULL` identity columns before the primary-key conflict can turn it
+     * into an update. Every caller resolves the row under the write lock and
+     * throws when it is gone, so matching zero rows means a device was removed
+     * between the resolve and the write — the patch is lost, and a lost write
+     * that says nothing reads as a write that happened.
+     */
+    patch(deviceId: number, patch: DeviceRowPatch): Promise<void>;
+    /**
+     * Insert-or-update the registration columns. See {@link DeviceRegistrationRow}
+     * for why this is a separate, fully-specified statement rather than a patch.
+     */
+    upsertRegistration(row: DeviceRegistrationRow): Promise<void>;
+    /** Drop the device's row. Idempotent. */
+    remove(deviceId: number): Promise<void>;
+    /**
+     * The retirement door for the three blobs this collection replaced.
+     *
+     * The purge is gated on THIS collection being non-empty, and the count has to
+     * be taken after `declare()` — which is why the owning addon runs it and the
+     * settings engine cannot: at the engine's own boot no addon has declared
+     * anything, so every successor would read as unreadable, forever.
+     */
+    retiredRowStore(): RetiredRowStore;
+}

package/dist/builtins/sqlite-storage/retired-settings-keys.d.ts

@@ -42,6 +42,27 @@ export interface RetiredKeyStore {
     /** Replace the row with `value`. */
     write(spec: RetiredKeySpec, value: Record<string, unknown>): Promise<void>;
 }
+/**
+ * The store access the ROW purge needs. Separate from {@link RetiredKeyStore}
+ * because it has a different owner: a retired row is purged by the ADDON that
+ * stopped writing it, right after it has declared the successor collection —
+ * not by the settings engine at its own boot, which runs before any addon has
+ * declared anything and would find every successor unreadable, forever.
+ */
+export interface RetiredRowStore {
+    /** Does the row exist at all? Throws on fault. */
+    hasRow(spec: RetiredRowSpec): Promise<boolean>;
+    /** Delete the row outright. Idempotent. */
+    deleteRow(spec: RetiredRowSpec): Promise<void>;
+    /** How many rows the evidence collection holds. Throws on fault. */
+    countRows(collection: SettingsCollection): Promise<number>;
+}
+/** What a row purge deleted. */
+export interface RetiredRowPurgeResult {
+    readonly owner: string;
+    readonly collection: string;
+    readonly row: string;
+}
 /**
  * Is THIS node the one whose settings store is the cluster's authority?
  *
@@ -83,6 +104,69 @@ export interface RetiredKeyLogger {
  *    `addon-pipeline/src/detection-pipeline/engine-store-keys.ts`.
  */
 export declare const RETIRED_SETTINGS_KEYS: readonly RetiredKeySpec[];
+/**
+ * Whole ROWS whose owner stopped writing them.
+ *
+ * A key purge cannot express this. It reads a row, drops keys, writes the rest
+ * back — so retiring everything in a row leaves an empty row behind, and
+ * retiring a row that IS a map of devices would mean listing 974 keys. What is
+ * dead here is the row itself.
+ *
+ * ### Addressing: these rows are NOT namespaced
+ *
+ * `namespace` on a {@link RetiredKeySpec} is the settings-store namespace, and
+ * it resolves to the table `<namespace>:<collection>`. That is right for an
+ * addon whose `ctx.settings` came from `addon-context-factory` (a forked
+ * runner), which writes `<addonId>:addon-settings` row `root`. A HUB BUILTIN
+ * does not: its `ctx.settings` comes from `ConfigManager.createSettingsView`,
+ * which is `getAllAddon` / `setAllAddon` — one row per key in the UNSCOPED
+ * `addon-settings` table, keyed `<addonId>.<key>`.
+ *
+ * The device-manager is a hub builtin, so its rows are
+ * `addon-settings` / `device-manager.deviceMeta` and never lived in
+ * `device-manager:addon-settings`. The previous key-spec pointed at the scoped
+ * table and was therefore a no-op on every hub that ever ran it — measured on
+ * the 2026-08-19 evidence copy: `device-manager:addon-settings` has zero rows,
+ * while `addon-settings` holds all six device-manager keys.
+ *
+ * ### Ordering: the guard is not optional
+ *
+ * These rows are the ONLY copy of the fleet until
+ * `scripts/migrate-device-manager-blobs.mjs` has written
+ * `device-manager:devices`. Purging them on a hub that has not been migrated
+ * destroys every device. {@link purgeRetiredSettingsRows} therefore refuses
+ * unless `evidence` — a collection that must be non-empty — actually is.
+ */
+export interface RetiredRowSpec {
+    /** Settings-store namespace, or absent for an unscoped collection. */
+    readonly namespace?: string;
+    readonly collection: SettingsCollection;
+    /** Row id inside that collection. */
+    readonly row: string;
+    /** Addon that owned the row — reported, never used to address it. */
+    readonly owner: string;
+    /**
+     * A collection that must hold at least one row before this one may go.
+     * The successor of the retired data: if it is empty, the migration has not
+     * run here and deleting is data loss, not cleanup.
+     */
+    readonly evidence: {
+        readonly collection: SettingsCollection;
+    };
+    readonly reason: string;
+}
+/**
+ * The device-manager's three fleet blobs, replaced by one row per device in
+ * `device-manager:devices` (`device-row-store.ts`).
+ *
+ * 625 KB of the `addon-settings` table's 627 KB, re-read and re-parsed on every
+ * projection and rewritten in full on every rename. `deviceIndex` is listed
+ * here like the other two even though it was never migrated: `addonId` and
+ * `stableId` are columns of every row, so an addon's device list is a query,
+ * and the one bit that was not derivable — "has `registerDevice` run?" — is the
+ * `registered` column.
+ */
+export declare const RETIRED_SETTINGS_ROWS: readonly RetiredRowSpec[];
 /**
  * Adapt the settings backend to {@link RetiredKeyStore}.
  *
@@ -107,3 +191,18 @@ export declare function planRetiredKeyPurge(blob: Readonly<Record<string, unknow
  * after the first boot that ran it.
  */
 export declare function purgeRetiredSettingsKeys(store: RetiredKeyStore, logger: RetiredKeyLogger, specs?: readonly RetiredKeySpec[], env?: NodeJS.ProcessEnv): Promise<readonly RetiredKeyPurgeResult[]>;
+/**
+ * Delete every retired ROW whose successor is populated — on the hub.
+ *
+ * Off the authoritative node this is a no-op that touches nothing and says
+ * nothing, same gate as {@link purgeRetiredSettingsKeys}.
+ *
+ * **The evidence check is the whole safety of this function.** A retired row is
+ * the only copy of its data until the migration has written the successor
+ * collection, and the migration is an OFFLINE step an operator runs — it is not
+ * part of boot. So a hub that boots the new code before being migrated must
+ * find its blobs intact, not deleted: the purge SKIPS, loudly, and the next
+ * boot after the migration cleans up. An evidence read that FAILS is treated
+ * exactly like an empty one — a fault is never permission to delete.
+ */
+export declare function purgeRetiredSettingsRows(store: RetiredRowStore, logger: RetiredKeyLogger, specs?: readonly RetiredRowSpec[], env?: NodeJS.ProcessEnv): Promise<readonly RetiredRowPurgeResult[]>;

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

@@ -1,4 +1,4 @@
-import { CollectionColumn, CollectionIndex, DataStoreEngineInfo, HistogramBucket, ISettingsBackend, SettingsCountInput, SettingsDeleteInput, SettingsGetInput, SettingsHistogramInput, SettingsInsertInput, SettingsIsEmptyInput, SettingsQueryInput, SettingsRecord, SettingsSetInput, SettingsUpdateInput, IScopedLogger } from '@camstack/types';
+import { CollectionColumn, CollectionIndex, DataStoreEngineInfo, HistogramBucket, IScopedLogger, ISettingsBackend, SettingsCountInput, SettingsDeleteInput, SettingsGetInput, SettingsHistogramInput, SettingsInsertInput, SettingsIsEmptyInput, SettingsQueryInput, SettingsRecord, SettingsSetInput, SettingsUpdateInput } from '@camstack/types';
 import { default as Database } from 'better-sqlite3';
 import { MutationFilterInput } from './filter-compiler.js';
 /** Input for {@link SqliteSettingsBackend.deleteWhere}. */
@@ -123,7 +123,29 @@ export declare class SqliteSettingsBackend implements ISettingsBackend {
     setSystem(key: string, value: unknown): void;
     /** Get all system settings as flat key-value */
     getAllSystem(): Record<string, unknown>;
-    /** Get all settings for an addon */
+    /**
+     * Get all settings for an addon.
+     *
+     * Selected by the SAME key range {@link setAllAddon} deletes and re-inserts
+     * — `prefixWhere("<addonId>.")` — and for the same reason `getAllScoped`
+     * uses it: `"<addonId>.<key>"` is the PRIMARY KEY, so the range is a
+     * `SEARCH … USING INDEX` while anything else is a full `SCAN`.
+     *
+     * It used to select on `json_extract(data, '$.addonId')`, which is a second
+     * authority for "this addon's rows" and disagreed with the writer in both
+     * directions: a row inside the JSON's idea of the addon but outside the key
+     * range was READ and never DELETED (a config key that could not be cleared),
+     * and `json_extract` was evaluated on EVERY row — so a four-key addon paid
+     * for the whole table and one unparseable neighbour aborted the statement,
+     * taking out every addon's config read at once.
+     *
+     * The cost was not theoretical. On the live hub `addon-settings` is 627 KB
+     * in 24 rows, 625 KB of it device-manager's three fleet blobs; a V8 profile
+     * of a boot (2026-08-19) had hub-main's JS thread 99.9% busy with **64% of
+     * it inside this method**, which is what put a ~45 s queue in front of every
+     * runner's first store read. Measured on that table: 0.947 ms → ~0.02 ms for
+     * a four-key addon, 2.90 ms → 2.13 ms for device-manager's own.
+     */
     getAllAddon(addonId: string): Record<string, unknown>;
     /** Bulk-set all settings for an addon */
     setAllAddon(addonId: string, config: Record<string, unknown>): void;