@namzu/sdk 27.1.0 → 28.0.0

package/src/connector/web/types.ts

@@ -0,0 +1,99 @@
+/**
+ * Reaching the web, as a seam rather than as a bundled vendor.
+ *
+ * Two providers, and they are separated on purpose. **Fetching a URL is a
+ * capability this kernel can implement**: the rules are about the network
+ * and the same everywhere, so a wrong answer is a defect rather than a
+ * preference. **Searching is not.** Every search backend has its own
+ * account, its own terms, its own result shape and its own opinion about
+ * what a result even is, and picking one here would make that choice for
+ * every consumer while adding a dependency nobody asked for.
+ *
+ * So `WebFetchProvider` ships with a guarded implementation and
+ * `WebSearchProvider` ships with none. A host that wants search brings one.
+ * That asymmetry is the design, not an omission — see
+ * `GuardedFetchProvider` for what "guarded" is doing the work of.
+ */
+
+export interface WebFetchRequest {
+	readonly url: string
+	/** Extra headers. The provider may refuse or strip some; see the guard. */
+	readonly headers?: Readonly<Record<string, string>>
+	readonly signal?: AbortSignal
+}
+
+export interface WebFetchResult {
+	readonly url: string
+	readonly status: number
+	readonly contentType?: string
+	readonly body: string
+	/**
+	 * Whether the body was cut off at the size cap.
+	 *
+	 * Reported, never silent. A truncated page that reads as complete is a
+	 * model concluding something from a document whose second half it never
+	 * saw — the same rule the tool-output cap and the background job buffer
+	 * already follow.
+	 */
+	readonly truncated: boolean
+	/** Every URL in the redirect chain, in order, including the final one. */
+	readonly redirects: readonly string[]
+}
+
+/** Why a fetch was refused before it left the process. */
+export type WebFetchRefusalReason =
+	| 'scheme'
+	| 'private-address'
+	| 'redirect-limit'
+	| 'redirect-target'
+	| 'blocked-host'
+
+export class WebFetchRefusedError extends Error {
+	readonly details: { url: string; reason: WebFetchRefusalReason }
+
+	constructor(message: string, details: { url: string; reason: WebFetchRefusalReason }) {
+		super(message)
+		this.name = 'WebFetchRefusedError'
+		this.details = details
+	}
+}
+
+export interface WebFetchProvider {
+	fetch(request: WebFetchRequest): Promise<WebFetchResult>
+}
+
+export interface WebSearchRequest {
+	readonly query: string
+	readonly limit?: number
+	readonly signal?: AbortSignal
+}
+
+export interface WebSearchHit {
+	readonly title: string
+	readonly url: string
+	/**
+	 * The backend's own excerpt, when it has one.
+	 *
+	 * Not synthesised here. A snippet this kernel wrote would be a claim
+	 * about a page nobody fetched, and a model citing it would be citing us.
+	 */
+	readonly snippet?: string
+}
+
+export interface WebSearchResult {
+	readonly query: string
+	readonly hits: readonly WebSearchHit[]
+}
+
+/**
+ * Search, which this kernel does NOT implement.
+ *
+ * Declared so the tool surface and the wiring can exist without a vendor,
+ * and so a host's backend has a shape to satisfy rather than a convention
+ * to guess at. There is deliberately no default: a search provider means an
+ * account, terms of service, and a result shape, and choosing one here
+ * would choose it for every consumer.
+ */
+export interface WebSearchProvider {
+	search(request: WebSearchRequest): Promise<WebSearchResult>
+}

package/src/constants/acp/index.ts

