@camstack/system 1.2.455 → 1.2.457

package/dist/builtins/local-auth/preferences-record-kinds.d.ts

@@ -0,0 +1,27 @@
+/**
+* The per-user account preferences kind (D894), owned by `local-auth` because
+* it owns the users the rows belong to — a user's delete wipes them in the
+* same call (`endAllAccess`).
+*
+* Declared on its OWN, never folded into `localAuthRecordKinds`: that map is
+* the phase-6 adoption set, and a kind missing from the catalog there sends
+* the whole auth builtin back to its legacy tables.
+*/
+import { type DefinedRecordKind, type PreferenceValue } from "@camstack/types";
+import { z } from "zod";
+/** One `(user, namespace)` row. The record id is {@link userPreferenceRecordId}. */
+export type UserPreferenceBody = {
+	readonly userId: string;
+	readonly namespace: string;
+	readonly value: PreferenceValue;
+	readonly revision: number;
+	readonly updatedAt: number;
+	readonly updatedByDevice: string | null;
+};
+export declare const UserPreferenceBodySchema: z.ZodType<UserPreferenceBody>;
+export type LocalAuthPreferencesRecordKindsMap = {
+	readonly "user-preferences": DefinedRecordKind<z.ZodType<UserPreferenceBody>>;
+};
+export declare const localAuthPreferencesRecordKinds: LocalAuthPreferencesRecordKindsMap;
+/** Namespaces cannot hold `:`, so the id splits unambiguously. */
+export declare function userPreferenceRecordId(userId: string, namespace: string): string;

package/dist/builtins/local-auth/record-kinds.d.ts

@@ -5,7 +5,10 @@
 * use `storageAdmin.dropCollection` with `expectRows` after verify (see
 * `docs/design/records-phase-6-auth-migration.md`).
 *
-* Before hub restart: mint and test an admin token (`csa_`); snapshot every kind.
+* Before hub restart: mint and test an admin token (`auth.mintToken` with `'*'`); snapshot every kind.
+*
+* `scoped-tokens` and `admin-tokens` hold pre-D892 rows read by nothing since
+* D895; they stay declared so the layout is unchanged.
 */
 import { ApiKeyRecordSchema, type DefinedRecordKind, type RecordKindHandle, type RecordsAccess, ScopedTokenSchema, TokenScopeSchema, UserRecordSchema } from "@camstack/types";
 import { z } from "zod";
