@camstack/system 1.2.455 → 1.2.457

package/dist/builtins/storage-orchestrator/storage-orchestrator.addon.mjs

@@ -1,4 +1,4 @@
-import { $i as normalizeNodeId, Ar as withLocationMode, En as legacyModeOf, G as LegacyStorageLocationDefaultSchema, Li as defineRecordKinds, Ln as modeMayWrite, Nn as mayReadLocation, Pn as mayWriteToLocation, _r as storageCapability, at as StorageCleanupJobSchema, ct as StorageMigrationJobSchema, da as secretTreeFromPaths, dn as gbToBytes, dr as settingsStoreCapability, ga as transformSecretWrite, ir as resolveLocationMode, ki as collectSecretConfigKeys, la as resolveSecretMarkers, ot as StorageLocationModeSchema, qi as isSecretMarker, qr as BaseAddon, rn as evictionPolicyOfLocation, st as StorageLocationTypeSchema, ta as parseJsonObject, ui as REDACTED_SECRET, vr as storageMigrationCapability, ya as EventCategory, yn as isLocationEnabled } from "../../dist-BpSENkRJ.mjs";
+import { Dr as storageMigrationCapability, Er as storageCapability, Fn as legacyModeOf, Hn as mayReadLocation, Ki as defineRecordKinds, Kn as modeMayWrite, Oa as EventCategory, On as isLocationEnabled, Ri as collectSecretConfigKeys, Ta as transformSecretWrite, Un as mayWriteToLocation, ba as secretTreeFromPaths, br as settingsStoreCapability, ca as normalizeNodeId, dn as evictionPolicyOfLocation, ft as StorageCleanupJobSchema, ht as StorageMigrationJobSchema, mt as StorageLocationTypeSchema, na as isSecretMarker, ni as BaseAddon, pr as resolveLocationMode, pt as StorageLocationModeSchema, q as LegacyStorageLocationDefaultSchema, ua as parseJsonObject, va as resolveSecretMarkers, yi as REDACTED_SECRET, yn as gbToBytes, zr as withLocationMode } from "../../dist-Dhux90yB.mjs";
 import { t as require_read_all_rows } from "../../read-all-rows-TaPqdWNF.mjs";
 import { z } from "zod";
 import { randomUUID } from "node:crypto";
@@ -3952,6 +3952,107 @@ var StorageLocationBandMonitor = class {
 	}
 };
 //#endregion
