@camstack/system 1.2.456 → 1.2.457

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-BpqA2CT0.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 { $r as BaseAddon, In as logDestinationCapability } from "../../dist-BSF_C8W2.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>;
+}

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

@@ -0,0 +1,77 @@
+export declare const INDEX_VERSION = 1;
+export declare const BLOCK_BYTES: number;
+/** Above this many distinct values a block's set becomes `null` (anything). */
+export declare const MAX_SET = 256;
+/** One completed block of the sidecar. */
+export interface IndexBlock {
+	/** Byte range [s, e), e on a line boundary. */
+	readonly s: number;
+	readonly e: number;
+	readonly n: number;
+	/** Epoch ms range; null when a line's timestamp could not be read. */
+	readonly t0: number | null;
+	readonly t1: number | null;
+	readonly d: number[] | null;
+	readonly a: string[] | null;
+	readonly o: string[] | null;
+	/** Highest level rank in the block. */
+	readonly l: number;
+}
+/** What one raw line contributes to its block. */
+export interface LineFacts {
+	readonly ts: number | null;
+	readonly level: number;
+	readonly deviceIds: readonly number[];
+	readonly addonIds: readonly string[];
+	readonly nodes: readonly string[];
+}
+/** Facts off the raw text — no JSON.parse. */
+export declare function extractLineFacts(line: string): LineFacts;
+/** Accumulates lines into one block. */
+export declare class BlockBuilder {
+	readonly start: number;
+	private n;
+	private t0;
+	private t1;
+	private tsUnknown;
+	private readonly d;
+	private readonly a;
+	private readonly o;
+	private l;
+	constructor(start: number);
+	add(facts: LineFacts): void;
+	/** A line whose facts could not be read: the block may hold anything. */
+	addUnknown(): void;
+	get lines(): number;
+	finish(end: number): IndexBlock;
+}
+/** In-memory index state of one file. */
+export interface FileIndex {
+	readonly ino: number;
+	/** Completed blocks, ascending, tiling [0, indexedEnd). */
+	readonly blocks: IndexBlock[];
+}
+export declare function indexEnd(index: FileIndex): number;
+export declare function indexPathOf(logPath: string): string;
+/**
+* Load `<file>.idx`. Returns an empty index (to be rebuilt) when the sidecar
+* is missing, belongs to another inode, or is not a contiguous tiling; keeps
+* the valid prefix when only its tail is torn.
+*/
+export declare function loadFileIndex(logPath: string, ino: number, size: number): Promise<{
+	readonly index: FileIndex;
+	/** True when the sidecar must be rewritten from `index` before appending. */
+	readonly rewrite: boolean;
+}>;
+/** Something that yields between chunks so a reader on the same thread can run. */
+export type Yield = () => Promise<void>;
+/**
+* Extend `index` over whatever complete lines were appended to the file since
+* its last completed block, persisting each block as it completes. Returns
+* the number of bytes read.
+*/
+export declare function catchUpFileIndex(logPath: string, index: FileIndex, opts: {
+	readonly rewrite: boolean;
+	readonly yieldFn?: Yield;
+	readonly shouldStop?: () => boolean;
+}): Promise<number>;

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