@@ -0,0 +1,104 @@
+/**
+ * The agent-client protocol's version and method set, pinned.
+ *
+ * A table rather than string literals scattered through the server, because
+ * the two things that go wrong with a wire protocol are a method spelled
+ * differently in one place and a method implemented but never advertised.
+ * Both are invisible at compile time and both present to a client as "that
+ * agent does not support this".
+ *
+ * `bridge/acp/server.ts` authors its handler map independently and a test
+ * compares the two SETS in both directions: a handler with no entry here
+ * fails, and an entry here with no handler fails. That is the only
+ * arrangement where the comparison can fail — deriving the handlers from
+ * this table would make the test a tautology, which is the shape
+ * `a-check-that-cannot-fail` names.
+ *
+ * Zero imports, deliberately: this is read by the types module, the server,
+ * and the CLI command, and a constant table that pulls in a dependency
+ * becomes a cycle the moment one of those three moves.
+ */
+
+/**
+ * The protocol revision this bridge speaks.
+ *
+ * A number, matching the wire field, and pinned rather than negotiated
+ * downward. A client asking for a version this does not implement is told
+ * what it does implement; guessing that an older client can be served by a
+ * newer agent is how a protocol bridge produces a session that half works.
+ */
+export const ACP_PROTOCOL_VERSION = 1
+
+/** Methods a client calls on this agent. */
+export const ACP_METHODS = {
+	INITIALIZE: 'initialize',
+	SESSION_NEW: 'session/new',
+	SESSION_PROMPT: 'session/prompt',
+	SESSION_CANCEL: 'session/cancel',
+	SESSION_LOAD: 'session/load',
+} as const
+
+export type AcpMethod = (typeof ACP_METHODS)[keyof typeof ACP_METHODS]
+
+/**
+ * Notifications this agent sends the client.
+ *
+ * Separate from `ACP_METHODS` because the drift test is about what a client
+ * may CALL. Mixing the two directions into one table would make that test
+ * demand a handler for a message this side only ever sends.
+ */
+export const ACP_CLIENT_NOTIFICATIONS = {
+	SESSION_UPDATE: 'session/update',
+} as const
+
+/**
+ * REQUESTS this agent makes of the client, which it answers.
+ *
+ * Distinct from a notification: each carries an id and this side waits for
+ * the response. That direction is what makes a permission prompt possible at
+ * all — the agent has a question and cannot proceed until the human behind
+ * the client answers it.
+ */
+export const ACP_CLIENT_REQUESTS = {
+	REQUEST_PERMISSION: 'session/request_permission',
+	FS_READ: 'fs/read_text_file',
+	FS_WRITE: 'fs/write_text_file',
+} as const
+
+/**
+ * JSON-RPC error codes this bridge answers with.
+ *
+ * `METHOD_NOT_FOUND` is the one with a behavioural requirement attached: an
+ * unknown method is answered and the connection STAYS OPEN. A bridge that
+ * closed on an unrecognised call would make a client's feature probe fatal.
+ */
+export const ACP_ERROR_CODES = {
+	PARSE_ERROR: -32700,
+	INVALID_REQUEST: -32600,
+	METHOD_NOT_FOUND: -32601,
+	INVALID_PARAMS: -32602,
+	INTERNAL_ERROR: -32603,
+} as const
+
+/**
+ * The capability a client must declare before a session is created.
+ *
+ * Approval routing is a later change, so a session that could not ask a
+ * human anything must not be created at all: it would run with every tool
+ * auto-approved, which is not a degraded version of asking — it is the
+ * opposite of it. The refusal names this string so a client author knows
+ * what to send.
+ */
+export const ACP_PERMISSION_CAPABILITY = 'permission'
+
+/**
+ * The capability that lets the EDITOR's buffers be the source of truth.
+ *
+ * Optional, unlike `permission`. A client that does not declare it gets an
+ * agent reading and writing the disk, which is correct and is what every
+ * non-editor peer wants. A client that DOES declare it is telling this
+ * agent that the file on disk may be stale — the user has unsaved changes —
+ * and that reading disk anyway would show the model a version of the file
+ * nobody is looking at.
+ */
+export const ACP_FILESYSTEM_CAPABILITY = 'fs'

package/src/constants/credential-env-keys.ts

