@camstack/system 1.2.447 → 1.2.449

package/dist/builtins/device-history/index.d.ts

@@ -0,0 +1,3 @@
+export { DeviceHistoryAddon, default } from "./device-history.addon.js";
+export type { DeviceHistoryConfig } from "./device-history.addon.js";
+export { DEFAULT_RETENTION, type RetentionPolicy } from "./retention/retention.js";

package/dist/builtins/device-history/ingest/producer-ingest.d.ts

@@ -0,0 +1,89 @@
+/**
+* The producer door (plan §5.1): `declareSeries`, `record`, `recordBuckets`.
+*
+* Ownership is the transport-stamped caller (`callerAddonId`), never anything
+* the caller claims; a key is `addon:<callerAddonId>/<name>`, so one addon can
+* only ever declare keys inside its own prefix and a write to another addon's
+* key is `not-owner`. Every refusal is COUNTED per (key, reason) and returned
+* (D391): a producer that is silently dropped looks exactly like one that never
+* produced.
+*
+* `record` is for low-rate points (at most one per 10 s per series, sustained);
+* `recordBuckets` takes CLOSED five-minute buckets and is an idempotent upsert
+* keyed (series, bucketStart), written before the call returns so a failure
+* reaches the producer, which re-queues (D58).
+*/
+import { type DeviceHistoryIngestResult, type DeviceHistorySubject, type IScopedLogger } from "@camstack/types";
+import type { DeviceDirectory } from "../capture/device-directory.js";
+import type { PointWriter } from "../capture/point-writer.js";
+import type { HistoryCounters } from "../status/counters.js";
+import type { HistoryStore } from "../store/history-store.js";
+import { type SeriesRegistry } from "../store/series-registry.js";
+/** One point per series per this many ms, sustained. */
+export declare const RECORD_MIN_INTERVAL_MS: number;
+/** A point or bucket may be at most this far in the future (clock skew). */
+export declare const FUTURE_TOLERANCE_MS: number;
+export interface DeclareSeriesInput {
+	readonly name: string;
+	readonly subjectKind: "device" | "node";
+	readonly kind: "gauge" | "counter" | "boolean";
+	readonly unit?: string;
+	readonly displayName: string;
+	readonly ingest: "points" | "buckets";
+}
+export interface RecordPointInput {
+	readonly key: string;
+	readonly subject: DeviceHistorySubject;
+	readonly scope: string;
+	readonly ts: number;
+	readonly value: number;
+}
+export interface RecordBucketInput {
+	readonly key: string;
+	readonly subject: DeviceHistorySubject;
+	readonly scope: string;
+	readonly bucketStart: number;
+	readonly samples: number;
+	readonly sum: number;
+	readonly min: number;
+	readonly max: number;
+	readonly last: number | null;
+	readonly lastTs: number | null;
+}
+export interface IngestDeps {
+	readonly registry: SeriesRegistry;
+	readonly store: HistoryStore;
+	readonly directory: DeviceDirectory;
+	readonly writer: PointWriter;
+	readonly counters: HistoryCounters;
+	readonly logger: IScopedLogger;
+	readonly clock: () => number;
+	readonly optedOut: () => ReadonlySet<number>;
+	readonly retention: () => {
+		readonly rawMs: number;
+		readonly fiveMinuteMs: number;
+	};
+	/** A 5m row landed; the hour containing it is dirty. */
+	readonly onBucketWritten: (seriesId: number, bucketStart: number) => void;
+}
+export declare class ProducerIngest {
+	private readonly deps;
+	/** Last accepted point time per series, for the sustained-rate bound. */
+	private readonly lastAccepted;
+	constructor(deps: IngestDeps);
+	/** A purged series leaves no rate-limit state behind. */
+	forgetSeries(series: {
+		key: string;
+		subject: string;
+		scope: string;
+	}): void;
+	declareSeries(callerAddonId: string | null, input: DeclareSeriesInput): Promise<{
+		key: string;
+	}>;
+	/** Why a write to `metric` by `caller` for this subject must be refused, or null. */
+	private refusalFor;
+	record(callerAddonId: string | null, points: readonly RecordPointInput[]): Promise<DeviceHistoryIngestResult>;
+	recordBuckets(callerAddonId: string | null, buckets: readonly RecordBucketInput[]): Promise<DeviceHistoryIngestResult>;
+	/** Persist the widened span of every series a bucket batch touched, then remember it. */
+	private recordSpans;
+}

