@camstack/system 1.2.390 → 1.2.392

package/dist/builtins/sqlite-storage/retired-collections.d.ts

@@ -1,70 +1,139 @@
-import { RetiredKeyLogger } from './retired-settings-keys.js';
-import { DroppedTable, SqliteSettingsBackend } from './sqlite-settings-backend.js';
+/**
+* Retired COLLECTIONS — the boot-time drop of dead tables.
+*
+* ## Why this is not the retired-key purge
+*
+* `retired-settings-keys.ts` handles two shapes of dead configuration: keys
+* inside a live row, and whole rows inside a live collection. Neither can
+* express the third shape — a whole TABLE whose owning code is gone. Deleting
+* its rows would leave the table, and the table is what makes a reader believe
+* the feature still exists: `devices` and `device_settings_kv` sat in the
+* schema of every hub, described by their own `@durable` records, next to a
+* fleet of 974 cameras none of which had ever been written there.
+*
+* ## Where it runs: EVERY node, unlike the key purge
+*
+* The retired keys live in the hub-central settings store, so cleaning them
+* anywhere else is work that can never find anything — hence
+* `settingsStoreIsAuthoritativeHere`. A retired table is the opposite: it was
+* materialised by a `declareCollection` that ran inside whatever engine the
+* declaring code booted next to, so every node that ever ran that code has its
+* own copy. This purge is therefore NOT role-gated — and it takes no `env`
+* parameter at all, where its sibling does, so that the gate cannot be added
+* back by copying a signature.
+*
+* ## Contract
+*
+* - **Idempotent.** An absent table plans nothing, drops nothing, logs nothing.
+* - **Loud exactly once per drop**, and the line carries the row count. An
+*   empty drop is `info`; a drop that destroyed rows is `warn`, because
+*   "nothing read this" is a claim about the code and the number is the only
+*   evidence of what it cost on this machine.
+* - **A fault never blocks boot.** A drop that throws is warned about and the
+*   next spec still runs; the next boot retries.
+*
+* ## Adding a collection
+*
+* Only add a table whose declaring code you have DELETED in the same change.
+* A table listed here while something still declares it is dropped at every
+* boot and recreated moments later — a churn no test would catch. Worse than
+* churn, in fact: the purge is not role-gated, so a live table added here is
+* dropped **on the hub too**, at every boot, and the rows are reported only
+* after they are gone. `scripts/check-retired-collections-are-dead.ts` now
+* refuses any entry that still appears in `docs/reference/storage.md`.
+*
+* ## What this list can NOT retire: a whole node's store
+*
+* On 2026-09-01 agents stopped booting a `data-store-provider` of their own
+* (`server/backend/src/agent/agent-infra-capabilities.ts`). It looks like a
+* deletion that should retire its tables. It is not, for two independent
+* reasons, and both are worth writing down because the next session will reach
+* for this file first:
+*
+*  1. **Every table an agent held is a table the hub still declares.**
+*     `addon-settings`, `storage_locations`, `system-settings`, `sections`,
+*     `provider-settings`, the `device-*` family, `alerts`, `vec_indexes` and
+*     each `<addonId>:addon-settings` variant are all live on the hub. Listing
+*     any of them here drops the HUB's copy — see the guard.
+*  2. **The purge runs inside the engine's boot, and the agent no longer boots
+*     one.** Nothing on that node would execute the drop even if a name were
+*     safe to add. This is not hypothetical: the `macmini` node's leftover
+*     store still carries `devices` and `device_settings_kv` — the two tables
+*     D183 retired — because its engine has not booted since 2026-05-09.
+*
+* The agent's leftover `camstack.db` is therefore inert, not resurrectable: no
+* engine opens it and no code reads it. Its disposal is an operator decision,
+* not a boot-time one, and it is recorded in the ADR rather than automated
+* here — this module drops TABLES, and deleting somebody's database file is a
+* different kind of act.
+*/
+import type { RetiredKeyLogger } from "./retired-settings-keys.js";
+import type { DroppedTable, SqliteSettingsBackend } from "./sqlite-settings-backend.js";
 /** One retired-table declaration. */
 export interface RetiredCollectionSpec {
-    /**
-     * The table name as it exists on disk. These tables are NOT namespaced —
-     * the retired code declared them bare — so this is the literal name, not a
-     * `<namespace>:<collection>` pair to be resolved.
-     */
-    readonly collection: string;
-    /** The code that used to own it — reported, never used to address it. */
-    readonly owner: string;
-    /** Why it is dead. Cited in the log line, not re-derived at the call site. */
-    readonly reason: string;
+	/**
+	* The table name as it exists on disk. These tables are NOT namespaced —
+	* the retired code declared them bare — so this is the literal name, not a
+	* `<namespace>:<collection>` pair to be resolved.
+	*/
+	readonly collection: string;
+	/** The code that used to own it — reported, never used to address it. */
+	readonly owner: string;
+	/** Why it is dead. Cited in the log line, not re-derived at the call site. */
+	readonly reason: string;
 }
 /** What one drop destroyed. */
 export interface RetiredCollectionDrop {
-    readonly collection: string;
-    readonly owner: string;
-    /** Rows the table held. Zero is the expected case and is still reported. */
-    readonly rows: number;
+	readonly collection: string;
+	readonly owner: string;
+	/** Rows the table held. Zero is the expected case and is still reported. */
+	readonly rows: number;
 }
 /** The engine access the purge needs. Narrow on purpose — trivially fakeable. */
 export interface RetiredCollectionStore {
-    /** Drop `collection`, or answer `null` when it is not there. Throws on fault. */
-    drop(collection: string): Promise<DroppedTable | null>;
+	/** Drop `collection`, or answer `null` when it is not there. Throws on fault. */
+	drop(collection: string): Promise<DroppedTable | null>;
 }
 /**
- * The dead tables.
- *
- * `devices` / `device_settings_kv` — the device half of the
- * integration-registry ([D183](../../../../../docs/decisions/adr-0183.md)).
- * The registry's INTEGRATION half is live (`integrations`,
- * `integration_settings`); its device half never had a production caller and
- * never had a row. The fleet lives in `device-manager:devices`, under numeric
- * ids, while these tables key on `dev_NNNN` — the two id-spaces could not be
- * reconciled even if something had wanted to.
- *
- * `pipeline-analytics:track-groups` / `:track-group-members` — the co-moving
- * GROUP entity. It shipped on 2026-08-24 and was kill-switched the same day
- * (duplicate sealed rows made Library → Gruppi unusable); the operator decided
- * on 2026-09-01 to delete it rather than re-open it. The clusterer, the live
- * buffer, the sealer, the query, the two cap methods and the two custom
- * actions are gone, so nothing declares these tables any more. The group-owned
- * MEDIA rows are NOT here — they live in the shared `pipeline-analytics:media`
- * and are collected by the orphan audit through `RETIRED_OWNER_KINDS`.
- *
- * `pipeline-analytics:summaries` / `:summary-members` — the session SUMMARY,
- * the entity that grouped tracks by proximity at birth (D489) and split them
- * when they walked apart (D490). Its production path was switched off on
- * 2026-09-16 and the operator decided on 2026-09-29 to delete it (D680): the
- * sealer, the store, the group shot, the three cap methods and the digest's
- * `groups` reading are gone, so nothing declares these tables. The group
- * shots were `summary`-owned rows in `pipeline-analytics:media` and go the
- * same way as the group entity's — through `RETIRED_OWNER_KINDS`.
- */
+* The dead tables.
+*
+* `devices` / `device_settings_kv` — the device half of the
+* integration-registry ([D183](../../../../../docs/decisions/adr-0183.md)).
+* The registry's INTEGRATION half is live (`integrations`,
+* `integration_settings`); its device half never had a production caller and
+* never had a row. The fleet lives in `device-manager:devices`, under numeric
+* ids, while these tables key on `dev_NNNN` — the two id-spaces could not be
+* reconciled even if something had wanted to.
+*
+* `pipeline-analytics:track-groups` / `:track-group-members` — the co-moving
+* GROUP entity. It shipped on 2026-08-24 and was kill-switched the same day
+* (duplicate sealed rows made Library → Gruppi unusable); the operator decided
+* on 2026-09-01 to delete it rather than re-open it. The clusterer, the live
+* buffer, the sealer, the query, the two cap methods and the two custom
+* actions are gone, so nothing declares these tables any more. The group-owned
+* MEDIA rows are NOT here — they live in the shared `pipeline-analytics:media`
+* and are collected by the orphan audit through `RETIRED_OWNER_KINDS`.
+*
+* `pipeline-analytics:summaries` / `:summary-members` — the session SUMMARY,
+* the entity that grouped tracks by proximity at birth (D489) and split them
+* when they walked apart (D490). Its production path was switched off on
+* 2026-09-16 and the operator decided on 2026-09-29 to delete it (D680): the
+* sealer, the store, the group shot, the three cap methods and the digest's
+* `groups` reading are gone, so nothing declares these tables. The group
+* shots were `summary`-owned rows in `pipeline-analytics:media` and go the
+* same way as the group entity's — through `RETIRED_OWNER_KINDS`.
+*/
 export declare const RETIRED_COLLECTIONS: readonly RetiredCollectionSpec[];
 /**
- * Adapt the SQLite engine to {@link RetiredCollectionStore}.
- *
- * The DDL itself is the engine's — it owns the handle and the memos a drop has
- * to evict. This module owns only the list and the reporting.
- */
+* Adapt the SQLite engine to {@link RetiredCollectionStore}.
+*
+* The DDL itself is the engine's — it owns the handle and the memos a drop has
+* to evict. This module owns only the list and the reporting.
+*/
 export declare function retiredCollectionStoreOf(backend: SqliteSettingsBackend): RetiredCollectionStore;
 /**
- * Drop every retired table that is still present. Returns one entry per table
- * actually dropped — empty when the schema is already clean, which is the
- * steady state after the first boot that ran it.
- */
+* Drop every retired table that is still present. Returns one entry per table
+* actually dropped — empty when the schema is already clean, which is the
+* steady state after the first boot that ran it.
+*/
 export declare function purgeRetiredCollections(store: RetiredCollectionStore, logger: RetiredKeyLogger, specs?: readonly RetiredCollectionSpec[]): Promise<readonly RetiredCollectionDrop[]>;