@camstack/system 1.2.137 → 1.2.138

package/dist/builtins/device-manager/device-manager.addon.js

@@ -3949,6 +3949,112 @@ var DeviceMetaStore = class {
 	};
 };
 //#endregion
+//#region src/builtins/device-manager/fleet-read-census.ts
+/** How many stack frames identify a call site. One frame is a method; three are
+*  a cause — `listFleet < listAll < onDeviceRegistered` is the answer, `listAll`
+*  alone is not. Same choice, for the same reason, as `read-census.ts`. */
+var CENSUS_STACK_FRAMES = 3;
+function siteFromStack(stack) {
+	if (stack === void 0) return "unknown";
+	const frames = stack.split("\n").slice(1).map((line) => line.trim().replace(/^at\s+/, "")).filter((line) => line.length > 0).slice(0, CENSUS_STACK_FRAMES).map((line) => {
+		const open = line.indexOf(" (");
+		return (open > 0 ? line.slice(0, open) : line).replace(/^async\s+/, "");
+	});
+	return frames.length === 0 ? "unknown" : frames.join(" < ");
+}
+var FleetReadCensus = class FleetReadCensus {
+	/**
+	* Longest window the census may be armed for.
+	*
+	* Ten minutes covers a boot several times over and bounds what an operator
+	* pays if they set the variable and forget it. A diagnostic that can be left
+	* on becomes a tax nobody remembers enabling.
+	*/
+	static MAX_WINDOW_MS = 10 * 6e4;
+	windowMs;
+	closesAt;
+	counts = /* @__PURE__ */ new Map();
+	reported = false;
+	constructor(rawEnv, nowMs) {
+		const parsed = rawEnv === void 0 ? NaN : Number(rawEnv);
+		const valid = Number.isFinite(parsed) && parsed > 0;
+		this.windowMs = valid ? Math.min(parsed, FleetReadCensus.MAX_WINDOW_MS) : 0;
+		this.closesAt = valid ? nowMs + this.windowMs : 0;
+	}
+	get armed() {
+		return this.windowMs > 0;
+	}
+	/** Test seam: pretend the window closed. Production reads the clock. */
+	closeAt(nowMs) {
+		if (nowMs >= this.closesAt) this.forceClosed = true;
+	}
+	forceClosed = false;
+	isOpen(nowMs) {
+		if (!this.armed || this.forceClosed) return false;
+		return nowMs < this.closesAt;
+	}
+	/**
+	* Capture the caller, or `null` when the window is shut.
+	*
+	* Called at the START of a read. A read that began inside the window belongs
+	* to it even if it lands after the close — otherwise the slow reads at the
+	* edge would be attributed to nobody, and the slow ones are the interesting
+	* ones.
+	*/
+	siteOf(nowMs = Date.now()) {
+		if (!this.isOpen(nowMs)) return null;
+		const holder = {};
+		Error.captureStackTrace(holder, this.siteOf);
+		return siteFromStack(holder.stack);
+	}
+	/** Count one read at an already-captured site. A `null` site is not counted. */
+	record(site, rowCount) {
+		if (site === null) return;
+		const existing = this.counts.get(site);
+		if (existing === void 0) {
+			this.counts.set(site, {
+				site,
+				calls: 1,
+				rows: rowCount
+			});
+			return;
+		}
+		existing.calls += 1;
+		existing.rows += rowCount;
+	}
+	/** Attributed sites, busiest first. */
+	rows() {
+		return [...this.counts.values()].map((c) => ({
+			site: c.site,
+			calls: c.calls,
+			rows: c.rows
+		})).sort((a, b) => b.calls - a.calls);
+	}
+	/**
+	* Emit the report ONCE.
+	*
+	* `perMin` is included because the raw count is unreadable without the window
+	* it was taken over — "4 149" means nothing until you know it was 66 seconds.
+	*/
+	report(logger, elapsedMs) {
+		if (this.reported || !this.armed) return;
+		this.reported = true;
+		const rows = this.rows();
+		const totalCalls = rows.reduce((acc, r) => acc + r.calls, 0);
+		logger.info("fleet read census", { meta: {
+			elapsedMs,
+			sites: rows.length,
+			totalCalls,
+			rows: rows.map((r) => ({
+				site: r.site,
+				calls: r.calls,
+				rows: r.rows,
+				perMin: elapsedMs === 0 ? 0 : Math.round(r.calls * 6e4 / elapsedMs)
+			}))
+		} });
+	}
+};
+//#endregion
 //#region src/builtins/device-manager/device-row-store.ts
 /**
 * @durable class=ledger owner=device-manager
@@ -4278,9 +4384,17 @@ var DeviceRowStore = class {
 	backend;
 	logger;
 	declared = null;
-	constructor(backend, logger) {
+	/** Call-site attribution for fleet reads. Armed only by
+	*  `CAMSTACK_FLEET_READ_CENSUS_MS`; see `fleet-read-census.ts`. */
+	census;
+	constructor(backend, logger, census) {
 		this.backend = backend;
 		this.logger = logger;
+		this.census = census ?? new FleetReadCensus(process.env["CAMSTACK_FLEET_READ_CENSUS_MS"], Date.now());
+		if (this.census.armed) {
+			const startedAt = Date.now();
+			setTimeout(() => this.census.report(this.logger, Date.now() - startedAt), this.census.windowMs).unref?.();
+		}
 	}
 	/**
 	* Lazy, idempotent `declareCollection`, memoised on the PROMISE so N
@@ -4449,11 +4563,13 @@ var DeviceRowStore = class {
 	}
 	async list(filter, columns) {
 		await this.declare();
+		const site = this.census.siteOf();
 		const records = await this.backend.query({
 			collection: DEVICE_ROWS_COLLECTION,
 			filter,
 			...columns === void 0 ? {} : { columns }
 		});
+		this.census.record(site, records.length);
 		const out = [];
 		for (const record of records) {
 			const decoded = decodeDeviceRow(record.data);

package/dist/builtins/device-manager/device-manager.addon.mjs

@@ -3944,6 +3944,112 @@ var DeviceMetaStore = class {
 	};
 };
 //#endregion
+//#region src/builtins/device-manager/fleet-read-census.ts
+/** How many stack frames identify a call site. One frame is a method; three are
+*  a cause — `listFleet < listAll < onDeviceRegistered` is the answer, `listAll`
+*  alone is not. Same choice, for the same reason, as `read-census.ts`. */
+var CENSUS_STACK_FRAMES = 3;
+function siteFromStack(stack) {
+	if (stack === void 0) return "unknown";
+	const frames = stack.split("\n").slice(1).map((line) => line.trim().replace(/^at\s+/, "")).filter((line) => line.length > 0).slice(0, CENSUS_STACK_FRAMES).map((line) => {
+		const open = line.indexOf(" (");
+		return (open > 0 ? line.slice(0, open) : line).replace(/^async\s+/, "");
+	});
+	return frames.length === 0 ? "unknown" : frames.join(" < ");
+}
+var FleetReadCensus = class FleetReadCensus {
+	/**
+	* Longest window the census may be armed for.
+	*
+	* Ten minutes covers a boot several times over and bounds what an operator
+	* pays if they set the variable and forget it. A diagnostic that can be left
+	* on becomes a tax nobody remembers enabling.
+	*/
+	static MAX_WINDOW_MS = 10 * 6e4;
+	windowMs;
+	closesAt;
+	counts = /* @__PURE__ */ new Map();
+	reported = false;
+	constructor(rawEnv, nowMs) {
+		const parsed = rawEnv === void 0 ? NaN : Number(rawEnv);
+		const valid = Number.isFinite(parsed) && parsed > 0;
+		this.windowMs = valid ? Math.min(parsed, FleetReadCensus.MAX_WINDOW_MS) : 0;
+		this.closesAt = valid ? nowMs + this.windowMs : 0;
+	}
+	get armed() {
+		return this.windowMs > 0;
+	}
+	/** Test seam: pretend the window closed. Production reads the clock. */
+	closeAt(nowMs) {
+		if (nowMs >= this.closesAt) this.forceClosed = true;
+	}
+	forceClosed = false;
+	isOpen(nowMs) {
+		if (!this.armed || this.forceClosed) return false;
+		return nowMs < this.closesAt;
+	}
+	/**
+	* Capture the caller, or `null` when the window is shut.
+	*
+	* Called at the START of a read. A read that began inside the window belongs
+	* to it even if it lands after the close — otherwise the slow reads at the
+	* edge would be attributed to nobody, and the slow ones are the interesting
+	* ones.
+	*/
+	siteOf(nowMs = Date.now()) {
+		if (!this.isOpen(nowMs)) return null;
+		const holder = {};
+		Error.captureStackTrace(holder, this.siteOf);
+		return siteFromStack(holder.stack);
+	}
+	/** Count one read at an already-captured site. A `null` site is not counted. */
+	record(site, rowCount) {
+		if (site === null) return;
+		const existing = this.counts.get(site);
+		if (existing === void 0) {
+			this.counts.set(site, {
+				site,
+				calls: 1,
+				rows: rowCount
+			});
+			return;
+		}
+		existing.calls += 1;
+		existing.rows += rowCount;
+	}
+	/** Attributed sites, busiest first. */
+	rows() {
+		return [...this.counts.values()].map((c) => ({
+			site: c.site,
+			calls: c.calls,
+			rows: c.rows
+		})).sort((a, b) => b.calls - a.calls);
+	}
+	/**
+	* Emit the report ONCE.
+	*
+	* `perMin` is included because the raw count is unreadable without the window
+	* it was taken over — "4 149" means nothing until you know it was 66 seconds.
+	*/
+	report(logger, elapsedMs) {
+		if (this.reported || !this.armed) return;
+		this.reported = true;
+		const rows = this.rows();
+		const totalCalls = rows.reduce((acc, r) => acc + r.calls, 0);
+		logger.info("fleet read census", { meta: {
+			elapsedMs,
+			sites: rows.length,
+			totalCalls,
+			rows: rows.map((r) => ({
+				site: r.site,
+				calls: r.calls,
+				rows: r.rows,
+				perMin: elapsedMs === 0 ? 0 : Math.round(r.calls * 6e4 / elapsedMs)
+			}))
+		} });
+	}
+};
+//#endregion
 //#region src/builtins/device-manager/device-row-store.ts
 /**
 * @durable class=ledger owner=device-manager
@@ -4273,9 +4379,17 @@ var DeviceRowStore = class {
 	backend;
 	logger;
 	declared = null;
-	constructor(backend, logger) {
+	/** Call-site attribution for fleet reads. Armed only by
+	*  `CAMSTACK_FLEET_READ_CENSUS_MS`; see `fleet-read-census.ts`. */
+	census;
+	constructor(backend, logger, census) {
 		this.backend = backend;
 		this.logger = logger;
+		this.census = census ?? new FleetReadCensus(process.env["CAMSTACK_FLEET_READ_CENSUS_MS"], Date.now());
+		if (this.census.armed) {
+			const startedAt = Date.now();
+			setTimeout(() => this.census.report(this.logger, Date.now() - startedAt), this.census.windowMs).unref?.();
+		}
 	}
 	/**
 	* Lazy, idempotent `declareCollection`, memoised on the PROMISE so N
@@ -4444,11 +4558,13 @@ var DeviceRowStore = class {
 	}
 	async list(filter, columns) {
 		await this.declare();
+		const site = this.census.siteOf();
 		const records = await this.backend.query({
 			collection: DEVICE_ROWS_COLLECTION,
 			filter,
 			...columns === void 0 ? {} : { columns }
 		});
+		this.census.record(site, records.length);
 		const out = [];
 		for (const record of records) {
 			const decoded = decodeDeviceRow(record.data);

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

@@ -1,6 +1,7 @@
 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';
+import { FleetReadCensus } from './fleet-read-census.js';
 /**
  * @durable class=ledger owner=device-manager
  *   write="one row per device, written by `allocateDeviceId` (identity placeholder),
@@ -211,7 +212,10 @@ export declare class DeviceRowStore {
     private readonly backend;
     private readonly logger;
     private declared;
-    constructor(backend: DeviceRowBackend, logger: IScopedLogger);
+    /** Call-site attribution for fleet reads. Armed only by
+     *  `CAMSTACK_FLEET_READ_CENSUS_MS`; see `fleet-read-census.ts`. */
+    private readonly census;
+    constructor(backend: DeviceRowBackend, logger: IScopedLogger, census?: FleetReadCensus);
     /**
      * Lazy, idempotent `declareCollection`, memoised on the PROMISE so N
      * concurrent first-callers issue one declaration rather than N. A rejection

package/dist/builtins/device-manager/fleet-read-census.d.ts

@@ -0,0 +1,47 @@
+import { IScopedLogger } from '@camstack/types';
+/** One attributed call site. */
+export interface FleetCensusRow {
+    readonly site: string;
+    readonly calls: number;
+    readonly rows: number;
+}
+export declare class FleetReadCensus {
+    /**
+     * Longest window the census may be armed for.
+     *
+     * Ten minutes covers a boot several times over and bounds what an operator
+     * pays if they set the variable and forget it. A diagnostic that can be left
+     * on becomes a tax nobody remembers enabling.
+     */
+    static readonly MAX_WINDOW_MS: number;
+    readonly windowMs: number;
+    private readonly closesAt;
+    private readonly counts;
+    private reported;
+    constructor(rawEnv: string | undefined, nowMs: number);
+    get armed(): boolean;
+    /** Test seam: pretend the window closed. Production reads the clock. */
+    closeAt(nowMs: number): void;
+    private forceClosed;
+    private isOpen;
+    /**
+     * Capture the caller, or `null` when the window is shut.
+     *
+     * Called at the START of a read. A read that began inside the window belongs
+     * to it even if it lands after the close — otherwise the slow reads at the
+     * edge would be attributed to nobody, and the slow ones are the interesting
+     * ones.
+     */
+    siteOf(nowMs?: number): string | null;
+    /** Count one read at an already-captured site. A `null` site is not counted. */
+    record(site: string | null, rowCount: number): void;
+    /** Attributed sites, busiest first. */
+    rows(): readonly FleetCensusRow[];
+    /**
+     * Emit the report ONCE.
+     *
+     * `perMin` is included because the raw count is unreadable without the window
+     * it was taken over — "4 149" means nothing until you know it was 66 seconds.
+     */
+    report(logger: IScopedLogger, elapsedMs: number): void;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@camstack/system",
-  "version": "1.2.137",
+  "version": "1.2.138",
   "description": "Core addon for CamStack — builtins, pipeline, process management, auth, logging, events",
   "keywords": [
     "camstack",