@namzu/sdk 27.0.0 → 28.0.0

package/src/utils/log/caps.ts

@@ -0,0 +1,118 @@
+// Cardinality and size caps, enforced once at the pipeline boundary — not
+// per sink, and not left to whichever sink happens to serialize the record.
+// A prose rule here would not survive the first attribute added under
+// deadline; these are type-and-code boundaries a caller cannot route around
+// by picking a different sink.
+//
+// Order matters and is fixed by createLogger: redact, THEN cap. Truncating
+// first could slice a secret in half and ship the surviving fragment: a
+// `[REDACTED:label]` placeholder is short and never needs truncating itself,
+// but half of a real key still leaks half a key.
+
+import type { LogRecord, MutableLogSinkCounters } from './types.js'
+
+export const MAX_ATTRIBUTES = 64
+export const MAX_VALUE_BYTES = 8 * 1024
+export const MAX_RECORD_BYTES = 16 * 1024
+
+/**
+ * At most 64 attributes. Excess keys are dropped in ascending key order —
+ * the same deterministic rule `capTotalSize` uses below, so a reader who has
+ * learned one learns both.
+ */
+export function capAttributeCount(record: LogRecord, counters: MutableLogSinkCounters): LogRecord {
+	const keys = Object.keys(record.attributes)
+	if (keys.length <= MAX_ATTRIBUTES) return record
+
+	const dropCount = keys.length - MAX_ATTRIBUTES
+	const dropped = new Set([...keys].sort().slice(0, dropCount))
+
+	const attributes: Record<string, unknown> = {}
+	for (const key of keys) {
+		if (!dropped.has(key)) attributes[key] = record.attributes[key]
+	}
+
+	counters.attributesDropped += dropCount
+	return { ...record, attributes }
+}
+
+/**
+ * Each string attribute value truncated at 8 KiB, tail replaced by
+ * `…[truncated N bytes]` inside the value — self-describing, so no extra
+ * flag field is minted for something the value already says about itself.
+ */
+export function truncateValues(record: LogRecord, counters: MutableLogSinkCounters): LogRecord {
+	let changed = false
+	const attributes: Record<string, unknown> = {}
+
+	for (const [key, value] of Object.entries(record.attributes)) {
+		if (typeof value !== 'string') {
+			attributes[key] = value
+			continue
+		}
+		const [text, wasTruncated] = truncateToByteLength(value, MAX_VALUE_BYTES)
+		attributes[key] = text
+		if (wasTruncated) {
+			changed = true
+			counters.valuesTruncated++
+		}
+	}
+
+	return changed ? { ...record, attributes } : record
+}
+
+function truncateToByteLength(value: string, maxBytes: number): [text: string, truncated: boolean] {
+	const totalBytes = Buffer.byteLength(value, 'utf8')
+	if (totalBytes <= maxBytes) return [value, false]
+
+	// Walk by Unicode codepoint, not UTF-16 code unit, so the cut point never
+	// lands inside a surrogate pair — splitting one produces an unpaired
+	// surrogate that some JSON readers choke on or silently mangle.
+	let kept = ''
+	let bytes = 0
+	for (const ch of value) {
+		const chBytes = Buffer.byteLength(ch, 'utf8')
+		if (bytes + chBytes > maxBytes) break
+		kept += ch
+		bytes += chBytes
+	}
+
+	const removedBytes = totalBytes - bytes
+	return [`${kept}…[truncated ${removedBytes} bytes]`, true]
+}
+
+/**
+ * Total serialized record ≤ 16 KiB. Per-value and per-count caps are
+ * independently satisfiable by a record with many small attributes, so this
+ * is the last line and measures the whole record, not one dimension of it.
+ * Attributes are dropped in ascending key order until it fits, and
+ * `namzu.log.truncated = true` is set on what remains — the marker a
+ * downstream reader needs to tell "this record is smaller than what was
+ * logged" from "this is genuinely all there was".
+ */
+export function capTotalSize(record: LogRecord, counters: MutableLogSinkCounters): LogRecord {
+	if (serializedByteLength(record) <= MAX_RECORD_BYTES) return record
+
+	const sortedKeys = Object.keys(record.attributes).sort()
+	for (let dropCount = 1; dropCount <= sortedKeys.length; dropCount++) {
+		const keptKeys = sortedKeys.slice(dropCount)
+		const attributes: Record<string, unknown> = {}
+		for (const key of keptKeys) attributes[key] = record.attributes[key]
+
+		const candidate: LogRecord = { ...record, attributes }
+		if (keptKeys.length === 0 || serializedByteLength(candidate) <= MAX_RECORD_BYTES) {
+			counters.recordsTruncated++
+			return { ...record, attributes: { ...attributes, 'namzu.log.truncated': true } }
+		}
+	}
+
+	// Unreachable: the final iteration of the loop above always has
+	// `keptKeys.length === 0` and returns from inside it. Kept as a typed
+	// fallback rather than a non-null assertion on the loop's last candidate.
+	counters.recordsTruncated++
+	return { ...record, attributes: { 'namzu.log.truncated': true } }
+}
+
+function serializedByteLength(record: LogRecord): number {
+	return Buffer.byteLength(JSON.stringify(record), 'utf8')
+}

