@namzu/sdk 0.4.0 → 0.4.2

package/src/runtime/query/replay/mutate.ts

@@ -0,0 +1,76 @@
+import type { ToolCallId } from '../../../types/ids/index.js'
+import {
+	type AssistantMessage,
+	type Message,
+	type ToolCall,
+	createToolMessage,
+} from '../../../types/message/index.js'
+import { type Mutation, MutationNotApplicableError } from '../../../types/run/replay.js'
+
+/**
+ * Returns the tool calls on the most recent assistant message that do not
+ * yet have a matching {@link import('../../../types/message/index.js').ToolMessage}
+ * response further down the message list. These are the fork-point "pending"
+ * tool calls that mutations may target.
+ */
+function findPendingToolCalls(messages: readonly Message[]): ToolCall[] {
+	let lastAssistantIdx = -1
+	for (let i = messages.length - 1; i >= 0; i--) {
+		const msg = messages[i]
+		if (msg && msg.role === 'assistant' && (msg.toolCalls?.length ?? 0) > 0) {
+			lastAssistantIdx = i
+			break
+		}
+	}
+	if (lastAssistantIdx === -1) return []
+
+	const assistant = messages[lastAssistantIdx] as AssistantMessage
+	const satisfied = new Set<string>()
+	for (let i = lastAssistantIdx + 1; i < messages.length; i++) {
+		const msg = messages[i]
+		if (msg && msg.role === 'tool') {
+			satisfied.add(msg.toolCallId)
+		}
+	}
+	return (assistant.toolCalls ?? []).filter((tc) => !satisfied.has(tc.id))
+}
+
+/**
+ * Apply an ordered list of {@link Mutation} to a checkpoint's message
+ * history at the fork point, producing a new message array that the
+ * resumed iteration loop consumes. Pure function; does not touch the run
+ * store, does not emit events.
+ *
+ * Throws {@link MutationNotApplicableError} when an `injectToolResponse`
+ * mutation targets a tool call id that is not pending at the fork point —
+ * the error payload carries the list of ids that *are* pending so the
+ * caller can recover without guessing.
+ *
+ * See ses_005-deterministic-replay design §3.3.
+ */
+export function applyMutations(
+	messages: readonly Message[],
+	mutations: readonly Mutation[],
+): Message[] {
+	let current: Message[] = [...messages]
+	for (const m of mutations) {
+		current = applyOne(current, m)
+	}
+	return current
+}
+
+function applyOne(messages: Message[], mutation: Mutation): Message[] {
+	switch (mutation.type) {
+		case 'injectToolResponse': {
+			const pending = findPendingToolCalls(messages)
+			const match = pending.find((tc) => tc.id === mutation.toolCallId)
+			if (!match) {
+				throw new MutationNotApplicableError(
+					`No pending tool call ${mutation.toolCallId} at fork point`,
+					pending.map((tc) => tc.id as ToolCallId),
+				)
+			}
+			return [...messages, createToolMessage(mutation.response.output, mutation.toolCallId)]
+		}
+	}
+}

package/src/runtime/query/replay/prepare.ts

