@namzu/sdk 27.0.0 → 28.0.0

package/src/types/topic/objective.ts

@@ -0,0 +1,93 @@
+import type { RunId, TenantId, TopicId } from '../ids/index.js'
+
+/**
+ * Work that outlives one run.
+ *
+ * Nothing in this kernel survived a single `query()` call. `stopWhen` and
+ * `prepareStep` shape one loop, the completion inbox holds one run open for
+ * a worker, and the topic manager owned a container with no work state in
+ * it at all — so a host wanting "keep going until X is done, stop safely if
+ * it stalls or runs long, let a human pause and inspect" had to hand-roll
+ * the store, the round cap and the compare-and-set outside the SDK.
+ *
+ * The Topic's own docstring already called it "one per objective or
+ * line-of-work". This is that objective, written down.
+ */
+
+export type ObjectivePhase = 'active' | 'paused' | 'blocked' | 'complete'
+
+/** Why an objective stopped, in a form a caller can branch on. */
+export interface ObjectiveBlock {
+	/**
+	 * A code, not just prose. `round_cap` and "the model gave up" are
+	 * different situations with different next moves, and a message alone
+	 * makes a host parse English to tell them apart.
+	 */
+	readonly code: 'round_cap' | 'runner_failed' | 'external'
+	readonly message: string
+}
+
+export interface TopicObjective {
+	readonly id: string
+	readonly topicId: TopicId
+	readonly tenantId: TenantId
+	/** Compare-and-set counter, `0` before the first write. */
+	readonly revision: number
+	readonly objective: string
+	readonly phase: ObjectivePhase
+	readonly blockedReason?: ObjectiveBlock
+	/**
+	 * The hard stop.
+	 *
+	 * Not a suggestion and not a timeout: an objective that cannot tell it
+	 * is stuck will keep spending money on rounds that make no progress, and
+	 * a wall-clock bound stops a slow objective rather than a stalled one.
+	 */
+	readonly maxRounds: number
+	/**
+	 * Rounds BEGUN, not rounds finished.
+	 *
+	 * Debited before the work runs, so a round that crashes still counts. A
+	 * counter that only advanced on success lets an objective failing every
+	 * round spin forever, which is precisely the runaway the cap exists to
+	 * stop.
+	 */
+	readonly roundsStarted: number
+	readonly lastRunId?: RunId
+	readonly updatedAt: number
+}
+
+/** A write whose `revision` no longer matches what is stored. */
+export class StaleObjectiveError extends Error {
+	readonly details: { id: string; expectedRevision: number; actualRevision: number }
+
+	constructor(details: { id: string; expectedRevision: number; actualRevision: number }) {
+		super(
+			`Stale objective ${details.id}: expected revision=${details.expectedRevision}, actual=${details.actualRevision}`,
+		)
+		this.name = 'StaleObjectiveError'
+		this.details = details
+	}
+}
+
+/** Why an `advanceObjective` did nothing. */
+export interface ObjectiveRefusal {
+	readonly kind: 'refused'
+	readonly reason: string
+	readonly phase: ObjectivePhase
+}
+
+export interface ObjectiveAdvance {
+	readonly kind: 'advanced'
+	readonly objective: TopicObjective
+}
+
+export type ObjectiveAdvanceResult = ObjectiveAdvance | ObjectiveRefusal
+
+/** What one round decided. */
+export interface ObjectiveRoundVerdict {
+	/** `undefined` leaves the phase alone: the round ran and said nothing. */
+	readonly phase?: Extract<ObjectivePhase, 'complete' | 'blocked'>
+	readonly blockedReason?: ObjectiveBlock
+	readonly runId?: RunId
+}

package/src/types/topic/state.ts

