@namzu/sdk 0.4.1 → 0.4.3

package/src/store/session/index.ts

@@ -3,11 +3,12 @@
 // Messages are scoped to a `SessionId` and every accessor carries explicit
 // `TenantId` (Convention #17). Concrete implementations live in sibling
 // files; re-export them here so consumers import via
-// `../store/session/index.js`.
+// `../store/session/index.js`. The `SessionMessage` shape lives under
+// `types/session/messages.ts` — re-exported here for convenience.
 
 export { InMemorySessionStore } from './memory.js'
 export { DiskSessionStore } from './disk.js'
 export type { DiskSessionStoreConfig } from './disk.js'
-export type { SessionMessage } from './messages.js'
+export type { SessionMessage } from '../../types/session/messages.js'
 export { getAncestry, getChildren, orderChildren } from './linkage.js'
 export type { LinkageView } from './linkage.js'

package/src/store/session/linkage.ts

@@ -9,9 +9,9 @@
  */
 
 import { AncestryCycleError } from '../../session/errors.js'
-import type { SubSession } from '../../session/hierarchy/sub-session.js'
 import type { SessionId } from '../../types/ids/index.js'
 import type { SubSessionId } from '../../types/session/ids.js'
+import type { SubSession } from '../../types/session/sub-session.js'
 
 /**
  * Read shape required by the pure linkage helpers. Both in-memory and disk

package/src/store/session/memory.ts

@@ -9,14 +9,13 @@
  */
 
 import { TenantIsolationError } from '../../session/errors.js'
-import type { Project } from '../../session/hierarchy/project.js'
-import type { Session } from '../../session/hierarchy/session.js'
-import type { SubSession } from '../../session/hierarchy/sub-session.js'
-import { SessionAlreadySummarizedError } from '../../session/summary/ref.js'
-import type { SessionSummaryRef } from '../../session/summary/ref.js'
+import { SessionAlreadySummarizedError } from '../../session/summary/errors.js'
 import type { MessageId, SessionId, TenantId } from '../../types/ids/index.js'
 import type { Message } from '../../types/message/index.js'
+import type { Project } from '../../types/project/entity.js'
+import type { Session } from '../../types/session/entity.js'
 import type { ProjectId, SubSessionId, ThreadId } from '../../types/session/ids.js'