@@ -0,0 +1,114 @@
+import { join } from 'node:path'
+import { EmergencySaveManager } from '../../../manager/run/emergency.js'
+import { RunDiskStore } from '../../../store/run/disk.js'
+import type { CheckpointId, IterationCheckpoint } from '../../../types/hitl/index.js'
+import type { RunId } from '../../../types/ids/index.js'
+import type { Message } from '../../../types/message/index.js'
+import type { Mutation, ReplayAttribution } from '../../../types/run/replay.js'
+import type { Logger } from '../../../utils/logger.js'
+import { projectEmergencyToCheckpoint } from '../checkpoint.js'
+import { applyMutations } from './mutate.js'
+
+export type CheckpointSelector = CheckpointId | 'latest' | 'emergency'
+
+export interface PrepareReplayInput {
+	/** Directory that contains `<runId>/` for the source run. */
+	baseDir: string
+	/** Source run to fork from. */
+	runId: RunId
+	/** Which checkpoint to fork at. */
+	fromCheckpoint: CheckpointSelector
+	/** Optional mutations applied at the fork point before the caller hands state to `query()`. */
+	mutate?: Mutation[]
+	/**
+	 * Directory that holds emergency dumps. Required only when `fromCheckpoint`
+	 * is `'emergency'`; conventionally sibling of `baseDir` (the `.namzu/emergency`
+	 * folder), but left explicit so callers with non-default layouts can redirect.
+	 */
+	emergencyDir?: string
+	logger?: Logger
+}
+
+export interface PreparedReplayState {
+	/**
+	 * Message history at the fork point, with mutations applied. Seed this
+	 * as the new run's initial messages and pass `sourceCheckpoint.id` as
+	 * `resumeFromCheckpoint` when you call `query()`.
+	 */
+	messages: Message[]
+	/** The checkpoint the replay forks from (already projected if emergency). */
+	sourceCheckpoint: IterationCheckpoint
+	/**
+	 * Attribution to stamp on the replay run once it is created. The caller
+	 * sets `Run.replayOf = buildAttribution(prepared, replayedAt)` on the
+	 * new `RunPersistence` before persisting the first time.
+	 */
+	attribution: ReplayAttribution
+}
+
+/**
+ * Produce the state materials needed to execute a replay run — the mutated
+ * message history, the resolved source checkpoint, and the replay
+ * attribution record. Pure read; does not touch the run store beyond
+ * reading the source run's checkpoint files.
+ *
+ * This is the state-preparation half of the replay primitive. The
+ * caller is expected to thread the returned `messages` +
+ * `sourceCheckpoint.id` into `query({ resumeFromCheckpoint, messages,
+ * ... })` and stamp `Run.replayOf = prepared.attribution` on the resulting
+ * run. The end-to-end `replay()` entry that does all of this in one call
+ * is a follow-up session (`ReplayEnvironment` shape).
+ *
+ * See `ses_005-deterministic-replay/design.md` §3.1.
+ */
+export async function prepareReplayState(input: PrepareReplayInput): Promise<PreparedReplayState> {
+	const sourceCheckpoint = await resolveCheckpoint(input)
+	const mutations = input.mutate ?? []
+	const messages = applyMutations(sourceCheckpoint.messages, mutations)
+
+	const attribution: ReplayAttribution = {
+		sourceRunId: input.runId,
+		fromCheckpointId: sourceCheckpoint.id,
+		mutations,
+		replayedAt: Date.now(),
+	}
+
+	return { messages, sourceCheckpoint, attribution }
+}
+
+async function resolveCheckpoint(input: PrepareReplayInput): Promise<IterationCheckpoint> {
+	if (input.fromCheckpoint === 'emergency') {
+		return resolveEmergency(input)
+	}
+	const store = new RunDiskStore({ baseDir: input.baseDir, logger: input.logger })
+	await store.initRun(input.runId)
+
+	if (input.fromCheckpoint === 'latest') {
+		const all = await store.listCheckpoints()
+		if (all.length === 0) {
+			throw new Error(`No checkpoints found for run ${input.runId} in ${input.baseDir}`)
+		}
+		return [...all].sort((a, b) => b.iteration - a.iteration)[0] as IterationCheckpoint
+	}
+
+	const checkpoint = await store.readCheckpoint(input.fromCheckpoint)
+	if (!checkpoint) {
+		throw new Error(`Checkpoint ${input.fromCheckpoint} not found for run ${input.runId}`)
+	}
+	return checkpoint
+}
+
+async function resolveEmergency(input: PrepareReplayInput): Promise<IterationCheckpoint> {
+	if (!input.emergencyDir) {
+		throw new Error(
+			"fromCheckpoint: 'emergency' requires an `emergencyDir` — conventionally sibling of baseDir",
+		)
+	}
+	const path = join(input.emergencyDir, `${input.runId}.json`)
+	try {
+		const dump = EmergencySaveManager.loadSave(path)
+		return projectEmergencyToCheckpoint(dump)
+	} catch (err) {
+		throw new Error(`No emergency dump found for run ${input.runId} at ${path}`, { cause: err })
+	}
+}