@@ -0,0 +1,63 @@
+/**
+ * Credential-bearing environment variable KEY NAMES, in one place.
+ *
+ * A leaf with no imports, beside `secret-patterns.ts` and holding the
+ * complement of it: that file matches credential VALUES, this one matches
+ * the names variables carry them under. Neither re-declares the other's,
+ * because a value pattern and a key name answer different questions and a
+ * table that tried to do both would be wrong at whichever end it was not
+ * written for.
+ *
+ * Two readers, and that is the point of moving it here. The host-bash
+ * environment scrub uses it to decide what a shell command must not
+ * inherit, and `EnvCredentialProvider` uses it to decide what counts as a
+ * credential it can resolve. Those were about to become two tables — the
+ * CLI's provider registry already keeps a third, of `envVars` per provider
+ * — and a name in one and not another means a variable the CLI reads a
+ * credential from and the scrub happily hands to a shell.
+ */
+
+/**
+ * Key-name patterns that mark an inherited variable as credential-shaped.
+ *
+ * Matched case-insensitively against the whole key. Deliberately broad: a
+ * false positive costs a command one variable it can be handed back
+ * explicitly, while a false negative costs a leaked secret that cannot be
+ * recalled from a transcript.
+ */
+export const CREDENTIAL_KEY_PATTERNS: readonly RegExp[] = [
+	/KEY/i,
+	/SECRET/i,
+	/TOKEN/i,
+	/PASSWORD/i,
+	/PASSWD/i,
+	/CREDENTIAL/i,
+	/(^|_)AUTH(_|$)/i,
+	/PRIVATE/i,
+	/SESSION_ID/i,
+	/COOKIE/i,
+	/SIGNATURE/i,
+	/(^|_)PAT(_|$)/i,
+]
+
+/**
+ * Keys that are credential-bearing but whose names match none of the patterns
+ * above. Kept as an explicit list so each entry is a decision somebody can
+ * read, rather than a pattern nobody can evaluate.
+ */
+export const CREDENTIAL_KEY_EXACT: ReadonlySet<string> = new Set([
+	'AWS_SESSION_TOKEN',
+	'AWS_SECURITY_TOKEN',
+	'GOOGLE_APPLICATION_CREDENTIALS',
+	'NPM_CONFIG__AUTH',
+	'GH_ENTERPRISE_TOKEN',
+	'DOCKER_AUTH_CONFIG',
+	'KUBECONFIG',
+	'NETRC',
+])
+
+/** True when an inherited variable's name marks it as credential-shaped. */
+export function isCredentialEnvKey(key: string): boolean {
+	if (CREDENTIAL_KEY_EXACT.has(key.toUpperCase())) return true
+	return CREDENTIAL_KEY_PATTERNS.some((pattern) => pattern.test(key))
+}

package/src/constants/index.ts

@@ -1,3 +1,4 @@
+export * from './acp/index.js'
 export * from './a2a/index.js'
 export * from './advisory/index.js'
 export * from './compaction/index.js'
@@ -10,7 +11,8 @@ export * from './agent/index.js'
 export * from './continuation.js'
 export * from './limits.js'
 export * from './bus/index.js'
-export * from './verification/index.js'
+export * from './authorization/index.js'
 export * from './emergency.js'
 export * from './plugin/index.js'
 export * from './sandbox/index.js'
+export * from './secret-patterns.js'

package/src/constants/secret-patterns.ts

