@namzu/sdk 27.1.0 → 29.0.0

package/dist/utils/log/types.d.ts

@@ -0,0 +1,183 @@
+/**
+ * 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 declare 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 declare 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 declare 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];
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/utils/log/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/utils/log/types.ts"],"names":[],"mappings":"AASA;;;;;;;;GAQG;AACH,MAAM,MAAM,QAAQ,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAA;AAE1D;;;;GAIG;AACH,MAAM,MAAM,WAAW,GAAG,QAAQ,GAAG,QAAQ,CAAA;AAE7C;iCACiC;AACjC,MAAM,WAAW,QAAQ;IACxB,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAA;IAC/B,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAA;IACnC,QAAQ,CAAC,qBAAqB,CAAC,EAAE,MAAM,CAAA;CACvC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,WAAW,SAAS;IACzB,iCAAiC;IACjC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,uEAAuE;IACvE,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAA;IAClC,QAAQ,CAAC,cAAc,EAAE,CAAC,GAAG,CAAC,GAAG,EAAE,GAAG,EAAE,CAAA;IACxC,QAAQ,CAAC,YAAY,EAAE,QAAQ,CAAA;IAC/B;4DACwD;IACxD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,KAAK,EAAE;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAA;IACzC;oBACgB;IAChB,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAA;IAC3B,QAAQ,CAAC,UAAU,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA;IACtD;;qDAEiD;IACjD,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAA;IAC3B;;;;;;;;;;;;;;;;;OAiBG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAC5B;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,oBAAoB,qBAAqB,CAAA;AAEtD;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,eAAe,oBAAoB,CAAA;AAEhD;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,aAAa,QAAQ,CAAA;AAElC,MAAM,WAAW,OAAO;IACvB;;;;;OAKG;IACH,IAAI,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CAAA;CAC7B;AAED,MAAM,WAAW,aAAa;IAC7B,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAA;IACtB;;;;;;;;;OASG;IACH,QAAQ,CAAC,KAAK,EAAE;QAAE,OAAO,EAAE,WAAW,CAAA;KAAE,CAAA;IACxC,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAA;IAC3B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CACtB;AAED,MAAM,WAAW,eAAe;IAC/B;2CACuC;IACvC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,4EAA4E;IAC5E,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB;mBACe;IACf,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAA;IAClC,mEAAmE;IACnE,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAA;IAChC;yCACqC;IACrC,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAA;CACjC;AAED;;;;;GAKG;AACH,MAAM,MAAM,sBAAsB,GAAG;IAAE,CAAC,UAAU,CAAC,IAAI,MAAM,eAAe,GAAG,eAAe,CAAC,CAAC,CAAC;CAAE,CAAA"}

package/dist/utils/log/types.js

@@ -0,0 +1,55 @@
+// 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 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';
+//# sourceMappingURL=types.js.map

package/dist/utils/log/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/utils/log/types.ts"],"names":[],"mappings":"AAAA,gDAAgD;AAChD,EAAE;AACF,mEAAmE;AACnE,4EAA4E;AAC5E,4EAA4E;AAC5E,wEAAwE;AACxE,2EAA2E;AAC3E,4BAA4B;AAyF5B;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,kBAAkB,CAAA;AAEtD;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,iBAAiB,CAAA;AAEhD;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,KAAK,CAAA"}

package/dist/utils/logger.d.ts

@@ -1,3 +1,4 @@
+import type { LogSinkCounters } from './log/types.js';
 export type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'silent';
 export type LogContext = Record<string, unknown>;
 export interface Logger {
@@ -7,7 +8,50 @@ export interface Logger {
     error(message: string, data?: LogContext): void;
     child(context: LogContext): Logger;
 }
+/**
+ * @deprecated Prefer `installProcessSink` (own the process's log
+ * destination) or `createLogger` (build a logger scoped to a run, tenant or
+ * subsystem) from `packages/sdk/src/utils/log/`. `getRootLogger` and
+ * `configureLogger` read and write one process-wide global with no
+ * destination lever beyond a level threshold — the reason every CLI entry
+ * point historically had only one option: switch it off entirely.
+ * Unchanged behaviour; this JSDoc is the only edit.
+ */
 export declare function getRootLogger(): Logger;
