@ayepi/log 0.1.0 → 0.2.0

package/README.md

@@ -209,7 +209,7 @@ This package ships dense, machine-oriented reference docs written for **AI codin
 - [`ayepi-log-transports.md`](./ayepi-log-transports.md)
 - [`ayepi-log.md`](./ayepi-log.md)
 
-They live next to the source in the [repo](https://github.com/ClickerMonkey/ayepi/tree/main/packages/log) and are **not** shipped in the npm tarball.
+They ship with this package and also live in the [repo](https://github.com/ClickerMonkey/ayepi/tree/main/packages/log).
 
 ## License
 

package/ayepi-log-errors-console.md

@@ -0,0 +1,171 @@
+<!--
+ayepi-log-errors-console.md — reference for `@ayepi/log` error serialization & console
+interception, written for coding agents.
+
+Copy this file into any project that depends on `@ayepi/log` (e.g. into your repo's
+`docs/` or `.claude/` directory) and reference it from your agents and slash commands.
+It documents the public API, the patterns the package expects, and how it works under the
+hood, with copy-pasteable examples. Keep it in sync with the installed package version.
+-->
+
+# `@ayepi/log` — Error serialization & console interception
+
+Part of the `@ayepi/log` doc set (see `ayepi-log.md` for the overview and index). This
+file covers how `Error` arguments are serialized and how to opt into `console.*`
+interception.
+
+## Error serialization
+
+`Error` args passed to `log()` (and the exported `serializeError`) produce a
+`SerializedError`:
+
+```ts
+interface SerializedError {
+  readonly name: string
+  readonly message: string
+  readonly stack?: string
+  readonly cause?: unknown            // recursively serialized if an Error, depth-bounded
+  readonly [key: string]: unknown     // own enumerable props (e.g. code, statusCode)
+}
+
+function serializeError(err: unknown, cfg?: ErrorCaptureConfig): SerializedError
+```
+
+The first `Error` arg becomes the record's `error`; any further `Error` args become
+`additionalErrors`. Non‑`Error` values become `{ name: 'NonError', message }` (the message
+is the string itself, or `String(value)`, guarded against unstringifiable values).
+
+```ts
+const e1 = new Error('first'); (e1 as { code?: string }).code = 'E1'
+const e2 = new TypeError('second')
+
+log.error('failed', e1, e2)
+// record.error            = { name:'Error', message:'first', stack:'…', code:'E1' }
+// record.additionalErrors = [{ name:'TypeError', message:'second', stack:'…' }]
+```
+
+### Configuration — `ErrorConfig` / `ErrorCaptureConfig`
+
+What's captured is configured via `LoggerConfig.error`, with optional per‑level overrides
+(shallow‑merged over the base):
+
+```ts
+interface ErrorCaptureConfig {
+  readonly stack?: boolean          // include error.stack (default true)
+  readonly cause?: boolean          // recurse into error.cause (default true)
+  readonly fields?: boolean         // include own props like code/statusCode (default true)
+  readonly maxCauseDepth?: number   // max cause recursion depth (default 5)
+}
+
+interface ErrorConfig extends ErrorCaptureConfig {
+  readonly perLevel?: Partial<Record<Level, ErrorCaptureConfig>>
+}
+```
+
+```ts
+// Full stacks at error, but drop them for warn:
+const log = createLogger({
+  error: { stack: true, perLevel: { warn: { stack: false } } },
+})
+log.error('x', new Error('e')) // record.error.stack is a string
+log.warn('y', new Error('e'))  // record.error.stack is undefined
+```
+
+### `cause` chains
+
+`cause` is recursed when it's an `Error` (up to `maxCauseDepth`, default 5) and copied
+as‑is when it's a non‑Error value:
+
+```ts
+const root = new Error('root')
+const wrap = new Error('wrap', { cause: root })
+
+serializeError(wrap).cause                 // { name:'Error', message:'root', … }
+serializeError(wrap, { cause: false }).cause // undefined
+```
+
+### Error‑attached trace context
+
+When an error carries trace context (because it was rejected out of a `logWith` — see
+`ayepi-log.md`), logging it merges that context into the record:
+
+```ts
+const err = new Error('x')
+await log.logWith({ reqId: 'r9' }, () => Promise.reject(err)).catch(() => {})
+log.error('caught', err) // record includes reqId: 'r9'
+```
+
+---
+
+## Console interception (opt‑in)
+
+A bare `import` does **nothing** to `console`. Turn it on at creation or via
+`interceptConsole()`:
+
+```ts
+import { createLogger, interceptConsole, restoreConsole } from '@ayepi/log'
+
+createLogger({ interceptConsole: true })
+// or, on the default logger:
+const restore = interceptConsole()
+
+console.log('routed', { through: 'the logger' })
+restore()          // put the originals back
+// or: restoreConsole()
+```
+
+`Logger.interceptConsole()` returns a restore function; `Logger.restoreConsole()` does the
+same restore. Both are **idempotent**: calling `interceptConsole()` while already
+intercepting returns the same restore without re‑installing, and `restoreConsole()` after
+already restored is a no‑op. Interception captures the **true original** of each method so
+restore is exact.
+
+### Default method → level mapping (`CONSOLE_LEVEL_MAP`)
+
+| console method | level |
+| --- | --- |
+| `log`, `info`, `dir` | `info` |
+| `debug`, `trace` | `debug` |
+| `warn` | `warn` |
+| `error` | `error` |
+
+Object args passed to `console.*` are merged into the record just like normal `log()` args:
+
+```ts
+console.log('hello', { a: 1 }) // → record { level:'info', msg:'hello', a:1 }
+console.dir({ d: 1 })          // → record { level:'info', msg:'', d:1 }
+```
+
+Override the mapping with `LoggerConfig.consoleMap` (keys are method names, values are
+levels):
+
+```ts
+createLogger({
+  interceptConsole: true,
+  consoleMap: { log: 'debug', info: 'info', warn: 'warn', error: 'error' },
+})
+```
+
+### Recursion safety
+
+The default console transport writes through the **captured original** console, and the
+logger has a reentrancy guard so that even a custom transport which logs through the
+intercepted `console.*` cannot recurse infinitely — the nested intercepted call is
+short‑circuited.
+
+---
+
+## Gotchas
+
+- **Interception is global state.** Replacing `console.*` affects every consumer of that
+  console in the process; always keep the restore function and call it (e.g. in tests'
+  teardown).
+- **`info` maps to `info` level, but `log` also maps to `info`** by default — both land at
+  `info`. Adjust via `consoleMap` if you want `console.log` at `debug`.
+- **Below‑threshold console calls are dropped** like any other log (e.g. `console.debug`
+  with a logger at `level: 'info'`).
+- **Inject a `console`** via `LoggerConfig.console` to intercept a non‑global console (used
+  heavily in tests).
+
+See `ayepi-log.md` for the overview and `ayepi-log-transports.md` /
+`ayepi-log-middleware.md` for the rest of the doc set.

package/ayepi-log-middleware.md

@@ -0,0 +1,238 @@
+<!--
+ayepi-log-middleware.md — reference for `@ayepi/log/middleware` and internals, written for
+coding agents.
+
+Copy this file into any project that depends on `@ayepi/log` (e.g. into your repo's
+`docs/` or `.claude/` directory) and reference it from your agents and slash commands.
+It documents the public API, the patterns the package expects, and how it works under the
+hood, with copy-pasteable examples. Keep it in sync with the installed package version.
+-->
+
+# `@ayepi/log` — Middleware, merge & internals
+
+Part of the `@ayepi/log` doc set (see `ayepi-log.md` for the overview and index). This
+file covers the `@ayepi/log/middleware` ayepi integration (its `@ayepi/log/server` impl
+binder), the exported collision‑renaming `merge`, and how the package works under the hood.
+
+## `@ayepi/log/middleware` + `@ayepi/log/server`
+
+The ayepi middleware follows core's **def/impl split**: a frontend‑safe **def** declared in
+the spec, plus a server‑only **impl** bound with `implement(api).middleware(...)`.
+
+- **`@ayepi/log/middleware`** — frontend‑safe, **no `node:async_hooks`**. `logMiddleware(opts?)`
+  is a **def factory**: a no‑context middleware that establishes log trace context for the
+  downstream chain. Put this in shared/frontend code and your spec.
+- **`@ayepi/log/server`** — the impl, which pulls in `node:async_hooks` through the package
+  internals. `logMiddleware` here is **augmented** with `.server(def, { context, logWith? })`,
+  the binder that wraps `io.next()` in `logWith(...)` so the **entire downstream chain, the
+  handler, and any error they throw** run inside that context. Put this only in server code.
+
+See `ayepi-core-middleware.md` for how middleware, `requires`, stacks, `.group()` /
+`.endpoint()`, and `implement(api).middleware(def, impl)` work.
+
+```ts
+// @ayepi/log/middleware — frontend-safe def factory
+function logMiddleware<const R extends readonly AnyMiddleware[] = readonly []>(
+  opts?: LogMiddlewareOptions<R>,
+): MiddlewareDef<Provides, R, StackLP<R>>
+
+interface LogMiddlewareOptions<R extends readonly AnyMiddleware[]> {
+  /** Middleware this one depends on — their context is available (and typed) in `.server`'s `context`. */
+  readonly requires?: R
+  /** Middleware name for docs/debugging (default 'log'). */
+  readonly name?: string
+}
+
+// @ayepi/log/server — the impl binder (augmented onto logMiddleware)
+logMiddleware.server<Def>(
+  def: Def,
+  opts: LogServerOptions<StackCtx<Def>>,
+): MiddlewareImpl<Def>
+
+interface LogServerOptions<Ctx extends object> {
+  /** Build the context object to push for the downstream chain + handler. */
+  readonly context: (ctx: Ctx, req: Request) => object
+  /** logWith to use (default the package's shared trace context).
+   *  Pass a specific logger's logWith to scope it. */
+  readonly logWith?: <T>(add: object, inner: () => T) => T
+  /** Observe an error from building/pushing the context (off by default). The middleware is
+   *  fail-open: a throwing `context`/`logWith` runs the chain anyway, without the context. */
+  readonly onError?: (err: unknown) => void
+}
+```
+
+The def provides **nothing** to the handler context (`Provides = Record<never, never>`) — it
+only establishes the log context. The `context` builder and optional `logWith` live on the
+server side, in `.server`; the `requires` middleware flow their (typed) context into the
+`context` callback. Internally the impl just does `wrap(opts.context(io.ctx, io.req),
+() => io.next())`, where `wrap` is the `logWith` option (default the package's shared
+`logWith`).
+
+Every middleware in a chain must be bound: if you mount a `logMiddleware` def but never
+bind its impl with `.middleware(...)`, `server()` throws.
+
+### Wiring into a server
+
+The def goes in your spec (and any shared/frontend code); the impl is bound on the
+chainable `implement(api)` builder.
+
+```ts
+// shared.ts — frontend-safe: def only, no node:async_hooks
+import { spec } from '@ayepi/core'
+import { logMiddleware } from '@ayepi/log/middleware'
+import { z } from 'zod'
+
+export const trace = logMiddleware()
+export const api = spec({
+  endpoints: {
+    ping: trace.endpoint({ response: z.object({ path: z.string() }) }),
+  },
+})
+```
+
+```ts
+// server.ts — server-only: bind the impl (pulls in node:async_hooks)
+import { implement, server } from '@ayepi/core'
+import { logMiddleware } from '@ayepi/log/server'
+import { context } from '@ayepi/log'
+import { api, trace } from './shared'
+
+const app = server(api, [
+  implement(api)
+    .middleware(logMiddleware.server(trace, {
+      context: (_ctx, req) => ({ reqId: crypto.randomUUID(), path: new URL(req.url).pathname }),
+    }))
+    .handlers({
+      ping: () => ({ path: (context().path as string) ?? 'none' }),
+    }),
+])
+// Any log inside the handler — or a deeper async call — carries { reqId, path }.
+```
+
+Use `trace.group({ … })` to apply the def across a group of endpoints, exactly like any
+core middleware def (see `ayepi-core-middleware.md`).
+
+### Typed `requires`
+
+`requires` is declared on the **def** (frontend‑safe); the context from those middleware is
+available and typed in the `.server` `context` callback:
+
+```ts
+import { middleware } from '@ayepi/core'
+
+// shared.ts — def
+const auth = middleware('auth') // the auth def
+const trace = logMiddleware({ requires: [auth] })
+
+// server.ts — impl
+implement(api).middleware(logMiddleware.server(trace, {
+  context: (ctx) => ({ userId: ctx.user.id }), // ctx.user is typed from auth's def
+}))
+```
+
+### The `logWith` option — scoping to a specific logger
+
+By default the impl uses the package's **shared** trace context (the same
+`AsyncLocalStorage` the default logger and the top‑level `logWith`/`context` read). To call
+through a particular logger instance, pass that logger's `logWith` in `.server`:
+
+```ts
+const myLog = createLogger({ structured: true })
+implement(api).middleware(logMiddleware.server(trace, {
+  context: (_ctx, req) => ({ path: new URL(req.url).pathname }),
+  logWith: myLog.logWith, // call through myLog
+}))
+```
+
+It also accepts any wrapper of the shape `<T>(add, inner) => T`, useful for tests:
+
+```ts
+const seen: object[] = []
+logMiddleware.server(trace, {
+  context: () => ({ x: 1 }),
+  logWith: (add, inner) => { seen.push(add); return inner() },
+})
+```
+
+> Important: there is **no `logWith` hook on `server()`**. The only integration point is
+> this middleware wrapping `io.next()`. And because every `createLogger` instance shares
+> **one** global `AsyncLocalStorage`, the `logWith` option selects which logger object you
+> call through, but the underlying store is the same — `context()` anywhere observes the
+> same fields. The option exists for explicitness and for injecting a custom wrapper.
+
+---
+
+## Collision‑renaming `merge` (and `deepEqual`)
+
+Object args, ambient context, and error‑attached context are combined with an immutable
+**collision‑renaming `merge`** (exported, along with `deepEqual`):
+
+```ts
+function merge(a: Record<string, unknown>, b: Record<string, unknown>): Record<string, unknown>
+function deepEqual(a: unknown, b: unknown): boolean
+```
+
+`a` keeps all of its keys. Each key of `b` goes in the first free slot among
+`key, key2, key3, …`, **unless** an existing slot already deep‑equals `b`'s value (then
+it's deduped and dropped). Neither input is mutated.
+
+```ts
+merge({ a: 1 }, { a: 2 })          // { a: 1, a2: 2 }
+merge({ a: 1, a2: 9 }, { a: 2 })   // { a: 1, a2: 9, a3: 2 }
+merge({ a: 1 }, { a: 1 })          // { a: 1 }  (deduped)
+merge({ a: 1 }, { b: 2 })          // { a: 1, b: 2 }
+```
+
+`deepEqual` handles primitives (incl. `NaN`), `Date`, arrays, `Error` (by name + message),
+plain objects, and cycles. This is why ambient request fields like `reqId` / `userId` stay
+on their bare key across every log in a request, while a colliding call‑site value lands on
+`reqId2`.
+
+---
+
+## How it works under the hood
+
+- **AsyncLocalStorage propagation.** The package owns a single module‑level
+  `AsyncLocalStorage<Record<string, unknown>>`. `logWith` computes
+  `merge(currentStore, add)` and runs `inner` via `store.run(merged, inner)`. Because ALS
+  context survives `await`, every log emitted anywhere inside that call tree reads the same
+  merged object through `getContext()`. Outside any `logWith`, the store is empty (`{}`).
+- **Error tagging across async.** When `inner` returns a thenable, `logWith` attaches a
+  rejection handler that, on failure, defines a non‑enumerable `LOG_CONTEXT` property on
+  the error carrying the merged context (only if not already present — innermost wins),
+  then re‑throws. When that error is later passed to `log.error(err)`, the record builder
+  reads `err[LOG_CONTEXT]` and merges it in, so the catch‑site log reflects the throw‑site
+  context.
+- **Record building.** The builder partitions args into messages / objects / errors,
+  serializes errors per the effective (per‑level‑merged) `ErrorConfig`, then merges in
+  order: reserved fields → ambient context → object args → error‑attached contexts.
+- **Console interception.** Installation replaces each method named in `consoleMap` on the
+  target console with a closure that emits at the mapped level, saving the true original
+  for restore. The default console transport writes through the captured original console,
+  and `emit` has a reentrancy guard so a transport that logs through the intercepted
+  console can't recurse infinitely.
+- **File transport batching.** `write()` pushes a line into an in‑memory buffer and either
+  schedules a flush (`flushInterval`, with an unref'd timer) or forces one immediately once
+  the buffer crosses `maxBufferBytes`. `flush()` joins the buffer into one batch, does at
+  most one append per flush with one flush in flight, lazily stats the file once for size
+  rotation, and rotates/prunes as needed — all async, all best‑effort.
+
+---
+
+## Gotchas
+
+- **`@ayepi/core` is an optional peer dependency**, required only for the middleware
+  entries (`/middleware` and `/server`). The main and `/file` entries don't need it.
+- **Keep the def frontend‑safe.** Import `logMiddleware` from `@ayepi/log/middleware` in
+  shared/frontend code and your spec — it has **no `node:async_hooks`**. Only `server.ts`
+  should import from `@ayepi/log/server`, which pulls in `node:async_hooks`.
+- **Bind every middleware.** A `logMiddleware` def mounted in the chain must be bound with
+  `implement(api).middleware(logMiddleware.server(def, …))`, or `server()` throws.
+- **No `server()` logging hook.** Wire trace context exclusively through `logMiddleware`.
+- **One shared trace store.** You can't get two fully isolated context stores by creating
+  two loggers; the `logWith` option selects the call‑through logger, not a separate store.
+- **`context()` returns a frozen snapshot**; `getContext()` (also exported) returns the
+  live store object — prefer `context()` in application code.
+
+See `ayepi-log.md` for the overview, and `ayepi-log-transports.md` /
+`ayepi-log-errors-console.md` for the rest of the doc set.

package/ayepi-log-transports.md

@@ -0,0 +1,205 @@
+<!--
+ayepi-log-transports.md — reference for `@ayepi/log` transports, written for coding agents.
+
+Copy this file into any project that depends on `@ayepi/log` (e.g. into your repo's
+`docs/` or `.claude/` directory) and reference it from your agents and slash commands.
+It documents the public API, the patterns the package expects, and how it works under the
+hood, with copy-pasteable examples. Keep it in sync with the installed package version.
+-->
+
+# `@ayepi/log` — Transports
+
+Part of the `@ayepi/log` doc set (see `ayepi-log.md` for the overview and index). This
+file covers the `Transport` interface, the built‑in `consoleTransport`, and the
+non‑blocking rotating `fileTransport` from `@ayepi/log/file`.
+
+## The `Transport` interface
+
+```ts
+interface Transport {
+  readonly name: string
+  /** Write one record; `text` is the pre-formatted line. May be async; the logger never awaits it. */
+  write(record: LogRecord, text: string): void | Promise<void>
+  /** Optional: drain buffered writes without tearing down. Driven by `logger.flush()`. */
+  flush?(): void | Promise<void>
+  /** Optional: flush + release resources. Driven by `logger.close()`. */
+  close?(): void | Promise<void>
+}
+```
+
+`logger.flush()` calls every transport's `flush?()`; `logger.close()` calls every `close?()`.
+Both run in parallel and route a throwing transport to `onError` (they never reject), so one
+bad transport can't abort shutdown. The file transport implements both (`flush` drains the
+buffer; `close` does the same).
+
+The logger writes the same record to **every** configured transport, fire‑and‑forget:
+
+- a transport that **throws** never breaks logging (the error is swallowed);
+- returned **promises are not awaited**;
+- `setTransports(list)` swaps the transport list at runtime.
+
+A minimal in‑memory transport (handy for tests):
+
+```ts
+import { createLogger, type LogRecord, type Transport } from '@ayepi/log'
+
+const records: LogRecord[] = []
+const mem: Transport = { name: 'mem', write: (r) => void records.push(r) }
+const log = createLogger({ transports: [mem] })
+```
+
+A capture transport that grabs the formatted text:
+
+```ts
+let line = ''
+const cap: Transport = { name: 'cap', write: (_r, text) => { line = text } }
+```
+
+---
+
+## `consoleTransport(opts?)`
+
+```ts
+function consoleTransport(opts?: ConsoleTransportOptions): Transport
+
+interface ConsoleTransportOptions {
+  /** The console to write through — should be the original (pre-interception) console to avoid recursion. */
+  readonly console?: ConsoleLike
+  /** Map a record level to a console method (default: error→error, warn→warn, debug→debug, else→log). */
+  readonly method?: (level: Level) => keyof ConsoleLike
+}
+
+interface ConsoleLike {
+  log(...args: unknown[]): void
+  info(...args: unknown[]): void
+  debug(...args: unknown[]): void
+  warn(...args: unknown[]): void
+  error(...args: unknown[]): void
+}
+```
+
+Writes the pre‑formatted `text` to the level‑mapped console method. The default level →
+method mapping is `error → error`, `warn → warn`, `debug → debug`, everything else →
+`log`.
+
+The default logger's default transport is a `consoleTransport` bound to the **captured
+original** console (taken before any interception is installed), so logs aren't recursed
+even when console interception is on. If `globalThis.console` is absent it falls back to a
+no‑op console (no throw).
+
+```ts
+import { createLogger, consoleTransport } from '@ayepi/log'
+
+// Route everything to console.error, e.g. for stderr-only logging:
+createLogger({ transports: [consoleTransport({ method: () => 'error' })] })
+```
+
+---
+
+## `fileTransport(opts)` — `@ayepi/log/file`
+
+A Node file transport with rotation, built for heavy load. `write()` is **non‑blocking**:
+it appends to an in‑memory buffer and returns immediately. Buffered lines flush to disk in
+**batches** — one append per flush, at most one flush in flight — so callers never wait on
+I/O and the FS isn't hit with a syscall per line. Everything touching the filesystem uses
+`node:fs/promises`, so a flush never blocks the event loop. It **defaults to structured
+JSON lines** regardless of the logger's text/JSON setting.
+
+```ts
+function fileTransport(opts: FileTransportOptions): Transport
+
+interface FileTransportOptions {
+  /** Target file path (e.g. './logs/app.log'). The directory is created if missing. */
+  readonly path: string
+  /** Rotate when the active file would exceed this many bytes (default 10 MiB). */
+  readonly maxSize?: number
+  /** Keep at most this many rotated/dated files (default 5). */
+  readonly maxFiles?: number
+  /** Write structured JSON lines regardless of the logger's text/json setting (default true). */
+  readonly structured?: boolean
+  /** Rotation strategy (default 'size'). */
+  readonly strategy?: 'size' | 'date'
+  /** Flush the buffer at most this often, in ms (default 250). */
+  readonly flushInterval?: number
+  /** Force an immediate flush once the buffer reaches this many bytes (default 256 KiB). */
+  readonly maxBufferBytes?: number
+  /** Injected fs (default node:fs/promises). */
+  readonly fs?: FsLike
+  /** Observe a background flush failure (disk full / permission denied). Best-effort: a failed
+   *  flush never rejects; this hook lets you notice. Off by default. */
+  readonly onError?: (err: unknown) => void
+  /** Injected clock for date rotation/naming (default () => Date.now()). */
+  readonly now?: () => number
+}
+```
+
+### Rotation strategies
+
+- **`'size'`** (default): keeps `app.log` bounded to `maxSize`, shifting
+  `app.log → app.log.1 → app.log.2 → …` and pruning beyond `maxFiles`. On rotation the
+  oldest (`app.log.{maxFiles}`) is deleted first, then files shift up, then the active
+  `app.log → app.log.1`. The active size is statted lazily (once) to avoid a `stat` per
+  write.
+- **`'date'`**: writes `app-YYYY-MM-DD.log` (date from `now()`), pruning dated files
+  beyond `maxFiles` (oldest ISO date first).
+
+### Flushing & shutdown
+
+`close()` flushes the buffer — wire it to a shutdown hook (e.g. an `@ayepi/updown`
+shutdown hook) so the last batch isn't lost on exit. The internal flush timer is
+`unref`'d, so a pending flush won't keep the process alive on its own.
+
+```ts
+import { createLogger } from '@ayepi/log'
+import { fileTransport } from '@ayepi/log/file'
+
+const file = fileTransport({
+  path: './logs/app.log',
+  maxSize: 10 * 1024 * 1024,
+  maxFiles: 7,
+})
+const log = createLogger({ structured: true, transports: [file] })
+
+// on shutdown:
+await file.close?.()
+```
+
+Date rotation:
+
+```ts
+const file = fileTransport({ path: './logs/app.log', strategy: 'date', maxFiles: 14 })
+// writes ./logs/app-2026-06-16.log, rolling to a new file each day
+```
+
+### `FsLike`
+
+The async fs surface the transport uses (`node:fs/promises` satisfies it). Exported so
+tests can inject a deterministic in‑memory fs and assert rotation/prune behavior:
+
+```ts
+interface FsLike {
+  exists(path: string): Promise<boolean>
+  stat(path: string): Promise<{ size: number }>
+  mkdir(path: string, opts: { recursive: true }): Promise<void>
+  appendFile(path: string, data: string): Promise<void> // the hot path
+  rename(from: string, to: string): Promise<void>
+  unlink(path: string): Promise<void>
+  readdir?(path: string): Promise<string[]> // required for date pruning
+}
+```
+
+---
+
+## Gotchas
+
+- **Transports are fire‑and‑forget.** The logger never awaits `write()` and swallows its
+  throws. The file transport may still be buffering when a call returns — call `close()`
+  on shutdown to flush.
+- **The file transport defaults to JSON lines** even if the logger is in text mode. Pass
+  `structured: false` to write the text format (`text` argument) instead.
+- **Directory creation is lazy**, on first flush — not at construction time.
+- **Best‑effort I/O.** A flush that fails (or a failed rotate/prune) is swallowed, never
+  rejected — file logging never crashes the app.
+
+See `ayepi-log.md` for the overview and `ayepi-log-errors-console.md` /
+`ayepi-log-middleware.md` for the rest of the doc set.

package/ayepi-log.md

@@ -0,0 +1,470 @@
+<!--
+ayepi-log.md — reference for `@ayepi/log`, written for coding agents.
+
+Copy this file into any project that depends on `@ayepi/log` (e.g. into your repo's
+`docs/` or `.claude/` directory) and reference it from your agents and slash commands.
+It documents the public API, the patterns the package expects, and how it works under the
+hood, with copy-pasteable examples. Keep it in sync with the installed package version.
+-->
+
+# `@ayepi/log`
+
+Structured logging built around an **AsyncLocalStorage trace context**: you stack
+context with `logWith(...)` and every log emitted inside that async call tree — and
+any `Error` thrown out of it — automatically carries those fields. Records are built
+from mixed primitive/object/`Error` arguments, formatted as text (default) or JSON,
+and written to pluggable **transports** (a console transport in the main entry, a
+non‑blocking rotating **file transport** in `@ayepi/log/file`). It can optionally
+intercept `console.*`, and ships an ayepi **middleware** — a frontend‑safe def
+(`@ayepi/log/middleware`) bound by a server impl (`@ayepi/log/server`) — that pushes
+per‑request trace context for an entire endpoint chain. Reach for it when
+you want request‑scoped, traceable structured logs in an ayepi service (or any Node
+app). A bare `import` has **no side effects** — console interception is opt‑in.
+
+```sh
+pnpm add @ayepi/log
+```
+
+This package builds on `@ayepi/core` middleware concepts — see `ayepi-core.md` and
+`ayepi-core-middleware.md` for `middleware()`, `spec()`, `server()`, stacks, and
+`.group()` / `.endpoint()`.
+
+## This doc set
+
+This reference is split by topic:
+
+- **`ayepi-log.md`** (this file) — overview, entry points, `createLogger` / `Logger`,
+  log levels, record building, the trace context (`logWith` / `context`), formatting,
+  and the `filter` hook.
+- **`ayepi-log-transports.md`** — the `Transport` interface, `consoleTransport`, and the
+  non‑blocking rotating `fileTransport` (`@ayepi/log/file`) with all its options.
+- **`ayepi-log-errors-console.md`** — error serialization (`serializeError`, `ErrorConfig`,
+  per‑level overrides) and opt‑in `console.*` interception.
+- **`ayepi-log-middleware.md`** — the `@ayepi/log/middleware` def + `@ayepi/log/server`
+  impl ayepi integration, plus the collision‑renaming `merge` and a "how it works under the
+  hood" section.
+
+## Entry points
+
+| Import | Exposes |
+| --- | --- |
+| `@ayepi/log` | `createLogger`, `consoleTransport`, the default logger + bound convenience functions, `logWith`/`context`, console interception, `logMaybe`, `createSanitizer`/`partialMask`, `resolveLogValue`, `merge`/`deepEqual`/`serializeError`/`getContext`, and all types |
+| `@ayepi/log/file` | `fileTransport`, `FileTransportOptions`, `FsLike` |
+| `@ayepi/log/middleware` | `logMiddleware` def factory, `LogMiddlewareOptions` — frontend‑safe, **no `node:async_hooks`** (peer‑depends on `@ayepi/core`) |
+| `@ayepi/log/server` | `logMiddleware` augmented with `.server(def, { context, logWith? })`, `LogServerOptions` — the impl binder, pulls in `node:async_hooks` (peer‑depends on `@ayepi/core`) |
+
+---
+
+## Quick start
+
+```ts
+import { createLogger } from '@ayepi/log'
+
+const log = createLogger({ level: 'debug' })
+
+log.logWith({ reqId: 'abc' }, async () => {
+  log.info('handling', { userId: 'u1' }) // record carries reqId + userId
+  await work()                            // a rejection here is tagged with { reqId, userId }
+})
+```
+
+There is also a ready‑made **default logger** (level `info`, text output, writes to the
+captured console) with bound top‑level functions, so you don't have to create one:
+
+```ts
+import { info, error, logWith, context } from '@ayepi/log'
+
+info('server started', { port: 3000 })
+logWith({ reqId: 'r1' }, () => error('boom', new Error('nope')))
+```
+
+The full set of default‑logger bindings: `log`, `debug`, `info`, `warn`, `error`,
+`logWith`, `context`, `interceptConsole`, `restoreConsole`, and `logger` (the instance
+itself).
+
+---
+
+## Levels
+
+```ts
+type Level = 'debug' | 'info' | 'warn' | 'error'
+```
+
+Severity ordering (`debug < info < warn < error`). A logger emits a record only if its
+level is `>=` the configured threshold; below‑threshold calls are dropped **before** a
+record is built (cheap to leave in). Default threshold is `'info'`.
+
+---
+
+## `createLogger(config?)`
+
+```ts
+function createLogger(config?: LoggerConfig): Logger
+```
+
+### `LoggerConfig`
+
+```ts
+interface LoggerConfig {
+  /** Minimum level emitted (default 'info'). Logs below this are dropped before a record is built. */
+  readonly level?: Level
+  /** Structured JSON output vs `[tms] level msg key=value` text (default false = text). */
+  readonly structured?: boolean
+  /** Timestamp format — ISO string (default) or numeric epoch ms. */
+  readonly timestamp?: 'iso' | 'epoch'
+  /** Transports to write to (default: a single consoleTransport bound to the captured original console). */
+  readonly transports?: readonly Transport[]
+  /** Intercept global console.* immediately (default false — opt-in). */
+  readonly interceptConsole?: boolean
+  /** console method → level mapping for interception (default CONSOLE_LEVEL_MAP). */
+  readonly consoleMap?: Readonly<Record<string, Level>>
+  /** The console to read originals from / intercept (default the global console). */
+  readonly console?: ConsoleLike
+  /** Error serialization config, including per-level overrides. */
+  readonly error?: ErrorConfig
+  /** Final hook over the built record before formatting. Return a (possibly modified)
+   *  record to log it, or null/undefined to drop the log entirely. Runs before `sanitize`. */
+  readonly filter?: (record: LogRecord) => LogRecord | null | undefined
+  /** Declarative redaction/truncation applied to every record (after `filter`) — for both
+   *  direct calls and intercepted console.*. See "Sanitization" below. */
+  readonly sanitize?: SanitizeOptions
+  /** Custom serializers for types you don't own (Request/URL/Buffer/third-party). See "Value resolution". */
+  readonly serializers?: readonly Serializer[]
+  /** Observe a pipeline error — a throwing `filter`, an unserializable record, or a transport
+   *  whose `write` throws. Logging is best-effort: the line is dropped, never thrown. Off by default. */
+  readonly onError?: (err: unknown) => void
+  /** Clock injection for tests (default () => Date.now()). */
+  readonly now?: () => number
+}
+```
+
+> Logging never throws into the caller: if building/filtering/formatting a line or a transport
+> `write` fails, the line is dropped and routed to `onError` (if set). The file transport takes
+> its own `onError` for background **flush** failures (disk full / permission denied).
+
+See `ayepi-log-transports.md` for `Transport`, `ayepi-log-errors-console.md` for
+`ErrorConfig` / `ConsoleLike` / `consoleMap`.
+
+### `Logger`
+
+```ts
+interface Logger {
+  /** Emit a record at `level` from mixed primitive/object/Error args. No-op below the threshold. */
+  log(level: Level, ...args: unknown[]): void
+  debug(...args: unknown[]): void
+  info(...args: unknown[]): void
+  warn(...args: unknown[]): void
+  error(...args: unknown[]): void
+  /** Merge `add` into the current trace context, run `inner` within it, tag promise rejections. */
+  logWith<R>(add: object, inner: () => R): R
+  /** Snapshot of the current merged trace context (empty outside any logWith). */
+  context(): Readonly<Record<string, unknown>>
+  /** Replace the transports at runtime. */
+  setTransports(transports: readonly Transport[]): void
+  /** Change the minimum emitted level at runtime (e.g. bump to 'debug' on demand). */
+  setLevel(level: Level): void
+  /** Whether a record at `level` would be emitted now — guard expensive prep (cf. logMaybe). */
+  isLevelEnabled(level: Level): boolean
+  /** Drain every transport's buffered writes (e.g. the file transport) without closing them. */
+  flush(): Promise<void>
+  /** Flush AND close every transport (release timers/handles) — wire to a shutdown hook. */
+  close(): Promise<void>
+  /** The effective level/format/timestamp (`level` reflects setLevel). */
+  readonly config: { readonly level: Level; readonly structured: boolean; readonly timestamp: 'iso' | 'epoch' }
+  /** Begin intercepting console.* (idempotent); returns a restore function. */
+  interceptConsole(): () => void
+  /** Restore any console interception this logger installed (idempotent). */
+  restoreConsole(): void
+}
+```
+
+- **`setLevel` / `isLevelEnabled`** — change verbosity at runtime (an admin endpoint, a signal
+  handler) without recreating the logger; `isLevelEnabled(lvl)` guards an expensive block when
+  `logMaybe` doesn't fit. `config.level` reflects the current level.
+- **`flush` / `close`** — `flush()` drains buffered transports (the file transport) without
+  tearing them down; `close()` flushes **and** releases resources. Both run every transport in
+  parallel and route a failing one to `onError` (never throwing), so one bad transport can't
+  abort shutdown. Wire `close()` into an `@ayepi/updown` teardown hook.
+
+---
+
+## Building a record — `log(level, …args)`
+
+Each `log` / `debug` / `info` / `warn` / `error` call builds a `LogRecord` from mixed
+arguments:
+
+- **non‑object args** (strings, numbers, booleans, `null`, `undefined`) are stringified
+  and space‑joined into `msg`;
+- **plain object args** are **merged** into the record (see the collision‑renaming `merge`
+  in `ayepi-log-middleware.md`);
+- **`Error` args** become `error` (the first) and `additionalErrors` (the rest),
+  serialized; and **any trace context attached to a caught error is merged in** (so an
+  error logged at the catch site carries the context from where it was thrown).
+
+```ts
+interface LogRecord {
+  readonly tms: string | number        // ISO string (default) or epoch ms
+  readonly level: Level
+  readonly msg: string
+  readonly error?: SerializedError
+  readonly additionalErrors?: readonly SerializedError[]
+  readonly [key: string]: unknown      // merged fields
+}
+```
+
+```ts
+log.info('done in', 42, 'ms', { req: 'x' })
+// → { tms, level:'info', msg:'done in 42 ms', req:'x' }
+
+log.error('upload failed', err, { docId })
+// → { tms, level:'error', msg:'upload failed', docId, error:{ name, message, stack, cause… }, …throwSiteContext }
+```
+
+The field‑order precedence used to build the record is:
+**reserved (`tms`/`level`/`msg`/`error`/`additionalErrors`) → ambient context → object
+args → error‑attached context**, all combined with the collision‑renaming `merge`. The
+ambient context therefore keeps the bare key; a colliding call‑site object value lands
+on `key2`.
+
+```ts
+log.logWith({ user: 'a' }, () => log.info('hi', { user: 'b' }))
+// → { user: 'a', user2: 'b', msg: 'hi', … }
+```
+
+### Value resolution — `toLOG` / `toJSON`
+
+Before a value is merged/classified, it's resolved to its **loggable plain shape** (deeply),
+so the resolved shape is consistent everywhere: the record object transports receive, the
+`sanitize` pass, and both the JSON and text output. Two hooks are honored, then a structural
+copy (mirroring `JSON.stringify` — own enumerable entries; `Error`s keep their dedicated
+serialization; cycles are preserved):
+
+- **`toLOG()`** — a **logging-specific** hook that **takes precedence over `toJSON`**. Define it
+  to shape a value for logs alone, without affecting `JSON.stringify` / your API responses. It
+  **may return a promise** — the line is then delivered asynchronously once it resolves (an
+  expensive or async log view is only produced when the line actually logs).
+- **`toJSON(key)`** — the standard hook (e.g. `Date` → ISO string).
+
+```ts
+class Money {
+  constructor(private cents: number) {}
+  toJSON() { return this.cents }                       // API: a number
+  toLOG()  { return `$${(this.cents / 100).toFixed(2)}` } // logs: "$19.99"
+}
+log.info('charged', { amount: new Money(1999) }) // → { msg:'charged', amount:'$19.99' }
+
+class Account {
+  async toLOG() { return { id: this.id, balance: await this.fetchBalance() } } // awaited before logging
+}
+```
+
+- A top-level value whose hook resolves to a **scalar** joins `msg`; to an **object**, merges
+  as fields (so a top-level `toJSON`/`toLOG` no longer clobbers the line).
+- A hook that **throws or rejects** (or a raw promise value that rejects) degrades that value to
+  `'(unresolved value)'` and reports to `onError` — the rest of the line still logs.
+- The exported **`resolveLogValue(value)`** runs this resolution standalone.
+
+**Custom serializers** handle values you *don't* own — a `Request`, `URL`, `Buffer`, a
+third-party class — where you can't add a `toLOG` hook. Configure `serializers` on the logger:
+each is tried in order at every depth, the first non-`undefined` result wins, and serializers
+take **precedence over** a value's own `toLOG`/`toJSON`. Return `undefined` (or throw — it's
+reported) to decline to the next.
+
+```ts
+type Serializer = (value: object) => unknown // return the shape, or undefined to decline
+
+createLogger({
+  serializers: [
+    (v) => (v instanceof URL ? v.href : undefined),
+    (v) => (v instanceof Request ? { method: v.method, url: v.url } : undefined),
+    (v) => (Buffer.isBuffer(v) ? `<${v.length}b>` : undefined),
+  ],
+})
+```
+
+Precedence overall: **serializers → `toLOG` → `toJSON` → structural copy** (`Error`s keep their
+dedicated serialization).
+
+---
+
+## Trace context — `logWith` / `context`
+
+```ts
+logWith<R>(add: object, inner: () => R): R
+context(): Readonly<Record<string, unknown>>
+```
+
+`logWith(add, inner)` merges `add` into the ambient context (immutably) and runs `inner`
+inside an `AsyncLocalStorage` scope carrying the merged context. Every log emitted by
+`inner` — at any await depth — picks up those fields automatically.
+
+```ts
+import { logWith, context } from '@ayepi/log'
+
+await logWith({ reqId: 'r1' }, async () => {
+  context() // { reqId: 'r1' }
+  await new Promise((r) => setTimeout(r, 5))
+  context() // still { reqId: 'r1' } — propagates across awaits
+})
+context() // {} — restored on exit
+```
+
+Nesting stacks (innermost merged over outer):
+
+```ts
+logWith({ a: 1 }, () => logWith({ b: 2 }, () => context())) // { a: 1, b: 2 }
+```
+
+### Errors thrown out of `logWith` are tagged
+
+If `inner` returns a **promise**, its rejection is tagged with the full merged context,
+stored on the error under the `LOG_CONTEXT` symbol. The **innermost** `logWith` wins, and
+an already‑tagged error is never overwritten.
+
+```ts
+const err = new Error('boom')
+await logWith({ reqId: 'r1' }, () => Promise.reject(err)).catch(() => {})
+// err now carries { reqId: 'r1' } under LOG_CONTEXT
+
+// Later, at the catch site, logging the error reattaches that context:
+log.error('caught', err) // record includes reqId: 'r1'
+```
+
+> Note: only **promise rejections** are tagged. A **synchronous** throw out of `logWith`
+> is re‑thrown unchanged (not tagged) — make `inner` async if you want the tag.
+
+`LOG_CONTEXT` is exported (`Symbol.for('@ayepi/log:ctx')`, stable across bundles) so you
+can read it off an error directly: `(err as Record<symbol, unknown>)[LOG_CONTEXT]`.
+
+`getContext()` is also exported — it returns the **mutable** current store object
+(`Record<string, unknown>`), whereas `context()` returns a frozen snapshot. Prefer
+`context()` in application code.
+
+---
+
+## Output & formatting
+
+Two formats, chosen by `structured`:
+
+- **text** (default): `[tms] level msg key=value, key=value` with a trailing
+  `error=Name: message` and `(+N more)` for additional errors.
+  ```
+  [1700000000000] info hello a=1, b=x
+  [1700000000000] error boom error=Error: nope
+  ```
+- **JSON** (`structured: true`): one stable JSON object per line. `undefined` values are
+  dropped and residual cycles become `"[Circular]"`.
+
+`timestamp: 'epoch'` makes `tms` a number (`Date.now()`); the default `'iso'` makes it
+`new Date(now()).toISOString()`.
+
+### `filter` hook
+
+Runs on the built record just before formatting (and after threshold + record build).
+Return a (possibly modified) record to keep it, or `null` / `undefined` to drop the log
+entirely. Use it to redact or enrich:
+
+```ts
+createLogger({
+  filter: (r) => (r.secret ? null : { ...r, ip: redact(r.ip) }),
+})
+```
+
+---
+
+## Sanitization — `sanitize` / `createSanitizer`
+
+Declarative redaction + truncation applied to every record after `filter`, for both direct
+logger calls **and** intercepted `console.*` (it transforms the record before formatting, so
+text and JSON output are both sanitized). Configure it on the logger, or build a standalone
+transformer with `createSanitizer(opts)` (same `(record) => record | null` shape as `filter`,
+so it composes there too).
+
+```ts
+interface SanitizeOptions {
+  /** Drop a record entirely — return false. Runs first. */
+  filter?: (record: LogRecord) => boolean
+  /** Property names to mask — string (case-insensitive exact) or RegExp. Matched at any depth. */
+  sensitiveKeys?: readonly (string | RegExp)[]
+  /** String values to mask when they match — string (case-insensitive substring) or RegExp. */
+  sensitiveValues?: readonly (string | RegExp)[]
+  /** Turn a sensitive value into its masked form (default () => '[redacted]'; see partialMask). */
+  mask?: (value: unknown, key?: string) => unknown
+  /** Truncate strings longer than this; appends '... (+N more)'. */
+  maxStringLength?: number
+  /** Truncate a homogeneous array (all elements same kind) beyond this; appends a '(+N more)' element. */
+  maxArrayLength?: number
+}
+```
+
+```ts
+import { createLogger, partialMask } from '@ayepi/log'
+
+const log = createLogger({
+  sanitize: {
+    sensitiveKeys: ['password', 'authorization', /token$/i], // → '[redacted]'
+    sensitiveValues: [/\b\d{16}\b/],                          // mask card-number-looking strings
+    mask: partialMask(3),                                      // keep first 3 chars, then '***'
+    maxStringLength: 2000,                                     // long blobs → 'first 2000…... (+N more)'
+    maxArrayLength: 100,                                       // big homogeneous arrays → first 100 + '(+N more)'
+  },
+})
+```
+
+- The sanitizer walks **plain** objects and arrays; the reserved `tms` / `level` fields are
+  kept pristine. (In the pipeline, values are already resolved to plain shapes by the
+  `toLOG`/`toJSON` pass above before `sanitize` runs, so `Date`s arrive as strings, etc.)
+- `partialMask(keep = 0, fill = '***')` is the bundled helper (`partialMask(3)('secret') === 'sec***'`;
+  values no longer than `keep`, and the default `keep` of 0, mask fully).
+- Cycles / shared references are left as the original ref (the formatter handles them).
+
+## Deferred arguments — `logMaybe`
+
+`logMaybe(fn)` wraps an expensive argument so `fn` runs **only when the line is actually
+logged** (its level passes the threshold). Under console interception the structured pipeline
+calls `fn(level)` and awaits it, then treats the result as a normal argument (an object is
+merged, a string joins `msg`, an `Error` becomes `record.error`). A line below the threshold
+never invokes `fn` at all.
+
+```ts
+import { logMaybe } from '@ayepi/log'
+
+log.debug('state', logMaybe(() => buildExpensiveSnapshot())) // snapshot built only at debug level
+log.info('user', logMaybe(async (lvl) => loadProfile(lvl)))  // async is awaited before the line is written
+```
+
+```ts
+function logMaybe(fn: (level: Level) => MaybePromise<unknown>): LazyLogValue
+```
+
+- A line containing a top-level `logMaybe` is delivered **asynchronously** (the value is
+  awaited first). Nested `logMaybe` values aren't resolved — they render via `toJSON`.
+- On the **non-intercepted** path the returned value has a `toJSON` (and Node inspect) that
+  renders the synchronous value, or `'(unresolved value)'` when `fn` returns a promise.
+- If `fn` throws / rejects, the argument becomes `'(unresolved value)'` and the error is
+  routed to `onError`.
+
+---
+
+## Gotchas (overview‑level)
+
+- **Bare import is side‑effect‑free.** Nothing touches `console` until you opt in.
+- **Synchronous throws aren't tagged** with trace context — only promise rejections out of
+  `logWith` get the `LOG_CONTEXT` tag.
+- **Threshold drops happen early.** A call below the level threshold never builds a record
+  or runs `filter`, so don't rely on side effects in argument expressions — wrap an expensive
+  argument in `logMaybe(fn)` to compute it only when the line will be logged.
+- **One shared trace store.** Every logger instance shares the package's global
+  `AsyncLocalStorage`; you can't get two fully isolated context stores by creating two
+  loggers. (More in `ayepi-log-middleware.md`.)
+
+For transport‑, error‑, console‑, and middleware‑specific gotchas, see the topic files.
+
+---
+
+## Related docs
+
+- `ayepi-log-transports.md`, `ayepi-log-errors-console.md`, `ayepi-log-middleware.md`
+  (this doc set).
+- `ayepi-core.md` — `spec()`, `implement()`, `server()`.
+- `ayepi-core-middleware.md` — `middleware()`, stacks, `.group()` / `.endpoint()`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ayepi/log",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Structured logging for ayepi — AsyncLocalStorage trace context, console interception, console/file transports, error serialization, middleware",
   "license": "MIT",
   "publishConfig": {
@@ -18,7 +18,8 @@
   "type": "module",
   "sideEffects": false,
   "files": [
-    "dist"
+    "dist",
+    "ayepi-*.md"
   ],
   "exports": {
     ".": {
@@ -67,7 +68,7 @@
     "node": ">=18"
   },
   "peerDependencies": {
-    "@ayepi/core": "^0.1.0"
+    "@ayepi/core": "^0.2.0"
   },
   "peerDependenciesMeta": {
     "@ayepi/core": {
@@ -80,7 +81,7 @@
     "tsdown": "^0.12.0",
     "vitest": "^2.1.8",
     "zod": "^4.4.3",
-    "@ayepi/core": "0.1.0"
+    "@ayepi/core": "0.2.0"
   },
   "keywords": [
     "ayepi",