@camstack/system 1.2.455 → 1.2.457

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 {};

package/dist/builtins/winston-logging/winston-destination.d.ts

@@ -1,4 +1,5 @@
-import type { ILogDestination, LogEntry, LogFilter } from "@camstack/types";
+import type { ILogDestination, LogEntry, LogReadCapabilities, LogReadQuery, LogReadResult } from "@camstack/types";
+import { type LogFileReadClientOptions } from "./log-file-read-client.js";
 interface WinstonConfig {
 	readonly level: string;
 	readonly retentionDays: number;
@@ -12,10 +13,27 @@ interface WinstonConfig {
 * structured JSON shape so log tooling can query tags/meta.
 */
 export declare class WinstonDestination implements ILogDestination {
+	private readonly readerOptions;
 	private logger;
+	private reader;
+	private retentionDays;
+	/**
+	* `readerOptions` reaches the history reader (D898) — a spec runs it in
+	* process or points the thread at the TypeScript source.
+	*/
+	constructor(readerOptions?: Omit<LogFileReadClientOptions, "logsDir">);
 	initialize(config?: WinstonConfig): Promise<void>;
 	write(entry: LogEntry): void;
-	query(_filter: LogFilter): Promise<readonly LogEntry[]>;
+	/** The rotated files ARE the hub's history (D898): every filter is applied here. */
+	describeRead(): Promise<LogReadCapabilities>;
+	/** Index the existing files in the background now (the hub's history). */
+	startBackgroundIndexing(): void;
+	read(query: LogReadQuery): Promise<LogReadResult>;
+	cancelRead(input: {
+		readonly requestId: string;
+	}): Promise<{
+		readonly cancelled: boolean;
+	}>;
 	shutdown(): Promise<void>;
 }
 export {};

package/dist/{composition-sources-CSzD5_qX.mjs → composition-sources-B_jeZDRJ.mjs}

@@ -1,4 +1,4 @@
-import { Kr as errMsg, zr as compositionSourceKey } from "./dist-BpSENkRJ.mjs";
+import { Jr as compositionSourceKey, ti as errMsg } from "./dist-Dhux90yB.mjs";
 //#region src/builtins/core-blocks/composition-sources.ts
 /**
 * Describe what a composition reads and writes for SAVE-time validation

package/dist/{composition-sources-BxUkLNSo.js → composition-sources-qKyvMAvc.js}

@@ -1,4 +1,4 @@
-const require_dist = require("./dist-DjQ8C-ku.js");
+const require_dist = require("./dist-C89nqNnn.js");
 //#region src/builtins/core-blocks/composition-sources.ts
 /**
 * Describe what a composition reads and writes for SAVE-time validation

package/dist/{constants-DruwCkfp.js → constants-B_X9cWEK.js}

@@ -1,5 +1,5 @@
 /** `secret://system/global/meshCaKey` — EC P-256 PKCS#8 PEM of the hub mesh CA. */
-var MESH_CA_KEY_REF = require("./dist-DjQ8C-ku.js").buildSecretRef({
+var MESH_CA_KEY_REF = require("./dist-C89nqNnn.js").buildSecretRef({
 	owner: "system",
 	scope: { kind: "global" },
 	fieldPath: "meshCaKey"

package/dist/{constants-DOlYt1t1.mjs → constants-cxKcZRMi.mjs}

@@ -1,4 +1,4 @@
-import { Oi as buildSecretRef } from "./dist-BpSENkRJ.mjs";
+import { Li as buildSecretRef } from "./dist-Dhux90yB.mjs";
 /** `secret://system/global/meshCaKey` — EC P-256 PKCS#8 PEM of the hub mesh CA. */
 var MESH_CA_KEY_REF = buildSecretRef({
 	owner: "system",

package/dist/{device-ca-uFbTyY_o.mjs → device-ca-BB6nHAL5.mjs}

@@ -1,4 +1,4 @@
-import { O as DEVICE_SAN_CREDENTIAL_PREFIX, Oi as buildSecretRef, k as DEVICE_SAN_USER_PREFIX } from "./dist-BpSENkRJ.mjs";
+import { A as DEVICE_SAN_CREDENTIAL_PREFIX, Li as buildSecretRef, j as DEVICE_SAN_USER_PREFIX } from "./dist-Dhux90yB.mjs";
 import { S as backdatedNotBefore, a as KeyUsageFlags, d as SubjectKeyIdentifierExtension, f as X509Certificate$1, m as cryptoProvider, n as BasicConstraintsExtension, o as KeyUsagesExtension, p as X509CertificateGenerator, r as ExtendedKeyUsageExtension, s as PemConverter, t as AuthorityKeyIdentifierExtension, u as SubjectAlternativeNameExtension } from "./x509.es-DK__ETIe.mjs";
 import { X509Certificate, createPublicKey, randomBytes, verify, webcrypto } from "node:crypto";
 //#region src/auth/jwt-signing-key.ts

package/dist/{device-ca-QPBgfqVY.js → device-ca-CVK3YcR_.js}

@@ -1,4 +1,4 @@
-const require_dist = require("./dist-DjQ8C-ku.js");
+const require_dist = require("./dist-C89nqNnn.js");
 const require_x509_es = require("./x509.es-C4cOo48M.js");
 let node_crypto = require("node:crypto");
 //#region src/auth/jwt-signing-key.ts