+/**
+ * Fall back to the process root only when nobody supplied their own. Kept
+ * here rather than inlined at each call site so a boundary that threads a
+ * host-supplied logger can stay entirely free of `getRootLogger()` itself.
+ * `RunContextFactory.buildLogger` was the first caller (LOG-07); LOG-10
+ * moved every remaining constructor across `packages/sdk/src` onto this
+ * same seam, so this function's own fallback is now the ONLY place in the
+ * package that reads the process-wide global outside a host's direct call
+ * to `getRootLogger()` itself. `getRootLoggerCount` in
+ * `scripts/log-standard.json` measures exactly that: it cannot reach zero
+ * while an optional, non-breaking fallback exists at all — removing the
+ * fallback (flipping the default to `NOOP_LOGGER`) is LOG-20's major, not
+ * this seam's.
+ */
+export declare function resolveLogger(logger: Logger | undefined): Logger;
+/**
+ * What the record pipeline did to the records it was given, or `undefined`
+ * when no host has claimed the process's log destination.
+ *
+ * `undefined` is the honest answer for that case, not a zeroed set. With no
+ * sink installed `getRootLogger` falls back to the legacy stderr writer,
+ * which has no pipeline and therefore no redaction pass, no size caps and
+ * nothing to count -- reporting five zeros there would read as "nothing was
+ * dropped, nothing was redacted", which is a stronger claim than "this was
+ * never measured" and happens to be the claim a reader most wants to trust.
+ * `namzu doctor`'s `logging.pipeline` check turns the absence into its own
+ * row rather than into a clean bill of health.
+ */
+export declare function getLogCounters(): LogSinkCounters | undefined;
+/**
+ * @deprecated See `getRootLogger`'s deprecation note. `installProcessSink`
+ * is the strictly more capable replacement — it picks a destination, not
+ * only a threshold. Unchanged behaviour; this JSDoc is the only edit.
+ */
 export declare function configureLogger(options: {
     level?: LogLevel;
 }): void;

package/dist/utils/logger.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/utils/logger.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,QAAQ,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,QAAQ,CAAA;AAErE,MAAM,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;AAchD,MAAM,WAAW,MAAM;IACtB,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,UAAU,GAAG,IAAI,CAAA;IAC/C,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,UAAU,GAAG,IAAI,CAAA;IAC9C,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,UAAU,GAAG,IAAI,CAAA;IAC9C,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,UAAU,GAAG,IAAI,CAAA;IAC/C,KAAK,CAAC,OAAO,EAAE,UAAU,GAAG,MAAM,CAAA;CAClC;AAsCD,wBAAgB,aAAa,IAAI,MAAM,CAKtC;AAED,wBAAgB,eAAe,CAAC,OAAO,EAAE;IAAE,KAAK,CAAC,EAAE,QAAQ,CAAA;CAAE,GAAG,IAAI,CAEnE"}
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/utils/logger.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAA;AAGrD,MAAM,MAAM,QAAQ,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,QAAQ,CAAA;AAErE,MAAM,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;AAchD,MAAM,WAAW,MAAM;IACtB,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,UAAU,GAAG,IAAI,CAAA;IAC/C,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,UAAU,GAAG,IAAI,CAAA;IAC9C,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,UAAU,GAAG,IAAI,CAAA;IAC9C,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,UAAU,GAAG,IAAI,CAAA;IAC/C,KAAK,CAAC,OAAO,EAAE,UAAU,GAAG,MAAM,CAAA;CAClC;AAuCD;;;;;;;;GAQG;AACH,wBAAgB,aAAa,IAAI,MAAM,CAkBtC;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAEhE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,IAAI,eAAe,GAAG,SAAS,CAE5D;AAqDD;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE;IAAE,KAAK,CAAC,EAAE,QAAQ,CAAA;CAAE,GAAG,IAAI,CAEnE"}

package/dist/utils/logger.js

