@namzu/sdk 0.4.1 → 0.4.2

package/src/session/retention/index.ts

@@ -1,9 +1,11 @@
 // Sub-barrel for the retention/archival module (Convention #4).
-// Concrete types + manager live in sibling files.
+// Concrete shape types live under `types/retention/`; runtime machinery
+// (backend contract, manager, disk backend) lives in sibling files under
+// `session/retention/`.
 
-export type { ArchiveBackendRef } from './archive-backend-ref.js'
-export type { RetentionPolicy } from './policy.js'
-export { RETENTION_POLICY_DISABLED } from './policy.js'
+export type { ArchiveBackendRef } from '../../types/retention/archive-backend-ref.js'
+export type { RetentionPolicy } from '../../types/retention/policy.js'
+export { RETENTION_POLICY_DISABLED } from '../../types/retention/policy.js'
 export type { ArchiveBackend, ArchiveInput, ArchiveOutput, SubSessionTombstone } from './backend.js'
 export {
 	ArchivalManager,

package/src/session/{hierarchy/__tests__/session.test.ts → status/__tests__/derive.test.ts}

@@ -1,5 +1,7 @@
 import { describe, expect, it } from 'vitest'
 import type { RunStatus } from '../../../types/run/status.js'
+import type { ActorRef } from '../../../types/session/actor.js'
+import type { Session, SessionStatus } from '../../../types/session/entity.js'
 import type {
 	ProjectId,
 	SessionId,
@@ -7,8 +9,7 @@ import type {
 	ThreadId,
 	UserId,
 } from '../../../types/session/ids.js'
-import type { ActorRef } from '../actor.js'
-import { type Session, type SessionStatus, deriveStatus } from '../session.js'
+import { deriveStatus } from '../derive.js'
 
 const tenant = 'tnt_a' as TenantId
 const project = 'prj_a' as ProjectId

package/src/session/{hierarchy/session.ts → status/derive.ts}

@@ -1,61 +1,11 @@
-import type { SessionId, TenantId } from '../../types/ids/index.js'
-import type { RunStatus } from '../../types/run/status.js'
-import type { ProjectId, ThreadId, WorkspaceId } from '../../types/session/ids.js'
-import type { ActorRef } from './actor.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 Thread} this Session lives under.
- *     Set at creation, immutable; Sessions never move threads.
- *   - `projectId` — the {@link 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).
- */
-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
-}
-
 /**
  * Pure Run→Session fan-in helper per session-hierarchy.md §5.1.
  *
+ * Extracted from `session/hierarchy/session.ts` on 2026-04-21 (ses_010 commit
+ * 4) so the shape definition can live under `types/session/` while the
+ * runtime helper stays in a feature folder — the type-layering rule
+ * (`types/` = pure shapes, feature folders = runtime).
+ *
  * The precedence (highest first) matches the pattern-doc table:
  *   1. Session-level states that do not fan in from Run status:
  *      - `locked` (handoff CAS window) — preserved verbatim
@@ -75,6 +25,10 @@ export interface Session {
  * not a terminal Session state"). Only `failed` runs drive the Session to
  * `failed` when every Run ended that way.
  */
+
+import type { RunStatus } from '../../types/run/status.js'
+import type { Session, SessionStatus } from '../../types/session/entity.js'
+
 export function deriveStatus(
 	session: Session,
 	runs: readonly { status: RunStatus }[],

package/src/session/summary/__tests__/materialize.test.ts

@@ -1,16 +1,13 @@
 import { describe, expect, it } from 'vitest'
 import { TenantIsolationError } from '../../../session/errors.js'
-import type { ActorRef } from '../../../session/hierarchy/actor.js'
 import { InMemorySessionStore } from '../../../store/session/memory.js'
 import type { AgentId, SessionId, TenantId, UserId } from '../../../types/ids/index.js'
+import type { ActorRef } from '../../../types/session/actor.js'
 import type { SummaryId, ThreadId } from '../../../types/session/ids.js'
-import type { DeliverableRef } from '../deliverable.js'
+import type { DeliverableRef } from '../../../types/summary/deliverable.js'
+import { AGENT_SUMMARY_MAX_CHARS } from '../../../types/summary/ref.js'
+import { AgentSummaryTooLongError, SessionAlreadySummarizedError } from '../errors.js'
 import { SessionSummaryMaterializer } from '../materialize.js'
-import {
-	AGENT_SUMMARY_MAX_CHARS,
-	AgentSummaryTooLongError,
-	SessionAlreadySummarizedError,
-} from '../ref.js'
 
 const TEST_THREAD_ID = 'thd_test' as ThreadId
 

package/src/session/summary/errors.ts

@@ -0,0 +1,51 @@
+/**
+ * Runtime errors emitted by the session-summary materialization path.
+ *
+ * Split from `session/summary/ref.ts` on 2026-04-21 (ses_010 commit 1): the
+ * shape types moved to `types/summary/ref.ts`; runtime behaviour (error
+ * classes, materializer) remains under `session/summary/`. This keeps the
+ * type-layering rule consistent — `types/` holds only pure shapes.
+ */
+
+import type { SessionId } from '../../types/ids/index.js'
+import type { SummaryId } from '../../types/session/ids.js'
+
+/**
+ * Raised by `SessionSummaryMaterializer.materialize` when the provided
+ * `agentSummary` exceeds the max-character bound declared at
+ * `types/summary/ref.ts#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 `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/summary/index.ts

@@ -1,9 +1,9 @@
 // Sub-barrel for the session summary module (Convention #4).
 //
 // See session-hierarchy.md §4.7 (SessionSummaryRef shape) and §8.1
-// (kernel-only emission invariant). Concrete types and the materializer live
-// in sibling files; re-export them here so consumers import via
-// `../session/summary/index.js`.
+// (kernel-only emission invariant). Shape types live under
+// `types/summary/`; runtime (materializer + error classes) lives in
+// sibling files under `session/summary/`.
 
 export type {
 	ArtifactBlobDeliverable,
@@ -12,18 +12,15 @@ export type {
 	FileDeliverable,
 	MessageDeliverable,
 	SessionSummaryDeliverable,
-} from './deliverable.js'
-export {
-	AGENT_SUMMARY_MAX_CHARS,
-	AgentSummaryTooLongError,
-	SessionAlreadySummarizedError,
-} from './ref.js'
+} from '../../types/summary/deliverable.js'
+export { AGENT_SUMMARY_MAX_CHARS } from '../../types/summary/ref.js'
 export type {
 	SessionSummaryKeyDecision,
 	SessionSummaryOutcome,
 	SessionSummaryOutcomeStatus,
 	SessionSummaryRef,
-} from './ref.js'
+} from '../../types/summary/ref.js'
+export { AgentSummaryTooLongError, SessionAlreadySummarizedError } from './errors.js'
 export { SessionSummaryMaterializer } from './materialize.js'
 export type {
 	MaterializeInput,

package/src/session/summary/materialize.ts

@@ -19,18 +19,17 @@
  */
 
 import type { SessionId, TenantId } from '../../types/ids/index.js'
+import type { Session } from '../../types/session/entity.js'
 import type { SummaryId } from '../../types/session/ids.js'
 import type { SessionStore } from '../../types/session/store.js'
-import type { Session } from '../hierarchy/session.js'
-import type { DeliverableRef } from './deliverable.js'
+import type { DeliverableRef } from '../../types/summary/deliverable.js'
 import {
 	AGENT_SUMMARY_MAX_CHARS,
-	AgentSummaryTooLongError,
-	SessionAlreadySummarizedError,
 	type SessionSummaryKeyDecision,
 	type SessionSummaryOutcome,
 	type SessionSummaryRef,
-} from './ref.js'
+} from '../../types/summary/ref.js'
+import { AgentSummaryTooLongError, SessionAlreadySummarizedError } from './errors.js'
 
 /**
  * Dependencies for {@link SessionSummaryMaterializer}. The generator is

package/src/session/workspace/__tests__/git-worktree.test.ts

@@ -1,4 +1,5 @@
 import { describe, expect, it, vi } from 'vitest'
+import type { WorkspaceRef } from '../../../types/workspace/ref.js'
 import { WorkspaceBackendError } from '../../errors.js'
 import {
 	type ExecFile,
@@ -6,7 +7,6 @@ import {
 	GitWorktreeDriver,
 	parseWorktreeList,
 } from '../git-worktree.js'
-import type { WorkspaceRef } from '../ref.js'
 
 function stubLogger() {
 	return {

package/src/session/workspace/driver.ts

@@ -9,7 +9,7 @@
  * later phase (Convention #10: provider abstraction).
  */
 
-import type { WorkspaceBackendKind, WorkspaceRef } from './ref.js'
+import type { WorkspaceBackendKind, WorkspaceRef } from '../../types/workspace/ref.js'
 
 /**
  * Params for {@link WorkspaceBackendDriver.create}. `baseRef` selects the
@@ -57,4 +57,4 @@ export interface WorkspaceBackendDriver {
 	inspect(ref: WorkspaceRef): Promise<WorkspaceInspection>
 }
 
-export type { WorkspaceBackendKind } from './ref.js'
+export type { WorkspaceBackendKind } from '../../types/workspace/ref.js'

package/src/session/workspace/git-worktree.ts

@@ -13,6 +13,7 @@
 import { execFile } from 'node:child_process'
 import { join } from 'node:path'
 import { promisify } from 'node:util'
+import type { GitWorktreeBackendMeta, WorkspaceRef } from '../../types/workspace/ref.js'
 import { generateWorkspaceId } from '../../utils/id.js'
 import type { Logger } from '../../utils/logger.js'
 import { WorkspaceBackendError } from '../errors.js'
@@ -22,7 +23,6 @@ import type {
 	WorkspaceBackendDriver,
 	WorkspaceInspection,
 } from './driver.js'
-import type { GitWorktreeBackendMeta, WorkspaceRef } from './ref.js'
 
 const execFileAsync = promisify(execFile)
 

package/src/session/workspace/index.ts

@@ -1,13 +1,14 @@
 // Sub-barrel for the workspace module (Convention #4).
-// Concrete types + driver implementation live in sibling files; re-export
-// them here so other modules import via `../session/workspace/index.js`.
+// Shape types live under `types/workspace/`; runtime machinery (drivers,
+// registry, path-builder, git-worktree) lives in sibling files under
+// `session/workspace/`.
 
 export type {
-	WorkspaceRef,
-	WorkspaceBackendMeta,
-	WorkspaceBackendKind,
 	GitWorktreeBackendMeta,
-} from './ref.js'
+	WorkspaceBackendKind,
+	WorkspaceBackendMeta,
+	WorkspaceRef,
+} from '../../types/workspace/ref.js'
 
 export type {
 	WorkspaceBackendDriver,

package/src/store/run/disk.ts

@@ -1,7 +1,7 @@
 import { appendFile, mkdir, readFile, readdir, rename, unlink, writeFile } from 'node:fs/promises'
 import { join } from 'node:path'
 import type { CheckpointId, IterationCheckpoint } from '../../types/hitl/index.js'
-import type { AgentRun, RunEvent, RunStoreConfig } from '../../types/run/index.js'
+import type { Run, RunEvent, RunStoreConfig } from '../../types/run/index.js'
 import { type Logger, getRootLogger } from '../../utils/logger.js'
 
 export class RunDiskStore {
@@ -44,7 +44,7 @@ export class RunDiskStore {
 		await appendFile(join(dir, 'transcript.jsonl'), line, 'utf-8')
 	}
 
-	async writeRunMeta(run: AgentRun): Promise<void> {
+	async writeRunMeta(run: Run): Promise<void> {
 		const dir = this.requireInit()
 
 		const meta: Record<string, unknown> = {
@@ -65,7 +65,7 @@ export class RunDiskStore {
 		await atomicWriteJson(join(dir, 'run.json'), meta)
 	}
 
-	async writeMessages(run: AgentRun): Promise<void> {
+	async writeMessages(run: Run): Promise<void> {
 		const dir = this.requireInit()
 		await atomicWriteJson(join(dir, 'messages.json'), run.messages)
 	}
@@ -151,7 +151,7 @@ export class RunDiskStore {
 		}
 	}
 
-	async addToIndex(run: AgentRun): Promise<void> {
+	async addToIndex(run: Run): Promise<void> {
 		if (run.parentRunId) return
 
 		const prev = this.indexLock

package/src/store/session/__tests__/disk.test.ts

@@ -4,9 +4,9 @@ import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { afterEach, beforeEach, describe, expect, it } from 'vitest'
 import { TenantIsolationError } from '../../../session/errors.js'
-import type { ActorRef } from '../../../session/hierarchy/actor.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 { DiskSessionStore } from '../disk.js'
 
 const tenantA = 'tnt_alpha' as TenantId
@@ -389,9 +389,9 @@ describe('DiskSessionStore', () => {
 	})
 })
 
-import type { SessionSummaryRef } from '../../../session/summary/ref.js'
 // Import after use so tests are self-contained w.r.t. types we already use.
 import type { SessionId } from '../../../types/ids/index.js'
 import type { SummaryId, ThreadId } from '../../../types/session/ids.js'
+import type { SessionSummaryRef } from '../../../types/summary/ref.js'
 
 const TEST_THREAD_ID = 'thd_test' as ThreadId

package/src/store/session/__tests__/memory.test.ts

@@ -1,10 +1,10 @@
 import { describe, expect, it } from 'vitest'
 import { TenantIsolationError } from '../../../session/errors.js'
-import type { ActorRef } from '../../../session/hierarchy/actor.js'
-import type { SubSession } from '../../../session/hierarchy/sub-session.js'
 import type { AgentId, SessionId, 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 } from '../../../types/session/ids.js'
+import type { SubSession } from '../../../types/session/sub-session.js'
 import { InMemorySessionStore } from '../memory.js'
 
 const TEST_THREAD_ID = 'thd_test' as ThreadId

package/src/store/session/disk.ts

@@ -33,19 +33,13 @@ import {
 } from 'node:fs/promises'
 import { join } from 'node:path'
 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 type { DeliverableRef } from '../../session/summary/deliverable.js'
-import { SessionAlreadySummarizedError } from '../../session/summary/ref.js'
-import type {
-	SessionSummaryKeyDecision,
-	SessionSummaryOutcome,
-	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, SummaryId, ThreadId } from '../../types/session/ids.js'
+import type { SessionMessage } from '../../types/session/messages.js'
 import type {
 	CreateProjectParams,
 	CreateSessionParams,
@@ -53,6 +47,13 @@ import type {
 	SessionStore,
 	SessionView,
 } from '../../types/session/store.js'
+import type { SubSession } from '../../types/session/sub-session.js'
+import type { DeliverableRef } from '../../types/summary/deliverable.js'
+import type {
+	SessionSummaryKeyDecision,
+	SessionSummaryOutcome,
+	SessionSummaryRef,
+} from '../../types/summary/ref.js'
 import {
 	generateMessageId,
 	generateProjectId,
@@ -61,7 +62,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'
 
 /**
  * Config for {@link DiskSessionStore}. `rootDir` is absolute; all files live
@@ -973,4 +973,4 @@ async function atomicWriteJson(filePath: string, value: unknown): Promise<void>
 // line is a whole record. This matches pattern doc §13.4 persistence
 // (`messages.json[l]` as append-only event log).
 
-export type { SessionMessage } from './messages.js'
+export type { SessionMessage } from '../../types/session/messages.js'

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/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'