@namzu/sdk 27.0.0 → 28.0.0

package/src/utils/log/sinks.ts

@@ -0,0 +1,205 @@
+// Built-in sinks. All three receive already-redacted, already-capped
+// records — see redact.ts and caps.ts — so nothing here re-implements
+// either concern; a sink's only job is to render.
+
+import { applyTemplate, columnLabel, scopeColour } from './templates.js'
+import type { LogRecord, LogSink } from './types.js'
+
+/**
+ * Delivers nothing, by construction. `createLogger`'s dispatch identity-
+ * checks the configured sink against this exact reference and counts the
+ * record as dropped rather than calling `emit` — a no-op `emit` and a real
+ * delivery both return `undefined`, so without the identity check nothing
+ * downstream could ever tell "configured to discard" from "silently eating
+ * every record".
+ */
+export const NOOP_SINK: LogSink = {
+	emit() {},
+}
+
+/**
+ * One JSON object per line — the canonical wire format for the machine-read
+ * path (`namzu run-stream`'s stderr). JSON string-escaping neutralises
+ * `\n`/`\r` by construction, closing the log-forging surface without a
+ * single character-stripping call site, which is bypassable anyway.
+ *
+ * `JSON.stringify` leaves U+2028 and U+2029 literal in its output, and some
+ * readers — older V8, some log shippers — treat either codepoint as a line
+ * terminator regardless of the JSON quoting around it. Escaped here so a
+ * record can never masquerade as two lines to a reader that split on them.
+ */
+export function jsonLinesSink(stream: NodeJS.WritableStream): LogSink {
+	return {
+		emit(record: LogRecord) {
+			// U+2028/U+2029 built via fromCharCode rather than a \u escape in a
+			// regex literal — either escape, typed directly, risks becoming the raw
+			// codepoint again instead of the six characters of escape text; a raw
+			// U+2028/U+2029 inside a regex literal is a LineTerminator to the JS
+			// parser itself and fails to compile.
+			const lineSeparator = String.fromCharCode(0x2028)
+			const paragraphSeparator = String.fromCharCode(0x2029)
+			const line = JSON.stringify(record)
+				.split(lineSeparator)
+				.join('\\u2028')
+				.split(paragraphSeparator)
+				.join('\\u2029')
+			stream.write(`${line}\n`)
+		},
+	}
+}
+
+const SEVERITY_LABEL: Record<LogRecord['severityText'], string> = {
+	debug: 'DEBUG',
+	info: 'INFO',
+	warn: 'WARN',
+	error: 'ERROR',
+}
+
+// Every C0 control byte (0x00-0x1F) and DEL (0x7F) becomes its `\xNN`
+// form — ESC included, so a full ANSI CSI/OSC sequence survives as inert,
+// readable text (`\x1b[31m`) rather than as live bytes a terminal would
+// act on. Deleting the escape byte outright was the first draft of this
+// function and is worse: it silently drops information (nothing in the
+// output says an escape sequence was even there) for no extra safety
+// over converting it to text, since every OTHER control byte already gets
+// the same visible treatment.
+// `body` and `scope` reach this renderer as plain strings with no upstream
+// guarantee yet that either is a constant (that lands with the CI gate in
+// later work) — a remote MCP server that names itself an escape sequence
+// erasing the previous line and printing a fake refusal is a real forging
+// attempt against the terminal `namzu run` writes to today, not a
+// hypothetical one.
+// biome-ignore lint/suspicious/noControlCharactersInRegex: this pattern IS the control-character filter — the escapes below are ASCII text (`\x00`-`\x1F`, `\x7F`), not raw bytes pasted into the source.
+const CONTROL_BYTE = /[\x00-\x1F\x7F]/g
+
+// U+2028 (LINE SEPARATOR) and U+2029 (PARAGRAPH SEPARATOR) are not ASCII
+// control bytes, so CONTROL_BYTE above never matches either — but both are
+// LineTerminator characters to a reader that splits on them, the exact gap
+// jsonLinesSink above documents and closes for its own NDJSON output.
+// `JSON.stringify` does not escape either codepoint, so the attribute half
+// of a record — which reaches this file as already-serialized JSON text,
+// below — can still carry either straight through unescaped. Built via
+// `fromCharCode` and plain `.split()/.join()` rather than a backslash-u
+// escape in a regex literal, for the same reason jsonLinesSink's own
+// separators are: typed directly, either escape risks becoming the raw
+// codepoint again instead of the six characters of escape text, and a raw
+// instance of either inside a regex literal is a LineTerminator to the JS
+// parser itself and fails to compile.
+const LINE_SEPARATOR = String.fromCharCode(0x2028)
+const PARAGRAPH_SEPARATOR = String.fromCharCode(0x2029)
+
+function escapeForDisplay(text: string): string {
+	return text
+		.replace(CONTROL_BYTE, (byte) => `\\x${byte.charCodeAt(0).toString(16).padStart(2, '0')}`)
+		.split(LINE_SEPARATOR)
+		.join('\\u2028')
+		.split(PARAGRAPH_SEPARATOR)
+		.join('\\u2029')
+}
+
+/** Column width for the scope label. Long labels overflow rather than truncate. */
+const SCOPE_WIDTH = 12
+
+/**
+ * The marker between the scope column and the body.
+ *
+ * A glyph rather than a `[WARN]` label, because at `info` the overwhelming
+ * majority of boot lines are ordinary and a label on each one is the wall
+ * this renderer exists to remove. The two that are not ordinary have to be
+ * findable by eye in a column, which a bracketed word at variable position
+ * is not.
+ */
+const MARKER: Record<LogRecord['severityText'], string> = {
+	debug: ' ',
+	info: ' ',
+	warn: '!',
+	error: '✗',
+}
+
+/** `+Nms`, left-padded so the numbers line up in a column. */
+function elapsedColumn(deltaMs: number): string {
+	return `+${deltaMs}ms`.padStart(7)
+}
+
+/**
+ * Human-readable line, one record per line — the boot narrative's renderer.
+ *
+ * Three things it does that a generic sink does not, each answering a
+ * specific half of "the logs tell me nothing":
+ *
+ * - **`+Nms` instead of an absolute timestamp.** Elapsed since the previous
+ *   record ON THIS SINK, so the column reads as which phase was slow. The
+ *   state is a closure variable rather than module-level: two sinks in one
+ *   process each measure their own stream, and a shared `lastTimestamp`
+ *   would make each one's deltas depend on the other's traffic.
+ * - **A fixed-width scope column, coloured by a stable hash.** A dozen
+ *   module initialisations read as structure rather than scroll.
+ * - **A template per boot event**, so `info` shows the two attributes that
+ *   matter rather than all forty as JSON.
+ *
+ * Colour is emitted only when the stream reports `isTTY`, so a redirected
+ * log has no escape bytes in it at all.
+ */
+export function prettySink(stream: NodeJS.WritableStream): LogSink {
+	// Per-instance, deliberately. See the note above.
+	let previousTimestamp: number | undefined
+
+	// Read once. A stream does not become a TTY part-way through a process,
+	// and re-reading per record would let a mid-run reassignment change the
+	// shape of a file somebody is already tailing.
+	const colour = (stream as NodeJS.WriteStream).isTTY === true
+
+	return {
+		emit(record: LogRecord) {
+			// Seeded from the FIRST record rather than from sink construction,
+			// so the first line is `+0ms` and not however long the process
+			// spent before anything was logged — which is not a phase anybody
+			// can act on.
+			const delta = previousTimestamp === undefined ? 0 : record.timestamp - previousTimestamp
+			previousTimestamp = record.timestamp
+
+			const label = escapeForDisplay(columnLabel(record))
+			const templated = applyTemplate(record)
+			const marker = MARKER[record.severityText]
+
+			if (templated !== undefined) {
+				const painted = colour ? `\x1b[${scopeColour(label)}m${label}\x1b[0m` : label
+				// Padding is computed from the UNPAINTED label: the escape
+				// bytes have no width on screen but do have length in a string,
+				// so padding the painted form shortens every coloured column by
+				// exactly the length of its escape sequence.
+				const pad = ' '.repeat(Math.max(1, SCOPE_WIDTH - label.length))
+				stream.write(
+					`  ${elapsedColumn(delta)}  ${painted}${pad}${marker} ${escapeForDisplay(templated)}\n`,
+				)
+				return
+			}
+
+			// Everything that is not a boot event keeps the original shape.
+			// A record from a foreign vocabulary has no template to be right
+			// about, and inventing a column layout for it would drop the
+			// attributes it does carry.
+			const timestamp = new Date(record.timestamp).toISOString()
+			const level = SEVERITY_LABEL[record.severityText]
+			const scope = escapeForDisplay(record.scope.name)
+			const body = escapeForDisplay(record.body)
+
+			// JSON.stringify turns every ASCII control byte 0x00-0x1F — ESC
+			// included — into literal `\uXXXX` text inside each attribute value,
+			// but it does not touch DEL (0x7F) or U+2028/U+2029: none of the
+			// three are in JSON's mandatory escape set, so all three used to
+			// reach this stream exactly as JSON.stringify left them — DEL as a
+			// raw byte, U+2028/U+2029 as raw codepoints — the same gap
+			// jsonLinesSink already closed on its own path, just left open
+			// here. Running escapeForDisplay over the already-serialized JSON
+			// text closes it: every OTHER control byte JSON.stringify already
+			// turned into backslash text has no raw byte left for the regex to
+			// match, so this only ever touches the three it left behind.
+			const attributeKeys = Object.keys(record.attributes)
+			const attributes =
+				attributeKeys.length > 0 ? ` ${escapeForDisplay(JSON.stringify(record.attributes))}` : ''
+
+			stream.write(`[${timestamp}] [${level}] [${scope}] ${body}${attributes}\n`)
+		},
+	}
+}