@@ -0,0 +1,102 @@
+/**
+ * Credential shapes redacted before they leave this tree, in one place.
+ *
+ * Two tables evolved independently and disagreed:
+ *
+ *  - `runtime/query/guardrail-presets.ts` carried eight vendor-prefix-anchored
+ *    patterns, private and unexported, deliberately narrow — a loose
+ *    "looks like a secret" regex over model output produces false positives
+ *    on ordinary code, and a redactor that fires on the wrong thing gets
+ *    switched off, at which point it protects nothing.
+ *  - `provider/errors.ts` carried a broader, field-name-aware set (a
+ *    generic key-prefix pattern, a bearer-header pattern, and a JSON
+ *    field-name scrubber that catches a secret by the key it sits under
+ *    regardless of value shape) because the narrow approach had already
+ *    proven insufficient there: a vendor error body echoes the request,
+ *    and a request can carry a credential shape the narrow table never
+ *    anticipated.
+ *
+ * Both live here now, as two exported sets rather than one, because the
+ * cost of a false positive is not the same at the two call sites:
+ *
+ *  - `OUTPUT_SECRET_PATTERNS` (the original narrow eight) is what
+ *    `secretRedactionGuardrail` matches against MODEL OUTPUT. A false
+ *    positive there rewrites the answer the caller asked for, so it stays
+ *    narrow on purpose.
+ *  - `LOG_SECRET_PATTERNS` (the union of both tables) is for text that is
+ *    being logged or carried in an error's `detail`, never returned as the
+ *    answer itself. A false positive there redacts one word out of a
+ *    diagnostic line nobody was going to copy-paste as a credential, which
+ *    is a cost worth paying for the wider net.
+ *
+ * `SecretPattern` label strings are never returned to the caller verbatim —
+ * consumers replace a match with `[REDACTED:<label>]`, not the matched
+ * text, so a `label` here should never itself carry anything secret.
+ *
+ * Zero imports. This is a leaf module on purpose: `utils/logger.ts` is
+ * imported by most of `runtime/query/`, so pulling this table back out of
+ * `runtime/query` would have made it a same-package import cycle, and a
+ * cycle on a security-relevant table fails as a TDZ error or a
+ * partially-initialised module — quietly, in the worst possible place.
+ * Keeping this file leaf-only is what lets `runtime/query/guardrail-presets.ts`
+ * and `provider/errors.ts` both import from it without one importing the
+ * other.
+ */
+
+export type SecretPattern = readonly [label: string, pattern: RegExp]
+
+/**
+ * The narrow, prefix-anchored set. Unchanged from the table this replaces —
+ * same labels, same regexes, same order — because moving it was the whole
+ * point of this module and widening it was not: `secretRedactionGuardrail`
+ * still needs a redactor precise enough that it never gets switched off.
+ */
+export const OUTPUT_SECRET_PATTERNS: readonly SecretPattern[] = [
+	['aws-access-key', /\b(?:AKIA|ASIA)[0-9A-Z]{16}\b/g],
+	['github-token', /\bgh[pousr]_[A-Za-z0-9]{36,}\b/g],
+	['openai-key', /\bsk-(?:proj-)?[A-Za-z0-9_-]{20,}\b/g],
+	['anthropic-key', /\bsk-ant-[A-Za-z0-9_-]{20,}\b/g],
+	['slack-token', /\bxox[abprs]-[A-Za-z0-9-]{10,}\b/g],
+	['google-api-key', /\bAIza[0-9A-Za-z_-]{35}\b/g],
+	['private-key-block', /-----BEGIN (?:RSA |EC |OPENSSH |PGP )?PRIVATE KEY-----/g],
+	['jwt', /\beyJ[A-Za-z0-9_-]{10,}\.eyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\b/g],
+]
+
+/**
+ * The union: every pattern above, plus everything `provider/errors.ts`
+ * carried that the narrow set did not cover — a generic key-prefix catch,
+ * a bearer-header pattern, and a JSON field-name scrubber.
+ *
+ * Two adjustments over a plain concatenation, both required so that
+ * deleting any ONE entry changes behaviour for exactly the shape that
+ * entry names, which is what the test suite for this module pins:
+ *
+ *  - `github-token` uses the wider `{20,}` threshold `provider/errors.ts`
+ *    used, not the guardrail's `{36,}` — the union takes the broader of
+ *    two disagreeing thresholds for the same vendor, never the narrower.
+ *  - The two broad `sk-`-family entries each carry a negative lookahead
+ *    excluding the `sk-ant-` and `sk-proj-` shapes, which a plain
+ *    `sk-`/`pk-`/`rk-` prefix scan would otherwise ALSO match. Without the
+ *    lookaheads, deleting the narrower entry for one of those shapes leaves a
+ *    value of that shape still caught — by the broad entries, in array order —
+ *    so the redaction succeeds while the label names the wrong issuer.
+ *
+ *    A mislabelled redaction is not a cosmetic problem: the label is what an
+ *    operator greps for when rotating one credential and not another. That is
+ *    also why the mutation check deletes each entry in turn and asserts only
+ *    its own sample breaks.
+ */
+export const LOG_SECRET_PATTERNS: readonly SecretPattern[] = [
+	['aws-access-key', /\b(?:AKIA|ASIA)[0-9A-Z]{16}\b/g],
+	['github-token', /\bgh[pousr]_[A-Za-z0-9]{20,}\b/g],
+	['anthropic-key', /\bsk-ant-[A-Za-z0-9_-]{20,}\b/g],
+	['openai-key', /\bsk-(?!ant-)(?:proj-)?[A-Za-z0-9_-]{20,}\b/g],
+	['slack-token', /\bxox[abprs]-[A-Za-z0-9-]{10,}\b/g],
+	['google-api-key', /\bAIza[0-9A-Za-z_-]{35}\b/g],
+	['private-key-block', /-----BEGIN (?:RSA |EC |OPENSSH |PGP )?PRIVATE KEY-----/g],
+	['jwt', /\beyJ[A-Za-z0-9_-]{10,}\.eyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\b/g],
+	['npm-token', /\bnpm_[A-Za-z0-9]{20,}\b/g],
+	['bearer-token', /\bBearer\s+[A-Za-z0-9._~+/-]{12,}=*/gi],
+	['generic-key', /\b(?:sk[-_](?!ant-|proj-)|pk[-_]|rk[-_])[A-Za-z0-9_-]{12,}\b/g],
+	['json-secret-field', /"(?:api[_-]?key|authorization|token|secret|password)"\s*:\s*"[^"]*"/gi],
+]

