feat(logs): app log store — backend pino DB sink + frontend error collection

Add a third data stream (app_logs), distinct from the signed ledger and device
telemetry, for operational/diagnostic logs — an offline appliance has no Sentry to
ship to, so the host is the log store.

Backend: a pino stream tees warn/error/fatal into app_logs (info/debug stay
stdout-only) with no call-site change; the DB is built before Fastify so the logger
has its sink. Frontend (lib/logger.ts): ships failed API requests (minus 401 churn),
window.onerror, unhandledrejection, and a top-level React ErrorBoundary; console
warn/error forwarded only at debug/trace. Batched/throttled POST, sendBeacon on
pagehide, loop-safe (never logs the /api/logs call), best-effort everywhere.

POST /api/logs (any signed-in user, CSRF, tolerant) + GET /api/logs gated by a new
log:read permission (new `log` RBAC resource; admin holds it). Retention: pruned by
age + row cap, hourly + at startup. UI: a Logs screen under /setup (filter
level/source/since, expand to context+stack), sq+en. Migration 0009_app_logs.

Verified end-to-end via app.inject: login -> POST 204 -> GET 200 with the record;
backend warn/error persisted, info dropped; non-admin GET 403 / POST 204.

Claude-Session: https://claude.ai/code/session_01Xcm6ikLgGoCxxHrxtjkk5V

apps/server/src/log-service.ts