package/src/utils/log/templates.ts

@@ -0,0 +1,161 @@
+import { BOOT_EVENT_NAMES, type BootEventName } from '../../constants/telemetry/index.js'
+import type { LogRecord } from './types.js'
+
+/**
+ * How a boot record is turned into one readable line.
+ *
+ * The complaint this exists to answer is that the logs say nothing when the
+ * project starts. A record already carries everything — the problem is the
+ * shape it arrives in: an absolute ISO timestamp nobody can subtract in
+ * their head, and every attribute dumped as JSON, so the two facts that
+ * matter sit inside forty that do not.
+ *
+ * Two things fix most of it, and neither is a freebie of a generic sink.
+ * The `+Nms` column turns a wall of timestamps into a readout of which
+ * phase was slow. And a template per event decides which attributes are
+ * worth a line at `info`, instead of printing all of them.
+ *
+ * **Display only.** Nothing here may mutate a record, and no machine-read
+ * path sees any of it — `jsonLinesSink` renders the same records
+ * byte-identically whether or not this file is loaded.
+ */
+
+/**
+ * A template returns the text after the marker, or `undefined` to fall
+ * through to the default rendering.
+ *
+ * It receives the record rather than just the attributes because several
+ * lines are the body with two attributes appended, and re-deriving the body
+ * from attributes would let the rendered line disagree with what the
+ * emitter actually said.
+ */
+export type BootTemplate = (record: LogRecord) => string | undefined
+
+function attr(record: LogRecord, key: string): string | undefined {
+	const value = record.attributes[key]
+	if (value === undefined || value === null) return undefined
+	return typeof value === 'string' ? value : JSON.stringify(value)
+}
+
+/** `a · b · c`, skipping anything absent, or `undefined` if all are. */
+function joined(parts: (string | undefined)[]): string | undefined {
+	const kept = parts.filter((p): p is string => p !== undefined && p !== '')
+	return kept.length > 0 ? kept.join(' · ') : undefined
+}
+
+/** The body, with a `key=value` tail for the named attributes that exist. */
+function bodyWith(record: LogRecord, keys: string[]): string {
+	const tail = keys
+		.map((key) => {
+			const value = attr(record, key)
+			return value === undefined ? undefined : `${shortKey(key)}=${value}`
+		})
+		.filter((p): p is string => p !== undefined)
+	return tail.length > 0 ? `${record.body}  ${tail.join(' ')}` : record.body
+}
+
+/** `namzu.config.key.count` reads as `count` in a column already labelled `config`. */
+function shortKey(key: string): string {
+	const parts = key.split('.')
+	return parts[parts.length - 1] ?? key
+}
+
+/**
+ * One template per boot event, as a TOTAL map over the union.
+ *
+ * `Record<BootEventName, …>` rather than `Partial<…>` on purpose: adding a
+ * member to `BOOT_EVENT_NAMES` then fails to compile here until somebody
+ * decides how it should read. A partial map would let a new event silently
+ * fall through to the default dump, which is the exact outcome this file
+ * exists to prevent — and nothing would fail.
+ */
+export const BOOT_TEMPLATES: Record<BootEventName, BootTemplate> = {
+	[BOOT_EVENT_NAMES.BOOT_START]: (r) => bodyWith(r, ['namzu.boot.cwd', 'namzu.boot.argv']),
+	[BOOT_EVENT_NAMES.CONFIG_RESOLVED]: (r) =>
+		joined([r.body, attr(r, 'namzu.config.key.count'), attr(r, 'namzu.config.sources')]),
+	[BOOT_EVENT_NAMES.SANDBOX_RESOLVED]: (r) =>
+		bodyWith(r, ['namzu.sandbox.backend', 'namzu.sandbox.enforces']),
+	[BOOT_EVENT_NAMES.PROVIDER_RESOLVED]: (r) =>
+		bodyWith(r, ['namzu.provider.chain', 'namzu.provider.constructed']),
+	[BOOT_EVENT_NAMES.CAPABILITY_DETECTED]: (r) => bodyWith(r, ['namzu.capability.name']),
+	[BOOT_EVENT_NAMES.CAPABILITY_BROKEN]: (r) =>
+		bodyWith(r, ['namzu.capability.name', 'namzu.capability.reason']),
+	[BOOT_EVENT_NAMES.TELEMETRY_STATUS]: (r) => r.body,
+	// `kind`, not `root`. This asked for `namzu.migration.root`, which NOTHING
+	// has ever written — neither `loggingMigrationSink` nor the
+	// nothing-to-do branch in `runtime/query/index.ts` — so the operator's
+	// migration line rendered the body and appended an empty string. `kind`
+	// is the fact worth seeing: migrated, already_migrated, or noop_no_legacy.
+	[BOOT_EVENT_NAMES.MIGRATION_COMPLETED]: (r) => bodyWith(r, ['namzu.migration.kind']),
+	[BOOT_EVENT_NAMES.DISCOVERY_COMPLETED]: (r) =>
+		joined([
+			r.body,
+			attr(r, 'namzu.discovery.plugins'),
+			attr(r, 'namzu.discovery.skills'),
+			attr(r, 'namzu.discovery.connectors'),
+		]),
+	[BOOT_EVENT_NAMES.BOOT_REFUSED]: (r) => bodyWith(r, ['namzu.boot.refusal.reason']),
+	[BOOT_EVENT_NAMES.BOOT_READY]: (r) => bodyWith(r, ['namzu.boot.duration.ms']),
+}
+
+/**
+ * The column label: `namzu.config.resolved` reads as `config`.
+ *
+ * Derived from the event name rather than `scope.name` because the scope of
+ * every one of these is the process that emitted it — `cli` for all eleven —
+ * which would make the column a constant and buy nothing. A record with no
+ * event name keeps its scope, which is the only thing it has.
+ */
+export function columnLabel(record: LogRecord): string {
+	const name = record.eventName
+	if (!name) return record.scope.name
+	const parts = name.split('.')
+	// `namzu.<area>.<verb>` → `<area>`; anything else keeps its whole name so
+	// a foreign vocabulary is not silently truncated into a wrong label.
+	if (parts.length === 3 && parts[0] === 'namzu') return parts[1] as string
+	return name
+}
+
+const BOOT_EVENT_SET: ReadonlySet<string> = new Set(Object.values(BOOT_EVENT_NAMES))
+
+/** The rendered body for a record, or `undefined` to use the default. */
+export function applyTemplate(record: LogRecord): string | undefined {
+	const name = record.eventName
+	if (!name || !BOOT_EVENT_SET.has(name)) return undefined
+	return BOOT_TEMPLATES[name as BootEventName](record)
+}
+
+// ─── the scope column's colour ───────────────────────────────────────────
+
+/**
+ * Eight ANSI foreground colours, pinned here.
+ *
+ * Not 256-colour and not truecolour: this has to be legible on a default
+ * terminal profile, and the bright/dim variants of these eight are the only
+ * ones a user's own theme is guaranteed to have already made readable
+ * against their background. Black and white are absent because one of the
+ * two disappears on any given background.
+ */
+const PALETTE = [31, 32, 33, 34, 35, 36, 91, 92] as const
+
+/**
+ * FNV-1a, written out rather than imported.
+ *
+ * The requirement is that the same scope gets the same colour in a
+ * different process on a different day, so nothing here may touch process
+ * state — no `Math.random`, no insertion order, no `Date`. Written out
+ * because a dependency could change its algorithm in a patch release and
+ * every colour in every terminal would move at once, for a bump nobody
+ * reviewed as a display change.
+ */
+export function scopeColour(scope: string): number {
+	let hash = 0x811c9dc5
+	for (let i = 0; i < scope.length; i++) {
+		hash ^= scope.charCodeAt(i)
+		// `Math.imul` keeps this in 32-bit integer space; `hash * 16777619`
+		// exceeds 2^53 and starts losing low bits, which is where a hash
+		// stops distributing.
+		hash = Math.imul(hash, 0x01000193)
+	}
+	return PALETTE[Math.abs(hash) % PALETTE.length] as number
+}