package/src/constants/telemetry/index.ts

@@ -54,4 +54,102 @@ export const NAMZU = {
 	CACHE_READ_TOKENS: 'namzu.cache.read_tokens',
 	CACHE_WRITE_TOKENS: 'namzu.cache.write_tokens',
 	CACHE_DISCOUNT: 'namzu.cache.discount',
+
+	// Correlation attributes for the run's own logger — see
+	// RunContextFactory.buildLogger (runtime/query/context.ts). RUN_ID above
+	// already covered the run itself; these are the layers above it
+	// (Tenant -> Project -> Thread -> Session -> Run, Convention #17) that
+	// used to reach the run's logger as four bare, un-namespaced keys.
+	SESSION_ID: 'namzu.session.id',
+	THREAD_ID: 'namzu.thread.id',
+	PROJECT_ID: 'namzu.project.id',
+	TENANT_ID: 'namzu.tenant.id',
+	// Set only when a run was started by another run (the sub-agent gateway
+	// path) — see query()'s params.parentRunId in runtime/query/index.ts.
+	// Previously reached the RunContext's own fields but never the logger.
+	RUN_PARENT_ID: 'namzu.run.parent_id',
+
+	// AbstractAgent's per-instance identity (agents/AbstractAgent.ts). The id
+	// half reuses GENAI.AGENT_ID — an agent's id is the same concept whether
+	// it is read off a span or a log record, and GENAI.AGENT_ID already
+	// exists and is already bound at the run's own correlated logger and
+	// root span. TYPE has no GENAI analogue, so it is new.
+	AGENT_TYPE: 'namzu.agent.type',
+
+	// ManagedRegistry's per-subclass distinction (registry/ManagedRegistry.ts).
+	// scope.name is fixed to 'registry' for every ManagedRegistry subclass —
+	// they all log through this one file — so the per-instance name that
+	// `component: config.componentName` used to carry moves here instead.
+	// `ManagedRegistryConfig.componentName`'s FIELD NAME is unchanged.
+	REGISTRY_NAME: 'namzu.registry.name',
+
+	// InMemoryCredentialVault (vault/InMemoryCredentialVault.ts) — closes a
+	// PRE-EXISTING violation of "no attribute string literal at a call
+	// site": both keys already existed as raw string literals there before
+	// this change. Values are unchanged.
+	CREDENTIAL_ID: 'namzu.credential.id',
+	CREDENTIAL_LABEL: 'namzu.credential.label',
+
+	// MCPClient (connector/mcp/client.ts). SERVER_ID is the OPERATOR's own
+	// configured identifier for the connector instance being dialed;
+	// SERVER_NAME is the REMOTE server's own self-reported name from its
+	// initialize response — kept separate on purpose, since the remote's
+	// self-report is attacker-influenced data (see
+	// connector/mcp/__tests__/a-server-cannot-forge-a-second-log-line.test.ts).
+	// SERVER_NAME closes the same kind of pre-existing literal violation as
+	// the two CREDENTIAL_* keys above.
+	SERVER_ID: 'namzu.connector.server.id',
+	SERVER_NAME: 'namzu.connector.server.name',
+
+	// The MCP server this process HOSTS (connector/mcp/server/server.ts), not
+	// one it dials. Deliberately not SERVER_ID above: that key is the client
+	// side's identifier for a remote, and a record carrying both concepts
+	// under one name is the collision the namespace rule exists to stop. The
+	// value is an `MCPServerId` minted here, so unlike SERVER_NAME it is not
+	// attacker-influenced.
+	MCP_SERVER_ID: 'namzu.mcp.server.id',
+
+	// The concrete subclass behind a base class that logs on its children's
+	// behalf — the same shape as REGISTRY_NAME above, and for the same
+	// reason: `scope.name` is the MODULE (`connector/base`, `execution/base`)
+	// because that is the file the record is emitted from, so the subclass
+	// identity every one of those records used to carry as `component:
+	// this.constructor.name` needs somewhere to go that is not the scope.
+	CONNECTOR_TYPE: 'namzu.connector.type',
+	EXECUTION_TYPE: 'namzu.execution.type',
+
+	// LocalSandbox (sandbox/provider/local.ts). The file hosts two logging
+	// classes — the sandbox and its provider — and both scope to
+	// `sandbox/provider/local`, so this id is what separates one sandbox's
+	// records from the provider's and from each other's.
+	SANDBOX_ID: 'namzu.sandbox.id',
 } as const