+//#region src/builtins/storage-orchestrator/location-history-recorder.ts
+var LOCATION_HISTORY_NAMES = {
+	usedPercent: "location-used-percent",
+	freeBytes: "location-free-bytes",
+	ownedBytes: "location-owned-bytes"
+};
+var DECLARATIONS = [
+	{
+		name: LOCATION_HISTORY_NAMES.usedPercent,
+		displayName: "Location volume used %",
+		unit: "%"
+	},
+	{
+		name: LOCATION_HISTORY_NAMES.freeBytes,
+		displayName: "Location volume free",
+		unit: "bytes"
+	},
+	{
+		name: LOCATION_HISTORY_NAMES.ownedBytes,
+		displayName: "Location held by CamStack",
+		unit: "bytes"
+	}
+];
+var LocationHistoryRecorder = class {
+	deps;
+	keys = /* @__PURE__ */ new Map();
+	lastAt = /* @__PURE__ */ new Map();
+	constructor(deps) {
+		this.deps = deps;
+	}
+	async ensureDeclared() {
+		if (this.keys.size === DECLARATIONS.length) return true;
+		try {
+			for (const d of DECLARATIONS) {
+				const { key } = await this.deps.deviceHistory.declareSeries({
+					name: d.name,
+					subjectKind: "node",
+					kind: "gauge",
+					displayName: d.displayName,
+					ingest: "points",
+					unit: d.unit
+				});
+				this.keys.set(d.name, key);
+			}
+			return true;
+		} catch (err) {
+			this.keys.clear();
+			this.deps.logger.warn("storage: location history declare failed — retried next sweep", { meta: { error: err instanceof Error ? err.message : String(err) } });
+			return false;
+		}
+	}
+	/** The points of one sweep; pure apart from the per-location rate memory. */
+	pointsOf(readings, at) {
+		const points = [];
+		for (const r of readings) {
+			const last = this.lastAt.get(r.locationId);
+			if (last !== void 0 && at >= last && at - last < 6e4) continue;
+			const add = (name, value) => {
+				const key = this.keys.get(name);
+				if (key === void 0 || !Number.isFinite(value)) return;
+				points.push({
+					key,
+					subject: {
+						kind: "node",
+						nodeId: r.nodeId
+					},
+					scope: r.locationId,
+					ts: at,
+					value
+				});
+			};
+			const before = points.length;
+			if (r.capacity !== null && r.capacity.totalBytes > 0) {
+				const used = r.capacity.totalBytes - r.capacity.availableBytes;
+				add(LOCATION_HISTORY_NAMES.usedPercent, Math.round(used / r.capacity.totalBytes * 1e3) / 10);
+				add(LOCATION_HISTORY_NAMES.freeBytes, r.capacity.availableBytes);
+			}
+			if (r.ownedBytes !== void 0) add(LOCATION_HISTORY_NAMES.ownedBytes, r.ownedBytes);
+			if (points.length > before) this.lastAt.set(r.locationId, at);
+		}
+		return points;
+	}
+	async record(readings, at) {
+		if (readings.length === 0 || !await this.ensureDeclared()) return;
+		const points = this.pointsOf(readings, at);
+		if (points.length === 0) return;
+		try {
+			const result = await this.deps.deviceHistory.record({ points });
+			if (result.refused.length > 0) {
+				if (result.refused.some((r) => r.reason === "undeclared")) this.keys.clear();
+				this.deps.logger.warn("storage: location history points refused", { meta: {
+					accepted: result.accepted,
+					refused: result.refused
+				} });
+			}
+		} catch (err) {
+			this.deps.logger.warn("storage: location history not stored", { meta: { error: err instanceof Error ? err.message : String(err) } });
+		}
+	}
+};
+//#endregion
 //#region src/builtins/storage-orchestrator/storage-orchestrator.addon.ts
 /**
 * `storage-orchestrator` builtin — singleton owner of the consumer-
@@ -4019,6 +4120,9 @@ var StorageOrchestratorAddon = class extends BaseAddon {
 		return this.occupancySlice;
 	}
 	pressureTimer = null;
+	/** Occupancy over time (device-history). Created with the timer that feeds it. */
+	locationHistory = null;
+	locationHistoryInFlight = false;
 	pressureSweepInFlight = false;
 	migration = null;
 	/** Guards every single-location repoint and arbitrates movers per physical root. */
@@ -4435,8 +4539,16 @@ var StorageOrchestratorAddon = class extends BaseAddon {
 				}
 			}
 		});