package/src/utils/log/create-logger.ts

@@ -0,0 +1,198 @@
+// The pipeline: builds a record from a call, runs it through redaction and
+// the size caps, then dispatches to the configured sink — catching whatever
+// that sink does, because a host sink is arbitrary code the kernel does not
+// control.
+//
+// `createLogger` returns a plain `Logger` with one extra, non-Logger
+// property (`counters`) riding along on the same object. That is a
+// deliberate choice over a `{ logger, counters }` pair: the returned value
+// still satisfies `logger?: Logger` at every existing call site with no
+// unwrapping, while a caller that wants to observe the pipeline reads
+// `.counters` off the same reference. That caller is now real: LOG-06's
+// `logging.pipeline` doctor check. It could not have been while every
+// `getRootLogger()` built a logger with its own counters — see `shared`
+// below and `utils/__tests__/log-counters-are-process-wide.test.ts`.
+
+import { getActiveSpanContext } from '../../telemetry/runtime-accessors.js'
+import type { LogContext, Logger } from '../logger.js'
+import { capAttributeCount, capTotalSize, truncateValues } from './caps.js'
+import { errorAttributes } from './exception.js'
+import { redactRecord } from './redact.js'
+import { NOOP_SINK } from './sinks.js'
+import {
+	ERR_ATTRIBUTE,
+	EVENT_NAME_ATTRIBUTE,
+	type LevelFilter,
+	type LogRecord,
+	type LogSinkCounters,
+	type LoggerOptions,
+	type MutableLogSinkCounters,
+	SCOPE_ATTRIBUTE,
+	type Severity,
+} from './types.js'
+
+const SEVERITY_RANK: Record<Severity, number> = { debug: 0, info: 1, warn: 2, error: 3 }
+const LEVEL_RANK: Record<LevelFilter, number> = { ...SEVERITY_RANK, silent: 4 }
+const SEVERITY_NUMBER: Record<Severity, 5 | 9 | 13 | 17> = {
+	debug: 5,
+	info: 9,
+	warn: 13,
+	error: 17,
+}
+
+export type CreatedLogger = Logger & { readonly counters: LogSinkCounters }
+
+export function newCounters(): MutableLogSinkCounters {
+	return { dropped: 0, redacted: 0, attributesDropped: 0, valuesTruncated: 0, recordsTruncated: 0 }
+}
+
+/**
+ * `shared` lets several loggers write through ONE counter set.
+ *
+ * Without it the counters answer a question nobody asks. `getRootLogger()`
+ * resolves per call and builds a fresh logger each time, so every count it
+ * accumulated died with the expression that read it -- the five fields were
+ * incremented on every record in the process and read by nothing, which is
+ * `declared-but-undriven` with a comment above it promising `namzu doctor`
+ * would read them. `installProcessSink` now owns one set for the process,
+ * and that promise is discharged rather than deleted.
+ */
+export function createLogger(
+	options: LoggerOptions,
+	shared?: MutableLogSinkCounters,
+): CreatedLogger {
+	return build(options, shared ?? newCounters(), {})
+}
+
+function build(
+	options: LoggerOptions,
+	counters: MutableLogSinkCounters,
+	bound: Readonly<Record<string, unknown>>,
+): CreatedLogger {
+	function emit(severityText: Severity, body: string, data?: LogContext): void {
+		// Read per record, off the shared mutable holder — never resolved once
+		// and captured in this closure. Today's `Logger.child()` bakes its level
+		// in exactly that way, which is why three module-scope loggers in the
+		// skills/plugin loaders are frozen at `info` forever and unreachable by
+		// any later `configureLogger` call.
+		if (SEVERITY_RANK[severityText] < LEVEL_RANK[options.level.current]) return
+
+		const now = Date.now()
+		// Promote the two reserved keys before anything else touches
+		// `attributes` — redact/cap below only ever see the caller's real
+		// attributes, never the event name or the raw thrown value a second
+		// time under a second spelling. `err` maps through `errorAttributes`
+		// (bounded, cycle-safe cause walk — see ./exception.ts) rather than
+		// being copied verbatim: the whole point of the reserved key is that
+		// the THROWN VALUE reaches the mapper, not a string a call site
+		// already built with `toErrorMessage` and so already lost the stack
+		// and cause off of.
+		const merged: Record<string, unknown> = { ...bound, ...data }
+		const { [EVENT_NAME_ATTRIBUTE]: rawEventName, [ERR_ATTRIBUTE]: rawErr, ...attributes } = merged
+		// Computed here, before redact/cap run, so `exception.stacktrace` gets
+		// exactly the same treatment as an attribute any call site set by
+		// hand — see the redaction-pipeline test planting a secret inside a
+		// NESTED cause's message specifically to pin this ordering. `rawErr`
+		// wins over a same-named `exception.*` key set by hand: once a call
+		// site hands over the real thrown value, that value is the
+		// authoritative source, not whatever text a caller pre-computed
+		// before this reserved key existed.
+		const attributesWithException =
+			rawErr !== undefined ? { ...attributes, ...errorAttributes(rawErr) } : attributes
+		// Resolved HERE, at emit time, off the live `@opentelemetry/api` global —
+		// never once at `createLogger` construction and captured in this
+		// closure. `telemetry/metrics.ts` documents the construction-time
+		// version of this mistake already happening once, for a meter: a bag
+		// that captured the no-op instance at construction stayed no-op for the
+		// rest of the process even after a real one registered later.
+		// `undefined` with no telemetry configured — see `getActiveSpanContext`'s
+		// own doc for why that is the default, not a case this file detects.
+		const spanContext = getActiveSpanContext()
+		let record: LogRecord = {
+			timestamp: now,
+			observedTimestamp: now,
+			severityNumber: SEVERITY_NUMBER[severityText],
+			severityText,
+			body,
+			scope: { name: options.scope },
+			resource: options.resource,
+			attributes: attributesWithException,
+			...(typeof rawEventName === 'string' ? { eventName: rawEventName } : {}),
+			// All three or none: a trace id with no span id would be a
+			// half-address (see `LogRecord.traceId`'s doc).
+			...(spanContext
+				? {
+						traceId: spanContext.traceId,
+						spanId: spanContext.spanId,
+						traceFlags: spanContext.traceFlags,
+					}
+				: {}),
+		}
+
+		// Order matters: redact BEFORE capping. Truncating a value first could
+		// slice a secret in half and ship the surviving fragment; the
+		// `[REDACTED:label]` placeholder redaction leaves behind is short and
+		// never needs truncating itself.
+		record = redactRecord(record, counters)
+		record = capAttributeCount(record, counters)
+		record = truncateValues(record, counters)
+		record = capTotalSize(record, counters)
+
+		dispatch(record)
+	}
+
+	function dispatch(record: LogRecord): void {
+		if (options.sink === NOOP_SINK) {
+			counters.dropped++
+			return
+		}
+		try {
+			options.sink.emit(record)
+		} catch {
+			// A host sink is arbitrary code the kernel does not control. The old
+			// direct `process.stderr.write` implementation could never throw into
+			// an in-flight run; a naive seam here would introduce that failure
+			// mode for the first time — a broken sink aborting, say, a
+			// tool-completion path. Never rethrown, never logged through the same
+			// sink that just failed — counted instead, so a doctor check can
+			// surface a sink that is silently eating every record.
+			counters.dropped++
+		}
+	}
+
+	return {
+		debug: (message, data) => emit('debug', message, data),
+		info: (message, data) => emit('info', message, data),
+		warn: (message, data) => emit('warn', message, data),
+		error: (message, data) => emit('error', message, data),
+		child: (context) => {
+			// The one context key that changes a PROPERTY OF THE LOGGER
+			// (`options.scope`) rather than joining `bound` as an ordinary
+			// attribute — see `SCOPE_ATTRIBUTE`'s own doc comment in `./types.js`.
+			// Stripped out of `rest` before merging, for the same reason
+			// `EVENT_NAME_ATTRIBUTE` is stripped out of `attributes` above: an
+			// attribute and a property carrying the same value would be the same
+			// name spelled two ways in one record.
+			const { [SCOPE_ATTRIBUTE]: scopeOverride, ...rest } = context
+			const nextOptions =
+				typeof scopeOverride === 'string' ? { ...options, scope: scopeOverride } : options
+			return build(nextOptions, counters, { ...bound, ...rest })
+		},
+		counters,
+	}
+}
+
+/**
+ * A logger that discards everything, countably. Every call is accepted (the
+ * level is `debug`, the widest threshold), and every accepted call is routed
+ * to `NOOP_SINK` and counted as dropped — a host holding `NOOP_LOGGER` can
+ * still tell "N calls happened and were discarded" from "N calls never
+ * happened", which a logger that filtered everything out at `silent` could
+ * not: a filtered call never reaches dispatch and is never counted at all.
+ */
+export const NOOP_LOGGER: CreatedLogger = createLogger({
+	sink: NOOP_SINK,
+	level: { current: 'debug' },
+	resource: { 'service.name': '@namzu/sdk' },
+	scope: 'namzu.noop',
+})

