@deksden-com/dd-console 0.0.0-stage → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,7 @@
+# @deksden-com/dd-console
+
+## 0.2.0
+
+### Minor Changes
+
+- eeed993: Ship the npm dd-console executable with foreground shutdown, detached start/stop/restart/status commands, build-aware replacement, and process identity checks. Add Changesets release automation.

package/README.md

@@ -1,3 +1,155 @@
-# Temporary Holding Version
+# dd-console
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Локальная веб-консоль для наблюдения за выполнением **dd-flow** и **dd-eval**.
+
+Один локальный сервер, два раздела — Flows и Evals, отдельные экраны детализации и навигация через breadcrumbs. Из execution эвала можно перейти во вложенный flow, затем в работу, сессию и её события.
+
+Статус: реализован первый локальный read-only выпуск. Сервер слушает только
+`127.0.0.1`, не запускает команды раннеров и не меняет их данные.
+
+- [План реализации: архитектура, экраны, API и приёмка](docs/implementation-plan.md)
+- [Очередь работ первого выпуска](docs/work-plan.md)
+- [Исследование существующих раннеров](docs/research.md)
+- [Поддерживаемые источники и версии](docs/compatibility.md)
+- [DTO, freshness и безопасное отображение](docs/data-contract.md)
+- [Фактическая приёмка и известные ограничения](docs/acceptance.md)
+
+Первый выпуск — живое наблюдение и просмотр истории. Раннеры сохраняют управление выполнением и своими данными; закрытие консоли не останавливает запуски. Управление pause/resume/stop запланировано следующим этапом.
+
+## Запуск
+
+Требуется Node.js 26 и macOS либо Linux/glibc. Проверки выполнены на macOS. В корне репозитория:
+
+```sh
+npm install
+npm run check
+npm run start:open
+```
+
+`npm start` запускает сервер без открытия браузера; `npm run start:open` — с открытием. Оба скрипта сначала собирают приложение. Дополнительные параметры передаются после `--`, например `npm start -- --port 8080`.
+
+`serve` добавляет доступные по умолчанию `~/.dd-flow` и `~/.dd-eval` в
+`~/.dd-console/sources.json`, затем печатает URL. Для другого расположения
+используйте `--flow-home` и `--eval-home`, либо управляйте реестром явно:
+
+```sh
+dd-console sources add --kind flow --path /path/to/dd-flow-home
+dd-console sources add --kind eval --path /path/to/dd-eval-home
+dd-console sources list
+dd-console sources remove SRC-…
+```
+
+Реестр записывается атомарно и блокируется на время изменения. Если файл
+повреждён, console оставляет его как есть и сообщает ошибку вместо перезаписи.
+Остановите foreground-сервер `Ctrl-C`.
+
+Установленный пакет использует ту же команду:
+
+```sh
+npm install -g @deksden-com/dd-console
+dd-console start --open
+```
+
+До первой публикации пакет можно установить из созданного
+`npm pack` tarball; инструкции выпуска приведены ниже. API не предназначен для удалённого доступа, а браузер не
+получает пути source и raw evidence. Для Flow используются короткие read-only
+транзакции SQLite с существующим WAL. Данные БД не меняются; служебные SHM
+read-marks обслуживает SQLite. Копирования живого DB/WAL нет.
+
+Файлы читаются через дескрипторы каталогов (`openat`/`O_NOFOLLOW`), а локальные
+locks используют `flock`. Для этих POSIX API используется пакет `koffi`.
+История событий доступна страницами; filters/sort/cursors сохраняются в URL.
+Артефакты receipt/stdout/stderr открываются в собственном экране с breadcrumbs.
+Preview ограничен 256 KiB за фрагмент, следующий фрагмент доступен по ссылке.
+
+Повторная проверка поставки: `npm run pack:check` после `npm run build`.
+[Отчёт об исправлениях ревью](docs/implementation-review.md).
+
+Для новых Eval `dd-eval` публикует рядом с `events.jsonl` файл
+`observation.json` (`dd-eval/observation@1`). Он даёт консоли сохранённое
+состояние Eval и executions без обращения к живому runner. Исторические Eval
+без этой проекции остаются доступными, но имеют явную отметку о частичном
+наблюдении.
+
+Список Flows объединяет самостоятельные запуски из Flow-источников и RUN из
+manifest-declared executions Eval с проверенным `managed-runtime.json`.
+Фильтр «Запущен через → Eval» оставляет только вложенные запуски. В строке видны
+полный RUN ID, проект, источник и ссылки на Eval/execution. Одинаковые RUN ID
+в разных runtime остаются отдельными записями. Удалённые или неподтверждённые
+runtime не восстанавливаются по догадке; старые статусы отражают сохранённые данные.
+
+### Local Eval home registry
+
+`~/.dd-eval/homes.json` is the shared registry, independent of `DD_EVAL_HOME`.
+The version 1 document contains `schema_version: 1` and `homes` entries with
+`id`, canonical `root`, `label`, `created_at` and `disabled` fields.
+Creating an Eval or requesting continuation registers its home automatically.
+An explicit removal stays disabled until explicitly added again.
+
+```sh
+dd-eval homes list
+dd-eval homes add --path /absolute/path/to/eval-home --label qualification
+dd-eval homes remove --id SRC-...
+```
+
+The console reads the registry on each request, keeps unavailable sources visible,
+and deduplicates it against its own sources. Local source removal overrides
+registry discovery in that console. A new home requires no console restart.
+Registry mutations use a process-owned lock and atomic replacement; malformed
+registry data is preserved and reported instead of reset.
+
+## CLI и фоновый сервер
+
+После публикации пакет устанавливается глобально:
+
+```sh
+npm install -g @deksden-com/dd-console
+dd-console                 # сервер в терминале; Ctrl-C останавливает его
+dd-console start --open    # сервер в фоне; завершение команды оставляет его работающим
+dd-console status          # состояние, URL
+dd-console stop            # дождаться завершения сервера и освобождения locks
+dd-console restart         # заменить процесс актуальной сборкой
+```
+
+По умолчанию используется `http://127.0.0.1:50036`; `--port` и
+`DD_CONSOLE_PORT` меняют порт. `--port 0` выбирает свободный порт.
+`serve` — явный вариант запуска в переднем плане.
+`start` повторно использует текущую сборку, при изменении ревизии заменяет её;
+`restart` всегда заменяет процесс и сохраняет текущий порт, если новый не указан.
+`--json` возвращает машиночитаемый результат.
+`status` возвращает код 1, если сервер остановлен или не отвечает.
+Остановка завершается успешно, даже если сервер уже остановлен.
+
+Один сервер на `DD_CONSOLE_HOME` (по умолчанию `~/.dd-console`).
+`server.json` хранит PID, URL, уникальную идентичность процесса и версию сборки;
+перед отправкой сигнала CLI сверяет идентичность с `/healthz`.
+Устаревший PID чужого процесса не получает сигнал.
+Вывод фонового процесса сохраняется в `~/.dd-console/server.log`.
+Фоновый режим не устанавливает системную службу: после перезагрузки компьютера
+нужно снова выполнить `dd-console start`. Закрытие браузера не останавливает сервер.
+
+В checkout доступны `npm run start:background`, `npm run stop`,
+`npm run restart`, `npm run status`. Команды запуска собирают актуальную ревизию.
+Установленный npm CLI запускается из любого каталога без TypeScript и пересборки.
+
+## Выпуск через Changesets
+
+```sh
+npm run changeset          # описание изменения и тип semver bump
+npm run version:release    # версии, CHANGELOG.md, package-lock.json
+npm run release            # сборка и публикация версий через Changesets
+```
+
+`Release console` в GitHub Actions запускается вручную на `main`:
+при наличии changeset создаёт/обновляет PR с версиями и changelog;
+после слияния этого PR повторный запуск публикует пакет.
+Проверки CLI и установки tarball выполняются перед публикацией.
+CI также проверяет пакет на macOS и Linux.
+
+Для публикации настройте npm Trusted Publisher для
+`deksden-com/dd-console`, workflow `release.yml`.
+Первая публикация нового пакета требует npm-аккаунта с правом публикации
+в scope `@deksden-com`; после создания пакета можно настроить Trusted Publisher.
+В GitHub включите разрешение Actions создавать pull requests.
+Непубликуемый исходный changeset хранится в `.changeset/console-lifecycle.md`;
+после `version:release` он превращается в запись changelog и новую версию.

