@namzu/sdk 27.1.0 → 28.0.0

package/src/utils/log/types.ts

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

package/src/utils/logger.ts

@@ -1,3 +1,8 @@
+import { createLogger } from './log/create-logger.js'
+import { getProcessSink, getProcessSinkCounters } from './log/process-sink.js'
+import type { LogSinkCounters } from './log/types.js'
+import { type LevelFilter, type LogSink, SCOPE_ATTRIBUTE } from './log/types.js'
+
 export type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'silent'
 
 export type LogContext = Record<string, unknown>
@@ -41,9 +46,10 @@ function createLoggerImpl(name: string, minLevel: LogLevel, parentContext: LogCo
 	}
 
 	function child(context: LogContext): Logger {
-		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,
 		})
 	}
 
@@ -58,13 +64,126 @@ function createLoggerImpl(name: string, minLevel: LogLevel, parentContext: LogCo
 
 let _rootLogger: Logger | null = 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(): Logger {
+	// 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: Logger | undefined): 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(): LogSinkCounters | undefined {
+	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: LogSink,
+	level: LevelFilter,
+	bound: LogContext = {},
+	scope = 'namzu',
+): Logger {
+	// 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: 'debug' | 'info' | 'warn' | 'error') => (message: string, data?: LogContext) => {
+			created[severity](message, { ...bound, ...data })
+		}
+	return {
+		debug: write('debug'),
+		info: write('info'),
+		warn: write('warn'),
+		error: write('error'),
+		child: (context: LogContext) => {
+			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: { level?: LogLevel }): void {
 	_rootLogger = createLoggerImpl('namzu', options.level ?? 'info', {})
 }

package/src/utils/renamed-field.ts

@@ -0,0 +1,35 @@
+/**
+ * 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<T>(
+	oldName: string,
+	oldValue: T | undefined,
+	newName: string,
+	newValue: T | undefined,
+): T | undefined {
+	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
+}

package/src/vault/CredentialProvider.ts

@@ -0,0 +1,147 @@
+import { isCredentialEnvKey } from '../constants/credential-env-keys.js'
+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 class ReadOnlyCredentialProviderError extends NamzuError {
+	constructor(ref: CredentialRef, source: string, alternative: string) {
+		super({
+			code: 'invalid_config',
+			message: `${source} cannot store credentials: "${ref}" is read from the process environment, which this process does not own. ${alternative}`,
+			details: { ref, source },
+			retryable: false,
+		})
+		this.name = 'ReadOnlyCredentialProviderError'
+	}
+}
+
+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 class EnvCredentialProvider implements CredentialProvider {
+	static readonly source = 'env'
+
+	private readonly env: NodeJS.ProcessEnv
+	private readonly anyKey: boolean
+
+	constructor(options: EnvCredentialProviderOptions = {}) {
+		this.env = options.env ?? process.env
+		this.anyKey = options.anyKey ?? false
+	}
+
+	private answers(ref: CredentialRef): boolean {
+		return this.anyKey || isCredentialEnvKey(ref)
+	}
+
+	async resolve(ref: CredentialRef): Promise<ResolvedCredential | undefined> {
+		if (!this.answers(ref)) return undefined
+		const value = this.env[ref]
+		// An empty string is not a credential. A variable exported as `FOO=`
+		// is the shape a shell script produces when a lookup failed, and
+		// treating it as present sends a caller off to authenticate with
+		// nothing.
+		return value ? { value, source: EnvCredentialProvider.source } : undefined
+	}
+
+	async describe(ref: CredentialRef): Promise<CredentialDescription> {
+		const found = await this.resolve(ref)
+		return {
+			configured: found !== undefined,
+			...(found ? { source: found.source } : {}),
+			writable: false,
+		}
+	}
+
+	// Takes the value it will not store, so the signature reads as the
+	// interface's and a caller does not have to discover the refusal by
+	// getting an arity error instead of the named one.
+	async set(ref: CredentialRef, _value: string): Promise<void> {
+		throw new ReadOnlyCredentialProviderError(
+			ref,
+			EnvCredentialProvider.source,
+			'Set it in the environment this process is started from, or supply a writable CredentialProvider.',
+		)
+	}
+
+	async unset(ref: CredentialRef): Promise<void> {
+		throw new ReadOnlyCredentialProviderError(
+			ref,
+			EnvCredentialProvider.source,
+			'Unset it in the environment this process is started from, or supply a writable CredentialProvider.',
+		)
+	}
+}

package/src/vault/InMemoryCredentialVault.ts

@@ -1,15 +1,18 @@
+import { NAMZU } from '../constants/telemetry/index.js'
 import type { AuthConfig, CredentialRef, CredentialVault } from '../types/connector/index.js'
 import type { ConnectorId, CredentialId, TenantId } from '../types/ids/index.js'
 import { generateCredentialId } from '../utils/id.js'
-import { type Logger, getRootLogger } from '../utils/logger.js'
+import type { LogAttributes } from '../utils/log/index.js'
+import { SCOPE_ATTRIBUTE } from '../utils/log/types.js'
+import { type Logger, resolveLogger } from '../utils/logger.js'
 
 export class InMemoryCredentialVault implements CredentialVault {
 	private refs: Map<CredentialId, CredentialRef> = new Map()
 	private secrets: Map<CredentialId, AuthConfig> = new Map()
 	private log: Logger
 
-	constructor() {
-		this.log = getRootLogger().child({ component: 'InMemoryCredentialVault' })
+	constructor(log?: Logger) {
+		this.log = resolveLogger(log).child({ [SCOPE_ATTRIBUTE]: 'vault' })
 	}
 
 	async store(
@@ -30,7 +33,12 @@ export class InMemoryCredentialVault implements CredentialVault {
 
 		this.refs.set(id, ref)
 		this.secrets.set(id, auth)
-		this.log.info(`Credential stored: ${id} (${label}) for tenant ${tenantId}`)
+		const storedAttributes: LogAttributes = {
+			[NAMZU.CREDENTIAL_ID]: id,
+			[NAMZU.CREDENTIAL_LABEL]: label,
+			[NAMZU.TENANT_ID]: tenantId,
+		}
+		this.log.info('Credential stored', storedAttributes)
 		return ref
 	}
 
@@ -43,7 +51,10 @@ export class InMemoryCredentialVault implements CredentialVault {
 		this.refs.delete(credentialId)
 		this.secrets.delete(credentialId)
 		if (existed) {
-			this.log.info(`Credential revoked: ${credentialId}`)
+			const revokedAttributes: LogAttributes = {
+				[NAMZU.CREDENTIAL_ID]: credentialId,
+			}
+			this.log.info('Credential revoked', revokedAttributes)
 		}
 		return existed
 	}

package/src/vault/index.ts

@@ -1 +1,17 @@
 export { InMemoryCredentialVault } from './InMemoryCredentialVault.js'
+
+// Where a credential comes from, as a seam a host can implement — parallel
+// to the connector-scoped `CredentialVault`, which answers a different
+// question and holds a whole `AuthConfig` per connector.
+export { wrapCredentialProviderWithProbes } from './instrumentation.js'
+export {
+	EnvCredentialProvider,
+	ReadOnlyCredentialProviderError,
+} from './CredentialProvider.js'
+export type {
+	CredentialDescription,
+	CredentialProvider,
+	CredentialRef,
+	EnvCredentialProviderOptions,
+	ResolvedCredential,
+} from './CredentialProvider.js'

package/src/vault/instrumentation.ts

@@ -1,10 +1,13 @@
 import { buildProbeContext } from '../probe/context.js'
-import { type ProbeRegistry, probe as defaultProbeRegistry } from '../probe/registry.js'
+import { probe as defaultProbeRegistry } from '../probe/registry.js'
+import type { ProbeObservation } from '../probe/registry.js'
 import type { AuthConfig, CredentialRef, CredentialVault } from '../types/connector/index.js'
 import type { ConnectorId, CredentialId, RunId, TenantId } from '../types/ids/index.js'
+import type { CredentialProvider } from './CredentialProvider.js'
 
 export interface VaultInstrumentationOptions {
-	readonly probes?: ProbeRegistry
+	/** Observation only — a vault wrapper records, it never refuses. */
+	readonly probes?: ProbeObservation
 	readonly runId?: RunId
 	readonly vaultId?: string
 	readonly tenantId?: TenantId
@@ -54,3 +57,61 @@ export function wrapVaultWithProbes(
 		},
 	}
 }
