akanjs 3.0.0-alpha.70 → 3.0.0-alpha.72

package/client/cookie.ts

@@ -1,7 +1,7 @@
 import { getEnv } from "akanjs/base";
 import { decodeJwtPayload, Logger } from "akanjs/common";
 import type { Account } from "akanjs/fetch";
-import { cookies as serverCookies, headers as serverHeaders } from "akanjs/fetch";
+import { parseCookieHeader, cookies as serverCookies, headers as serverHeaders } from "akanjs/fetch";
 import { loadCapacitorCore } from "./capacitor";
 import { storage } from "./storage";
 import { fetch } from "./useClient";
@@ -12,23 +12,6 @@ interface CookieOptions {
   secure?: boolean;
 }
 
-function parseCookieHeader(cookieHeader: string): Map<string, { name: string; value: string }> {
-  const entries = cookieHeader
-    .split(";")
-    .map((c) => c.trim())
-    .filter(Boolean)
-    .map((c) => {
-      const eqIdx = c.indexOf("=");
-      if (eqIdx === -1) return null;
-      const name = c.slice(0, eqIdx).trim();
-      const raw = c.slice(eqIdx + 1).trim();
-      const value = typeof raw === "string" && raw.startsWith("j:") ? (JSON.parse(raw.slice(2)) as string) : raw;
-      return [name, { name, value }] as const;
-    })
-    .filter((e): e is NonNullable<typeof e> => e !== null);
-  return new Map(entries);
-}
-
 export const cookies = (): Map<string, { name: string; value: string }> => {
   if (getEnv().side === "server") return serverCookies();
   return parseCookieHeader(document.cookie);
@@ -53,21 +36,18 @@ export const setCookie = (
     .catch(() => undefined);
 };
 
-export const getCookie = (key: string): string | undefined => {
-  if (getEnv().side === "server") return cookies().get(key)?.value;
-  else
-    return document.cookie
-      .split(";")
-      .find((c) => c.trim().startsWith(`${key}=`))
-      ?.split("=")[1];
-};
+/**
+ * Reads through `cookies()` on both sides, which is the only way the two agree: a hand-rolled
+ * `split("=")[1]` truncates a value at its first `=` (base64 padding) and never decodes the `j:` form the
+ * server branch does. Capacitor's own docs say to read `document.cookie`, and `cookies()` does.
+ */
+export const getCookie = (key: string): string | undefined => cookies().get(key)?.value;
 
 export const removeCookie = (key: string, options: { path: string } = { path: "/" }) => {
-  if (getEnv().side === "server") return cookies().delete(key);
-  else {
-    
-    document.cookie = `${key}=; expires=Thu, 01 Jan 1970 00:00:00 UTC; path=/;`;
-  }
+
+  if (getEnv().side === "server") return;
+  
+  document.cookie = `${key}=; expires=Thu, 01 Jan 1970 00:00:00 UTC; path=${options.path};`;
 };
 export const headers = (): Map<string, string> => {
   if (getEnv().side !== "server") return new Map();
@@ -77,9 +57,15 @@ export const headers = (): Map<string, string> => {
 export const getHeader = (key: string): string | undefined => {
   return headers().get(key);
 };
-/** Decodes the current JWT into account data when it belongs to this app/environment. */
+/**
+ * Decodes the current JWT into account data when it belongs to this app/environment.
+ *
+ * The two credentials read here are exactly the two the server honours — the `jwt` cookie and
+ * `Authorization: Bearer` (`AccountMiddleware`). It used to fall back to a bare `jwt` *header*, which nothing
+ * sends and no guard accepts, so a request carrying one read as signed in here and anonymous at the endpoint.
+ */
 export const getAccount = <AddData = unknown>(): Account<AddData> => {
-  const jwt = getCookie("jwt") ?? getHeader("jwt");
+  const jwt = getCookie("jwt") ?? getHeader("authorization")?.replace(/^Bearer\s+/i, "");
   const defaultAccount = { appName: getEnv().appName, environment: getEnv().environment } as Account<AddData>;
   if (!jwt) return defaultAccount;
   const account = decodeJwtPayload<Account<AddData>>(jwt);
@@ -105,7 +91,8 @@ interface InitAuthOption {
 export const initAuth = ({ jwt }: InitAuthOption = {}) => {
   const token = jwt ?? cookies().get("jwt")?.value;
   if (token) setAuth({ jwt: token });
-  Logger.verbose(`JWT set from cookie: ${token}`);
+  
+  Logger.verbose(`JWT ${token ? "restored from cookie" : "not found in cookie"}`);
 };
 
 export const resetAuth = () => {

package/client/csrTypes.ts

@@ -262,18 +262,6 @@ export type PageState = CsrState & {
   topInset: number;
   bottomInset: number;
 };
-export const defaultPageState: PageState = {
-  transition: "none",
-  topSafeArea: 0,
-  bottomSafeArea: 0,
-  topInset: 0,
-  bottomInset: 0,
-  gesture: true,
-  cache: false,
-  ssr: "stream",
-  topSafeAreaColor: "var(--color-background, Canvas)",
-  bottomSafeAreaColor: "var(--color-background, Canvas)",
-};
 
 export interface Location {
   href: string;

package/client/frameConfig.ts

@@ -120,6 +120,19 @@ export function getExplicitPageConfigKeys(configChain: PageConfig[] = []): Parti
   return explicitKeys;
 }
 
+export const defaultPageState: PageState = {
+  transition: "none",
+  topSafeArea: 0,
+  bottomSafeArea: 0,
+  topInset: 0,
+  bottomInset: 0,
+  gesture: true,
+  cache: false,
+  ssr: "stream",
+  topSafeAreaColor: "var(--color-background, Canvas)",
+  bottomSafeAreaColor: "var(--color-background, Canvas)",
+};
+
 export function resolvePageState({
   configChain = [],
   path,

package/client/router.ts

@@ -167,11 +167,11 @@ class Router {
   #instance: InternalRouterInstance = {
     push: (href: string) => {
       const { href: fullHref } = this.#getPathInfo(href);
-      Logger.log(`push to:${fullHref}`);
+      Logger.info(`push to:${fullHref}`);
     },
     replace: (href: string) => {
       const { pathname } = this.#getPathInfo(href);
-      Logger.log(`replace to:${pathname}`);
+      Logger.info(`replace to:${pathname}`);
     },
     back: () => {
       throw new Error("back is only available in client");
@@ -191,7 +191,7 @@ class Router {
     );
     this.#indexPath = splitHref(options.indexPath ?? "/").path;
     if (this.#routePaths.size > 0 && !this.#routePaths.has(this.#indexPath)) {
-      Logger.log(`[router] indexPath '${this.#indexPath}' was not found in route manifest. Falling back to '/'.`);
+      Logger.info(`[router] indexPath '${this.#indexPath}' was not found in route manifest. Falling back to '/'.`);
       this.#indexPath = "/";
     }
     this.#ensureHistoryState();
@@ -318,7 +318,7 @@ class Router {
     return getPathInfo(href, lang, shouldExposeBasePath() ? this.#prefix : "");
   }
   #postPathChange({ path, pathname, hash }: { path: string; pathname: string; hash: string }) {
-    Logger.log(`pathChange-start:${path}${hash ? `#${hash}` : ""}`);
+    Logger.info(`pathChange-start:${path}${hash ? `#${hash}` : ""}`);
     window.parent.postMessage({ type: "pathChange", path, pathname, hash }, "*");
   }
   #postDevSyncNavigation(kind: "push" | "replace", href: string) {
@@ -338,7 +338,7 @@ class Router {
     const normalizedHref = normalizeDeepLinkHref(href);
     const { path, search, hash } = splitHref(normalizedHref);
     if (this.#routePaths.size > 0 && !this.#routePaths.has(path)) {
-      Logger.log(`[router] deep link target '${path}' was not found in route manifest.`);
+      Logger.info(`[router] deep link target '${path}' was not found in route manifest.`);
       return [];
     }
     const stack = this.#routePaths.size > 0 ? this.#getExistingSegmentStack(path) : [path];
@@ -416,7 +416,7 @@ class Router {
       const lang = (h.get("x-locale") ?? langFromPath ?? this.#lang) as string;
       const basePath = getServerBasePath(reqPathname, lang, h.get("x-base-path") ?? undefined, this.#prefix);
       const { pathname, href: fullHref } = getPathInfo(href, lang, shouldExposeBasePath() ? basePath : "");
-      Logger.log(`redirect to:${pathname}`);
+      Logger.info(`redirect to:${pathname}`);
       throw new AkanRedirectError(fullHref, method, status);
     } else {
       this.#instance[method](href);
@@ -425,7 +425,7 @@ class Router {
   }
   notFound(): never {
     if (getEnv().side === "server") {
-      Logger.log(`redirect to:/404`);
+      Logger.info(`redirect to:/404`);
       throw new AkanNotFoundError();
     }
     this.#checkInitialized();

package/common/Logger.ts

@@ -1,17 +1,64 @@
 import dayjs from "dayjs";
+import { type LogContextSnapshot, readLogContext } from "./logContext";
 
-const logLevels = ["trace", "verbose", "debug", "log", "info", "warn", "error"] as const;
+export const logLevels = ["trace", "verbose", "debug", "info", "warn", "error"] as const;
 export type LogLevel = (typeof logLevels)[number];
+export type LogLevelInput = LogLevel | "log";
+
+export const logSeverity = { trace: 1, verbose: 3, debug: 5, info: 9, warn: 13, error: 17 } as const satisfies {
+  [key in LogLevel]: number;
+};
+
+/** `text` is the human console line; the `ndjson` pair make the container's stdout one JSON record per line. */
+export const logFormats = ["text", "ndjson", "ndjson-only"] as const;
+export type LogFormat = (typeof logFormats)[number];
+
+export type LogAttrValue = string | number | boolean | null;
+export interface LogAttrs {
+  [key: string]: LogAttrValue;
+}
+
+export interface LogRecord {
+  at: number;
+  /** Milliseconds since the producing process started — what the `+Nms` in the rendered line shows. */
+  elapsedMs: number;
+  level: LogLevel | null;
+  sev: number;
+  name: string;
+  context: string;
+  message: string;
+  stream: "stdout" | "stderr";
+  pid: number | null;
+  replicaIdx: number | null;
+  role: string | null;
+  origin: string | null;
+  traceId: string | null;
+  endpoint: string | null;
+  attrs?: LogAttrs;
+}
 
 export interface LoggerSinkEntry {
   stream: "stdout" | "stderr";
   level?: LogLevel;
   message: string;
   plainMessage: string;
+  record: LogRecord;
 }
 
 export type LoggerSink = (entry: LoggerSinkEntry) => void | Promise<void>;
 
+export interface LoggerSinkOptions {
+  minLevel?: LogLevelInput;
+}
+
+export interface LoggerEmitInput {
+  level: LogLevel;
+  name: string;
+  message: string;
+  context?: string;
+  attrs?: LogAttrs;
+}
+
 const clc = {
   bold: (text: string) => `\x1B[1m${text}\x1B[0m`,
   green: (text: string) => `\x1B[32m${text}\x1B[39m`,
@@ -25,7 +72,6 @@ const colorizeMap: { [key in LogLevel]: (text: string) => string } = {
   trace: clc.bold,
   verbose: clc.cyanBright,
   debug: clc.magentaBright,
-  log: clc.green,
   info: clc.green,
   warn: clc.yellow,
   error: clc.red,
@@ -33,36 +79,129 @@ const colorizeMap: { [key in LogLevel]: (text: string) => string } = {
 
 const ansiPattern = new RegExp(`${String.fromCharCode(27)}\\[[0-?]*[ -/]*[@-~]`, "g");
 
+const redactedAttrKey = /password|passwd|token|jwt|authorization|cookie|secret|api[-_]?key|private[-_]?key/i;
+
+/**
+ * `process.env?.X` guards only `env` being absent, never `process` itself — an undeclared `process` is a
+ * ReferenceError, and at module scope that takes the whole client bundle with it. This is the most widely
+ * imported file in `common/`, and the unguarded form works today only because the browser build ships a shim.
+ */
+const envValue = (key: string): string | undefined => (typeof process === "undefined" ? undefined : process.env?.[key]);
+
 /** Log-level aware logger used by Akan runtime, CLI, and application services. */
 export class Logger {
-  static level: LogLevel = (process.env?.AKAN_PUBLIC_LOG_LEVEL as LogLevel | undefined) ?? "log";
-  static #levelIdx = logLevels.findIndex((l) => l === (process.env?.AKAN_PUBLIC_LOG_LEVEL ?? "log"));
-  static fileLevel: LogLevel = (process.env?.AKAN_LOG_FILE_LEVEL as LogLevel | undefined) ?? "trace";
-  static #fileLevelIdx = logLevels.findIndex((l) => l === (process.env?.AKAN_LOG_FILE_LEVEL ?? "trace"));
-  static #startAt = dayjs();
-  static #sinks = new Set<LoggerSink>();
-
-  static setLevel(level: LogLevel) {
-    Logger.level = level;
-    Logger.#levelIdx = logLevels.indexOf(level);
-  }
-  static addSink(sink: LoggerSink) {
-    Logger.#sinks.add(sink);
+  /** `AKAN_LOG_STDOUT_LEVEL` names what the container's stdout carries; without it the console level is that. */
+  static level: LogLevel = Logger.#levelFromEnv(
+    envValue("AKAN_LOG_STDOUT_LEVEL"),
+    Logger.#levelFromEnv(envValue("AKAN_PUBLIC_LOG_LEVEL"), "info"),
+  );
+  static fileLevel: LogLevel = Logger.#levelFromEnv(envValue("AKAN_LOG_FILE_LEVEL"), "trace");
+  static format: LogFormat = Logger.#formatFromEnv(envValue("AKAN_LOG_FORMAT"));
+  /** Which process this is (`gateway`, `all`, `batch`, `rsc-worker`); the owner sets it at boot. */
+  static role: string | null = envValue("SERVER_MODE") ?? null;
+  /**
+   * Whether this process writes its own lines to the terminal. Off in every server process of an ndjson
+   * deployment: the hub owner writes the one JSON stream, and a text line from anyone would corrupt it.
+   */
+  static consoleOutput = true;
+  /** Set by the trace layer when a flight recorder or a per-request debug floor can be active. */
+  static contextGate = false;
+  static readonly startAt = Date.now();
+  static #consoleSev: number = logSeverity[Logger.level];
+  static #fileSev: number = logSeverity[Logger.fileLevel];
+  static #sinkFloorSev = Number.POSITIVE_INFINITY;
+  static #sinks = new Map<LoggerSink, number | null>();
+
+  static setLevel(level: LogLevelInput) {
+    Logger.level = Logger.normalizeLevel(level);
+    Logger.#consoleSev = logSeverity[Logger.level];
+  }
+  static setFileLevel(level: LogLevelInput) {
+    Logger.fileLevel = Logger.normalizeLevel(level);
+    Logger.#fileSev = logSeverity[Logger.fileLevel];
+    Logger.#refreshSinkFloor();
+  }
+  static addSink(sink: LoggerSink, { minLevel }: LoggerSinkOptions = {}) {
+    Logger.#sinks.set(sink, minLevel === undefined ? null : logSeverity[Logger.normalizeLevel(minLevel)]);
+    Logger.#refreshSinkFloor();
     return () => Logger.removeSink(sink);
   }
   static removeSink(sink: LoggerSink) {
     Logger.#sinks.delete(sink);
-  }
-  static setFileLevel(level: LogLevel) {
-    Logger.fileLevel = level;
-    Logger.#fileLevelIdx = logLevels.indexOf(level);
+    Logger.#refreshSinkFloor();
   }
   static isVerbose() {
-    return Logger.#levelIdx <= 1;
+    return Logger.#consoleSev <= logSeverity.verbose;
+  }
+  static get isNdjson() {
+    return Logger.format !== "text";
   }
   /** For hot-path callers that would otherwise build a message the level is about to discard. */
-  static shouldLog(logLevel: LogLevel) {
-    return Logger.#shouldLog(logLevel);
+  static shouldLog(logLevel: LogLevelInput) {
+    return Logger.#shouldLog(Logger.normalizeLevel(logLevel));
+  }
+  static normalizeLevel(level: LogLevelInput): LogLevel {
+    return level === "log" ? "info" : level;
+  }
+  /** The lowest named level whose severity is at least `sev`. */
+  static levelAtOrAbove(sev: number): LogLevel {
+    return logLevels.find((level) => logSeverity[level] >= sev) ?? "error";
+  }
+  static render(record: LogRecord): string {
+    const level = record.level;
+    if (level === null) return record.message;
+    const replicaMsg = record.replicaIdx === null ? "" : `#${record.replicaIdx} `;
+    const processMsg = Logger.#colorize(`[${record.name}] ${replicaMsg}${record.pid ?? "window"} -`, level);
+    const timestampMsg = dayjs(record.at).format("MM/DD/YYYY, HH:mm:ss A");
+    const logLevelMsg = Logger.#colorize(level.toUpperCase().padStart(7, " "), level);
+    const contextMsg = record.context ? clc.yellow(`[${record.context}] `) : "";
+    const contentMsg = Logger.#colorize(record.message, level);
+    const attrsMsg = record.attrs ? Logger.formatAttrs(record.attrs) : "";
+    const timeDiffMsg = clc.yellow(`+${record.elapsedMs}ms`);
+    return `${processMsg} ${timestampMsg} ${logLevelMsg} ${contextMsg} ${contentMsg}${attrsMsg ? ` ${attrsMsg}` : ""} ${timeDiffMsg}\n`;
+  }
+  /** `key=value` pairs; a string with whitespace is quoted so the line stays splittable. */
+  static formatAttrs(attrs: LogAttrs): string {
+    return Object.entries(attrs)
+      .map(
+        ([key, value]) =>
+          `${key}=${typeof value === "string" && /\s/.test(value) ? JSON.stringify(value) : String(value)}`,
+      )
+      .join(" ");
+  }
+  /**
+   * A record somebody asked for below the level — a failed call's flight recorder, a request carrying
+   * `x-akan-debug` — passes every floor between here and the reader; the floors exist to drop what nobody asked for.
+   */
+  static isPromoted(record: LogRecord) {
+    return record.attrs?.flight === true || record.attrs?.debug === true;
+  }
+  static redactAttrs(attrs: LogAttrs): LogAttrs {
+    let redacted: LogAttrs | null = null;
+    for (const key of Object.keys(attrs)) {
+      if (!redactedAttrKey.test(key)) continue;
+      redacted ??= { ...attrs };
+      redacted[key] = "[redacted]";
+    }
+    return redacted ?? attrs;
+  }
+  /** A structured record from a caller that has more than a sentence to say — the canonical request line. */
+  static emit({ level, name, message, context = "", attrs }: LoggerEmitInput) {
+    if (Logger.#shouldLog(level)) Logger.#write(name, message, context, level, attrs);
+  }
+  /**
+   * Writes records that were captured below the gate and are now promoted — a failed request's flight
+   * recorder. They bypass the console level, since not showing them is what the recorder was for, and reach
+   * sinks under their own floors; each is marked `flight` so a reader knows why a trace line appears at info.
+   */
+  static replay(records: LogRecord[], { evicted = 0 }: { evicted?: number } = {}) {
+    records.forEach((record, idx) => {
+      const attrs: LogAttrs = { ...record.attrs, flight: true };
+      if (idx === 0 && evicted > 0) attrs.flightEvicted = evicted;
+      const entry = Logger.#entry({ ...record, attrs });
+      Logger.#emit(entry);
+      Logger.#writeConsole(entry);
+    });
   }
 
   name?: string;
@@ -70,25 +209,26 @@ export class Logger {
     this.name = name;
   }
   trace(msg: string, context = "", name = this.name ?? "App") {
-    if (Logger.#shouldLog("trace")) Logger.#printMessages(name, msg, context, "trace");
+    if (Logger.#shouldLog("trace")) Logger.#write(name, msg, context, "trace");
   }
   verbose(msg: string, context = "", name = this.name ?? "App") {
-    if (Logger.#shouldLog("verbose")) Logger.#printMessages(name, msg, context, "verbose");
+    if (Logger.#shouldLog("verbose")) Logger.#write(name, msg, context, "verbose");
   }
   debug(msg: string, context = "", name = this.name ?? "App") {
-    if (Logger.#shouldLog("debug")) Logger.#printMessages(name, msg, context, "debug");
+    if (Logger.#shouldLog("debug")) Logger.#write(name, msg, context, "debug");
   }
+  /** @deprecated Emits at `info`; call `info()`. */
   log(msg: string, context = "", name = this.name ?? "App") {
-    if (Logger.#shouldLog("log")) Logger.#printMessages(name, msg, context, "log");
+    if (Logger.#shouldLog("info")) Logger.#write(name, msg, context, "info");
   }
   info(msg: string, context = "", name = this.name ?? "App") {
-    if (Logger.#shouldLog("info")) Logger.#printMessages(name, msg, context, "info");
+    if (Logger.#shouldLog("info")) Logger.#write(name, msg, context, "info");
   }
   warn(msg: string, context = "", name = this.name ?? "App") {
-    if (Logger.#shouldLog("warn")) Logger.#printMessages(name, msg, context, "warn");
+    if (Logger.#shouldLog("warn")) Logger.#write(name, msg, context, "warn");
   }
   error(msg: string, context = "", name = this.name ?? "App") {
-    if (Logger.#shouldLog("error")) Logger.#printMessages(name, msg, context, "error");
+    if (Logger.#shouldLog("error")) Logger.#write(name, msg, context, "error");
   }
   raw(msg: string, method?: "console" | "process") {
     Logger.rawLog(msg, method);
@@ -96,86 +236,166 @@ export class Logger {
   rawLog(msg: string, method?: "console" | "process") {
     Logger.rawLog(msg, method);
   }
-  
   static trace(msg: string, context = "", name = "App") {
-    if (Logger.#shouldLog("trace")) Logger.#printMessages(name, msg, context, "trace");
+    if (Logger.#shouldLog("trace")) Logger.#write(name, msg, context, "trace");
   }
   static verbose(msg: string, context = "", name = "App") {
-    if (Logger.#shouldLog("verbose")) Logger.#printMessages(name, msg, context, "verbose");
+    if (Logger.#shouldLog("verbose")) Logger.#write(name, msg, context, "verbose");
   }
   static debug(msg: string, context = "", name = "App") {
-    if (Logger.#shouldLog("debug")) Logger.#printMessages(name, msg, context, "debug");
+    if (Logger.#shouldLog("debug")) Logger.#write(name, msg, context, "debug");
   }
+  /** @deprecated Emits at `info`; call `info()`. */
   static log(msg: string, context = "", name = "App") {
-    if (Logger.#shouldLog("log")) Logger.#printMessages(name, msg, context, "log");
+    if (Logger.#shouldLog("info")) Logger.#write(name, msg, context, "info");
   }
   static info(msg: string, context = "", name = "App") {
-    if (Logger.#shouldLog("info")) Logger.#printMessages(name, msg, context, "info");
+    if (Logger.#shouldLog("info")) Logger.#write(name, msg, context, "info");
   }
   static warn(msg: string, context = "", name = "App") {
-    if (Logger.#shouldLog("warn")) Logger.#printMessages(name, msg, context, "warn");
+    if (Logger.#shouldLog("warn")) Logger.#write(name, msg, context, "warn");
   }
   static error(msg: string, context = "", name = "App") {
-    if (Logger.#shouldLog("error")) Logger.#printMessages(name, msg, context, "error");
+    if (Logger.#shouldLog("error")) Logger.#write(name, msg, context, "error");
+  }
+  static #levelFromEnv(value: string | undefined, fallback: LogLevel): LogLevel {
+    if (value === "log") return "info";
+    return (logLevels as readonly string[]).includes(value ?? "") ? (value as LogLevel) : fallback;
+  }
+  static #formatFromEnv(value: string | undefined): LogFormat {
+    return (logFormats as readonly string[]).includes(value ?? "") ? (value as LogFormat) : "text";
+  }
+  static #refreshSinkFloor() {
+    let floor = Number.POSITIVE_INFINITY;
+    for (const minSev of Logger.#sinks.values()) floor = Math.min(floor, minSev ?? Logger.#fileSev);
+    Logger.#sinkFloorSev = floor;
   }
   static #colorize(msg: string, logLevel: LogLevel) {
     return colorizeMap[logLevel](msg);
   }
-  static #stripAnsi(msg: string) {
+  static stripAnsi(msg: string) {
     return msg.replace(ansiPattern, "");
   }
   static #shouldLog(logLevel: LogLevel) {
-    return Logger.#shouldWriteConsole(logLevel) || Logger.#shouldEmitSink(logLevel);
+    if (Logger.#shouldWriteConsole(logLevel) || Logger.#shouldEmitSink(logLevel)) return true;
+    return Logger.contextGate && Logger.#contextFloor(readLogContext()) <= logSeverity[logLevel];
   }
   static #shouldWriteConsole(logLevel: LogLevel) {
-    return Logger.#levelIdx <= logLevels.indexOf(logLevel);
+    return Logger.consoleOutput && logSeverity[logLevel] >= Logger.#consoleSev;
   }
   static #shouldEmitSink(logLevel: LogLevel) {
-    return Logger.#sinks.size > 0 && Logger.#fileLevelIdx <= logLevels.indexOf(logLevel);
+    return logSeverity[logLevel] >= Logger.#sinkFloorSev;
+  }
+  /** The lowest severity the ambient request wants captured or shown, or +∞ outside one. */
+  static #contextFloor(ctx: LogContextSnapshot | undefined) {
+    if (!ctx) return Number.POSITIVE_INFINITY;
+    return Math.min(ctx.flight?.minSev ?? Number.POSITIVE_INFINITY, ctx.debugSev ?? Number.POSITIVE_INFINITY);
+  }
+  static #buildRecord(
+    name: string | undefined,
+    message: string,
+    context: string,
+    level: LogLevel | null,
+    stream: "stdout" | "stderr",
+    ctx: LogContextSnapshot | undefined,
+    attrs?: LogAttrs,
+  ): LogRecord {
+    const proc = process as unknown as NodeJS.Process | undefined;
+    const replicaIdx = Number(proc?.env?.AKAN_REPLICA_IDX ?? Number.NaN);
+    const at = Date.now();
+    return {
+      at,
+      elapsedMs: at - Logger.startAt,
+      level,
+      sev: level === null ? 0 : logSeverity[level],
+      name: name ?? "App",
+      context,
+      message,
+      stream,
+      pid: proc?.pid ?? null,
+      replicaIdx: Number.isNaN(replicaIdx) ? null : replicaIdx,
+      role: Logger.role,
+      origin: ctx?.origin ?? null,
+      traceId: ctx?.traceId ?? null,
+      endpoint: ctx?.endpoint ?? null,
+      ...(attrs ? { attrs: Logger.redactAttrs(attrs) } : {}),
+    };
+  }
+  static #entry(record: LogRecord, text?: string): LoggerSinkEntry {
+    let message = text;
+    let plainMessage: string | undefined;
+    return {
+      stream: record.stream,
+      level: record.level ?? undefined,
+      record,
+      get message() {
+        message ??= Logger.render(record);
+        return message;
+      },
+      get plainMessage() {
+        plainMessage ??= Logger.stripAnsi(this.message);
+        return plainMessage;
+      },
+    };
   }
   static #emit(entry: LoggerSinkEntry) {
-    for (const sink of Logger.#sinks) {
+    for (const [sink, minSev] of Logger.#sinks) {
+      
+      if (
+        entry.record.level !== null &&
+        entry.record.sev < (minSev ?? Logger.#fileSev) &&
+        !Logger.isPromoted(entry.record)
+      )
+        continue;
       try {
         void Promise.resolve(sink(entry)).catch(() => undefined);
       } catch {
       }
     }
   }
-  static #printMessages(
-    name: string | undefined,
-    content: string,
-    context: string,
-    logLevel: LogLevel,
-    writeStreamType: "stdout" | "stderr" = logLevel === "error" ? "stderr" : "stdout",
-  ) {
-    const now = dayjs();
-    const replicaIdx = (process as unknown as NodeJS.Process | undefined)?.env?.AKAN_REPLICA_IDX;
-    const replicaMsg = replicaIdx === undefined ? "" : `#${replicaIdx} `;
-    const processMsg = Logger.#colorize(
-      `[${name ?? "App"}] ${replicaMsg}${(process as unknown as NodeJS.Process | undefined)?.pid ?? "window"} -`,
+  static #writeConsole(entry: LoggerSinkEntry) {
+    if (!Logger.consoleOutput) return;
+    if (typeof window === "undefined")
+      (process[entry.stream] as unknown as NodeJS.WriteStream | undefined)?.write(entry.message);
+    else console.log(entry.message);
+  }
+  static #write(name: string | undefined, message: string, context: string, logLevel: LogLevel, attrs?: LogAttrs) {
+    const stream = logLevel === "error" ? "stderr" : "stdout";
+    const ctx = readLogContext();
+    const sev = logSeverity[logLevel];
+    const debug = ctx?.debugSev !== undefined && ctx.debugSev !== null && sev >= ctx.debugSev;
+
+    const promoted = debug && sev < Logger.#consoleSev;
+    const record = Logger.#buildRecord(
+      name,
+      message,
+      context,
       logLevel,
+      stream,
+      ctx,
+      promoted ? { ...attrs, debug: true } : attrs,
     );
-    const timestampMsg = now.format("MM/DD/YYYY, HH:mm:ss A");
-    const logLevelMsg = Logger.#colorize(logLevel.toUpperCase().padStart(7, " "), logLevel);
-    const contextMsg = context ? clc.yellow(`[${context}] `) : "";
-    const contentMsg = Logger.#colorize(content, logLevel);
-    const timeDiffMsg = clc.yellow(`+${now.diff(Logger.#startAt, "ms")}ms`);
-    const message = `${processMsg} ${timestampMsg} ${logLevelMsg} ${contextMsg} ${contentMsg} ${timeDiffMsg}\n`;
-    if (Logger.#shouldEmitSink(logLevel))
-      Logger.#emit({ stream: writeStreamType, level: logLevel, message, plainMessage: Logger.#stripAnsi(message) });
-    if (!Logger.#shouldWriteConsole(logLevel)) return;
-    if (typeof window === "undefined")
-      (process[writeStreamType] as unknown as NodeJS.WriteStream | undefined)?.write(message);
-    else console.log(message);
+    const toConsole = Logger.#shouldWriteConsole(logLevel) || (debug && Logger.consoleOutput);
+    const toSinks = Logger.#shouldEmitSink(logLevel) || debug;
+    ctx?.flight?.capture(record, toConsole || toSinks);
+    if (!toConsole && !toSinks) return;
+    const entry = Logger.#entry(record);
+    if (toSinks) Logger.#emit(entry);
+    if (toConsole) Logger.#writeConsole(entry);
   }
   static rawLog(msg = "", method?: "console" | "process", outputStream?: "log" | "error") {
     Logger.raw(`${msg}\n`, method, outputStream);
   }
   static raw(msg = "", method?: "console" | "process", outputStream?: "log" | "error") {
     const stream = outputStream === "error" ? "stderr" : "stdout";
-    Logger.#emit({ stream, message: msg, plainMessage: Logger.#stripAnsi(msg) });
+    Logger.#emit(Logger.#entry(Logger.#buildRecord(undefined, msg, "", null, stream, readLogContext()), msg));
+    if (!Logger.consoleOutput) return;
     if (typeof window === "undefined" && method !== "console" && (process as unknown as NodeJS.Process | undefined))
       process[stream].write(msg);
     else console[outputStream === "error" ? "error" : "log"](msg.trim());
   }
+  static {
+    if (envValue("AKAN_PUBLIC_LOG_LEVEL") === "log" && typeof window === "undefined")
+      Logger.warn("AKAN_PUBLIC_LOG_LEVEL=log is deprecated and now means info; set AKAN_PUBLIC_LOG_LEVEL=info.");
+  }
 }