+
+/**
+ * The boot narrative's closed event-name vocabulary — every `eventName` the
+ * SDK itself emits between process start and `namzu.boot.ready`. A call
+ * site spells `BOOT_EVENT_NAMES.X`, not the literal string, so a typo
+ * becomes a missing property at compile time rather than a name that
+ * silently never matches a host's filter.
+ *
+ * `BootEventName` is DERIVED from this record rather than declared beside
+ * it, so the two cannot drift — there is only one place a member is added.
+ * `LogRecord.eventName` itself stays `string`, not this union: widening it
+ * to a fixed union would make the field unusable for a future emitter
+ * naming events from a different vocabulary.
+ */
+export const BOOT_EVENT_NAMES = {
+	BOOT_START: 'namzu.boot.start',
+	CONFIG_RESOLVED: 'namzu.config.resolved',
+	SANDBOX_RESOLVED: 'namzu.sandbox.resolved',
+	PROVIDER_RESOLVED: 'namzu.provider.resolved',
+	CAPABILITY_DETECTED: 'namzu.capability.detected',
+	CAPABILITY_BROKEN: 'namzu.capability.broken',
+	TELEMETRY_STATUS: 'namzu.telemetry.status',
+	MIGRATION_COMPLETED: 'namzu.migration.completed',
+	DISCOVERY_COMPLETED: 'namzu.discovery.completed',
+	BOOT_REFUSED: 'namzu.boot.refused',
+	BOOT_READY: 'namzu.boot.ready',
+} as const
+
+export type BootEventName = (typeof BOOT_EVENT_NAMES)[keyof typeof BOOT_EVENT_NAMES]

package/src/contracts/api.ts

@@ -149,12 +149,23 @@ export type StreamEventType =
 	| 'run.resuming'
 	| 'iteration.started'
 	| 'iteration.completed'
