@ekkolyth/logging 0.1.0 → 0.1.1

package/README.md

@@ -1,751 +1,29 @@
 # @ekkolyth/logging
 
-Structured logging for JavaScript/TypeScript and Go, with a private Go
-companion module sharing the same semantics. The published package is
-`@ekkolyth/logging`; the Go module is source-private and lives alongside it in
-the same repository.
+Structured logging for JavaScript/TypeScript.
 
-## 1. Purpose
-
-`@ekkolyth/logging` gives a service one thing to reach for when it needs to emit
-a log line, propagate request context, or wrap an HTTP boundary. It replaces
-a wrapper around a third-party logging library with an owned engine: no
-runtime dependencies, no borrowed formatting, no surface the maintainer
-didn't design.
-
-The JavaScript package targets Node ≥20, Bun, and browsers. The Go module
-targets `log/slog`. Both produce the same semantic log record — same field
-names, same defaults, same failure behavior — while keeping each runtime's
-own idiom for calling the logger.
-
-## 2. Design mindset
-
-Three decisions shape everything else in this package:
-
-- **Own the engine, don't wrap one.** JavaScript's formatter, redactor, and
-  serializer are all first-party code with zero runtime dependencies. Go
-  builds directly on the standard library's `log/slog.Handler` interface
-  rather than introducing a second logging abstraction next to it.
-- **Total normalization.** No supported logging call fails because a value
-  can't be represented. A cyclic object, a throwing getter, a stray
-  `Symbol`, or a `slog.LogValuer` that panics all resolve to an explicit
-  marker instead of crashing the caller. A logging library that can throw
-  from inside a call site defeats the reason it exists.
-- **Validated boundaries, minimal surface.** Each entry point exports
-  exactly what it needs to and nothing accumulated along the way. Enum and
-  environment misconfiguration fails loudly and early, at construction time
-  — a `TypeError` in JavaScript, a panic in Go — because that failure is
-  cheap to see in development and expensive to discover in production.
-  Runtime record and output failures never do this; they degrade to an
-  internal-error path instead (see §6).
-
-## 3. The React-to-React-Native semantic-parity model
-
-JavaScript and Go are not the same language, and this package doesn't
-pretend they are. The model is closer to React and React Native: the same
-concepts — components, props, a render cycle — expressed through each
-platform's native idiom (JSX and the DOM vs. native views). A developer who
-knows one can read the other without relearning what a "component" is, but
-never expects the call syntax to match.
-
-`@ekkolyth/logging` and its Go companion apply the same idea to logging:
-
-| Concept | Shared semantics | JavaScript idiom | Go idiom |
-|---|---|---|---|
-| Emit a record | same field names, same precedence, same failure behavior | `log.info(msg, attrs)` — message first, attributes second | `log.Info(msg, "key", value, ...)` — native `slog` variadic pairs |
-| Bind attributes | new logger, same emission rules | `log.with(bindings)` returns a new `Logger` | `log.With(...)` returns a new `*slog.Logger` |
-| Configure | same options, same env vars, same resolution order | `createLogger(options)` throws `TypeError` on bad input | `logger.New(options)` panics naming the bad field |
-| Propagate context | same merge rules, root logger picks it up automatically | `AsyncLocalStorage` under `runWithContext` | `context.Context` under `logcontext.With` |
-| Wrap HTTP | same correlation, same level policy, same sampling | Web `Request`/`Response` wrappers | `http.Handler`/`http.RoundTripper` wrappers |
-
-What is **intentionally** different: JavaScript accepts an attributes object
-because that is how the language expresses a record; Go accepts variadic
-key-value pairs because that is `slog`'s native argument shape. Go returns
-`*slog.Logger` so `With`, `Enabled`, and the `*Context` methods keep their
-standard-library behavior; JavaScript returns a purpose-built `Logger`
-because there is no standard-library equivalent to preserve. Neither side
-apologizes for reading like the language it's written in — a Go caller
-should never have to squint at a JavaScript-shaped API, and vice versa.
-
-## 4. Package anatomy
-
-Three JavaScript entry points, and a Go module with two subpackages that
-mirror them:
-
-```text
-@ekkolyth/logging            core: levels, records, redaction, formatting, output
-@ekkolyth/logging/context    transport of immutable bindings
-@ekkolyth/logging/http       correlation-header handling, HTTP boundary records
-```
-
-```text
-github.com/ekkolyth/ekko-os/packages/logging/go            package logger
-github.com/ekkolyth/ekko-os/packages/logging/go/context    package logcontext
-github.com/ekkolyth/ekko-os/packages/logging/go/http       package loghttp
-```
-
-The dependency direction is one-way: HTTP may consume context, context knows
-nothing about HTTP, and none of the three layers imports anything outside
-the package. In particular, no layer imports this repository's Ekko service
-or scope catalog — that catalog is repository-only lint data (see §9), never
-a runtime dependency of the logger itself.
-
-## 5. Quick starts
-
-<!-- readme-quickstart:js -->
-
-```ts
-import { createLogger } from '@ekkolyth/logging'
-import { runWithContext } from '@ekkolyth/logging/context'
-import { wrapHandler } from '@ekkolyth/logging/http'
-
-const log = createLogger({ service: 'api', scope: 'queue' })
-
-log.info('queue drained', { count: 12, duration_ms: 340 })
-
-await runWithContext({ request_id: 'req_123' }, async () => {
-    log.info('processing job')
-})
-
-const handler = wrapHandler(log, async () => new Response('ok'))
-```
-
-<!-- readme-quickstart:go -->
-
-```go
-import (
-    "context"
-
-    logger "github.com/ekkolyth/ekko-os/packages/logging/go"
-    logcontext "github.com/ekkolyth/ekko-os/packages/logging/go/context"
-)
-
-log := logger.New(logger.Options{Service: "api", Scope: "queue"})
-
-log.Info("queue drained", "count", 12, "duration_ms", 340)
-
-ctx := logcontext.With(context.Background(), "request_id", "req_123")
-log.InfoContext(ctx, "processing job")
-```
-
-### Core public API
-
-```ts
-export type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'silent'
-export type LogFormat = 'auto' | 'json' | 'pretty'
-export type LogAttributes = Record<string, unknown>
-export type LogOutput = (line: string) => void
-
-export interface LoggerOptions {
-    service?: string
-    scope?: string
-    level?: LogLevel
-    format?: LogFormat
-    colors?: 'auto' | boolean
-    output?: LogOutput
-    bindings?: LogAttributes
-    redact?: readonly string[]
-    onInternalError?: (error: unknown) => void
-}
-
-export interface Logger {
-    with(bindings: LogAttributes): Logger
-    enabled(level: Exclude<LogLevel, 'silent'>): boolean
-    debug(message: string, attributes?: LogAttributes): void
-    info(message: string, attributes?: LogAttributes): void
-    warn(message: string, attributes?: LogAttributes): void
-    error(message: string, attributes?: LogAttributes): void
-}
-
-export function createLogger(options?: LoggerOptions): Logger
-```
-
-`silent` is a threshold value, not an emission method — there is no
-`log.silent(...)`. `with` never mutates its parent; it returns an
-independent `Logger` that layers its own bindings on top. Every emission
-method takes the message first and an optional attributes object second;
-there is no attributes-first overload.
-
-```go
-type Level uint8
-
-const (
-    LevelDefault Level = iota
-    LevelDebug
-    LevelInfo
-    LevelWarn
-    LevelError
-    LevelSilent
-)
-
-type Format uint8
-
-const (
-    FormatAuto Format = iota
-    FormatJSON
-    FormatPretty
-)
-
-type ColorMode uint8
-
-const (
-    ColorsAuto ColorMode = iota
-    ColorsAlways
-    ColorsNever
-)
-
-type Options struct {
-    Service         string
-    Scope           string
-    Level           Level
-    Format          Format
-    Colors          ColorMode
-    Output          io.Writer
-    Bindings        []slog.Attr
-    Redact          []string
-    OnInternalError func(error)
-}
-
-func New(options Options) *slog.Logger
-func NewHandler(options Options) slog.Handler
-```
-
-`New` returns a real `*slog.Logger`, so `With`, `Enabled`, the level
-methods, and the `*Context` variants all behave exactly as the standard
-library documents them. `NewHandler` exists for composition — wrapping in
-another `slog.Handler`, or installing with `slog.SetDefault` — and
-implements `Enabled`, `Handle`, `WithAttrs`, and `WithGroup` correctly. A
-nil `Output` means `os.Stdout`.
-
-`slog.Logger` also exposes `Log` and `LogAttrs` at arbitrary numeric
-levels; the output contract still has four buckets. Anything below
-`slog.LevelInfo` renders as `debug`, `[Info, Warn)` as `info`, `[Warn,
-Error)` as `warn`, and `Error` and above as `error`. A custom numeric level
-never produces an output-level name outside those four.
-
-### Context public API
-
-```ts
-export function runWithContext<T>(
-    bindings: LogAttributes,
-    callback: () => T | Promise<T>,
-): T | Promise<T>
-
-export function currentContext(): Readonly<LogAttributes> | undefined
-```
-
-The Node/Bun implementation uses `AsyncLocalStorage`: bindings are copied,
-nested calls merge onto the parent, concurrent call stacks stay isolated,
-and the previous context is restored after the callback settles either way.
-A root `Logger` merges the active context into every record automatically
-— nothing has to read `currentContext()` by hand at each call site.
-
-The browser build exports the same two names, and each one throws a clear
-unsupported-runtime error instead of silently running the callback with no
-context. Browser code binds request-scoped data explicitly with
-`log.with(bindings)` instead.
-
-```go
-func With(ctx context.Context, attrs ...any) context.Context
-func Attrs(ctx context.Context) []slog.Attr
-```
-
-`With` uses `slog`'s own argument conversion, copies whatever bindings
-already exist on `ctx`, and returns a child context carrying the merge.
-`Attrs` returns a copy, never the stored slice. The root handler merges
-these bindings only into `*Context` calls (`InfoContext`, `ErrorContext`,
-…) — a plain `Info`/`Error` call passes no context and picks up nothing.
-
-The context module is a transport for arbitrary bindings. It has no
-opinion about HTTP, doesn't generate request IDs, and doesn't parse
-headers — that's §5's HTTP module. Correlation IDs are ordinary bindings as
-far as this module is concerned.
-
-### HTTP public API
-
-```ts
-type RequestHandler = (request: Request) => Response | Promise<Response>
-type FetchLike = (
-    input: RequestInfo | URL,
-    init?: RequestInit,
-) => Promise<Response>
-
-interface HandlerOptions {
-    sampleRate?: number
-    slowThresholdMs?: number
-    route?: (request: Request) => string | undefined
-    clientIp?: (request: Request) => string | undefined
-    exclude?: (request: Request) => boolean
-}
-
-interface FetchOptions {
-    provider?: string
-    sampleRate?: number
-    slowThresholdMs?: number
-}
-
-export function wrapHandler(
-    log: Logger,
-    handler: RequestHandler,
-    options?: HandlerOptions,
-): RequestHandler
-
-export function wrapFetch(
-    log: Logger,
-    fetch: FetchLike,
-    options?: FetchOptions,
-): FetchLike
-```
-
-`FetchLike` is a **structural** shape, not `typeof globalThis.fetch`
-verbatim — the ambient `fetch` type on some runtimes (Bun's included) also
-carries non-standard static members such as `fetch.preconnect`, which a
-plain function value passed in a test or a wrapped client doesn't have.
-Any real `fetch` implementation still satisfies the narrower shape used
-here.
-
-The browser build supports `wrapFetch` fully — it derives correlation from
-explicit request headers and from the bound attributes already on the
-`Logger` passed in, so it needs no ambient context. `wrapHandler` throws
-the same unsupported-runtime error as browser context, and it throws at
-wrap time rather than at request time: concurrent request context has no
-platform adapter in a browser, so there is no safe way to implement it
-there.
-
-```go
-type HandlerOptions struct {
-    SampleRate    float64
-    SlowThreshold time.Duration
-    Route         func(*http.Request) string
-    ClientIP      func(*http.Request) string
-    Exclude       func(*http.Request) bool
-}
-
-type TransportOptions struct {
-    Provider      string
-    SampleRate    float64
-    SlowThreshold time.Duration
-}
-
-func WrapHandler(
-    log *slog.Logger,
-    next http.Handler,
-    options HandlerOptions,
-) http.Handler
-
-func WrapTransport(
-    log *slog.Logger,
-    base http.RoundTripper,
-    options TransportOptions,
-) http.RoundTripper
-```
-
-A nil `log` uses `slog.Default()`; a nil `base` transport uses
-`http.DefaultTransport`. A zero `SampleRate` means the documented default
-of `1.0`; an explicit rate must fall within `(0, 1]`. A zero
-`SlowThreshold` means one second; a negative one is invalid. JavaScript
-uses `undefined` for the same two defaults and the same `(0, 1]` bound.
-
-`exclude`/`Exclude` only suppresses the completion record for that
-request — correlation, context binding, and the echoed request ID on the
-response all still apply. This is a generic policy hook: an application
-that only wants to exclude its own health-check route supplies that
-decision at boot rather than the package hardcoding a path prefix.
-
-## 6. Behavioral contracts
-
-### Records
-
-Every emitted line has this semantic shape:
-
-```json
-{
-    "time": "2026-08-21T14:32:18.417Z",
-    "level": "info",
-    "msg": "queue drained",
-    "service": "discord-bot",
-    "scope": "music",
-    "count": 12,
-    "duration_ms": 340
-}
-```
-
-- `time` is UTC RFC 3339 with millisecond precision.
-- `level` is lowercase `debug`, `info`, `warn`, or `error` — never `silent`.
-- `msg` is the caller's stable event description; variable data belongs in
-  attributes, not interpolated into the message.
-- `service` and `scope` appear only when non-empty.
-- `time`, `level`, and `msg` are package-owned and cannot be overridden by
-  a caller-supplied attribute of the same name.
-- Precedence, low to high: logger bindings, then active context, then
-  call-site attributes, then the three package-owned fields above.
-  Duplicate keys resolve last-write-wins under that ordering.
-- Canonical fields render first, in the order shown; remaining keys render
-  in ascending Unicode code-point order. Field order is not a semantic
-  guarantee, but it is deterministic — this is what makes byte-for-byte
-  pretty-output comparison between the two runtimes possible.
-- Ekko call sites use flat `snake_case` attribute names by repository
-  convention; the runtime itself preserves whatever keys a caller passes.
-- Every formatter writes exactly one physical line with one trailing
-  newline.
-
-Pretty output is the same record for a human:
+Entry points:
 
 ```text
-14:32:18.417 [discord-bot] [music] INFO  queue drained count=12 duration_ms=340
+@ekkolyth/logging            core: levels, records, redaction, formatting
+@ekkolyth/logging/context    request-scoped bindings
+@ekkolyth/logging/http       HTTP wrappers + correlation
 ```
 
-A missing `service` or `scope` drops its bracket rather than leaving an
-empty one. Levels are padded to five characters. The clock is UTC
-`HH:mm:ss.SSS`. A scalar renders bare only when it's safe to; anything
-empty, or containing whitespace, quotes, backslashes, or control
-characters, gets JSON-string-escaped instead — a literal newline or escape
-byte inside a value can never split the physical line or smuggle in an
-unowned ANSI sequence. Removing ANSI bytes from a colored line always
-yields the exact uncolored line; color decorates existing segments and
-never changes their content.
-
-### Safe normalization and limits
-
-No supported logging call fails because a value can't be represented:
-
-- `Date` (JavaScript) and `time.Time` (Go) normalize to UTC RFC 3339.
-- A `slog.LogValuer` resolves with panic recovery and the standard
-  100-step ceiling; a panic or an exhausted chain becomes
-  `[Unserializable]`.
-- `bigint` normalizes to a decimal string.
-- Non-finite floats normalize to the strings `NaN`, `Infinity`, or
-  `-Infinity`.
-- A cyclic reference normalizes to `[Circular]`.
-- Anything past a recursion depth of eight normalizes to `[MaxDepth]`.
-- Strings are capped at 16 KiB of UTF-8 and end in `[Truncated]` when cut,
-  never mid-way through a multi-byte sequence.
-- Arrays and slices keep their first 100 normalized entries and append a
-  `[Truncated: N items]` marker for the rest.
-- Objects and maps keep the first 100 keys, in the same deterministic
-  order as everything else, and add `_logging_truncated` with the omitted
-  count — a caller-supplied key of that exact name is overwritten by the
-  package's own truncation marker.
-- A throwing getter becomes `[Unserializable]` for that one property.
-- Functions, symbols, channels, complex numbers, unsafe pointers, and
-  other unrepresentable runtime values become `[Unsupported: type]`.
-
-These are fixed v1 safety limits, not public configuration.
-
-### Redaction
-
-Redaction runs recursively, after normalization and before formatting or
-output. Key matching lowercases and strips non-alphanumeric separators —
-`api_key`, `API-KEY`, and `apiKey` are the same key, while `token_count`
-does not match `token`. The non-disableable default set:
-
-```text
-password  passwd  secret  token  authorization  proxy_authorization
-cookie  set_cookie  api_key  access_token  refresh_token  private_key
-client_secret
-```
-
-`redact` adds exact keys under the same normalization; it can only extend
-the set, never remove from it. A matched value becomes `[REDACTED]`,
-including inside nested objects and structured errors. HTTP logging
-separately never collects bodies, query values, credentials embedded in a
-URL, authorization headers, or cookies in the first place — redaction is
-the second line of defense, not the only one. It does not scan an ordinary
-message string for secrets that were interpolated into it; keep variable
-data in attributes.
-
-### Errors
+## Quick start
 
 ```ts
-log.error('failed to fetch user', {
-    error,
-    operation: 'fetch_user',
-    user_id: userId,
-})
-```
-
-```go
-log.Error(
-    "failed to fetch user",
-    "error", err,
-    "operation", "fetch_user",
-    "user_id", userID,
-)
-```
-
-There is no required error class or interface. A native error normalizes
-to an object carrying `type` and `message` always, plus `code`, `stack`,
-a recursive `cause`, and `causes` (JavaScript `AggregateError`, Go
-`Unwrap() []error`) when present. JavaScript's `type` is the error's
-`name`, falling back to its constructor name; Go's `type` is
-`reflect.TypeOf(err).String()`. A non-error value passed on the `error`
-key still normalizes safely, carrying its runtime type and string form.
-Arbitrary enumerable properties on an error are not copied — put anything
-else worth keeping in an explicit attribute. `err` has no special meaning
-and is not a supported alias for `error`.
-
-The severity rule this package assumes:
-
-- An expected outcome is a value, logged at `info` or not at all.
-- A recoverable anomaly is `warn`.
-- An unexpected, actionable failure is `error`.
-- A catch that rethrows or wraps doesn't log at that site — the eventual
-  catch that actually handles it logs once, there.
-- A top-level boundary logs an otherwise-unhandled failure exactly once
-  before letting the platform's normal control flow continue (rethrow,
-  re-panic, or an unhandled-rejection handler).
-
-`operation`, `error_code`, and `retryable` are optional cross-runtime
-contextual attribute names. The logger never infers them and never changes
-severity based on them.
-
-### Internal logger failures
-
-A serialization, redaction, formatting, or output failure never replaces
-the application's own log call with an exception. The logger calls
-`onInternalError`/`OnInternalError` when one is configured; otherwise it
-makes one best-effort diagnostic write to `stderr`. That emergency write
-never passes back through a logger, so it cannot recurse. If the callback
-itself throws or panics, or the `stderr` write also fails, the logger
-recovers silently and gives up — an internal failure is never allowed to
-crash the caller.
-
-On the Go side, calling `Handle` directly also returns the underlying
-write error after the internal-error path has already run, so a caller
-that owns a raw `slog.Handler` can still see it. A call through
-`slog.Logger` keeps `slog`'s own behavior and does not surface that return
-value.
-
-Unknown enum values and invalid environment values are a different kind of
-failure — a configuration mistake, not a runtime one — and are reported
-immediately: JavaScript throws `TypeError` inside `createLogger`, Go
-panics inside `New`/`NewHandler` naming the bad setting.
+import { createLogger } from "@ekkolyth/logging";
+import { runWithContext } from "@ekkolyth/logging/context";
+import { wrapHandler } from "@ekkolyth/logging/http";
 
