@namzu/sdk 27.1.0 → 29.0.0

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
+}

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
+}