@@ -0,0 +1,60 @@
+import type { TenantId, TopicId } from '../ids/index.js'
+import type { PermissionMode } from '../permission/index.js'
+
+/**
+ * State that outlives a run but belongs to the conversation, not to a run.
+ *
+ * `PermissionMode` was resolved once per run and copied into the executor,
+ * so leaving plan mode meant ending the run and starting a fresh one with
+ * `permissionMode: 'auto'` — discarding the in-flight step and the
+ * tool-schema context with it. The look-around, propose, get-approval,
+ * continue-in-the-SAME-conversation flow could not be built on that, and
+ * `approve_plan` already existed with its approval changing nothing about
+ * the mode.
+ *
+ * Its own record beside the Topic rather than a field on it, with its own
+ * schema version. The Topic record is identity and ownership; this is
+ * mutable session state that changes several times within one conversation
+ * and whose writers are not the Topic's writers. Merging them would make
+ * every mode toggle a CAS conflict against a title rename.
+ */
+export interface TopicState {
+	readonly topicId: TopicId
+	readonly tenantId: TenantId
+	/**
+	 * Compare-and-set counter, starting at 0 for a record's first write.
+	 *
+	 * Separate from the Topic's `ownerVersion` on purpose — see above. A
+	 * host toggling the mode and a manager renaming the topic must not
+	 * invalidate each other.
+	 */
+	readonly revision: number
+	readonly permissionMode: PermissionMode
+	/**
+	 * Messages left for the run that has not started yet.
+	 *
+	 * On the same record as the mode and under the same revision, so a host
+	 * queueing a message and one toggling the mode cannot silently overwrite
+	 * each other — they collide loudly instead, which is what a shared
+	 * conversation needs.
+	 */
+	readonly queuedMessages?: readonly import('../message/index.js').Message[]
+	readonly updatedAt: number
+}
+
+/** A write whose `revision` no longer matches what is stored. */
+export class StaleTopicStateError extends Error {
+	readonly details: {
+		topicId: TopicId
+		expectedRevision: number
+		actualRevision: number
+	}
+
+	constructor(details: { topicId: TopicId; expectedRevision: number; actualRevision: number }) {
+		super(
+			`Stale topic state for ${details.topicId}: expected revision=${details.expectedRevision}, actual=${details.actualRevision}`,
+		)
+		this.name = 'StaleTopicStateError'
+		this.details = details
+	}
+}

package/src/types/topic/store.ts

@@ -0,0 +1,101 @@
+/**
+ * TopicStore — canonical persistence contract for the Topic layer
+ * (Project → **Topic** → Session → SubSession → Run).
+ *
+ * Topics are pure containers (Phase 0 decision B.1). They have no own
+ * message stream and no fan-in `deriveStatus()` — status is owner-managed
+ * (`'open' | 'archived'`). Every accessor takes explicit {@link TenantId};
+ * cross-tenant access rejects with `TenantIsolationError` (Convention #17).
+ *
+ * Read accessors return `null` when the resource does not exist for the
+ * supplied tenant (deny-by-default surface). Callers branch on missing
+ * explicitly — no fallback substitution.
+ *
+ * `deleteTopic` is intentionally a dumb record-delete at this layer:
+ * it does NOT walk session ownership. The "reject when sessions attached"
+ * precondition lives in {@link import('../../manager/topic/lifecycle.js').TopicManager}
+ * where both stores are in scope. Keeping TopicStore free of cross-store
+ * awareness preserves the single-boundary ownership boundary that Phase 2
+ * has just introduced for this layer (Convention #0).
+ *
+ * NZ-TOPIC-01 renamed this from `ThreadStore`/`createThread` etc, leaving
+ * the `threadId` parameter below alone — it is the FK field a Session
+ * carries to its owning Topic, and that rename had its own data-migration
+ * story (persisted `session.json` records already on disk, see
+ * `store/session/disk.ts`). NZ-TOPIC-03 lands it: the parameter below is
+ * `topicId` now, matching the `Session.topicId` it identifies.
+ */
+
+import type { Topic } from '../../types/topic/entity.js'
+import type { TenantId } from '../ids/index.js'
+import type { ProjectId, TopicId } from '../session/ids.js'
+
+/**
+ * Params for {@link TopicStore.createTopic}. The store owns id generation,
+ * `ownerVersion` initialization (0 at create), and timestamps.
+ */
+export interface CreateTopicParams {
+	projectId: ProjectId
+	/**
+	 * User-facing display label. Not unique within the project — see
+	 * {@link Topic} JSDoc. Empty strings are permitted; callers that require
+	 * a label should validate at the API layer.
+	 */
+	title: string
+}
+
+/**
+ * Canonical persistence contract for the Topic layer. Every accessor takes
+ * explicit `tenantId`; cross-tenant reads/writes reject with
+ * `TenantIsolationError` (`session/errors.ts`, Convention #17).
+ */
+export interface TopicStore {
+	/**
+	 * Persist a new Topic under the given project. Returns the minted
+	 * {@link Topic} with `ownerVersion: 0` and freshly-generated
+	 * {@link import('../ids/index.js').TopicId}. Callers must ensure the parent
+	 * project exists and belongs to the same tenant — the store does not
+	 * validate project ownership (that is a cross-store precondition owned by
+	 * the manager).
+	 */
+	createTopic(params: CreateTopicParams, tenantId: TenantId): Promise<Topic>
+
+	/**
+	 * Read a Topic by id. Returns `null` when absent. Cross-tenant reads
+	 * reject with `TenantIsolationError`.
+	 */
+	getTopic(topicId: TopicId, tenantId: TenantId): Promise<Topic | null>
+
+	/**
+	 * Persist a mutation to a Topic record. CAS on `ownerVersion`: if the
+	 * supplied `topic.ownerVersion` does not match the persisted version,
+	 * rejects with {@link import('../../session/errors.js').StaleThreadError}
+	 * (class name unchanged this release). On success the write commits with
+	 * `ownerVersion + 1` and a refreshed `updatedAt`.
+	 *
+	 * Archival transition (`status: 'open' → 'archived'`) shares this path;
+	 * the caller is responsible for verifying that no non-terminal Sessions
+	 * are attached before flipping (see TopicManager.archive).
+	 */
+	updateTopic(topic: Topic, tenantId: TenantId): Promise<void>
+
+	/**
+	 * Hard-delete a Topic record. Idempotent — absent topics succeed as a
+	 * no-op. Rejects with `TenantIsolationError` on cross-tenant access.
+	 *
+	 * **Does NOT cascade to child Sessions** — the caller (typically
+	 * TopicManager) enforces the precondition that no Sessions reference
+	 * this topic. Convention #5: deny-by-default, no implicit cascade.
+	 */
+	deleteTopic(topicId: TopicId, tenantId: TenantId): Promise<void>
+
+	/**
+	 * List all Topics under a project for the given tenant, ordered by
+	 * `createdAt` ascending. Returns an empty array when none exist.
+	 * Cross-tenant reads reject with `TenantIsolationError`.
+	 *
+	 * The return shape is a concrete snapshot — callers that mutate the
+	 * result array do not affect store state.
+	 */
+	listTopics(projectId: ProjectId, tenantId: TenantId): Promise<readonly Topic[]>
+}

