@bli-cockpit/log-digest 0.0.0-stage → 0.1.0

package/dist/sources/railway.js

@@ -0,0 +1,156 @@
+/**
+ * `railway` and `railway:<service>`: Tower's Railway services, through the
+ * installed `railway` CLI.
+ *
+ * Project and environment are ALWAYS passed explicitly. `apps/inference`'s
+ * `railway link` points at the RUNNER service, so a bare `railway logs` run from
+ * a checkout answers for the wrong service; nothing here reads the link.
+ *
+ * Measured limits (BLI-12833, `railway` 5.54): `--lines` accepts at most 5,000
+ * (10,000 is "Invalid input"), and the busiest service (`ladder`, six replicas)
+ * writes about 1,000 lines a minute, so a 5,000-line read is five minutes. A
+ * longer window is read in pages going back in time with `--until`, newest
+ * first, up to a page cap, and the digest says how far back it got. Railway
+ * serves the logs of the latest deployment: a redeploy inside the window hides
+ * the lines before it, which shows as "read back to" a time later than the
+ * window start.
+ */
+import { isoOf } from "../window.js";
+import { SourceRefusal } from "./types.js";
+export const RAILWAY_PROJECT_ID = "868238ce-d8fe-4629-8e05-fb7492baff1f"; // bli-cockpit-inference, workspace "canakobli's Projects"
+export const RAILWAY_ENVIRONMENT = "production";
+const SERVICE_NAME_ONLY = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+const PAGE_LINES = 5000;
+const MAX_PAGES = 4;
+const CONCURRENCY = 4;
+/** Which named refusal a failed `railway` run is, or null when the run is not a refusal. */
+export function railwayRefusal(run, service) {
+    if (run.failure === "ENOENT") {
+        return new SourceRefusal("railway_cli_missing", "the `railway` CLI is not installed on this machine; install it (`brew install railway`) and run `railway login`");
+    }
+    const said = `${run.stderr}\n${run.stdout.split("\n").filter((line) => !line.startsWith("{")).join("\n").slice(0, 2000)}`;
+    if (/Unauthorized|not logged in|railway login|No token|invalid.*token/i.test(said)) {
+        return new SourceRefusal("railway_not_logged_in", "the `railway` CLI has no usable login; run `railway login` with an account on the bli-cockpit-inference project");
+    }
+    if (/Service '.*' not found|service .* not found/i.test(said)) {
+        return new SourceRefusal("railway_service_unknown", `Railway has no service ${service ?? "of that name"} in the bli-cockpit-inference project`);
+    }
+    if (/Project .* not found|not authorized to access|do not have access|doesn't have access/i.test(said)) {
+        return new SourceRefusal("railway_project_unreachable", "this Railway login cannot read the bli-cockpit-inference project");
+    }
+    return null;
+}
+function parseLines(stdout) {
+    const out = [];
+    for (const line of stdout.split("\n")) {
+        if (!line.startsWith("{"))
+            continue;
+        try {
+            out.push(JSON.parse(line));
+        }
+        catch {
+            // a line cut off by a timeout or the byte ceiling: not a record
+        }
+    }
+    return out;
+}
+async function listServices(context) {
+    const result = await context.run("railway", ["service", "list", "--json", "--project", RAILWAY_PROJECT_ID, "--environment", RAILWAY_ENVIRONMENT], { timeoutMs: 30_000, maxBytes: 8 * 1024 * 1024 });
+    const refusal = railwayRefusal(result);
+    if (refusal)
+        throw refusal;
+    try {
+        const parsed = JSON.parse(result.stdout);
+        const names = parsed.map((entry) => entry.name).filter((name) => typeof name === "string").sort();
+        if (names.length === 0)
+            throw new Error("empty");
+        return names;
+    }
+    catch {
+        throw new SourceRefusal("railway_failed", `\`railway service list\` returned nothing readable (exit ${result.status ?? "none"})`);
+    }
+}
+async function readService(context, service, refuseOnFailure) {
+    if (!SERVICE_NAME_ONLY.test(service))
+        throw new SourceRefusal("invalid_service_name", "a Railway service name is letters, digits, dot, dash and underscore");
+    const { window, run, log } = context;
+    const timeoutMs = context.limits?.timeoutMs ?? 60_000;
+    const pageLines = context.limits?.railwayLines ?? PAGE_LINES;
+    const lines = [];
+    let until = null;
+    let cappedAt = null;
+    for (let page = 1; page <= MAX_PAGES; page += 1) {
+        const args = [
+            "logs", "--service", service, "--project", RAILWAY_PROJECT_ID, "--environment", RAILWAY_ENVIRONMENT,
+            "--since", isoOf(window.fromEpoch), ...(until ? ["--until", until] : []), "--lines", String(pageLines), "--json",
+        ];
+        const result = await run("railway", args, { timeoutMs, maxBytes: 64 * 1024 * 1024 });
+        const refusal = railwayRefusal(result, service);
+        if (refusal) {
+            if (refuseOnFailure || refusal.reason === "railway_not_logged_in" || refusal.reason === "railway_cli_missing")
+                throw refusal;
+            log("[logs railway] service unreadable", { service, reason: refusal.reason });
+            return { service, lines, cappedAt, problem: refusal.reason };
+        }
+        if (result.failure && result.failure !== "timeout") {
+            if (refuseOnFailure)
+                throw new SourceRefusal("railway_failed", `the railway CLI could not run (${result.failure})`);
+            return { service, lines, cappedAt, problem: `railway_failed:${result.failure}` };
+        }
+        if (result.status !== 0 && result.status !== null && !result.stdout.startsWith("{")) {
+            const tail = (result.stderr.trim().split("\n").pop() ?? "").slice(0, 160).replace(/\s+/g, " ");
+            if (refuseOnFailure)
+                throw new SourceRefusal("railway_failed", `railway logs exited ${result.status}: ${tail}`);
+            return { service, lines, cappedAt, problem: `railway_failed:exit_${result.status}` };
+        }
+        const records = parseLines(result.stdout).filter((record) => record.timestamp && (until === null || record.timestamp < until));
+        for (const record of records) {
+            if (typeof record.message === "string" && record.message) {
+                lines.push({ unit: service, message: record.message, ts: Date.parse(record.timestamp) / 1000, level: record.level });
+            }
+        }
+        log("[logs railway] page read", { service, page, lines: records.length, timed_out: result.failure === "timeout" });
+        if (records.length < pageLines)
+            return { service, lines, cappedAt: null, problem: result.failure === "timeout" ? "timeout" : null };
+        until = records.reduce((oldest, record) => (record.timestamp < oldest ? record.timestamp : oldest), records[0].timestamp);
+        cappedAt = until;
+    }
+    return { service, lines, cappedAt, problem: null };
+}
+export async function readRailway(context, service) {
+    const services = service ? [service] : await listServices(context);
+    const reads = [];
+    let next = 0;
+    const worker = async () => {
+        while (next < services.length) {
+            const name = services[next++];
+            reads.push(await readService(context, name, Boolean(service)));
+        }
+    };
+    await Promise.all(Array.from({ length: Math.min(CONCURRENCY, services.length) }, () => worker()));
+    reads.sort((a, b) => (a.service < b.service ? -1 : a.service > b.service ? 1 : 0));
+    const lines = reads.flatMap((read) => read.lines);
+    const notes = [];
+    const quiet = reads.filter((read) => read.lines.length === 0 && !read.problem).length;
+    notes.push(`${services.length} service${services.length === 1 ? "" : "s"} read, ${quiet} with no lines in the window`);
+    const capped = reads.filter((read) => read.cappedAt);
+    if (capped.length > 0) {
+        notes.push(`capped (newest first, ${MAX_PAGES * (context.limits?.railwayLines ?? PAGE_LINES)} lines a service): ${capped.map((read) => `${read.service} back to ${read.cappedAt.slice(11, 16)}Z`).join(", ")}`);
+    }
+    // A busy service whose first line is well after the window start was redeployed inside the window: Railway serves
+    // the latest deployment's logs only. (A quiet cron's first line is late too, so only services with real volume.)
+    const hidden = reads.filter((read) => {
+        if (read.cappedAt || read.lines.length < 200)
+            return false;
+        const first = Math.min(...read.lines.map((line) => line.ts));
+        return first - context.window.fromEpoch > Math.max(120, (context.window.toEpoch - context.window.fromEpoch) * 0.1);
+    });
+    if (hidden.length > 0) {
+        notes.push(`latest deployment only: ${hidden.map((read) => `${read.service} from ${isoOf(Math.min(...read.lines.map((line) => line.ts))).slice(11, 16)}Z`).join(", ")} (a redeploy hides the lines before)`);
+    }
+    const broken = reads.filter((read) => read.problem);
+    if (broken.length > 0)
+        notes.push(`unreadable: ${broken.map((read) => `${read.service} (${read.problem})`).join(", ")}`);
+    context.log("[logs railway] read complete", { services: services.length, lines: lines.length, capped_services: capped.length, unreadable_services: broken.length });
+    return { lines, notes };
+}