package/dist/builtins/device-history/query/history-query.d.ts

@@ -0,0 +1,69 @@
+/**
+* Reads: `listSeries` and `query` (plan §5.1).
+*
+* `auto` resolution picks the finest tier whose retention covers `from` and
+* whose point count fits `maxPoints`: a rollup tier fits when
+* `ceil(range / bucket) <= maxPoints`, raw fits when a read of `maxPoints + 1`
+* rows comes back short. The coarsest covering tier is the last resort and is
+* truncated to its newest `maxPoints` points (`truncated: true`) rather than
+* answering nothing.
+*
+* `before` is the last point strictly before the window in the chosen tier, so a
+* step chart can start at the value in force when the window opens — a quiet
+* bucket has no row, and the held value is otherwise invisible.
+*/
+import type { DeviceHistoryQueryPoint, DeviceHistoryResolution, DeviceHistorySeriesInfo, DeviceHistorySubject } from "@camstack/types";
+import { type RetentionPolicy } from "../retention/retention.js";
+import type { HistoryStore } from "../store/history-store.js";
+import { type SeriesRegistry } from "../store/series-registry.js";
+import { type HistoryCatalog } from "../capture/capture-engine.js";
+type Tier = DeviceHistoryResolution;
+export interface QueryInput {
+	readonly key: string;
+	readonly subject: DeviceHistorySubject;
+	readonly scope?: string;
+	readonly from: number;
+	readonly to: number;
+	readonly resolution: Tier | "auto";
+	readonly maxPoints: number;
+}
+export interface QuerySeries {
+	readonly scope: string;
+	readonly before: {
+		readonly t: number;
+		readonly value: number | null;
+	} | null;
+	readonly points: readonly DeviceHistoryQueryPoint[];
+}
+export interface QueryOutput {
+	readonly resolution: Tier;
+	readonly series: readonly QuerySeries[];
+	readonly truncated: boolean;
+}
+export interface QueryDeps {
+	readonly registry: SeriesRegistry;
+	readonly store: HistoryStore;
+	readonly clock: () => number;
+	readonly retention: () => RetentionPolicy;
+	readonly catalog: HistoryCatalog;
+	/** The device's current slice of a cap, for a `unitFrom` series; `null` when unreadable. */
+	readonly readCapSlice: (deviceId: number, capName: string) => Promise<Readonly<Record<string, unknown>> | null>;
+}
+export declare class HistoryQuery {
+	private readonly deps;
+	constructor(deps: QueryDeps);
+	query(input: QueryInput): Promise<QueryOutput>;
+	/** Tiers whose retention covers `from`, finest first; the coarsest is always present. */
+	private coveringTiers;
+	/** Cheap fit test for rollup tiers; raw is decided by the read itself. */
+	private fits;
+	private readTier;
+	/** Rows arrive newest first and one over the bound; keep the newest `maxPoints`, oldest first. */
+	private shape;
+	private before;
+	listSeries(subject: DeviceHistorySubject): Promise<readonly DeviceHistorySeriesInfo[]>;
+	/** The metric's fixed unit, else the device's own (a `unitFrom` field), else unknown. */
+	private unitOf;
+	private specOf;
+}
+export {};

package/dist/builtins/device-history/retention/departure-tracker.d.ts