package/src/utils/log/exception.ts

@@ -0,0 +1,124 @@
+// Maps a thrown value to the exception.* attributes the OTel Logs Data
+// Model reserves for it — exception.type / exception.message /
+// exception.stacktrace — walking a `cause` chain the way a terminal
+// `console.error` would: newest frame first, oldest cause last.
+//
+// Two things this file deliberately does NOT do:
+//
+//  - It does not redact anything itself. `redactRecord` (../log/redact.ts)
+//    runs over every attribute value unconditionally, once, at the record
+//    boundary — stack text included. A second scan here would be a second
+//    place to keep LOG_SECRET_PATTERNS in sync with, and the whole point of
+//    a record-boundary scan is that nothing gets to opt out of it by
+//    running earlier.
+//  - It does not license re-attaching `cause` where it was deliberately
+//    dropped. `provider/errors.ts` refuses to keep one on a classified
+//    provider error on purpose — a vendor SDK's error message (and so its
+//    own `cause`, when the vendor wraps a transport error) can carry a
+//    credential the upstream echoed back, and "a `cause` survives every
+//    logger that serializes an error chain" is exactly the property this
+//    file exists to provide. Being able to walk a `cause` safely is not the
+//    same claim as every `cause` being safe to attach in the first place;
+//    see that file's own doc comment and docs/conventions/index.md.
+
+import type { LogAttributes } from './attributes.js'
+
+/**
+ * How many `cause` hops past the thrown value itself get folded into
+ * `exception.stacktrace`. Four, not "as many as there are": an ordinary
+ * retry-then-fallback call stack in this codebase is a handful of layers
+ * deep, but nothing stops a caller from building a cause chain as long as
+ * it likes, and walking all of it turns one log call into an unbounded
+ * string build ahead of the 8 KiB per-value cap (caps.ts) that would
+ * otherwise be the only thing catching it. The bound is enforced here,
+ * explicitly, rather than left to that cap truncating mid-frame with no
+ * indication anything was cut.
+ */
+const DEFAULT_CAUSE_DEPTH = 4
+
+/** What a thrown non-`Error` still needs a name for. */
+const UNKNOWN_EXCEPTION_TYPE = 'UnknownError'
+
+/**
+ * `exception.type` / `exception.message` / `exception.stacktrace` for a
+ * thrown value. `causeDepth` overrides the default bound above — exposed
+ * for tests, not because a production call site should ordinarily need a
+ * different one.
+ */
+export function errorAttributes(
+	err: unknown,
+	opts?: { readonly causeDepth?: number },
+): LogAttributes {
+	const maxDepth = opts?.causeDepth ?? DEFAULT_CAUSE_DEPTH
+	const { type, message } = describe(err)
+	return {
+		'exception.type': type,
+		'exception.message': message,
+		'exception.stacktrace': buildStacktrace(err, maxDepth),
+	}
+}
+
+function describe(value: unknown): { type: string; message: string } {
+	if (value instanceof Error) {
+		return { type: value.name || UNKNOWN_EXCEPTION_TYPE, message: value.message }
+	}
+	if (typeof value === 'object' && value !== null) {
+		return { type: UNKNOWN_EXCEPTION_TYPE, message: safeStringify(value) }
+	}
+	return { type: UNKNOWN_EXCEPTION_TYPE, message: String(value) }
+}
+
+function safeStringify(value: object): string {
+	try {
+		return JSON.stringify(value)
+	} catch {
+		// A circular non-Error thrown value. `String()` on a plain object gives
+		// '[object Object]' — unhelpful, but the one thing this function must
+		// never do is itself throw from inside a logging call.
+		return String(value)
+	}
+}
+
+/**
+ * `err`'s own stack (or a `type: message` line when there is none) followed
+ * by each `.cause`'s, newest first, bounded by `maxDepth` hops. Stops early
+ * — WITH a note saying so, per refuse-do-not-degrade — on a cycle or on
+ * reaching the bound with more chain left to walk. Never loops: every value
+ * this function visits is added to `seen` before the value after it is even
+ * read, so a self-referencing `cause` is caught on the very next hop rather
+ * than by exhausting the depth bound.
+ */
+function buildStacktrace(err: unknown, maxDepth: number): string {
+	const seen = new Set<unknown>([err])
+	const frames: string[] = [frameText(err)]
+
+	let cursor: unknown = err instanceof Error ? err.cause : undefined
+	let depth = 0
+
+	while (cursor !== undefined && cursor !== null) {
+		if (seen.has(cursor)) {
+			frames.push(`Caused by: [cause chain cycle detected at depth ${depth + 1} — stopped]`)
+			return frames.join('\n')
+		}
+		if (depth >= maxDepth) {
+			frames.push(
+				`Caused by: [cause chain truncated at depth ${maxDepth} — deeper causes not walked]`,
+			)
+			return frames.join('\n')
+		}
+
+		seen.add(cursor)
+		frames.push(`Caused by: ${frameText(cursor)}`)
+		depth++
+		cursor = cursor instanceof Error ? cursor.cause : undefined
+	}
+
+	return frames.join('\n')
+}
+
+function frameText(value: unknown): string {
+	if (value instanceof Error) {
+		return value.stack ?? `${value.name || UNKNOWN_EXCEPTION_TYPE}: ${value.message}`
+	}
+	return String(value)
+}