package/src/runtime/query/result.ts

@@ -3,7 +3,7 @@ import type { PlanManager } from '../../manager/plan/lifecycle.js'
 import type { RunPersistence } from '../../manager/run/persistence.js'
 import type { ActivityStore } from '../../store/activity/memory.js'
 import { GENAI, NAMZU } from '../../telemetry/attributes.js'
-import type { AgentRun, RunEvent } from '../../types/run/index.js'
+import type { Run, RunEvent } from '../../types/run/index.js'
 import { toErrorMessage } from '../../utils/error.js'
 import type { Logger } from '../../utils/logger.js'
 import type { EmitEvent } from './events.js'
@@ -87,7 +87,7 @@ export class ResultAssembler {
 		})
 	}
 
-	async finalize(): Promise<AgentRun> {
+	async finalize(): Promise<Run> {
 		await this.config.runMgr.persist()
 		return this.config.runMgr.getRun()
 	}

package/src/session/__tests__/integration/_fixtures.ts

@@ -30,11 +30,11 @@ import type { AgentDefinition } from '../../../types/agent/factory.js'
 import type { AgentTaskContext, SendMessageOptions } from '../../../types/agent/task.js'
 import type { AgentId, RunId, SessionId, TenantId, UserId } from '../../../types/ids/index.js'
 import { createAssistantMessage } from '../../../types/message/index.js'
+import type { ActorRef } from '../../../types/session/actor.js'
+import type { Session } from '../../../types/session/entity.js'
 import type { ProjectId, SummaryId, ThreadId } from '../../../types/session/ids.js'
 import { ZERO_COST } from '../../../utils/cost.js'
 import { DefaultCapacityValidator } from '../../handoff/capacity.js'
-import type { ActorRef } from '../../hierarchy/actor.js'
-import type { Session } from '../../hierarchy/session.js'
 import { SessionSummaryMaterializer } from '../../summary/materialize.js'
 import type { ExecFile, ExecFileResult } from '../../workspace/git-worktree.js'
 import { GitWorktreeDriver } from '../../workspace/git-worktree.js'

package/src/session/__tests__/integration/archive-gate.test.ts

@@ -17,6 +17,7 @@ import { ThreadManager } from '../../../manager/thread/lifecycle.js'
 import { InMemorySessionStore } from '../../../store/session/memory.js'
 import { InMemoryThreadStore } from '../../../store/thread/memory.js'
 import type { AgentId, RunId, UserId } from '../../../types/ids/index.js'
+import type { ActorRef } from '../../../types/session/actor.js'
 import { generateHandoffId } from '../../../utils/id.js'
 import { ThreadClosedError } from '../../errors.js'
 import type { HandoffAssignment } from '../../handoff/assignment.js'
@@ -24,7 +25,6 @@ import { type BroadcastHandoffDeps, executeBroadcastHandoff } from '../../handof
 import { DefaultCapacityValidator } from '../../handoff/capacity.js'
 import type { HandoffEventSink } from '../../handoff/events.js'
 import { type SingleHandoffDeps, executeSingleHandoff } from '../../handoff/single.js'
-import type { ActorRef } from '../../hierarchy/actor.js'
 import { GitWorktreeDriver } from '../../workspace/git-worktree.js'
 import { WorkspaceBackendRegistry } from '../../workspace/registry.js'
 import {

package/src/session/__tests__/integration/capacity-caps.test.ts

@@ -11,8 +11,8 @@
  */
 
 import { describe, expect, it } from 'vitest'
+import type { ActorRef } from '../../../types/session/actor.js'
 import { DelegationCapacityExceeded } from '../../handoff/capacity.js'
-import type { ActorRef } from '../../hierarchy/actor.js'
 import {
 	DEFAULT_TENANT,
 	agentActor,

package/src/session/__tests__/integration/e2e-spawn.test.ts

@@ -34,10 +34,10 @@ import type { AgentTaskContext, SendMessageOptions } from '../../../types/agent/
 import type { RunId, TenantId, UserId } from '../../../types/ids/index.js'
 import { createAssistantMessage } from '../../../types/message/index.js'
 import type { RunEvent } from '../../../types/run/events.js'
+import type { ActorRef } from '../../../types/session/actor.js'
 import type { SummaryId } from '../../../types/session/ids.js'
 import { ZERO_COST } from '../../../utils/cost.js'
 import { DefaultCapacityValidator } from '../../handoff/capacity.js'
-import type { ActorRef } from '../../hierarchy/actor.js'
 import { SessionSummaryMaterializer } from '../../summary/materialize.js'
 import { WorkspaceBackendRegistry } from '../../workspace/registry.js'
 

package/src/session/__tests__/integration/handoff-broadcast-e2e.test.ts

@@ -14,13 +14,13 @@ import { ThreadManager } from '../../../manager/thread/lifecycle.js'
 import { InMemorySessionStore } from '../../../store/session/memory.js'
 import { InMemoryThreadStore } from '../../../store/thread/memory.js'
 import type { SessionId } from '../../../types/ids/index.js'
+import type { ActorRef } from '../../../types/session/actor.js'
 import type { ProjectId, ThreadId } from '../../../types/session/ids.js'
 import { generateHandoffId } from '../../../utils/id.js'
 import type { HandoffAssignment } from '../../handoff/assignment.js'
 import { type BroadcastHandoffDeps, executeBroadcastHandoff } from '../../handoff/broadcast.js'
 import { DefaultCapacityValidator } from '../../handoff/capacity.js'
 import type { HandoffEventSink } from '../../handoff/events.js'
-import type { ActorRef } from '../../hierarchy/actor.js'
 import type { ExecFile } from '../../workspace/git-worktree.js'
 import { GitWorktreeDriver } from '../../workspace/git-worktree.js'
 import { WorkspaceBackendRegistry } from '../../workspace/registry.js'

package/src/session/__tests__/integration/handoff-single-e2e.test.ts

@@ -17,13 +17,13 @@ import { ThreadManager } from '../../../manager/thread/lifecycle.js'
 import { InMemorySessionStore } from '../../../store/session/memory.js'
 import { InMemoryThreadStore } from '../../../store/thread/memory.js'
 import type { TenantId } from '../../../types/ids/index.js'
+import type { Session } from '../../../types/session/entity.js'
 import { generateHandoffId } from '../../../utils/id.js'
 import { TenantIsolationError } from '../../errors.js'
 import type { HandoffAssignment } from '../../handoff/assignment.js'
 import { DefaultCapacityValidator } from '../../handoff/capacity.js'
 import type { HandoffEventSink } from '../../handoff/events.js'
 import { type SingleHandoffDeps, executeSingleHandoff } from '../../handoff/single.js'
-import type { Session } from '../../hierarchy/session.js'
 import { GitWorktreeDriver } from '../../workspace/git-worktree.js'
 import { WorkspaceBackendRegistry } from '../../workspace/registry.js'
 import { DEFAULT_TENANT, OTHER_TENANT, okExec, stubLogger, userActor } from './_fixtures.js'

package/src/session/__tests__/integration/prev-artifact-dag.test.ts

@@ -20,13 +20,16 @@ import type {
 	SummaryId,
 	ThreadId,
 } from '../../../types/session/ids.js'
+import type {
+	DeliverableRef,
+	SessionSummaryDeliverable,
+} from '../../../types/summary/deliverable.js'
 import {
 	ArtifactRefCycleError,
 	type InterventionChainLoader,
 	InterventionDepthExceeded,
 	validatePrevArtifactChain,
 } from '../../intervention/prev-artifact.js'
-import type { DeliverableRef, SessionSummaryDeliverable } from '../../summary/deliverable.js'
 import { DEFAULT_TENANT, agentActor, userActor } from './_fixtures.js'
 
 const TEST_THREAD_ID = 'thd_test' as ThreadId

package/src/session/__tests__/integration/retention-archive.test.ts

@@ -16,9 +16,9 @@ import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import { InMemorySessionStore } from '../../../store/session/memory.js'
 import { createUserMessage } from '../../../types/message/index.js'
 import type { ThreadId, WorkspaceId } from '../../../types/session/ids.js'
+import type { WorkspaceRef } from '../../../types/workspace/ref.js'
 import { ArchivalManager, ArchiveNotConfiguredError } from '../../retention/archive.js'
 import { DiskArchiveBackend } from '../../retention/disk-backend.js'
-import type { WorkspaceRef } from '../../workspace/ref.js'
 import { WorkspaceBackendRegistry } from '../../workspace/registry.js'
 import { DEFAULT_TENANT, agentActor, userActor } from './_fixtures.js'
 

package/src/session/__tests__/integration/spawn-rollback.test.ts

@@ -41,10 +41,11 @@ import type { AgentDefinition } from '../../../types/agent/factory.js'
 import type { AgentTaskContext, SendMessageOptions } from '../../../types/agent/task.js'
 import type { RunId, TenantId, UserId } from '../../../types/ids/index.js'
 import { createAssistantMessage } from '../../../types/message/index.js'
+import type { ActorRef } from '../../../types/session/actor.js'
 import type { SummaryId } from '../../../types/session/ids.js'
+import type { WorkspaceRef } from '../../../types/workspace/ref.js'
 import { ZERO_COST } from '../../../utils/cost.js'
 import { DefaultCapacityValidator } from '../../handoff/capacity.js'
-import type { ActorRef } from '../../hierarchy/actor.js'
 import { SessionSummaryMaterializer } from '../../summary/materialize.js'
 import type {
 	BranchWorkspaceParams,
@@ -52,7 +53,6 @@ import type {
 	WorkspaceBackendDriver,
 	WorkspaceInspection,
 } from '../../workspace/driver.js'
-import type { WorkspaceRef } from '../../workspace/ref.js'
 import { WorkspaceBackendRegistry } from '../../workspace/registry.js'
 
 const tenant = 'tnt_alpha' as TenantId

package/src/session/__tests__/integration/summary-materialization-e2e.test.ts

@@ -19,8 +19,8 @@ import { describe, expect, it } from 'vitest'
 import { InMemorySessionStore } from '../../../store/session/memory.js'
 import type { SessionId } from '../../../types/ids/index.js'
 import type { SummaryId, ThreadId } from '../../../types/session/ids.js'
+import { SessionAlreadySummarizedError } from '../../summary/errors.js'
 import { SessionSummaryMaterializer } from '../../summary/materialize.js'
-import { SessionAlreadySummarizedError } from '../../summary/ref.js'
 import { DEFAULT_TENANT, agentActor } from './_fixtures.js'
 
 const TEST_THREAD_ID = 'thd_test' as ThreadId

package/src/session/errors.ts

@@ -8,8 +8,8 @@
  */
 
 import type { SessionId, TenantId } from '../types/ids/index.js'
+import type { SessionStatus } from '../types/session/entity.js'
 import type { ThreadId } from '../types/session/ids.js'
-import type { SessionStatus } from './hierarchy/session.js'
 import type { WorkspaceBackendKind } from './workspace/driver.js'
 
 /**

package/src/session/events/index.ts

@@ -1,16 +1,17 @@
 // Sub-barrel for session-hierarchy run-event surface.
-// Convention #4: concrete types live in sibling files; re-export them here.
+// Shape types live under `types/run/` (subsession-events.ts + schema-version.ts);
+// this barrel only re-exports them. No runtime emitter lives here today.
 //
 // Phase 2 scope is limited to the sub-session lifecycle variants that are
 // spliced into `RunEvent`. A dedicated `SessionHierarchyEvent` top-level
 // union lands in a later phase (see session-hierarchy.md §10.2).
 
-export { RUN_EVENT_SCHEMA_VERSION } from './schema-version.js'
-export type { RunEventSchemaVersion } from './schema-version.js'
+export { RUN_EVENT_SCHEMA_VERSION } from '../../types/run/schema-version.js'
+export type { RunEventSchemaVersion } from '../../types/run/schema-version.js'
 
 export type {
 	SubsessionSpawnedEvent,
 	SubsessionMessagedEvent,
 	SubsessionIdledEvent,
 	SubsessionLifecycleEvent,
-} from './types.js'
+} from '../../types/run/subsession-events.js'

package/src/session/handoff/__tests__/broadcast.test.ts

@@ -1,6 +1,5 @@
 import { beforeEach, describe, expect, it, vi } from 'vitest'
 import { ThreadManager } from '../../../manager/thread/lifecycle.js'
-import type { ActorRef } from '../../../session/hierarchy/actor.js'
 import {
 	type ExecFile,
 	type ExecFileResult,
@@ -10,6 +9,7 @@ import { WorkspaceBackendRegistry } from '../../../session/workspace/registry.js
 import { InMemorySessionStore } from '../../../store/session/memory.js'
 import { InMemoryThreadStore } from '../../../store/thread/memory.js'
 import type { SessionId, TenantId, UserId } from '../../../types/ids/index.js'
+import type { ActorRef } from '../../../types/session/actor.js'
 import type { ProjectId } from '../../../types/session/ids.js'
 import { generateHandoffId } from '../../../utils/id.js'
 import type { HandoffAssignment } from '../assignment.js'

package/src/session/handoff/__tests__/capacity.test.ts

@@ -1,8 +1,8 @@
 import { describe, expect, it } from 'vitest'
-import type { ActorRef } from '../../../session/hierarchy/actor.js'
 import { InMemorySessionStore } from '../../../store/session/memory.js'
 import { InMemoryThreadStore } from '../../../store/thread/memory.js'
 import type { AgentId, SessionId, TenantId, UserId } from '../../../types/ids/index.js'
+import type { ActorRef } from '../../../types/session/actor.js'
 import type { ProjectId, ThreadId } from '../../../types/session/ids.js'
 import { DefaultCapacityValidator, DelegationCapacityExceeded } from '../capacity.js'
 

package/src/session/handoff/__tests__/single.test.ts

@@ -1,7 +1,6 @@
 import { beforeEach, describe, expect, it, vi } from 'vitest'
 import { ThreadManager } from '../../../manager/thread/lifecycle.js'
 import { TenantIsolationError } from '../../../session/errors.js'
-import type { ActorRef } from '../../../session/hierarchy/actor.js'
 import {
 	type ExecFile,
 	type ExecFileResult,
@@ -11,6 +10,7 @@ import { WorkspaceBackendRegistry } from '../../../session/workspace/registry.js
 import { InMemorySessionStore } from '../../../store/session/memory.js'
 import { InMemoryThreadStore } from '../../../store/thread/memory.js'
 import type { AgentId, SessionId, TenantId, UserId } from '../../../types/ids/index.js'
+import type { ActorRef } from '../../../types/session/actor.js'
 import { generateHandoffId } from '../../../utils/id.js'
 import type { HandoffAssignment } from '../assignment.js'
 import { DefaultCapacityValidator } from '../capacity.js'

package/src/session/handoff/assignment.ts

@@ -9,8 +9,8 @@
  */
 
 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 { ActorRef } from '../hierarchy/actor.js'
 
 /**
  * Handoff mode discriminator. `single` transfers ownership of the source

package/src/session/handoff/broadcast.ts

@@ -23,12 +23,12 @@
 
 import type { ThreadManager } from '../../manager/thread/lifecycle.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'
 import type { SessionStore } from '../../types/session/store.js'
+import type { WorkspaceRef } from '../../types/workspace/ref.js'
 import { TenantIsolationError } from '../errors.js'
-import type { Session } from '../hierarchy/session.js'
 import type { WorkspaceBackendDriver } from '../workspace/driver.js'
-import type { WorkspaceRef } from '../workspace/ref.js'
 import type { WorkspaceBackendRegistry } from '../workspace/registry.js'
 import type { HandoffAssignment, HandoffOutcome } from './assignment.js'
 import type { CapacityValidator } from './capacity.js'

package/src/session/handoff/single.ts

@@ -22,11 +22,11 @@
 
 import type { ThreadManager } from '../../manager/thread/lifecycle.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'
+import type { WorkspaceRef } from '../../types/workspace/ref.js'
 import { TenantIsolationError } from '../errors.js'
-import type { Session } from '../hierarchy/session.js'
 import type { WorkspaceBackendDriver } from '../workspace/driver.js'
-import type { WorkspaceRef } from '../workspace/ref.js'
 import type { WorkspaceBackendRegistry } from '../workspace/registry.js'
 import type { HandoffAssignment, HandoffOutcome } from './assignment.js'
 import type { CapacityValidator } from './capacity.js'

package/src/session/index.ts

@@ -1,10 +1,11 @@
-// Top-level barrel for the session hierarchy module.
-// Phase 1 populates `hierarchy/`; Phase 2 adds `events/`; Phase 3 adds
-// `workspace/` + `errors.ts`; Phase 4 adds `handoff/`; Phase 5 adds
-// `summary/` + `intervention/`; Phase 7 adds `migration/`; Phase 8 adds
-// `retention/`.
+// Top-level barrel for the session module.
+// Shape types (Project / Thread / Session / SubSession / Actor / Lineage /
+// Tenant) live under `types/` as of ses_010 (2026-04-21); this barrel
+// re-exports only the runtime machinery that lives under `session/*/`
+// (events, workspace, handoff, summary, intervention, migration, retention,
+// status). Consumers of `@namzu/sdk` reach entity shapes through the root
+// barrel directly.
 
-export * from './hierarchy/index.js'
 export * from './events/index.js'
 export * from './workspace/index.js'
 export * from './handoff/index.js'

package/src/session/intervention/__tests__/prev-artifact.test.ts

@@ -1,7 +1,10 @@
 import { describe, expect, it } from 'vitest'
 import type { SessionId } from '../../../types/ids/index.js'
 import type { DeliverableId, SubSessionId, SummaryId } from '../../../types/session/ids.js'
-import type { DeliverableRef, SessionSummaryDeliverable } from '../../summary/deliverable.js'
+import type {
+	DeliverableRef,
+	SessionSummaryDeliverable,
+} from '../../../types/summary/deliverable.js'
 import {
 	ArtifactRefCycleError,
 	type InterventionChainLoader,

package/src/session/intervention/prev-artifact.ts

@@ -17,7 +17,7 @@
 
 import type { SessionId } from '../../types/ids/index.js'
 import type { SubSessionId } from '../../types/session/ids.js'
-import type { DeliverableRef } from '../summary/deliverable.js'
+import type { DeliverableRef } from '../../types/summary/deliverable.js'
 
 /**
  * Minimal record the validator needs to step ancestrally from one

package/src/session/retention/__tests__/archive.test.ts

@@ -2,15 +2,15 @@ import { mkdtempSync, rmSync } from 'node:fs'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
-import type { ActorRef } from '../../../session/hierarchy/actor.js'
-import type { SubSession } from '../../../session/hierarchy/sub-session.js'
 import { type ExecFile, GitWorktreeDriver } from '../../../session/workspace/git-worktree.js'
-import type { WorkspaceRef } from '../../../session/workspace/ref.js'
 import { WorkspaceBackendRegistry } from '../../../session/workspace/registry.js'
 import { InMemorySessionStore } from '../../../store/session/memory.js'
 import type { AgentId, TenantId, UserId } from '../../../types/ids/index.js'
 import { createUserMessage } from '../../../types/message/index.js'
+import type { ActorRef } from '../../../types/session/actor.js'
 import type { ThreadId, WorkspaceId } from '../../../types/session/ids.js'
+import type { SubSession } from '../../../types/session/sub-session.js'
+import type { WorkspaceRef } from '../../../types/workspace/ref.js'
 import {
 	ArchivalManager,
 	ArchiveNotConfiguredError,

package/src/session/retention/__tests__/disk-backend.test.ts

@@ -3,13 +3,13 @@ import { readFile, readdir } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { afterEach, beforeEach, describe, expect, it } from 'vitest'
-import type { SessionMessage } from '../../../store/session/messages.js'
 import type { MessageId, SessionId, TenantId } from '../../../types/ids/index.js'
 import { createUserMessage } from '../../../types/message/index.js'
+import type { ArchiveBackendRef } from '../../../types/retention/archive-backend-ref.js'
 import type { SubSessionId, SummaryId, WorkspaceId } from '../../../types/session/ids.js'
-import type { SessionSummaryRef } from '../../summary/ref.js'
-import type { WorkspaceRef } from '../../workspace/ref.js'
-import type { ArchiveBackendRef } from '../archive-backend-ref.js'
+import type { SessionMessage } from '../../../types/session/messages.js'
+import type { SessionSummaryRef } from '../../../types/summary/ref.js'
+import type { WorkspaceRef } from '../../../types/workspace/ref.js'
 import { DiskArchiveBackend } from '../disk-backend.js'
 
 const tenantA = 'tnt_alpha' as TenantId

package/src/session/retention/archive.ts

@@ -28,8 +28,8 @@
 import type { SessionId, SubSessionId, TenantId } from '../../types/ids/index.js'
 import type { WorkspaceId } from '../../types/session/ids.js'
 import type { SessionStore } from '../../types/session/store.js'
-import type { SubSession, SubSessionStatus } from '../hierarchy/sub-session.js'
-import type { WorkspaceRef } from '../workspace/ref.js'
+import type { SubSession, SubSessionStatus } from '../../types/session/sub-session.js'
+import type { WorkspaceRef } from '../../types/workspace/ref.js'
 import type { WorkspaceBackendRegistry } from '../workspace/registry.js'
 import type { ArchiveBackend, SubSessionTombstone } from './backend.js'
 

package/src/session/retention/backend.ts

@@ -12,12 +12,12 @@
  * `SessionStore` is the Store it mutates.
  */
 
-import type { SessionMessage } from '../../store/session/messages.js'
 import type { SessionId, SubSessionId, TenantId } from '../../types/ids/index.js'
+import type { ArchiveBackendRef } from '../../types/retention/archive-backend-ref.js'
 import type { SummaryId } from '../../types/session/ids.js'
-import type { SessionSummaryRef } from '../summary/ref.js'
-import type { WorkspaceRef } from '../workspace/ref.js'
-import type { ArchiveBackendRef } from './archive-backend-ref.js'
+import type { SessionMessage } from '../../types/session/messages.js'
+import type { SessionSummaryRef } from '../../types/summary/ref.js'
+import type { WorkspaceRef } from '../../types/workspace/ref.js'
 
 /**
  * Output of a successful {@link ArchiveBackend.store} call. `archiveRef` is

package/src/session/retention/disk-backend.ts

@@ -29,11 +29,11 @@
 import { randomBytes } from 'node:crypto'
 import { mkdir, readFile, readdir, rename, unlink, writeFile } from 'node:fs/promises'
 import { join } from 'node:path'
-import type { SessionMessage } from '../../store/session/messages.js'
 import type { SessionId, SubSessionId, TenantId } from '../../types/ids/index.js'
-import type { SessionSummaryRef } from '../summary/ref.js'
-import type { WorkspaceRef } from '../workspace/ref.js'
-import type { ArchiveBackendRef } from './archive-backend-ref.js'
+import type { ArchiveBackendRef } from '../../types/retention/archive-backend-ref.js'
+import type { SessionMessage } from '../../types/session/messages.js'
+import type { SessionSummaryRef } from '../../types/summary/ref.js'
+import type { WorkspaceRef } from '../../types/workspace/ref.js'
 import type { ArchiveBackend, ArchiveInput, ArchiveOutput } from './backend.js'
 
 /**