@namzu/sdk 27.1.0 → 28.0.0

package/src/scheduler/delegating.ts

@@ -0,0 +1,297 @@
+import { EMPTY_TOKEN_USAGE, ZERO_COST } from '../constants/limits.js'
+import type { Delegate, DelegateRequest, DelegateResult } from '../types/agent/delegate.js'
+import type { CreateTaskOptions, TaskHandle, TaskScheduler } from '../types/agent/scheduler.js'
+import type { AgentTaskState } from '../types/agent/task.js'
+import type { RunExecutionStatus } from '../types/common/index.js'
+import type { TaskId } from '../types/ids/index.js'
+import { asRunId, generateTaskId } from '../utils/id.js'
+
+/**
+ * Presents a set of foreign delegates as a `TaskScheduler`.
+ *
+ * The two delegation tools, the completion inbox and the sibling-failure
+ * policy all speak `TaskScheduler`, and none of them should have to learn
+ * that a specialist moved out of process. So the seam is here rather than
+ * in the tools: an id this knows about is dispatched to its `Delegate`, and
+ * anything else falls through to the local scheduler untouched.
+ *
+ * **The mapping onto `TaskHandle` is the load-bearing part.** `taskSucceeded`
+ * and `taskFailed` require the gateway state and the run status to AGREE,
+ * because locally they are two independent authorities and a check reading
+ * only one of them has already shipped a failed worker as an answer. A
+ * foreign delegate has only its own word, so both fields are written from
+ * that one answer — which keeps every existing predicate correct without
+ * inventing a second authority that would only ever agree with the first.
+ */
+
+export interface DelegatingTaskSchedulerConfig {
+	/**
+	 * Where an id no delegate claims goes.
+	 *
+	 * Optional, and its absence is a real configuration: a host that
+	 * delegates ONLY to foreign peers has no local scheduler to fall back
+	 * to, and an unknown id there is a caller error rather than something to
+	 * pass along.
+	 */
+	readonly local?: TaskScheduler
+	readonly delegates: readonly Delegate[]
+}
+
+/** Two delegates, or a delegate and nothing, claiming one id. */
+export class DelegateIdCollisionError extends Error {
+	readonly details: { id: string }
+
+	constructor(details: { id: string }) {
+		super(`Two delegates are registered under the id "${details.id}".`)
+		this.name = 'DelegateIdCollisionError'
+		this.details = details
+	}
+}
+
+/** A delegate whose declared capabilities do not match its methods. */
+export class DelegateCapabilityMismatchError extends Error {
+	readonly details: { id: string; capability: string }
+
+	constructor(details: { id: string; capability: string }) {
+		super(
+			`Delegate "${details.id}" declares capabilities.${details.capability} but does not implement it.`,
+		)
+		this.name = 'DelegateCapabilityMismatchError'
+		this.details = details
+	}
+}
+
+/** An operation the delegate said it cannot do. */
+export class DelegateCapabilityError extends Error {
+	readonly details: { id: string; capability: string }
+
+	constructor(details: { id: string; capability: string }) {
+		super(`Delegate "${details.id}" does not support ${details.capability}.`)
+		this.name = 'DelegateCapabilityError'
+		this.details = details
+	}
+}
+
+/** An agent id nothing can serve. */
+export class NoDelegateError extends Error {
+	readonly details: { agentId: string }
+
+	constructor(details: { agentId: string }) {
+		super(
+			`No delegate is registered for "${details.agentId}", and this scheduler has no local fallback.`,
+		)
+		this.name = 'NoDelegateError'
+		this.details = details
+	}
+}
+
+/**
+ * The two authorities a delegate's one answer is written onto.
+ *
+ * **Cancelled is not failed, and conflating them cancels a fan-out.**
+ * `taskFailed` is `state === 'failed' || result.status === 'failed'`, and
+ * `SiblingFailurePolicy: 'cancel-siblings'` acts on it — so writing
+ * `status: 'failed'` for a delegation somebody deliberately stopped would
+ * tear down every healthy sibling as a consequence of the stop. The first
+ * draft here did exactly that, in the same commit as a comment saying it
+ * must not.
+ *
+ * Note the spelling difference, which is the tree's and not a typo:
+ * `AgentTaskState` has `'canceled'`, `RunExecutionStatus` has
+ * `'cancelled'`. A table is what keeps that from being written from memory
+ * at each site.
+ */
+const OUTCOME: Record<
+	DelegateResult['status'],
+	{ readonly state: AgentTaskState; readonly status: RunExecutionStatus }
+> = {
+	completed: { state: 'completed', status: 'completed' },
+	failed: { state: 'failed', status: 'failed' },
+	cancelled: { state: 'canceled', status: 'cancelled' },
+}
+
+interface Entry {
+	handle: TaskHandle
+	delegate: Delegate
+	controller: AbortController
+	settled: Promise<void>
+}
+
+export class DelegatingTaskScheduler implements TaskScheduler {
+	private readonly byId = new Map<string, Delegate>()
+	private readonly tasks = new Map<TaskId, Entry>()
+	private readonly listeners = new Set<(handle: TaskHandle) => void>()
+
+	constructor(private readonly config: DelegatingTaskSchedulerConfig) {
+		for (const delegate of config.delegates) {
+			if (this.byId.has(delegate.id)) {
+				// Refused rather than resolved by precedence. A precedence rule
+				// makes which delegate answers depend on registration order,
+				// which is not visible at the call site that gets the wrong one.
+				throw new DelegateIdCollisionError({ id: delegate.id })
+			}
+			if (delegate.capabilities.continue && typeof delegate.continue !== 'function') {
+				// Checked at registration, not at the call. A capability that
+				// claims a method the object does not have is a lie the caller
+				// would otherwise find mid-delegation, with a worker running.
+				throw new DelegateCapabilityMismatchError({ id: delegate.id, capability: 'continue' })
+			}
+			this.byId.set(delegate.id, delegate)
+		}
+	}
+
+	/** The delegate serving this id, or `undefined` for the local path. */
+	delegateFor(agentId: string): Delegate | undefined {
+		return this.byId.get(agentId)
+	}
+
+	async createTask(options: CreateTaskOptions): Promise<TaskHandle> {
+		const delegate = this.byId.get(options.agentId)
+		if (!delegate) {
+			if (!this.config.local) throw new NoDelegateError({ agentId: options.agentId })
+			return await this.config.local.createTask(options)
+		}
+
+		const taskId = generateTaskId()
+		const controller = new AbortController()
+		const request: DelegateRequest = {
+			prompt: options.prompt,
+			workingDirectory: options.workingDirectory,
+			...(options.runtimeContext ? { runtimeContext: options.runtimeContext } : {}),
+			...(options.configOverrides?.env ? { env: options.configOverrides.env } : {}),
+		}
+
+		const entry: Entry = {
+			handle: {
+				taskId,
+				agentId: options.agentId,
+				state: 'running',
+				createdAt: Date.now(),
+			},
+			delegate,
+			controller,
+			settled: Promise.resolve(),
+		}
+		this.tasks.set(taskId, entry)
+
+		entry.settled = (async () => {
+			let result: DelegateResult
+			try {
+				result = await delegate.dispatch(request, { signal: controller.signal })
+			} catch (err) {
+				// A delegate that threw failed; it did not vanish. Leaving the
+				// handle `running` would have `waitForTask` hang forever on a
+				// delegation that is already over.
+				result = {
+					status: 'failed',
+					error: err instanceof Error ? err.message : String(err),
+				}
+			}
+			entry.handle = this.settle(entry.handle, result)
+			for (const listener of this.listeners) listener(entry.handle)
+		})()
+
+		return entry.handle
+	}
+
+	private settle(handle: TaskHandle, result: DelegateResult): TaskHandle {
+		const outcome = OUTCOME[result.status]
+		return {
+			...handle,
+			state: outcome.state,
+			completedAt: Date.now(),
+			result: {
+				// A synthetic run record. The id names the task rather than
+				// borrowing a run id that does not exist: a foreign delegate has
+				// no run in this kernel, and minting a plausible-looking `run_`
+				// would put an id in the transcript that nothing can resolve.
+				runId: asRunId(`run_delegate_${handle.taskId}`),
+				status: outcome.status,
+				// Zero, and honestly so: this kernel did not spend these tokens
+				// and has no way to learn what the delegate spent. `ZERO_COST`
+				// carries no rate card for exactly this reason — a rate of zero
+				// would read as "the model is free" rather than "nobody priced
+				// this".
+				usage: { ...EMPTY_TOKEN_USAGE },
+				cost: { ...ZERO_COST },
+				iterations: 0,
+				durationMs: Date.now() - handle.createdAt,
+				messages: [],
+				...(result.output === undefined ? {} : { result: result.output }),
+				...(result.error === undefined ? {} : { lastError: result.error }),
+			},
+		}
+	}
+
+	async waitForTask(taskId: TaskId): Promise<TaskHandle> {
+		const entry = this.tasks.get(taskId)
+		if (!entry) {
+			if (!this.config.local) throw new Error(`No task ${taskId}.`)
+			return await this.config.local.waitForTask(taskId)
+		}
+		await entry.settled
+		return entry.handle
+	}
+
+	async continueTask(taskId: TaskId, message: string): Promise<void> {
+		const entry = this.tasks.get(taskId)
+		if (!entry) {
+			if (!this.config.local) throw new Error(`No task ${taskId}.`)
+			return await this.config.local.continueTask(taskId, message)
+		}
+		if (!entry.delegate.capabilities.continue || !entry.delegate.continue) {
+			// Refused, not silently dropped. A no-op here has the parent
+			// believe it steered a worker that never heard it — and it would
+			// go on believing that until the answer came back unchanged.
+			throw new DelegateCapabilityError({ id: entry.delegate.id, capability: 'continue' })
+		}
+		await entry.delegate.continue(message)
+	}
+
+	cancelTask(taskId: TaskId): void {
+		const entry = this.tasks.get(taskId)
+		if (!entry) {
+			this.config.local?.cancelTask(taskId)
+			return
+		}
+		if (!entry.delegate.capabilities.cancel) {
+			throw new DelegateCapabilityError({ id: entry.delegate.id, capability: 'cancel' })
+		}
+		controllerAbort(entry)
+	}
+
+	getTask(taskId: TaskId): TaskHandle | undefined {
+		return this.tasks.get(taskId)?.handle ?? this.config.local?.getTask(taskId)
+	}
+
+	listTasks(): TaskHandle[] {
+		// Both, because a supervisor listing its children should not have to
+		// know which of them happen to be foreign.
+		return [
+			...[...this.tasks.values()].map((e) => e.handle),
+			...(this.config.local?.listTasks() ?? []),
+		]
+	}
+
+	onTaskCompleted(callback: (handle: TaskHandle) => void): () => void {
+		this.listeners.add(callback)
+		const localOff = this.config.local?.onTaskCompleted(callback)
+		return () => {
+			this.listeners.delete(callback)
+			localOff?.()
+		}
+	}
+}
+
+/**
+ * Abort, and let the dispatch settle itself.
+ *
+ * Deliberately NOT writing the `canceled` state here. The delegate's own
+ * `dispatch` is what resolves — with `cancelled`, or with an answer it had
+ * already finished producing — and marking the handle from outside would
+ * race that: a delegate that completed a microsecond before the abort would
+ * be recorded as cancelled while its answer sat unread.
+ */
+function controllerAbort(entry: Entry): void {
+	entry.controller.abort()
+}

