@namzu/sdk 27.1.0 → 29.0.0

package/src/utils/hash.ts

@@ -14,3 +14,19 @@ export function buildToolResultHashes(
 	}
 	return hashes
 }
+
+/**
+ * A short, stable digest of any JSON-able value.
+ *
+ * `JSON.stringify` is not stable across key insertion order, so callers
+ * that need two equal-by-content values to hash alike must normalise
+ * first. The one caller that does — the request envelope — sorts its tool
+ * list before hashing, because the ORDER of the tool array is itself part
+ * of what the model sees and a re-ordered catalogue is a real change.
+ */
+export function stableDigest(value: unknown): string {
+	return createHash('sha256')
+		.update(JSON.stringify(value) ?? 'null')
+		.digest('hex')
+		.slice(0, 16)
+}

package/src/utils/id.ts

@@ -1,8 +1,11 @@
 import { randomBytes } from 'node:crypto'
+import { unsafeId } from '../types/ids/brand.js'
 import type {
 	ActivityId,
 	AdvisoryCallId,
 	AdvisoryId,
+	AgentId,
+	AuditEventId,
 	CheckpointId,
 	ChunkId,
 	ConnectorId,
@@ -15,10 +18,13 @@ import type {
 	ExecutionContextId,
 	HandoffId,
 	KnowledgeBaseId,
+	KnowledgeBaseRef,
+	LockId,
 	MCPClientId,
 	MCPServerId,
 	MCPSessionId,
 	MemoryId,
+	MemoryStoreRef,
 	MessageId,
 	PlanId,
 	PluginId,
@@ -30,8 +36,10 @@ import type {
 	SummaryId,
 	TaskId,
 	TenantId,
-	ThreadId,
 	ToolCallId,
+	TopicId,
+	UserId,
+	VaultRef,
 	WorkspaceId,
 } from '../types/ids/index.js'
 
@@ -39,7 +47,25 @@ const ALPHABET = '0123456789abcdefghijklmnopqrstuvwxyz'
 const ALPHABET_LEN = ALPHABET.length
 const MAX_UNIFORM_BYTE = Math.floor(256 / ALPHABET_LEN) * ALPHABET_LEN
 
-function generateId<T extends string>(prefix: T, length = 12): `${T}${string}` {
+/**
+ * Mints an id, with the PREFIX checked against the id's own type.
+ *
+ * The two type parameters are what keeps that check alive now the ids are
+ * nominal (NZ-SURF-11). `T` is inferred from the caller's declared return
+ * type, `P` from the literal prefix, and the constraint `T extends
+ * `${P}${string}`` is what makes `generateRunId` unable to return
+ * `generateId('ses_')`: a branded `RunId` is assignable to `` `run_${string}` ``
+ * but not to `` `ses_${string}` ``, so the wrong prefix fails to compile.
+ *
+ * Without the constraint the brand would have COST a check — `unsafeId<T>`
+ * accepts any string, so `T` alone would let every generator mint any
+ * prefix. That is the docker `sandbox_`/`sbx_` defect, one layer up, which
+ * is why this is written the awkward way rather than the short way.
+ */
+function generateId<T extends `${P}${string}`, P extends string = string>(
+	prefix: P,
+	length = 12,
+): T {
 	let suffix = ''
 	let remaining = length
 	while (remaining > 0) {
@@ -52,15 +78,15 @@ function generateId<T extends string>(prefix: T, length = 12): `${T}${string}` {
 			}
 		}
 	}
-	return `${prefix}${suffix}` as `${T}${string}`
+	return unsafeId<T>(`${prefix}${suffix}`)
 }
 
 export function generateProjectId(): ProjectId {
 	return generateId('prj_')
 }
 
-export function generateThreadId(): ThreadId {
-	return generateId('thd_')
+export function generateTopicId(): TopicId {
+	return generateId('top_')
 }
 
 export function generateRunId(): RunId {
@@ -151,6 +177,10 @@ export function generateAdvisoryCallId(): AdvisoryCallId {
 	return generateId('advc_')
 }
 
+export function generateAuditEventId(): AuditEventId {
+	return generateId('aud_')
+}
+
 export function generateEmergencySaveId(): EmergencySaveId {
 	return generateId('esave_')
 }
@@ -187,25 +217,146 @@ export function generateDeliverableId(): DeliverableId {
 	return generateId('del_')
 }
 
-function parseId<T extends string>(raw: string, prefix: string, typeName: string): T {
+function parseId<T extends `${P}${string}`, P extends string = string>(
+	raw: string,
+	prefix: P,
+	typeName: string,
+): T {
 	if (!raw.startsWith(prefix)) {
 		throw new Error(`Invalid ${typeName}: expected "${prefix}" prefix, got "${raw}"`)
 	}
-	return raw as T
+	return unsafeId<T>(raw)
 }
 
 export function parseProjectId(raw: string): ProjectId {
-	return parseId<ProjectId>(raw, 'prj_', 'ProjectId')
+	return parseId(raw, 'prj_', 'ProjectId')
 }
 export function parseRunId(raw: string): RunId {
-	return parseId<RunId>(raw, 'run_', 'RunId')
+	return parseId(raw, 'run_', 'RunId')
 }
 export function parseConnectorInstanceId(raw: string): ConnectorInstanceId {
-	return parseId<ConnectorInstanceId>(raw, 'ci_', 'ConnectorInstanceId')
+	return parseId(raw, 'ci_', 'ConnectorInstanceId')
 }
 export function parsePluginId(raw: string): PluginId {
-	return parseId<PluginId>(raw, 'plg_', 'PluginId')
+	return parseId(raw, 'plg_', 'PluginId')
 }
 export function parseSandboxId(raw: string): SandboxId {
-	return parseId<SandboxId>(raw, 'sbx_', 'SandboxId')
+	return parseId(raw, 'sbx_', 'SandboxId')
+}
+
+// ─── validating constructors ─────────────────────────────────────────────
+//
+// There is no runtime prefix check anywhere in this tree. The 700-odd
+// `as RunId` casts in it assert without verifying, so a `ses_` value cast to
+// `RunId` reaches a store key unremarked and the first sign of it is a
+// lookup that finds nothing.
+//
+// These are the check. One per id type rather than a single generic
+// `asId(prefix, value)`, and the repetition is the point: a generic loses
+// the return type, so the call site stops type-checking and the whole
+// exercise buys nothing. The implementations are one function.
+
+/** A string that does not carry the prefix the id type requires. */
+export class InvalidIdError extends Error {
+	constructor(
+		readonly value: string,
+		readonly expectedPrefix: string,
+	) {
+		super(
+			`Not a valid id: ${JSON.stringify(value)} does not start with ${JSON.stringify(expectedPrefix)}. Ids are minted by the matching generate*Id() factory; a literal from a log or a URL has to be checked before it is used as one.`,
+		)
+		this.name = 'InvalidIdError'
+	}
 }
+
+/**
+ * Builds one prefix check.
+ *
+ * Throws rather than returning `undefined`, per `refuse-do-not-degrade`: a
+ * caller holding a malformed id has no correct fallback available, and the
+ * value is on its way to becoming a store key. Returning the input
+ * unchanged on the happy path is also load-bearing — a constructor that
+ * allocated a copy would silently break `===` on ids used as map keys.
+ *
+ * The trailing underscore in every prefix is what makes them unambiguous:
+ * `mcpc_x` does not start with `mcp_`, and `advc_x` does not start with
+ * `adv_`, so no id type can swallow another's values.
+ */
+/**
+ * What a checked constructor is, named so the id type can be supplied by
+ * ANNOTATION rather than as a type argument.
+ *
+ * That distinction is load-bearing and was got wrong once. `makeIdParser<
+ * RunId>('ses_')` compiles: supplying one of two type parameters explicitly
+ * makes the other fall back to its DEFAULT rather than be inferred, so `P`
+ * became `string`, the constraint read `RunId extends string`, and the
+ * prefix check evaporated. Caught by mutating `asRunId`'s prefix and finding
+ * the build still green — a check that cannot fail. With the type on the
+ * const instead, `T` comes from the contextual type and `P` is inferred from
+ * the argument, so the same mutation is a compile error.
+ */
+type IdParser<T extends string> = (value: string) => T
+
+function makeIdParser<T extends `${P}${string}`, P extends string = string>(
+	prefix: P,
+): IdParser<T> {
+	return (value: string): T => {
+		if (!value.startsWith(prefix)) throw new InvalidIdError(value, prefix)
+		return unsafeId<T>(value)
+	}
+}
+
+export const asRunId: IdParser<RunId> = makeIdParser('run_')
+export const asMessageId: IdParser<MessageId> = makeIdParser('msg_')
+export const asSessionId: IdParser<SessionId> = makeIdParser('ses_')
+export const asToolCallId: IdParser<ToolCallId> = makeIdParser('call_')
+export const asActivityId: IdParser<ActivityId> = makeIdParser('act_')
+export const asTaskId: IdParser<TaskId> = makeIdParser('task_')
+export const asPlanId: IdParser<PlanId> = makeIdParser('plan_')
+export const asKnowledgeBaseId: IdParser<KnowledgeBaseId> = makeIdParser('kb_')
+export const asDocumentId: IdParser<DocumentId> = makeIdParser('doc_')
+export const asChunkId: IdParser<ChunkId> = makeIdParser('chk_')
+export const asConnectorId: IdParser<ConnectorId> = makeIdParser('conn_')
+export const asConnectorInstanceId: IdParser<ConnectorInstanceId> = makeIdParser('ci_')
+export const asTenantId: IdParser<TenantId> = makeIdParser('tnt_')
+export const asCredentialId: IdParser<CredentialId> = makeIdParser('cred_')
+export const asExecutionContextId: IdParser<ExecutionContextId> = makeIdParser('ectx_')
+export const asMCPServerId: IdParser<MCPServerId> = makeIdParser('mcp_')
+export const asMCPClientId: IdParser<MCPClientId> = makeIdParser('mcpc_')
+export const asMCPSessionId: IdParser<MCPSessionId> = makeIdParser('mcps_')
+export const asEnvironmentId: IdParser<EnvironmentId> = makeIdParser('env_')
+export const asCheckpointId: IdParser<CheckpointId> = makeIdParser('cp_')
+export const asLockId: IdParser<LockId> = makeIdParser('lock_')
+export const asAdvisoryId: IdParser<AdvisoryId> = makeIdParser('adv_')
+export const asAdvisoryCallId: IdParser<AdvisoryCallId> = makeIdParser('advc_')
+export const asEmergencySaveId: IdParser<EmergencySaveId> = makeIdParser('esave_')
+export const asMemoryId: IdParser<MemoryId> = makeIdParser('mem_')
+export const asPluginId: IdParser<PluginId> = makeIdParser('plg_')
+export const asSandboxId: IdParser<SandboxId> = makeIdParser('sbx_')
+export const asAuditEventId: IdParser<AuditEventId> = makeIdParser('aud_')
+export const asUserId: IdParser<UserId> = makeIdParser('usr_')
+/**
+ * @deprecated Nothing in this kernel mints an `agt_` id, so this constructor
+ * throws on every agent identifier the kernel actually produces — an agent is
+ * named by its registry key. See {@link AgentId}. Removal is a later major.
+ */
+export const asAgentId: IdParser<AgentId> = makeIdParser('agt_')
+export const asMemoryStoreRef: IdParser<MemoryStoreRef> = makeIdParser('mms_')
+export const asVaultRef: IdParser<VaultRef> = makeIdParser('vlt_')
+export const asKnowledgeBaseRef: IdParser<KnowledgeBaseRef> = makeIdParser('kbs_')
+export const asProjectId: IdParser<ProjectId> = makeIdParser('prj_')
+export const asTopicId: IdParser<TopicId> = makeIdParser('top_')
+export const asSubSessionId: IdParser<SubSessionId> = makeIdParser('sub_')
+export const asHandoffId: IdParser<HandoffId> = makeIdParser('hof_')
+export const asWorkspaceId: IdParser<WorkspaceId> = makeIdParser('wsp_')
+export const asSummaryId: IdParser<SummaryId> = makeIdParser('sum_')
+export const asDeliverableId: IdParser<DeliverableId> = makeIdParser('del_')
+
+// No `asThreadId`, deliberately. `ThreadId` is an alias of `TopicId` from
+// the Topic rename, so `asTopicId` already accepts every value one can hold
+// — and a parser shipped `@deprecated` on the day it is written is a name
+// that exists only to be removed. `declared-but-undriven`.
+
+// `ToolUseId` is a bare `string` — it comes from a provider, which chooses
+// its own shape, so there is no prefix to check and a constructor here would
+// be a check that cannot fail.

package/src/utils/log/attributes.ts

@@ -0,0 +1,47 @@
+// The allowlist for a hand-built attribute bag. `LogContext` on
+// `../logger.ts` stays exactly what it is — `Record<string, unknown>` —
+// because `Logger.child(context: LogContext)` is in INPUT position on the
+// public surface (`logger?: Logger` on `RunConfig` and tool config:
+// `types/run/config.ts:156`, `types/tool/index.ts:396`): narrowing it would
+// break every host that already implemented `Logger` correctly, for a type
+// change with no payoff to them. `LogAttributes` is instead a type a caller
+// builds TOWARD — construct the variable half of a log call with this type
+// and hand the result to `Logger.info`/`.child()` where `LogContext` is
+// expected. That direction always compiles: every `LogAttributes` value is
+// already a valid `LogContext` value, never the reverse.
+//
+// Two things this closes as a compile error rather than leaving to review:
+// a key outside the four prefixes the rest of the telemetry surface already
+// uses (`serverId`, `label`, `apiKey` — anything un-namespaced), and a
+// nested object value (the shape a splatted `AuthConfig`, `ResolvedConfig`
+// or `process.env` would need, and the OTel `AnyValue` subset below has no
+// room for one).
+//
+// What it does NOT close: `{ 'namzu.connector.auth': JSON.stringify(auth) }`
+// is a namespaced key holding a string, and passes every rule in this file.
+// A secret in string form is not a shape this type can see — closing THAT
+// is the record-boundary redaction scan's job (`redact.ts`), which runs on
+// every record regardless of what built its attributes. Say so wherever
+// this type is documented; it narrows what a caller can express, it does
+// not make leakage inexpressible.
+type AttributeValue = string | number | boolean | readonly (string | number | boolean)[]
+
+type AttributeKey =
+	| `namzu.${string}`
+	| `gen_ai.${string}`
+	| `service.${string}`
+	| `exception.${string}`
+
+/**
+ * A namespaced, shape-safe attribute bag. Deliberately NOT
+ * `Partial<Record<...>>`: `Partial` would type every property as
+ * `AttributeValue | undefined`, and this repo's tsconfig does not set
+ * `exactOptionalPropertyTypes` — so a `Partial` version would let
+ * `{ 'namzu.x.y': undefined }` compile, an attribute that is present and
+ * holds nothing. Plain `Record` over a template-literal key domain does not
+ * require every possible key to appear — there is no finite set of keys to
+ * require — so dropping `Partial` costs a caller nothing: it still supplies
+ * only the keys it has, and gains that an explicit `undefined` is rejected
+ * the same way `null` and a nested object already are.
+ */
+export type LogAttributes = Readonly<Record<AttributeKey, AttributeValue>>

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',
+})