@namzu/sdk 30.2.0 → 31.0.0

package/src/session/errors.ts

@@ -64,7 +64,10 @@ export class AncestryCycleError extends Error {
 		cyclePath: readonly SessionId[]
 	}
 
-	constructor(details: { sessionId: SessionId; cyclePath: readonly SessionId[] }) {
+	constructor(details: {
+		sessionId: SessionId
+		cyclePath: readonly SessionId[]
+	}) {
 		super(
 			`Ancestry cycle detected starting at ${details.sessionId}: ${details.cyclePath.join(' -> ')}`,
 		)
@@ -86,7 +89,11 @@ export class WorkspaceBackendError extends Error {
 		cause?: unknown
 	}
 
-	constructor(details: { op: string; kind: WorkspaceBackendKind; cause?: unknown }) {
+	constructor(details: {
+		op: string
+		kind: WorkspaceBackendKind
+		cause?: unknown
+	}) {
 		super(`Workspace backend ${details.kind} failed on ${details.op}`)
 		this.name = 'WorkspaceBackendError'
 		this.details = details
@@ -94,24 +101,27 @@ export class WorkspaceBackendError extends Error {
 }
 
 /**
- * Raised by {@link import('../types/thread/store.js').ThreadStore.updateThread}
- * when the supplied {@link Thread.ownerVersion} does not match the persisted
- * record. The caller must re-read via `getThread`, re-apply its intended
- * mutation on top of the fresh record, and retry. Mirrors the Session
- * handoff CAS pattern (§6.1).
+ * Raised by {@link import('../types/topic/store.js').TopicStore.updateTopic}
+ * when the supplied Topic owner version does not match the persisted record.
+ * The caller re-reads the Topic, reapplies its intended mutation, and retries.
+ * Mirrors the Session handoff CAS pattern (§6.1).
  */
-export class StaleThreadError extends Error {
+export class StaleTopicError extends Error {
 	readonly details: {
-		threadId: TopicId
+		topicId: TopicId
 		expectedVersion: number
 		actualVersion: number
 	}
 
-	constructor(details: { threadId: TopicId; expectedVersion: number; actualVersion: number }) {
+	constructor(details: {
+		topicId: TopicId
+		expectedVersion: number
+		actualVersion: number
+	}) {
 		super(
-			`Stale Thread ${details.threadId}: expected ownerVersion=${details.expectedVersion}, actual=${details.actualVersion}`,
+			`Stale Topic ${details.topicId}: expected ownerVersion=${details.expectedVersion}, actual=${details.actualVersion}`,
 		)
-		this.name = 'StaleThreadError'
+		this.name = 'StaleTopicError'
 		this.details = details
 	}
 }
@@ -119,8 +129,8 @@ export class StaleThreadError extends Error {
 /**
  * Raised when a Session write names a version the store no longer has.
  *
- * The sibling of {@link StaleThreadError}, and it arrived much later: Thread
- * had a working compare-and-set from the start while `Session.ownerVersion`
+ * The sibling of {@link StaleTopicError}, and it arrived much later: Topic had
+ * a working compare-and-set from the start while `Session.ownerVersion`
  * was documented as a CAS counter that nothing enforced. Two concurrent
  * handoffs could both pass, both provision a worktree, and one silently erase
  * the other.
@@ -136,7 +146,11 @@ export class StaleSessionError extends Error {
 		actualVersion: number
 	}
 
-	constructor(details: { sessionId: SessionId; expectedVersion: number; actualVersion: number }) {
+	constructor(details: {
+		sessionId: SessionId
+		expectedVersion: number
+		actualVersion: number
+	}) {
 		super(
 			`Stale Session ${details.sessionId}: expected ownerVersion=${details.expectedVersion}, actual=${details.actualVersion}. Another writer took ownership; re-read the session before retrying.`,
 		)
@@ -146,65 +160,71 @@ export class StaleSessionError extends Error {
 }
 
 /**
- * Raised by the spawn path (and any caller that enforces the open-thread
- * precondition) when a Thread is in `'archived'` state and would-be mutations
- * require it to be `'open'`. Convention #5: deny-by-default — archival is a
- * hard read-only boundary.
+ * Raised by the spawn path (and any caller that enforces the open-Topic
+ * precondition) when a Topic is archived and a mutation requires it to be
+ * open. Convention #5: deny-by-default — archival is a hard read-only
+ * boundary.
  */
-export class ThreadClosedError extends Error {
+export class TopicArchivedError extends Error {
 	readonly details: {
-		threadId: TopicId
+		topicId: TopicId
 		op: string
 	}
 
-	constructor(details: { threadId: TopicId; op: string }) {
-		super(`Thread ${details.threadId} is archived; operation '${details.op}' rejected`)
-		this.name = 'ThreadClosedError'
+	constructor(details: { topicId: TopicId; op: string }) {
+		super(`Topic ${details.topicId} is archived; operation '${details.op}' rejected`)
+		this.name = 'TopicArchivedError'
 		this.details = details
 	}
 }
 
 /**
  * Raised by {@link import('../manager/topic/lifecycle.js').TopicManager.archive}
- * and `.delete` when the Thread's session-presence precondition is violated:
+ * and `.delete` when the Topic's session-presence precondition is violated:
  *
- * - `op: 'archive'` — at least one Session under the Thread is in a
+ * - `op: 'archive'` — at least one Session under the Topic is in a
  *   non-terminal state (`active | locked | awaiting_hitl | awaiting_merge`).
  *   The caller must first quiesce those sessions (let them reach `idle`,
- *   `failed`, or `archived`) before flipping the Thread to archived.
- * - `op: 'delete'` — the Thread still has at least one attached Session.
+ *   `failed`, or `archived`) before flipping the Topic to archived.
+ * - `op: 'delete'` — the Topic still has at least one attached Session.
  *   Callers must either archive + tombstone those sessions (`deleteSession`)
- *   before calling `deleteThread`, or accept that deletion is not yet safe.
+ *   before calling `deleteTopic`, or accept that deletion is not yet safe.
  *
- * `blockingSessions` carries the first {@link THREAD_NOT_EMPTY_SAMPLE_LIMIT}
+ * `blockingSessions` carries the first {@link TOPIC_NOT_EMPTY_SAMPLE_LIMIT}
  * offenders with their current status so operator tooling can surface an
- * actionable list without unbounded error payloads on large threads.
+ * actionable list without unbounded error payloads on large topics.
  * `totalBlockingSessions` holds the full count even when the sample is
  * truncated. Convention #5: deny-by-default — no implicit cascade, no silent
  * no-op.
  */
-export const THREAD_NOT_EMPTY_SAMPLE_LIMIT = 50
+export const TOPIC_NOT_EMPTY_SAMPLE_LIMIT = 50
 
-export class ThreadNotEmptyError extends Error {
+export class TopicNotEmptyError extends Error {
 	readonly details: {
-		threadId: TopicId
+		topicId: TopicId
 		tenantId: TenantId
 		op: 'archive' | 'delete'
-		blockingSessions: ReadonlyArray<{ sessionId: SessionId; status: SessionStatus }>
+		blockingSessions: ReadonlyArray<{
+			sessionId: SessionId
+			status: SessionStatus
+		}>
 		totalBlockingSessions: number
 	}
 
 	constructor(details: {
-		threadId: TopicId
+		topicId: TopicId
 		tenantId: TenantId
 		op: 'archive' | 'delete'
-		blockingSessions: ReadonlyArray<{ sessionId: SessionId; status: SessionStatus }>
+		blockingSessions: ReadonlyArray<{
+			sessionId: SessionId
+			status: SessionStatus
+		}>
 		totalBlockingSessions: number
 	}) {
 		super(
-			`Thread ${details.threadId} ${details.op} blocked: ${details.totalBlockingSessions} session(s) still attached`,
+			`Topic ${details.topicId} ${details.op} blocked: ${details.totalBlockingSessions} session(s) still attached`,
 		)
-		this.name = 'ThreadNotEmptyError'
+		this.name = 'TopicNotEmptyError'
 		this.details = details
 	}
 }
@@ -212,7 +232,7 @@ export class ThreadNotEmptyError extends Error {
 /**
  * Raised when an ingress path is asked to attach work to an archived Project.
  *
- * The sibling of {@link ThreadClosedError}, on the level that survives. A
+ * The sibling of {@link TopicArchivedError}, on the level that survives. A
  * closed workspace is a decision by its owner, and the paths that create
  * sessions have to be able to see it — otherwise "archived" is a word in a
  * listing rather than a state of the system.
@@ -247,7 +267,10 @@ export class ProjectNotEmptyError extends Error {
 		projectId: ProjectId
 		tenantId: TenantId
 		op: 'archive'
-		blockingSessions: ReadonlyArray<{ sessionId: SessionId; status: SessionStatus }>
+		blockingSessions: ReadonlyArray<{
+			sessionId: SessionId
+			status: SessionStatus
+		}>
 		totalBlockingSessions: number
 	}
 
@@ -255,7 +278,10 @@ export class ProjectNotEmptyError extends Error {
 		projectId: ProjectId
 		tenantId: TenantId
 		op: 'archive'
-		blockingSessions: ReadonlyArray<{ sessionId: SessionId; status: SessionStatus }>
+		blockingSessions: ReadonlyArray<{
+			sessionId: SessionId
+			status: SessionStatus
+		}>
 		totalBlockingSessions: number
 	}) {
 		super(

package/src/session/handoff/broadcast.ts

@@ -22,7 +22,7 @@
  */
 
 import { requireOpenProject } from '../../manager/project/lifecycle.js'
-import type { TopicManager } from '../../manager/topic/lifecycle.js'
+import { type TopicManagerDependency, resolveTopicManager } from '../../manager/topic/dependency.js'
 import type { SessionId, TenantId } from '../../types/ids/index.js'
 import type { Session } from '../../types/session/entity.js'
 import type { SubSessionId } from '../../types/session/ids.js'
@@ -37,7 +37,7 @@ import type { HandoffEventSink } from './events.js'
 import type { RunStatusResolver } from './single.js'
 import { HandoffLockRejected, HandoffVersionConflict } from './version.js'
 
-export interface BroadcastHandoffDeps {
+interface BroadcastHandoffBaseDeps {
 	store: SessionStore
 	workspaceRegistry: WorkspaceBackendRegistry
 	capacity: CapacityValidator
@@ -47,14 +47,11 @@ export interface BroadcastHandoffDeps {
 	 * that used to stand in here reported every session unblocked.
 	 */
 	runStatus: RunStatusResolver
-	/**
-	 * Gate every recipient-session creation on the Thread being `'open'`.
-	 * Added in Phase 2.6; checked once per broadcast (all recipients share
-	 * a threadId by the fan-out invariant validated above).
-	 */
-	threadManager: TopicManager
 }
 
+/** Dependencies for a multi-recipient handoff. */
+export type BroadcastHandoffDeps = BroadcastHandoffBaseDeps & TopicManagerDependency
+
 /**
  * Per-recipient partial state tracked during fan-out so rollback can
  * compensate exactly what was created. `subSessionId` is populated at the
@@ -145,11 +142,11 @@ export async function executeBroadcastHandoff(
 		seen.add(key)
 	}
 
-	// Thread archive gate (Phase 2.6) — runs BEFORE source load/capacity so an
-	// archived thread fails fastest with `ThreadClosedError`. All assignments
+	// Topic archive gate (Phase 2.6) — runs BEFORE source load/capacity so an
+	// archived Topic fails fastest with `TopicArchivedError`. All assignments
 	// share `topicId` by the shape validation above. Runs BEFORE the CAS
 	// lock so a denied fan-out leaves the source session untouched.
-	await deps.threadManager.requireOpen(first.topicId, tenantId)
+	await resolveTopicManager(deps).requireOpen(first.topicId, tenantId)
 
 	// 3. Load source + tenant check.
 	const source = await deps.store.getSession(first.sourceSessionId, tenantId)
@@ -190,7 +187,10 @@ export async function executeBroadcastHandoff(
 	const runResolver = deps.runStatus
 	const blocking = await runResolver.blockingRun(source.id, tenantId)
 	if (blocking) {
-		throw new HandoffLockRejected({ sessionId: source.id, reason: blocking.reason })
+		throw new HandoffLockRejected({
+			sessionId: source.id,
+			reason: blocking.reason,
+		})
 	}
 
 	// 6. Capacity — width + depth. Width covers N new children in one shot
@@ -218,7 +218,11 @@ export async function executeBroadcastHandoff(
 	// the lock at the version it read left the locked window invisible, so a
 	// second broadcast holding the same snapshot passed the check above and
 	// fanned out over a session that was already locked.
-	const locked: Session = { ...source, status: 'locked', ownerVersion: source.ownerVersion + 1 }
+	const locked: Session = {
+		...source,
+		status: 'locked',
+		ownerVersion: source.ownerVersion + 1,
+	}
 	await deps.store.updateSession(locked, tenantId, first.expectedOwnerVersion)
 	emit(deps.events.onLocked, { sessionId: source.id, at: new Date() })
 
@@ -244,7 +248,9 @@ export async function executeBroadcastHandoff(
 			}
 			partials.push(partial)
 
-			partial.workspace = await driver.create({ label: `broadcast-${assignment.id}` })
+			partial.workspace = await driver.create({
+				label: `broadcast-${assignment.id}`,
+			})
 			worktreesProvisioned += 1
 
 			const childSession = await deps.store.createSession(

package/src/session/handoff/single.ts

@@ -21,7 +21,7 @@
  */
 
 import { requireOpenProject } from '../../manager/project/lifecycle.js'
-import type { TopicManager } from '../../manager/topic/lifecycle.js'
+import { type TopicManagerDependency, resolveTopicManager } from '../../manager/topic/dependency.js'
 import type { SessionId, TenantId } from '../../types/ids/index.js'
 import type { Session } from '../../types/session/entity.js'
 import type { SessionStore } from '../../types/session/store.js'
@@ -50,10 +50,12 @@ export interface RunStatusResolver {
 	blockingRun(
 		sessionId: SessionId,
 		tenantId: TenantId,
-	): Promise<{ reason: 'active_run' | 'pending_hitl' | 'pending_subsession' } | null>
+	): Promise<{
+		reason: 'active_run' | 'pending_hitl' | 'pending_subsession'
+	} | null>
 }
 
-export interface SingleHandoffDeps {
+interface SingleHandoffBaseDeps {
 	store: SessionStore
 	workspaceRegistry: WorkspaceBackendRegistry
 	capacity: CapacityValidator
@@ -65,14 +67,11 @@ export interface SingleHandoffDeps {
 	 * fail dressed as a check that ran.
 	 */
 	runStatus: RunStatusResolver
-	/**
-	 * Gate the recipient-session creation on the Topic being `'open'`.
-	 * Added in Phase 2.6 to mirror spawn — a handoff into an archived
-	 * Topic would otherwise undermine `TopicManager.archive`.
-	 */
-	threadManager: TopicManager
 }
 
+/** Dependencies for a single-recipient handoff. */
+export type SingleHandoffDeps = SingleHandoffBaseDeps & TopicManagerDependency
+
 /**
  * Executes a single-recipient handoff against `deps.store`. Throws
  * {@link HandoffLockRejected}, {@link HandoffVersionConflict},
@@ -92,11 +91,11 @@ export async function executeSingleHandoff(
 		})
 	}
 
-	// Thread archive gate (Phase 2.6) — runs FIRST so an archived thread
-	// fails fastest with `ThreadClosedError` rather than a lock rejection or
+	// Topic archive gate (Phase 2.6) — runs FIRST so an archived Topic
+	// fails fastest with `TopicArchivedError` rather than a lock rejection or
 	// capacity error. Checked BEFORE the CAS lock so a denied handoff leaves
 	// the source session untouched.
-	await deps.threadManager.requireOpen(assignment.topicId, tenantId)
+	await resolveTopicManager(deps).requireOpen(assignment.topicId, tenantId)
 
 	// 1. Load source session + tenant check.
 	const source = await deps.store.getSession(assignment.sourceSessionId, tenantId)
@@ -185,7 +184,9 @@ export async function executeSingleHandoff(
 	let createdSessionId: SessionId | null = null
 	try {
 		const driver: WorkspaceBackendDriver = deps.workspaceRegistry.get('git-worktree')
-		provisionedWorkspace = await driver.create({ label: `handoff-${assignment.id}` })
+		provisionedWorkspace = await driver.create({
+			label: `handoff-${assignment.id}`,
+		})
 
 		const recipientSession = await deps.store.createSession(
 			{

package/src/store/attachment/index.ts

@@ -51,6 +51,15 @@ export interface StoredBytes {
 	readonly mediaType: string
 }
 
+/** Authority owned by the public operation resolving stored bytes. */
+export interface AttachmentOperationOptions {
+	/**
+	 * A pre-aborted signal starts no store work. Implementations should use it
+	 * to stop their own I/O; the SDK also stops awaiting a store that ignores it.
+	 */
+	readonly signal?: AbortSignal
+}
+
 export interface AttachmentStore {
 	/**
 	 * Take bytes, return a ref.
@@ -60,7 +69,7 @@ export interface AttachmentStore {
 	 */
 	put(bytes: StoredBytes): Promise<string>
 	/** `undefined` for a ref this store does not hold. */
-	get(ref: string): Promise<StoredBytes | undefined>
+	get(ref: string, options?: AttachmentOperationOptions): Promise<StoredBytes | undefined>
 }
 
 /** A reference nothing could resolve. */
@@ -117,11 +126,20 @@ export const isStoredAttachment = (
 export async function resolveAttachment(
 	attachment: MessageAttachment,
 	store: AttachmentStore | undefined,
+	options: AttachmentOperationOptions = {},
 ): Promise<MessageAttachment> {
+	const { signal } = options
+	signal?.throwIfAborted()
 	if (!isStoredAttachment(attachment)) return attachment
 	if (!store) throw new NoAttachmentStoreError({ ref: attachment.ref })
 
-	const bytes = await store.get(attachment.ref)
+	const bytes = await awaitStoreRead(signal, () =>
+		signal ? store.get(attachment.ref, { signal }) : store.get(attachment.ref),
+	)
+	// A store completion can win its promise reaction and remove the abort
+	// listener immediately before an already-queued abort. Publication is a
+	// second authority boundary, so fence it independently.
+	signal?.throwIfAborted()
 	if (!bytes) throw new AttachmentNotFoundError({ ref: attachment.ref })
 
 	if (bytes.mediaType !== attachment.mediaType) {
@@ -159,7 +177,9 @@ export async function resolveAttachment(
 export async function resolveAttachments(
 	messages: readonly Message[],
 	store: AttachmentStore | undefined,
+	options: AttachmentOperationOptions = {},
 ): Promise<readonly Message[]> {
+	options.signal?.throwIfAborted()
 	// `Message` rather than a structural constraint: only some members of
 	// the union carry `attachments`, and a structural bound over a union
 	// like that is not assignable in either direction. Naming the real type
@@ -175,8 +195,50 @@ export async function resolveAttachments(
 			if (!attachments?.some(isStoredAttachment)) return message
 			return {
 				...message,
-				attachments: await Promise.all(attachments.map((a) => resolveAttachment(a, store))),
+				attachments: await Promise.all(
+					attachments.map((attachment) => resolveAttachment(attachment, store, options)),
+				),
 			}
 		}),
 	)
 }
+
+/**
+ * Await a host store without handing it ownership of run cancellation.
+ *
+ * Forwarding the signal is cooperative cleanup; this race is the public
+ * liveness boundary when a remote or custom store ignores it. The first cause
+ * wins, and late store completion has no route back into the returned value.
+ */
+async function awaitStoreRead<T>(
+	signal: AbortSignal | undefined,
+	start: () => Promise<T>,
+): Promise<T> {
+	if (!signal) return await start()
+	signal.throwIfAborted()
+
+	return new Promise<T>((resolve, reject) => {
+		let settled = false
+		const cleanup = (): void => signal.removeEventListener('abort', onAbort)
+		const rejectOnce = (reason: unknown): void => {
+			if (settled) return
+			settled = true
+			cleanup()
+			reject(reason)
+		}
+		const resolveOnce = (value: T): void => {
+			if (settled) return
+			settled = true
+			cleanup()
+			resolve(value)
+		}
+		const onAbort = (): void => rejectOnce(signal.reason)
+
+		signal.addEventListener('abort', onAbort, { once: true })
+		try {
+			Promise.resolve(start()).then(resolveOnce, rejectOnce)
+		} catch (error) {
+			rejectOnce(error)
+		}
+	})
+}

package/src/store/feedback/conformance.ts

@@ -122,6 +122,45 @@ export function defineMessageFeedbackConformance(options: FeedbackConformanceOpt
 			expect(listed[0]?.ownerVersion).toBe(1)
 		})
 
+		it('lets exactly one of two racing updates advance a stored version', async () => {
+			const { store, runId, knownMessageId } = await makeStore()
+			await store.putMessageFeedback({
+				runId,
+				messageId: knownMessageId,
+				rating: 'good',
+				expectedVersion: 0,
+			})
+
+			const attempts = [
+				{ rating: 'good' as const, note: 'writer-a' },
+				{ rating: 'bad' as const, note: 'writer-b' },
+			].map((candidate) =>
+				store
+					.putMessageFeedback({
+						runId,
+						messageId: knownMessageId,
+						...candidate,
+						expectedVersion: 1,
+					})
+					.then(
+						(record) => ({ kind: 'ok' as const, record }),
+						() => ({ kind: 'refused' as const }),
+					),
+			)
+			const outcomes = await Promise.all(attempts)
+			const winners = outcomes.filter((outcome) => outcome.kind === 'ok')
+
+			expect(winners).toHaveLength(1)
+			expect(outcomes.filter((outcome) => outcome.kind === 'refused')).toHaveLength(1)
+			const winner = winners[0]
+			if (winner?.kind !== 'ok') throw new Error('expected one feedback update winner')
+			const listed = await store.listMessageFeedback({ runId })
+			expect(listed).toHaveLength(1)
+			expect(listed[0]?.ownerVersion).toBe(2)
+			expect(listed[0]?.rating).toBe(winner.record.rating)
+			expect(listed[0]?.note).toBe(winner.record.note)
+		})
+
 		it('advances the version on a correct update', async () => {
 			const { store, runId, knownMessageId } = await makeStore()
 			await store.putMessageFeedback({