-### Configuration
+const log = createLogger({ service: "api", scope: "queue" });
 
-Both server runtimes resolve every setting in the same order:
+log.info("queue drained", { count: 12, duration_ms: 340 });
 
-```text
-explicit option → environment variable → runtime detection → package default
-```
-
-The only environment variables the package reads:
-
-| Variable | Effect |
-|---|---|
-| `LOG_LEVEL` | `debug` \| `info` \| `warn` \| `error` \| `silent` |
-| `LOG_FORMAT` | `auto` \| `json` \| `pretty` |
-| `NO_COLOR` | presence disables ANSI, unless `colors`/`Colors` is explicit |
-| `FORCE_COLOR` | any value other than `0` enables ANSI (`0` disables it), unless `colors`/`Colors` or `NO_COLOR` outranks it |
-
-`auto` format selects pretty output on a TTY and JSON otherwise. JSON never
-contains ANSI. `colors` changes only how pretty output is rendered; it
-never changes which format got selected. The browser build never reads
-`process.env` — `auto` there always means uncolored pretty output. A
-JavaScript output callback's return value is ignored, including a
-returned `Promise` — the output contract stays synchronous regardless.
-
-`LOG_JSON`, `LOG_COLORS`, `forceJson`, and `forceColors` do not exist on
-this package. There is no file-output option (`LOG_SOURCE`,
-`LOG_FILE_MAP`, or a Go `LogOutput` field) — the package owns `stdout` and
-whatever synchronous output a caller supplies, nothing else. An
-application that needs a file writes to it itself and passes an explicit
-output (JavaScript) or an `io.MultiWriter` (Go) — file lifecycle,
-permissions, rotation, and shutdown stay with the application that opened
-the file.
-
-### Correlation
-
-Inbound wrappers validate `traceparent` against W3C Trace Context and
-`X-Request-Id` as 1-128 ASCII characters from `[A-Za-z0-9._:-]`; anything
-invalid or absent is replaced. IDs are generated with Web Crypto in
-JavaScript and `crypto/rand` in Go — no UUID dependency either side.
-
-A valid incoming trace keeps its trace ID and flags and gets a fresh local
-span ID. With no valid trace, the wrapper mints a version `00` traceparent
-with a non-zero 16-byte trace ID, a non-zero 8-byte span ID, and flags
-`00`. A valid `tracestate` header is preserved unchanged. The active log
-context receives `request_id`, `trace_id`, and the local `span_id` so
-every log call inside the request picks them up automatically.
-
-The request ID is set on the Go request context before the handler runs,
-and echoed on every JavaScript response. An outbound wrapper injects
-`traceparent`, `tracestate`, and `X-Request-Id` only into headers the
-caller hasn't already set — an explicit header is never overwritten, and
-an explicit valid header seeds correlation ahead of ambient context. When
-neither an explicit header nor ambient context supplies correlation, the
-outbound wrapper mints a fresh root so sampling still has a stable
-identifier. Baggage propagation is out of scope for this version.
-
-This is propagation-grade correlation, not span recording — the package
-exports no tracer, no span type, and no telemetry backend.
-
-### Inbound and outbound HTTP records
-
-Every non-excluded inbound call emits one `request completed` record with
-`method`, `path` (query string excluded), an optional `route`, `status`,
-`duration_ms`, `response_size_bytes` when measurable, `request_id`,
-`trace_id`, `span_id`, an optional `ip`, an optional `user_agent`, and
-`error` on an unhandled failure. `response_size_bytes` is
-platform-conditional: Go always counts the bytes actually written, while
-JavaScript can only report it when the response carries a
-`content-length` header — the Fetch `Response` type gives no portable way
-to measure a streamed body otherwise. JavaScript has no portable
-client-IP API either, so `ip` is present only when a `clientIp` callback
-supplies it; Go defaults to `RemoteAddr` with its port stripped, falling
-back to the raw value if it can't be split.
-
-Level and volume:
-
-- An unhandled throw or panic is `error`, always emitted.
-- Status `>= 500` is `error`, always emitted.
-- Status `400`-`499` is `warn`, always emitted.
-- A fast-enough status below `400` that's still at or above the slow
-  threshold is `warn`, always emitted.
-- A fast, successful status is `info`, eligible for sampling.
-
-The wrapper catches an unhandled throw or panic only long enough to emit
-the completion record, then rethrows or re-panics the original value — it
-never chooses or writes an application response itself.
-
-Outbound calls follow the same shape under `outbound request completed`,
-with `provider`, `method`, `host`, and `path` in place of the inbound
-fields, and no request-body or query-string data ever collected either
-direction. Failures and slow calls are never sampled away on either side
-of the wire.
-
-`duration_ms` truncates to a whole millisecond rather than rounding — both
-runtimes: `Math.trunc(...)` in JavaScript, `time.Duration.Milliseconds()`
-in Go, which is itself an integer division.
-
-### Deterministic sampling
+await runWithContext({ request_id: "req_123" }, async () => {
+  log.info("processing job");
+});
 
