nilometer 0.0.0-stage → 0.1.0

package/dist/core/ingest/derive.js

@@ -0,0 +1,212 @@
+/**
+ * @file Filling the derived tables from raw lines (docs/development.md P4.4, D-002).
+ *
+ * Each raw line derives independently of every other line, so new lines can be derived as they
+ * arrive, and a full rebuild produces the same rows. Cross-line logic (dedup winners, totals) lives
+ * in SQL views over these tables.
+ */
+import { blobBytes, transaction } from "../db/database.js";
+import { classifyLine, extractEvent, extractLinks, extractRequest, identityString, parseLine, parseTimestamp, } from "./classify.js";
+import { resolveResetTime } from "./reset-time.js";
+import { deriveNewSpoolLines } from "./spool.js";
+/**
+ * Version of the derivation rules. Bump it whenever classify.ts or this file changes what a raw line
+ * derives to; the next open rebuilds every derived row.
+ */
+export const PARSER_VERSION = "7";
+/** Classes that produce an event row. */
+const EVENT_CLASSES = new Set([
+    "limit_hit",
+    "api_error",
+    "synthetic_other",
+    "retry_notice",
+    "model_fallback",
+]);
+/** Links of a line that didn't parse. */
+const NO_LINKS = {
+    uuid: null,
+    parentUuid: null,
+    originKind: null,
+    userContent: null,
+    isMeta: false,
+};
+/**
+ * Returns a value when it's a string, else null.
+ * @param value - Any parsed JSON value.
+ * @returns The string or null.
+ */
+function stringOrNull(value) {
+    return typeof value === "string" ? value : null;
+}
+/**
+ * Derives every row one raw line produces. Pure: no database access.
+ * @param bytes - The raw line's exact bytes.
+ * @returns Parsed fields, optional request and event fields, and problems.
+ */
+export function deriveLine(bytes) {
+    const line = parseLine(bytes);
+    const lineClass = classifyLine(line);
+    if (line === null) {
+        return {
+            parsed: {
+                lineClass,
+                sessionId: null,
+                type: null,
+                subtype: null,
+                timestampRaw: null,
+                timestampUtc: null,
+                cwd: null,
+                gitBranch: null,
+                ccVersion: null,
+                isSidechain: false,
+            },
+            links: NO_LINKS,
+            request: null,
+            event: null,
+            resetAtUtc: null,
+            problems: [],
+        };
+    }
+    const timestamp = parseTimestamp(line["timestamp"]);
+    const problems = [];
+    let request = null;
+    if (lineClass === "request") {
+        request = extractRequest(line);
+        for (const field of request.missingFields) {
+            problems.push(["missing_field", field]);
+        }
+        // The raw value is kept as JSON text so a number, null, or absent timestamp stays distinguishable.
+        if (timestamp === null) {
+            problems.push(["unparsed_timestamp", JSON.stringify(line["timestamp"] ?? null)]);
+        }
+        for (const type of request.nonMessageIterations) {
+            problems.push(["non_message_iteration", type]);
+        }
+    }
+    const event = EVENT_CLASSES.has(lineClass) ? extractEvent(line, lineClass) : null;
+    // Only limit hits carry reset text, so every other event resolves to null here.
+    const textResetAtUtc = resolveResetTime(event?.resetText ?? null, timestamp?.utc ?? null);
+    if (event !== null) {
+        problems.push(...quotaProblems(event, textResetAtUtc));
+    }
+    return {
+        parsed: {
+            lineClass,
+            sessionId: identityString(line["sessionId"]),
+            type: identityString(line["type"]),
+            subtype: stringOrNull(line["subtype"]),
+            timestampRaw: line["timestamp"] === undefined ? null : JSON.stringify(line["timestamp"]),
+            timestampUtc: timestamp?.utc ?? null,
+            cwd: stringOrNull(line["cwd"]),
+            gitBranch: stringOrNull(line["gitBranch"]),
+            ccVersion: stringOrNull(line["version"]),
+            isSidechain: line["isSidechain"] === true,
+        },
+        links: extractLinks(line),
+        request,
+        event,
+        resetAtUtc: textResetAtUtc,
+        problems,
+    };
+}
+/**
+ * Lists what's wrong with a limit hit's `quotaLimits` (D-067): unusable members, and a window or
+ * reset that disagrees with the message text. Nothing is corrected here; the views prefer the
+ * structured fields, and these problems say where the two sources differed.
+ * @param event - The line's event fields.
+ * @param textResetAtUtc - The reset text resolved against the hit's timestamp, or null.
+ * @returns `[problem, detail]` pairs; empty for lines that aren't limit hits.
+ */
+export function quotaProblems(event, textResetAtUtc) {
+    const problems = event.quota.unusable.map((field) => [
+        "unusable_quota_field",
+        field,
+    ]);
+    const quotaWindow = event.quota.window;
+    if (quotaWindow !== null && event.window !== null && quotaWindow !== event.window) {
+        problems.push(["quota_window_disagrees", `quotaLimits=${quotaWindow} text=${event.window}`]);
+    }
+    const quotaReset = event.quota.resetsAtUtc;
+    // Reset text has minute precision, so only a gap of a minute or more is a disagreement.
+    if (quotaReset !== null &&
+        textResetAtUtc !== null &&
+        Math.abs(Date.parse(quotaReset) - Date.parse(textResetAtUtc)) >= 60_000) {
+        problems.push(["quota_reset_disagrees", `quotaLimits=${quotaReset} text=${textResetAtUtc}`]);
+    }
+    return problems;
+}
+/**
+ * Derives and stores rows for every session-log raw line that has none yet. Spool lines are
+ * derived by `deriveNewSpoolLines` instead.
+ * @param db - Open, migrated database.
+ * @returns Number of log lines derived.
+ */
+export function deriveNewLines(db) {
+    const pending = db
+        .prepare(`SELECT l.id, l.bytes FROM raw_lines l
+       JOIN source_files f ON f.id = l.source_file_id AND f.kind = 'log'
+       LEFT JOIN parsed_lines p ON p.raw_line_id = l.id
+       WHERE p.raw_line_id IS NULL ORDER BY l.id`)
+        .all();
+    const insertParsed = db.prepare("INSERT INTO parsed_lines (raw_line_id, class, session_id, type, subtype, timestamp_raw, timestamp_utc, cwd, git_branch, cc_version, is_sidechain, uuid, parent_uuid, origin_kind, user_content, is_meta) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)");
+    const insertRequest = db.prepare("INSERT INTO requests (raw_line_id, dedup_key, message_id, request_id, model, input_tokens, output_tokens, cache_read_tokens, cache_write_5m_tokens, cache_write_1h_tokens, cache_write_unsplit_tokens, speed, service_tier, inference_geo) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)");
+    const insertEvent = db.prepare("INSERT INTO events (raw_line_id, class, error, api_error_status, window, reset_text, unknown_error_key, retry_rate_limits_present, reset_at_utc, quota_window, quota_resets_at_utc, fallback_original_model, fallback_model, fallback_request_id, refusal_category) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)");
+    const insertProblem = db.prepare("INSERT INTO line_problems (raw_line_id, problem, detail) VALUES (?, ?, ?)");
+    transaction(db, () => {
+        for (const { id, bytes } of pending) {
+            const derived = deriveLine(blobBytes(bytes));
+            const p = derived.parsed;
+            insertParsed.run(id, p.lineClass, p.sessionId, p.type, p.subtype, p.timestampRaw, p.timestampUtc, p.cwd, p.gitBranch, p.ccVersion, p.isSidechain ? 1 : 0, derived.links.uuid, derived.links.parentUuid, derived.links.originKind, derived.links.userContent, derived.links.isMeta ? 1 : 0);
+            const r = derived.request;
+            if (r !== null) {
+                insertRequest.run(id, r.dedupKey, r.messageId, r.requestId, r.model, r.inputTokens, r.outputTokens, r.cacheReadTokens, r.cacheWrite5mTokens, r.cacheWrite1hTokens, r.cacheWriteUnsplitTokens, r.speed, r.serviceTier, r.inferenceGeo);
+            }
+            const e = derived.event;
+            if (e !== null) {
+                insertEvent.run(id, p.lineClass, e.error, e.apiErrorStatus, e.window, e.resetText, e.unknownErrorKey, e.retryRateLimitsPresent ? 1 : 0, derived.resetAtUtc, e.quota.window, e.quota.resetsAtUtc, e.fallback.originalModel, e.fallback.fallbackModel, e.fallback.requestId, e.fallback.refusalCategory);
+            }
+            for (const [problem, detail] of derived.problems) {
+                insertProblem.run(id, problem, detail);
+            }
+        }
+    });
+    return pending.length;
+}
+/** Derived tables, in the order they're cleared (children before parents). */
+export const DERIVED_TABLES = [
+    "line_problems",
+    "events",
+    "requests",
+    "parsed_lines",
+    "rate_limit_windows",
+    "status_readings",
+];
+/**
+ * Deletes every derived row and derives again from raw lines, recording the parser version.
+ * @param db - Open, migrated database.
+ * @returns Number of raw lines derived (log and spool).
+ */
+export function rebuildDerived(db) {
+    return transaction(db, () => {
+        for (const table of DERIVED_TABLES) {
+            db.prepare(`DELETE FROM ${table}`).run();
+        }
+        const count = deriveNewLines(db) + deriveNewSpoolLines(db);
+        db.prepare("INSERT INTO derive_meta (key, value) VALUES ('parser_version', ?) ON CONFLICT (key) DO UPDATE SET value = excluded.value").run(PARSER_VERSION);
+        return count;
+    });
+}
+/**
+ * Brings derived tables up to date: a full rebuild if the parser version changed, otherwise only
+ * the raw lines not yet derived.
+ * @param db - Open, migrated database.
+ * @returns Number of raw lines derived and whether a rebuild happened.
+ */
+export function ensureDerived(db) {
+    const row = db.prepare("SELECT value FROM derive_meta WHERE key = 'parser_version'").get();
+    if (row?.value !== PARSER_VERSION) {
+        return { derived: rebuildDerived(db), rebuilt: true };
+    }
+    return { derived: deriveNewLines(db) + deriveNewSpoolLines(db), rebuilt: false };
+}
+//# sourceMappingURL=derive.js.map