@@ -0,0 +1,236 @@
+import { randomUUID } from "node:crypto";
+import { and, appLogs, desc, eq, sql, type Db } from "@parking/db";
+import {
+  LOG_LEVEL_ORDER,
+  type AppLogRecord,
+  type ClientLogInput,
+  type LogLevel,
+  type LogSource,
+} from "@parking/shared";
+
+// Application/diagnostic LOG SINK — the host-side store behind the third log stream
+// (app_logs), distinct from the signed ledger and device telemetry. It persists:
+//   - BACKEND warn/error/fatal, fed by a pino stream (see pinoDbStream) so any
+//     app.log.warn/error lands in the DB without changing call sites.
+//   - FRONTEND errors POSTed to /api/logs (failed requests, uncaught errors).
+// Everything here is UNSIGNED + prunable. Pruned by age AND a row cap so an offline
+// appliance with finite disk can't be filled by a log storm. See
+// wiki/concepts/app-logs.md, decisions/event-streams-split.md.
+
+/** Only warn and above are persisted from the backend (info/debug stay stdout-only). */
+const BACKEND_PERSIST_MIN: LogLevel = "warn";
+
+/** Defensive caps so one runaway log can't bloat a row (chars). */
+const MAX_MESSAGE = 4_000;
+const MAX_STACK = 16_000;
+const MAX_CONTEXT_JSON = 16_000;
+
+export interface LogRetention {
+  /** Delete logs older than this many days. */
+  readonly maxAgeDays: number;
+  /** Hard cap on total rows — the oldest beyond this are pruned. */
+  readonly maxRows: number;
+}
+
+export const DEFAULT_RETENTION: LogRetention = {
+  maxAgeDays: Number(process.env.LOG_RETENTION_DAYS ?? 30),
+  maxRows: Number(process.env.LOG_RETENTION_MAX_ROWS ?? 50_000),
+};
+
+function clamp(s: string | null | undefined, max: number): string | null {
+  if (s == null) return null;
+  return s.length > max ? s.slice(0, max) : s;
+}
+
+/** Serialize context to JSON, bounded — never throw on a circular/huge object. */
+function safeContext(ctx: Record<string, unknown> | null | undefined): Record<string, unknown> | null {
+  if (ctx == null) return null;
+  try {
+    const json = JSON.stringify(ctx);
+    if (json.length <= MAX_CONTEXT_JSON) return ctx;
+    return { _truncated: true, preview: json.slice(0, MAX_CONTEXT_JSON) };
+  } catch {
+    return { _unserializable: true };
+  }
+}
+
+export class LogService {
+  readonly #db: Db;
+  readonly #retention: LogRetention;
+  /** Reentrancy guard: never let persisting a log itself emit a persisted log. */
+  #writing = false;
+
+  constructor(db: Db, retention: LogRetention = DEFAULT_RETENTION) {
+    this.#db = db;
+    this.#retention = retention;
+  }
+
+  /** Low-level insert. Best-effort: a logging failure must never break a request or
+   *  recurse (a DB error here would otherwise log → insert → error → log …). */
+  #insert(row: {
+    level: LogLevel;
+    source: LogSource;
+    message: string;
+    context?: Record<string, unknown> | null;
+    httpStatus?: number | null;
+    path?: string | null;
+    stack?: string | null;
+    userId?: string | null;
+    userAgent?: string | null;
+    createdAt?: string;
+  }): void {
+    if (this.#writing) return;
+    this.#writing = true;
+    try {
+      this.#db
+        .insert(appLogs)
+        .values({
+          id: randomUUID(),
+          level: row.level,
+          source: row.source,
+          message: clamp(row.message, MAX_MESSAGE) ?? "",
+          context: safeContext(row.context),
+          httpStatus: row.httpStatus ?? null,
+          path: clamp(row.path, 512),
+          stack: clamp(row.stack, MAX_STACK),
+          userId: row.userId ?? null,
+          userAgent: clamp(row.userAgent, 512),
+          createdAt: row.createdAt ?? new Date().toISOString(),
+        })
+        .run();
+    } catch {
+      // Swallow — diagnostics must never take down the path they observe. (Can't log
+      // it; that's the recursion we're guarding against.)
+    } finally {
+      this.#writing = false;
+    }
+  }
+
+  /** Persist a BACKEND log line (called by the pino stream). Below warn is dropped. */
+  recordBackend(level: LogLevel, message: string, context?: Record<string, unknown> | null): void {
+    if (LOG_LEVEL_ORDER[level] < LOG_LEVEL_ORDER[BACKEND_PERSIST_MIN]) return;
+    this.#insert({ level, source: "backend", message, context });
+  }
+
+  /** Persist a FRONTEND-reported log (from POST /api/logs). The server stamps the
+   *  user + receive time; the client supplies level/message/context. */
+  recordClient(
+    input: ClientLogInput,
+    meta: { userId?: string | null; userAgent?: string | null },
+  ): void {
+    this.#insert({
+      level: input.level,
+      source: "frontend",
+      message: input.message,
+      context: input.context ?? null,
+      httpStatus: input.httpStatus ?? null,
+      path: input.path ?? null,
+      stack: input.stack ?? null,
+      userId: meta.userId ?? null,
+      userAgent: meta.userAgent ?? null,
+      // Keep the client's capture time in context for ordering; createdAt is server time.
+      createdAt: new Date().toISOString(),
+    });
+  }
+
+  /** Read recent logs, newest first, with optional level/source/since filters. */
+  query(opts: {
+    limit: number;
+    level?: LogLevel;
+    source?: LogSource;
+    since?: string;
+  }): AppLogRecord[] {
+    const conds = [];
+    if (opts.level) conds.push(eq(appLogs.level, opts.level));
+    if (opts.source) conds.push(eq(appLogs.source, opts.source));
+    if (opts.since) conds.push(sql`${appLogs.createdAt} >= ${opts.since}`);
+    const rows = this.#db
+      .select()
+      .from(appLogs)
+      .where(conds.length ? and(...conds) : undefined)
+      .orderBy(desc(appLogs.createdAt))
+      .limit(opts.limit)
+      .all();
+    return rows as unknown as AppLogRecord[];
+  }
+
+  /** Prune by age then by row cap. Returns how many rows were deleted. Safe to call
+   *  on a timer; cheap (indexed on created_at). */
+  prune(): number {
+    let deleted = 0;
+    try {
+      const cutoff = new Date(Date.now() - this.#retention.maxAgeDays * 86_400_000).toISOString();
+      const byAge = this.#db.delete(appLogs).where(sql`${appLogs.createdAt} < ${cutoff}`).run();
+      deleted += byAge.changes ?? 0;
+
+      // Row cap: keep the newest maxRows, delete the rest. One subquery — find the
+      // created_at boundary of the keep-window, delete older.
+      const total = this.#db.select({ c: sql<number>`count(*)` }).from(appLogs).get();
+      const count = total?.c ?? 0;
+      if (count > this.#retention.maxRows) {
+        const boundary = this.#db
+          .select({ createdAt: appLogs.createdAt })
+          .from(appLogs)
+          .orderBy(desc(appLogs.createdAt))
+          .limit(1)
+          .offset(this.#retention.maxRows - 1)
+          .get();
+        if (boundary) {
+          const byCap = this.#db
+            .delete(appLogs)
+            .where(sql`${appLogs.createdAt} < ${boundary.createdAt}`)
+            .run();
+          deleted += byCap.changes ?? 0;
+        }
+      }
+    } catch {
+      // best-effort
+    }
+    return deleted;
+  }
+}
+
+/**
+ * A pino-compatible write stream that forwards BACKEND warn+ lines into the LogService.
+ * Pino writes one JSON object per line to this stream; we parse, map the numeric level
+ * to a name, and persist. Returned as `{ write }` so it can be passed as pino's stream.
+ * stdout still receives the same line (we tee), so console logging is unchanged.
+ */
+export function pinoDbStream(
+  service: LogService,
+  tee: NodeJS.WritableStream,
+): { write: (line: string) => void } {
+  const NUM_TO_LEVEL: Record<number, LogLevel> = {
+    10: "trace",
+    20: "debug",
+    30: "info",
+    40: "warn",
+    50: "error",
+    60: "fatal",
+  };
+  return {
+    write(line: string): void {
+      // Always tee to the original destination first (don't lose stdout logging).
+      try {
+        tee.write(line);
+      } catch {
+        /* ignore */
+      }
+      try {
+        const obj = JSON.parse(line) as {
+          level?: number;
+          msg?: string;
+          err?: { stack?: string; message?: string };
+          [k: string]: unknown;
+        };
+        const level = NUM_TO_LEVEL[obj.level ?? 30] ?? "info";
+        if (LOG_LEVEL_ORDER[level] < LOG_LEVEL_ORDER[BACKEND_PERSIST_MIN]) return;
+        // Strip pino's noisy standard fields from the persisted context.
+        const { level: _l, time: _t, pid: _p, hostname: _h, msg, ...rest } = obj;
+        service.recordBackend(level, typeof msg === "string" ? msg : "", rest);
+      } catch {
+        // A non-JSON line (shouldn't happen with pino) — ignore for persistence.
+      }
+    },
+  };
+}

apps/server/src/routes/logs.ts

@@ -0,0 +1,66 @@
+import type { FastifyInstance } from "fastify";
+import type { AppLogRecord, ClientLogInput, LogLevel } from "@parking/shared";
+import { requireAuth, requirePermission } from "../auth.js";
+import type { LogService } from "../log-service.js";
+
+// Application/diagnostic logs (app_logs) — see wiki/concepts/app-logs.md. Two ends:
+//   - POST /api/logs  : the FRONTEND ships its errors here (failed requests, uncaught
+//                       exceptions). Any signed-in user may write (it's their own
+//                       browser's diagnostics); CSRF still applies (mutation).
+//   - GET  /api/logs  : read the store — gated by `log:read` (admin/diagnostic role).
+// Writes go through the shared LogService (bounded, best-effort, reentrancy-guarded);
+// the DB sink for BACKEND warn+ is wired at the pino stream, not here.
+
+const LEVELS: ReadonlySet<string> = new Set(["trace", "debug", "info", "warn", "error", "fatal"]);
+
+/** Cap a single ingest batch so a misbehaving client can't flood the store. */
+const MAX_BATCH = 50;
+
+function isValidEntry(e: unknown): e is ClientLogInput {
+  if (!e || typeof e !== "object") return false;
+  const o = e as Record<string, unknown>;
+  return typeof o.message === "string" && typeof o.level === "string" && LEVELS.has(o.level);
+}
+
+export async function logRoutes(app: FastifyInstance, logService: LogService): Promise<void> {
+  // INGEST — accept one entry or a small batch ({ entries: [...] }). Returns 204.
+  // Deliberately tolerant: it never 4xx's on a malformed entry (a client erroring
+  // while reporting an error shouldn't get a second error) — invalid items are skipped.
+  app.post<{ Body: ClientLogInput | { entries?: unknown[] } }>(
+    "/api/logs",
+    { preHandler: requireAuth },
+    async (req, reply) => {
+      const body = req.body as ClientLogInput | { entries?: unknown[] };
+      const raw = Array.isArray((body as { entries?: unknown[] }).entries)
+        ? (body as { entries: unknown[] }).entries
+        : [body];
+      const userId = req.user?.sub ?? null;
+      const userAgent = req.headers["user-agent"] ?? null;
+      for (const entry of raw.slice(0, MAX_BATCH)) {
+        if (!isValidEntry(entry)) continue;
+        logService.recordClient(entry, { userId, userAgent });
+      }
+      reply.code(204).send();
+    },
+  );
+
+  // READ — newest first, with optional level/source/since filters + a limit. The
+  // booth Logs viewer calls this. Gated by log:read.
+  app.get<{ Querystring: { limit?: string; level?: string; source?: string; since?: string } }>(
+    "/api/logs",
+    { preHandler: requirePermission("log:read") },
+    async (req): Promise<{ logs: AppLogRecord[] }> => {
+      const limit = Math.min(Math.max(Number(req.query.limit) || 200, 1), 2000);
+      const level = (req.query.level ?? "").trim();
+      const source = (req.query.source ?? "").trim();
+      const since = (req.query.since ?? "").trim();
+      const logs = logService.query({
+        limit,
+        level: LEVELS.has(level) ? (level as LogLevel) : undefined,
+        source: source === "frontend" || source === "backend" ? source : undefined,
+        since: since || undefined,
+      });
+      return { logs };
+    },
+  );
+}

apps/server/src/server.ts

@@ -17,6 +17,8 @@ import { CredentialCapture } from "./credential-capture.js";
 import { PrinterMonitor } from "./printer-monitor.js";
 import { DeviceMonitor } from "./device-monitor.js";
 import { buildSigner, buildVerifier } from "./signer.js";
+import { LogService, pinoDbStream } from "./log-service.js";
+import { logRoutes } from "./routes/logs.js";
 import { authRoutes } from "./routes/auth.js";
 import { userRoutes } from "./routes/users.js";
 import { roleRoutes } from "./routes/roles.js";
@@ -43,12 +45,20 @@ export interface BuildOptions {
 }
 
 export async function buildServer(opts: BuildOptions = {}): Promise<FastifyInstance> {
-  const app = Fastify({
-    logger: { level: process.env.LOG_LEVEL ?? "info" },
-  });
-
+  // DB first — the logger's DB sink needs it before Fastify is constructed.
   const db = opts.db ?? createDb();
 
+  // Application-log store: a pino stream tees warn+ lines into app_logs (and still
+  // writes them to stdout), so backend warnings/errors are queryable from the booth
+  // alongside frontend errors. See log-service.ts + wiki/concepts/app-logs.md.
+  const logService = new LogService(db);
+  const app = Fastify({
+    logger: {
+      level: process.env.LOG_LEVEL ?? "info",
+      stream: pinoDbStream(logService, process.stdout),
+    },
+  });
+
   // Wire the RBAC permission resolver to this DB (route guards resolve a user's
   // role → permission set through it). See auth.ts.
   initAuth(db);
@@ -188,6 +198,20 @@ export async function buildServer(opts: BuildOptions = {}): Promise<FastifyInsta
   // at capacity) is in the entry flow. See wiki/concepts/capacity-occupancy.md.
   await siteRoutes(app, db);
 
+  // Application logs: ingest frontend errors (POST /api/logs, any signed-in user) +
+  // read the store (GET /api/logs, log:read). See wiki/concepts/app-logs.md.
+  await logRoutes(app, logService);
+
+  // Periodic retention prune (age + row cap) so the log table stays bounded on the
+  // offline appliance. Runs hourly; unref'd so it never holds the process open.
+  const pruneTimer = setInterval(() => {
+    const n = logService.prune();
+    if (n > 0) app.log.debug(`pruned ${n} app_log rows`);
+  }, 60 * 60 * 1000);
+  pruneTimer.unref();
+  logService.prune(); // once at startup
+  app.addHook("onClose", async () => clearInterval(pruneTimer));
+
   const unsubscribeInput = deviceEvents.onInput((e) => {
     // Record every input edge as unsigned telemetry, keyed to the device that fired
     // (provenance). No lane — the pool-of-spaces model has none. The entry flow

apps/web/src/LogsViewer.tsx

@@ -0,0 +1,159 @@
+import { useState } from "react";
+import { useTranslation } from "react-i18next";
+import { useQuery } from "@tanstack/react-query";
+import { fetchLogs, type AppLogRecord, type LogLevel } from "./api.js";
+import { formatRelativeDateTime } from "./lib/format.js";
+
+// Diagnostic log viewer (app_logs) — backend warn+ and frontend errors in one place.
+// Gated by log:read server-side. Filter by level / source / since; each row expands to
+// the structured context + stack. Read-only — logs are an evidence/diagnostic stream,
+// never edited. See wiki/concepts/app-logs.md.
+
+const LEVELS: LogLevel[] = ["trace", "debug", "info", "warn", "error", "fatal"];
+
+/** Terminal-theme colour per level. */
+const LEVEL_COLOR: Record<LogLevel, string> = {
+  trace: "text-term-muted",
+  debug: "text-term-muted",
+  info: "text-term-cyan",
+  warn: "text-term-amber",
+  error: "text-term-red",
+  fatal: "text-term-red",
+};
+
+function LogRow({ log }: { log: AppLogRecord }) {
+  const { t } = useTranslation();
+  const [open, setOpen] = useState(false);
+  const hasDetail = (log.context && Object.keys(log.context).length > 0) || log.stack;
+
+  return (
+    <div className={`border-b border-term-border/50 ${log.level === "error" || log.level === "fatal" ? "bg-term-red/5" : ""}`}>
+      <button
+        type="button"
+        onClick={() => hasDetail && setOpen((v) => !v)}
+        className={`grid w-full grid-cols-[auto_4rem_5rem_1fr_auto] items-center gap-x-3 px-1 py-1 text-left text-[12px] ${
+          hasDetail ? "hover:bg-term-panel-2" : "cursor-default"
+        }`}
+      >
+        <span className="text-term-muted tabular-nums">{formatRelativeDateTime(log.createdAt, t)}</span>
+        <span className={`font-semibold uppercase ${LEVEL_COLOR[log.level]}`}>{log.level}</span>
+        <span className="text-term-muted">{t(log.source === "frontend" ? "logs.frontend" : "logs.backend")}</span>
+        <span className="truncate text-term-text">{log.message}</span>
+        <span className="text-term-muted tabular-nums">{log.httpStatus ?? ""}</span>
+      </button>
+      {open && hasDetail && (
+        <div className="border-t border-term-border/40 bg-term-bg px-3 py-2">
+          {log.path && (
+            <div className="mb-1 text-[11px] text-term-muted">
+              {t("logs.path")}: <code className="text-term-text">{log.path}</code>
+            </div>
+          )}
+          {log.context && Object.keys(log.context).length > 0 && (
+            <pre className="mb-2 overflow-x-auto rounded-term border border-term-border bg-term-panel-2 p-2 text-[11px] text-term-text">
+              {JSON.stringify(log.context, null, 2)}
+            </pre>
+          )}
+          {log.stack && (
+            <pre className="overflow-x-auto rounded-term border border-term-border bg-term-panel-2 p-2 text-[11px] text-term-red/90">
+              {log.stack}
+            </pre>
+          )}
+        </div>
+      )}
+    </div>
+  );
+}
+
+export function LogsViewer() {
+  const { t } = useTranslation();
+  const [level, setLevel] = useState("");
+  const [source, setSource] = useState("");
+  const [since, setSince] = useState("");
+  const [applied, setApplied] = useState<{ level?: string; source?: string; since?: string }>({});
+
+  const q = useQuery({
+    queryKey: ["logs", applied],
+    queryFn: () => fetchLogs({ ...applied, limit: 500 }),
+    refetchInterval: 15_000, // keep the booth view roughly live without a WS
+  });
+
+  const logs = q.data?.logs ?? [];
+
+  function apply() {
+    setApplied({
+      level: level || undefined,
+      source: source || undefined,
+      since: since ? new Date(`${since}T00:00:00`).toISOString() : undefined,
+    });
+  }
+  function clear() {
+    setLevel("");
+    setSource("");
+    setSince("");
+    setApplied({});
+  }
+
+  return (
+    <div className="mx-auto max-w-5xl">
+      <div className="mb-3 flex items-center justify-between">
+        <h1 className="text-sm font-bold uppercase tracking-widest text-term-amber">{t("logs.title")}</h1>
+        <button type="button" className="btn btn-ghost btn-sm" onClick={() => q.refetch()}>
+          {t("logs.refresh")}
+        </button>
+      </div>
+
+      <div className="card mb-3 flex flex-wrap items-end gap-3 p-3">
+        <div className="field">
+          <span className="label">{t("logs.level")}</span>
+          <select className="select w-32" value={level} onChange={(e) => setLevel(e.target.value)}>
+            <option value="">{t("logs.allLevels")}</option>
+            {LEVELS.map((l) => (
+              <option key={l} value={l}>
+                {l}
+              </option>
+            ))}
+          </select>
+        </div>
+        <div className="field">
+          <span className="label">{t("logs.source")}</span>
+          <select className="select w-36" value={source} onChange={(e) => setSource(e.target.value)}>
+            <option value="">{t("logs.allSources")}</option>
+            <option value="frontend">{t("logs.frontend")}</option>
+            <option value="backend">{t("logs.backend")}</option>
+          </select>
+        </div>
+        <div className="field">
+          <span className="label">{t("logs.since")}</span>
+          <input type="date" className="input w-40" value={since} onChange={(e) => setSince(e.target.value)} />
+        </div>
+        <button type="button" className="btn btn-primary btn-sm" onClick={apply}>
+          {t("logs.apply")}
+        </button>
+        <button type="button" className="btn btn-ghost btn-sm" onClick={clear}>
+          {t("logs.clear")}
+        </button>
+      </div>
+
+      <div className="card p-2">
+        {q.isLoading ? (
+          <div className="p-3 text-[12px] text-term-muted">{t("common.loading")}</div>
+        ) : logs.length === 0 ? (
+          <div className="p-3 text-[12px] text-term-muted">{t("logs.empty")}</div>
+        ) : (
+          <>
+            <div className="grid grid-cols-[auto_4rem_5rem_1fr_auto] gap-x-3 border-b border-term-border px-1 pb-1 text-[10px] uppercase tracking-wider text-term-muted">
+              <span>{t("logs.time")}</span>
+              <span>{t("logs.level")}</span>
+              <span>{t("logs.source")}</span>
+              <span>{t("logs.message")}</span>
+              <span>{t("logs.status")}</span>
+            </div>
+            {logs.map((log) => (
+              <LogRow key={log.id} log={log} />
+            ))}
+          </>
+        )}
+      </div>
+    </div>
+  );
+}

apps/web/src/api.ts

@@ -5,6 +5,9 @@
 // CSRF cookie back in the X-CSRF-Token header (double-submit). See
 // wiki/entities/local-jwt-auth.md.
 
+import { logFailedRequest } from "./lib/logger.js";
+import type { AppLogRecord } from "@parking/shared";
+
 const CSRF_COOKIE = "parking_csrf";
 const CSRF_HEADER = "X-CSRF-Token";
 
@@ -27,7 +30,14 @@ export async function apiFetch<T>(path: string, init: RequestInit = {}): Promise
   const res = await fetch(path, { ...init, headers, credentials: "include" });
   if (!res.ok) {
     const msg = (await res.json().catch(() => ({}))) as { error?: string };
-    throw new ApiError(msg.error ?? `${path}: ${res.status}`, res.status);
+    const error = msg.error ?? `${path}: ${res.status}`;
+    // Ship the failed request to the backend log store (best-effort, loop-safe — the
+    // logger itself never logs the /api/logs call). 401s are normal pre-login churn,
+    // so we don't report them as errors. See lib/logger.ts.
+    if (res.status !== 401) {
+      logFailedRequest({ path, method, status: res.status, error });
+    }
+    throw new ApiError(error, res.status);
   }
   if (res.status === 204) return undefined as T;
   return res.json() as Promise<T>;
@@ -160,6 +170,23 @@ export function deleteRole(id: string): Promise<{ ok: boolean }> {
   return apiFetch(`/api/roles/${id}`, { method: "DELETE" });
 }
 
+// --- Application logs (app_logs) ------------------------------------------
+/** Read recent diagnostic logs (gated server-side by log:read). */
+export function fetchLogs(params: {
+  limit?: number;
+  level?: string;
+  source?: string;
+  since?: string;
+} = {}): Promise<{ logs: AppLogRecord[] }> {
+  const q = new URLSearchParams();
+  if (params.limit) q.set("limit", String(params.limit));
+  if (params.level) q.set("level", params.level);
+  if (params.source) q.set("source", params.source);
+  if (params.since) q.set("since", params.since);
+  const qs = q.toString();
+  return apiFetch(`/api/logs${qs ? `?${qs}` : ""}`);
+}
+
 // --- Device setup ---------------------------------------------------------
 
 export interface ConfigField {
@@ -632,7 +659,8 @@ export function fetchDeviceStatus(): Promise<{ devices: DeviceStatus[] }> {
 
 /** A persisted ledger row. Re-exported from shared so UI code has one source of
  *  truth for the event shape (the same type the WS pushes). */
-export type { LedgerEvent } from "@parking/shared";
+export type { LedgerEvent, LogLevel, LogSource } from "@parking/shared";
+export type { AppLogRecord };
 
 /** Recent ledger events, newest first (default 100, max 1000). Used for the
  *  booth feed's initial load; live updates then arrive over the WS. `since` (ISO)

apps/web/src/lib/ErrorBoundary.tsx

@@ -0,0 +1,50 @@
+import { Component, type ErrorInfo, type ReactNode } from "react";
+import { logClient } from "./logger.js";
+
+// Top-level React error boundary: catches a render/lifecycle crash anywhere in the
+// tree, reports it to the backend log store (app_logs), and shows a minimal recovery
+// screen instead of a white page. A booth must never be left staring at a blank
+// screen with no trace of why. See wiki/concepts/app-logs.md.
+
+interface State {
+  hasError: boolean;
+  message?: string;
+}
+
+export class ErrorBoundary extends Component<{ children: ReactNode }, State> {
+  override state: State = { hasError: false };
+
+  static getDerivedStateFromError(err: Error): State {
+    return { hasError: true, message: err.message };
+  }
+
+  override componentDidCatch(err: Error, info: ErrorInfo): void {
+    logClient({
+      level: "fatal",
+      message: err.message || "React render error",
+      stack: err.stack,
+      path: typeof location !== "undefined" ? location.pathname : undefined,
+      context: { kind: "react_error_boundary", componentStack: info.componentStack },
+    });
+  }
+
+  override render(): ReactNode {
+    if (!this.state.hasError) return this.props.children;
+    // Intentionally un-i18n'd + dependency-free: the app tree just crashed, so we can't
+    // assume providers (i18n/router/query) are healthy.
+    return (
+      <div style={{ padding: "2rem", fontFamily: "monospace", color: "#e5e5e5", background: "#0a0a0a", minHeight: "100vh" }}>
+        <h1 style={{ color: "#ef4444" }}>Something went wrong</h1>
+        <p>The screen crashed and has been reported. Try reloading.</p>
+        {this.state.message && <pre style={{ color: "#a3a3a3" }}>{this.state.message}</pre>}
+        <button
+          type="button"
+          onClick={() => location.reload()}
+          style={{ marginTop: "1rem", padding: "0.5rem 1rem", cursor: "pointer" }}
+        >
+          Reload
+        </button>
+      </div>
+    );
+  }
+}

apps/web/src/lib/i18n/en.ts

@@ -49,6 +49,7 @@ export const en: Catalog = {
     users: "Users",
     roles: "Roles",
     shifts: "Shifts",
+    logs: "Logs",
   },
   status: {
     live: "LIVE",
@@ -482,6 +483,24 @@ export const en: Catalog = {
     cashRemoved: "Cash removed",
     loadFailed: "Failed to load shifts.",
   },
+  logs: {
+    title: "System logs",
+    refresh: "Refresh",
+    level: "Level",
+    source: "Source",
+    since: "Since",
+    apply: "Apply",
+    clear: "Clear",
+    allLevels: "All levels",
+    allSources: "All sources",
+    frontend: "Frontend",
+    backend: "Backend",
+    time: "Time",
+    message: "Message",
+    status: "Status",
+    path: "Path",
+    empty: "No logs.",
+  },
   pay: {
     ticket: "Ticket",
     entry: "Entry",

apps/web/src/lib/i18n/sq.ts

@@ -51,6 +51,7 @@ export const sq = {
     users: "Përdoruesit",
     roles: "Rolet",
     shifts: "Turnet",
+    logs: "Regjistrat",
   },
   status: {
     live: "LIVE",
@@ -495,6 +496,24 @@ export const sq = {
     cashRemoved: "Para të hequra",
     loadFailed: "Ngarkimi i turneve dështoi.",
   },
+  logs: {
+    title: "Regjistrat e sistemit",
+    refresh: "Rifresko",
+    level: "Niveli",
+    source: "Burimi",
+    since: "Që nga",
+    apply: "Apliko",
+    clear: "Pastro",
+    allLevels: "Të gjitha nivelet",
+    allSources: "Të gjitha burimet",
+    frontend: "Ndërfaqja",
+    backend: "Serveri",
+    time: "Koha",
+    message: "Mesazhi",
+    status: "Statusi",
+    path: "Rruga",
+    empty: "Asnjë regjistër.",
+  },
   pay: {
     ticket: "Bileta",
     entry: "Hyrja",

apps/web/src/lib/logger.ts

@@ -0,0 +1,198 @@
+// Frontend error/log collector. Ships failed requests, uncaught errors, and rejected
+// promises to the backend (POST /api/logs → app_logs), so a booth problem is
+// diagnosable from the host instead of needing the operator's devtools. See
+// wiki/concepts/app-logs.md.
+//
+// Design notes:
+//  - BATCHED + THROTTLED: entries queue and flush on a short timer (and on page hide
+//    via sendBeacon), so a burst of errors is one request, not hundreds.
+//  - LOOP-SAFE: a failure of the /api/logs request itself is NEVER re-logged (that
+//    would be an infinite error → log → error spiral). We also never recurse through
+//    apiFetch — the flush uses raw fetch/sendBeacon.
+//  - LEVEL-GATED noise: console.warn/error are only forwarded when the client log
+//    level is debug/trace (off by default) — they're noisy (3rd-party chatter). The
+//    high-signal sources (failed requests, uncaught errors) are always captured.
+
+import { LOG_LEVEL_ORDER, type ClientLogInput, type LogLevel } from "@parking/shared";
+
+const ENDPOINT = "/api/logs";
+const FLUSH_MS = 4000;
+const MAX_QUEUE = 100; // drop oldest beyond this (bounded memory on a long-lived booth)
+const CSRF_COOKIE = "parking_csrf";
+const CSRF_HEADER = "X-CSRF-Token";
+
+/** The client capture threshold. Entries below this level are dropped before queueing.
+ *  Default `info`: failed requests (error) + uncaught errors (error) always pass;
+ *  console.warn/error forwarding is wired separately and only ON at debug/trace. */
+let clientLevel: LogLevel = (import.meta.env.VITE_LOG_LEVEL as LogLevel) || "info";
+
+export function setClientLogLevel(level: LogLevel): void {
+  clientLevel = level;
+}
+export function getClientLogLevel(): LogLevel {
+  return clientLevel;
+}
+/** Are console.warn/error forwarded? Only when the client level is debug or trace. */
+function consoleForwardEnabled(): boolean {
+  return LOG_LEVEL_ORDER[clientLevel] <= LOG_LEVEL_ORDER.debug;
+}
+
+const queue: ClientLogInput[] = [];
+let timer: ReturnType<typeof setTimeout> | null = null;
+/** Set true only while flushing, so the flush's own network activity is never logged. */
+let flushing = false;
+
+function readCookie(name: string): string | null {
+  const m = document.cookie.match(new RegExp(`(?:^|; )${name}=([^;]*)`));
+  return m ? decodeURIComponent(m[1]!) : null;
+}
+
+function scheduleFlush(): void {
+  if (timer != null) return;
+  timer = setTimeout(() => {
+    timer = null;
+    void flush();
+  }, FLUSH_MS);
+}
+
+/** Enqueue an entry. Drops it if below the client level or if it concerns the log
+ *  endpoint itself (loop guard). */
+export function logClient(entry: ClientLogInput): void {
+  if (LOG_LEVEL_ORDER[entry.level] < LOG_LEVEL_ORDER[clientLevel]) return;
+  if (flushing) return; // don't log anything produced by the flush itself
+  if (entry.path && entry.path.startsWith(ENDPOINT)) return; // never log the log call
+  queue.push({ ...entry, at: entry.at ?? new Date().toISOString() });
+  if (queue.length > MAX_QUEUE) queue.splice(0, queue.length - MAX_QUEUE);
+  scheduleFlush();
+}
+
+/** POST the queued entries. Raw fetch (not apiFetch) so a failure can't recurse. A
+ *  failed flush silently re-queues nothing — diagnostics are best-effort, never fatal. */
+async function flush(): Promise<void> {
+  if (queue.length === 0) return;
+  const entries = queue.splice(0, queue.length);
+  flushing = true;
+  try {
+    const headers: Record<string, string> = { "content-type": "application/json" };
+    const csrf = readCookie(CSRF_COOKIE);
+    if (csrf) headers[CSRF_HEADER] = csrf;
+    await fetch(ENDPOINT, {
+      method: "POST",
+      headers,
+      credentials: "include",
+      body: JSON.stringify({ entries }),
+      keepalive: true,
+    });
+  } catch {
+    // Drop on failure — we must not re-log (loop) nor grow unbounded.
+  } finally {
+    flushing = false;
+  }
+}
+
+/** Best-effort synchronous flush on page hide (sendBeacon survives unload). */
+function flushBeacon(): void {
+  if (queue.length === 0) return;
+  const entries = queue.splice(0, queue.length);
+  try {
+    const blob = new Blob([JSON.stringify({ entries })], { type: "application/json" });
+    // sendBeacon can't set the CSRF header; the server accepts the ingest for any
+    // signed-in session (cookie sent automatically). If CSRF later guards it strictly,
+    // this path degrades to "lost on unload" — acceptable for diagnostics.
+    navigator.sendBeacon(ENDPOINT, blob);
+  } catch {
+    /* ignore */
+  }
+}
+
+/** Record a FAILED API request (called from apiFetch's error path). Always high-signal. */
+export function logFailedRequest(info: {
+  path: string;
+  method: string;
+  status: number;
+  error?: string;
+  requestId?: string;
+}): void {
+  logClient({
+    level: "error",
+    message: `${info.method} ${info.path} → ${info.status}${info.error ? `: ${info.error}` : ""}`,
+    httpStatus: info.status,
+    path: info.path,
+    context: { kind: "request_failed", method: info.method, requestId: info.requestId },
+  });
+}
+
+let installed = false;
+
+/** Wire global handlers once, at app startup. Idempotent. */
+export function installClientLogging(): void {
+  if (installed || typeof window === "undefined") return;
+  installed = true;
+
+  // Uncaught runtime errors.
+  window.addEventListener("error", (e: ErrorEvent) => {
+    logClient({
+      level: "error",
+      message: e.message || "uncaught error",
+      stack: e.error?.stack,
+      path: location.pathname,
+      context: {
+        kind: "window_error",
+        filename: e.filename,
+        line: e.lineno,
+        col: e.colno,
+      },
+    });
+  });
+
+  // Unhandled promise rejections.
+  window.addEventListener("unhandledrejection", (e: PromiseRejectionEvent) => {
+    const reason = e.reason;
+    const message =
+      reason instanceof Error ? reason.message : typeof reason === "string" ? reason : "unhandled rejection";
+    logClient({
+      level: "error",
+      message,
+      stack: reason instanceof Error ? reason.stack : undefined,
+      path: location.pathname,
+      context: { kind: "unhandled_rejection" },
+    });
+  });
+
+  // console.warn / console.error → only forwarded at debug/trace (noisy otherwise).
+  const origWarn = console.warn.bind(console);
+  const origError = console.error.bind(console);
+  console.warn = (...args: unknown[]) => {
+    origWarn(...args);
+    if (consoleForwardEnabled()) {
+      logClient({ level: "warn", message: stringifyArgs(args), path: location.pathname, context: { kind: "console" } });
+    }
+  };
+  console.error = (...args: unknown[]) => {
+    origError(...args);
+    if (consoleForwardEnabled()) {
+      logClient({ level: "error", message: stringifyArgs(args), path: location.pathname, context: { kind: "console" } });
+    }
+  };
+
+  // Flush on tab hide / unload.
+  window.addEventListener("visibilitychange", () => {
+    if (document.visibilityState === "hidden") flushBeacon();
+  });
+  window.addEventListener("pagehide", flushBeacon);
+}
+
+function stringifyArgs(args: unknown[]): string {
+  return args
+    .map((a) => (a instanceof Error ? a.message : typeof a === "string" ? a : safeStringify(a)))
+    .join(" ")
+    .slice(0, 2000);
+}
+
+function safeStringify(v: unknown): string {
+  try {
+    return JSON.stringify(v);
+  } catch {
+    return String(v);
+  }
+}

apps/web/src/main.tsx

@@ -3,12 +3,20 @@ import { createRoot } from "react-dom/client";
 import "./index.css";
 import "./lib/i18n/index.js"; // initialize i18next before the app renders
 import { App } from "./App.js";
+import { ErrorBoundary } from "./lib/ErrorBoundary.js";
+import { installClientLogging } from "./lib/logger.js";
+
+// Capture uncaught errors / rejections / console noise → backend log store, before
+// the app mounts so even an early crash is reported. See lib/logger.ts.
+installClientLogging();
 
 const rootEl = document.getElementById("root");
 if (!rootEl) throw new Error("root element not found");
 
 createRoot(rootEl).render(
   <StrictMode>
+    <ErrorBoundary>
       <App />
+    </ErrorBoundary>
   </StrictMode>,
 );

apps/web/src/router.tsx

@@ -27,6 +27,7 @@ import { SiteSettings } from "./SiteSettings.js";
 import { UsersManager } from "./UsersManager.js";
 import { RolesManager } from "./RolesManager.js";
 import { ShiftsHistory } from "./ShiftsHistory.js";
+import { LogsViewer } from "./LogsViewer.js";
 
 // Code-based TanStack Router (no file-based codegen — the app is small enough that
 // an explicit tree is clearer). The router context carries the signed-in user and
@@ -84,6 +85,7 @@ function SetupLayout() {
         {show("user:read") && <SetupTab to="/setup/users" label={t("nav.users")} />}
         {show("role:read") && <SetupTab to="/setup/roles" label={t("nav.roles")} />}
         {show("shift:read") && <SetupTab to="/setup/shifts" label={t("nav.shifts")} />}
+        {show("log:read") && <SetupTab to="/setup/logs" label={t("nav.logs")} />}
       </nav>
       <Outlet />
     </div>
@@ -363,6 +365,7 @@ const SETUP_TABS: { to: string; perm: Permission }[] = [
   { to: "/setup/users", perm: "user:read" },
   { to: "/setup/roles", perm: "role:read" },
   { to: "/setup/shifts", perm: "shift:read" },
+  { to: "/setup/logs", perm: "log:read" },
 ];
 
 // /setup is a LAYOUT route (tab bar + <Outlet>); the config screens are its
@@ -437,6 +440,14 @@ const shiftsHistoryRoute = createRoute({
   },
 });
 
+// Diagnostic logs. Gated by log:read (an admin/diagnostic permission).
+const logsRoute = createRoute({
+  getParentRoute: () => setupRoute,
+  path: "logs",
+  beforeLoad: ({ context }) => requirePerm("log:read")(context),
+  component: LogsViewer,
+});
+
 const routeTree = rootRoute.addChildren([
   indexRoute,
   boothRoute,
@@ -450,6 +461,7 @@ const routeTree = rootRoute.addChildren([
     usersRoute,
     rolesRoute,
     shiftsHistoryRoute,
+    logsRoute,
   ]),
 ]);
 

packages/db/drizzle/0009_app_logs.sql

@@ -0,0 +1,20 @@
+CREATE TABLE `app_logs` (
+	`id` text PRIMARY KEY NOT NULL,
+	`level` text NOT NULL,
+	`source` text NOT NULL,
+	`message` text NOT NULL,
+	`context` text,
+	`http_status` integer,
+	`path` text,
+	`stack` text,
+	`user_id` text,
+	`user_agent` text,
+	`created_at` text DEFAULT (current_timestamp) NOT NULL
+);
+--> statement-breakpoint
+CREATE INDEX `app_logs_created_at_idx` ON `app_logs` (`created_at`);--> statement-breakpoint
+CREATE INDEX `app_logs_level_idx` ON `app_logs` (`level`);--> statement-breakpoint
+-- Grant the new log:read permission to the built-in admin role (enforcement is
+-- runtime-special-cased to ALL permissions, but the Roles UI lists the grid from these
+-- rows — keep it in sync). INSERT OR IGNORE: harmless if the row already exists.
+INSERT OR IGNORE INTO `role_permissions` (`role_id`, `permission`) VALUES ('admin','log:read');

packages/db/drizzle/meta/_journal.json

@@ -64,6 +64,13 @@
       "when": 1781885100000,
       "tag": "0008_user_profile_theme",
       "breakpoints": true
+    },
+    {
+      "idx": 9,
+      "version": "6",
+      "when": 1781885200000,
+      "tag": "0009_app_logs",
+      "breakpoints": true
     }
   ]
 }

packages/db/src/schema.ts

@@ -356,6 +356,39 @@ export const sessions = sqliteTable("sessions", {
   lastEventIndex: integer("last_event_index"),
 });
 
+// --- Application logs (diagnostics, UNSIGNED, prunable) ------------------
+// A THIRD stream, distinct from the signed ledger_events (business facts) and
+// device_events (hardware telemetry): operational/diagnostic logs for debugging the
+// appliance. Backend warn/error/fatal (a Pino sink) AND frontend errors land here —
+// failed requests, uncaught exceptions, rejected promises — so a booth problem is
+// queryable from one place on an offline box. Never signed, never reconciled, pruned
+// by age + row cap. See wiki/concepts/app-logs.md, event-streams-split.md.
+export const appLogs = sqliteTable("app_logs", {
+  id: text("id").primaryKey(),
+  // pino levels: trace|debug|info|warn|error|fatal. We persist warn+ from the backend.
+  level: text("level", {
+    enum: ["trace", "debug", "info", "warn", "error", "fatal"],
+  }).notNull(),
+  // Which side produced it — the booth UI or the host.
+  source: text("source", { enum: ["frontend", "backend"] }).notNull(),
+  message: text("message").notNull(),
+  // Free-form structured detail: the failed request (path/method/status/body), the
+  // error name, component, anything the caller attaches. Kept in one JSON column.
+  context: text("context", { mode: "json" }).$type<Record<string, unknown>>(),
+  // Pulled out of context for cheap filtering of the common "failed request" case.
+  httpStatus: integer("http_status"),
+  path: text("path"),
+  // Captured stack trace, when there is one (uncaught errors / rejections).
+  stack: text("stack"),
+  // Who was logged in when it happened (frontend) / acted (backend), if known.
+  userId: text("user_id"),
+  // The browser/user-agent for a frontend log (triage which booth/device).
+  userAgent: text("user_agent"),
+  createdAt: text("created_at")
+    .notNull()
+    .default(sql`(current_timestamp)`),
+});
+
 export type UserRow = typeof users.$inferSelect;
 export type RoleRow = typeof roles.$inferSelect;
 export type RolePermissionRow = typeof rolePermissions.$inferSelect;
@@ -372,3 +405,4 @@ export type SubscriptionCredentialRow = typeof subscriptionCredentials.$inferSel
 export type SubscriptionPlateRow = typeof subscriptionPlates.$inferSelect;
 export type BlocklistRow = typeof blocklist.$inferSelect;
 export type SessionRow = typeof sessions.$inferSelect;
+export type AppLogRow = typeof appLogs.$inferSelect;

packages/shared/src/index.ts

@@ -26,6 +26,7 @@ export const RESOURCES = [
   "session", // active sessions, lookup
   "event", // the signed ledger feed + void
   "report", // events feed, occupancy, future reports
+  "log", // application/diagnostic logs (app_logs) — view + retention
 ] as const;
 export type Resource = (typeof RESOURCES)[number];
 
@@ -51,6 +52,7 @@ export const PERMISSIONS: readonly Permission[] = [
   "session:read",
   "event:read", "event:void",
   "report:read",
+  "log:read",
 ] as const;
 
 /** The protected built-in role: non-deletable, non-editable, always = ALL
@@ -260,6 +262,52 @@ export function reasonPayload(
 /** Operational device telemetry — UNSIGNED, prunable. NOT the ledger. */
 export type DeviceEventKind = "input" | "relay" | "status" | "read" | "snapshot";
 
+/**
+ * Application/diagnostic logs — a THIRD unsigned, prunable stream (app_logs), distinct
+ * from the signed ledger and from device telemetry. Backend warn+ and frontend errors
+ * land here so a booth problem is queryable in one place. See
+ * wiki/concepts/app-logs.md, decisions/event-streams-split.md.
+ */
+export type LogLevel = "trace" | "debug" | "info" | "warn" | "error" | "fatal";
+export type LogSource = "frontend" | "backend";
+
+/** A persisted log record (the read shape returned by GET /api/logs). */
+export interface AppLogRecord {
+  readonly id: string;
+  readonly level: LogLevel;
+  readonly source: LogSource;
+  readonly message: string;
+  readonly context: Record<string, unknown> | null;
+  readonly httpStatus: number | null;
+  readonly path: string | null;
+  readonly stack: string | null;
+  readonly userId: string | null;
+  readonly userAgent: string | null;
+  readonly createdAt: string;
+}
+
+/** One log entry POSTed by the frontend to /api/logs (server stamps id/userId/time). */
+export interface ClientLogInput {
+  readonly level: LogLevel;
+  readonly message: string;
+  readonly context?: Record<string, unknown> | null;
+  readonly httpStatus?: number | null;
+  readonly path?: string | null;
+  readonly stack?: string | null;
+  /** Client-side capture time (ISO). The server records its own receive time too. */
+  readonly at?: string;
+}
+
+/** The numeric ordering of levels (pino-compatible), for threshold comparisons. */
+export const LOG_LEVEL_ORDER: Record<LogLevel, number> = {
+  trace: 10,
+  debug: 20,
+  info: 30,
+  warn: 40,
+  error: 50,
+  fatal: 60,
+};
+
 /**
  * The composable rate card stored in a tariff_version.structure.
  *

wiki/concepts/app-logs.md

@@ -0,0 +1,101 @@
+---
+type: concept
+tags: [parking, observability, diagnostics, logging, frontend, backend]
+sources: []
+updated: 2026-06-19
+status: open
+---
+
+# Application logs (diagnostics) — the third stream
+
+A **third data stream**, deliberately distinct from the two in [[event-streams-split]]:
+
+| Stream | Table | Signed? | Purpose |
+| --- | --- | --- | --- |
+| Business ledger | `ledger_events` | ✅ ATECC608 | money/accountability ([[append-only-event-chain]]) |
+| Device telemetry | `device_events` | ❌ | hardware chatter ([[device-events]]) |
+| **App logs** | **`app_logs`** | ❌ | **operational/diagnostic logs** (this page) |
+
+App logs answer *"why did the booth misbehave?"* — a question neither of the other streams should
+absorb (logs are neither business facts nor hardware telemetry). On an **offline appliance** there's
+no Sentry/Datadog to ship to, so the host **is** the log store: backend warnings/errors AND frontend
+errors land in one queryable table, viewable at the booth. Built 2026-06-19.
+
+## What's captured
+
+- **Backend `warn` / `error` / `fatal`** — a pino stream tees these into `app_logs` (and still writes
+  them to stdout, unchanged). `info`/`debug`/`trace` stay **stdout-only** — they'd bloat the DB. So
+  every `app.log.warn/error(...)` already in the codebase is now persisted with **no call-site
+  change**.
+- **Frontend errors** (always): every **failed API request** (`apiFetch`'s non-OK path → method,
+  path, status, server error body — except `401`, which is normal pre-login churn), every **uncaught
+  error** (`window.onerror`), every **unhandled promise rejection**, and a top-level **React
+  ErrorBoundary** (a render crash is reported as `fatal` instead of a white screen).
+- **`console.warn` / `console.error`** — only forwarded when the **client log level is `debug`/`trace`**
+  (off by default; they're noisy with third-party chatter). The high-signal sources above are always
+  on. Toggle via `VITE_LOG_LEVEL` / `setClientLogLevel()`.
+
+## Shape
+
+`app_logs`: `level` (pino names), `source` (`frontend`|`backend`), `message`, `context` (one JSON
+column — the failed request, error name, component stack, anything), plus pulled-out `httpStatus` /
+`path` for cheap filtering, `stack`, `userId`, `userAgent`, `createdAt`. Indexed on `created_at` +
+`level`. Shared types: `AppLogRecord` / `ClientLogInput` / `LogLevel` in `@parking/shared`.
+
+## The API + the access split
+
+- **`POST /api/logs`** — the frontend ships errors here. **Any signed-in user** may write (it's their
+  own browser's diagnostics) — `requireAuth`, not a permission. CSRF still applies (it's a mutation).
+  Accepts one entry or a `{ entries: [...] }` batch (capped at 50). **Deliberately never 4xx's on a
+  malformed entry** — a client erroring *while reporting an error* must not get a second error.
+- **`GET /api/logs`** — read the store (level/source/since filters), gated by the **new `log:read`
+  permission** (a new `log` resource in the dynamic [[local-jwt-auth|RBAC]] grid). Admin holds it;
+  it's grantable to a diagnostic role. *Verified: a cashier without `log:read` gets 403 on GET but
+  204 on POST — the intended asymmetry.*
+
+## Reliability invariants (a logger must never make things worse)
+
+- **No infinite loop.** The frontend collector never logs the `/api/logs` request itself, and flushes
+  via **raw `fetch`/`sendBeacon`**, not `apiFetch` (so a flush failure can't recurse into a new log).
+  The backend `LogService` has a **reentrancy guard** — persisting a log can't emit a persisted log.
+- **Best-effort, never fatal.** Every write is wrapped; a DB/logging failure is swallowed (it can't be
+  logged — that's the recursion we guard). Diagnostics must never break the path they observe.
+- **Bounded.** Frontend queue capped (drops oldest); message/stack/context clamped per row;
+  ingest batch capped.
+
+## Retention (offline appliance ⇒ must be bounded)
+
+Pruned by **age AND a row cap** (a burst could blow past an age-only window): delete older than
+`LOG_RETENTION_DAYS` (default 30) **and** keep only the newest `LOG_RETENTION_MAX_ROWS` (default
+50 000). Runs **hourly** (unref'd timer) + once at startup. Both env-configurable. Same "prunable,
+not precious" durability class as `device_events` — the opposite of the append-only ledger.
+
+## The booth viewer
+
+A **Logs screen** under Setup (`/setup/logs`, gated by `log:read`, sq+en) — filter by
+level/source/since, newest first, each row expands to the structured `context` + stack. Read-only
+(logs are evidence, never edited). Polls every 15 s (no WS — diagnostics aren't latency-critical).
+Sits alongside the other admin tabs in [[booth-console]].
+
+## As-built (2026-06-19)
+
+- `packages/db`: `app_logs` table + migration `0009_app_logs.sql` (+ journal idx 9; seeds admin
+  `log:read`). Applied to the live `apps/server/parking.sqlite`.
+- `@parking/shared`: `log` resource + `log:read` permission; `LogLevel`/`LogSource`/`AppLogRecord`/
+  `ClientLogInput`/`LOG_LEVEL_ORDER`.
+- `apps/server`: `log-service.ts` (`LogService` + `pinoDbStream`), `routes/logs.ts`, wired in
+  `server.ts` (DB built before Fastify so the pino stream has the sink; prune timer).
+- `apps/web`: `lib/logger.ts` (collector + global handlers), `lib/ErrorBoundary.tsx`, `apiFetch` hook,
+  `LogsViewer.tsx` + route/nav, i18n.
+
+## Open
+
+- **No automated test** (the standing harness gap) — though the ingest/read/gate path was verified by
+  in-process `app.inject` smoke (login → POST 204 → GET 200 with the record; non-admin 403/204 split).
+- **Server API error strings stay English** — unchanged here; this is about *persisting* logs, not
+  localizing them. The localized-ledger-reason pattern ([[i18n]]) is the template if log *display*
+  ever needs translation (currently the message is whatever the thrower wrote).
+- **Surfacing critical logs live** — a `fatal`/`error` count badge on the booth footer over the
+  existing `/api/ws` could flag problems without opening the viewer. Deferred.
+- **Correlation id** — no request-id threads a frontend failed-request log to its backend log yet;
+  add a `x-request-id` echo if cross-stream correlation is wanted.

wiki/concepts/device-events.md

@@ -31,6 +31,11 @@ diagnostics, and live booth status — **not** anti-fraud.
 - **Device-keyed** — references the `devices` instance (raw device provenance). No `lane`
   (pool-of-spaces model — see [[entry-exit-points]]).
 
+> **Not to be confused with [[app-logs]].** `device_events` is **hardware telemetry** (a relay fired,
+> a camera failed). Diagnostic/application logs (a failed API request, an uncaught frontend error,
+> a backend warning) are a **separate third stream** in `app_logs` — don't route app errors here, nor
+> hardware telemetry there. Both are unsigned + prunable; the distinction is *what produced it*.
+
 ## The boundary that matters
 
 A device event is *evidence the host saw something happen*; it does **not** by itself authorize or

wiki/decisions/event-streams-split.md

@@ -50,8 +50,16 @@ A raw button press is **telemetry** → `device_events`. The entry flow then min
   input-push handler to emit `device_events` (+ the entry flow signs `vehicle_entry`).
 - `ParkingEventType` in `packages/shared` splits into ledger types vs. a device-event type set.
 
+## A third stream followed (2026-06-19)
+
+The same separation logic produced a **third** stream: **`app_logs`** — operational/diagnostic logs
+(backend warn+ via a pino sink, plus frontend errors). They're neither business facts (ledger) nor
+hardware telemetry (device_events), so they get their own unsigned, prunable table. See
+[[app-logs]]. The principle generalizes: *one stream per durability/meaning class*.
+
 ## Open
 
-- `device_events` retention/rotation policy.
+- `device_events` retention/rotation policy. (Resolved for `app_logs`: age + row cap — see
+  [[app-logs]]; the same policy is a candidate for `device_events`.)
 - Which device facts (if any) are witness-grade enough to *also* warrant a signed ledger entry
   (e.g. `barrier_open_observed` from a loop sensor) — see [[append-only-event-chain]] witness gap.

wiki/index.md

@@ -7,7 +7,7 @@ updated: 2026-06-19
 # Index
 
 Content catalog for the wiki. Start at [[overview]]. Maintained on every ingest.
-Counts: 4 sources · 19 entities · 42 concepts · 5 decision records.
+Counts: 4 sources · 19 entities · 44 concepts · 5 decision records.
 
 ## Overview & navigation
 - [[overview]] — the top-level synthesis and entry point.
@@ -93,6 +93,7 @@ Counts: 4 sources · 19 entities · 42 concepts · 5 decision records.
 - [[ticket-encoding]] — transient ticket id (11-digit numeric + Luhn) as Code128; printed at entry, scanned at pay station + exit; barcode geometry must fit paper width (KP-300H overflow); plate-as-ticket alt.
 - [[anti-passback]] — block/flag one id entering twice without an exit; fold over open sessions.
 - [[device-events]] — unsigned hardware telemetry (relay/printer/camera/reader/input); separate from the signed ledger.
+- [[app-logs]] — the third stream: diagnostic logs (backend warn+ pino sink + frontend errors) → app_logs; log:read viewer; pruned by age+row cap.
 - [[subscription]] — recurring plan (e.g. 10,000 ALL/month); RF/QR or plate identity, car-count + max-concurrent, host-in-loop; short-circuits payment. (Renamed from "permit"; time-of-day windows noted, deferred.)
 - [[opencv-anpr-service]] — host-side vision microservice: ANPR (plate identity) + vehicle verification (anti-plate-spoofing witness).
 - [[blocklist]] — barred plates/cards refused at entry (never at exit); signed, attributed.

wiki/log.md

@@ -892,3 +892,15 @@ Dates were raw ISO on paper and time-only in the UI (a 2-day-old session showed
 ## [2026-06-19] fix | KP-300H barcode line-overflow — ticket id 13→11 digits
 
 The Cashino KP-300H entry dispenser printed entry tickets as RASTER GARBAGE (solid black bars/banding) while the Rongta printed the IDENTICAL byte stream fine. Diagnosed on hardware: plain-text-only prints were clean → isolated to the `GS k` Code128 barcode. ROOT CAUSE = barcode line-overflow, not corruption: a Code128-B symbol is (11·chars+35)·moduleWidth dots; the old 13-digit id at module width 3 = ~534 dots OVERRAN the KP-300H's 72mm line (512 usable dots @ 203 dpi). The Rongta runs 80mm (576 dots) and had just enough room — why only the Cashino failed. FIX: shorten the ticket id 13→11 digits (10 random + Luhn) → ~468 dots, fits 72mm; scanned the full value at the exit reader (verified). Length is driven by GUESS-RESISTANCE not volume (10^10 space, ~1-in-10^7 to hit a live open ticket vs the booth-operator threat); chose 11 over the requested 9 (10^8 → ~1-in-10^5, too weak). validateTicketCode made length-agnostic (\d{10,14}+Luhn) so legacy 13-digit tickets still validate. NB: module width must stay 3 — a width-2 test scanned but returned TRUNCATED values (partial reads logged as exit.refused.noSession anomalies). Also fixed a separate latent transport bug in sendRaw: write-then-destroy could RST mid-stream (the write callback ≠ peer-flushed) and truncate a job; now end(payload)+FIN, resolve on socket `close`, timeout-after-write = success. NOT the cause of the garbage but a real risk. Committed bbf61c4. Updated [[ticket-encoding]], [[rongta-printer]].
+
+## [2026-06-19] feat | Snapshots on refused entry/exit + subscriber access medium in the activity log
+
+Two booth-evidence gaps closed. (1) **Refused entry/exit now snapshot.** Originally only the OPEN paths fired the directional camera; refusal/hold anomalies didn't — yet a turned-away car is exactly the evidence an operator/auditor wants (fraud/dispute signal). Added `#fireSnapshot` to every refusal: entry refused-full + held-no-ticket (a refused entry has no ticket id, so mint a synthetic `REFUSED-…` ref to key the anomaly + photo together), exit refused closed/no-session/unpaid/grace-expired (BOTH booth `exitForBooth` and reader `#runExit` paths), and refused [[subscription]] (the lane the reader sits at — `resolved.direction`, "both"→entry — picks the camera). Same fire-and-forget contract: a refusal is never delayed/blocked by a camera; failed captures still surface as "⚠ camera unreachable" tiles. (2) **Subscriber access medium (`via`) surfaced.** The subscription flow already SIGNED `via` (`"qr"|"card"|"plate"`) into the entry/exit payload but the activity log never showed it. Added it as a typed `LedgerPayload.via` field, a cyan chip in the ticker, and an "Entry medium / Mënyra e hyrjes" row in the detail modal (QR code / RFID card·chip / plate, localized sq+en) — a lost-card investigation can now see which credential opened a barrier. Display-only, no re-signing. Refused-subscription anomalies also now carry `via`. Build+lint green. Updated [[entry-exit-points]], [[booth-console]].
+
+## [2026-06-19] feat | One car = one ticket (entry anti-double-press) + refusal snapshots + subscriber via
+
+FLAW found: the entry button could be pressed without limit — each press minted a fresh ticket + signed vehicle_entry, corrupting occupancy (one car counts as many) and letting a transient SHOP the cheapest ticket at exit. The old `#inFlight` guard only blocked OVERLAPPING presses (released in finally). FIX is per-relay config (`config.relays[]`), mode chosen by available barrier feedback: (1) PRESENCE (preferred) — `presenceInput` ties ticketing to a vehicle loop on a Dingtian input; a press prints only with a car present, and NO second ticket until the loop CLEARS (car drove in) and a new car re-occupies it → physical one-car-one-ticket; (2) COOLDOWN (fallback, no feedback) — `entryCooldownSec` suppresses repeat presses for N seconds (a timer, mitigation not guarantee). New `relayForPresence()` resolves a loop edge to its entry relay; `EntryFlow` keeps a per-relay `#guard` map (present/armed), disarms on PRINT success, re-arms on loop clear. A suppressed press = UNSIGNED device_events telemetry (entrySuppressed:true), NOT a signed anomaly (operator's call — it's a correct no-op, not fraud). SetupWizard relay editor exposes Presence-loop + Cooldown fields (sq+en). Fail-closed entry + barrier-is-not-a-door invariants untouched; guard state is in-memory/rebuildable, starts armed after restart (safe default). New page [[entry-double-press]]; updated [[entry-exit-points]], index. Build+lint green. (Bundled with this session's earlier refusal-snapshots + subscriber-`via` work.)
+
+## [2026-06-19] feat | Application logs — backend pino DB sink + frontend error collection (app_logs)
+
+Added a THIRD data stream (`app_logs`) alongside the signed ledger and device telemetry — operational/diagnostic logs, since an OFFLINE appliance has no Sentry to ship to. BACKEND: a pino stream tees warn/error/fatal into app_logs (info/debug stay stdout-only — no bloat) with NO call-site change; the DB is now built BEFORE Fastify so the logger stream has its sink. FRONTEND (lib/logger.ts): always ships failed API requests (apiFetch non-OK path, minus 401 pre-login churn), window.onerror, unhandledrejection, and a top-level React ErrorBoundary (render crash → fatal, not a white screen); console.warn/error forwarded ONLY at client debug/trace level (noisy otherwise). Batched/throttled POST, flush via raw fetch + sendBeacon on pagehide. Reliability invariants: never log the /api/logs call itself (loop guard), LogService reentrancy guard, all writes best-effort/swallowed, bounded queue + clamped rows. API: POST /api/logs (any signed-in user, CSRF, tolerant — never 4xx on a bad entry) + GET /api/logs gated by a NEW `log:read` permission (new `log` resource in the RBAC grid; admin holds it). Retention: pruned by age (LOG_RETENTION_DAYS=30) AND row cap (MAX_ROWS=50k), hourly + at startup. UI: a Logs screen under /setup (filter level/source/since, expand to context+stack, 15s poll), sq+en. DB migration 0009_app_logs (+journal idx 9, seeds admin log:read) applied to the live apps/server DB. Verified end-to-end via app.inject: login→POST 204→GET 200 with the record; backend warn/error persisted + info dropped; non-admin GET 403 / POST 204 (the intended split). Build+lint green. New page [[app-logs]]; updated [[event-streams-split]], [[device-events]], index.