@@ -0,0 +1,33 @@
+/**
+* Since when each device has been ABSENT from every successful device listing.
+*
+* A listing that answered is not a listing that was complete: after a hub restart
+* a provider addon that is still booting leaves its devices out of an otherwise
+* successful `listAll`, and change-only capture means a stable series has not been
+* written for days. Deciding "gone" from one listing, or from the series' own last
+* write, would delete live history for good (D49). So the only thing a listing may
+* do here is move a clock: the first listing that misses a device records WHEN
+* (persisted, so a restart neither resets it to now nor treats it as old), any
+* listing that shows the device clears it, and a series becomes purgeable only
+* after {@link DEPARTED_ABSENCE_MS} of unbroken absence.
+*
+* The `device.unregistered` event is deliberately not used: it is telemetry and
+* may be dropped, and a provider that restarts emits it for devices that come back.
+*/
+import type { IScopedLogger } from "@camstack/types";
+import type { HistoryStore } from "../store/history-store.js";
+import type { SeriesRegistry } from "../store/series-registry.js";
+export declare const DEPARTED_ABSENCE_MS: number;
+export declare class DepartureTracker {
+	private readonly store;
+	private readonly registry;
+	private readonly logger;
+	private missing;
+	constructor(store: HistoryStore, registry: SeriesRegistry, logger: IScopedLogger);
+	load(): Promise<void>;
+	missingSince(deviceId: number): number | undefined;
+	/** Forget a device's clock — its series were removed because it was DELETED (D865). */
+	forget(deviceId: number): Promise<void>;
+	/** Feed one SUCCESSFUL listing. A failed read never reaches here. */
+	observe(listed: ReadonlySet<number>, now: number): Promise<void>;
+}

package/dist/builtins/device-history/retention/retention.d.ts

@@ -0,0 +1,67 @@
+/**
+* Retention (plan §5.5, operator answer §13): raw 7 days, 5m 14 days, 1h 1 year,
+* 1d forever — global addon settings.
+*
+* Per series and per tier the delete is a PRIMARY KEY range
+* (`series_id = ? AND ts BETWEEN 0 AND cutoff-1`), so no `ts` index exists to
+* maintain. A row whose time equals the cutoff is KEPT. Each series is visited
+* at most once per {@link RETENTION_STEP_MS} of cutoff advance (an hour for the
+* short tiers, a day for the long ones): without that, every active series
+* would pay an empty-range delete on every ten-minute run.
+*
+* Every delete is SLICED by time (a day for the short tiers, 30 days for the long
+* ones) with a yield between slices, so one statement never holds the history
+* thread for a whole backlog.
+*
+* A series is purged only after its device has been absent from EVERY successful
+* device listing for a week ({@link DepartureTracker}); it is never judged from the
+* series' own last write, which for a stable change-only series is days old while
+* the device is perfectly alive. An OPTED-OUT device keeps its history until
+* retention ages it out: stopping capture is the switch; deleting history is not.
+*/
+import type { IScopedLogger } from "@camstack/types";
+import type { DepartureTracker } from "./departure-tracker.js";
+import type { HistoryCounters } from "../status/counters.js";
+import type { HistoryStore, StoredTier } from "../store/history-store.js";
+import type { SeriesRegistry } from "../store/series-registry.js";
+export interface RetentionPolicy {
+	readonly rawDays: number;
+	readonly fiveMinuteDays: number;
+	readonly hourDays: number;
+	/** `null` (or 0) keeps the daily tier forever. */
+	readonly dayDays: number | null;
+}
+export declare const DEFAULT_RETENTION: RetentionPolicy;
+/** Cutoff per tier: rows strictly older are deleted. `null` = keep forever. */
+export declare function retentionCutoffs(policy: RetentionPolicy, now: number): Readonly<Record<StoredTier, number | null>>;
+export interface RetentionDeps {
+	readonly store: HistoryStore;
+	readonly registry: SeriesRegistry;
+	readonly departures: DepartureTracker;
+	readonly counters: HistoryCounters;
+	readonly logger: IScopedLogger;
+	/** Gives the thread back between slices; a spec counts it. */
+	readonly yieldNow?: () => Promise<void>;
+}
+export declare class RetentionJob {
+	private readonly deps;
+	private readonly appliedUpTo;
+	private running;
+	constructor(deps: RetentionDeps);
+	run(policy: RetentionPolicy, now: number): Promise<void>;
+	private doRun;
+	/** Delete `[lo, hiInclusive]` of one tier in time slices, yielding between them. */
+	/** Drop the visit markers of a purged series. */
+	forgetSeries(seriesId: number): void;
+	private deleteSliced;
+	/** Tier by tier in slices, then the series row (and whatever the slices missed). */
+	private purgeSeries;
+	/**
+	* Delete every series of a DELETED device now (D865). Driven by a tombstone
+	* through the `device-removal-hook`, never by a listing: the week-long
+	* absence clock above remains the backstop for a device removed before
+	* tombstones existed.
+	*/
+	purgeDevice(deviceId: number, now: number): Promise<number>;
+	private purgeDeparted;
+}