package/src/utils/log/types.ts

@@ -0,0 +1,195 @@
+// The LogSink seam's record and pipeline types.
+//
+// `../logger.ts` keeps `Logger`, `LogContext`, `getRootLogger` and
+// `configureLogger` completely unchanged — `Logger` is in INPUT position on
+// the public surface (`logger?: Logger` on `RunConfig` and tool config), so
+// every host's existing implementation must keep satisfying it forever.
+// Everything here is additive: a new, structurally separate seam that does
+// not touch that interface.
+
+/**
+ * The severity vocabulary Namzu actually emits. `trace` and `fatal` are
+ * deliberately absent — shipping either with no emitter is exactly the "a
+ * declaration nothing drives is a defect" this codebase forbids, and `fatal`
+ * in a library is a category error besides: the SDK never terminates the
+ * host process it runs inside. The OTel numeric scale leaves 1-4 and 21-24
+ * free, so both can arrive later, with their own emitters, without renaming
+ * anything that ships today.
+ */
+export type Severity = 'debug' | 'info' | 'warn' | 'error'
+
+/**
+ * `silent` is not a severity — nothing is ever emitted "at" silent. It is a
+ * property of a filter, which is why it lives on this type and not on
+ * `Severity`.
+ */
+export type LevelFilter = Severity | 'silent'
+
+/** OTel Resource: identifies the process emitting records, stamped once per
+ *  logger and never per call. */
+export interface Resource {
+	readonly 'service.name': string
+	readonly 'service.version'?: string
+	readonly 'service.instance.id'?: string
+}
+
+/**
+ * A structural subset of the OTel Logs Data Model — the fields this
+ * kernel actually populates. `traceId`, `spanId` and `traceFlags` arrived
+ * together with the emitter that writes them: `createLogger`'s `emit`,
+ * reading `telemetry/runtime-accessors.ts`'s `getActiveSpanContext()` on
+ * every accepted record. See their own doc comment below for what
+ * "arrived" means when nothing is active — declaring them and leaving them
+ * unwritten would have been the same defect with extra steps, present on
+ * the type and wrong in every record.
+ *
+ * `eventName` arrives a different way than the rest of the record. No
+ * field on `LoggerOptions` sets it and `Logger` gains no method for it —
+ * `Logger` is in INPUT position on the public surface (see the file
+ * header), so a fifth method would break every host's existing
+ * implementation. Instead a call site sets `EVENT_NAME_ATTRIBUTE` on the
+ * `data` it already passes to `debug`/`info`/`warn`/`error`; `createLogger`
+ * promotes that one attribute onto this field and deletes it from
+ * `attributes` so the same name never appears twice in one record.
+ */
+export interface LogRecord {
+	/** Epoch ms at the call site. */
+	readonly timestamp: number
+	/** Epoch ms at the point the pipeline finished building the record. */
+	readonly observedTimestamp: number
+	readonly severityNumber: 5 | 9 | 13 | 17
+	readonly severityText: Severity
+	/** OTel Body. Intended to be a constant string at every call site — a
+	 *  future CI gate enforces that; this type does not. */
+	readonly body: string
+	readonly scope: { readonly name: string }
+	/** Stamped once by `createLogger` from `LoggerOptions.resource`, never
+	 *  per call. */
+	readonly resource: Resource
+	readonly attributes: Readonly<Record<string, unknown>>
+	/** Promoted from the `EVENT_NAME_ATTRIBUTE` attribute when a call site
+	 *  set one. Absent on the great majority of records — only the boot
+	 *  narrative and other named events carry it. */
+	readonly eventName?: string
+	/**
+	 * The active span's identity at the moment this record was built —
+	 * resolved fresh per record by `createLogger`'s `emit`, from
+	 * `telemetry/runtime-accessors.ts`'s `getActiveSpanContext()`. All three
+	 * of `traceId`, `spanId` and `traceFlags` arrive together or not at
+	 * all: a trace id with no span id would be a half-address, useless to a
+	 * trace viewer's join and worse than the plain absence a reader can
+	 * already tell apart from "unwritten".
+	 *
+	 * Genuinely ABSENT — not `''`, not `'unknown'` — whenever nothing is
+	 * active: no tracer provider registered, or a real one registered with
+	 * no context manager to carry it past the first `await` (the default
+	 * `NoopContextManager` `@opentelemetry/api` ships is exactly that; see
+	 * `getActiveSpanContext`'s own doc). Reading the active context this
+	 * way cannot make a check fail on a host that never configured
+	 * telemetry — it can only ever add information that was not there
+	 * before.
+	 */
+	readonly traceId?: string
+	readonly spanId?: string
+	readonly traceFlags?: number
+}
+
+/**
+ * The one attribute key `createLogger` treats specially: set it on the
+ * `data` passed to a `Logger` call and the value is promoted to
+ * `LogRecord.eventName` and removed from `attributes`, rather than copied to
+ * both — an attribute and a field carrying the same value would be the same
+ * name spelled two ways in one record. Exported so the small number of call
+ * sites that name an event (see `BOOT_EVENT_NAMES` in
+ * `constants/telemetry`) spell the reserved key once, not as a duplicated
+ * string literal each has to keep in sync with this one.
+ */
+export const EVENT_NAME_ATTRIBUTE = 'namzu.event.name'
+
+/**
+ * The one context key `Logger.child()` treats specially, at every backing
+ * implementation: set it on the object passed to `child()` and the value
+ * REPLACES the logger's `scope.name` for every record that logger (and its
+ * own descendants) emit from then on, rather than being copied into
+ * `attributes` — the same "one name spelled once" rule `EVENT_NAME_ATTRIBUTE`
+ * follows, applied to a property of the LOGGER instead of a property of one
+ * CALL. Scope is stamped once per `child()`, not read per record, which is
+ * why it lives here rather than as an ordinary attribute: a module's
+ * identity does not change between one log line and the next inside it.
+ *
+ * A plain, un-namespaced key (historically `component`) is deliberately NOT
+ * treated as an alias for this. A call site that still binds `component`
+ * gets an ordinary, inert attribute, not a scope change — see the
+ * `component`-is-inert tests in `utils/__tests__/log-scope-attribute.test.ts`.
+ */
+export const SCOPE_ATTRIBUTE = 'namzu.log.scope'
+
+/**
+ * The other attribute key `createLogger` treats specially, alongside
+ * `EVENT_NAME_ATTRIBUTE` above: set it on the `data` passed to a `Logger`
+ * call to the THROWN VALUE ITSELF — not a string a call site already built
+ * with `toErrorMessage` — and `errorAttributes` (`./exception.ts`) maps it
+ * to `exception.type` / `exception.message` / `exception.stacktrace` before
+ * the record reaches redaction and the size caps, exactly like any other
+ * attribute a call site set by hand. Removed from `attributes` the same way
+ * `EVENT_NAME_ATTRIBUTE` is, so the raw `Error` object this key held is
+ * never itself what a sink tries to serialize.
+ *
+ * Spelled `err`, not `error`: dozens of existing call sites already pass
+ * `{ error: toErrorMessage(err) }` — a STRING built by hand — and giving the
+ * new, structured path a different key means both shapes keep compiling
+ * side by side instead of one silently shadowing the other depending on
+ * which call site wrote last.
+ */
+export const ERR_ATTRIBUTE = 'err'
+
+export interface LogSink {
+	/**
+	 * Must not throw. `createLogger`'s dispatch enforces this regardless —
+	 * see `create-logger.ts` — because a host sink is arbitrary code the
+	 * kernel does not control, and the seam cannot rely on every
+	 * implementation honouring a comment.
+	 */
+	emit(record: LogRecord): void
+}
+
+export interface LoggerOptions {
+	readonly sink: LogSink
+	/**
+	 * A mutable holder, read per record inside `createLogger`'s dispatch —
+	 * never captured in a closure at construction. `child()` on today's
+	 * `Logger` bakes its level in exactly that way, which is why the
+	 * module-scope loggers in `skills/loader.ts`, `skills/registry.ts` and
+	 * `plugin/loader.ts` are frozen at `info` forever and unreachable by any
+	 * later `configureLogger` call — verified live: `skills/loader.ts:12`,
+	 * `skills/registry.ts:10` and `plugin/loader.ts:12` all call
+	 * `getRootLogger().child({...})` at module load time.
+	 */
+	readonly level: { current: LevelFilter }
+	readonly resource: Resource
+	readonly scope: string
+}
+
+export interface LogSinkCounters {
+	/** Records that never reached a live sink — the sink threw, or the
+	 *  configured sink was `NOOP_SINK`. */
+	readonly dropped: number
+	/** Records where the redaction scan replaced at least one matched value. */
+	readonly redacted: number
+	/** Records where more than 64 attributes were present; the excess were
+	 *  dropped. */
+	readonly attributesDropped: number
+	/** Attribute string values truncated at the per-value byte cap. */
+	readonly valuesTruncated: number
+	/** Records whose total serialized size exceeded the cap and were
+	 *  shrunk by dropping attributes. */
+	readonly recordsTruncated: number
+}
+
+/**
+ * The mutable view of `LogSinkCounters` the pipeline writes through.
+ * Deliberately not exported from `log/index.ts` — a consumer only ever
+ * reads the readonly view attached to the logger it was handed, never
+ * increments one directly.
+ */
+export type MutableLogSinkCounters = { -readonly [K in keyof LogSinkCounters]: LogSinkCounters[K] }