@@ -128,8 +131,6 @@ export declare const LOCAL_AUTH_RECORDS_LEGACY_COLLECTIONS: readonly string[];
 export interface LocalAuthRecordStores {
 	readonly users: RecordKindHandle<UserBody>;
 	readonly apiKeys: RecordKindHandle<ApiKeyBody>;
-	readonly scopedTokens: RecordKindHandle<ScopedTokenBody>;
-	readonly adminTokens: RecordKindHandle<AdminTokenBody>;
 	readonly loginSessions: RecordKindHandle<LoginSessionBody>;
 	readonly loginSessionCutoffs: RecordKindHandle<LoginSessionCutoffBody>;
 	readonly oauthSessions: RecordKindHandle<OauthSessionBody>;

package/dist/builtins/local-auth/user-preferences-store.d.ts

@@ -0,0 +1,56 @@
+/**
+* Per-user account preferences (D894): one row per `(userId, namespace)`.
+*
+* Every method takes the OWNER's id as its first argument and touches only
+* that user's rows; the hub router stamps it from the principal, and nothing
+* here accepts a second user id.
+*
+* The poll (`changedSince`) is answered from an in-memory mirror of each
+* user's `namespace → revision`, loaded once on first touch. This store is the
+* kind's only writer (one in-process instance in `local-auth`), so the mirror
+* cannot fall behind the rows; a poll that finds nothing changed reads no row.
+* Writes of one user are serialized, so a read-modify-write never interleaves.
+*/
+import { type PreferenceRow, type PreferencesChangedSinceOutput, type PreferencesPutInput, type PreferencesPutOutput, type RecordKindHandle } from "@camstack/types";
+import { type UserPreferenceBody } from "./preferences-record-kinds.js";
+export type PreferencesLimitReason = "value-too-large" | "too-many-namespaces";
+/** A write the limits refuse; nothing was stored. */
+export declare class PreferencesLimitError extends Error {
+	readonly reason: PreferencesLimitReason;
+	constructor(reason: PreferencesLimitReason, message: string);
+}
+/**
+* The limit refusal behind `error`, or `null`. By name and field, not
+* `instanceof`: the store and its caller may load different copies of this
+* module.
+*/
+export declare function preferencesLimitReasonOf(error: unknown): PreferencesLimitReason | null;
+export interface UserPreferencesStoreOptions {
+	readonly now?: () => number;
+}
+export declare class UserPreferencesStore {
+	private readonly kind;
+	private readonly now;
+	/** `userId → namespace → revision`; absent until the user is first touched. */
+	private readonly mirrors;
+	private readonly locks;
+	constructor(kind: RecordKindHandle<UserPreferenceBody>, options?: UserPreferencesStoreOptions);
+	/** The caller's rows; `namespaces` narrows them (unknown ones are simply absent). */
+	get(userId: string, namespaces?: readonly string[]): Promise<readonly PreferenceRow[]>;
+	put(userId: string, input: PreferencesPutInput): Promise<PreferencesPutOutput>;
+	/** `false` when the namespace did not exist. */
+	delete(userId: string, namespace: string): Promise<boolean>;
+	/**
+	* What the client is missing: every row whose revision differs from the one
+	* it holds (or that it does not list), and every listed namespace now gone.
+	*/
+	changedSince(userId: string, known: Readonly<Record<string, number>>): Promise<PreferencesChangedSinceOutput>;
+	/** Every row of `userId` goes (user delete). Returns how many. */
+	wipeUser(userId: string): Promise<number>;
+	/** Rows whose user is not in `liveUserIds` go (boot sweep). Returns how many. */
+	wipeOrphans(liveUserIds: ReadonlySet<string>): Promise<number>;
+	private mirrorOf;
+	private scanUser;
+	/** Run `task` after every earlier write of the same user has settled. */
+	private serialized;
+}

package/dist/builtins/local-network/local-network.addon.d.ts

@@ -164,6 +164,14 @@ export declare class LocalNetworkAddon extends BaseAddon<LocalNetworkConfig> {
 	private reconcileMeshEndpoint;
 	private resolvedHttpPort;
 	private tlsDataDir;
+	/**
+	* The hub's name (D861) for a local root this action may CREATE (an existing root is
+	* never renamed). Hub only: on an agent the hub's name would mislabel the agent's own
+	* material, so it gets the plain name. A failed read falls back to the machine
+	* hostname (what the hub shows when unnamed) and says so: a certificate action must
+	* not fail over a label.
+	*/
+	private caHubName;
 	private snapshotTls;
 	/**
 	* Hot-swap the HTTPS listener onto the pair now on disk. A failure is not

package/dist/builtins/local-network/local-network.addon.js

@@ -1,7 +1,7 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const require_chunk = require("../../chunk-Cek0wNdY.js");
-const require_dist = require("../../dist-DjQ8C-ku.js");
-const require_hub_mdns_ciao = require("../../hub-mdns-ciao-Bkrvgnma.js");
+const require_dist = require("../../dist-C89nqNnn.js");
+const require_hub_mdns_ciao = require("../../hub-mdns-ciao-DB1Y9agt.js");
 let zod = require("zod");
 let node_net = require("node:net");
 let node_os = require("node:os");
@@ -887,7 +887,10 @@ var LocalNetworkAddon = class extends require_dist.BaseAddon {
 			getTlsStatus: async () => this.snapshotTls(),
 			regenerateCertificate: async (_input) => {
 				const extraSans = [...require_hub_mdns_ciao.readExtraSans(this.tlsDataDir())];
-				await require_hub_mdns_ciao.regenerateCertificate(this.tlsDataDir(), { extraSans });
+				await require_hub_mdns_ciao.regenerateCertificate(this.tlsDataDir(), {
+					extraSans,
+					...await this.caHubName()
+				});
 				this.putCertificateOnListener("regenerate");
 				return this.snapshotTls();
 			},
@@ -910,7 +913,10 @@ var LocalNetworkAddon = class extends require_dist.BaseAddon {
 			},
 			revertToGeneratedCertificate: async () => {
 				const extraSans = [...require_hub_mdns_ciao.readExtraSans(this.tlsDataDir())];
-				await require_hub_mdns_ciao.revertToGeneratedCertificate(this.tlsDataDir(), { extraSans });
+				await require_hub_mdns_ciao.revertToGeneratedCertificate(this.tlsDataDir(), {
+					extraSans,
+					...await this.caHubName()
+				});
 				this.putCertificateOnListener("revert");
 				return this.snapshotTls();
 			}
@@ -1117,6 +1123,22 @@ var LocalNetworkAddon = class extends require_dist.BaseAddon {
 	tlsDataDir() {
 		return this.ctx.nodeDataDir ?? this.ctx.dataDir;
 	}
+	/**
+	* The hub's name (D861) for a local root this action may CREATE (an existing root is
+	* never renamed). Hub only: on an agent the hub's name would mislabel the agent's own
+	* material, so it gets the plain name. A failed read falls back to the machine
+	* hostname (what the hub shows when unnamed) and says so: a certificate action must
+	* not fail over a label.
+	*/
+	async caHubName() {
+		if ((this.ctx.kernel.localNodeId ?? "hub") !== "hub") return {};
+		try {
+			return { hubName: (await this.ctx.api.system.info.query()).serverName.name };
+		} catch (err) {
+			this.ctx.logger.warn("local-network: server name unreadable - naming the CA after the hostname", { meta: { error: require_dist.errMsg(err) } });
+			return { hubName: require_dist.shortHostname(node_os.hostname()) };
+		}
+	}
 	snapshotTls() {
 		const status = require_hub_mdns_ciao.readTlsAccessStatus(this.tlsDataDir(), require_hub_mdns_ciao.servedHttpsLeafFingerprint());
 		return {
@@ -1165,7 +1187,10 @@ var LocalNetworkAddon = class extends require_dist.BaseAddon {
 		if (hostname !== "") {
 			require_hub_mdns_ciao.writeExtraSans(this.tlsDataDir(), [hostname]);
 			if (require_hub_mdns_ciao.readTlsMode(this.tlsDataDir()) === "generated") {
-				if ((await require_hub_mdns_ciao.ensureTlsCert(this.tlsDataDir(), { extraSans: [hostname] })).generated) this.putCertificateOnListener("hostname");
+				if ((await require_hub_mdns_ciao.ensureTlsCert(this.tlsDataDir(), {
+					extraSans: [hostname],
+					hubName: require_dist.shortHostname(node_os.hostname())
+				})).generated) this.putCertificateOnListener("hostname");
 			}
 		} else require_hub_mdns_ciao.writeExtraSans(this.tlsDataDir(), []);
 	}

package/dist/builtins/local-network/local-network.addon.mjs

@@ -1,5 +1,5 @@
-import { $n as resolveAppConnections, B as HUB_MDNS_TXT_KEYS, Er as validateCustomAddress, On as localNetworkCapability, Wn as pickAppLinkHub, Y as NetworkTunnelStartedDataSchema, hn as isAppLinkBase, kt as checkRoleAddress, l as CAMSTACK_APP_LINK_ORIGIN, or as resolveNotificationTapAddress, qr as BaseAddon, rr as resolveHubAddressRoles, vn as isDefaultAppConnectionEndpoint, ya as EventCategory, z as HUB_MDNS_SERVICE_TYPE } from "../../dist-BpSENkRJ.mjs";
-import { P as readLanHttpState, a as storeUploadedCertificate, d as servedHttpsLeafFingerprint, g as readTlsMode, h as readTlsAccessStatus, i as revertToGeneratedCertificate, j as applyLanHttp, k as DEFAULT_LAN_HTTP_PORT, m as readExtraSans, n as applyCertificateToListener, o as useStoredUploadedCertificate, r as regenerateCertificate, t as createCiaoPublisher, v as writeExtraSans, w as ensureTlsCert } from "../../hub-mdns-ciao-DlgkFJVY.mjs";
+import { $n as pickAppLinkHub, Cn as isAppLinkBase, Dn as isDefaultAppConnectionEndpoint, Fr as validateCustomAddress, H as HUB_MDNS_TXT_KEYS, Ln as localNetworkCapability, Lt as checkRoleAddress, Oa as EventCategory, V as HUB_MDNS_SERVICE_TYPE, Z as NetworkTunnelStartedDataSchema, cr as resolveAppConnections, fr as resolveHubAddressRoles, hr as resolveNotificationTapAddress, l as CAMSTACK_APP_LINK_ORIGIN, ni as BaseAddon, ti as errMsg, xr as shortHostname } from "../../dist-Dhux90yB.mjs";
+import { P as readLanHttpState, a as storeUploadedCertificate, d as servedHttpsLeafFingerprint, g as readTlsMode, h as readTlsAccessStatus, i as revertToGeneratedCertificate, j as applyLanHttp, k as DEFAULT_LAN_HTTP_PORT, m as readExtraSans, n as applyCertificateToListener, o as useStoredUploadedCertificate, r as regenerateCertificate, t as createCiaoPublisher, v as writeExtraSans, w as ensureTlsCert } from "../../hub-mdns-ciao-B8olZqqd.mjs";
 import { z } from "zod";
 import { isIP } from "node:net";
 import * as os$1 from "node:os";
@@ -884,7 +884,10 @@ var LocalNetworkAddon = class extends BaseAddon {
 			getTlsStatus: async () => this.snapshotTls(),
 			regenerateCertificate: async (_input) => {
 				const extraSans = [...readExtraSans(this.tlsDataDir())];
-				await regenerateCertificate(this.tlsDataDir(), { extraSans });
+				await regenerateCertificate(this.tlsDataDir(), {
+					extraSans,
+					...await this.caHubName()
+				});
 				this.putCertificateOnListener("regenerate");
 				return this.snapshotTls();
 			},
@@ -907,7 +910,10 @@ var LocalNetworkAddon = class extends BaseAddon {
 			},
 			revertToGeneratedCertificate: async () => {
 				const extraSans = [...readExtraSans(this.tlsDataDir())];
-				await revertToGeneratedCertificate(this.tlsDataDir(), { extraSans });
+				await revertToGeneratedCertificate(this.tlsDataDir(), {
+					extraSans,
+					...await this.caHubName()
+				});
 				this.putCertificateOnListener("revert");
 				return this.snapshotTls();
 			}
@@ -1114,6 +1120,22 @@ var LocalNetworkAddon = class extends BaseAddon {
 	tlsDataDir() {
 		return this.ctx.nodeDataDir ?? this.ctx.dataDir;
 	}
+	/**
+	* The hub's name (D861) for a local root this action may CREATE (an existing root is
+	* never renamed). Hub only: on an agent the hub's name would mislabel the agent's own
+	* material, so it gets the plain name. A failed read falls back to the machine
+	* hostname (what the hub shows when unnamed) and says so: a certificate action must
+	* not fail over a label.
+	*/
+	async caHubName() {
+		if ((this.ctx.kernel.localNodeId ?? "hub") !== "hub") return {};
+		try {
+			return { hubName: (await this.ctx.api.system.info.query()).serverName.name };
+		} catch (err) {
+			this.ctx.logger.warn("local-network: server name unreadable - naming the CA after the hostname", { meta: { error: errMsg(err) } });
+			return { hubName: shortHostname(os$1.hostname()) };
+		}
+	}
 	snapshotTls() {
 		const status = readTlsAccessStatus(this.tlsDataDir(), servedHttpsLeafFingerprint());
 		return {
@@ -1162,7 +1184,10 @@ var LocalNetworkAddon = class extends BaseAddon {
 		if (hostname !== "") {
 			writeExtraSans(this.tlsDataDir(), [hostname]);
 			if (readTlsMode(this.tlsDataDir()) === "generated") {
-				if ((await ensureTlsCert(this.tlsDataDir(), { extraSans: [hostname] })).generated) this.putCertificateOnListener("hostname");
+				if ((await ensureTlsCert(this.tlsDataDir(), {
+					extraSans: [hostname],
+					hubName: shortHostname(os$1.hostname())
+				})).generated) this.putCertificateOnListener("hostname");
 			}
 		} else writeExtraSans(this.tlsDataDir(), []);
 	}

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

@@ -3,7 +3,9 @@ Object.defineProperties(exports, {
 	[Symbol.toStringTag]: { value: "Module" }
 });
 require("../../chunk-Cek0wNdY.js");
-const require_dist = require("../../dist-DjQ8C-ku.js");
+const require_dist = require("../../dist-C89nqNnn.js");
+const require_log_read_filter = require("../../log-read-filter-Bi066jwU.js");
+let zod = require("zod");
 //#region src/builtins/loki-logging/loki-payload.ts
 /**
 * Loki rejects a label name that is not a valid Prometheus label
@@ -41,6 +43,7 @@ function toUnixNano(timestamp) {
 */
 function formatLokiLine(entry) {
 	const line = { message: entry.message };
+	if (entry.id !== void 0) line["id"] = entry.id;
 	if (entry.scope !== void 0 && entry.scope.length > 0) line["scope"] = entry.scope;
 	if (entry.tags !== void 0 && Object.keys(entry.tags).length > 0) line["tags"] = entry.tags;
 	if (entry.meta !== void 0 && Object.keys(entry.meta).length > 0) line["meta"] = entry.meta;
@@ -91,6 +94,231 @@ function buildPushBody(entries, labels) {
 	return { streams };
 }
 //#endregion
+//#region src/builtins/loki-logging/loki-read.ts
+/**
+* Reading history back from Loki (D898): `GET /loki/api/v1/query_range`,
+* newest first.
+*
+* The label selector narrows by what IS a label (`job`, `node`, `level` —
+* see `loki-payload.ts` for why nothing else is); line filters (`|=`, `|~`)
+* narrow by device, addon and text on the JSON body; the shared
+* `lineMatches` then decides exactly, so a line filter only has to be a
+* superset.
+*
+* The cursor is the nanosecond timestamp of the oldest line returned plus a
+* short hash of each line returned AT that nanosecond: entries share
+* timestamps (they are millisecond-precise), so "older than t" would drop the
+* siblings a page cut through, and "t or older" would repeat them. The next
+* page asks for `end = t + 1` (Loki's end is exclusive) and skips the hashes.
+*/
+var LEVELS = [
+	"debug",
+	"info",
+	"warn",
+	"error"
+];
+/** One query_range window. A busy stream fills `limit` long before this. */
+var LOKI_WINDOW_MS = 360 * 60 * 1e3;
+var MS_NS = 1000000n;
+var CURSOR_PREFIX = "l1.";
+var LokiCursorSchema = zod.z.object({
+	/** Nanosecond epoch, decimal string. */
+	n: zod.z.string().regex(/^\d{1,22}$/),
+	/** Hashes of the lines already returned at exactly `n`. */
+	h: zod.z.array(zod.z.string().max(16)).max(1e3)
+});
+function encodeLokiCursor(cursor) {
+	return `${CURSOR_PREFIX}${Buffer.from(JSON.stringify(cursor)).toString("base64url")}`;
+}
+function decodeLokiCursor(raw) {
+	if (!raw.startsWith(CURSOR_PREFIX)) return null;
+	try {
+		const parsed = LokiCursorSchema.safeParse(JSON.parse(Buffer.from(raw.slice(3), "base64url").toString("utf8")));
+		return parsed.success ? parsed.data : null;
+	} catch {
+		return null;
+	}
+}
+/** FNV-1a, 32 bit, hex — a dedupe key, not a security property. */
+function lineHash(line) {
+	let h = 2166136261;
+	for (let i = 0; i < line.length; i += 1) {
+		h ^= line.charCodeAt(i);
+		h = Math.imul(h, 16777619);
+	}
+	return (h >>> 0).toString(16);
+}
+/** A LogQL double-quoted string literal. */
+function quote(value) {
+	return `"${value.replaceAll("\\", "\\\\").replaceAll("\"", "\\\"")}"`;
+}
+function escapeRegex(value) {
+	return value.replaceAll(/[\\.+*?()|[\]{}^$]/g, (c) => `\\${c}`);
+}
+/** The LogQL for a read. Pure. */
+function buildLogQl(query, labels) {
+	const selectors = [`job=${quote(labels.job)}`];
+	if (query.fromNodeId !== void 0) selectors.push(`node=${quote(query.fromNodeId)}`);
+	if (query.level !== void 0 && query.level !== "debug") {
+		const floor = LEVELS.indexOf(query.level);
+		selectors.push(`level=~${quote(LEVELS.slice(floor).join("|"))}`);
+	}
+	let logql = `{${selectors.join(",")}}`;
+	if (query.deviceId !== void 0) logql += ` |= ${quote(`"deviceId":${String(query.deviceId)}`)}`;
+	if (query.fromAddonId !== void 0) {
+		const bare = query.fromAddonId.split("@")[0] ?? query.fromAddonId;
+		logql += ` |= ${quote(`"addonId":"${bare}`)}`;
+	}
+	const text = query.text?.trim();
+	if (text !== void 0 && text.length > 0) logql += ` |~ ${quote(`(?i)${escapeRegex(text)}`)}`;
+	return logql;
+}
+var LokiResponseSchema = zod.z.object({ data: zod.z.object({ result: zod.z.array(zod.z.object({
+	stream: zod.z.record(zod.z.string(), zod.z.string()),
+	values: zod.z.array(zod.z.tuple([zod.z.string(), zod.z.string()]))
+})) }) });
+var LokiLineSchema = zod.z.object({
+	id: zod.z.string().optional(),
+	message: zod.z.string(),
+	scope: zod.z.string().optional(),
+	tags: zod.z.record(zod.z.string(), zod.z.unknown()).optional(),
+	meta: zod.z.record(zod.z.string(), zod.z.unknown()).optional()
+});
+function levelOf(label) {
+	return label === "debug" || label === "warn" || label === "error" ? label : "info";
+}
+/** A query_range body → rows, newest first. Lines that are not ours are dropped. */
+function parseQueryRange(body) {
+	const parsed = LokiResponseSchema.safeParse(body);
+	if (!parsed.success) throw new Error("Loki answered with an unexpected query_range shape");
+	const rows = [];
+	for (const stream of parsed.data.data.result) {
+		const level = levelOf(stream.stream["level"]);
+		for (const [nsText, text] of stream.values) {
+			let json;
+			try {
+				json = JSON.parse(text);
+			} catch {
+				continue;
+			}
+			const line = LokiLineSchema.safeParse(json);
+			if (!line.success) continue;
+			const ns = BigInt(nsText);
+			const timestamp = Number(ns / MS_NS);
+			const tags = {};
+			for (const [k, v] of Object.entries(line.data.tags ?? {})) if (typeof v === "string" || typeof v === "number") tags[k] = v;
+			const hasTags = Object.keys(tags).length > 0;
+			const entry = {
+				...line.data.id !== void 0 ? { id: line.data.id } : {},
+				timestamp,
+				level,
+				...line.data.scope !== void 0 ? { scope: line.data.scope } : {},
+				message: line.data.message,
+				...hasTags ? { tags } : {},
+				...line.data.meta !== void 0 ? { meta: line.data.meta } : {}
+			};
+			rows.push({
+				ns,
+				hash: lineHash(text),
+				entry,
+				line: {
+					timestamp,
+					level,
+					message: line.data.message,
+					scope: line.data.scope,
+					tags: hasTags ? tags : void 0,
+					meta: line.data.meta
+				}
+			});
+		}
+	}
+	return rows.toSorted((a, b) => a.ns < b.ns ? 1 : a.ns > b.ns ? -1 : 0);
+}
+/**
+* One backward slice over Loki: windows of {@link LOKI_WINDOW_MS}, newest
+* first, until `limit` matches, the horizon, the budget or a cancel.
+*/
+async function readLokiBackward(args) {
+	const { query } = args;
+	const now = args.now ?? Date.now;
+	const filter = require_log_read_filter.compileLogFilter(query);
+	const limit = query.limit ?? 200;
+	const deadline = now() + Math.min(query.budgetMs ?? 2e3, 1e4);
+	const logql = buildLogQl(query, args.labels);
+	const horizonMs = query.since ?? now() - 30 * 864e5;
+	const horizonNs = BigInt(Math.trunc(horizonMs)) * MS_NS;
+	const cursor = query.before !== void 0 ? decodeLokiCursor(query.before) : null;
+	const untilNs = query.until !== void 0 ? BigInt(Math.trunc(query.until) + 1) * MS_NS : null;
+	let endNs = cursor !== null ? BigInt(cursor.n) + 1n : untilNs ?? BigInt(now() + 1) * MS_NS;
+	let seenAtBoundary = new Set(cursor?.h ?? []);
+	let boundaryNs = cursor !== null ? BigInt(cursor.n) : null;
+	const entries = [];
+	let bytes = 0;
+	while (endNs > horizonNs) {
+		if (args.isCancelled()) return {
+			entries,
+			nextBefore: encodeLokiCursor({
+				n: String(endNs - 1n),
+				h: [...seenAtBoundary]
+			}),
+			nextAfter: null,
+			scannedBytes: bytes,
+			done: false,
+			cancelled: true
+		};
+		const windowStart = endNs - BigInt(LOKI_WINDOW_MS) * MS_NS;
+		const startNs = windowStart > horizonNs ? windowStart : horizonNs;
+		const want = limit - entries.length + seenAtBoundary.size;
+		const { rows, bytes: got } = await args.range({
+			logql,
+			startNs,
+			endNs,
+			limit: want
+		});
+		bytes += got;
+		let oldest = null;
+		for (const row of rows) {
+			if (boundaryNs !== null && row.ns === boundaryNs && seenAtBoundary.has(row.hash)) continue;
+			if (oldest === null || row.ns < oldest) {
+				if (oldest !== null && row.ns < oldest) seenAtBoundary = /* @__PURE__ */ new Set();
+				oldest = row.ns;
+			}
+			if (row.ns === oldest) seenAtBoundary.add(row.hash);
+			boundaryNs = oldest;
+			if (!require_log_read_filter.lineMatches(row.line, filter)) continue;
+			entries.push(row.entry);
+			if (entries.length >= limit) return {
+				entries,
+				nextBefore: encodeLokiCursor({
+					n: String(row.ns),
+					h: [...seenAtBoundary]
+				}),
+				nextAfter: null,
+				scannedBytes: bytes,
+				done: false
+			};
+		}
+		if (rows.length >= want && oldest !== null) endNs = oldest + 1n;
+		else {
+			endNs = startNs;
+			seenAtBoundary = /* @__PURE__ */ new Set();
+			boundaryNs = null;
+		}
+		if (now() >= deadline) break;
+	}
+	const done = endNs <= horizonNs;
+	return {
+		entries,
+		nextBefore: done ? null : encodeLokiCursor({
+			n: String(endNs - 1n),
+			h: [...seenAtBoundary]
+		}),
+		nextAfter: null,
+		scannedBytes: bytes,
+		done
+	};
+}
+//#endregion
 //#region src/builtins/loki-logging/loki-destination.ts
 var LEVEL_ORDER = {
 	debug: 0,
@@ -114,6 +342,8 @@ var LokiDestination = class {
 	failures = 0;
 	lastError = null;
 	lastPushAtMs = null;
+	/** In-flight history reads, by requestId, so `cancelRead` can abort the fetch. */
+	reads = /* @__PURE__ */ new Map();
 	fetchFn;
 	setIntervalFn;
 	clearIntervalFn;
@@ -121,7 +351,7 @@ var LokiDestination = class {
 		this.fetchFn = deps?.fetchFn ?? ((url, init) => globalThis.fetch(url, {
 			method: init.method,
 			headers: { ...init.headers },
-			body: init.body,
+			...init.body !== void 0 ? { body: init.body } : {},
 			...init.signal ? { signal: init.signal } : {}
 		}));
 		this.setIntervalFn = deps?.setIntervalFn ?? setInterval;
@@ -213,9 +443,10 @@ var LokiDestination = class {
 	}
 	async push(body, config) {
 		const endpoint = `${config.url.replace(/\/+$/, "")}/loki/api/v1/push`;
-		const headers = { "content-type": "application/json" };
-		if (config.tenantId.trim().length > 0) headers["X-Scope-OrgID"] = config.tenantId.trim();
-		if (config.username.length > 0) headers["authorization"] = `Basic ${Buffer.from(`${config.username}:${config.password}`).toString("base64")}`;
+		const headers = {
+			"content-type": "application/json",
+			...this.authHeaders(config)
+		};
 		const controller = new AbortController();
 		const timeout = setTimeout(() => controller.abort(), Math.max(1e3, config.timeoutMs));
 		try {
@@ -283,8 +514,93 @@ var LokiDestination = class {
 			};
 		}
 	}
-	async query(_filter) {
-		return [];
+	/** Headers every call to this Loki carries: tenant + basic auth. */
+	authHeaders(config) {
+		const headers = {};
+		if (config.tenantId.trim().length > 0) headers["X-Scope-OrgID"] = config.tenantId.trim();
+		if (config.username.length > 0) headers["authorization"] = `Basic ${Buffer.from(`${config.username}:${config.password}`).toString("base64")}`;
+		return headers;
+	}
+	/**
+	* Readable when it is configured (D898): the same URL and credentials the
+	* push uses answer `query_range`. Labels are `job`/`node`/`level`, so those
+	* filter at the index; device, addon and text are line filters.
+	*/
+	async describeRead() {
+		const configured = this.isActive();
+		return {
+			readable: configured,
+			reason: configured ? null : "Loki is not enabled or has no URL",
+			filters: {
+				deviceId: true,
+				addonId: true,
+				nodeId: true,
+				tags: true,
+				level: true,
+				text: true,
+				timeRange: true
+			},
+			retentionDays: null
+		};
+	}
+	/** One backward slice from `query_range`, newest first. Never logs. */
+	async read(query) {
+		const config = this.config;
+		if (config === null || !this.isActive()) throw new Error("Loki is not enabled or has no URL");
+		const controller = new AbortController();
+		const requestId = query.requestId;
+		if (requestId !== void 0) this.reads.set(requestId, controller);
+		const base = config.url.replace(/\/+$/, "");
+		const range = async ({ logql, startNs, endNs, limit }) => {
+			const params = new URLSearchParams({
+				query: logql,
+				start: String(startNs),
+				end: String(endNs),
+				limit: String(limit),
+				direction: "backward"
+			});
+			const timeout = setTimeout(() => controller.abort(), Math.max(1e3, config.timeoutMs));
+			try {
+				const response = await this.fetchFn(`${base}/loki/api/v1/query_range?${params.toString()}`, {
+					method: "GET",
+					headers: this.authHeaders(config),
+					signal: controller.signal
+				});
+				const text = await response.text();
+				if (!response.ok) throw new Error(`Loki query failed: ${String(response.status)}${text.length > 0 ? ` — ${text.slice(0, 200)}` : ""}`);
+				return {
+					rows: parseQueryRange(JSON.parse(text)),
+					bytes: Buffer.byteLength(text)
+				};
+			} finally {
+				clearTimeout(timeout);
+			}
+		};
+		try {
+			return await readLokiBackward({
+				query,
+				labels: { job: config.job },
+				range,
+				isCancelled: () => controller.signal.aborted
+			});
+		} catch (error) {
+			if (controller.signal.aborted) return {
+				entries: [],
+				nextBefore: query.before ?? null,
+				nextAfter: null,
+				scannedBytes: 0,
+				done: false,
+				cancelled: true
+			};
+			throw error;
+		} finally {
+			if (requestId !== void 0) this.reads.delete(requestId);
+		}
+	}
+	async cancelRead(input) {
+		const controller = this.reads.get(input.requestId);
+		controller?.abort();
+		return { cancelled: controller !== void 0 };
 	}
 	async shutdown() {
 		this.stopTimer();