@north-light/api 0.3.580 → 0.3.588

package/dist/core/events/read.d.ts

@@ -0,0 +1,40 @@
+import { type EventComponent, type EventEnvelope, type EventLevel, type OperationId } from './types.js';
+export interface EventReadQuery {
+    nodeId?: string;
+    component?: EventComponent;
+    operationId?: OperationId;
+    sinceMs?: number;
+    untilMs?: number;
+    minimumLevel?: EventLevel;
+    pattern?: string;
+}
+export interface CanonicalReadItem {
+    kind: 'event';
+    envelope: EventEnvelope;
+    source: string;
+    streamKey: string;
+    generation: 2 | 1 | 0;
+    byteOffset: number;
+    effectiveTsMs: number;
+    /** True when this item's source omitted content: the reader's fixed byte
+     *  bound cut its start, or the same file also contained a corrupt/mismatched
+     *  line. Constant across every item from one source file. */
+    truncated: boolean;
+}
+export interface RawReadItem {
+    kind: 'raw';
+    component: 'daemon' | 'broker';
+    source: string;
+    content: string;
+    effectiveTsMs: number;
+    /** True when the reader's fixed byte bound cut this source's start. */
+    truncated: boolean;
+}
+export type LogSnapshotItem = CanonicalReadItem | RawReadItem;
+export interface LogSnapshotResult {
+    items: LogSnapshotItem[];
+    invalidCanonicalLines: number;
+}
+export type Tier1Event = Pick<EventEnvelope, 'v' | 'ts' | 'level' | 'event' | 'component' | 'operation_id' | 'node_id' | 'stream_id' | 'duration_ms' | 'outcome' | 'attempt' | 'error_class'>;
+export declare function readLogSnapshot(query: EventReadQuery, includeRaw: boolean): LogSnapshotResult;
+export declare function projectTier1Event(envelope: EventEnvelope): Tier1Event;

package/dist/core/events/read.js