+		this.locationHistory = new LocationHistoryRecorder({
+			deviceHistory: {
+				declareSeries: (input) => this.ctx.api.deviceHistory.declareSeries.mutate(input),
+				record: (input) => this.ctx.api.deviceHistory.record.mutate({ points: [...input.points] })
+			},
+			logger: this.ctx.logger
+		});
 		this.pressureTimer = setInterval(() => {
 			this.runPressureSweep();
+			this.recordLocationHistory();
 		}, PRESSURE_SWEEP_INTERVAL_MS);
 		this.ctx.logger.info("Storage orchestrator initialized");
 		return [
@@ -4583,6 +4695,37 @@ var StorageOrchestratorAddon = class extends BaseAddon {
 		}
 	}
 	/**
+	* One occupancy reading per location this node can read, into device-history.
+	* The volume figures come from the same probe `listLocations` serves, the
+	* held bytes from the occupancy slice; an unknown figure is no point (D393).
+	*/
+	async recordLocationHistory() {
+		const svc = this.service;
+		const recorder = this.locationHistory;
+		if (!svc || !recorder || this.locationHistoryInFlight) return;
+		this.locationHistoryInFlight = true;
+		try {
+			this.occupancy.serveAndRevalidate();
+			const localNode = svc.getLocalNodeId();
+			const readings = [];
+			for (const loc of svc.listLocations()) {
+				if (!mayReadLocation(loc) || (loc.nodeId ?? HUB_NODE_ID) !== localNode) continue;
+				const capacity = await this.localCapacityOf(loc).catch(() => null);
+				readings.push({
+					locationId: loc.id,
+					nodeId: localNode,
+					capacity,
+					ownedBytes: this.occupancy.ownedFor(loc.id)?.bytes
+				});
+			}
+			await recorder.record(readings, Date.now());
+		} catch (err) {
+			this.ctxIfReady?.logger.warn("storage: location history pass failed", { meta: { error: err instanceof Error ? err.message : String(err) } });
+		} finally {
+			this.locationHistoryInFlight = false;
+		}
+	}
+	/**
 	* Sample free space for every managed location and emit NC band edges.
 	* A failed capacity read stays `null` and changes no band — never folded to 0 (D393).
 	*/

package/dist/builtins/system-config/system-config.addon.js

@@ -3,11 +3,11 @@ Object.defineProperties(exports, {
 	[Symbol.toStringTag]: { value: "Module" }
 });
 const require_chunk = require("../../chunk-Cek0wNdY.js");
-const require_dist = require("../../dist-DjQ8C-ku.js");
+const require_dist = require("../../dist-C89nqNnn.js");
 const require_safe_buffer$1 = require("../../safe-buffer-D3aoa-7X.js");
 const require_x509_es = require("../../x509.es-C4cOo48M.js");
-const require_constants$8 = require("../../constants-DruwCkfp.js");
-const require_agent_https = require("../../agent-https-CCvlRQKV.js");
+const require_constants$8 = require("../../constants-B_X9cWEK.js");
+const require_agent_https = require("../../agent-https-CoyOZ3pC.js");
 const require_src$1 = require("../../src-CnAqG6EF.js");
 let zod = require("zod");
 let node_crypto = require("node:crypto");

package/dist/builtins/system-config/system-config.addon.mjs

@@ -1,9 +1,9 @@
 import { a as __toCommonJS, i as __require, n as __esmMin, o as __toESM, r as __exportAll, t as __commonJSMin } from "../../chunk-CNf5ZN-e.mjs";
-import { Hi as hydrateSchema, Ii as defineCustomActions, Kr as errMsg, Pi as customAction, fr as shortHostname, qr as BaseAddon, rt as ServerNameSchema } from "../../dist-BpSENkRJ.mjs";
+import { Gi as defineCustomActions, Ui as customAction, Zi as hydrateSchema, ni as BaseAddon, ti as errMsg, ut as ServerNameSchema, xr as shortHostname } from "../../dist-Dhux90yB.mjs";
 import { t as require_safe_buffer } from "../../safe-buffer-B1OjL1I9.mjs";
 import { c as Pkcs10CertificateRequest } from "../../x509.es-DK__ETIe.mjs";