package/dist/core/ingest/discover.js

@@ -0,0 +1,126 @@
+/**
+ * @file Finding Claude Code session logs (docs/development.md P4.1, `ingest-session-logs` skill § 1).
+ *
+ * Roots follow ccusage's resolution so both tools read the same logs (D-011): an explicit
+ * `CLAUDE_CONFIG_DIR` (comma-separated) wins; otherwise `$XDG_CONFIG_HOME/claude` and `~/.claude`.
+ * Each root's `projects/` tree is walked with no depth limit, because subagent transcripts live
+ * below session directories and a depth cap silently misses them (haasonsaas).
+ */
+import { readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { expandHome } from "../util/paths.js";
+/** `CLAUDE_CONFIG_DIR` is set but names no usable directory. Nothing is read when this is raised. */
+export class DiscoveryError extends Error {
+    /**
+     * Creates a discovery error.
+     * @param message - What is wrong.
+     */
+    constructor(message) {
+        super(message);
+        this.name = "DiscoveryError";
+    }
+}
+/**
+ * Reports whether a path is an existing directory.
+ * @param path - Path to test.
+ * @returns True for a directory; false if missing, not a directory, or unreadable.
+ */
+export function isDirectory(path) {
+    try {
+        return statSync(path).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Resolves the roots whose `projects/` directories hold session logs.
+ * @param env - Relevant environment variables.
+ * @param home - The user's home directory.
+ * @param isDir - Directory test, injectable for tests.
+ * @returns Roots in priority order, each containing a `projects/` directory; may be empty.
+ * @throws {DiscoveryError} If `CLAUDE_CONFIG_DIR` is set and none of its entries has `projects/`.
+ */
+export function resolveRoots(env, home, isDir = isDirectory) {
+    const explicit = env.CLAUDE_CONFIG_DIR?.trim();
+    if (explicit !== undefined && explicit !== "") {
+        const entries = explicit
+            .split(",")
+            .map((entry) => entry.trim())
+            .filter((entry) => entry !== "")
+            .map((entry) => expandHome(entry, home));
+        const roots = unique(entries.filter((root) => isDir(join(root, "projects"))));
+        // An explicit setting that matches nothing is a mistake worth stopping for, not an empty report.
+        if (roots.length === 0) {
+            throw new DiscoveryError(`CLAUDE_CONFIG_DIR is set but none of its entries contains a projects/ directory: ${explicit}`);
+        }
+        return roots;
+    }
+    const candidates = [];
+    const xdg = env.XDG_CONFIG_HOME;
+    if (xdg !== undefined && xdg.startsWith("/")) {
+        candidates.push(join(xdg, "claude"));
+    }
+    candidates.push(join(home, ".claude"));
+    return unique(candidates.filter((root) => isDir(join(root, "projects"))));
+}
+/**
+ * Removes repeated strings, keeping the first occurrence.
+ * @param values - Values in priority order.
+ * @returns The values without repeats, order preserved.
+ */
+export function unique(values) {
+    return [...new Set(values)];
+}
+/**
+ * Compares two strings by their UTF-8 bytes, the order fixtures/README.md defines for files.
+ * @param a - First string.
+ * @param b - Second string.
+ * @returns Negative, zero, or positive, like `Array.prototype.sort` expects.
+ */
+export function compareBytes(a, b) {
+    // JavaScript's default string order is by UTF-16 code unit, which differs from byte order
+    // for characters outside the Basic Multilingual Plane.
+    return Buffer.compare(Buffer.from(a, "utf8"), Buffer.from(b, "utf8"));
+}
+/**
+ * Lists every `.jsonl` file under a root's `projects/` directory.
+ * @param root - A root from {@link resolveRoots}.
+ * @param listDir - Directory listing; defaults to the real filesystem.
+ * @param onUnreadable - Called with the path of a folder that can't be listed (deleted mid-run, or
+ *   permission denied). The folder is skipped instead of failing the run (D-050).
+ * @returns Paths relative to the root (starting `projects/`), joined with `/` on every platform and
+ *   sorted by UTF-8 bytes.
+ */
+export function discoverLogFiles(root, listDir = (path) => readdirSync(path, { withFileTypes: true }), onUnreadable = () => undefined) {
+    const found = [];
+    /**
+     * Walks one directory, collecting `.jsonl` files.
+     * @param relative - Directory path relative to the root.
+     */
+    const walk = (relative) => {
+        let entries;
+        try {
+            entries = listDir(join(root, relative));
+        }
+        catch {
+            onUnreadable(join(root, relative));
+            return;
+        }
+        for (const entry of entries) {
+            // "/" on every platform, so stored paths, fixtures, and explain's locations match on Windows (D-049).
+            const child = `${relative}/${entry.name}`;
+            if (entry.isDirectory()) {
+                walk(child);
+            }
+            else if (entry.isFile() && entry.name.endsWith(".jsonl")) {
+                // Symlinks are neither files nor directories to Dirent, so they're skipped: following
+                // them could loop or read outside the root.
+                found.push(child);
+            }
+        }
+    };
+    walk("projects");
+    return found.sort(compareBytes);
+}
+//# sourceMappingURL=discover.js.map

package/dist/core/ingest/ingest.js

@@ -0,0 +1,160 @@
+/**
+ * @file One ingest run over session logs: discover, read new lines, store them (docs/development.md P4.3).
+ *
+ * Implements README § How it works (copy logs into SQLite before Claude Code deletes them) with
+ * D-002 and D-003. Derived tables (classification, requests, events) are refreshed from raw lines by
+ * later steps; this module only makes sure every complete line on disk is stored exactly once.
+ */
+import { existsSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { transaction } from "../db/database.js";
+import { discoverLogFiles } from "./discover.js";
+import { DEFAULT_CHUNK_SIZE, readCompleteLines, readStart } from "./reader.js";
+import { finishRun, findOrCreateSourceFile, rawLineWriter, recordProblem, saveFileState, startRun, } from "./store.js";
+/**
+ * Reads a file's size and inode.
+ * @param path - File path.
+ * @param statImpl - Stat function, injectable so a zero inode can be tested.
+ * @returns Size in bytes and inode (null when the platform reports 0).
+ */
+export function statFile(path, statImpl = statSync) {
+    const stats = statImpl(path);
+    // Some filesystems report inode 0 when they have none; treat that as unknown, not as a value.
+    return { size: stats.size, inode: stats.ino === 0 ? null : stats.ino };
+}
+/** File name of the hook's spool inside the data directory (hooks/statusline.sh). */
+export const SPOOL_FILE = "statusline.spool.jsonl";
+/**
+ * Rewrites log paths stored with Windows separators to use `/` (D-049).
+ *
+ * Until 2026-09-17, discovery joined relative paths with the platform separator, so a database
+ * built on Windows holds `projects\...`. Discovery now always uses `/`; without this rewrite every
+ * existing file would look new and its lines would be stored again.
+ * @param db - Open, migrated database.
+ * @param platform - The platform. Only Windows rows are rewritten: `\` can't appear in a Windows
+ *   file name, so there it is always a separator, but it can be part of a POSIX file name.
+ * @returns How many rows were rewritten.
+ */
+export function normalizeWindowsRelativePaths(db, platform) {
+    if (platform !== "win32") {
+        return 0;
+    }
+    // node:sqlite types changes as number or bigint; a row count here never nears 2^53.
+    return Number(db
+        .prepare("UPDATE source_files SET relative_path = replace(relative_path, char(92), '/') WHERE kind = 'log' AND instr(relative_path, char(92)) > 0")
+        .run().changes);
+}
+/**
+ * Reads one file's new complete lines into raw_lines and saves its position, in one transaction.
+ * @param db - Open, migrated database.
+ * @param file - Kind, root, and path below the root.
+ * @param run - The current run's ID, options, stat function, and counters to update.
+ */
+function ingestFile(db, file, run) {
+    const { runId, options, counts } = run;
+    const path = join(file.root, file.relativePath);
+    const current = run.stat(path);
+    counts.files += 1;
+    if (file.kind === "log") {
+        counts.logFiles += 1;
+    }
+    // One transaction per file: its lines and its new offset commit together, so a crash can
+    // never save an offset past lines that weren't stored.
+    transaction(db, () => {
+        const row = findOrCreateSourceFile(db, { ...file, stat: current }, runId);
+        const start = options.mode === "full"
+            ? { byteOffset: 0, lineCount: 0, rewritten: false }
+            : readStart(row.state, current);
+        if (start.rewritten) {
+            counts.filesRewritten += 1;
+            recordProblem(db, {
+                runId,
+                fileId: row.id,
+                problem: "file_rewritten",
+                detail: `size ${current.size} is below the stored offset ${row.state?.byteOffset ?? 0}, or the inode changed; reread from the start`,
+            });
+        }
+        const store = rawLineWriter(db, row.id, runId);
+        const result = readCompleteLines(path, start, (line) => {
+            if (store(line)) {
+                counts.linesStored += 1;
+            }
+        }, options.chunkSize ?? DEFAULT_CHUNK_SIZE);
+        counts.linesRead += result.linesRead;
+        saveFileState(db, row.id, {
+            byteOffset: result.byteOffset,
+            lineCount: result.lineCount,
+            size: current.size,
+            inode: current.inode,
+        }, runId);
+    });
+}
+/**
+ * Runs one ingest over every log file under the given roots, then the spool if one is configured.
+ * @param db - Open, migrated database.
+ * @param options - Roots, mode, clock, optional spool directory, chunk size, and stat.
+ * @returns Counts describing the run.
+ * @throws {Error} Whatever reading a file throws; each file is written in its own transaction, so
+ *   files finished before the error stay stored, and the run is left unfinished.
+ */
+export function ingestLogs(db, options) {
+    // Before comparing discovered paths with stored ones, so a Windows database's files aren't read twice.
+    normalizeWindowsRelativePaths(db, options.platform ?? process.platform);
+    const stat = options.stat ?? ((path) => statFile(path));
+    const runId = startRun(db, options.mode, options.now());
+    const counts = {
+        logFiles: 0,
+        files: 0,
+        unreadable: 0,
+        linesRead: 0,
+        linesStored: 0,
+        filesRewritten: 0,
+    };
+    const run = { runId, options, stat, counts };
+    for (const root of options.roots) {
+        for (const relativePath of discoverLogFiles(root, options.listDir, () => {
+            counts.unreadable += 1;
+        })) {
+            readFileOrCount(db, { kind: "log", root, relativePath }, run);
+        }
+    }
+    const spoolRead = options.spoolDir !== undefined && existsSync(join(options.spoolDir, SPOOL_FILE));
+    if (spoolRead) {
+        readFileOrCount(db, { kind: "spool", root: options.spoolDir, relativePath: SPOOL_FILE }, run);
+    }
+    finishRun(db, runId, options.now());
+    return {
+        runId,
+        files: counts.files,
+        logFiles: counts.logFiles,
+        spoolRead,
+        linesRead: counts.linesRead,
+        linesStored: counts.linesStored,
+        linesAlreadyStored: counts.linesRead - counts.linesStored,
+        filesRewritten: counts.filesRewritten,
+        unreadable: counts.unreadable,
+    };
+}
+/**
+ * Ingests one file, counting it as unreadable instead of failing the run (D-050).
+ *
+ * A session log can be deleted between discovery and open (Claude Code removes them after 30 days),
+ * or be unreadable. Either would otherwise abort the run with a stack trace, leaving the run
+ * unfinished and, during `init`, landing after settings.json was already changed.
+ * @param db - Open, migrated database.
+ * @param file - Kind, root, and path below the root.
+ * @param run - The current run's context.
+ * @throws {unknown} Anything that isn't a filesystem error, since that would be a bug.
+ */
+function readFileOrCount(db, file, run) {
+    try {
+        ingestFile(db, file, run);
+    }
+    catch (error) {
+        if (error.code === undefined) {
+            throw error;
+        }
+        run.counts.unreadable += 1;
+    }
+}
+//# sourceMappingURL=ingest.js.map

package/dist/core/ingest/reader.js

@@ -0,0 +1,89 @@
+/**
+ * @file Reading complete lines from a file, starting at a stored byte offset (docs/development.md P4.2, D-003).
+ *
+ * The reader never loads a whole file: it reads fixed-size chunks and hands each complete line to
+ * a callback. A trailing fragment without a newline isn't consumed, so the next run reads it once
+ * it's complete. Counting a half-written line and then skipping it forever is how phuryn's scanner
+ * lost turns.
+ */
+import { closeSync, openSync, readSync } from "node:fs";
+/**
+ * Decides where to resume reading a file.
+ * @param state - What was stored after the last read, or null for a file never seen.
+ * @param stat - The file's current size and inode.
+ * @returns The offset and line count to start from, and whether a rewrite was detected.
+ */
+export function readStart(state, stat) {
+    if (state === null) {
+        return { byteOffset: 0, lineCount: 0, rewritten: false };
+    }
+    // A shorter file or a different inode means the bytes before our offset are no longer the ones
+    // we read. Restart; raw-line identity makes rereading unchanged lines a no-op (D-002).
+    const inodeChanged = state.inode !== null && stat.inode !== null && state.inode !== stat.inode;
+    if (stat.size < state.byteOffset || inodeChanged) {
+        return { byteOffset: 0, lineCount: 0, rewritten: true };
+    }
+    return { byteOffset: state.byteOffset, lineCount: state.lineCount, rewritten: false };
+}
+/** Default chunk size: large enough to be fast, small enough to bound memory on huge files. */
+export const DEFAULT_CHUNK_SIZE = 64 * 1024;
+/** The real filesystem implementation of {@link ReaderFs}. */
+export const NODE_READER_FS = {
+    open: (path) => openSync(path, "r"),
+    read: (fd, buffer, length, position) => readSync(fd, buffer, 0, length, position),
+    close: (fd) => {
+        closeSync(fd);
+    },
+};
+/**
+ * Reads every complete line after `start`, calling `onLine` for each, in file order.
+ * @param path - File to read.
+ * @param start - Offset and line count to resume from.
+ * @param onLine - Receives each complete line.
+ * @param chunkSize - Bytes requested per read.
+ * @param fs - File operations; defaults to the real filesystem.
+ * @returns The new offset and line count, and how many lines were read.
+ * @throws {Error} Whatever the filesystem throws opening or reading; the descriptor is always closed.
+ */
+export function readCompleteLines(path, start, onLine, chunkSize = DEFAULT_CHUNK_SIZE, fs = NODE_READER_FS) {
+    const fd = fs.open(path);
+    try {
+        const chunk = Buffer.alloc(chunkSize);
+        // Bytes read but not yet ending in a newline: the start of a line that continues in the next chunk.
+        let pending = Buffer.alloc(0);
+        let pendingOffset = start.byteOffset;
+        let position = start.byteOffset;
+        let lineCount = start.lineCount;
+        let linesRead = 0;
+        for (;;) {
+            const bytesRead = fs.read(fd, chunk, chunkSize, position);
+            if (bytesRead === 0) {
+                break;
+            }
+            position += bytesRead;
+            const data = pending.length === 0
+                ? chunk.subarray(0, bytesRead)
+                : Buffer.concat([pending, chunk.subarray(0, bytesRead)]);
+            let lineStart = 0;
+            for (let newline = data.indexOf(0x0a); newline !== -1; newline = data.indexOf(0x0a, lineStart)) {
+                lineCount += 1;
+                linesRead += 1;
+                // Copy: `data` may be the reusable chunk buffer, which the next read overwrites.
+                onLine({
+                    bytes: Buffer.from(data.subarray(lineStart, newline)),
+                    offset: pendingOffset + lineStart,
+                    lineNumber: lineCount,
+                });
+                lineStart = newline + 1;
+            }
+            pendingOffset += lineStart;
+            pending = Buffer.from(data.subarray(lineStart));
+        }
+        // Whatever is still pending has no newline yet; the offset stays before it.
+        return { byteOffset: pendingOffset, lineCount, linesRead };
+    }
+    finally {
+        fs.close(fd);
+    }
+}
+//# sourceMappingURL=reader.js.map

package/dist/core/ingest/reset-time.js

@@ -0,0 +1,97 @@
+/**
+ * @file Resolving a limit hit's reset text to a UTC instant (D-023).
+ *
+ * Claude Code writes the reset time as wall-clock text in a named zone: "6:10am (<IANA zone>)".
+ * The text has no date, so the instant is the first matching wall-clock minute at or after the hit.
+ * Scanning whole UTC minutes, rather than converting local time to UTC arithmetically, gives one
+ * answer at DST changes without special cases: a repeated local time matches its first occurrence,
+ * and a skipped local time never matches that day, so the next day's occurrence is found.
+ */
+/** Reset text this module understands: `H[:MM]am|pm (Zone)`, case-insensitive. */
+const RESET_TEXT = /^(\d{1,2})(?::(\d{2}))?\s*(am|pm)\s*\(([^()]+)\)$/i;
+/** How far ahead of the hit the scan looks. A time of day recurs within 24 hours; DST adds at most one more. */
+export const RESET_SEARCH_MINUTES = 48 * 60;
+/** One minute in milliseconds. */
+const MINUTE_MS = 60_000;
+/**
+ * Builds a formatter that reads the 24-hour wall-clock hour and minute in a zone.
+ * @param zone - IANA zone name as written in the log.
+ * @returns The formatter, or null when the runtime doesn't know the zone.
+ */
+function wallClockFormatter(zone) {
+    try {
+        return new Intl.DateTimeFormat("en-US", {
+            timeZone: zone,
+            hourCycle: "h23",
+            hour: "2-digit",
+            minute: "2-digit",
+        });
+    }
+    catch {
+        // An unknown zone throws RangeError; the reset stays unknown rather than guessed.
+        return null;
+    }
+}
+/**
+ * Reads the wall-clock hour and minute of an instant.
+ * @param formatter - From {@link wallClockFormatter}.
+ * @param ms - Epoch milliseconds.
+ * @returns Hour 0–23 and minute 0–59 as the zone shows them.
+ */
+function wallClock(formatter, ms) {
+    let hour = -1;
+    let minute = -1;
+    for (const part of formatter.formatToParts(ms)) {
+        if (part.type === "hour") {
+            hour = Number(part.value);
+        }
+        else if (part.type === "minute") {
+            minute = Number(part.value);
+        }
+    }
+    return { hour, minute };
+}
+/**
+ * Resolves reset text to the UTC instant it names.
+ * @param resetText - The limit hit's reset text (`events.reset_text`), or null.
+ * @param hitUtc - The hit's UTC timestamp (`YYYY-MM-DDTHH:MM:SS.sssZ`), or null when it didn't parse.
+ * @returns `YYYY-MM-DDTHH:MM:00.000Z`, or null when either input is missing, the hit time doesn't
+ *   parse, the text isn't a 12-hour time with a zone, the hour or minute is out of range, the zone
+ *   is unknown, or no match is found within {@link RESET_SEARCH_MINUTES}.
+ * @example
+ * resolveResetTime("6:10am (UTC)", "2026-09-01T03:00:00.000Z"); // "2026-09-01T06:10:00.000Z"
+ */
+export function resolveResetTime(resetText, hitUtc) {
+    if (resetText === null || hitUtc === null) {
+        return null;
+    }
+    const match = RESET_TEXT.exec(resetText.trim());
+    if (match === null) {
+        return null;
+    }
+    const hour12 = Number(match[1]);
+    const minute = match[2] === undefined ? 0 : Number(match[2]);
+    if (hour12 < 1 || hour12 > 12 || minute > 59) {
+        return null;
+    }
+    const formatter = wallClockFormatter(match[4].trim());
+    if (formatter === null) {
+        return null;
+    }
+    // 12am is hour 0 and 12pm is hour 12; every other pm hour adds 12.
+    const hour = (hour12 % 12) + (match[3].toLowerCase() === "pm" ? 12 : 0);
+    // Start at the hit's own minute: text shows minutes only, so a reset in the hit's minute is that minute.
+    const start = Math.floor(Date.parse(hitUtc) / MINUTE_MS) * MINUTE_MS;
+    if (Number.isNaN(start)) {
+        return null;
+    }
+    for (let step = 0; step <= RESET_SEARCH_MINUTES; step += 1) {
+        const ms = start + step * MINUTE_MS;
+        const clock = wallClock(formatter, ms);
+        if (clock.hour === hour && clock.minute === minute) {
+            return new Date(ms).toISOString();
+        }
+    }
+    return null;
+}
+//# sourceMappingURL=reset-time.js.map