package/dist/sources/stdin.d.ts

@@ -0,0 +1,9 @@
+/**
+ * `-`: lines piped in. Plain text lines are digested as they are; a JSON line is
+ * understood when it is a journald export (`MESSAGE`, `_SYSTEMD_UNIT`,
+ * `__REALTIME_TIMESTAMP`), `railway logs --json` (`message`, `level`, an ISO
+ * `timestamp`) or `vercel logs --json` (`message`, `level`, a millisecond
+ * `timestamp`, nested `logs`). Anything else JSON is judged as a JSON log line.
+ */
+import { type SourceContext, type SourceRead } from "./types.js";
+export declare function readStdin(context: SourceContext): Promise<SourceRead>;

package/dist/sources/stdin.js

@@ -0,0 +1,56 @@
+/**
+ * `-`: lines piped in. Plain text lines are digested as they are; a JSON line is
+ * understood when it is a journald export (`MESSAGE`, `_SYSTEMD_UNIT`,
+ * `__REALTIME_TIMESTAMP`), `railway logs --json` (`message`, `level`, an ISO
+ * `timestamp`) or `vercel logs --json` (`message`, `level`, a millisecond
+ * `timestamp`, nested `logs`). Anything else JSON is judged as a JSON log line.
+ */
+import { SourceRefusal } from "./types.js";
+function epochOf(value) {
+    if (typeof value === "number")
+        return value > 1e12 ? value / 1000 : value;
+    if (typeof value === "string") {
+        const parsed = Date.parse(value);
+        return Number.isFinite(parsed) ? parsed / 1000 : 0;
+    }
+    return 0;
+}
+function fromJson(data, fallback) {
+    if (typeof data["MESSAGE"] === "string") {
+        const micros = Number.parseInt(String(data["__REALTIME_TIMESTAMP"] ?? 0), 10);
+        const unit = String(data["UNIT"] ?? data["_SYSTEMD_UNIT"] ?? data["SYSLOG_IDENTIFIER"] ?? "stdin");
+        return [{ unit, message: data["MESSAGE"], ts: Number.isFinite(micros) ? micros / 1e6 : 0 }];
+    }
+    if (Array.isArray(data["logs"]) && typeof data["requestPath"] === "string") {
+        const ts = epochOf(data["timestamp"]);
+        return data["logs"]
+            .filter((entry) => typeof entry["message"] === "string")
+            .map((entry) => ({ unit: "stdin", message: String(entry["message"]), ts, level: typeof entry["level"] === "string" ? entry["level"] : undefined }));
+    }
+    if (typeof data["message"] === "string" && ("level" in data || "timestamp" in data)) {
+        return [{ unit: "stdin", message: data["message"], ts: epochOf(data["timestamp"]), level: typeof data["level"] === "string" ? data["level"] : undefined }];
+    }
+    return [{ unit: "stdin", message: fallback, ts: 0 }];
+}
+export async function readStdin(context) {
+    if (context.stdinIsTerminal)
+        throw new SourceRefusal("stdin_is_terminal", "`-` reads piped lines; nothing was piped (try `railway logs --json | cockpit logs -`)");
+    const text = context.stdinText ?? "";
+    const lines = [];
+    for (const row of text.split("\n")) {
+        if (!row.trim())
+            continue;
+        if (row.startsWith("{")) {
+            try {
+                lines.push(...fromJson(JSON.parse(row), row));
+                continue;
+            }
+            catch {
+                // not JSON after all: a plain text line
+            }
+        }
+        lines.push({ unit: "stdin", message: row, ts: 0 });
+    }
+    const notes = lines.length === 0 ? ["stdin was empty"] : [];
+    return { lines, notes };
+}