-import { a as MESH_CA_KEY_REF, i as MESH_CA_FIELD, n as DEFAULT_HUB_TLS_TCP_PORT, o as MESH_CA_SETTINGS_KEY } from "../../constants-DOlYt1t1.mjs";
-import { $ as generateMeshKeyPair, B as systemConfigRecordKinds, F as AGENT_HTTPS_NAMES_COLLECTION, G as describeMeshLeaf, H as MESH_NODE_CERTIFICATES_COLUMNS, I as AGENT_HTTPS_NAMES_COLUMNS, L as AgentHttpsNames, Q as generateMeshCa, R as getProcessAgentHttpsNames, U as MeshCertificateRegistry, V as MESH_NODE_CERTIFICATES_COLLECTION, X as createMeshCsrPem, Y as caFingerprintCompact, Z as exportMeshPrivateKeyPem, et as isValidAgentNodeId, it as subjectCn, j as isLocalOnlyHostname, nt as issueMeshLeafFromCsr, q as setProcessMeshCertificateRegistry, rt as loadMeshCa, tt as issueMeshLeafForNode, u as isPrivateAddress, z as setProcessAgentHttpsNames } from "../../agent-https-CLWrOO3o.mjs";
+import { a as MESH_CA_KEY_REF, i as MESH_CA_FIELD, n as DEFAULT_HUB_TLS_TCP_PORT, o as MESH_CA_SETTINGS_KEY } from "../../constants-cxKcZRMi.mjs";
+import { $ as generateMeshCa, B as setProcessAgentHttpsNames, H as MESH_NODE_CERTIFICATES_COLLECTION, I as AGENT_HTTPS_NAMES_COLLECTION, J as setProcessMeshCertificateRegistry, K as describeMeshLeaf, L as AGENT_HTTPS_NAMES_COLUMNS, M as isLocalOnlyHostname, Q as exportMeshPrivateKeyPem, R as AgentHttpsNames, U as MESH_NODE_CERTIFICATES_COLUMNS, V as systemConfigRecordKinds, W as MeshCertificateRegistry, X as caFingerprintCompact, Z as createMeshCsrPem, at as subjectCn, et as generateMeshKeyPair, it as loadMeshCa, nt as issueMeshLeafForNode, rt as issueMeshLeafFromCsr, tt as isValidAgentNodeId, u as isPrivateAddress, z as getProcessAgentHttpsNames } from "../../agent-https-CK9Z4sSR.mjs";
 import { t as require_src } from "../../src-hG4grMU4.mjs";
 import { z } from "zod";
 import { X509Certificate, createHash, createPrivateKey, randomBytes, randomInt, sign, timingSafeEqual, verify, webcrypto } from "node:crypto";

package/dist/builtins/winston-logging/index.js

@@ -3,14 +3,132 @@ Object.defineProperties(exports, {
 	[Symbol.toStringTag]: { value: "Module" }
 });
 const require_chunk = require("../../chunk-Cek0wNdY.js");
-const require_dist = require("../../dist-DjQ8C-ku.js");
+const require_dist = require("../../dist-C89nqNnn.js");
 const require_formatter = require("../../formatter-DqAKDlvN.js");
+const require_log_file_read_protocol = require("../../log-file-read-protocol-D0WcLbIV.js");
 let node_path = require("node:path");
 node_path = require_chunk.__toESM(node_path);
+let node_module = require("node:module");
+let node_worker_threads = require("node:worker_threads");
 let winston = require("winston");
 winston = require_chunk.__toESM(winston);
 let winston_daily_rotate_file = require("winston-daily-rotate-file");
 winston_daily_rotate_file = require_chunk.__toESM(winston_daily_rotate_file);