package/src/types/workspace/ref.ts

@@ -42,6 +42,13 @@ export type WorkspaceBackendMeta = GitWorktreeBackendMeta
  * Persisted ref to a provisioned workspace. Every {@link Session} with a
  * running Run persists a {@link WorkspaceRef} so recovery after process
  * restart is possible (session-hierarchy.md §7.1).
+ *
+ * NOT `Project.rootPath`. This is per-RUN provisioning — a git worktree cut
+ * for one run and discarded after it, which may be a different directory
+ * entirely. `Project.rootPath` is the durable binding a host uses to answer
+ * "which project is this directory" across sessions and process restarts.
+ * The two words are close enough that the distinction has been rediscovered
+ * more than once; it is written here so it does not have to be again.
  */
 export interface WorkspaceRef {
 	id: WorkspaceId

package/src/utils/abort.ts

@@ -27,7 +27,22 @@ import { toErrorMessage } from './error.js'
  */
 export function abortReasonText(reason: unknown): string | undefined {
 	if (!(reason instanceof Error)) return undefined
-	if (reason.name === 'AbortError' || reason.name === 'TimeoutError') return undefined
+	// `RunCancelled` carries a machine-readable CAUSE ('user' | 'parent' |
+	// 'budget' | 'hook'), and rendering it here would print "was cancelled:
+	// run cancelled by parent" — the same noise the two names above are
+	// suppressed for. A reader wanting the cause asks `cancelCauseOf`.
+	//
+	// By name, not by class, for the reason this whole function is: a reason
+	// crosses a package boundary where `instanceof` stops holding across
+	// duplicate copies. Importing the class here would also close a cycle
+	// between `utils/` and `types/run/`.
+	if (
+		reason.name === 'AbortError' ||
+		reason.name === 'TimeoutError' ||
+		reason.name === 'RunCancelled'
+	) {
+		return undefined
+	}
 	const text = toErrorMessage(reason).trim()
 	return text.length > 0 ? text : undefined
 }

package/src/utils/hash.ts

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

package/src/utils/id.ts

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

package/src/utils/log/attributes.ts

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