package/dist/builtins/device-history/rollup/rollup-engine.d.ts

@@ -0,0 +1,72 @@
+/**
+* Rollups 5m / 1h / 1d, computed by this addon and nowhere else (plan §5.5).
+*
+* Every rollup is a RECOMPUTE from the tier below — never an increment — so
+* running one twice, after a restart, or after a late write gives the same row:
+*
+*  - 5m (point series only): from the raw rows of the bucket, once it has
+*    closed (+30 s grace). Raw is the source of truth, which is why a restart
+*    loses nothing: {@link RollupEngine.bootRecompute} rebuilds the recent
+*    window, the still-open bucket included, from raw.
+*  - 1h: from the 5m rows when the hour closes (+5 min grace).
+*  - 1d: from the 1h rows at hub-local midnight (+15 min grace).
+*
+* A write marks the bucket above it DIRTY; a late `recordBuckets` into an hour
+* that was already rolled just marks it again, and the next tick recomputes it.
+* The dirty sets are memory: a crash forgets them, and the boot window
+* ({@link BOOT_WINDOW_MS}) is what makes that harmless.
+*/
+import type { IScopedLogger } from "@camstack/types";
+import type { HistoryCounters } from "../status/counters.js";
+import type { HistoryStore } from "../store/history-store.js";
+import type { SeriesRegistry } from "../store/series-registry.js";
+import type { WrittenPoints } from "../capture/point-writer.js";
+/** Series handled per tier per tick: bounds one tick on a catch-up. */
+export declare const MAX_SERIES_PER_TICK: number;
+/** How far back a boot rebuilds from raw and re-marks the upper tiers. */
+export declare const BOOT_WINDOW_MS: number;
+export interface RollupEngineDeps {
+	readonly store: HistoryStore;
+	readonly registry: SeriesRegistry;
+	readonly counters: HistoryCounters;
+	readonly logger: IScopedLogger;
+	readonly clock: () => number;
+}
+export declare class RollupEngine {
+	private readonly deps;
+	private readonly dirty5m;
+	private readonly dirty1h;
+	private readonly dirty1d;
+	private ticking;
+	constructor(deps: RollupEngineDeps);
+	dirtyCounts(): {
+		readonly m5: number;
+		readonly h1: number;
+		readonly d1: number;
+	};
+	/** Raw points landed: their 5-minute buckets (and a late bucket's successor) are dirty. */
+	markPoints(written: readonly WrittenPoints[]): void;
+	/** A 5m row landed (computed, or a producer bucket): its hour is dirty. */
+	markFiveMinuteRow(seriesId: number, bucketStart: number): void;
+	/** One pass over the three tiers. Single-flight; errors are counted and the work stays dirty. */
+	tick(): Promise<void>;
+	private doTick;
+	private guarded;
+	private closedBuckets;
+	/** Forget everything held for a series that was purged. */
+	forgetSeries(seriesId: number): void;
+	private tickFiveMinute;
+	private tickHour;
+	private tickDay;
+	/** Raw → 5m rows for buckets in `[from, toExclusive)`; writes them and marks their hours. */
+	recomputeFiveMinute(seriesId: number, from: number, toExclusive: number, horizon: number): Promise<number>;
+	private recomputeHour;
+	private recomputeDay;
+	private recomputeFrom;
+	/**
+	* After a restart the dirty sets are gone. Rebuild the recent window from raw
+	* (the still-open bucket included, time-weighted up to `now`), then mark the
+	* 1h / 1d buckets of that window dirty so the next ticks recompute them.
+	*/
+	bootRecompute(now: number): Promise<number>;
+}