+//#region src/builtins/winston-logging/log-file-read-client.ts
+/**
+* The parent side of the rotated-file reader thread (D898).
+*
+* The thread is spawned on the first read, not at boot: a hub nobody reads
+* logs on pays nothing but the background index pass, which starts with the
+* thread. A thread that dies fails its in-flight reads and is respawned on
+* the next one.
+*/
+/** `dist/log-file-read-worker.js` at the package root, found through its own `package.json`. */
+function defaultReaderWorkerPath() {
+	const require_ = (0, node_module.createRequire)(require("url").pathToFileURL(__filename).href);
+	const packageRoot = node_path.dirname(require_.resolve("@camstack/system/package.json"));
+	return node_path.join(packageRoot, "dist", "log-file-read-worker.js");
+}
+var LogFileReadClient = class {
+	logsDir;
+	backgroundPassMs;
+	spawn;
+	worker = null;
+	nextId = 1;
+	pending = /* @__PURE__ */ new Map();
+	local;
+	constructor(options) {
+		this.logsDir = options.logsDir;
+		this.backgroundPassMs = options.backgroundPassMs ?? 6e4;
+		if (options.inProcess === true) {
+			this.spawn = null;
+			this.local = {
+				store: new require_log_file_read_protocol.LogFileIndexStore(options.logsDir),
+				cancels: new require_log_file_read_protocol.CancelBook()
+			};
+			return;
+		}
+		this.local = null;
+		const workerPath = options.workerPath ?? defaultReaderWorkerPath();
+		const execArgv = options.workerExecArgv;
+		this.spawn = options.workerFactory ?? ((workerData) => new node_worker_threads.Worker(workerPath, {
+			workerData,
+			...execArgv !== void 0 ? { execArgv: [...execArgv] } : {}
+		}));
+	}
+	async read(query) {
+		if (this.local !== null) return (await require_log_file_read_protocol.serveRead(this.logsDir, this.local.store, this.local.cancels, query)).result;
+		const worker = this.ensureWorker();
+		const id = this.nextId++;
+		return new Promise((resolve, reject) => {
+			this.pending.set(id, {
+				resolve,
+				reject
+			});
+			worker.postMessage({
+				type: "read",
+				id,
+				query
+			});
+		});
+	}
+	/**
+	* Start the thread now, so its background pass indexes the existing files
+	* before anyone reads them. The hub calls this; an agent, whose files
+	* nobody reads, leaves the thread unstarted.
+	*/
+	warm() {
+		if (this.local === null) this.ensureWorker();
+	}
+	cancel(requestId) {
+		if (this.local !== null) {
+			this.local.cancels.cancel(requestId);
+			return true;
+		}
+		if (this.worker === null) return false;
+		this.worker.postMessage({
+			type: "cancel",
+			requestId
+		});
+		return true;
+	}
+	stop() {
+		this.worker?.postMessage({ type: "stop" });
+		this.worker = null;
+		this.failAll(/* @__PURE__ */ new Error("log reader stopped"));
+	}
+	ensureWorker() {
+		if (this.worker !== null) return this.worker;
+		if (this.spawn === null) throw new Error("log reader has no worker factory");
+		const worker = this.spawn({
+			logsDir: this.logsDir,
+			backgroundPassMs: this.backgroundPassMs
+		});
+		worker.unref?.();
+		worker.on("message", (message) => {
+			if (!require_log_file_read_protocol.isFromReader(message)) return;
+			const waiter = this.pending.get(message.id);
+			if (waiter === void 0) return;
+			this.pending.delete(message.id);
+			if (message.type === "result") waiter.resolve(message.result);
+			else waiter.reject(new Error(message.message));
+		});
+		worker.on("error", (err) => {
+			this.failAll(err instanceof Error ? err : new Error(String(err)));
+		});
+		worker.on("exit", () => {
+			if (this.worker === worker) this.worker = null;
+			this.failAll(/* @__PURE__ */ new Error("log reader thread exited"));
+		});
+		this.worker = worker;
+		return worker;
+	}
+	failAll(error) {
+		for (const waiter of this.pending.values()) waiter.reject(error);
+		this.pending.clear();
+	}
+};
+//#endregion
 //#region src/builtins/winston-logging/winston-destination.ts
 /**
 * Rotated-file log destination. Console output goes through the shared
@@ -19,9 +137,24 @@ winston_daily_rotate_file = require_chunk.__toESM(winston_daily_rotate_file);
 * structured JSON shape so log tooling can query tags/meta.
 */
 var WinstonDestination = class {
+	readerOptions;
 	logger = null;
+	reader = null;
+	retentionDays = 30;
+	/**
+	* `readerOptions` reaches the history reader (D898) — a spec runs it in
+	* process or points the thread at the TypeScript source.
+	*/
+	constructor(readerOptions = {}) {
+		this.readerOptions = readerOptions;
+	}
 	async initialize(config) {
 		const { level = "info", retentionDays = 30, logsDir = node_path.join("camstack-data", "logs") } = config ?? {};
+		this.retentionDays = retentionDays;
+		this.reader = new LogFileReadClient({
+			...this.readerOptions,
+			logsDir
+		});
 		winston.format.printf((info) => {
 			const rendered = info._rendered;
 			return typeof rendered === "string" ? rendered : String(info.message);
@@ -47,6 +180,7 @@ var WinstonDestination = class {
 		const ts = entry.timestamp instanceof Date ? entry.timestamp.toISOString() : String(entry.timestamp);
 		const rendered = require_formatter.formatLogLine(entry, { colorize: true });
 		this.logger.log({
+			...entry.id !== void 0 ? { id: entry.id } : {},
 			level: entry.level,
 			message: entry.message,
 			_rendered: rendered,
@@ -56,10 +190,37 @@ var WinstonDestination = class {
 			...entry.meta ? { meta: entry.meta } : {}
 		});
 	}
-	async query(_filter) {
-		return [];
+	/** The rotated files ARE the hub's history (D898): every filter is applied here. */
+	async describeRead() {
+		return {
+			readable: this.reader !== null,
+			reason: this.reader !== null ? null : "Not initialized",
+			filters: {
+				deviceId: true,
+				addonId: true,
+				nodeId: true,
+				tags: true,
+				level: true,
+				text: true,
+				timeRange: true
+			},
+			retentionDays: this.retentionDays
+		};
+	}
+	/** Index the existing files in the background now (the hub's history). */
+	startBackgroundIndexing() {
+		this.reader?.warm();
+	}
+	async read(query) {
+		if (this.reader === null) throw new Error("winston-logging: not initialized");
+		return this.reader.read(query);
+	}
+	async cancelRead(input) {
+		return { cancelled: this.reader?.cancel(input.requestId) ?? false };
 	}
 	async shutdown() {
+		this.reader?.stop();
+		this.reader = null;
 		if (!this.logger) return;
 		await new Promise((resolve) => {
 			this.logger.on("finish", resolve);
@@ -89,6 +250,7 @@ var WinstonLoggingAddon = class extends require_dist.BaseAddon {
 			...this.config,
 			logsDir
 		});
+		if (this.ctx.kernel.localNodeId === "hub") this.destination.startBackgroundIndexing();
 		this.ctx.logger.info("Winston logging initialized");
 		return [{
 			capability: require_dist.logDestinationCapability,

package/dist/builtins/winston-logging/index.mjs

@@ -1,9 +1,127 @@
-import { An as logDestinationCapability, qr as BaseAddon } from "../../dist-BpSENkRJ.mjs";
+import { ni as BaseAddon, zn as logDestinationCapability } from "../../dist-Dhux90yB.mjs";
 import { t as formatLogLine } from "../../formatter-B7qW8bPJ.mjs";
+import { a as LogFileIndexStore, i as serveRead, n as isFromReader, t as CancelBook } from "../../log-file-read-protocol-B7M3X3bT.mjs";
+import { createRequire } from "node:module";
 import * as path$1 from "node:path";
 import path from "node:path";
+import { Worker } from "node:worker_threads";
 import * as winston from "winston";
 import DailyRotateFile from "winston-daily-rotate-file";
+//#region src/builtins/winston-logging/log-file-read-client.ts
+/**
+* The parent side of the rotated-file reader thread (D898).
+*
+* The thread is spawned on the first read, not at boot: a hub nobody reads
+* logs on pays nothing but the background index pass, which starts with the
+* thread. A thread that dies fails its in-flight reads and is respawned on
+* the next one.
+*/
+/** `dist/log-file-read-worker.js` at the package root, found through its own `package.json`. */
+function defaultReaderWorkerPath() {
+	const require_ = createRequire(import.meta.url);
+	const packageRoot = path$1.dirname(require_.resolve("@camstack/system/package.json"));
+	return path$1.join(packageRoot, "dist", "log-file-read-worker.js");
+}
+var LogFileReadClient = class {
+	logsDir;
+	backgroundPassMs;
+	spawn;
+	worker = null;
+	nextId = 1;
+	pending = /* @__PURE__ */ new Map();
+	local;
+	constructor(options) {
+		this.logsDir = options.logsDir;
+		this.backgroundPassMs = options.backgroundPassMs ?? 6e4;
+		if (options.inProcess === true) {
+			this.spawn = null;
+			this.local = {
+				store: new LogFileIndexStore(options.logsDir),
+				cancels: new CancelBook()
+			};
+			return;
+		}
+		this.local = null;
+		const workerPath = options.workerPath ?? defaultReaderWorkerPath();
+		const execArgv = options.workerExecArgv;
+		this.spawn = options.workerFactory ?? ((workerData) => new Worker(workerPath, {
+			workerData,
+			...execArgv !== void 0 ? { execArgv: [...execArgv] } : {}
+		}));
+	}
+	async read(query) {
+		if (this.local !== null) return (await serveRead(this.logsDir, this.local.store, this.local.cancels, query)).result;
+		const worker = this.ensureWorker();
+		const id = this.nextId++;
+		return new Promise((resolve, reject) => {
+			this.pending.set(id, {
+				resolve,
+				reject
+			});
+			worker.postMessage({
+				type: "read",
+				id,
+				query
+			});
+		});
+	}
+	/**
+	* Start the thread now, so its background pass indexes the existing files
+	* before anyone reads them. The hub calls this; an agent, whose files
+	* nobody reads, leaves the thread unstarted.
+	*/
+	warm() {
+		if (this.local === null) this.ensureWorker();
+	}
+	cancel(requestId) {
+		if (this.local !== null) {
+			this.local.cancels.cancel(requestId);
+			return true;
+		}
+		if (this.worker === null) return false;
+		this.worker.postMessage({
+			type: "cancel",
+			requestId
+		});
+		return true;
+	}
+	stop() {
+		this.worker?.postMessage({ type: "stop" });
+		this.worker = null;
+		this.failAll(/* @__PURE__ */ new Error("log reader stopped"));
+	}
+	ensureWorker() {
+		if (this.worker !== null) return this.worker;
+		if (this.spawn === null) throw new Error("log reader has no worker factory");
+		const worker = this.spawn({
+			logsDir: this.logsDir,
+			backgroundPassMs: this.backgroundPassMs
+		});
+		worker.unref?.();
+		worker.on("message", (message) => {
+			if (!isFromReader(message)) return;
+			const waiter = this.pending.get(message.id);
+			if (waiter === void 0) return;
+			this.pending.delete(message.id);
+			if (message.type === "result") waiter.resolve(message.result);
+			else waiter.reject(new Error(message.message));
+		});
+		worker.on("error", (err) => {
+			this.failAll(err instanceof Error ? err : new Error(String(err)));
+		});
+		worker.on("exit", () => {
+			if (this.worker === worker) this.worker = null;
+			this.failAll(/* @__PURE__ */ new Error("log reader thread exited"));
+		});
+		this.worker = worker;
+		return worker;
+	}
+	failAll(error) {
+		for (const waiter of this.pending.values()) waiter.reject(error);
+		this.pending.clear();
+	}
+};
+//#endregion
 //#region src/builtins/winston-logging/winston-destination.ts
 /**
 * Rotated-file log destination. Console output goes through the shared
@@ -12,9 +130,24 @@ import DailyRotateFile from "winston-daily-rotate-file";
 * structured JSON shape so log tooling can query tags/meta.
 */
 var WinstonDestination = class {
+	readerOptions;
 	logger = null;
+	reader = null;
+	retentionDays = 30;
+	/**
+	* `readerOptions` reaches the history reader (D898) — a spec runs it in
+	* process or points the thread at the TypeScript source.
+	*/
+	constructor(readerOptions = {}) {
+		this.readerOptions = readerOptions;
+	}
 	async initialize(config) {
 		const { level = "info", retentionDays = 30, logsDir = path$1.join("camstack-data", "logs") } = config ?? {};
+		this.retentionDays = retentionDays;
+		this.reader = new LogFileReadClient({
+			...this.readerOptions,
+			logsDir
+		});
 		winston.format.printf((info) => {
 			const rendered = info._rendered;
 			return typeof rendered === "string" ? rendered : String(info.message);
@@ -40,6 +173,7 @@ var WinstonDestination = class {
 		const ts = entry.timestamp instanceof Date ? entry.timestamp.toISOString() : String(entry.timestamp);
 		const rendered = formatLogLine(entry, { colorize: true });
 		this.logger.log({
+			...entry.id !== void 0 ? { id: entry.id } : {},
 			level: entry.level,
 			message: entry.message,
 			_rendered: rendered,
@@ -49,10 +183,37 @@ var WinstonDestination = class {
 			...entry.meta ? { meta: entry.meta } : {}
 		});
 	}
-	async query(_filter) {
-		return [];
+	/** The rotated files ARE the hub's history (D898): every filter is applied here. */
+	async describeRead() {
+		return {
+			readable: this.reader !== null,
+			reason: this.reader !== null ? null : "Not initialized",
+			filters: {
+				deviceId: true,
+				addonId: true,
+				nodeId: true,
+				tags: true,
+				level: true,
+				text: true,
+				timeRange: true
+			},
+			retentionDays: this.retentionDays
+		};
+	}
+	/** Index the existing files in the background now (the hub's history). */
+	startBackgroundIndexing() {
+		this.reader?.warm();
+	}
+	async read(query) {
+		if (this.reader === null) throw new Error("winston-logging: not initialized");
+		return this.reader.read(query);
+	}
+	async cancelRead(input) {
+		return { cancelled: this.reader?.cancel(input.requestId) ?? false };
 	}
 	async shutdown() {
+		this.reader?.stop();
+		this.reader = null;
 		if (!this.logger) return;
 		await new Promise((resolve) => {
 			this.logger.on("finish", resolve);
@@ -82,6 +243,7 @@ var WinstonLoggingAddon = class extends BaseAddon {
 			...this.config,
 			logsDir
 		});
+		if (this.ctx.kernel.localNodeId === "hub") this.destination.startBackgroundIndexing();
 		this.ctx.logger.info("Winston logging initialized");
 		return [{
 			capability: logDestinationCapability,

package/dist/builtins/winston-logging/log-file-cursor.d.ts

@@ -0,0 +1,12 @@
+/** `camstack-YYYY-MM-DD.log`, as `winston-daily-rotate-file` names them. */
+export declare const LOG_FILE_NAME_RE: RegExp;
+/** A position in one daily file. */
+export interface FileCursor {
+	/** The daily file's name (never a path). */
+	readonly f: string;
+	/** A line-start byte offset in that file. */
+	readonly o: number;
+}
+export declare function encodeFileCursor(cursor: FileCursor): string;
+/** Null for anything this provider did not mint. */
+export declare function decodeFileCursor(raw: string): FileCursor | null;

package/dist/builtins/winston-logging/log-file-index-store.d.ts

@@ -0,0 +1,11 @@
+import { type FileIndex } from "./log-file-index.js";
+export declare class LogFileIndexStore {
+	private readonly logsDir;
+	private readonly files;
+	constructor(logsDir: string);
+	indexOf(fileName: string, opts?: {
+		readonly wait?: boolean;
+	}): Promise<FileIndex | null>;
+	/** Index everything, newest first; drop orphaned sidecars. */
+	backgroundPass(shouldStop: () => boolean): Promise<void>;
+}