@@ -0,0 +1,625 @@
+import { closeSync, constants, fstatSync, lstatSync, openSync, opendirSync, readSync, } from 'node:fs';
+import { isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { crtrHome, isSafeNodeId, nodesRoot } from '../canvas/paths.js';
+import { validateOperationId } from './operation-id.js';
+import { MAX_EVENT_RECORD_BYTES } from './serialize.js';
+import { errorClassCodes, } from './types.js';
+import { isRecord } from '../../shared/predicates.js';
+import { MAX_DAEMON_ACTIVE_BYTES } from '../log.js';
+const SNAPSHOT_ITEMS = 200;
+// A daemon log generation holds up to MAX_DAEMON_ACTIVE_BYTES, so a snapshot reads a whole generation.
+const MAX_CANONICAL_SOURCE_BYTES = MAX_DAEMON_ACTIVE_BYTES + 1024 * 1024;
+const MAX_RAW_SOURCE_BYTES = 256 * 1024;
+const MAX_CANONICAL_CONTENT_BYTES = MAX_EVENT_RECORD_BYTES - 1;
+const NO_FOLLOW_FLAG = typeof constants.O_NOFOLLOW === 'number' ? constants.O_NOFOLLOW : 0;
+const EVENT_NAME = /^[a-z][a-z0-9]*(?:[._][a-z0-9]+)*$/;
+const CANONICAL_TIMESTAMP = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/;
+const ISO_TIMESTAMP = /^\d{4}-\d{2}-\d{2}T/;
+const QUERY_KEYS = new Set(['nodeId', 'component', 'operationId', 'sinceMs', 'untilMs', 'minimumLevel', 'pattern']);
+const ERROR_CLASS_KEYS = new Set(['class', 'status', 'provider', 'retry_disposition']);
+const ERROR_KEYS = new Set(['type', 'message', 'stack', 'cause']);
+const TOP_LEVEL_KEYS = new Set([
+    'v',
+    'ts',
+    'level',
+    'event',
+    'component',
+    'operation_id',
+    'node_id',
+    'stream_id',
+    'duration_ms',
+    'outcome',
+    'attempt',
+    'error_class',
+    'error',
+    'fields',
+    'record_truncated',
+    'original_bytes',
+    'dropped_fields_count',
+]);
+const LEVELS = new Set(['debug', 'info', 'warn', 'error']);
+const COMPONENTS = new Set(['daemon', 'broker']);
+const OUTCOMES = new Set(['succeeded', 'failed', 'skipped']);
+const RETRY_DISPOSITIONS = new Set(['auto', 'manual', 'fatal']);
+const ERROR_CLASSES = new Set(errorClassCodes);
+const LEVEL_RANK = { debug: 0, info: 1, warn: 2, error: 3 };
+const GENERATION_RANK = { 2: 0, 1: 1, 0: 2 };
+function hasOwn(value, key) {
+    return Object.prototype.hasOwnProperty.call(value, key);
+}
+function hasOnlyKeys(value, allowed) {
+    return Object.keys(value).every((key) => allowed.has(key));
+}
+function boundedString(value, maximumBytes, nonempty = false) {
+    return typeof value === 'string'
+        && (!nonempty || value !== '')
+        && Buffer.byteLength(value, 'utf8') <= maximumBytes;
+}
+function normalizeQuery(query) {
+    if (typeof query !== 'object' || query === null || Array.isArray(query))
+        throw new TypeError('event read query is invalid');
+    const input = query;
+    if (!hasOnlyKeys(input, QUERY_KEYS))
+        throw new TypeError('event read query is invalid');
+    const normalized = {};
+    if (input.nodeId !== undefined) {
+        if (typeof input.nodeId !== 'string' || !isSafeNodeId(input.nodeId))
+            throw new TypeError('nodeId must be a safe non-empty path segment');
+        normalized.nodeId = input.nodeId;
+    }
+    if (input.component !== undefined) {
+        if (typeof input.component !== 'string' || !COMPONENTS.has(input.component))
+            throw new TypeError('component is invalid');
+        normalized.component = input.component;
+    }
+    if (input.operationId !== undefined)
+        normalized.operationId = validateOperationId(input.operationId);
+    if (input.sinceMs !== undefined) {
+        if (typeof input.sinceMs !== 'number' || !Number.isFinite(input.sinceMs))
+            throw new TypeError('sinceMs must be finite');
+        normalized.sinceMs = input.sinceMs;
+    }
+    if (input.untilMs !== undefined) {
+        if (typeof input.untilMs !== 'number' || !Number.isFinite(input.untilMs))
+            throw new TypeError('untilMs must be finite');
+        normalized.untilMs = input.untilMs;
+    }
+    if (normalized.sinceMs !== undefined && normalized.untilMs !== undefined && normalized.sinceMs > normalized.untilMs) {
+        throw new TypeError('sinceMs cannot exceed untilMs');
+    }
+    if (input.minimumLevel !== undefined) {
+        if (typeof input.minimumLevel !== 'string' || !LEVELS.has(input.minimumLevel))
+            throw new TypeError('minimumLevel is invalid');
+        normalized.minimumLevel = input.minimumLevel;
+    }
+    if (input.pattern !== undefined) {
+        if (!boundedString(input.pattern, 4_096, true))
+            throw new TypeError('pattern must be a non-empty string of at most 4,096 UTF-8 bytes');
+        normalized.pattern = input.pattern;
+    }
+    return normalized;
+}
+function selected(query, component) {
+    return query.component === undefined || query.component === component;
+}
+function identityOf(stats) {
+    return { dev: stats.dev, ino: stats.ino };
+}
+function sameIdentity(left, right) {
+    return left.dev === right.dev && left.ino === right.ino;
+}
+function safeSize(stats, absolute) {
+    if (stats.size < 0n || stats.size > BigInt(Number.MAX_SAFE_INTEGER))
+        throw new Error(`event source has an unsafe size: ${absolute}`);
+    return Number(stats.size);
+}
+function isMissing(error) {
+    return error?.code === 'ENOENT';
+}
+function isContained(home, absolute) {
+    const child = relative(home, absolute);
+    return child !== '' && !isAbsolute(child) && child !== '..' && !child.startsWith(`..${sep}`);
+}
+function validateDirectories(proofs) {
+    for (const proof of proofs) {
+        let stats;
+        try {
+            stats = lstatSync(proof.absolute, { bigint: true });
+        }
+        catch (error) {
+            throw new Error(`event source directory changed: ${proof.absolute}`, { cause: error });
+        }
+        if (stats.isSymbolicLink() || !stats.isDirectory() || !sameIdentity(proof, identityOf(stats))) {
+            throw new Error(`event source directory is unsafe: ${proof.absolute}`);
+        }
+    }
+}
+function proveDirectory(home, absolute, parents, optional) {
+    if (parents.length > 0 && !isContained(home, absolute))
+        throw new Error(`event source directory escapes its home: ${absolute}`);
+    validateDirectories(parents);
+    let stats;
+    try {
+        stats = lstatSync(absolute, { bigint: true });
+    }
+    catch (error) {
+        if (optional && isMissing(error))
+            return undefined;
+        throw new Error(`event source directory is unavailable: ${absolute}`, { cause: error });
+    }
+    if (stats.isSymbolicLink() || !stats.isDirectory())
+        throw new Error(`event source directory is unsafe: ${absolute}`);
+    validateDirectories(parents);
+    return { absolute, ...identityOf(stats) };
+}
+function forEachDirectoryEntry(proof, consume) {
+    validateDirectories([proof]);
+    let directory;
+    try {
+        directory = opendirSync(proof.absolute);
+    }
+    catch (error) {
+        throw new Error(`event source directory cannot be opened: ${proof.absolute}`, { cause: error });
+    }
+    try {
+        for (;;) {
+            const entry = directory.readSync();
+            if (entry === null)
+                break;
+            consume(entry.name, entry.isDirectory());
+        }
+    }
+    finally {
+        directory.closeSync();
+    }
+    validateDirectories([proof]);
+}
+function readExact(fd, bytes, position) {
+    let offset = 0;
+    while (offset < bytes.length) {
+        const count = readSync(fd, bytes, offset, bytes.length - offset, position + offset);
+        if (count === 0)
+            throw new Error('event source changed during read');
+        offset += count;
+    }
+}
+function readOwnedFile(home, directories, absolute, maximumBytes) {
+    if (!isContained(home, absolute))
+        throw new Error(`event source escapes its home: ${absolute}`);
+    validateDirectories(directories);
+    let before;
+    try {
+        before = lstatSync(absolute, { bigint: true });
+    }
+    catch (error) {
+        if (isMissing(error))
+            return undefined;
+        throw new Error(`event source is unavailable: ${absolute}`, { cause: error });
+    }
+    if (before.isSymbolicLink() || !before.isFile())
+        throw new Error(`event source is unsafe: ${absolute}`);
+    validateDirectories(directories);
+    let fd;
+    try {
+        fd = openSync(absolute, constants.O_RDONLY | NO_FOLLOW_FLAG);
+    }
+    catch (error) {
+        throw new Error(`event source cannot be opened safely: ${absolute}`, { cause: error });
+    }
+    try {
+        const opened = fstatSync(fd, { bigint: true });
+        if (!opened.isFile() || !sameIdentity(identityOf(before), identityOf(opened))) {
+            throw new Error(`event source changed before read: ${absolute}`);
+        }
+        validateDirectories(directories);
+        const size = safeSize(opened, absolute);
+        const length = Math.min(size, maximumBytes);
+        const start = size - length;
+        const bytes = Buffer.allocUnsafe(length);
+        readExact(fd, bytes, start);
+        const mtimeMs = Number(opened.mtimeMs);
+        return { bytes, start, mtimeMs: Number.isFinite(mtimeMs) ? mtimeMs : 0 };
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+function validErrorClass(value) {
+    if (!isRecord(value) || !hasOnlyKeys(value, ERROR_CLASS_KEYS))
+        return false;
+    if (typeof value.class !== 'string' || !ERROR_CLASSES.has(value.class))
+        return false;
+    if (hasOwn(value, 'status') && (typeof value.status !== 'number' || !Number.isSafeInteger(value.status)))
+        return false;
+    if (hasOwn(value, 'provider') && !boundedString(value.provider, 128, true))
+        return false;
+    return !hasOwn(value, 'retry_disposition')
+        || (typeof value.retry_disposition === 'string' && RETRY_DISPOSITIONS.has(value.retry_disposition));
+}
+function validError(value) {
+    if (!isRecord(value) || !hasOnlyKeys(value, ERROR_KEYS))
+        return false;
+    if (!boundedString(value.type, 128, true) || !boundedString(value.message, 4_096))
+        return false;
+    if (hasOwn(value, 'stack') && !boundedString(value.stack, 16_384))
+        return false;
+    return !hasOwn(value, 'cause') || boundedString(value.cause, 4_096);
+}
+function validEventField(value, depth, budget) {
+    if (budget.remaining <= 0)
+        return false;
+    budget.remaining -= 1;
+    if (value === null || typeof value === 'boolean')
+        return true;
+    if (typeof value === 'number')
+        return Number.isFinite(value);
+    if (typeof value === 'string')
+        return Buffer.byteLength(value, 'utf8') <= 4_096;
+    if (depth >= 4 || typeof value !== 'object' || value === null)
+        return false;
+    if (Array.isArray(value)) {
+        return value.length <= 64 && value.every((item) => validEventField(item, depth + 1, budget));
+    }
+    const entries = Object.entries(value);
+    return entries.length <= 64
+        && entries.every(([key, item]) => Buffer.byteLength(key, 'utf8') <= 128 && validEventField(item, depth + 1, budget));
+}
+function nonnegativeInteger(value) {
+    return typeof value === 'number' && Number.isSafeInteger(value) && value >= 0;
+}
+function parseCanonicalLine(content) {
+    if (content.length === 0 || content.length > MAX_CANONICAL_CONTENT_BYTES || content.includes(0x0d))
+        return undefined;
+    let parsed;
+    try {
+        parsed = JSON.parse(content.toString('utf8'));
+    }
+    catch {
+        return undefined;
+    }
+    if (!isRecord(parsed) || !hasOnlyKeys(parsed, TOP_LEVEL_KEYS))
+        return undefined;
+    if (parsed.v !== 1
+        || !boundedString(parsed.ts, 128, true)
+        || !CANONICAL_TIMESTAMP.test(parsed.ts)
+        || !boundedString(parsed.event, 128, true)
+        || !EVENT_NAME.test(parsed.event)
+        || typeof parsed.level !== 'string'
+        || !LEVELS.has(parsed.level)
+        || typeof parsed.component !== 'string'
+        || !COMPONENTS.has(parsed.component))
+        return undefined;
+    const effectiveTsMs = Date.parse(parsed.ts);
+    if (!Number.isFinite(effectiveTsMs) || new Date(effectiveTsMs).toISOString() !== parsed.ts)
+        return undefined;
+    let operationId;
+    try {
+        operationId = validateOperationId(parsed.operation_id);
+    }
+    catch {
+        return undefined;
+    }
+    const envelope = {
+        v: 1,
+        ts: parsed.ts,
+        level: parsed.level,
+        event: parsed.event,
+        component: parsed.component,
+        operation_id: operationId,
+    };
+    if (hasOwn(parsed, 'node_id')) {
+        if (!boundedString(parsed.node_id, 128, true))
+            return undefined;
+        envelope.node_id = parsed.node_id;
+    }
+    if (hasOwn(parsed, 'stream_id')) {
+        if (!boundedString(parsed.stream_id, 128, true))
+            return undefined;
+        envelope.stream_id = parsed.stream_id;
+    }
+    if (hasOwn(parsed, 'duration_ms')) {
+        if (typeof parsed.duration_ms !== 'number' || !Number.isFinite(parsed.duration_ms) || parsed.duration_ms < 0)
+            return undefined;
+        envelope.duration_ms = parsed.duration_ms;
+    }
+    if (hasOwn(parsed, 'outcome')) {
+        if (typeof parsed.outcome !== 'string' || !OUTCOMES.has(parsed.outcome))
+            return undefined;
+        envelope.outcome = parsed.outcome;
+    }
+    if (hasOwn(parsed, 'attempt')) {
+        if (typeof parsed.attempt !== 'number' || !Number.isSafeInteger(parsed.attempt) || parsed.attempt <= 0)
+            return undefined;
+        envelope.attempt = parsed.attempt;
+    }
+    if (hasOwn(parsed, 'error_class')) {
+        if (!validErrorClass(parsed.error_class))
+            return undefined;
+        envelope.error_class = parsed.error_class;
+    }
+    if (hasOwn(parsed, 'error')) {
+        if (!validError(parsed.error))
+            return undefined;
+        envelope.error = parsed.error;
+    }
+    if (hasOwn(parsed, 'fields')) {
+        if (!isRecord(parsed.fields) || !validEventField(parsed.fields, 0, { remaining: 5_000 }))
+            return undefined;
+        envelope.fields = parsed.fields;
+    }
+    const truncated = hasOwn(parsed, 'record_truncated');
+    const originalBytes = hasOwn(parsed, 'original_bytes');
+    const droppedFields = hasOwn(parsed, 'dropped_fields_count');
+    if (truncated) {
+        if (parsed.record_truncated !== true || !originalBytes || !droppedFields
+            || !nonnegativeInteger(parsed.original_bytes) || !nonnegativeInteger(parsed.dropped_fields_count))
+            return undefined;
+        envelope.record_truncated = true;
+        envelope.original_bytes = parsed.original_bytes;
+        envelope.dropped_fields_count = parsed.dropped_fields_count;
+    }
+    else if (originalBytes || droppedFields) {
+        return undefined;
+    }
+    return { envelope, effectiveTsMs };
+}
+function descriptorMatches(source, envelope) {
+    if (envelope.component !== source.component)
+        return false;
+    if (source.component === 'daemon')
+        return envelope.stream_id === undefined;
+    if (source.component === 'broker')
+        return envelope.node_id === source.boundNodeId && envelope.stream_id === undefined;
+    return envelope.stream_id === source.boundStreamId;
+}
+function matchesCanonical(query, source, parsed) {
+    const { envelope, effectiveTsMs } = parsed;
+    if (query.nodeId !== undefined && source.component !== 'broker' && envelope.node_id !== query.nodeId)
+        return false;
+    if (query.operationId !== undefined && envelope.operation_id !== query.operationId)
+        return false;
+    if (query.sinceMs !== undefined && effectiveTsMs < query.sinceMs)
+        return false;
+    if (query.untilMs !== undefined && effectiveTsMs > query.untilMs)
+        return false;
+    if (query.minimumLevel !== undefined && LEVEL_RANK[envelope.level] < LEVEL_RANK[query.minimumLevel])
+        return false;
+    if (query.pattern !== undefined
+        && !JSON.stringify(envelope).toLocaleLowerCase('en-US').includes(query.pattern.toLocaleLowerCase('en-US')))
+        return false;
+    return true;
+}
+function compareCandidates(left, right) {
+    if (left.item.effectiveTsMs !== right.item.effectiveTsMs)
+        return left.item.effectiveTsMs - right.item.effectiveTsMs;
+    if (left.orderSlot !== right.orderSlot)
+        return left.orderSlot < right.orderSlot ? -1 : 1;
+    if (left.generationRank !== right.generationRank)
+        return left.generationRank - right.generationRank;
+    return left.byteOffset - right.byteOffset;
+}
+function retainCandidate(state, candidate) {
+    const values = state.candidates;
+    if (values.length === SNAPSHOT_ITEMS && compareCandidates(candidate, values[0]) <= 0)
+        return;
+    let low = 0;
+    let high = values.length;
+    while (low < high) {
+        const middle = Math.floor((low + high) / 2);
+        if (compareCandidates(values[middle], candidate) <= 0)
+            low = middle + 1;
+        else
+            high = middle;
+    }
+    values.splice(low, 0, candidate);
+    if (values.length > SNAPSHOT_ITEMS)
+        values.shift();
+}
+function hasNonblank(bytes) {
+    for (const byte of bytes)
+        if (byte !== 0x20 && byte !== 0x09 && byte !== 0x0d)
+            return true;
+    return false;
+}
+function sourcePath(source) {
+    return source.generation === 0 ? source.activeAbsolute : `${source.activeAbsolute}.${source.generation}`;
+}
+function scanCanonicalSource(state, home, directories, source) {
+    const absolute = sourcePath(source);
+    const file = readOwnedFile(home, directories, absolute, MAX_CANONICAL_SOURCE_BYTES);
+    if (file === undefined)
+        return;
+    const relativeName = relative(home, absolute);
+    let lineStart = 0;
+    const bound = file.start > 0;
+    let corrupt = false;
+    const sourceItems = [];
+    if (bound) {
+        const firstLf = file.bytes.indexOf(0x0a);
+        if (firstLf < 0)
+            return;
+        lineStart = firstLf + 1;
+    }
+    for (;;) {
+        const lf = file.bytes.indexOf(0x0a, lineStart);
+        if (lf < 0)
+            break;
+        const parsed = parseCanonicalLine(file.bytes.subarray(lineStart, lf));
+        if (parsed === undefined || !descriptorMatches(source, parsed.envelope)) {
+            state.invalidCanonicalLines += 1;
+            corrupt = true;
+        }
+        else if (matchesCanonical(state.query, source, parsed)) {
+            const byteOffset = file.start + lineStart;
+            const item = {
+                kind: 'event',
+                envelope: parsed.envelope,
+                source: relativeName,
+                streamKey: source.streamKey,
+                generation: source.generation,
+                byteOffset,
+                effectiveTsMs: parsed.effectiveTsMs,
+                truncated: false,
+            };
+            sourceItems.push(item);
+            retainCandidate(state, {
+                item,
+                orderSlot: source.streamKey,
+                generationRank: GENERATION_RANK[source.generation],
+                byteOffset,
+            });
+        }
+        lineStart = lf + 1;
+    }
+    if (lineStart < file.bytes.length && hasNonblank(file.bytes.subarray(lineStart))) {
+        state.invalidCanonicalLines += 1;
+        corrupt = true;
+    }
+    if (bound || corrupt) {
+        for (const item of sourceItems)
+            item.truncated = true;
+    }
+}
+function rawTimestamp(content, fallback) {
+    const token = /^(\S+)/u.exec(content)?.[1];
+    if (token !== undefined && ISO_TIMESTAMP.test(token)) {
+        const parsed = Date.parse(token);
+        if (Number.isFinite(parsed))
+            return parsed;
+    }
+    return fallback;
+}
+function matchesRaw(query, component, content, effectiveTsMs) {
+    if (query.nodeId !== undefined && component === 'daemon' && !content.includes(query.nodeId))
+        return false;
+    if (query.sinceMs !== undefined && effectiveTsMs < query.sinceMs)
+        return false;
+    if (query.untilMs !== undefined && effectiveTsMs > query.untilMs)
+        return false;
+    return query.pattern === undefined
+        || content.toLocaleLowerCase('en-US').includes(query.pattern.toLocaleLowerCase('en-US'));
+}
+function scanRawSource(state, home, directories, absolute, component) {
+    const file = readOwnedFile(home, directories, absolute, MAX_RAW_SOURCE_BYTES);
+    if (file === undefined)
+        return;
+    const relativeName = relative(home, absolute);
+    const truncated = file.start > 0;
+    let lineStart = 0;
+    if (truncated) {
+        const firstLf = file.bytes.indexOf(0x0a);
+        if (firstLf < 0)
+            return;
+        lineStart = firstLf + 1;
+    }
+    for (;;) {
+        const lf = file.bytes.indexOf(0x0a, lineStart);
+        if (lf < 0 && lineStart === file.bytes.length)
+            return;
+        const lineEnd = lf < 0 ? file.bytes.length : lf;
+        const content = file.bytes.subarray(lineStart, lineEnd).toString('utf8');
+        const effectiveTsMs = rawTimestamp(content, file.mtimeMs);
+        if (matchesRaw(state.query, component, content, effectiveTsMs)) {
+            const byteOffset = file.start + lineStart;
+            const item = { kind: 'raw', component, source: relativeName, content, effectiveTsMs, truncated };
+            retainCandidate(state, { item, orderSlot: relativeName, generationRank: 2, byteOffset });
+        }
+        if (lf < 0)
+            return;
+        lineStart = lf + 1;
+    }
+}
+function scanCanonicalGenerations(state, home, directories, source) {
+    for (const generation of [2, 1, 0])
+        scanCanonicalSource(state, home, directories, { ...source, generation });
+}
+function scanBrokerNode(state, home, parents, nodeId, canonical, raw) {
+    const nodeAbsolute = join(parents[parents.length - 1].absolute, nodeId);
+    const node = proveDirectory(home, nodeAbsolute, parents, true);
+    if (node === undefined)
+        return;
+    const jobAbsolute = join(nodeAbsolute, 'job');
+    const job = proveDirectory(home, jobAbsolute, [...parents, node], true);
+    if (job === undefined)
+        return;
+    const directories = [...parents, node, job];
+    if (canonical) {
+        scanCanonicalGenerations(state, home, directories, {
+            component: 'broker',
+            streamKey: `broker:${nodeId}`,
+            activeAbsolute: join(jobAbsolute, 'log.jsonl'),
+            boundNodeId: nodeId,
+        });
+    }
+    if (raw)
+        scanRawSource(state, home, directories, join(jobAbsolute, 'broker.log'), 'broker');
+}
+export function readLogSnapshot(query, includeRaw) {
+    const normalized = normalizeQuery(query);
+    if (typeof includeRaw !== 'boolean')
+        throw new TypeError('includeRaw must be boolean');
+    const state = { query: normalized, candidates: [], invalidCanonicalLines: 0 };
+    const home = resolve(crtrHome());
+    const root = proveDirectory(home, home, [], true);
+    if (root === undefined)
+        return { items: [], invalidCanonicalLines: 0 };
+    const rootChain = [root];
+    const rawCompatible = includeRaw && normalized.operationId === undefined && normalized.minimumLevel === undefined;
+    if (selected(normalized, 'daemon')) {
+        scanCanonicalGenerations(state, home, rootChain, {
+            component: 'daemon',
+            streamKey: 'daemon',
+            activeAbsolute: join(home, 'crtrd.log'),
+        });
+        if (rawCompatible)
+            scanRawSource(state, home, rootChain, join(home, 'crtrd.err'), 'daemon');
+    }
+    const canonicalBroker = selected(normalized, 'broker');
+    const rawBroker = rawCompatible && selected(normalized, 'broker');
+    if (canonicalBroker || rawBroker) {
+        const nodesAbsolute = resolve(nodesRoot());
+        const nodes = proveDirectory(home, nodesAbsolute, rootChain, true);
+        if (nodes !== undefined) {
+            const parents = [root, nodes];
+            if (normalized.nodeId !== undefined) {
+                scanBrokerNode(state, home, parents, normalized.nodeId, canonicalBroker, rawBroker);
+            }
+            else {
+                forEachDirectoryEntry(nodes, (nodeId, isDirectory) => {
+                    // The node root may contain ordinary filesystem metadata such as
+                    // .DS_Store. Only a directory can be a node; proveDirectory still
+                    // revalidates it to reject a replacement or symlink race.
+                    if (isDirectory && isSafeNodeId(nodeId))
+                        scanBrokerNode(state, home, parents, nodeId, canonicalBroker, rawBroker);
+                });
+            }
+        }
+    }
+    return {
+        items: state.candidates.map((candidate) => candidate.item),
+        invalidCanonicalLines: state.invalidCanonicalLines,
+    };
+}
+export function projectTier1Event(envelope) {
+    const projected = {
+        v: envelope.v,
+        ts: envelope.ts,
+        level: envelope.level,
+        event: envelope.event,
+        component: envelope.component,
+        operation_id: envelope.operation_id,
+    };
+    if (envelope.node_id !== undefined)
+        projected.node_id = envelope.node_id;
+    if (envelope.stream_id !== undefined)
+        projected.stream_id = envelope.stream_id;
+    if (envelope.duration_ms !== undefined)
+        projected.duration_ms = envelope.duration_ms;
+    if (envelope.outcome !== undefined)
+        projected.outcome = envelope.outcome;
+    if (envelope.attempt !== undefined)
+        projected.attempt = envelope.attempt;
+    if (envelope.error_class !== undefined)
+        projected.error_class = envelope.error_class;
+    return projected;
+}