package/dist/sources/types.d.ts

@@ -0,0 +1,67 @@
+/**
+ * What every log source hands the digest: lines with a unit, a message, a time
+ * and optionally the source's own severity word, plus plain-words facts about
+ * the read itself (capped, partial, no per-line times).
+ */
+import type { LogWindow } from "../window.js";
+export interface SourceLine {
+    /** The unit group the line belongs to: a Railway service, a Vercel route, a collector tag. */
+    unit: string;
+    message: string;
+    /** Epoch seconds; 0 when the source has no per-line time. */
+    ts: number;
+    /** The source's own severity word (`error`, `warn`, `info`). */
+    level?: string;
+}
+export interface SourceRead {
+    lines: SourceLine[];
+    /** Printed under the header exactly as written: what the read could and could not see. */
+    notes: string[];
+    /** The size of what was read when it is more than the lines' own text (a collector log's indented receipts). */
+    rawChars?: number;
+}
+/** The outcome of one command a source runs (`vercel`, `railway`). */
+export interface CliRun {
+    status: number | null;
+    stdout: string;
+    stderr: string;
+    /** `ENOENT` when the program is not installed, `timeout` when it was stopped, `aborted` when its output matched the caller's abort pattern, else a Node error code. */
+    failure?: string;
+    /** The stdout was cut at the byte ceiling or the time limit; what is here is a prefix. */
+    truncated?: boolean;
+}
+export type RunCli = (command: string, args: readonly string[], options: {
+    timeoutMs: number;
+    maxBytes: number;
+    abortOn?: RegExp;
+}) => Promise<CliRun>;
+export type LogFields = Record<string, string | number | boolean | null | undefined>;
+export type LogFn = (message: string, fields: LogFields) => void;
+export interface SourceContext {
+    window: LogWindow;
+    run: RunCli;
+    log: LogFn;
+    /** Where the collector keeps its state (`~/.local/state/bli-cockpit`); the caller computes it per platform. */
+    stateDir?: string;
+    /** Stdin text for the `-` source. */
+    stdinText?: string;
+    /** Whether stdin is a terminal (nothing was piped). */
+    stdinIsTerminal?: boolean;
+    /** Read every Vercel record, not just error, warning, fatal and 5xx (slow: the CLI answers 50 records a call). */
+    allLevels?: boolean;
+    /** Overrides, mostly for tests. */
+    limits?: {
+        railwayLines?: number;
+        timeoutMs?: number;
+    };
+}
+/** A named refusal: the reason is computed where it happens and travels intact to the person. */
+export declare class SourceRefusal extends Error {
+    readonly reason: string;
+    readonly detail: string;
+    constructor(reason: string, detail: string);
+}
+export interface SourceSpec {
+    /** `collector`, `dashboard`, `railway`, `railway:<service>`, `-`. */
+    name: string;
+}