-Sampling hashes the active trace ID (falling back to the request ID) with
-unsigned FNV-1a, 32-bit, over its UTF-8 bytes, and retains the record when
-`hash / 2^32 < sampleRate`. Both runtimes implement the identical
-algorithm, so the same identifier and rate make the identical keep/drop
-decision on either side. Every retained record below a rate of `1.0`
-carries the exact `sample_rate` that decided it. `warn` and `error`
-records are never sampled and never carry `sample_rate` — see the level
-table above. The generic default is `1.0`; a lower rate is always an
-explicit application choice.
-
-### Quiet window and `every`
-
-Two repeat-suppression tools sit alongside sampling:
-
-- **Handler quiet window.** Both `wrapHandler` and `WrapHandler` drop
-  repeat fast-2xx completion records that share `method|path|status`
-  inside a window — ten minutes by default. `warn`, `error`, and slow
-  records always emit. Disable with `quietWindowMs: 0` (JavaScript) or
-  `QuietWindowOff` (Go, whose zero value selects the default instead).
-- **`every`.** `log.every(window, ...keyParts)` in JavaScript returns a
-  rate-limited view of the logger that drops repeats of the same message
-  inside the window, keyed on service, scope, and the given parts; windows
-  accept `250ms`/`2s`/`10m`/`1h` strings or milliseconds. Go's equivalents
-  are `Every(window, keyParts...)` on the default logger, `EveryFor` on a
-  specific one, and the underlying `Throttler` for custom keys.
-
-Suppression trades data for silence — a dropped repeat takes its count and
-duration with it. Sampling with a stamped `sample_rate` is the
-reconstructable alternative; the quiet window exists because a dev
-terminal and a small log viewer are usually worth more than the lost
-repeats.
-
-## 7. Package-authoring blueprint
-
-This package is meant to be the template the next owned repository package
-follows, not a one-off. Before publishing a package this way, work through:
-
-1. **A generic core.** No consumer-specific vocabulary — service names,
-   route prefixes, feature flags — leaks into the public API.
-2. **Explicit exports.** Every public entry point is declared and
-   intentional; nothing is public because it happened to be reachable.
-3. **Shared cross-runtime semantics.** If the package spans more than one
-   language, both implementations agree on the same concepts, field names,
-   defaults, and failure behavior — see §3.
-4. **Intentional platform-native differences.** Where the runtimes
-   genuinely diverge, the divergence is a deliberate idiom choice, stated
-   in the README, not an accident of who wrote which side first.
-5. **Validated boundaries.** Bad configuration fails immediately and
-   loudly, at the boundary where it was supplied — not three calls later
-   as a confusing runtime symptom.
-6. **Defined failure behavior.** Every failure mode the package can hit —
-   not just the happy path — has a stated, tested outcome.
-7. **One canonical contract.** A single source of truth for cross-runtime
-   behavior (shared fixtures, a shared schema, or an IDL) that both
-   implementations are checked against, rather than each side's tests
-   asserting only against itself.
-8. **Generated-artifact drift checks.** Anything generated from the
-   canonical contract is checked in CI against that contract, so drift
-   fails the build instead of shipping quietly.
-9. **Packed-consumer tests.** The exact artifact that will be published —
-   not the workspace source — is installed into a clean consumer and
-   exercised before release.
-10. **A completed migration before public release.** Every existing
-    in-repository consumer is moved onto the new API first. A public
-    release ships with no compatibility shim and no repository code still
-    depending on the old shape.
-
-## 8. Development and release commands
-
-From `packages/logging/js`:
-
-```sh
-bun run build          # tsdown → dist/
-bun run test           # build, then run the bun:test suite against dist
-bun run typecheck      # tsc --noEmit
-bun run pack:public    # stage the public-only manifest + README + LICENSE, pack a tarball
-bun run pack:verify -- <stage-dir> <tarball>   # validate the tarball in a clean Node + Bun consumer
+const handler = wrapHandler(log, async () => new Response("ok"));
 ```