package/dist/builtins/device-history/rollup/rollup-math.d.ts

@@ -0,0 +1,44 @@
+export interface RollupRow {
+	readonly seriesId: number;
+	readonly bucketStart: number;
+	readonly samples: number;
+	readonly sum: number;
+	readonly min: number;
+	readonly max: number;
+	/** `null` is unknown, never zero (D393). */
+	readonly last: number | null;
+	readonly lastTs: number | null;
+	/** Σ value·ms over the covered time; `null` for bucket-ingested series. */
+	readonly twSum: number | null;
+	/** Milliseconds `twSum` covers. */
+	readonly twMs: number | null;
+}
+export interface RawPoint {
+	readonly ts: number;
+	readonly value: number;
+}
+export interface RawToFiveMinuteInput {
+	readonly seriesId: number;
+	/** Ascending by `ts`. */
+	readonly points: readonly RawPoint[];
+	/** The newest point strictly before the first bucket in `points`, if any. */
+	readonly carryIn: RawPoint | null;
+	/** Time-weighting stops here for a bucket that has not closed yet. */
+	readonly horizon: number;
+}
+/** One row per 5-minute bucket that has at least one point. */
+export declare function rawToFiveMinuteRows(input: RawToFiveMinuteInput): readonly RollupRow[];
+export interface CombineInput {
+	readonly seriesId: number;
+	readonly windowStart: number;
+	readonly windowEnd: number;
+	readonly childWidthMs: number;
+	/** Child rows inside the window, ascending by `bucketStart`. */
+	readonly rows: readonly RollupRow[];
+	/** The `last` of the newest child row BEFORE the window, if known. */
+	readonly carryIn: number | null;
+	/** Time-weighting stops here for a window that has not closed yet. */
+	readonly horizon: number;
+}
+/** One row of the next tier from the child rows of its window; `null` when there are none. */
+export declare function combineRows(input: CombineInput): RollupRow | null;

package/dist/builtins/device-history/runtime/history-runtime.d.ts