package/dist/sources/types.js

@@ -0,0 +1,13 @@
+/** A named refusal: the reason is computed where it happens and travels intact to the person. */
+export class SourceRefusal extends Error {
+    reason;
+    detail;
+    // No parameter properties: scripts/lib/cli-vocabulary.mjs reads this package from SOURCE through Node's type
+    // stripping, which only erases types and cannot compile a constructor that declares fields.
+    constructor(reason, detail) {
+        super(`${reason}: ${detail}`);
+        this.name = "SourceRefusal";
+        this.reason = reason;
+        this.detail = detail;
+    }
+}

package/dist/sources/vercel.d.ts

@@ -0,0 +1,10 @@
+import { SourceRefusal, type CliRun, type SourceContext, type SourceRead } from "./types.js";
+export declare const VERCEL_PROJECT = "bli-cockpit-dashboard";
+export declare const VERCEL_SCOPE = "bli-inc";
+/** `/api/docs/3f2a…` becomes `/api/docs/:id`; digits, uuids, long hex and long slugs are one placeholder. */
+export declare function routeTemplate(path: string | undefined): string;
+/** Which named refusal a failed `vercel` run is, or null when the run is not a refusal. */
+export declare function vercelRefusal(run: CliRun): SourceRefusal | null;
+/** The refusal-pattern the runner stops on, so an interactive login is never left waiting. */
+export declare const VERCEL_ABORT_PATTERN: RegExp;
+export declare function readDashboard(context: SourceContext): Promise<SourceRead>;

package/dist/sources/vercel.js