package/src/utils/log/index.ts

@@ -0,0 +1,24 @@
+// The LogSink seam. `../logger.ts` keeps `Logger`, `LogContext`,
+// `getRootLogger` and `configureLogger` completely unchanged (now
+// `@deprecated`) — this directory is the additive replacement described in
+// docs/conventions and the observability docs page once those land.
+
+export type {
+	LevelFilter,
+	LogRecord,
+	LogSink,
+	LogSinkCounters,
+	Resource,
+	Severity,
+} from './types.js'
+export type { LogAttributes } from './attributes.js'
+export { createLogger, NOOP_LOGGER } from './create-logger.js'
+export { installProcessSink } from './process-sink.js'
+export { jsonLinesSink, NOOP_SINK, prettySink } from './sinks.js'
+// A value export, not a type — sits beside the type re-exports above rather
+// than folded into that block, because `export type { ... }` cannot carry a
+// runtime const. `EVENT_NAME_ATTRIBUTE` is how a host OUTSIDE this package
+// (the CLI's boot narrative, NZ-BOOT-05) names an event without duplicating
+// the reserved key `createLogger` promotes off of — see the doc comment on
+// the constant itself in `./types.js`.
+export { EVENT_NAME_ATTRIBUTE, SCOPE_ATTRIBUTE } from './types.js'