@@ -0,0 +1,93 @@
+/**
+* The assembled device-history engine, with no knowledge of the addon shell:
+* everything it needs from the hub arrives as a dependency (the door, the
+* device directory source, the snapshot read), so a spec can run the whole
+* thing over a real `history.db` in a temp dir with a controlled clock.
+*
+* Boot is two steps so the shell can subscribe to the bus in between and lose
+* nothing:
+*   {@link HistoryRuntime.prepare}    declare, load, seed — nothing is written;
+*   {@link HistoryRuntime.finishBoot} rebuild the recent rollup window, first reconcile.
+* Then {@link HistoryRuntime.startTimers} arms flush (10 s), rollups (60 s),
+* reconcile (5 min), retention (10 min) and the row counts (30 min).
+*/
+import type { DeviceHistoryStatus, IScopedLogger } from "@camstack/types";
+import { CaptureEngine, type HistoryCatalog, type SnapshotMap } from "../capture/capture-engine.js";
+import { DeviceDirectory, type DeviceTypeSource } from "../capture/device-directory.js";
+import { PointWriter } from "../capture/point-writer.js";
+import { ProducerIngest } from "../ingest/producer-ingest.js";
+import { HistoryQuery } from "../query/history-query.js";
+import { DepartureTracker } from "../retention/departure-tracker.js";
+import { RetentionJob, type RetentionPolicy } from "../retention/retention.js";
+import { RollupEngine } from "../rollup/rollup-engine.js";
+import { HistoryCounters } from "../status/counters.js";
+import type { HistoryDoor } from "../store/history-door.js";
+import { HistoryStore } from "../store/history-store.js";
+import { SeriesRegistry } from "../store/series-registry.js";
+export declare const ROLLUP_INTERVAL_MS: number;
+export declare const RECONCILE_INTERVAL_MS: number;
+export declare const RETENTION_INTERVAL_MS: number;
+/**
+* ONE exact row count per boot (a `COUNT(*)` is a full scan on the history thread), taken late so
+* boot is not spent scanning the raw table. After it the figures move with the writes and deletes
+* the addon itself makes — an estimate, labelled so in the docs.
+*/
+export declare const FIRST_COUNT_DELAY_MS: number;
+export interface HistoryRuntimeDeps {
+	readonly door: HistoryDoor;
+	readonly catalog: HistoryCatalog;
+	readonly deviceSource: DeviceTypeSource;
+	readonly readSnapshots: () => Promise<SnapshotMap>;
+	readonly readCapSlice: (deviceId: number, capName: string) => Promise<Readonly<Record<string, unknown>> | null>;
+	readonly retention: () => RetentionPolicy;
+	readonly logger: IScopedLogger;
+	readonly clock: () => number;
+}
+export declare class HistoryRuntime {
+	private readonly deps;
+	readonly counters: HistoryCounters;
+	readonly store: HistoryStore;
+	readonly registry: SeriesRegistry;
+	readonly directory: DeviceDirectory;
+	readonly rollup: RollupEngine;
+	readonly writer: PointWriter;
+	readonly capture: CaptureEngine;
+	readonly ingest: ProducerIngest;
+	readonly query: HistoryQuery;
+	readonly retentionJob: RetentionJob;
+	readonly departures: DepartureTracker;
+	private optedOutDevices;
+	private readonly tierCounts;
+	private readonly startedAt;
+	private timers;
+	private countTimeout;
+	private ready;
+	constructor(deps: HistoryRuntimeDeps);
+	prepare(): Promise<void>;
+	finishBoot(): Promise<void>;
+	startTimers(): void;
+	stop(): Promise<void>;
+	/** Emit pending trailing points, then write the buffer. */
+	flushNow(): Promise<void>;
+	/**
+	* Restore changes a dropped event missed. A FAILED read changes nothing (D49):
+	* it is counted and logged, and the next pass tries again.
+	*/
+	reconcile(): Promise<void>;
+	refreshCounts(): Promise<void>;
+	/**
+	* ONE aggregated INFO naming what was skipped, refused, deleted or failed since the
+	* previous report (D391) — the counts a per-event line would drown. Silent when
+	* nothing happened.
+	*/
+	reportWindow(): void;
+	isEnabled(deviceId: number): boolean;
+	setEnabled(deviceId: number, enabled: boolean): Promise<boolean>;
+	/** Delete the history of a deleted device: its series, opt-out and absence clock. */
+	removeDevice(deviceId: number): Promise<{
+		series: number;
+	}>;
+	/** Series held per device, for the admin clean-up listing. */
+	seriesByDevice(): ReadonlyMap<number, number>;
+	status(): DeviceHistoryStatus;
+}

package/dist/builtins/device-history/status/counters.d.ts

@@ -0,0 +1,55 @@
+/**
+* Counters since boot, read by `getStatus`. Everything the addon DROPS or
+* REFUSES is counted here (D391): a silent branch reads as "never happened".
+* `summarySinceLast` turns the same counters into the aggregated INFO line the
+* runtime logs once per pass.
+*/
+export type CountedTier = "raw" | "5m" | "1h" | "1d";
+export interface WindowSummary {
+	readonly skipped: Record<string, number>;
+	readonly refused: Record<string, number>;
+	readonly deleted: Record<string, number>;
+	readonly flushFailures: number;
+}
+export declare class HistoryCounters {
+	eventsSeen: number;
+	pointsEmitted: number;
+	pointsWritten: number;
+	pointsDropped: number;
+	trailingEmitted: number;
+	reconciledPoints: number;
+	reconcileRuns: number;
+	reconcileFailures: number;
+	lastReconcileAt: number | null;
+	lastFlushAt: number | null;
+	flushFailures: number;
+	ingestAccepted: number;
+	rollupErrors: number;
+	last5mAt: number | null;
+	last1hAt: number | null;
+	last1dAt: number | null;
+	retentionLastRunAt: number | null;
+	purgedSeries: number;
+	directoryRefreshAt: number | null;
+	private readonly skipped;
+	private readonly refused;
+	private readonly deleted;
+	private reported;
+	/** Net rows written minus deleted per tier since boot — the estimate behind `getStatus` row counts. */
+	private readonly rowDelta;
+	/** Newest bucket seen per (tier, series): a row beyond it is NEW, a rewrite of an older one is not. */
+	private readonly newestBucket;
+	skip(reason: string, count?: number): void;
+	refuse(reason: string, count?: number): void;
+	addDeleted(tier: string, count: number): void;
+	addRawRows(count: number): void;
+	/** Rollup rows written: only a bucket newer than the series' newest known is counted as a new row. */
+	noteRollupRows(tier: "5m" | "1h" | "1d", seriesId: number, bucketStarts: readonly number[]): void;
+	rowDeltaOf(tier: CountedTier): number;
+	forgetSeries(seriesId: number): void;
+	skippedRecord(): Record<string, number>;
+	refusedRecord(): Record<string, number>;
+	deletedRecord(): Record<string, number>;
+	/** What was skipped, refused, deleted or failed since the last call; `null` when nothing. */
+	summarySinceLast(): WindowSummary | null;
+}