@@ -0,0 +1,185 @@
+/**
+ * `dashboard`: Tower's Vercel runtime logs, through the installed `vercel` CLI.
+ *
+ * Project `bli-cockpit-dashboard`, team `bli-inc`. One Vercel record is one
+ * invocation (a request) carrying every console line the function wrote, so the
+ * source turns each nested line into one digest line, and adds a synthetic line
+ * for a request that ended 5xx / 429 / 403 even when the code logged nothing.
+ *
+ * Measured quirks this works around (BLI-12833, `vercel` 59.x):
+ *  - `vercel logs --since 1h --limit 10000` returned 10,000 lines of which 599
+ *    were distinct: a call answers one page of 50 records and then repeats that
+ *    page until `--limit`. A call that comes back with a full page is therefore
+ *    treated as possibly incomplete and its time slice is halved until every
+ *    answer is under a page; every record is de-duplicated by id.
+ *  - A full hour of every level is about 4,000 records, a few minutes of calls.
+ *    The default reads only what Vercel marks error, warning or fatal, plus every
+ *    5xx (a handful of calls); `allLevels` reads everything.
+ *  - With no credentials the CLI starts a browser login flow instead of failing.
+ *    That output is recognised and the process stopped at once, as the named
+ *    refusal `vercel_not_logged_in`.
+ */
+import { isoOf } from "../window.js";
+import { SourceRefusal } from "./types.js";
+export const VERCEL_PROJECT = "bli-cockpit-dashboard";
+export const VERCEL_SCOPE = "bli-inc";
+// The CLI answers a call with at most one page of 50 records; when more exist it repeats that page until
+// `--limit`. A page-full answer is therefore suspect, and the slice is halved until each answer is under a page.
+const PAGE = 50;
+const MIN_SLICE_SECONDS = 4;
+const MAX_CALLS = 240;
+const CONCURRENCY = 4;
+const CALL_TIMEOUT_MS = 45_000;
+// Default: only the records Vercel itself marks as trouble, plus every 5xx. A few calls an hour.
+const PROBLEM_QUERIES = [["--level", "error"], ["--level", "warning"], ["--level", "fatal"], ["--status-code", "5xx"]];
+const ALL_QUERIES = [[]];
+/** `/api/docs/3f2a…` becomes `/api/docs/:id`; digits, uuids, long hex and long slugs are one placeholder. */
+export function routeTemplate(path) {
+    if (!path)
+        return "";
+    const clean = path.split("?")[0];
+    return clean
+        .split("/")
+        .map((segment) => /^\d+$/.test(segment) || (/^[0-9a-f-]{8,}$/i.test(segment) && /\d/.test(segment)) || segment.length > 28 ? ":id" : segment)
+        .join("/");
+}
+/** Which named refusal a failed `vercel` run is, or null when the run is not a refusal. */
+export function vercelRefusal(run) {
+    if (run.failure === "ENOENT") {
+        return new SourceRefusal("vercel_cli_missing", "the `vercel` CLI is not installed on this machine; install it (`npm i -g vercel`) and run `vercel login`");
+    }
+    // Only the CLI's own words: a log record is a JSON line and may say "forbidden" about the app.
+    const said = `${run.stderr}\n${run.stdout.split("\n").filter((line) => !line.startsWith("{")).join("\n").slice(0, 4000)}`;
+    if (/No existing credentials|Starting login flow|oauth\/device|not_authorized|token .*rejected|Please log ?in|not logged in/i.test(said)) {
+        return new SourceRefusal("vercel_not_logged_in", "the `vercel` CLI has no usable login; run `vercel login` as a member of the bli-inc team");
+    }
+    if (/forbidden|not a member|do not have access|don't have access|insufficient permissions/i.test(said)) {
+        return new SourceRefusal("vercel_scope_denied", `this Vercel login cannot read the ${VERCEL_SCOPE} team's ${VERCEL_PROJECT} logs`);
+    }
+    if (/project .*not found|could not find project|no such project/i.test(said)) {
+        return new SourceRefusal("vercel_project_not_found", `Vercel has no project ${VERCEL_PROJECT} in the ${VERCEL_SCOPE} scope for this login`);
+    }
+    return null;
+}
+/** The refusal-pattern the runner stops on, so an interactive login is never left waiting. */
+export const VERCEL_ABORT_PATTERN = /No existing credentials|Starting login flow|oauth\/device/;
+function parseRecords(stdout) {
+    const records = [];
+    for (const line of stdout.split("\n")) {
+        if (!line.startsWith("{"))
+            continue;
+        try {
+            records.push(JSON.parse(line));
+        }
+        catch {
+            // a line cut off by a timeout or the byte ceiling: not a record
+        }
+    }
+    return records;
+}
+export async function readDashboard(context) {
+    const { window, run, log } = context;
+    const allLevels = context.allLevels ?? false;
+    const queries = allLevels ? ALL_QUERIES : PROBLEM_QUERIES;
+    const seen = new Map();
+    const queue = [];
+    const width = allLevels ? 120 : Math.max(300, Math.ceil((window.toEpoch - window.fromEpoch) / 4));
+    for (const query of queries) {
+        for (let end = window.toEpoch; end > window.fromEpoch; end -= width)
+            queue.push({ from: Math.max(window.fromEpoch, end - width), to: end, query });
+    }
+    let calls = 0;
+    let splits = 0;
+    let incomplete = 0;
+    let active = 0;
+    let failure = null;
+    const attempt = async (task) => {
+        calls += 1;
+        const result = await run("vercel", ["logs", "--project", VERCEL_PROJECT, "--scope", VERCEL_SCOPE, "--since", isoOf(task.from), "--until", isoOf(task.to), ...task.query, "--json", "--limit", "100", "--no-color", "--non-interactive"], { timeoutMs: context.limits?.timeoutMs ?? CALL_TIMEOUT_MS, maxBytes: 64 * 1024 * 1024, abortOn: VERCEL_ABORT_PATTERN });
+        const refusal = vercelRefusal(result);
+        if (refusal)
+            throw refusal;
+        if (result.failure && result.failure !== "timeout")
+            throw new SourceRefusal("vercel_failed", `the vercel CLI could not run (${result.failure})`);
+        if (result.status !== 0 && result.status !== null && !result.stdout.includes('"id"')) {
+            const tail = (result.stderr.trim().split("\n").pop() ?? "").slice(0, 160).replace(/\s+/g, " ");
+            throw new SourceRefusal("vercel_failed", `vercel logs exited ${result.status}: ${tail}`);
+        }
+        const records = parseRecords(result.stdout);
+        for (const record of records)
+            if (record.id && !seen.has(record.id))
+                seen.set(record.id, record);
+        const suspect = records.length >= PAGE || result.failure === "timeout";
+        if (!suspect)
+            return;
+        if (task.to - task.from > MIN_SLICE_SECONDS && calls < MAX_CALLS) {
+            const middle = (task.from + task.to) / 2;
+            queue.push({ ...task, from: task.from, to: middle }, { ...task, from: middle, to: task.to });
+            splits += 1;
+        }
+        else {
+            incomplete += 1;
+        }
+    };
+    const worker = async () => {
+        for (;;) {
+            if (failure)
+                return;
+            const task = queue.shift();
+            if (!task) {
+                if (active === 0)
+                    return;
+                await new Promise((resolve) => setTimeout(resolve, 25));
+                continue;
+            }
+            active += 1;
+            try {
+                await attempt(task);
+            }
+            catch (error) {
+                failure = error instanceof SourceRefusal ? error : new SourceRefusal("vercel_failed", "the vercel read failed unexpectedly");
+            }
+            finally {
+                active -= 1;
+            }
+        }
+    };
+    await Promise.all(Array.from({ length: CONCURRENCY }, () => worker()));
+    if (failure)
+        throw failure;
+    const lines = [];
+    const classes = { ok: 0, redirect: 0, client: 0, server: 0 };
+    for (const record of seen.values()) {
+        const ts = (record.timestamp ?? 0) / 1000;
+        if (ts && ts < window.fromEpoch)
+            continue;
+        const route = routeTemplate(record.requestPath);
+        const unit = route ? `dashboard:${route}` : "dashboard";
+        const nested = record.logs && record.logs.length > 0 ? record.logs : record.message ? [{ level: record.level, message: record.message }] : [];
+        for (const entry of nested) {
+            if (typeof entry.message === "string" && entry.message)
+                lines.push({ unit, message: entry.message, ts, level: entry.level });
+        }
+        const status = record.responseStatusCode ?? 0;
+        if (status >= 200 && status < 300)
+            classes.ok += 1;
+        else if (status >= 300 && status < 400)
+            classes.redirect += 1;
+        else if (status >= 400 && status < 500)
+            classes.client += 1;
+        else if (status >= 500)
+            classes.server += 1;
+        if (status >= 500 || status === 429 || status === 403) {
+            lines.push({ unit, message: `HTTP ${status} ${record.requestMethod ?? "?"} ${route || "?"}`, ts, level: "error" });
+        }
+    }
+    const notes = [];
+    const requests = classes.ok + classes.redirect + classes.client + classes.server;
+    notes.push(allLevels
+        ? `requests ${requests.toLocaleString("en-US")}: 2xx ${classes.ok.toLocaleString("en-US")}, 3xx ${classes.redirect}, 4xx ${classes.client}, 5xx ${classes.server}`
+        : `read only the records Vercel marks error, warning or fatal, and every 5xx (${seen.size} records); info-only requests were not read (--all-levels reads them, slowly)`);
+    if (incomplete > 0)
+        notes.push(`incomplete: ${incomplete} slice${incomplete === 1 ? "" : "s"} still returned a full page at ${MIN_SLICE_SECONDS} s or at the call limit`);
+    log("[logs dashboard] read complete", { calls, splits, incomplete_slices: incomplete, records: seen.size, lines: lines.length, server_errors: classes.server, all_levels: allLevels });
+    return { lines, notes };
+}