package/src/utils/log/process-sink.ts

@@ -0,0 +1,76 @@
+// The replacement for `configureLogger`'s "one process, one global" model —
+// still one process-wide destination (a CLI genuinely owns the whole
+// process), but a destination, not only a threshold: `configureLogger` could
+// only raise or lower a level against a fixed `process.stderr.write`.
+//
+// `getRootLogger` reads this: when a sink is installed, the deprecated
+// accessor routes through it instead of writing straight to stderr. That
+// bridge is what makes the seam reachable without rewriting the ~39 existing
+// `getRootLogger()` call sites in one commit — they keep the old shape and
+// gain the new destination.
+
+import { newCounters } from './create-logger.js'
+import type { LevelFilter, LogSink, LogSinkCounters, MutableLogSinkCounters } from './types.js'
+
+interface InstalledSink {
+	readonly sink: LogSink
+	readonly level: LevelFilter
+	readonly counters: MutableLogSinkCounters
+}
+
+let _processSink: InstalledSink | undefined
+
+export function installProcessSink(
+	sink: LogSink,
+	level: LevelFilter,
+	opts: { readonly replace?: boolean } = {},
+): void {
+	if (_processSink !== undefined && !opts.replace) {
+		// `refuse-do-not-degrade`: two callers each believing they own the
+		// process's log destination is a defect, not something to merge
+		// silently — the second install wins with neither party told, and
+		// whichever caller configured the first one loses its destination
+		// without an error anywhere in the tree.
+		throw new Error(
+			'installProcessSink was already called for this process. Two callers each believing ' +
+				"they own the process's log destination is a defect, not something to merge silently " +
+				'— pass { replace: true } if this call is a deliberate replacement of an earlier one.',
+		)
+	}
+	// One counter set per installed destination, so every logger that
+	// routes through it adds to the same totals. A `replace: true` install
+	// starts fresh: the counts describe the destination that is live, and
+	// carrying the old one's forward would attribute its drops to a sink
+	// that never saw those records.
+	_processSink = { sink, level, counters: newCounters() }
+}
+
+/** The installed destination, or `undefined` when nobody claimed the process. */
+export function getProcessSink():
+	| { readonly sink: LogSink; readonly level: LevelFilter; readonly counters: LogSinkCounters }
+	| undefined {
+	return _processSink
+}
+
+/**
+ * The mutable counter set the installed destination writes through.
+ *
+ * Internal: a reader wants {@link getProcessSink}'s readonly view. This
+ * exists so `getRootLogger`'s bridge can hand the SAME object to every
+ * logger it builds, which is what makes the totals process-wide rather
+ * than per-call.
+ */
+export function getProcessSinkCounters(): MutableLogSinkCounters | undefined {
+	return _processSink?.counters
+}
+
+/**
+ * Test-only: forget the installed sink.
+ *
+ * Production must never call this — the refusal above is the whole contract,
+ * and a reset that production could reach would let a second caller take the
+ * destination by clearing the first one rather than by saying `replace`.
+ */
+export function __resetProcessSinkForTests(): void {
+	_processSink = undefined
+}