package/dist/build.json

@@ -0,0 +1 @@
+{"version":"0.2.0","build_revision":"0.2.0+1791308847496"}

package/dist/cache.js

@@ -0,0 +1,52 @@
+/** Bounded in-process cache shared by every browser client.  It only retains
+ * normalized read models; no source files or raw transcripts are copied. */
+export class ReaderCache {
+    maxBytes;
+    maxInFlight;
+    #entries = new Map();
+    #inFlight = new Map();
+    #bytes = 0;
+    constructor(maxBytes = 64 * 1024 * 1024, maxInFlight = 32) {
+        this.maxBytes = maxBytes;
+        this.maxInFlight = maxInFlight;
+    }
+    async get(key, ttlMs, read, refresh = false) {
+        const hit = this.#entries.get(key);
+        if (!refresh && hit && hit.expiresAt > Date.now()) {
+            this.#entries.delete(key);
+            this.#entries.set(key, hit);
+            return hit.value;
+        }
+        const pending = this.#inFlight.get(key);
+        if (pending)
+            return pending;
+        if (this.#inFlight.size >= this.maxInFlight)
+            throw Object.assign(new Error("Очередь локального чтения занята."), { code: "reader_queue_busy" });
+        const stale = () => {
+            const value = hit?.value;
+            return value && Array.isArray(value.diagnostics) ? { ...value, diagnostics: [...value.diagnostics, { code: "reader_stale", severity: "warning", message: "Показано последнее успешное чтение; источник временно недоступен." }] } : undefined;
+        };
+        const task = read().then(value => {
+            if (value?.diagnostics?.some(item => item.severity === "error"))
+                return stale() ?? value;
+            this.store(key, value, ttlMs);
+            return value;
+        }).catch(error => { const value = stale(); if (value)
+            return value; throw error; }).finally(() => this.#inFlight.delete(key));
+        this.#inFlight.set(key, task);
+        return task;
+    }
+    store(key, value, ttlMs) {
+        const previous = this.#entries.get(key);
+        if (previous)
+            this.#bytes -= previous.bytes;
+        const bytes = Buffer.byteLength(JSON.stringify(value));
+        this.#entries.set(key, { value, expiresAt: Date.now() + ttlMs, bytes });
+        this.#bytes += bytes;
+        while (this.#bytes > this.maxBytes && this.#entries.size) {
+            const oldest = this.#entries.entries().next().value;
+            this.#entries.delete(oldest[0]);
+            this.#bytes -= oldest[1].bytes;
+        }
+    }
+}

package/dist/cli.js

@@ -0,0 +1,98 @@
+#!/usr/bin/env node
+import { spawn } from "node:child_process";
+import { ensureDefaultSources, loadSources, sourceAdd, sourceRemove } from "./sources.js";
+import { manageServer, serverStatus } from "./daemon.js";
+import { serve } from "./server.js";
+const argv = process.argv.slice(2);
+const command = !argv[0] || argv[0].startsWith("--") ? "serve" : argv.shift();
+const args = argv;
+const fail = (message) => { console.error(message); process.exit(2); };
+const usage = "Использование: dd-console [start|stop|restart|status|serve] [--port 50036] [--open] [--flow-home <path>] [--eval-home <path>] [--json] | sources list|add|remove";
+function options(items, values, flags) {
+    const result = new Map();
+    for (let index = 0; index < items.length; index += 1) {
+        const item = items[index];
+        if (flags.includes(item)) {
+            result.set(item, true);
+            continue;
+        }
+        if (!values.includes(item))
+            fail(usage);
+        const value = items[index + 1];
+        if (!value || value.startsWith("--"))
+            fail(usage);
+        result.set(item, value);
+        index += 1;
+    }
+    return result;
+}
+if (args.includes("--help") || command === "help") {
+    console.log(usage);
+    process.exit(0);
+}
+if (command === "stop" || command === "status") {
+    const values = options(args, [], ["--json"]);
+    const state = command === "status" ? await serverStatus() : await manageServer("stop", []);
+    console.log(values.get("--json") ? JSON.stringify(state) : `dd-console: ${state.status}${state.server ? ` ${state.server.url}` : ""}`);
+    if (command === "status" && state.status !== "running")
+        process.exitCode = 1;
+}
+else if (command === "start" || command === "restart") {
+    const values = options(args, ["--port", "--flow-home", "--eval-home"], ["--open", "--json"]);
+    const previous = command === "restart" ? await serverStatus() : undefined;
+    const port = Number(values.get("--port") ?? process.env.DD_CONSOLE_PORT ?? (previous?.server ? new URL(previous.server.url).port : "50036"));
+    if (!Number.isInteger(port) || port < 0 || port > 65535)
+        fail("--port должен быть числом 0..65535");
+    const forwarded = ["--port", String(port)];
+    for (const key of ["--flow-home", "--eval-home"])
+        if (typeof values.get(key) === "string")
+            forwarded.push(key, values.get(key));
+    const state = await manageServer(command, forwarded);
+    console.log(values.get("--json") ? JSON.stringify(state) : `dd-console: ${state.status} ${state.server.url}`);
+    if (values.get("--open"))
+        spawn(process.platform === "darwin" ? "open" : "xdg-open", [state.server.url], { stdio: "ignore", detached: true }).on("error", error => console.error(error.message)).unref();
+}
+else if (command === "sources") {
+    const [subcommand, ...subargs] = args;
+    if (subcommand === "list") {
+        if (subargs.length)
+            fail(usage);
+        console.log(JSON.stringify(await loadSources(), null, 2));
+    }
+    else if (subcommand === "add") {
+        const values = options(subargs, ["--kind", "--path", "--label"], []), kind = values.get("--kind"), target = values.get("--path"), label = values.get("--label");
+        if (kind !== "flow" && kind !== "eval")
+            fail("Использование: dd-console sources add --kind flow|eval --path <path> [--label <name>]");
+        if (typeof target !== "string")
+            fail("Использование: dd-console sources add --kind flow|eval --path <path> [--label <name>]");
+        console.log(JSON.stringify(await sourceAdd(kind, target, typeof label === "string" ? label : undefined), null, 2));
+    }
+    else if (subcommand === "remove") {
+        if (subargs.length !== 1 || subargs[0].startsWith("--"))
+            fail("Использование: dd-console sources remove <source-id>");
+        await sourceRemove(subargs[0]);
+    }
+    else
+        fail("Использование: dd-console sources list|add|remove");
+}
+else if (command === "serve") {
+    const values = options(args, ["--port", "--flow-home", "--eval-home"], ["--open", "--json"]), portValue = values.get("--port") ?? process.env.DD_CONSOLE_PORT ?? "50036", port = Number(portValue);
+    if (!Number.isInteger(port) || port < 0 || port > 65535)
+        fail("--port должен быть числом 0..65535");
+    const flowHome = values.get("--flow-home"), evalHome = values.get("--eval-home");
+    await ensureDefaultSources(typeof flowHome === "string" ? flowHome : undefined, typeof evalHome === "string" ? evalHome : undefined);
+    const { server, url, closed } = await serve(port, process.env), receipt = { ok: true, url };
+    if (values.get("--json"))
+        console.log(JSON.stringify(receipt));
+    else
+        console.log(`dd-console: ${url}`);
+    if (values.get("--open"))
+        spawn(process.platform === "darwin" ? "open" : "xdg-open", [url], { stdio: "ignore", detached: true }).on("error", error => console.error(error.message)).unref();
+    let stopping = false;
+    const close = () => { if (stopping)
+        return; stopping = true; server.close(); server.closeAllConnections(); void closed.then(() => { process.exitCode = 0; }, () => { process.exitCode = 1; }); };
+    process.on("SIGINT", close);
+    process.on("SIGTERM", close);
+}
+else
+    fail(usage);

package/dist/contracts.js

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

package/dist/daemon.js

@@ -0,0 +1,102 @@
+import { spawn } from "node:child_process";
+import { mkdir, open, readFile } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+import path from "node:path";
+import { acquireFileLock } from "./file-lock.js";
+import { consoleHome } from "./sources.js";
+const pause = () => new Promise(resolve => setTimeout(resolve, 100));
+const alive = (pid) => { try {
+    process.kill(pid, 0);
+    return true;
+}
+catch (error) {
+    if (error.code === "ESRCH")
+        return false;
+    throw error;
+} };
+export async function serverStatus(env = process.env) {
+    let server;
+    try {
+        server = JSON.parse(await readFile(path.join(consoleHome(env), "server.json"), "utf8"));
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return { status: "stopped" };
+        throw error;
+    }
+    if (!Number.isSafeInteger(server.pid) || server.pid <= 1 || typeof server.instance !== "string" || !/^http:\/\/127\.0\.0\.1:\d+$/.test(server.url))
+        throw new Error("Некорректный server.json; файл сохранён.");
+    if (!alive(server.pid))
+        return { status: "stopped" };
+    try {
+        const response = await fetch(`${server.url}/healthz`, { signal: AbortSignal.timeout(1_000) });
+        const health = await response.json();
+        if (response.ok && health.pid === server.pid && health.instance === server.instance)
+            return { status: "running", server };
+    }
+    catch { /* Never signal a process identified only by a stale PID. */ }
+    return { status: "unresponsive", server };
+}
+async function stop(env) {
+    const state = await serverStatus(env);
+    if (state.status === "stopped")
+        return state;
+    if (state.status !== "running")
+        throw new Error("Не удалось подтвердить процесс dd-console; сигнал не отправлен. Проверьте server.log.");
+    process.kill(state.server.pid, "SIGTERM");
+    for (let attempt = 0; attempt < 100; attempt++) {
+        if (!alive(state.server.pid))
+            return { status: "stopped" };
+        await pause();
+    }
+    throw new Error("dd-console не завершился за 10 секунд.");
+}
+export async function manageServer(command, args, env = process.env) {
+    const home = consoleHome(env);
+    await mkdir(home, { recursive: true, mode: 0o700 });
+    const release = await acquireFileLock(path.join(home, "control.lock"), 1_000, "Управление dd-console занято.");
+    try {
+        if (command === "stop")
+            return await stop(env);
+        if (command === "restart")
+            await stop(env);
+        const current = await serverStatus(env);
+        if (current.status === "unresponsive")
+            throw new Error("dd-console не отвечает; проверьте server.log.");
+        const build = JSON.parse(await readFile(new URL("./build.json", import.meta.url), "utf8"));
+        if (current.status === "running") {
+            if (current.server.build_revision === build.build_revision)
+                return current;
+            await stop(env);
+        }
+        const log = await open(path.join(home, "server.log"), "a", 0o600);
+        const child = spawn(process.execPath, [fileURLToPath(new URL("./cli.js", import.meta.url)), "serve", ...args], { detached: true, stdio: ["ignore", log.fd, log.fd], env });
+        let spawnError;
+        child.once("error", error => { spawnError = error; });
+        child.unref();
+        await log.close();
+        for (let attempt = 0; attempt < 100; attempt++) {
+            if (spawnError)
+                throw spawnError;
+            if (child.exitCode !== null)
+                throw new Error(`dd-console завершился при запуске; проверьте ${path.join(home, "server.log")}.`);
+            const state = await serverStatus(env);
+            if (state.status === "running" && state.server && state.server.pid === child.pid) {
+                try {
+                    const response = await fetch(state.server.url, { signal: AbortSignal.timeout(1_000) });
+                    await response.text();
+                    if (response.ok && response.headers.get("content-type")?.startsWith("text/html"))
+                        return state;
+                }
+                catch { /* Wait until the UI is ready as well as health. */ }
+            }
+            await pause();
+        }
+        if (child.pid)
+            child.kill("SIGTERM");
+        throw new Error(`dd-console не запустился; проверьте ${path.join(home, "server.log")}.`);
+    }
+    finally {
+        await release();
+    }
+}

package/dist/file-lock.js

@@ -0,0 +1,33 @@
+import koffi from "koffi";
+import { open } from "node:fs/promises";
+import { constants } from "node:fs";
+const libc = koffi.load(process.platform === "darwin" ? "/usr/lib/libSystem.B.dylib" : "libc.so.6");
+const flock = libc.func("int flock(int fd, int operation)");
+/** Kernel-owned locks survive neither process death nor descriptor close.
+ * Keep the inode after release: unlinking it can create two independent locks. */
+export async function acquireFileLock(file, attempts, busyMessage) {
+    const handle = await open(file, constants.O_CREAT | constants.O_RDWR | constants.O_NOFOLLOW, 0o600);
+    try {
+        for (let attempt = 0; attempt < attempts; attempt++) {
+            if (flock(handle.fd, 2 | 4) === 0) {
+                await handle.truncate(0);
+                await handle.writeFile(`${process.pid}\n`);
+                let released = false;
+                return async () => { if (!released) {
+                    released = true;
+                    await handle.close();
+                } };
+            }
+            const code = koffi.errno();
+            if (![koffi.os.errno.EAGAIN, koffi.os.errno.EWOULDBLOCK].includes(code))
+                throw new Error("Не удалось заблокировать локальный реестр.");
+            if (attempt + 1 < attempts)
+                await new Promise(resolve => setTimeout(resolve, 10));
+        }
+        throw new Error(busyMessage);
+    }
+    catch (error) {
+        await handle.close();
+        throw error;
+    }
+}

package/dist/journal.js

@@ -0,0 +1,124 @@
+import { workerData } from "node:worker_threads";
+import { createHash, createHmac, randomBytes, timingSafeEqual } from "node:crypto";
+import { openWithin } from "./safe-files.js";
+import { string } from "./util.js";
+const secret = workerData?.journalSecret ? Buffer.from(workerData.journalSecret) : randomBytes(32), chunkSize = 256 * 1024, maxLine = 1024 * 1024;
+const stale = () => Object.assign(new Error("Журнал заменён или усечён. Начните чтение заново."), { code: "stale_cursor" });
+const sign = (payload) => createHmac("sha256", secret).update(payload).digest("base64url");
+function encode(cursor) { const payload = Buffer.from(JSON.stringify(cursor)).toString("base64url"); return `${payload}.${sign(payload)}`; }
+function decode(token) {
+    try {
+        const [payload, signature] = token.split(".");
+        const expected = Buffer.from(sign(payload));
+        const actual = Buffer.from(signature ?? "");
+        if (expected.length !== actual.length || !timingSafeEqual(expected, actual))
+            throw stale();
+        return JSON.parse(Buffer.from(payload, "base64url").toString());
+    }
+    catch {
+        throw stale();
+    }
+}
+function event(line, generation, offset) {
+    try {
+        const value = JSON.parse(line.toString("utf8"));
+        if (!value || typeof value !== "object" || Array.isArray(value))
+            throw new Error();
+        const data = value.data, payload = value.payload;
+        return { id: string(value.id) ?? `${generation}:${offset}`, execution_id: string(value.executionid) ?? string(value.execution_id), time: string(value.time) ?? string(value.timestamp), type: string(value.type) ?? string(value.event) ?? "event", status: string(data?.state) ?? string(data?.status) ?? string(value.status), stage: string(data?.stage) ?? string(value.stage) ?? null, message: string(data?.message) ?? string(payload?.reason) };
+    }
+    catch {
+        return { id: `${generation}:${offset}`, type: "invalid_jsonl_record", status: "partial", message: "Повреждённая строка журнала." };
+    }
+}
+/** Pages backwards from the latest complete record, with bounded reads/memory.
+ * A signed cursor freezes the upper byte boundary; append leaves it valid.
+ * Every cursor revalidates the file generation, prefix and boundary anchor. */
+export async function journalPage(root, file, scope, limit = 50, token) {
+    let handle;
+    try {
+        handle = await openWithin(root, file);
+    }
+    catch (error) {
+        if (token)
+            throw stale();
+        return { items: [], next_cursor: null, truncated: false, pending_tail: false, diagnostics: [{ code: "journal_unavailable", severity: "warning", message: "Журнал отсутствует или недоступен." }] };
+    }
+    try {
+        const info = handle.stat(), generation = `${info.dev}:${info.ino}:${info.birthtimeMs}`;
+        const hash = async (start, length) => { const buffer = Buffer.alloc(length), { bytesRead } = await handle.read(buffer, start); return createHash("sha256").update(buffer.subarray(0, bytesRead)).digest("hex"); };
+        const old = token ? decode(token) : null;
+        if (old && (old.scope !== scope || old.generation !== generation || !Number.isSafeInteger(old.end) || old.end < 0 || old.end > old.size || info.size < old.size || old.head !== await hash(0, Math.min(256, old.size)) || old.anchor !== await hash(Math.max(0, old.end - 256), Math.min(256, old.end))))
+            throw stale();
+        let end = old?.end ?? info.size, pos = end, skipping = old?.skipping ?? false;
+        let buffer = Buffer.alloc(0), bytes = 0, pending = false;
+        const items = [], diagnostics = [];
+        // The rightmost incomplete record waits for a later append. Discard its
+        // bounded fragments while walking left; it is never parsed as an event.
+        let discardTail = !old || Boolean(old.tail), longLine = skipping;
+        while ((pos > 0 || buffer.length) && items.length < limit && bytes < 4 * 1024 * 1024) {
+            if (pos > 0) {
+                const start = Math.max(0, pos - chunkSize), part = Buffer.alloc(pos - start);
+                const { bytesRead } = await handle.read(part, start);
+                if (bytesRead !== part.length)
+                    throw stale();
+                buffer = Buffer.concat([part, buffer]);
+                bytes += bytesRead;
+                pos = start;
+            }
+            if (discardTail) {
+                const last = buffer.lastIndexOf(10);
+                if (last < 0) {
+                    pending = true;
+                    buffer = Buffer.alloc(0);
+                    end = pos;
+                    if (!pos)
+                        break;
+                    continue;
+                }
+                pending = last < buffer.length - 1 || pending;
+                buffer = buffer.subarray(0, last + 1);
+                end = pos + buffer.length;
+                discardTail = false;
+            }
+            while (buffer.length && items.length < limit) {
+                const previous = buffer.length > 1 ? buffer.lastIndexOf(10, buffer.length - 2) : -1;
+                if (previous < 0 && pos > 0)
+                    break;
+                const start = previous + 1, offset = pos + start, line = buffer.subarray(start, buffer.length - 1);
+                if (longLine || line.length > maxLine) {
+                    diagnostics.push({ code: "journal_line_too_large", severity: "warning", message: "Строка журнала больше 1 MiB пропущена." });
+                    items.push({ id: `${generation}:${offset}`, type: "oversized_jsonl_record", status: "partial" });
+                }
+                else if (line.length) {
+                    const item = event(line, generation, offset);
+                    items.push(item);
+                    if (item.type === "invalid_jsonl_record")
+                        diagnostics.push({ code: item.type, severity: "warning", message: item.message });
+                }
+                longLine = false;
+                buffer = buffer.subarray(0, start);
+                end = offset;
+            }
+            if (buffer.length > maxLine) {
+                buffer = Buffer.alloc(0);
+                longLine = true;
+                end = pos;
+            }
+            if (!pos)
+                break;
+        }
+        if (longLine || discardTail)
+            end = pos;
+        const after = handle.stat();
+        if (after.size < info.size || after.ino !== info.ino || after.size === info.size && after.mtimeMs !== info.mtimeMs)
+            throw stale();
+        if (bytes >= 4 * 1024 * 1024)
+            diagnostics.push({ code: "journal_scan_budget", severity: "info", message: "Достигнут лимит чтения страницы; продолжите по ссылке следующей страницы." });
+        const next_cursor = end > 0 ? encode({ scope, generation, end, size: info.size, head: await hash(0, Math.min(256, info.size)), anchor: await hash(Math.max(0, end - 256), Math.min(256, end)), skipping: longLine, tail: discardTail }) : null;
+        return { items, next_cursor, truncated: Boolean(next_cursor), pending_tail: pending, diagnostics };
+    }
+    finally {
+        handle.close();
+    }
+}