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

package/dist/tower-classes.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Tower's own class table: which masked log templates are bugs, which are
+ * hiccups, which are harmless. `docs/runbooks/tower-logs.md` ("Teach it a new
+ * pattern") is how to add one.
+ *
+ * Seeded on 2026-10-07 (BLI-12833) from real windows of every wired source: the
+ * dashboard (Vercel, 1 h of every level and 12 h of error/warning/5xx), Railway
+ * (every service, 1 d: crons keep only their latest deployment's logs) and this
+ * machine's collector logs (3 d, including the rotated archives). Each pattern
+ * names the evidence it came from. A template NO pattern matches is `unknown`
+ * and alerts: a new kind of problem must reach a person, so this table only ever
+ * grows by explaining something, never by silencing.
+ *
+ * Labels follow what the raw lines showed, not what a name suggests:
+ *  - benign / dead_source are counted on one line and never alerted;
+ *  - hiccup / rate_pushback are things the code retries or degrades on its own,
+ *    each with the line that proves the retry;
+ *  - a real defect is labelled our_bug / config_drift / capacity explicitly, so
+ *    it stays an ERROR with a note saying why, instead of sitting in `unknown`.
+ * First match wins, so specific patterns sit above generic ones.
+ */
+import { ClassTable, type ClassInfo, type ClassTableData, type TablePattern } from "./classify.js";
+export declare const TOWER_CLASSES: Record<string, ClassInfo>;
+/** Patterns, most specific first. */
+export declare const TOWER_PATTERNS: readonly TablePattern[];
+export declare const TOWER_TABLE: ClassTableData;
+/** The compiled Tower table (built once per process). */
+export declare function towerClassTable(): ClassTable;

package/dist/tower-classes.js

@@ -0,0 +1,301 @@
+/**
+ * Tower's own class table: which masked log templates are bugs, which are
+ * hiccups, which are harmless. `docs/runbooks/tower-logs.md` ("Teach it a new
+ * pattern") is how to add one.
+ *
+ * Seeded on 2026-10-07 (BLI-12833) from real windows of every wired source: the
+ * dashboard (Vercel, 1 h of every level and 12 h of error/warning/5xx), Railway
+ * (every service, 1 d: crons keep only their latest deployment's logs) and this
+ * machine's collector logs (3 d, including the rotated archives). Each pattern
+ * names the evidence it came from. A template NO pattern matches is `unknown`
+ * and alerts: a new kind of problem must reach a person, so this table only ever
+ * grows by explaining something, never by silencing.
+ *
+ * Labels follow what the raw lines showed, not what a name suggests:
+ *  - benign / dead_source are counted on one line and never alerted;
+ *  - hiccup / rate_pushback are things the code retries or degrades on its own,
+ *    each with the line that proves the retry;
+ *  - a real defect is labelled our_bug / config_drift / capacity explicitly, so
+ *    it stays an ERROR with a note saying why, instead of sitting in `unknown`.
+ * First match wins, so specific patterns sit above generic ones.
+ */
+import { ClassTable } from "./classify.js";
+export const TOWER_CLASSES = {
+    our_bug: { severity: "ERROR", about: "our code is wrong: exceptions, schema errors, crashes, a 5xx we caused" },
+    unknown: { severity: "ERROR", about: "no pattern matched: a new kind of problem, so it reaches a person" },
+    capacity: { severity: "ERROR", about: "memory, disk, CPU or quota exhausted" },
+    config_drift: { severity: "ERROR", about: "a key, env var, schedule, PATH or file not as documented" },
+    hiccup: { severity: "hiccup", about: "timeouts and 5xx from a dependency: retried or degraded by the code itself, a WARNING only when retries run out" },
+    rate_pushback: { severity: "hiccup", about: "429 or a provider slowing us down: lower the rate" },
+    dead_source: { severity: "WARNING", about: "the thing asked for is gone or was never shared (404, revoked, repo deleted): count only" },
+    benign: { severity: "WARNING", about: "looks like trouble but is known harmless: count only" },
+};
+const raw = String.raw;
+/** Patterns, most specific first. */
+export const TOWER_PATTERNS = [
+    // ------------------------------------------------------------------ collector (this machine's sync.log / sync.err.log)
+    {
+        id: "collector-git-diff-no-index",
+        class: "our_bug",
+        source: "^collector$",
+        match: raw `^\[raw-evidence\] git diff failed `,
+        note: "git printed its `diff --no-index` usage, which is what git does when the directory is not a git repository (error_detail: unknown option `cached`, pathspec limiting). The collector should skip such a root the way it skips repo_root_missing. A lead on the cause, the usage text itself is the evidence.",
+        basis: "collector logs, 3 d: 1,218 lines, both diff_target values, every tick",
+    },
+    {
+        id: "collector-git-diff-root-missing",
+        class: "dead_source",
+        source: "^collector$",
+        match: raw `^\[raw-evidence\] git diff skipped, repository root is no longer on disk`,
+        note: "a repository that was deleted or moved: nothing to diff, the collector says so and moves on",
+        basis: "collector logs, 3 d: 26 lines",
+    },
+    {
+        id: "collector-evidence-file-vanished",
+        class: "dead_source",
+        source: "^collector$",
+        match: raw `^\[raw-evidence\] evidence file could not be stat'd reason=file_read_failed .*error_code=ENOENT`,
+        note: "a session file that was listed and then deleted before it was read: nothing to collect",
+        basis: "collector logs, 3 d: 1 line (error_code ENOENT, syscall stat)",
+    },
+    {
+        id: "collector-redelivery-nothing-plannable",
+        class: "our_bug",
+        source: "^collector$",
+        match: raw `^\[evidence-redelivery\] staged evidence could not be delivered reason=nothing_plannable`,
+        note: "staged evidence packs whose manifest is unreadable (unplannable.manifest_unreadable) are terminal and never delivered; the line repeats every tick. Staged bytes that never leave the machine.",
+        basis: "collector logs, 3 d: 201 lines, terminal=6 packs, 25 MB",
+    },
+    {
+        id: "collector-stubs-exhausted",
+        class: "benign",
+        source: "^collector$",
+        match: raw `^\[collector stubs\] redaction-crash stubs asked reason=stubs_exhausted`,
+        note: "a count line: the stub list was read to its end (exhausted is the pagination word for complete)",
+        basis: "collector logs, 3 d: 197 lines, each with pages, stub_count and session_count",
+    },
+    {
+        id: "collector-work-context-missing",
+        class: "benign",
+        source: "^collector$",
+        match: raw `^\[upload-envelope\] work context present but unreadable, reporting it as missing`,
+        note: "a repo with no `cockpit start` binding: the envelope goes up with no ticket label, by session-first design (a label, never a gate)",
+        basis: "collector logs, 3 d: 24 lines, error_detail `Active work context missing for <repo>`",
+    },
+    {
+        id: "collector-heartbeat-reports-failure",
+        class: "benign",
+        source: "^collector$",
+        match: raw `^\[heartbeat\] checked in reason=heartbeat_recorded http_status=202 sync_reason=(sync_failed|network_failed)`,
+        note: "the heartbeat itself succeeded (202); it only carries the last sync's reason. The sync failure shows as its own template.",
+        basis: "collector logs, 3 d: 20 lines",
+    },
+    {
+        id: "collector-transport-hiccups",
+        class: "hiccup",
+        source: "^collector$",
+        match: raw `^\[(evidence-upload|session-reports|cockpit-sync|install-receipts)\] .*(before a status came back|spooled for retry|entry kept for retry)`,
+        note: "the network dropped a request (TypeError fetch failed); the entry is kept or spooled and retried on the next tick",
+        basis: "collector logs, 3 d: 20 lines, every one says retry, spooled or kept",
+    },
+    {
+        id: "collector-commit-409-backoff",
+        class: "hiccup",
+        source: "^collector$",
+        match: raw `^(\[cockpit-sync\] raw evidence delivery failed reason=commit_failed_http_409|\[session-sync\] raw evidence held by delivery backoff)`,
+        note: "the server answered 409 to a commit: the pack is held by delivery backoff and tried again",
+        basis: "collector logs, 3 d: 9 lines, `held_backoff` names the same 409",
+    },
+    {
+        id: "collector-restage-missing-chunks",
+        class: "hiccup",
+        source: "^collector$",
+        match: raw `^\[evidence-upload\] restaging missing chunks reason=staging_missing_between_passes`,
+        note: "the server's staging disagreed between two passes; the client restages the missing chunks (the dashboard logs the other half as evidence-commit upload failed closed)",
+        basis: "collector logs 3 d and dashboard 12 h: the same reason on both sides",
+    },
+    {
+        id: "collector-agent-artifacts-pointer-not-ingested",
+        class: "hiccup",
+        source: "^collector$",
+        match: raw `^\[agent-artifacts\] report refused reason=report_failed http_status=404 server_reason=BLI-E004: Artifact raw evidence pointer has not been ingested`,
+        note: "the artifact report named a raw-evidence pointer the server had not ingested yet; the dashboard logs it as WARNING and the report is sent again. A count that never falls means the pointer never ingests.",
+        basis: "collector logs, 3 d: 49 lines; dashboard 1 h: 5 lines at level WARNING",
+    },
+    {
+        id: "collector-secret-guard-rejected",
+        class: "our_bug",
+        source: "^collector$",
+        match: raw `^\[cockpit-sync\] raw evidence (delivery failed reason=secret_guard_rejected|permanently rejected reason=raw_evidence_permanently_rejected:secret_guard_rejected)`,
+        note: "session-first collection says a secret guard masks the match and uploads the rest, never drops a file; a rejection is a finding to trace (which file, which rule), not noise",
+        basis: "collector logs, 3 d: 9 lines",
+    },
+    {
+        id: "collector-spawn-cockpit-enoent",
+        class: "config_drift",
+        source: "^collector$",
+        match: raw `^\[process-runner\] spawn failed reason=spawn_failed error_code=ENOENT error_syscall=spawn cockpit`,
+        note: "the scheduled tick could not find `cockpit` on its PATH; `cockpit doctor` repairs the scheduler",
+        basis: "collector logs, 3 d: 8 lines (error_code ENOENT, syscall `spawn cockpit`)",
+    },
+    {
+        id: "collector-prune-blocked-by-uncommitted",
+        class: "capacity",
+        source: "^collector$",
+        match: raw `^\[collector prune\] still over the cap and nothing committed is left to take`,
+        note: "the staging area is over its cap and everything left is uncommitted, so nothing can be freed",
+        basis: "collector logs, 3 d: 1 line",
+    },
+    // ------------------------------------------------------------------ dashboard (Vercel runtime logs)
+    {
+        id: "dashboard-http-429-403",
+        class: "rate_pushback",
+        source: "^dashboard$",
+        match: raw `^HTTP (429|403) `,
+        note: "a request answered 429 or 403: a caller is being slowed or refused (the 403 may be an auth refusal, read the route)",
+        basis: "synthetic line the dashboard source adds for a request that ended 429 or 403",
+    },
+    {
+        id: "dashboard-http-gateway",
+        class: "hiccup",
+        source: "^dashboard$",
+        match: raw `^HTTP (502|503|504) `,
+        note: "a gateway or timeout answer: clients retry; a burst on one route is worth a look",
+        basis: "synthetic line for a 502, 503 or 504",
+    },
+    {
+        id: "dashboard-http-500",
+        class: "our_bug",
+        source: "^dashboard$",
+        match: raw `^HTTP 5\d\d `,
+        note: "one of our routes answered with a server error",
+        basis: "synthetic line for a 5xx other than the gateway three; one HTTP 500 on evidence/upload/chunk in 12 h",
+    },
+    {
+        id: "dashboard-ops-reader-timeout",
+        class: "hiccup",
+        source: "^dashboard$",
+        match: raw `^\[ops status\] reader over budget reason=reader_timeout`,
+        note: "one ops reader ran past its time budget and the board shows the rest without it (declared WARNING by the code)",
+        basis: "dashboard 12 h: 15 lines",
+    },
+    {
+        id: "dashboard-memory-arm-deadline",
+        class: "hiccup",
+        match: raw `\barm_deadline_exceeded\b`,
+        note: "a BLI Memory arm hit its deadline and the answer was built from the other arms (docs/architecture/agent-memory.md: never fixed by moving a timeout)",
+        basis: "dashboard 12 h: 14 lines across eight arms, all declared WARNING",
+    },
+    {
+        id: "dashboard-evidence-staging-missing",
+        class: "hiccup",
+        source: "^dashboard$",
+        match: raw `^\[(evidence-assembly|evidence-commit)\] .*reason=staging_missing_between_passes`,
+        note: "the commit failed closed because staging changed between two passes; the collector restages and commits again",
+        basis: "dashboard 12 h: 6 lines; the collector logs the restage",
+    },
+    {
+        id: "dashboard-storage-bad-gateway",
+        class: "hiccup",
+        source: "^dashboard$",
+        match: raw `StorageApiError: Bad Gateway`,
+        note: "Supabase storage answered 502 on an offload write; the data was kept inline, nothing lost",
+        basis: "dashboard 12 h: 1 line `offload write failed, kept inline`",
+    },
+    {
+        id: "dashboard-agent-artifacts-pointer-404",
+        class: "hiccup",
+        source: "^dashboard$",
+        match: raw `^\[ambient agent-artifacts\] report refused reason=report_refused status=404`,
+        note: "the other half of collector-agent-artifacts-pointer-not-ingested: refused while the pointer is not ingested, sent again",
+        basis: "dashboard 1 h: 5 lines at level WARNING",
+    },
+    {
+        id: "dashboard-work-ref-refused",
+        class: "benign",
+        source: "^dashboard$",
+        match: raw `^\[work (issues|issue-ref)\] refused reason=issue_not_found_or_unreadable`,
+        note: "a person or agent asked for a ticket that does not exist or that their RLS cannot read; the refusal is the design",
+        basis: "dashboard 1 h: 2 lines for a made-up ticket id",
+    },
+    {
+        id: "dashboard-work-completeness-capped",
+        class: "benign",
+        source: "^dashboard$",
+        match: raw `^\[work issues\] completeness reason=capped`,
+        note: "a list read stopped at its cap on purpose and says so (exhausted / capped / failed-partial); only failed-partial is trouble",
+        basis: "dashboard 1 h: 1 line at level WARNING",
+    },
+    {
+        id: "dashboard-msg-audit-escape-read",
+        class: "benign",
+        source: "^dashboard$",
+        match: raw `^\[msg audit\] escape read`,
+        note: "the audit record of a message read outside the caller's channels; written at WARNING on purpose so it is counted, never an alert",
+        basis: "dashboard 12 h: 22 lines",
+    },
+    {
+        id: "dashboard-mcp-oversized",
+        class: "benign",
+        source: "^dashboard$",
+        match: raw `^\[bli-cockpit-mcp tool\] warn outcome=answered_oversized`,
+        note: "an MCP tool answered over its per-half byte budget; measured by scripts/smoke.ts, not a failure",
+        basis: "dashboard 1 h: 1 line",
+    },
+    // ------------------------------------------------------------------ railway cron services
+    {
+        id: "railway-cal-sync-token-expired",
+        class: "hiccup",
+        source: "^railway$",
+        unit: "^cal-sync$",
+        match: raw `(sync_token_expired|\[cal sync\] token expired|\[cal-sync\] stage # attempt # failed \(exit \d+\); retrying in #s$|^npm error (path|workspace|location|command|code|Lifecycle script))`,
+        note: "Google expired a calendar's sync token; attempt 1 exits 1 (the npm error lines are that exit), the stage retries after 60 s with a full sync and succeeds",
+        basis: "railway cal-sync 1 d: 04:01 attempt 1 failed, 04:02 attempt 2 ok, 98 events read in full mode. A stage that fails every attempt is NOT matched here and stays an alert.",
+    },
+    {
+        id: "railway-docs-import-notion-page-not-shared",
+        class: "dead_source",
+        source: "^railway$",
+        unit: "^docs-import-notion$",
+        match: raw `^error: Public API request failed \(# Not Found object_not_found\): Could not find page with ID`,
+        note: "the Notion integration cannot see a page that was never shared with it (notion_page_unreadable): the world, nothing to fix here",
+        basis: "railway docs-import-notion 1 d: 51 lines, `Make sure the relevant pages and databases are shared with your integration`",
+    },
+    {
+        id: "railway-docs-import-notion-database-as-page",
+        class: "our_bug",
+        source: "^railway$",
+        unit: "^docs-import-notion$",
+        match: raw `^error: Public API request failed \(# Bad Request validation_error\): Provided ID <uuid> is a database, not a page`,
+        note: "the importer asked Notion for a PAGE with a DATABASE's id; it should use the retrieve-database API (the importer places each database as a folder)",
+        basis: "railway docs-import-notion 1 d: 10 lines, Notion's own message names the fix",
+    },
+    // ------------------------------------------------------------------ any source
+    {
+        id: "any-ai-sdk-warning",
+        class: "benign",
+        match: raw `^AI SDK Warning`,
+        note: "the AI SDK notes that a knob (temperature) is ignored by a reasoning model, once per call, plus its own switch-off hint; the provider ignores the knob. Dropping it at the call site (reasoning-policy) is the cleanup.",
+        basis: "dashboard 12 h: 46 lines on /api/memory/save; railway ladder 1 d: 6 lines",
+    },
+    {
+        id: "any-npm-warn-production",
+        class: "benign",
+        source: "^railway$",
+        match: raw `^npm warn config production Use \`--omit=dev\` instead\.$`,
+        note: "every Railway service's npm command still passes the deprecated --production flag: harmless until npm removes it (a config_drift cleanup, not an incident)",
+        basis: "railway, every service, once per start: about 20 lines in 1 d",
+    },
+];
+export const TOWER_TABLE = {
+    version: 1,
+    classes: TOWER_CLASSES,
+    patterns: TOWER_PATTERNS,
+    noiseUnits: [],
+};
+let cached = null;
+/** The compiled Tower table (built once per process). */
+export function towerClassTable() {
+    cached ??= new ClassTable(TOWER_TABLE);
+    return cached;
+}

package/dist/window.d.ts

@@ -0,0 +1,21 @@
+/**
+ * The time window a digest covers: `90s`, `15m`, `2h`, `1d`, a bare number of
+ * minutes, or an ISO timestamp. Kaiben's `--since` took the same relative forms.
+ */
+export interface LogWindow {
+    /** Epoch seconds: lines older than this are outside the window. */
+    fromEpoch: number;
+    /** Epoch seconds the window was cut at (now). */
+    toEpoch: number;
+    /** How the person wrote it, for the header line. */
+    label: string;
+}
+/** The only shapes `--since` may take: a count and one unit, or an ISO timestamp. Nothing else reaches a program. */
+export declare const SINCE_ALLOWLIST: RegExp;
+export declare class WindowError extends Error {
+    readonly reason = "invalid_since";
+}
+/** Seconds in a relative window like `15m`, or null when the text is not one. */
+export declare function relativeSeconds(text: string): number | null;
+export declare function parseWindow(text: string | undefined, nowMs?: number): LogWindow;
+export declare function isoOf(epochSeconds: number): string;

package/dist/window.js

@@ -0,0 +1,39 @@
+/**
+ * The time window a digest covers: `90s`, `15m`, `2h`, `1d`, a bare number of
+ * minutes, or an ISO timestamp. Kaiben's `--since` took the same relative forms.
+ */
+const UNIT_SECONDS = { "": 60, s: 1, m: 60, h: 3600, d: 86400 };
+/** The only shapes `--since` may take: a count and one unit, or an ISO timestamp. Nothing else reaches a program. */
+export const SINCE_ALLOWLIST = /^(\d{1,4}[smhd]|\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}(:\d{2}(\.\d{1,9})?)?(Z|[+-]\d{2}:\d{2})?)?)$/;
+export class WindowError extends Error {
+    reason = "invalid_since";
+}
+/** Seconds in a relative window like `15m`, or null when the text is not one. */
+export function relativeSeconds(text) {
+    const match = /^(\d+(?:\.\d+)?)\s*([smhd]?)$/.exec(text.trim());
+    if (!match)
+        return null;
+    return Number.parseFloat(match[1]) * UNIT_SECONDS[match[2]];
+}
+export function parseWindow(text, nowMs = Date.now()) {
+    const raw = (text ?? "15m").trim();
+    if (!SINCE_ALLOWLIST.test(raw))
+        throw new WindowError(`--since wants 15m, 1h, 2d or an ISO time, not ${JSON.stringify(raw.slice(0, 40))}`);
+    const toEpoch = nowMs / 1000;
+    const seconds = relativeSeconds(raw);
+    if (seconds !== null) {
+        if (seconds <= 0)
+            throw new WindowError(`--since wants 15m, 1h, 2d or an ISO time, not ${JSON.stringify(raw)}`);
+        return { fromEpoch: toEpoch - seconds, toEpoch, label: `last ${raw}` };
+    }
+    const parsed = Date.parse(raw);
+    if (!Number.isFinite(parsed) || !/^\d{4}-\d{2}-\d{2}/.test(raw)) {
+        throw new WindowError(`--since wants 15m, 1h, 2d or an ISO time, not ${JSON.stringify(raw)}`);
+    }
+    if (parsed > nowMs)
+        throw new WindowError("--since is in the future");
+    return { fromEpoch: parsed / 1000, toEpoch, label: `since ${new Date(parsed).toISOString().slice(0, 16)}Z` };
+}
+export function isoOf(epochSeconds) {
+    return new Date(epochSeconds * 1000).toISOString();
+}

package/package.json

@@ -1,6 +1,42 @@
 {
   "name": "@bli-cockpit/log-digest",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "private": false,
+  "description": "Token-cheap digest of log lines: variable parts masked into templates, equal templates counted, routine runs collapsed, every template classified. Node stdlib only.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist/",
+    "README.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc",
+    "prepack": "rm -rf dist && tsc",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  },
+  "devDependencies": {
+    "@types/node": "20.19.39",
+    "typescript": "5.9.3",
+    "vitest": "3.2.4"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/BLI-INC/bli-cockpit.git",
+    "directory": "packages/log-digest"
+  }
+}