@@ -1,3 +1,6 @@
+import { createLogger } from './log/create-logger.js';
+import { getProcessSink, getProcessSinkCounters } from './log/process-sink.js';
+import { SCOPE_ATTRIBUTE } from './log/types.js';
 const LOG_LEVELS = {
     debug: 0,
     info: 1,
@@ -26,9 +29,10 @@ function createLoggerImpl(name, minLevel, parentContext) {
         }
     }
     function child(context) {
-        return createLoggerImpl(context.component ? String(context.component) : name, minLevel, {
+        const { [SCOPE_ATTRIBUTE]: scopeOverride, ...rest } = context;
+        return createLoggerImpl(typeof scopeOverride === 'string' ? scopeOverride : name, minLevel, {
             ...parentContext,
-            ...context,
+            ...rest,
         });
     }
     return {
@@ -40,12 +44,108 @@ function createLoggerImpl(name, minLevel, parentContext) {
     };
 }
 let _rootLogger = null;
+/**
+ * @deprecated Prefer `installProcessSink` (own the process's log
+ * destination) or `createLogger` (build a logger scoped to a run, tenant or
+ * subsystem) from `packages/sdk/src/utils/log/`. `getRootLogger` and
+ * `configureLogger` read and write one process-wide global with no
+ * destination lever beyond a level threshold — the reason every CLI entry
+ * point historically had only one option: switch it off entirely.
+ * Unchanged behaviour; this JSDoc is the only edit.
+ */
 export function getRootLogger() {
+    // A process sink, when one is installed, wins over both the cached logger
+    // and the stderr default. Resolved per CALL rather than cached, for the
+    // same reason the new pipeline reads its level per record: a logger handed
+    // out before `installProcessSink` ran would otherwise keep writing to
+    // stderr forever, which is the exact shape of the three frozen loaders
+    // this migration just fixed.
+    //
+    // This bridge is what lets the ~39 existing `getRootLogger()` call sites
+    // reach a host's sink without being rewritten in one commit. They keep the
+    // old interface and gain the new destination.
+    const installed = getProcessSink();
+    if (installed)
+        return fromSink(installed.sink, installed.level);
     if (!_rootLogger) {
         _rootLogger = createLoggerImpl('namzu', 'info', {});
     }
     return _rootLogger;
 }
+/**
+ * Fall back to the process root only when nobody supplied their own. Kept
+ * here rather than inlined at each call site so a boundary that threads a
+ * host-supplied logger can stay entirely free of `getRootLogger()` itself.
+ * `RunContextFactory.buildLogger` was the first caller (LOG-07); LOG-10
+ * moved every remaining constructor across `packages/sdk/src` onto this
+ * same seam, so this function's own fallback is now the ONLY place in the
+ * package that reads the process-wide global outside a host's direct call
+ * to `getRootLogger()` itself. `getRootLoggerCount` in
+ * `scripts/log-standard.json` measures exactly that: it cannot reach zero
+ * while an optional, non-breaking fallback exists at all — removing the
+ * fallback (flipping the default to `NOOP_LOGGER`) is LOG-20's major, not
+ * this seam's.
+ */
+export function resolveLogger(logger) {
+    return logger ?? getRootLogger();
+}
+/**
+ * What the record pipeline did to the records it was given, or `undefined`
+ * when no host has claimed the process's log destination.
+ *
+ * `undefined` is the honest answer for that case, not a zeroed set. With no
+ * sink installed `getRootLogger` falls back to the legacy stderr writer,
+ * which has no pipeline and therefore no redaction pass, no size caps and
+ * nothing to count -- reporting five zeros there would read as "nothing was
+ * dropped, nothing was redacted", which is a stronger claim than "this was
+ * never measured" and happens to be the claim a reader most wants to trust.
+ * `namzu doctor`'s `logging.pipeline` check turns the absence into its own
+ * row rather than into a clean bill of health.
+ */
+export function getLogCounters() {
+    return getProcessSink()?.counters;
+}
+/**
+ * Adapts the record pipeline back to the legacy `Logger` shape. `scope`
+ * threads through recursive `child()` calls the same way `bound` does.
+ * Previously fixed at `'namzu'` on every recursive call regardless of what
+ * a caller bound — meaning every `getRootLogger()`-derived child logger
+ * (the majority of call sites in this package) reported the SAME
+ * `scope.name` no matter what `SCOPE_ATTRIBUTE` it was given. This is the
+ * single highest-leverage line in the LOG-09 migration: see the direct
+ * regression test in `runtime/query/__tests__/context.test.ts` and
+ * `utils/__tests__/log-scope-attribute.test.ts`.
+ */
+function fromSink(sink, level, bound = {}, scope = 'namzu') {
+    // The process's counter set, not a fresh one. `getRootLogger` resolves
+    // PER CALL and lands here every time, so a logger built with its own
+    // counters would throw the totals away between one log line and the
+    // next -- which is what made `LogSinkCounters` unreadable by anything.
+    const created = createLogger({
+        sink,
+        level: { current: level },
+        resource: { 'service.name': 'namzu' },
+        scope,
+    }, getProcessSinkCounters());
+    const write = (severity) => (message, data) => {
+        created[severity](message, { ...bound, ...data });
+    };
+    return {
+        debug: write('debug'),
+        info: write('info'),
+        warn: write('warn'),
+        error: write('error'),
+        child: (context) => {
+            const { [SCOPE_ATTRIBUTE]: scopeOverride, ...rest } = context;
+            return fromSink(sink, level, { ...bound, ...rest }, typeof scopeOverride === 'string' ? scopeOverride : scope);
+        },
+    };
+}
+/**
+ * @deprecated See `getRootLogger`'s deprecation note. `installProcessSink`
+ * is the strictly more capable replacement — it picks a destination, not
+ * only a threshold. Unchanged behaviour; this JSDoc is the only edit.
+ */
 export function configureLogger(options) {
     _rootLogger = createLoggerImpl('namzu', options.level ?? 'info', {});
 }

package/dist/utils/logger.js.map

@@ -1 +1 @@
-{"version":3,"file":"logger.js","sourceRoot":"","sources":["../../src/utils/logger.ts"],"names":[],"mappings":"AAIA,MAAM,UAAU,GAA6B;IAC5C,KAAK,EAAE,CAAC;IACR,IAAI,EAAE,CAAC;IACP,IAAI,EAAE,CAAC;IACP,KAAK,EAAE,CAAC;IACR,oEAAoE;IACpE,kEAAkE;IAClE,+DAA+D;IAC/D,8CAA8C;IAC9C,MAAM,EAAE,CAAC;CACT,CAAA;AAUD,SAAS,gBAAgB,CAAC,IAAY,EAAE,QAAkB,EAAE,aAAyB;IACpF,MAAM,WAAW,GAAG,UAAU,CAAC,QAAQ,CAAC,CAAA;IAExC,SAAS,GAAG,CAAC,KAAe,EAAE,OAAe,EAAE,IAAiB;QAC/D,IAAI,UAAU,CAAC,KAAK,CAAC,GAAG,WAAW;YAAE,OAAM;QAE3C,MAAM,SAAS,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAA;QAC1C,MAAM,MAAM,GAAG,IAAI,SAAS,MAAM,KAAK,CAAC,WAAW,EAAE,MAAM,IAAI,GAAG,CAAA;QAClE,MAAM,MAAM,GAAG,EAAE,GAAG,aAAa,EAAE,GAAG,IAAI,EAAE,CAAA;QAC5C,MAAM,UAAU,GAAG,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,MAAM,GAAG,CAAC,CAAA;QAEjD,IAAI,UAAU,EAAE,CAAC;YAChB,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,MAAM,IAAI,OAAO,IAAI,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,IAAI,CAAC,CAAA;QACzE,CAAC;aAAM,CAAC;YACP,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,MAAM,IAAI,OAAO,IAAI,CAAC,CAAA;QAC/C,CAAC;IACF,CAAC;IAED,SAAS,KAAK,CAAC,OAAmB;QACjC,OAAO,gBAAgB,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,QAAQ,EAAE;YACvF,GAAG,aAAa;YAChB,GAAG,OAAO;SACV,CAAC,CAAA;IACH,CAAC;IAED,OAAO;QACN,KAAK,EAAE,CAAC,GAAG,EAAE,IAAI,EAAE,EAAE,CAAC,GAAG,CAAC,OAAO,EAAE,GAAG,EAAE,IAAI,CAAC;QAC7C,IAAI,EAAE,CAAC,GAAG,EAAE,IAAI,EAAE,EAAE,CAAC,GAAG,CAAC,MAAM,EAAE,GAAG,EAAE,IAAI,CAAC;QAC3C,IAAI,EAAE,CAAC,GAAG,EAAE,IAAI,EAAE,EAAE,CAAC,GAAG,CAAC,MAAM,EAAE,GAAG,EAAE,IAAI,CAAC;QAC3C,KAAK,EAAE,CAAC,GAAG,EAAE,IAAI,EAAE,EAAE,CAAC,GAAG,CAAC,OAAO,EAAE,GAAG,EAAE,IAAI,CAAC;QAC7C,KAAK;KACL,CAAA;AACF,CAAC;AAED,IAAI,WAAW,GAAkB,IAAI,CAAA;AAErC,MAAM,UAAU,aAAa;IAC5B,IAAI,CAAC,WAAW,EAAE,CAAC;QAClB,WAAW,GAAG,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,CAAC,CAAA;IACpD,CAAC;IACD,OAAO,WAAW,CAAA;AACnB,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,OAA6B;IAC5D,WAAW,GAAG,gBAAgB,CAAC,OAAO,EAAE,OAAO,CAAC,KAAK,IAAI,MAAM,EAAE,EAAE,CAAC,CAAA;AACrE,CAAC"}
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../../src/utils/logger.ts"],"names":[],"mappings":"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"}

package/dist/utils/renamed-field.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Resolves a config field that is being renamed, while both names are live.
+ *
+ * A deprecation window means two spellings of one field accept values at the
+ * same time, and the interesting case is not "which do we prefer" — it is
+ * what to do when a caller sets BOTH to different things. Preferring one
+ * silently would run with a value the caller also told us not to use, which
+ * is the quiet degradation this repo's `refuse-do-not-degrade` rule exists
+ * to prevent. There is no correct guess available: a caller who set both has
+ * a genuine disagreement with themselves, and the only honest answer is to
+ * say so and name both fields, so the message points at the two lines they
+ * have to reconcile rather than at this helper.
+ *
+ * Identical values are not a disagreement — a host spreading one object into
+ * both spellings during its own migration is stating one thing twice. That
+ * passes.
+ */
+export declare function pickRenamed<T>(oldName: string, oldValue: T | undefined, newName: string, newValue: T | undefined): T | undefined;
+//# sourceMappingURL=renamed-field.d.ts.map

package/dist/utils/renamed-field.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"renamed-field.d.ts","sourceRoot":"","sources":["../../src/utils/renamed-field.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAC5B,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,CAAC,GAAG,SAAS,EACvB,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,CAAC,GAAG,SAAS,GACrB,CAAC,GAAG,SAAS,CAYf"}

package/dist/utils/renamed-field.js

@@ -0,0 +1,29 @@
+/**
+ * Resolves a config field that is being renamed, while both names are live.
+ *
+ * A deprecation window means two spellings of one field accept values at the
+ * same time, and the interesting case is not "which do we prefer" — it is
+ * what to do when a caller sets BOTH to different things. Preferring one
+ * silently would run with a value the caller also told us not to use, which
+ * is the quiet degradation this repo's `refuse-do-not-degrade` rule exists
+ * to prevent. There is no correct guess available: a caller who set both has
+ * a genuine disagreement with themselves, and the only honest answer is to
+ * say so and name both fields, so the message points at the two lines they
+ * have to reconcile rather than at this helper.
+ *
+ * Identical values are not a disagreement — a host spreading one object into
+ * both spellings during its own migration is stating one thing twice. That
+ * passes.
+ */
+export function pickRenamed(oldName, oldValue, newName, newValue) {
+    if (oldValue !== undefined && newValue !== undefined && oldValue !== newValue) {
+        throw new Error(`Both \`${oldName}\` and \`${newName}\` were set to different values. \`${oldName}\` is the deprecated spelling of \`${newName}\`; pass one. Neither was used, because choosing between them would mean running with a value you also asked not to use.`);
+    }
+    // The order here carries no information, and that is worth saying so
+    // nobody "corrects" it later: by this line the both-set case has already
+    // been fully decided above — either it threw, or the two are identical
+    // and either branch returns the same object. Written new-first only
+    // because it reads as the direction of travel.
+    return newValue ?? oldValue;
+}
+//# sourceMappingURL=renamed-field.js.map

package/dist/utils/renamed-field.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"renamed-field.js","sourceRoot":"","sources":["../../src/utils/renamed-field.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,WAAW,CAC1B,OAAe,EACf,QAAuB,EACvB,OAAe,EACf,QAAuB;IAEvB,IAAI,QAAQ,KAAK,SAAS,IAAI,QAAQ,KAAK,SAAS,IAAI,QAAQ,KAAK,QAAQ,EAAE,CAAC;QAC/E,MAAM,IAAI,KAAK,CACd,UAAU,OAAO,YAAY,OAAO,sCAAsC,OAAO,sCAAsC,OAAO,0HAA0H,CACxP,CAAA;IACF,CAAC;IACD,qEAAqE;IACrE,yEAAyE;IACzE,uEAAuE;IACvE,oEAAoE;IACpE,+CAA+C;IAC/C,OAAO,QAAQ,IAAI,QAAQ,CAAA;AAC5B,CAAC"}

package/dist/vault/CredentialProvider.d.ts

@@ -0,0 +1,89 @@
+import { NamzuError } from '../types/errors/index.js';
+/**
+ * Where a credential comes from, as a seam a host can implement.
+ *
+ * Parallel to `CredentialVault`, not a replacement for it. That interface is
+ * connector-scoped — it holds a whole `AuthConfig` for a named connector —
+ * and its only implementation keeps them in a `Map`, in-process, with no
+ * persistence and no notion of writability. This is the other question: given
+ * a variable name, who can answer what it is, and can anybody change it.
+ *
+ * It exists because all LLM-provider credential discovery lived in the CLI,
+ * which walks a provider registry and reads `process.env` itself. A host
+ * embedding the SDK without the CLI therefore had no way to plug in an env-
+ * or file-backed source short of reimplementing the vault interface for a
+ * question the vault does not ask.
+ */
+/** A credential's name — an environment variable, a keychain entry, a path. */
+export type CredentialRef = string;
+export interface ResolvedCredential {
+    readonly value: string;
+    /** Which backing store answered. Named so a host can say where it looked. */
+    readonly source: string;
+}
+export interface CredentialDescription {
+    readonly configured: boolean;
+    /** Absent when nothing has it — there is no source to name. */
+    readonly source?: string;
+    /**
+     * Whether `set`/`unset` will do anything.
+     *
+     * Reported rather than discovered by trying, because the discovery is a
+     * write. A caller that has to attempt a mutation to learn it is not
+     * allowed has already attempted it somewhere that permits it.
+     */
+    readonly writable: boolean;
+}
+export interface CredentialProvider {
+    resolve(ref: CredentialRef): Promise<ResolvedCredential | undefined>;
+    /**
+     * What is known about a credential WITHOUT returning it.
+     *
+     * Never carries the value. A "does this exist" question is asked in
+     * places a secret must not travel to — a doctor readout, a picker, a log
+     * line — and a description that carried one would leak on every one of
+     * them while looking like metadata.
+     */
+    describe(ref: CredentialRef): Promise<CredentialDescription>;
+    set(ref: CredentialRef, value: string): Promise<void>;
+    unset(ref: CredentialRef): Promise<void>;
+}
+/** A write attempted against a provider that cannot perform one. */
+export declare class ReadOnlyCredentialProviderError extends NamzuError {
+    constructor(ref: CredentialRef, source: string, alternative: string);
+}
+export interface EnvCredentialProviderOptions {
+    /** The environment to read. Injectable so a test needs no global. */
+    readonly env?: NodeJS.ProcessEnv;
+    /**
+     * Answer for any name, not only credential-shaped ones.
+     *
+     * Off by default. A provider that resolves ANY variable is a way to read
+     * arbitrary process state through a seam whose name says "credential",
+     * and the caller asking for `HOME` through a credential provider has
+     * asked the wrong object.
+     */
+    readonly anyKey?: boolean;
+}
+/**
+ * Credentials from the process environment.
+ *
+ * Read-only, and it says so rather than accepting a write and dropping it.
+ * `process.env` is inherited from whoever started this process; a `set` here
+ * would change one map in one process and vanish with it, while every
+ * caller who asked would be told it worked. That is the quiet degradation
+ * this repo has a rule about, and for a credential the failure surfaces
+ * later as an authentication error pointing nowhere.
+ */
+export declare class EnvCredentialProvider implements CredentialProvider {
+    static readonly source = "env";
+    private readonly env;
+    private readonly anyKey;
+    constructor(options?: EnvCredentialProviderOptions);
+    private answers;
+    resolve(ref: CredentialRef): Promise<ResolvedCredential | undefined>;
+    describe(ref: CredentialRef): Promise<CredentialDescription>;
+    set(ref: CredentialRef, _value: string): Promise<void>;
+    unset(ref: CredentialRef): Promise<void>;
+}
+//# sourceMappingURL=CredentialProvider.d.ts.map

package/dist/vault/CredentialProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CredentialProvider.d.ts","sourceRoot":"","sources":["../../src/vault/CredentialProvider.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAA;AAErD;;;;;;;;;;;;;;GAcG;AAEH,+EAA+E;AAC/E,MAAM,MAAM,aAAa,GAAG,MAAM,CAAA;AAElC,MAAM,WAAW,kBAAkB;IAClC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,6EAA6E;IAC7E,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CACvB;AAED,MAAM,WAAW,qBAAqB;IACrC,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAA;IAC5B,+DAA+D;IAC/D,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;IACxB;;;;;;OAMG;IACH,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAA;CAC1B;AAED,MAAM,WAAW,kBAAkB;IAClC,OAAO,CAAC,GAAG,EAAE,aAAa,GAAG,OAAO,CAAC,kBAAkB,GAAG,SAAS,CAAC,CAAA;IACpE;;;;;;;OAOG;IACH,QAAQ,CAAC,GAAG,EAAE,aAAa,GAAG,OAAO,CAAC,qBAAqB,CAAC,CAAA;IAC5D,GAAG,CAAC,GAAG,EAAE,aAAa,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACrD,KAAK,CAAC,GAAG,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CACxC;AAED,oEAAoE;AACpE,qBAAa,+BAAgC,SAAQ,UAAU;gBAClD,GAAG,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM;CASnE;AAED,MAAM,WAAW,4BAA4B;IAC5C,qEAAqE;IACrE,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAA;IAChC;;;;;;;OAOG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAA;CACzB;AAED;;;;;;;;;GASG;AACH,qBAAa,qBAAsB,YAAW,kBAAkB;IAC/D,MAAM,CAAC,QAAQ,CAAC,MAAM,SAAQ;IAE9B,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAmB;IACvC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;gBAEpB,OAAO,GAAE,4BAAiC;IAKtD,OAAO,CAAC,OAAO;IAIT,OAAO,CAAC,GAAG,EAAE,aAAa,GAAG,OAAO,CAAC,kBAAkB,GAAG,SAAS,CAAC;IAUpE,QAAQ,CAAC,GAAG,EAAE,aAAa,GAAG,OAAO,CAAC,qBAAqB,CAAC;IAY5D,GAAG,CAAC,GAAG,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAQtD,KAAK,CAAC,GAAG,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC;CAO9C"}