package/dist/tagged.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Tower's own log shape: `[tag] what happened {"reason":"x","http_status":502}`.
+ *
+ * `docs/engineering/message-standard.md` makes every deciding branch log a tag,
+ * a sentence and one JSON object of metadata. Judging such a line by the words
+ * anywhere in it misreads its keys (`"failed":{}` is an empty map, not a
+ * failure), so this reads the three parts separately:
+ *
+ *  - the SENTENCE is judged by the trouble words (`looksImportant`);
+ *  - the FIELDS are judged by their values: an HTTP-like status, a bad state
+ *    word, a `reason` whose words say failure, a non-empty `error`;
+ *  - the source's own LEVEL: warn is a line the unit itself declared a WARNING
+ *    (counted, never escalated). The error level is NOT a verdict here: Tower
+ *    writes ordinary lines with console.error, so Vercel marks them error.
+ *
+ * Opt-in (`DigestOptions.taggedLines`): Kaiben's journals are not in this shape,
+ * and the Python-pinned tests run with it off.
+ */
+import { type JsonObject } from "./judge.js";
+/** The line with its zero counters removed, so `failed=0` does not read as a failure. */
+export declare function withoutZeroCounters(text: string): string;
+export interface Tagged {
+    tag: string;
+    /** The sentence between the tag and the metadata. */
+    text: string;
+    fields: JsonObject | null;
+}
+/** `[tag] sentence {json}` split into its parts, or null when the line does not start with a tag. */
+export declare function parseTagged(message: string): Tagged | null;
+export interface TaggedJudgement {
+    important: boolean;
+    /** The template when important; the tag (the routine event name) otherwise. */
+    template: string;
+    declaredWarning: boolean;
+}
+/** Whether a tagged line can mean trouble, and the template it groups under. */
+export declare function judgeTagged(parsed: Tagged, level: string | undefined): TaggedJudgement;