package/dist/builtins/device-history/store/history-door.d.ts

@@ -0,0 +1,7 @@
+/**
+* The slice of the settings door device-history uses. A `Pick` of the
+* generated client, never a hand-written interface (a hand-written copy keeps
+* compiling after a method is removed and fails at runtime).
+*/
+import type { SettingsStoreClient } from "@camstack/types";
+export type HistoryDoor = Pick<SettingsStoreClient, "declareCollection" | "query" | "insert" | "upsertMany" | "transact" | "deleteWhere" | "update" | "count" | "delete">;

package/dist/builtins/device-history/store/history-schema.d.ts

@@ -0,0 +1,26 @@
+/**
+* The `history.db` data model (plan §4), declared through the settings door
+* with `database: 'history'` (D851). The engine turns each declaration into the
+* DDL the plan lists; a spec compares `sqlite_master` with it.
+*
+* The opt-out table is configuration, not history: it names no database and so
+* lives in `camstack.db`, which the nightly backup carries.
+*/
+import type { DeclareCollectionInput } from "@camstack/types";
+import type { RollupTier } from "../time/bucket-time.js";
+export declare const HISTORY_NAMESPACE = "device-history";
+export declare const COLLECTIONS: {
+	readonly metrics: "metrics";
+	readonly series: "series";
+	readonly raw: "raw";
+	readonly rollup5m: "rollup-5m";
+	readonly rollup1h: "rollup-1h";
+	readonly rollup1d: "rollup-1d";
+	readonly optOuts: "device-opt-outs";
+	readonly departures: "device-departures";
+};
+export type TierCollection = (typeof COLLECTIONS)["rollup5m" | "rollup1h" | "rollup1d"];
+export declare function rollupCollectionOf(tier: RollupTier): TierCollection;
+/** Table name the engine creates for a collection of this addon. */
+export declare function tableNameOf(collection: string): string;
+export declare const HISTORY_DECLARATIONS: readonly DeclareCollectionInput[];

package/dist/builtins/device-history/store/history-store.d.ts