@@ -0,0 +1,44 @@
+import type { LogReadQuery, LogReadResult } from "@camstack/types";
+import { type ReadWorkerData, type ToReader } from "./log-file-read-protocol.js";
+/** The structural surface of a `Worker` this client uses. */
+export interface ReaderWorkerHandle {
+	on(event: "message", listener: (message: unknown) => void): unknown;
+	on(event: "error", listener: (err: unknown) => void): unknown;
+	on(event: "exit", listener: (code: number) => void): unknown;
+	postMessage(message: ToReader): void;
+	unref?(): void;
+}
+export type ReaderWorkerFactory = (data: ReadWorkerData) => ReaderWorkerHandle;
+/** `dist/log-file-read-worker.js` at the package root, found through its own `package.json`. */
+export declare function defaultReaderWorkerPath(): string;
+export interface LogFileReadClientOptions {
+	readonly logsDir: string;
+	/** Background index pass period. Default 60 s; 0 disables (specs). */
+	readonly backgroundPassMs?: number;
+	/** Run in the calling thread — specs only. */
+	readonly inProcess?: boolean;
+	readonly workerPath?: string;
+	readonly workerExecArgv?: readonly string[];
+	readonly workerFactory?: ReaderWorkerFactory;
+}
+export declare class LogFileReadClient {
+	private readonly logsDir;
+	private readonly backgroundPassMs;
+	private readonly spawn;
+	private worker;
+	private nextId;
+	private readonly pending;
+	private readonly local;
+	constructor(options: LogFileReadClientOptions);
+	read(query: LogReadQuery): Promise<LogReadResult>;
+	/**
+	* 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(): void;
+	cancel(requestId: string): boolean;
+	stop(): void;
+	private ensureWorker;
+	private failAll;
+}

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

@@ -0,0 +1,41 @@
+/**
+* Messages between `WinstonDestination` and its reader thread (D898), and the
+* one function both the thread and the in-process mode run.
+*/
+import type { LogReadQuery, LogReadResult } from "@camstack/types";
+import type { LogFileIndexStore } from "./log-file-index-store.js";
+import { type FileReadOutcome } from "./log-file-reader.js";
+export interface ReadWorkerData {
+	readonly logsDir: string;
+	/** Period of the background index pass; 0 disables it (specs). */
+	readonly backgroundPassMs: number;
+}
+export type ToReader = {
+	readonly type: "read";
+	readonly id: number;
+	readonly query: LogReadQuery;
+} | {
+	readonly type: "cancel";
+	readonly requestId: string;
+} | {
+	readonly type: "stop";
+};
+export type FromReader = {
+	readonly type: "result";
+	readonly id: number;
+	readonly result: LogReadResult;
+} | {
+	readonly type: "error";
+	readonly id: number;
+	readonly message: string;
+};
+export declare function isFromReader(value: unknown): value is FromReader;
+export declare function isToReader(value: unknown): value is ToReader;
+/** Requests cancelled before or while they run, with when, so the set cannot grow. */
+export declare class CancelBook {
+	private readonly at;
+	cancel(requestId: string, now?: number): void;
+	isCancelled(requestId: string | undefined): boolean;
+	settle(requestId: string | undefined): void;
+}
+export declare function serveRead(logsDir: string, store: LogFileIndexStore, cancels: CancelBook, query: LogReadQuery): Promise<FileReadOutcome>;

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

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,51 @@
+import type { LogReadEntry, LogReadQuery, LogReadResult } from "@camstack/types";
+import { type CompiledLogFilter, type ReadableLine } from "../../logging/log-read-filter.js";
+import { type FileIndex, type IndexBlock } from "./log-file-index.js";
+export declare const DEFAULT_READ_LIMIT = 200;
+export declare const DEFAULT_BUDGET_MS = 1e3;
+export declare const MAX_BUDGET_MS = 5e3;
+export interface FileReadStats {
+	/** Blocks the index ruled out — never read. */
+	blocksSkipped: number;
+	/** Blocks (or unindexed regions) actually read. */
+	regionsRead: number;
+	/** Of those, INDEXED blocks — the ones the index could have skipped. */
+	blocksRead: number;
+	/** Lines handed to JSON.parse. */
+	linesParsed: number;
+}
+export interface FileReadOutcome {
+	readonly result: LogReadResult;
+	readonly stats: FileReadStats;
+}
+export interface FileReadContext {
+	readonly logsDir: string;
+	/** The file's index as far as it reaches (may be empty — then nothing is skipped). */
+	readonly indexOf: (fileName: string) => Promise<FileIndex | null>;
+	readonly isCancelled: () => boolean;
+	readonly now?: () => number;
+}
+/** What a reader can rule out from a block alone. */
+export declare function blockMayMatch(block: IndexBlock, filter: CompiledLogFilter): boolean;
+interface ParsedRow {
+	readonly entry: LogReadEntry;
+	readonly line: ReadableLine;
+}
+/** One JSON row → a read entry, or null for a line that is not one of ours. */
+export declare function parseLogRow(text: string): ParsedRow | null;
+/** Daily files, newest first. */
+export declare function listLogFiles(logsDir: string): Promise<string[]>;
+/**
+* One backward slice. `entries` newest first; `nextBefore` resumes exactly
+* where this slice stopped.
+*/
+export declare function readLogFilesBackward(ctx: FileReadContext, query: LogReadQuery): Promise<FileReadOutcome>;
+/**
+* One forward slice: lines strictly after `after`, scanned oldest first and
+* returned newest first like every page. `nextAfter` is where the next poll
+* starts; `done` means the scan reached the end of the newest file.
+*/
+export declare function readLogFilesForward(ctx: FileReadContext, query: LogReadQuery & {
+	readonly after: string;
+}): Promise<FileReadOutcome>;
+export {};