+
+/**
+ * Wrap a {@link CredentialProvider} so a change is observable.
+ *
+ * Through the SAME probe registry `vault_lookup` already uses. A second bus
+ * would mean a subscriber that saw lookups and not rotations, or the other
+ * way round, depending on which one it happened to find.
+ *
+ * `rotated` rather than `set` when a value was already there, and the
+ * distinction is the one a reader actually wants: a first write is
+ * configuration, a replacement is a credential turning over.
+ */
+export function wrapCredentialProviderWithProbes(
+	provider: CredentialProvider,
+	opts: VaultInstrumentationOptions & { readonly source?: string } = {},
+): CredentialProvider {
+	const probes = opts.probes ?? defaultProbeRegistry
+	const source = opts.source ?? provider.constructor.name
+
+	const announce = (kind: 'set' | 'unset' | 'rotated', ref: string): void => {
+		probes.dispatch(
+			{
+				type: 'vault_credential_changed',
+				kind,
+				source,
+				// The NAME, never the value. A change event exists to be logged,
+				// forwarded and retained, which is exactly what a credential
+				// must not be.
+				ref,
+				...(opts.tenantId ? { tenantId: opts.tenantId } : {}),
+				...(opts.runId ? { runId: opts.runId } : {}),
+			},
+			buildProbeContext(),
+		)
+	}
+
+	return {
+		resolve: (ref) => provider.resolve(ref),
+		describe: (ref) => provider.describe(ref),
+
+		async set(ref, value) {
+			// Asked BEFORE the write, because afterwards every credential looks
+			// like it was always there — and "configured for the first time"
+			// and "rotated" are the two facts this event exists to separate.
+			const before = await provider.describe(ref)
+			await provider.set(ref, value)
+			// Emitted only on success. A write that threw changed nothing, and
+			// an event for it would have a reader chasing a rotation that
+			// never happened.
+			announce(before.configured ? 'rotated' : 'set', ref)
+		},
+
+		async unset(ref) {
+			await provider.unset(ref)
+			announce('unset', ref)
+		},
+	}
+}