@@ -0,0 +1,86 @@
+/**
+* Every read and write device-history makes against its tables, through the
+* settings door (D44). No addon-side code builds SQL; the shapes below are what
+* the engine prepares, and a spec asserts the plan of each on the REAL
+* statement (D447): every range is a PRIMARY KEY search on `(series_id, ts)` or
+* `(series_id, bucket_start)`, so no `ts` index exists or is needed.
+*
+* Every read states a `limit` — the door's default row bound is 2 000 and an
+* unstated one would silently truncate (D58's cousin).
+*/
+import type { DeviceHistoryKind } from "@camstack/types";
+import type { RawPoint, RollupRow } from "../rollup/rollup-math.js";
+import type { RollupTier } from "../time/bucket-time.js";
+import type { HistoryDoor } from "./history-door.js";
+export interface MetricRecord {
+	readonly key: string;
+	readonly source: "cap" | "addon";
+	readonly ownerAddon: string;
+	readonly subjectKind: "device" | "node";
+	readonly kind: DeviceHistoryKind;
+	readonly unit: string | null;
+	readonly displayName: string;
+	readonly ingest: "points" | "buckets";
+	readonly declaredAt: number;
+}
+export interface SeriesRecord {
+	readonly id: number;
+	readonly key: string;
+	/** `d:<deviceId>` | `n:<nodeId>`. */
+	readonly subject: string;
+	readonly deviceId: number | null;
+	readonly scope: string;
+	readonly firstTs: number;
+	readonly lastTs: number;
+}
+export interface NewSeries {
+	readonly key: string;
+	readonly subject: string;
+	readonly deviceId: number | null;
+	readonly scope: string;
+	readonly ts: number;
+}
+export interface SeriesSpanUpdate {
+	readonly id: number;
+	readonly lastTs: number;
+}
+export type StoredTier = "raw" | RollupTier;
+/** Rows per read page. */
+export declare const READ_PAGE = 5e3;
+export declare class HistoryStore {
+	private readonly door;
+	constructor(door: HistoryDoor);
+	declare(): Promise<void>;
+	loadMetrics(): Promise<readonly MetricRecord[]>;
+	upsertMetric(metric: MetricRecord): Promise<void>;
+	/** Series with `id > afterId`, ascending — the boot load pages with this. */
+	loadSeriesPage(afterId: number, limit: number): Promise<readonly SeriesRecord[]>;
+	findSeries(key: string, subject: string, scope: string): Promise<SeriesRecord | null>;
+	insertSeries(series: NewSeries): Promise<SeriesRecord>;
+	touchSeries(updates: readonly SeriesSpanUpdate[]): Promise<void>;
+	widenSeriesStart(id: number, firstTs: number): Promise<void>;
+	upsertRaw(rows: readonly {
+		seriesId: number;
+		ts: number;
+		value: number;
+	}[]): Promise<void>;
+	/** Points of a series in `[from, toInclusive]`, ascending, at most `limit`. */
+	readRaw(seriesId: number, from: number, toInclusive: number, limit: number, direction?: "asc" | "desc"): Promise<readonly RawPoint[]>;
+	/** The newest raw point strictly before `ts`, if any. */
+	rawBefore(seriesId: number, ts: number): Promise<RawPoint | null>;
+	upsertRollups(tier: RollupTier, rows: readonly RollupRow[]): Promise<void>;
+	readRollups(tier: RollupTier, seriesId: number, from: number, toInclusive: number, limit: number, direction?: "asc" | "desc"): Promise<readonly RollupRow[]>;
+	/** The newest rollup row of `tier` strictly before `bucketStart`, if any. */
+	rollupBefore(tier: RollupTier, seriesId: number, bucketStart: number): Promise<RollupRow | null>;
+	/** Delete one series' rows of a tier with the order column in `[lo, hiInclusive]`. */
+	deleteRange(tier: StoredTier, seriesId: number, lo: number, hiInclusive: number): Promise<number>;
+	/** Delete every row of one series, in every tier, then the series row. */
+	deleteSeries(seriesId: number): Promise<void>;
+	countRows(tier: StoredTier): Promise<number>;
+	loadOptOuts(): Promise<ReadonlySet<number>>;
+	setOptOut(deviceId: number, at: number): Promise<void>;
+	loadDepartures(): Promise<ReadonlyMap<number, number>>;
+	markMissing(deviceIds: readonly number[], at: number): Promise<void>;
+	clearMissing(deviceIds: readonly number[]): Promise<void>;
+	clearOptOut(deviceId: number): Promise<void>;
+}

package/dist/builtins/device-history/store/row-readers.d.ts

@@ -0,0 +1,11 @@
+/**
+* Typed reads of a door row. The door hands back `Record<string, unknown>`;
+* a column that is not what the schema promised is a corrupt or foreign row,
+* and a store that guessed (`Number(x ?? 0)`) would turn "unknown" into zero
+* (D393). So these throw, naming the column.
+*/
+export type RowData = Readonly<Record<string, unknown>>;
+export declare function readNumber(data: RowData, column: string): number;
+export declare function readNumberOrNull(data: RowData, column: string): number | null;
+export declare function readText(data: RowData, column: string): string;
+export declare function readTextOrNull(data: RowData, column: string): string | null;