package/src/{gateway → scheduler}/local.ts

@@ -1,18 +1,20 @@
+import { GENAI } from '../constants/telemetry/index.js'
 import { taskFailed } from '../tools/coordinator/outcome.js'
 import type { AgentInput } from '../types/agent/base.js'
+import type { AgentManagerContract } from '../types/agent/manager.js'
 import type {
 	CreateTaskOptions,
 	SiblingFailurePolicy,
-	TaskGateway,
 	TaskHandle,
-} from '../types/agent/gateway.js'
-import type { AgentManagerContract } from '../types/agent/manager.js'
+	TaskScheduler,
+} from '../types/agent/scheduler.js'
 import type { AgentTaskContext } from '../types/agent/task.js'
 import type { TaskId } from '../types/ids/index.js'
 import { createUserMessage } from '../types/message/index.js'
 import type { RunEventListener } from '../types/run/events.js'
 import { toErrorMessage } from '../utils/error.js'
-import { getRootLogger } from '../utils/logger.js'
+import { SCOPE_ATTRIBUTE } from '../utils/log/types.js'
+import { type Logger, resolveLogger } from '../utils/logger.js'
 
 /**
  * How many launched tasks a gateway remembers.
@@ -25,7 +27,7 @@ import { getRootLogger } from '../utils/logger.js'
  */
 const GATEWAY_TASK_LEDGER_CAP = 1_000
 