+import type { SessionMessage } from '../../types/session/messages.js'
 import type {
 	CreateProjectParams,
 	CreateSessionParams,
@@ -24,6 +23,8 @@ import type {
 	SessionStore,
 	SessionView,
 } from '../../types/session/store.js'
+import type { SubSession } from '../../types/session/sub-session.js'
+import type { SessionSummaryRef } from '../../types/summary/ref.js'
 import {
 	generateMessageId,
 	generateProjectId,
@@ -32,7 +33,6 @@ import {
 } from '../../utils/id.js'
 import { getAncestry, getChildren, orderChildren } from './linkage.js'
 import type { LinkageView } from './linkage.js'
-import type { SessionMessage } from './messages.js'
 
 interface ProjectRecord {
 	tenantId: TenantId

package/src/store/thread/disk.ts

@@ -22,9 +22,9 @@
 import { mkdir, readFile, readdir, rename, rm, unlink, writeFile } from 'node:fs/promises'
 import { join } from 'node:path'
 import { StaleThreadError, TenantIsolationError } from '../../session/errors.js'
-import type { Thread, ThreadStatus } from '../../session/hierarchy/thread.js'
 import type { TenantId } from '../../types/ids/index.js'
 import type { ProjectId, ThreadId } from '../../types/session/ids.js'
+import type { Thread, ThreadStatus } from '../../types/thread/entity.js'
 import type { CreateThreadParams, ThreadStore } from '../../types/thread/store.js'
 import { generateThreadId } from '../../utils/id.js'
 

package/src/store/thread/memory.ts

@@ -9,9 +9,9 @@
  */
 
 import { StaleThreadError, TenantIsolationError } from '../../session/errors.js'
-import type { Thread } from '../../session/hierarchy/thread.js'
 import type { TenantId } from '../../types/ids/index.js'
 import type { ProjectId, ThreadId } from '../../types/session/ids.js'
+import type { Thread } from '../../types/thread/entity.js'
 import type { CreateThreadParams, ThreadStore } from '../../types/thread/store.js'
 import { generateThreadId } from '../../utils/id.js'
 

package/src/telemetry/attributes.ts

@@ -8,10 +8,6 @@ export function agentIterationSpanName(iteration: number): string {
 	return `namzu.agent.iteration ${iteration}`
 }
 
-export function chatSpanName(model: string): string {
-	return `chat ${model}`
-}
-
 export function toolSpanName(toolName: string): string {
 	return `namzu.tool.execute ${toolName}`
 }

package/src/telemetry/runtime-accessors.ts

@@ -8,12 +8,8 @@
 // return the no-op defaults and every span/meter write is silently
 // discarded — standard OTEL library behavior.
 
-import { type Meter, type Tracer, metrics, trace } from '@opentelemetry/api'
+import { type Tracer, trace } from '@opentelemetry/api'
 
 export function getTracer(): Tracer {
 	return trace.getTracer('namzu')
 }
-
-export function getMeter(): Meter {
-	return metrics.getMeter('namzu')
-}

package/src/test-setup.ts

@@ -0,0 +1,24 @@
+/**
+ * Vitest `setupFiles` entry for `@namzu/sdk`.
+ *
+ * Silences the root logger for the entire test run. Tests that assert on
+ * log output use their own mocked Logger instances (constructed via the
+ * `makeLogger()` helpers colocated with each test) — those are not
+ * affected by the root-level silence.
+ *
+ * The only thing this suppresses is the stderr spam produced by
+ * production code paths that fall through to `getRootLogger()` — e.g.
+ * `ToolRegistry.execute`'s zod-validation and thrown-error branches,
+ * `ConnectorToolRouter.getTools`' per-instance error catch, the
+ * AgentBus listener-throw handler, and every connector's `connect()`
+ * info log. GitHub Actions annotates any `[ERROR]` stderr line as a
+ * workflow error; silencing the root logger during tests keeps the CI
+ * log clean.
+ *
+ * This is test-only configuration. It runs before every test file and
+ * does not affect consumers.
+ */
+
+import { configureLogger } from './utils/logger.js'
+
+configureLogger({ level: 'silent' })

package/src/types/agent/task.ts

@@ -1,5 +1,5 @@
-import type { ActorRef } from '../../session/hierarchy/actor.js'
-import type { WorkspaceBackendKind } from '../../session/workspace/ref.js'
+import type { ActorRef } from '../../types/session/actor.js'
+import type { WorkspaceBackendKind } from '../../types/workspace/ref.js'
 import type { TokenUsage } from '../common/index.js'
 import type { RunId, SessionId, TaskId, TenantId } from '../ids/index.js'
 import type { Message } from '../message/index.js'

package/src/{session/hierarchy/project.ts → types/project/entity.ts}

@@ -1,6 +1,6 @@
-import type { KnowledgeBaseRef, MemoryStoreRef, TenantId, VaultRef } from '../../types/ids/index.js'
-import type { ProjectId } from '../../types/session/ids.js'
-import type { RetentionPolicy } from '../retention/policy.js'
+import type { RetentionPolicy } from '../../types/retention/policy.js'
+import type { KnowledgeBaseRef, MemoryStoreRef, TenantId, VaultRef } from '../ids/index.js'
+import type { ProjectId } from '../session/ids.js'
 
 /**
  * Per-project configuration. Defaults per session-hierarchy.md §3 / §4.2 /

package/src/types/project/index.ts

@@ -0,0 +1,4 @@
+// Sub-barrel for the project shape surface (Convention #4).
+// Concrete types live in sibling files; re-export them here.
+
+export type { Project, ProjectConfig } from './entity.js'

package/src/types/retention/index.ts

@@ -0,0 +1,6 @@
+// Sub-barrel for the retention shape surface (Convention #4).
+// Concrete types live in sibling files; re-export them here.
+
+export type { ArchiveBackendRef } from './archive-backend-ref.js'
+export type { RetentionPolicy } from './policy.js'
+export { RETENTION_POLICY_DISABLED } from './policy.js'

package/src/types/run/entity.ts

@@ -0,0 +1,63 @@
+import type { AgentStatus, CostInfo, TokenUsage } from '../common/index.js'
+import type { RunId } from '../ids/index.js'
+import type { Message } from '../message/index.js'
+import type { AgentRunConfig } from './config.js'
+import type { ReplayAttribution } from './replay.js'
+import type { StopReason } from './stop-reason.js'
+
+export interface RunStateMetadata {
+	agentId: string
+	agentName: string
+	config: AgentRunConfig
+	provider: string
+}
+
+export type SessionMetadata = RunStateMetadata
+
+/**
+ * Domain Run entity — the persistence record for a single agent invocation
+ * under a {@link import('../session/entity.js').Session}. Renamed from
+ * `AgentRun` on 2026-04-21 (ses_010 commit 7) to match the 5-layer hierarchy
+ * (`Project → Thread → Session → SubSession → Run`) ratified in ses_001.
+ *
+ * The wire counterpart is `WireRun` under `contracts/api.ts` — the two stay
+ * decoupled so the HTTP field shape can evolve independently from this
+ * persistence record. See `docs/sdk/sessions/` for the public hierarchy
+ * reference.
+ */
+export interface Run {
+	id: RunId
+	status: AgentStatus
+	metadata: RunStateMetadata
+	messages: Message[]
+	tokenUsage: TokenUsage
+	costInfo: CostInfo
+	currentIteration: number
+	startedAt: number
+	endedAt?: number
+	stopReason?: StopReason
+	lastError?: string
+	result?: string
+
+	parentRunId?: RunId
+
+	depth?: number
+
+	/**
+	 * Present when this run was produced by {@link replay}. `undefined` for
+	 * original runs. See `ses_005-deterministic-replay` for the primitive.
+	 */
+	replayOf?: ReplayAttribution
+}
+
+/**
+ * @deprecated Use {@link Run}. Alias retained for the 0.4.x compatibility
+ * window; scheduled for removal in a later session.
+ */
+export type AgentRun = Run
+
+/**
+ * @deprecated Use {@link Run}. Alias retained for the 0.4.x compatibility
+ * window; scheduled for removal in a later session.
+ */
+export type AgentSession = Run

package/src/types/run/events.ts

@@ -1,9 +1,3 @@
-import type {
-	SubsessionIdledEvent,
-	SubsessionMessagedEvent,
-	SubsessionSpawnedEvent,
-} from '../../session/events/index.js'
-import type { Lineage } from '../../session/hierarchy/lineage.js'
 import type { ActivityStatus, ActivityType } from '../activity/index.js'
 import type { BaseAgentResult } from '../agent/base.js'
 import type { CostInfo, TokenUsage } from '../common/index.js'
@@ -12,6 +6,12 @@ import type { ActivityId, PlanId, PluginId, RunId, SandboxId, TaskId } from '../
 import type { PlanStep } from '../plan/index.js'
 import type { PluginHookEvent, PluginHookResult } from '../plugin/index.js'
 import type { TaskStatus } from '../task/index.js'
+import type { Lineage } from './lineage.js'
+import type {
+	SubsessionIdledEvent,
+	SubsessionMessagedEvent,
+	SubsessionSpawnedEvent,
+} from './subsession-events.js'
 
 export type { StopReason } from './stop-reason.js'
 

package/src/types/run/index.ts

@@ -1,14 +1,21 @@
 export * from './stop-reason.js'
 export * from './config.js'
-export * from './state.js'
-// Note: `./status.js` is intentionally NOT re-exported via `export *` from
-// this barrel — the domain `RunStatus` type (session-hierarchy.md §4.6)
-// shares its name with the deprecated wire alias `RunStatus` in
-// `contracts/api.ts` (the canonical wire name is now `WireRunStatus`, see
-// Task 10 Phase 9). The root barrel re-exports the domain `RunStatus`
-// explicitly via `export type { RunStatus } from './types/run/status.js'`
-// so external consumers of `@namzu/sdk` land on the domain enum while
-// `@namzu/contracts` continues to own the wire shape.
+export * from './entity.js'
+export * from './replay.js'
+// Domain `RunStatus` (session-hierarchy.md §4.6 state machine). Safe to
+// re-export via `export *` now — the former wire-side `RunStatus` alias was
+// renamed to `WireRunStatus` in ses_010 commit 7, so there is no longer a
+// collision to avoid.
+export * from './status.js'
 export * from './events.js'
 export * from './metadata.js'
 export * from './emergency.js'
+export type { Lineage } from './lineage.js'
+export type {
+	SubsessionIdledEvent,
+	SubsessionLifecycleEvent,
+	SubsessionMessagedEvent,
+	SubsessionSpawnedEvent,
+} from './subsession-events.js'
+export { RUN_EVENT_SCHEMA_VERSION } from './schema-version.js'
+export type { RunEventSchemaVersion } from './schema-version.js'

package/src/{session/hierarchy → types/run}/lineage.ts

@@ -1,4 +1,4 @@
-import type { SessionId } from '../../types/ids/index.js'
+import type { SessionId } from '../ids/index.js'
 
 /**
  * Parent/root linkage carried on every sub-session event.

package/src/types/run/replay.ts

@@ -0,0 +1,61 @@
+import type { CheckpointId, RunId, ToolCallId } from '../ids/index.js'
+import type { ToolResult } from '../tool/index.js'
+
+/**
+ * Controlled mutation applied at the fork point during {@link replay}.
+ *
+ * v1 ships a single variant: `injectToolResponse` — the 80% debugging use
+ * case. Additional variants (`swapProvider`, `overrideBudget`, etc.) are
+ * deferred; see ses_005-deterministic-replay §3.3.
+ */
+export type Mutation = {
+	type: 'injectToolResponse'
+	toolCallId: ToolCallId
+	response: ToolResult
+}
+
+/**
+ * Lightweight listing entry returned by {@link listCheckpoints}. Projected
+ * from {@link import('../hitl/index.js').IterationCheckpoint} — not a full
+ * checkpoint payload, just enough to pick a fork point.
+ *
+ * Named `CheckpointListEntry` (not `CheckpointSummary`) to avoid collision
+ * with the pre-existing HITL `CheckpointSummary` shape at
+ * `types/hitl/index.ts`.
+ */
+export interface CheckpointListEntry {
+	id: CheckpointId
+	runId: RunId
+	iteration: number
+	createdAt: number
+	messageCount: number
+}
+
+/**
+ * Attribution record stamped on a {@link Run} produced by {@link replay}.
+ * Non-replay runs have `replayOf === undefined`. Shape mirrors voltagent's
+ * `replayedFromExecutionId` / `replayFromStepId` pattern, folded into a
+ * single optional rather than three parallel ones.
+ */
+export interface ReplayAttribution {
+	sourceRunId: RunId
+	fromCheckpointId: CheckpointId
+	mutations: Mutation[]
+	replayedAt: number
+}
+
+/**
+ * Thrown when a {@link Mutation} cannot be applied at the resolved fork
+ * point. Currently raised by `injectToolResponse` when the supplied
+ * `toolCallId` does not match any pending tool call in the checkpoint's
+ * last assistant message.
+ */
+export class MutationNotApplicableError extends Error {
+	constructor(
+		message: string,
+		public readonly availableToolCallIds: readonly ToolCallId[],
+	) {
+		super(message)
+		this.name = 'MutationNotApplicableError'
+	}
+}

package/src/{session/events/types.ts → types/run/subsession-events.ts}

@@ -1,7 +1,7 @@
-import type { MessageId, RunId, SessionId } from '../../types/ids/index.js'
-import type { SubSessionId } from '../../types/session/ids.js'
-import type { ActorRef } from '../hierarchy/actor.js'
-import type { Lineage } from '../hierarchy/lineage.js'
+import type { MessageId, RunId, SessionId } from '../ids/index.js'
+import type { ActorRef } from '../session/actor.js'
+import type { SubSessionId } from '../session/ids.js'
+import type { Lineage } from './lineage.js'
 import type { RunEventSchemaVersion } from './schema-version.js'
 
 /**

package/src/{session/hierarchy → types/session}/actor.ts

@@ -1,4 +1,4 @@
-import type { AgentId, TenantId, UserId } from '../../types/ids/index.js'
+import type { AgentId, TenantId, UserId } from '../ids/index.js'
 
 /**
  * Discriminated union of actors that can own a {@link Session}.

package/src/types/session/entity.ts

@@ -0,0 +1,59 @@
+import type { SessionId, TenantId } from '../ids/index.js'
+import type { ActorRef } from './actor.js'
+import type { ProjectId, ThreadId, WorkspaceId } from './ids.js'
+
+/**
+ * Session lifecycle states. See session-hierarchy.md §4.3 and the state
+ * machine in §5.1. `awaiting_merge` is a sub-state of idle used on the
+ * broadcast source session (§5.4) between fan-out and all recipients
+ * terminalizing.
+ */
+export type SessionStatus =
+	| 'active'
+	| 'idle'
+	| 'locked'
+	| 'awaiting_hitl'
+	| 'awaiting_merge'
+	| 'failed'
+	| 'archived'
+
+/**
+ * Multi-turn work unit owned by exactly one {@link ActorRef} at a time.
+ *
+ * Scope identifiers:
+ *   - `threadId` — the topic-level {@link import('../thread/entity.js').Thread}
+ *     this Session lives under. Set at creation, immutable; Sessions never
+ *     move threads.
+ *   - `projectId` — the {@link import('../project/entity.js').Project} the
+ *     owning Thread belongs to. **Denormalized** from `thread.projectId` at
+ *     creation time; immutable. Kept on the Session record for ergonomic
+ *     access (Project-scoped consumers — handoff validators, archival,
+ *     retention — would otherwise need a second round-trip to ThreadStore
+ *     on every read). This is NOT a deprecated mirror of a fading field;
+ *     it is a deliberate denormalization of structurally-immutable derived
+ *     data.
+ *
+ * Other invariants (session-hierarchy.md §4.3):
+ *   - `previousActors` is append-only and publicly read-only; previous
+ *     owners cannot write to the session again.
+ *   - `ownerVersion` is the CAS counter for handoff (§6.1 / §6.2 / §6.4).
+ *   - `workspaceId` is nullable for sessions whose workspace has not yet
+ *     been provisioned (or has been torn down during archival).
+ *
+ * The pure `deriveStatus(session, runs)` fan-in helper lives at
+ * `session/status/derive.ts` — it is runtime, not a shape, so it is not
+ * colocated with this interface.
+ */
+export interface Session {
+	id: SessionId
+	threadId: ThreadId
+	projectId: ProjectId
+	tenantId: TenantId
+	status: SessionStatus
+	currentActor: ActorRef | null
+	previousActors: readonly ActorRef[]
+	workspaceId: WorkspaceId | null
+	ownerVersion: number
+	createdAt: Date
+	updatedAt: Date
+}

package/src/types/session/index.ts

@@ -25,3 +25,18 @@ export type {
 	CreateSessionParams,
 	CreateSubSessionParams,
 } from './store.js'
+
+export type { SessionMessage } from './messages.js'
+
+export type { ActorRef, SystemRoleId } from './actor.js'
+
+export type { Session, SessionStatus } from './entity.js'
+
+export type {
+	CompletionMode,
+	DeliverableRef,
+	FailureMode,
+	SubSession,
+	SubSessionKind,
+	SubSessionStatus,
+} from './sub-session.js'

package/src/{store → types}/session/messages.ts

@@ -9,8 +9,8 @@
  * addressability + tenant isolation.
  */
 
-import type { MessageId, SessionId, TenantId } from '../../types/ids/index.js'
-import type { Message } from '../../types/message/index.js'
+import type { MessageId, SessionId, TenantId } from '../ids/index.js'
+import type { Message } from '../message/index.js'
 
 export interface SessionMessage {
 	readonly id: MessageId

package/src/types/session/store.ts

@@ -6,17 +6,17 @@
  * API — extensions land alongside their consumers.
  */
 
-import type { ActorRef } from '../../session/hierarchy/actor.js'
-import type { Project } from '../../session/hierarchy/project.js'
-import type { Session } from '../../session/hierarchy/session.js'
+import type { Project } from '../../types/project/entity.js'
+import type { ActorRef } from '../../types/session/actor.js'
+import type { Session } from '../../types/session/entity.js'
+import type { SessionMessage } from '../../types/session/messages.js'
 import type {
 	CompletionMode,
 	FailureMode,
 	SubSession,
 	SubSessionKind,
-} from '../../session/hierarchy/sub-session.js'
-import type { SessionSummaryRef } from '../../session/summary/ref.js'
-import type { SessionMessage } from '../../store/session/messages.js'
+} from '../../types/session/sub-session.js'
+import type { SessionSummaryRef } from '../../types/summary/ref.js'
 import type { MessageId, SessionId, TenantId } from '../ids/index.js'
 import type { Message } from '../message/index.js'
 import type { ProjectId, SubSessionId, SummaryId, ThreadId } from '../session/ids.js'

package/src/{session/hierarchy → types/session}/sub-session.ts

@@ -1,8 +1,8 @@
-import type { SessionId } from '../../types/ids/index.js'
-import type { SubSessionId, SummaryId, WorkspaceId } from '../../types/session/ids.js'
-import type { ArchiveBackendRef } from '../retention/archive-backend-ref.js'
-import type { DeliverableRef } from '../summary/deliverable.js'
+import type { ArchiveBackendRef } from '../../types/retention/archive-backend-ref.js'
+import type { DeliverableRef } from '../../types/summary/deliverable.js'
+import type { SessionId } from '../ids/index.js'
 import type { ActorRef } from './actor.js'
+import type { SubSessionId, SummaryId, WorkspaceId } from './ids.js'
 
 /**
  * Full 11-variant status union. See session-hierarchy.md §4.4 and the merge
@@ -50,15 +50,15 @@ export type CompletionMode = 'summary_ref' | 'merge_back'
 /**
  * Re-export of the real {@link DeliverableRef} discriminated union. The
  * concrete shape lives in `../summary/deliverable.ts` — see
- * session-hierarchy.md §4.7 / §8.1. Phase 5 (this phase) replaced the Phase 1
- * `unknown` placeholder with the real type.
+ * session-hierarchy.md §4.7 / §8.1. Phase 5 replaced the Phase 1 `unknown`
+ * placeholder with the real type.
  */
 export type { DeliverableRef }
 
 /**
- * Edge between a parent {@link Session} and a child session, carrying the
- * delegation metadata. The child session itself lives in `SessionStore`
- * like any other session — see session-hierarchy.md §4.4.
+ * Edge between a parent {@link import('./entity.js').Session} and a child
+ * session, carrying the delegation metadata. The child session itself lives
+ * in `SessionStore` like any other session — see session-hierarchy.md §4.4.
  */
 export interface SubSession {
 	id: SubSessionId

package/src/{session → types}/summary/deliverable.ts

@@ -17,8 +17,8 @@
  * handle all variants exhaustively.
  */
 
-import type { RunId, SessionId } from '../../types/ids/index.js'
-import type { DeliverableId, SummaryId } from '../../types/session/ids.js'
+import type { RunId, SessionId } from '../ids/index.js'
+import type { DeliverableId, SummaryId } from '../session/ids.js'
 
 /** Discriminator for {@link DeliverableRef}. */
 export type DeliverableKind = 'file' | 'session_summary' | 'message' | 'artifact_blob'

package/src/types/summary/index.ts

@@ -0,0 +1,18 @@
+// Sub-barrel for the session-summary shape surface (Convention #4).
+// Concrete types live in sibling files; re-export them here.
+
+export type {
+	ArtifactBlobDeliverable,
+	DeliverableKind,
+	DeliverableRef,
+	FileDeliverable,
+	MessageDeliverable,
+	SessionSummaryDeliverable,
+} from './deliverable.js'
+export { AGENT_SUMMARY_MAX_CHARS } from './ref.js'
+export type {
+	SessionSummaryKeyDecision,
+	SessionSummaryOutcome,
+	SessionSummaryOutcomeStatus,
+	SessionSummaryRef,
+} from './ref.js'

package/src/{session → types}/summary/ref.ts

@@ -1,9 +1,9 @@
 /**
  * SessionSummaryRef — the structured pointer a parent session sees when a
  * sub-session completes. Kernel-owned terminalization primitive: the only
- * producer is {@link SessionSummaryMaterializer.materialize} (see
- * `./materialize.ts`). See session-hierarchy.md §4.7 (shape) and §8.1
- * (emission invariant).
+ * producer is `SessionSummaryMaterializer.materialize` (see
+ * `session/summary/materialize.ts`). See session-hierarchy.md §4.7 (shape)
+ * and §8.1 (emission invariant).
  *
  * The `materializedBy: 'kernel'` literal field is load-bearing — combined
  * with the opaque {@link SummaryId} brand (mintable only by
@@ -14,10 +14,14 @@
  *
  * This is Convention #0 load-bearing: there is no "tool" path to emit a
  * summary; the parent agent sees only what the kernel seals.
+ *
+ * Runtime errors related to summary emission (`AgentSummaryTooLongError`,
+ * `SessionAlreadySummarizedError`) are runtime and therefore live at
+ * `session/summary/errors.ts` — they are NOT pure shapes.
  */
 
-import type { SessionId, TenantId } from '../../types/ids/index.js'
-import type { SummaryId } from '../../types/session/ids.js'
+import type { SessionId, TenantId } from '../ids/index.js'
+import type { SummaryId } from '../session/ids.js'
 import type { DeliverableRef } from './deliverable.js'
 
 /**
@@ -63,42 +67,3 @@ export interface SessionSummaryRef {
 	 */
 	readonly materializedBy: 'kernel'
 }
-
-/**
- * Raised by {@link SessionSummaryMaterializer.materialize} when the provided
- * `agentSummary` exceeds {@link AGENT_SUMMARY_MAX_CHARS}. Convention #5
- * deny-by-default — the kernel does not truncate silently.
- */
-export class AgentSummaryTooLongError extends Error {
-	readonly details: {
-		readonly actual: number
-		readonly max: number
-	}
-
-	constructor(details: { actual: number; max: number }) {
-		super(`agentSummary ${details.actual} chars exceeds max ${details.max}`)
-		this.name = 'AgentSummaryTooLongError'
-		this.details = details
-	}
-}
-
-/**
- * Raised when {@link SessionSummaryMaterializer.materialize} is invoked
- * against a session that already has a persisted summary. Re-materialization
- * would duplicate history — callers wanting to append must open a new
- * intervention sub-session (see session-hierarchy.md §4.5).
- */
-export class SessionAlreadySummarizedError extends Error {
-	readonly details: {
-		readonly sessionId: SessionId
-		readonly existingSummaryId: SummaryId
-	}
-
-	constructor(details: { sessionId: SessionId; existingSummaryId: SummaryId }) {
-		super(
-			`Session ${details.sessionId} already has summary ${details.existingSummaryId}; re-materialization rejected`,
-		)
-		this.name = 'SessionAlreadySummarizedError'
-		this.details = details
-	}
-}

package/src/{session/hierarchy/tenant.ts → types/tenant/entity.ts}

@@ -1,4 +1,4 @@
-import type { TenantId } from '../../types/ids/index.js'
+import type { TenantId } from '../ids/index.js'
 
 /**
  * Tenancy boundary for everything in the hierarchy.