package/src/utils/log/redact.ts

@@ -0,0 +1,77 @@
+// Scrubs anything secret-shaped out of a record before any sink sees it.
+//
+// Runs once, in the pipeline, ahead of sink dispatch — not inside
+// jsonLinesSink, and not inside any other individual sink. A scan that only
+// jsonLinesSink ran would leave prettySink (the one `namzu run` actually
+// uses) and every host-supplied sink with no second layer at all, which is
+// the gap a scoped-to-one-sink design would reintroduce: the machine-read
+// path would be the only protected one.
+//
+// This is defence in depth, not the guarantee — the primary control is the
+// output guardrail upstream (`runtime/query/guardrail-presets.ts`) and the
+// allowlist that keeps untrusted text out of attribute values in the first
+// place. A match here means that allowlist already had a hole.
+
+import { LOG_SECRET_PATTERNS } from '../../constants/secret-patterns.js'
+import type { LogRecord, MutableLogSinkCounters } from './types.js'
+
+export function redactRecord(record: LogRecord, counters: MutableLogSinkCounters): LogRecord {
+	const body = redactString(record.body)
+	const attributes = redactAttributes(record.attributes)
+
+	if (body === record.body && attributes === record.attributes) return record
+
+	counters.redacted++
+	return { ...record, body, attributes }
+}
+
+function redactString(text: string): string {
+	let out = text
+	for (const [label, pattern] of LOG_SECRET_PATTERNS) {
+		// Fresh lastIndex: these are module-level /g regexes, reused across
+		// every record — the same caution guardrail-presets.ts already takes
+		// on the same table.
+		pattern.lastIndex = 0
+		if (!pattern.test(out)) continue
+		pattern.lastIndex = 0
+		out = out.replace(pattern, `[REDACTED:${label}]`)
+	}
+	return out
+}
+
+function redactAttributes(
+	attributes: Readonly<Record<string, unknown>>,
+): Readonly<Record<string, unknown>> {
+	let changed = false
+	const next: Record<string, unknown> = {}
+	for (const [key, value] of Object.entries(attributes)) {
+		const redacted = redactValue(value)
+		if (redacted !== value) changed = true
+		next[key] = redacted
+	}
+	return changed ? next : attributes
+}
+
+// Strings and arrays of primitives are the shapes `LogAttributes` will
+// eventually restrict values to (a later increment); anything else passes
+// through untouched rather than being stringified, which would be a second,
+// unrelated way for structured data to leak.
+function redactValue(value: unknown): unknown {
+	if (typeof value === 'string') return redactString(value)
+
+	if (Array.isArray(value)) {
+		let changed = false
+		const next = value.map((entry) => {
+			const redacted = redactValue(entry)
+			if (redacted !== entry) changed = true
+			return redacted
+		})
+		// Only allocate a new array when something inside it actually changed —
+		// `.map()` always returns a fresh array, and comparing that fresh
+		// array's reference against the input would mark every array-valued
+		// attribute "redacted" whether or not a pattern ever matched.
+		return changed ? next : value
+	}
+
+	return value
+}