-export class LocalTaskGateway implements TaskGateway {
+export class LocalTaskScheduler implements TaskScheduler {
 	private agentManager: AgentManagerContract
 	private taskContext: AgentTaskContext
 	private listener: RunEventListener | undefined
@@ -53,18 +55,25 @@ export class LocalTaskGateway implements TaskGateway {
 	private siblingFailurePolicy: SiblingFailurePolicy = 'continue'
 	/** See {@link onTaskProgress}. */
 	private readonly progressListeners = new Set<(taskId: TaskId) => void>()
+	/** Raw, unresolved — kept as the caller handed it so each of the two log
+	 * sites below resolves it independently via `resolveLogger`, rather than
+	 * this constructor baking in ONE `.child()` binding both would then share
+	 * (which would also change how many `component:` bindings this file has,
+	 * a different ratchet than the one this task moves). */
+	private readonly log?: Logger
 
 	constructor(
 		agentManager: AgentManagerContract,
 		taskContext: AgentTaskContext,
 		listener?: RunEventListener,
 		parentInput?: Pick<AgentInput, 'taskStore' | 'runtimeToolOverrides' | 'runtimeContext'>,
-		options?: { siblingFailurePolicy?: SiblingFailurePolicy },
+		options?: { siblingFailurePolicy?: SiblingFailurePolicy; log?: Logger },
 	) {
 		this.agentManager = agentManager
 		this.taskContext = taskContext
 		this.listener = listener
 		this.parentInput = parentInput
+		this.log = options?.log
 		if (options?.siblingFailurePolicy) {
 			this.siblingFailurePolicy = options.siblingFailurePolicy
 		}
@@ -169,11 +178,11 @@ export class LocalTaskGateway implements TaskGateway {
 				}
 			})
 			.catch((err) => {
-				getRootLogger()
-					.child({ component: 'LocalTaskGateway' })
+				resolveLogger(this.log)
+					.child({ [SCOPE_ATTRIBUTE]: 'scheduler/local' })
 					.error('Task completion tracking failed', {
-						taskId: task.taskId,
-						error: toErrorMessage(err),
+						'namzu.task.id': task.taskId,
+						'exception.message': toErrorMessage(err),
 					})
 			})
 
@@ -212,12 +221,12 @@ export class LocalTaskGateway implements TaskGateway {
 		}
 
 		if (cancelled.length > 0) {
-			getRootLogger()
-				.child({ component: 'LocalTaskGateway' })
+			resolveLogger(this.log)
+				.child({ [SCOPE_ATTRIBUTE]: 'scheduler/local' })
 				.info('Cancelled siblings after a child failed', {
-					failed: finished.taskId,
-					agentId: finished.agentId,
-					cancelled,
+					'namzu.scheduler.failed': finished.taskId,
+					[GENAI.AGENT_ID]: finished.agentId,
+					'namzu.scheduler.cancelled': cancelled,
 				})
 		}
 	}

package/src/session/actor-scope.ts

@@ -0,0 +1,121 @@
+import type { ActorRef } from '../types/session/actor.js'
+
+/**
+ * Walking the actor chain that was already there.
+ *
+ * `ActorRef`'s agent variant has carried `parentActor` since the 0.2.0
+ * design, and its docblock says permission audit events walk this chain to
+ * attribute a subagent's actions back to the originating user. Nothing
+ * walked it — `rg 'isDescendantOf|ancestor'` over this package found no
+ * reader at all. A declared hierarchy with no code that traverses it is a
+ * `declared-but-undriven` primitive, and every cross-tree concern that came
+ * along instead invented its own propagation: `resumeHandler` is threaded
+ * by hand at the spawn site, and a tool scope was about to be.
+ *
+ * **Not a parallel parent registry.** The obvious fix is a `WeakMap` from
+ * child to parent maintained by the manager, and it is the wrong one: the
+ * chain is already persisted on the actor, so a second structure gives the
+ * tree two answers to the same question that can disagree — and the one a
+ * check reads would be the one that is NOT written to disk.
+ */
+
+/**
+ * How far the walk goes before giving up.
+ *
+ * A chain is built by the manager one link per spawn, and the spawn depth
+ * limit is far below this — so reaching it means the chain is malformed or
+ * cyclic, not that somebody legitimately nested a hundred deep. Bounded
+ * rather than cycle-detected with a `Set` because the bound is the thing
+ * that must hold: a containment check that hangs is a denial of service on
+ * whatever holds the lock, and a check that allocates per call to prove a
+ * property nobody can trigger is worse than one that stops.
+ */
+export const MAX_ACTOR_CHAIN_DEPTH = 64
+
+/** The identifying fields of one link, ignoring what is above it. */
+function sameLink(a: ActorRef, b: ActorRef): boolean {
+	// Tenant first, and it is never implied. Two agents in different tenants
+	// can share an `agentId` — the ids are per-tenant, not global — so
+	// comparing on kind and id alone would let a chain in one tenant satisfy
+	// a containment check made about another.
+	if (a.tenantId !== b.tenantId) return false
+	if (a.kind !== b.kind) return false
+	switch (a.kind) {
+		case 'user':
+			return a.userId === (b as Extract<ActorRef, { kind: 'user' }>).userId
+		case 'agent':
+			return a.agentId === (b as Extract<ActorRef, { kind: 'agent' }>).agentId
+		case 'system':
+			return a.role === (b as Extract<ActorRef, { kind: 'system' }>).role
+	}
+}
+
+/**
+ * Same actor — identifying fields AND everything above them.
+ *
+ * An agent's `ActorRef` does not identify a spawn: it has no instance id, so
+ * a supervisor that spawns `agt_worker` twice produces two links that are
+ * field-for-field identical. What separates them is their lineage.
+ *
+ * So identity here is the whole chain, and that is the safe direction for
+ * the question this answers. Matching on the id alone would let an actor
+ * claim containment by NAME — hand the check an `agt_sup` assembled under a
+ * different user and it would report the two as the same supervisor. For an
+ * authorization decision that is precisely the wrong error to make, and the
+ * data to avoid it is already on the ref.
+ *
+ * Compared iteratively and bounded, not recursively: a cyclic chain must
+ * return an answer rather than exhaust the stack.
+ */
+function sameActor(a: ActorRef, b: ActorRef, maxDepth: number): boolean {
+	let left: ActorRef | undefined = a
+	let right: ActorRef | undefined = b
+	for (let depth = 0; depth < maxDepth; depth++) {
+		if (left === undefined || right === undefined) return left === right
+		if (!sameLink(left, right)) return false
+		left = left.kind === 'agent' ? left.parentActor : undefined
+		right = right.kind === 'agent' ? right.parentActor : undefined
+	}
+	// Both chains ran past the bound while still agreeing. Cannot be
+	// established, so it is not claimed.
+	return false
+}
+
+/** The chain from `actor` up to its root, newest first, `actor` included. */
+export function actorChain(
+	actor: ActorRef,
+	opts: { readonly maxDepth?: number } = {},
+): readonly ActorRef[] {
+	const max = opts.maxDepth ?? MAX_ACTOR_CHAIN_DEPTH
+	const chain: ActorRef[] = []
+	let current: ActorRef | undefined = actor
+	while (current && chain.length < max) {
+		chain.push(current)
+		current = current.kind === 'agent' ? current.parentActor : undefined
+	}
+	return chain
+}
+
+/**
+ * Whether `ancestor` appears strictly above `actor` in its chain.
+ *
+ * Strictly: an actor is not its own ancestor. The question this answers is
+ * "may what happened up there constrain what happens here", and an actor
+ * constraining itself is not a hierarchy fact — reading it as one makes
+ * every self-comparison silently true and hides a caller that passed the
+ * same actor twice by mistake.
+ *
+ * Returns `false` on a malformed or cyclic chain rather than throwing. The
+ * callers are authorization checks, and the honest answer to "is this
+ * contained by that" when the chain cannot be read is no.
+ */
+export function isDescendantOfActor(
+	actor: ActorRef,
+	ancestor: ActorRef,
+	opts: { readonly maxDepth?: number } = {},
+): boolean {
+	const chain = actorChain(actor, opts)
+	const max = opts.maxDepth ?? MAX_ACTOR_CHAIN_DEPTH
+	// `slice(1)` — skip the actor itself, per the strictness above.
+	return chain.slice(1).some((link) => sameActor(link, ancestor, max))
+}

package/src/session/errors.ts

@@ -9,7 +9,7 @@
 
 import type { SessionId, TenantId } from '../types/ids/index.js'
 import type { SessionStatus } from '../types/session/entity.js'
-import type { ProjectId, ThreadId } from '../types/session/ids.js'
+import type { ProjectId, TopicId } from '../types/session/ids.js'
 import type { WorkspaceBackendKind } from './workspace/driver.js'
 
 /**
@@ -36,6 +36,28 @@ export class TenantIsolationError extends Error {
  * when walking parent sub-session links encounters a revisit. Indicates store
  * corruption — the write path enforces acyclicity (session-hierarchy.md §4.5).
  */
+/**
+ * A second project was asked for on a directory that already has one.
+ *
+ * Refused rather than deduplicated. Returning the existing project would
+ * be the friendlier-looking answer and would silently discard the `name`
+ * and `config` the caller passed — they asked to CREATE something, and
+ * getting a different thing back with their arguments dropped is worse
+ * than an error. A caller who wanted the existing one asks for it by name
+ * with `findProjectByRootPath`.
+ *
+ * Carries the existing id, so recovering is one call rather than a search.
+ */
+export class ProjectRootPathTakenError extends Error {
+	override readonly name = 'ProjectRootPathTakenError'
+
+	constructor(readonly details: { rootPath: string; existingProjectId: ProjectId }) {
+		super(
+			`A project already exists for ${details.rootPath}: ${details.existingProjectId}. Use findProjectByRootPath to get it, or create this project without a rootPath.`,
+		)
+	}
+}
+
 export class AncestryCycleError extends Error {
 	readonly details: {
 		sessionId: SessionId
@@ -80,12 +102,12 @@ export class WorkspaceBackendError extends Error {
  */
 export class StaleThreadError extends Error {
 	readonly details: {
-		threadId: ThreadId
+		threadId: TopicId
 		expectedVersion: number
 		actualVersion: number
 	}
 
-	constructor(details: { threadId: ThreadId; expectedVersion: number; actualVersion: number }) {
+	constructor(details: { threadId: TopicId; expectedVersion: number; actualVersion: number }) {
 		super(
 			`Stale Thread ${details.threadId}: expected ownerVersion=${details.expectedVersion}, actual=${details.actualVersion}`,
 		)
@@ -131,11 +153,11 @@ export class StaleSessionError extends Error {
  */
 export class ThreadClosedError extends Error {
 	readonly details: {
-		threadId: ThreadId
+		threadId: TopicId
 		op: string
 	}
 
-	constructor(details: { threadId: ThreadId; op: string }) {
+	constructor(details: { threadId: TopicId; op: string }) {
 		super(`Thread ${details.threadId} is archived; operation '${details.op}' rejected`)
 		this.name = 'ThreadClosedError'
 		this.details = details
@@ -143,7 +165,7 @@ export class ThreadClosedError extends Error {
 }
 
 /**
- * Raised by {@link import('../manager/thread/lifecycle.js').ThreadManager.archive}
+ * Raised by {@link import('../manager/topic/lifecycle.js').TopicManager.archive}
  * and `.delete` when the Thread's session-presence precondition is violated:
  *
  * - `op: 'archive'` — at least one Session under the Thread is in a
@@ -165,7 +187,7 @@ export const THREAD_NOT_EMPTY_SAMPLE_LIMIT = 50
 
 export class ThreadNotEmptyError extends Error {
 	readonly details: {
-		threadId: ThreadId
+		threadId: TopicId
 		tenantId: TenantId
 		op: 'archive' | 'delete'
 		blockingSessions: ReadonlyArray<{ sessionId: SessionId; status: SessionStatus }>
@@ -173,7 +195,7 @@ export class ThreadNotEmptyError extends Error {
 	}
 
 	constructor(details: {
-		threadId: ThreadId
+		threadId: TopicId
 		tenantId: TenantId
 		op: 'archive' | 'delete'
 		blockingSessions: ReadonlyArray<{ sessionId: SessionId; status: SessionStatus }>

package/src/session/handoff/assignment.ts

@@ -10,7 +10,7 @@
 
 import type { SessionId, TenantId } from '../../types/ids/index.js'
 import type { ActorRef } from '../../types/session/actor.js'
-import type { HandoffId, ProjectId, ThreadId, WorkspaceId } from '../../types/session/ids.js'
+import type { HandoffId, ProjectId, TopicId, WorkspaceId } from '../../types/session/ids.js'
 
 /**
  * Handoff mode discriminator. `single` transfers ownership of the source
@@ -34,13 +34,13 @@ export interface HandoffAssignment {
 	tenantId: TenantId
 	/**
 	 * Topic-layer scope the source session belongs to. Handoff recipients
-	 * always land on the same Thread (cross-thread handoff is forbidden —
+	 * always land on the same Topic (cross-topic handoff is forbidden —
 	 * a new actor taking over a conversation stays on the same topic).
-	 * Validated against `source.threadId` at execute time.
+	 * Validated against `source.topicId` at execute time.
 	 */
-	threadId: ThreadId
+	topicId: TopicId
 	/**
-	 * Denormalized from the owning Thread. Kept alongside `threadId` as the
+	 * Denormalized from the owning Topic. Kept alongside `topicId` as the
 	 * Session record itself carries both (see `Session` JSDoc). Consistency
 	 * validated against `source.projectId` at execute time.
 	 */