+	/**
+	 * Who answers when this run asks a human, changed mid-run.
+	 *
+	 * Wire-visible for the same reason `compaction.completed` is: an
+	 * operator watching a live run needs to see supervision loosen, not
+	 * infer it from approvals that stopped arriving. Names only — the wire
+	 * cannot carry a handler.
+	 */
+	| 'approval_policy.changed'
 	/**
 	 * A compaction pass replaced a span of history with a summary. Wire-
 	 * visible because the operation is destructive: a client rendering the
 	 * transcript needs to know its middle was dropped, not infer it.
 	 */
 	| 'compaction.completed'
+	/** Oversized tool results were emptied instead of the history summarized. */
+	| 'compaction.tool_results_cleared'
 	| 'compaction.failed'
 	/** A guardrail refused or corrected the run. */
 	| 'guardrail.triggered'

package/src/deprecated-aliases.ts

@@ -0,0 +1,86 @@
+/**
+ * Old spellings of renamed exports, kept alive for one deprecation window.
+ *
+ * SemVer's guidance, and this repo's rule, is that a removal is preceded by
+ * at least one minor release carrying the deprecation — so a consumer has a
+ * version where their code still compiles and warns. These are that version.
+ * Nothing in this tree imports from here; every in-tree call site moved to
+ * the new name in the same commit that added it, because an alias that the
+ * kernel itself still uses is not a deprecation, it is a second name.
+ *
+ * **Why each pair is written as a `const` plus a `type` rather than
+ * `export { New as Old }`.** The re-export form cannot carry a JSDoc tag on
+ * the alias: the tag lands on the original declaration or nowhere, so
+ * `Registry` would ship with no `@deprecated` marker at all. Nothing would
+ * fail — a consumer's editor simply would not strike it through, and the
+ * public-surface gate's `deprecated` view would not list it, which is the
+ * one place a reviewer looks to confirm a window is actually open. Declaring
+ * the pair explicitly puts the tag on a declaration of our own, and the two
+ * declarations merge across the value and type namespaces so a name used as
+ * both — every class here — keeps working in both positions.
+ *
+ * So: do not "simplify" these to `export { X as Y }`. It compiles, it passes
+ * the tests, and it silently empties the deprecated view.
+ */
+
+import { AuthorizationGate } from './authorization/gate.js'
+import { collectChatCompletion } from './provider/collect-chat-completion.js'
+import { BaseRegistry } from './registry/BaseRegistry.js'
+import { PromptCache, type PromptCacheConfig } from './runtime/query/prompt-cache.js'
+import { LocalTaskScheduler } from './scheduler/local.js'
+
+/**
+ * @deprecated Renamed to {@link collectChatCompletion}. Removed in the next
+ * major. The old name said nothing about what it collects; it drains a
+ * `StreamChunk` iterable into a `ChatCompletionResponse`.
+ */
+export const collect = collectChatCompletion
+
+/**
+ * @deprecated Renamed to {@link BaseRegistry}. Removed in the next major.
+ * The bare name read as the general-purpose registry while sitting beside
+ * seven domain-qualified siblings in the same barrel; it is the base class.
+ */
+export const Registry = BaseRegistry
+/**
+ * @deprecated Renamed to {@link BaseRegistry}. Removed in the next major.
+ */
+export type Registry<TDefinition> = BaseRegistry<TDefinition>
+
+/**
+ * @deprecated Renamed to {@link PromptCache}. Removed in the next major. The
+ * cluster named one input two ways a single call apart —
+ * `new ContextCache(ContextCacheConfig)` then `.getSystemPrompt(PromptCacheInput)`.
+ */
+export const ContextCache = PromptCache
+/**
+ * @deprecated Renamed to {@link PromptCache}. Removed in the next major.
+ */
+export type ContextCache = PromptCache
+
+/**
+ * @deprecated Renamed to {@link PromptCacheConfig}. Removed in the next major.
+ */
+export type ContextCacheConfig = PromptCacheConfig
+
+/**
+ * @deprecated Renamed to {@link LocalTaskScheduler}. Removed in the next
+ * major. It schedules in-process agent tasks; it is not a facade over
+ * anything external, which is what "gateway" told a reader to expect.
+ */
+export const LocalTaskGateway = LocalTaskScheduler
+/**
+ * @deprecated Renamed to {@link LocalTaskScheduler}. Removed in the next major.
+ */
+export type LocalTaskGateway = LocalTaskScheduler
+
+/**
+ * @deprecated Renamed to {@link AuthorizationGate}. Removed in the next
+ * major. It decides whether a tool call is permitted before the call runs;
+ * it does not verify anything after the fact.
+ */
+export const VerificationGate = AuthorizationGate
+/**
+ * @deprecated Renamed to {@link AuthorizationGate}. Removed in the next major.
+ */
+export type VerificationGate = AuthorizationGate