package/dist/bridge/tools/connector/adapter.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../../../../src/bridge/tools/connector/adapter.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AACvB,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,yCAAyC,CAAA;AAC/E,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mCAAmC,CAAA;AACxE,OAAO,KAAK,EAAE,WAAW,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAA;AACnF,OAAO,KAAK,EAAe,cAAc,EAAc,MAAM,8BAA8B,CAAA;AAG3F,wBAAgB,qBAAqB,CACpC,WAAW,EAAE,WAAW,EACxB,UAAU,EAAE,mBAAmB,EAC/B,MAAM,EAAE,eAAe,EACvB,OAAO,EAAE,gBAAgB,GACvB,cAAc,CA4BhB;AAED,wBAAgB,wBAAwB,CACvC,UAAU,EAAE,mBAAmB,EAC/B,OAAO,EAAE,gBAAgB,GACvB,cAAc,EAAE,CAUlB;AAED,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,gBAAgB,GAAG,cAAc,EAAE,CAM7E;AAED,QAAA,MAAM,0BAA0B;;;;;;;;;;;;;;;EAO9B,CAAA;AAEF,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,0BAA0B,CAAC,CAAA;AAE7E,wBAAgB,yBAAyB,CACxC,OAAO,EAAE,gBAAgB,GACvB,cAAc,CAAC,oBAAoB,CAAC,CA4CtC"}