package/dist/tagged.js

@@ -0,0 +1,114 @@
+/**
+ * Tower's own log shape: `[tag] what happened {"reason":"x","http_status":502}`.
+ *
+ * `docs/engineering/message-standard.md` makes every deciding branch log a tag,
+ * a sentence and one JSON object of metadata. Judging such a line by the words
+ * anywhere in it misreads its keys (`"failed":{}` is an empty map, not a
+ * failure), so this reads the three parts separately:
+ *
+ *  - the SENTENCE is judged by the trouble words (`looksImportant`);
+ *  - the FIELDS are judged by their values: an HTTP-like status, a bad state
+ *    word, a `reason` whose words say failure, a non-empty `error`;
+ *  - the source's own LEVEL: warn is a line the unit itself declared a WARNING
+ *    (counted, never escalated). The error level is NOT a verdict here: Tower
+ *    writes ordinary lines with console.error, so Vercel marks them error.
+ *
+ * Opt-in (`DigestOptions.taggedLines`): Kaiben's journals are not in this shape,
+ * and the Python-pinned tests run with it off.
+ */
+import { jsonRecords, looksImportant } from "./judge.js";
+import { mask, TEMPLATE_CHARS, cut } from "./mask.js";
+const TAGGED = /^\[([^\]\n]{1,60})\]\s*([\s\S]*)$/;
+// "exhausted" is bad only with a thing that ran out (retries, a budget); alone it is how a paginated read says it reached the end.
+const RAN_OUT_OF = new Set(["retries", "retry", "attempts", "budget", "quota", "credits", "tokens", "memory", "disk"]);
+const BAD_WORDS = new Set([
+    "fail", "failed", "failure", "error", "errors", "exception", "refused", "denied", "blocked", "timeout", "timed",
+    "fatal", "crash", "crashed", "killed", "abort", "aborted", "rejected", "unreachable", "invalid",
+    "missing", "unreadable", "stalled", "throttled",
+]);
+const BAD_STATE = /^(fail|failed|failure|error|errored|fatal|blocked|refused|timeout|timed_out|crash|crashed|killed|aborted|rejected)$/i;
+const EXPLAIN = [
+    "reason", "status", "outcome", "result", "http", "http_status", "code", "step", "what", "error", "error_name",
+    "exception", "detail", "server_reason", "sync_reason", "error_code", "error_syscall",
+];
+const WORD = /[A-Za-z]+/g;
+// `failed=0`, `errors: 0`: a counter at zero is a routine summary, not a failure.
+const ZERO_COUNTER = /\b(?:fail(?:ed|ures?)?|errors?)\s*[=:]\s*0\b/gi;
+/** The line with its zero counters removed, so `failed=0` does not read as a failure. */
+export function withoutZeroCounters(text) {
+    return text.replace(ZERO_COUNTER, "");
+}
+/** `[tag] sentence {json}` split into its parts, or null when the line does not start with a tag. */
+export function parseTagged(message) {
+    const head = TAGGED.exec(message);
+    if (!head)
+        return null;
+    const rest = head[2];
+    let text = rest;
+    let fields = null;
+    for (let at = rest.indexOf("{"); at >= 0; at = rest.indexOf("{", at + 1)) {
+        if (at > 0 && rest[at - 1] !== " ")
+            continue;
+        const records = jsonRecords(rest.slice(at).trim());
+        if (records && records.length === 1) {
+            text = rest.slice(0, at).trim();
+            fields = records[0];
+            break;
+        }
+    }
+    return { tag: head[1], text, fields };
+}
+function fieldsSayTrouble(fields) {
+    for (const key of ["http", "http_status", "code", "status"]) {
+        const value = fields[key];
+        if (typeof value === "number" && Number.isInteger(value) && (value === 403 || value === 429 || (value >= 500 && value <= 599)))
+            return true;
+    }
+    for (const key of ["status", "outcome", "result", "state", "verdict", "sync_status"]) {
+        const value = fields[key];
+        if (typeof value === "string" && BAD_STATE.test(value))
+            return true;
+    }
+    const reason = fields["reason"];
+    if (typeof reason === "string") {
+        const words = (reason.match(WORD) ?? []).map((word) => word.toLowerCase());
+        if (words.some((word) => BAD_WORDS.has(word)))
+            return true;
+        if (words.includes("exhausted") && words.some((word) => RAN_OUT_OF.has(word)))
+            return true;
+    }
+    for (const key of ["error", "error_name", "error_detail"]) {
+        const value = fields[key];
+        if (value !== null && value !== undefined && value !== "" && value !== 0 && value !== false)
+            return true;
+    }
+    return false;
+}
+function brief(value) {
+    if (typeof value === "number")
+        return Number.isInteger(value) && value >= 100 && value <= 599 ? String(value) : Number.isInteger(value) && value >= -9 && value <= 9 ? String(value) : "#";
+    if (typeof value === "boolean" || value === null)
+        return String(value);
+    if (typeof value === "string")
+        return mask(value);
+    return Array.isArray(value) ? "<list>" : "<dict>";
+}
+/** Whether a tagged line can mean trouble, and the template it groups under. */
+export function judgeTagged(parsed, level) {
+    const lowered = (level ?? "").toLowerCase();
+    // Not the error level: Tower writes plenty of ordinary lines with console.error, so Vercel's level
+    // "error" is not a verdict (measured 2026-10-07: most error-level lines in an hour were routine).
+    const warnLevel = lowered === "warn" || lowered === "warning";
+    const important = warnLevel || looksImportant(withoutZeroCounters(parsed.text)) || (parsed.fields !== null && fieldsSayTrouble(parsed.fields));
+    if (!important)
+        return { important: false, template: parsed.tag, declaredWarning: false };
+    const parts = [mask(`[${parsed.tag}] ${parsed.text}`)];
+    if (parsed.fields) {
+        for (const key of EXPLAIN) {
+            const value = parsed.fields[key];
+            if (value !== undefined && value !== null && value !== "")
+                parts.push(`${key}=${brief(value)}`);
+        }
+    }
+    return { important: true, template: cut(parts.join(" ").replace(/\s+/g, " ").trim(), TEMPLATE_CHARS), declaredWarning: warnLevel };
+}