package/src/eval/judge.ts

@@ -1,4 +1,4 @@
-import { collect } from '../provider/collect.js'
+import { collectChatCompletion } from '../provider/collect-chat-completion.js'
 import type { LLMProvider } from '../types/provider/interface.js'
 import type { EvalCase, EvalRun, Score, Scorer } from './types.js'
 
@@ -210,7 +210,7 @@ export function judgeScorer(config: JudgeScorerConfig): Scorer {
 	return {
 		name: config.name ?? 'judge',
 		async score(run: EvalRun, evalCase: EvalCase): Promise<Score> {
-			const response = await collect(
+			const response = await collectChatCompletion(
 				config.provider.chatStream({
 					model: config.model,
 					messages: [{ role: 'user', content: buildPrompt(config, run, evalCase, scale) }],

package/src/execution/base.ts

@@ -1,6 +1,8 @@
+import { NAMZU } from '../constants/telemetry/index.js'
 import type { ExecutionContextLifecycle, ExecutionEnvironment } from '../types/execution/index.js'
 import { toErrorMessage } from '../utils/error.js'
-import { type Logger, getRootLogger } from '../utils/logger.js'
+import { SCOPE_ATTRIBUTE } from '../utils/log/types.js'
+import { type Logger, resolveLogger } from '../utils/logger.js'
 
 export interface BaseExecutionEvent {
 	type: string
@@ -18,8 +20,11 @@ export abstract class BaseExecutionContext implements ExecutionContextLifecycle
 	protected ready = false
 	private listeners: ExecutionEventListener[] = []
 
-	constructor() {
-		this.log = getRootLogger().child({ component: this.constructor.name })
+	constructor(log?: Logger) {
+		this.log = resolveLogger(log).child({
+			[SCOPE_ATTRIBUTE]: 'execution/base',
+			[NAMZU.EXECUTION_TYPE]: this.constructor.name,
+		})
 	}
 
 	async initialize(): Promise<void> {
@@ -28,11 +33,17 @@ export abstract class BaseExecutionContext implements ExecutionContextLifecycle
 			this.ready = true
 			this.emit({ type: 'context_initialized', contextId: this.id, environment: this.environment })
 			this.emit({ type: 'context_ready', contextId: this.id })
-			this.log.info(`Execution context initialized: ${this.id} (${this.environment})`)
+			this.log.info('Execution context initialized', {
+				'namzu.execution.context_id': this.id,
+				'namzu.execution.environment': this.environment,
+			})
 		} catch (err) {
 			const message = toErrorMessage(err)
 			this.emit({ type: 'context_error', contextId: this.id, error: message })
-			this.log.error(`Execution context initialization failed: ${this.id}`, { error: message })
+			this.log.error('Execution context initialization failed', {
+				'namzu.execution.context_id': this.id,
+				'exception.message': message,
+			})
 			throw err
 		}
 	}
@@ -47,7 +58,7 @@ export abstract class BaseExecutionContext implements ExecutionContextLifecycle
 		} finally {
 			this.ready = false
 			this.emit({ type: 'context_teardown', contextId: this.id })
-			this.log.info(`Execution context torn down: ${this.id}`)
+			this.log.info('Execution context torn down', { 'namzu.execution.context_id': this.id })
 		}
 	}
 
@@ -66,7 +77,7 @@ export abstract class BaseExecutionContext implements ExecutionContextLifecycle
 				listener(event)
 			} catch (err) {
 				this.log.error('Execution context event listener error', {
-					error: toErrorMessage(err),
+					'exception.message': toErrorMessage(err),
 				})
 			}
 		}