-
-`pack:public` prints two lines — the staged directory and the tarball
-path — which `pack:verify` takes as its two arguments. Validation installs
-the exact tarball into throwaway Node and Bun consumers, imports every
-entry point under both the normal and `browser` conditions, exercises one
-real log record, confirms the browser build's unsupported operations fail
-explicitly, and confirms every declared export target exists in the
-archive.
-
-From the repository root: `bun run --filter @ekkolyth/logging build` (or
-`test`, `typecheck`) runs the same scripts through the workspace's task
-runner.
-
-From `packages/logging/go`:
-
-```sh
-go test ./...          # the logging module's own suite
-go test -race ./...    # the same suite under the race detector
-```
-
-Releases go through Changesets: a changeset entry in `.changeset/`
-describes the version bump, merging to the default branch opens or updates
-a version PR, and merging that PR builds, tests, stages, and validates the
-package before it publishes. See the repository's release workflow for the
-exact gating — this README documents the package, not the pipeline.
-
-## 9. Compatibility and support
-
-- **Module format:** ESM only. There is no CommonJS build and none is
-  planned.
-- **Runtimes:** Node ≥20 and Bun for the server entry points; any browser
-  with the Fetch API (`Request`/`Response`) and Web Crypto
-  (`crypto.getRandomValues`) for the browser condition of every entry.
-- **Dependencies:** zero runtime dependencies. The published manifest
-  declares none, and the packed artifact is verified to contain none.
-- **Side effects:** `sideEffects: false` — safe to tree-shake.
-- **License:** MIT.
-- **First public version:** `0.1.0` — the redesigned engine described in
-  this README, published with no prior public version to remain
-  compatible with.
-- **What's out of scope for this package:** framework-specific middleware
-  (Express, Next.js, Hono, Chi, …), an OpenTelemetry SDK dependency or
-  exporter, global exception hooks or panic recovery that consumes the
-  panic, an async/buffered logging pipeline, and a public test-logger or
-  memory-sink package. A consumer that needs one of these builds it on top
-  of the seams this package already exposes — a custom `output`/`Output`,
-  or a wrapped `RequestHandler`/`http.Handler`.
-- **Go module:** the companion Go module shares this package's semantics
-  and its behavioral contract fixtures, but is not published — it lives in
-  this repository's source tree only, consumed by this repository's own
-  services through a local module `replace`.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@ekkolyth/logging",
-    "version": "0.1.0",
+    "version": "0.1.1",
     "description": "Zero-dependency structured logging for JavaScript and TypeScript, with context propagation and HTTP correlation.",
     "keywords": [
         "logging",