@namzu/sdk 0.2.0 → 0.3.0

package/src/store/thread/memory.ts

@@ -0,0 +1,104 @@
+/**
+ * InMemoryThreadStore — reference in-memory implementation of
+ * {@link ThreadStore}.
+ *
+ * Mirrors the write-time CAS contract of the disk store: every
+ * `updateThread` compares the supplied `ownerVersion` against the persisted
+ * copy and rejects with `StaleThreadError` on mismatch. Convention #17:
+ * cross-tenant access throws `TenantIsolationError` with no fallback.
+ */
+
+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 { CreateThreadParams, ThreadStore } from '../../types/thread/store.js'
+import { generateThreadId } from '../../utils/id.js'
+
+interface ThreadRecord {
+	tenantId: TenantId
+	thread: Thread
+}
+
+export class InMemoryThreadStore implements ThreadStore {
+	private readonly threads = new Map<ThreadId, ThreadRecord>()
+
+	async createThread(params: CreateThreadParams, tenantId: TenantId): Promise<Thread> {
+		const now = new Date()
+		const thread: Thread = {
+			id: generateThreadId(),
+			projectId: params.projectId,
+			tenantId,
+			title: params.title,
+			status: 'open',
+			ownerVersion: 0,
+			createdAt: now,
+			updatedAt: now,
+		}
+		this.threads.set(thread.id, { tenantId, thread })
+		return thread
+	}
+
+	async getThread(threadId: ThreadId, tenantId: TenantId): Promise<Thread | null> {
+		const record = this.threads.get(threadId)
+		if (!record) return null
+		this.assertTenant(record.tenantId, tenantId, `thread(${threadId})`)
+		return record.thread
+	}
+
+	async updateThread(thread: Thread, tenantId: TenantId): Promise<void> {
+		if (thread.tenantId !== tenantId) {
+			throw new TenantIsolationError({
+				requested: tenantId,
+				resource: `thread(${thread.id}) payload`,
+			})
+		}
+		const existing = this.threads.get(thread.id)
+		if (!existing) {
+			throw new Error(`Thread ${thread.id} not found`)
+		}
+		this.assertTenant(existing.tenantId, tenantId, `thread(${thread.id})`)
+
+		// CAS on ownerVersion — supplied version must match persisted exactly.
+		// Any drift means another writer already advanced the record; the caller
+		// must re-read + re-apply + retry.
+		if (thread.ownerVersion !== existing.thread.ownerVersion) {
+			throw new StaleThreadError({
+				threadId: thread.id,
+				expectedVersion: thread.ownerVersion,
+				actualVersion: existing.thread.ownerVersion,
+			})
+		}
+
+		const updated: Thread = {
+			...thread,
+			ownerVersion: existing.thread.ownerVersion + 1,
+			updatedAt: new Date(),
+		}
+		this.threads.set(thread.id, { tenantId, thread: updated })
+	}
+
+	async deleteThread(threadId: ThreadId, tenantId: TenantId): Promise<void> {
+		const record = this.threads.get(threadId)
+		if (!record) return // Idempotent: missing = no-op.
+		this.assertTenant(record.tenantId, tenantId, `thread(${threadId})`)
+		this.threads.delete(threadId)
+	}
+
+	async listThreads(projectId: ProjectId, tenantId: TenantId): Promise<readonly Thread[]> {
+		const matches: Thread[] = []
+		for (const { tenantId: ownerTenant, thread } of this.threads.values()) {
+			if (ownerTenant !== tenantId) continue
+			if (thread.projectId !== projectId) continue
+			matches.push(thread)
+		}
+		matches.sort((a, b) => a.createdAt.getTime() - b.createdAt.getTime())
+		return matches
+	}
+
+	private assertTenant(owning: TenantId, requested: TenantId, resource: string): void {
+		if (owning !== requested) {
+			throw new TenantIsolationError({ requested, resource })
+		}
+	}
+}

package/src/types/agent/base.ts

@@ -1,10 +1,10 @@
 import type { AgentStatus, CostInfo, TokenUsage } from '../common/index.js'
-import type { RunId, SessionId, TenantId, ThreadId } from '../ids/index.js'
+import type { RunId, SessionId, TenantId } from '../ids/index.js'
 import type { InvocationState } from '../invocation/index.js'
 import type { Message } from '../message/index.js'
 import type { PermissionMode } from '../permission/index.js'
 import type { StopReason } from '../run/stop-reason.js'
-import type { ProjectId } from '../session/ids.js'
+import type { ProjectId, ThreadId } from '../session/ids.js'
 import type { TaskStore } from '../task/index.js'
 import type { ToolAvailability } from '../tool/index.js'
 
@@ -24,29 +24,25 @@ export interface BaseAgentConfig {
 	env?: Record<string, string>
 
 	/**
-	 * @deprecated Use `projectId`. Kept as a migration-window mirror; when both
-	 * are present `projectId` wins. See session-hierarchy.md §13.1.
+	 * Long-lived goal scope for the run. Required at runtime — agents reject
+	 * configs missing this (`'X requires sessionId, projectId, and tenantId
+	 * in config'`).
+	 *
+	 * Kept optional at the TYPE level because {@link AgentManager} stamps
+	 * this field AFTER `configBuilder` returns (manager/agent/lifecycle.ts).
+	 * Tightening to required is a separate task alongside
+	 * `AgentFactoryOptions` carrying the triple.
 	 */
-	threadId?: ThreadId
+	projectId?: ProjectId
 
 	/**
-	 * Long-lived goal scope for the run. Required at runtime in 0.2.0 per
-	 * session-hierarchy.md §12.1 — `{@link ReactiveAgent}`, `{@link
-	 * SupervisorAgent}`, etc. reject configs missing this (`'X requires
-	 * sessionId, projectId, and tenantId in config (§12.1)'`).
-	 *
-	 * Kept optional at the TYPE level during the 0.2.x migration window
-	 * because {@link AgentManager} stamps this field AFTER `configBuilder`
-	 * returns (manager/agent/lifecycle.ts:228–230). That stamping path is
-	 * how every `@namzu/agents` configBuilder currently gets its tenant /
-	 * session / project triple; flipping the type to required without first
-	 * updating every {@link AgentFactoryOptions} consumer (which does not
-	 * carry these fields) would be a gratuitous downstream break.
-	 *
-	 * Tightening to required is Phase 9 Known Delta #6. The type-level flip
-	 * lands in 0.3.0 alongside `AgentFactoryOptions` gaining the triple.
+	 * Topic the run belongs to. Optional at the TYPE level for the same
+	 * reason as `projectId` — {@link AgentManager} stamps this field after
+	 * `configBuilder` returns so `configBuilder` implementations do not
+	 * need to be updated before this tightens. Tightening to required
+	 * lands with the `AgentFactoryOptions` triple refactor.
 	 */
-	projectId?: ProjectId
+	threadId?: ThreadId
 
 	/** Session under which the run executes. See `projectId` for the tightening plan. */
 	sessionId?: SessionId

package/src/types/agent/factory.ts

@@ -14,7 +14,14 @@ export interface AgentDefinition {
 }
 
 export interface AgentFactoryOptions {
-	apiKey: string
+	/**
+	 * API key for providers that authenticate via key (OpenAI, Anthropic,
+	 * OpenRouter). Optional because BYO-provider flows (Bedrock IAM, custom
+	 * `ProviderRegistry.create(...)`) resolve credentials outside this object.
+	 * `configBuilder` implementations should treat an absent `apiKey` as the
+	 * BYO signal and use the provider passed via the agent config instead.
+	 */
+	apiKey?: string
 	model?: string
 	workingDirectory?: string
 	tokenBudget?: number
@@ -39,8 +46,6 @@ export interface AgentFactoryOptions {
 
 	taskRouter?: TaskRouterConfig
 
-	threadId?: string
-
 	runId?: string
 
 	parentRunId?: string

package/src/types/agent/task.ts

@@ -4,7 +4,7 @@ import type { TokenUsage } from '../common/index.js'
 import type { RunId, SessionId, TaskId, TenantId } from '../ids/index.js'
 import type { Message } from '../message/index.js'
 import type { RunEventListener } from '../run/events.js'
-import type { ProjectId } from '../session/ids.js'
+import type { ProjectId, ThreadId } from '../session/ids.js'
 import type { AgentInput, BaseAgentConfig, BaseAgentResult } from './base.js'
 import type { Agent } from './core.js'
 import type { AgentFactoryOptions } from './factory.js'
@@ -23,15 +23,10 @@ export function isTerminalAgentTaskState(state: AgentTaskState): boolean {
 }
 
 /**
- * Context carried into {@link AgentManager.sendMessage}. Phase 6 promotes
- * `tenantId`, `sessionId`, `projectId`, and `parentActor` to required fields —
- * the spawn path is the ingress point for the session hierarchy; callers must
- * provide the full scoping set (session-hierarchy.md §12.1 required-callsite
- * matrix).
- *
- * `threadId` was removed — `projectId` owns the root scope. The deprecated
- * alias `type ThreadId = ProjectId` still compiles for consumers transitioning
- * off the name, but the shape no longer exposes a separate slot.
+ * Context carried into {@link AgentManager.sendMessage}. `tenantId`,
+ * `threadId`, `sessionId`, `projectId`, and `parentActor` are required —
+ * the spawn path is the ingress point for the session hierarchy; callers
+ * must provide the full scoping set.
  */
 export interface AgentTaskContext {
 	parentRunId: RunId
@@ -49,13 +44,26 @@ export interface AgentTaskContext {
 	/** Isolation boundary. Required per session-hierarchy.md §12.1. */
 	tenantId: TenantId
 
+	/**
+	 * Topic the current task belongs to. Required in 0.3.0 — spawn copies
+	 * this onto the child session without a second ThreadStore round-trip,
+	 * and gates creation on {@link ThreadManager.requireOpen}. Children
+	 * inherit the parent's `threadId` verbatim; cross-thread spawn is
+	 * forbidden by design (a delegated sub-agent stays on the same topic).
+	 */
+	threadId: ThreadId
+
 	/**
 	 * Parent session under which any sub-agent spawn is recorded. Required
 	 * in 0.2.0; a spawn cannot be attributed without it.
 	 */
 	sessionId: SessionId
 
-	/** Long-lived goal scope (replaces `threadId`). Required. */
+	/**
+	 * Long-lived goal scope. Required. Denormalized from the owning Thread
+	 * (see {@link Thread}) — structurally immutable per Phase 2.4 decision
+	 * (sessions never cross threads, threads never cross projects).
+	 */
 	projectId: ProjectId
 
 	/**

package/src/types/ids/index.ts

@@ -38,29 +38,22 @@ export type MemoryStoreRef = `mms_${string}`
 export type VaultRef = `vlt_${string}`
 export type KnowledgeBaseRef = `kbs_${string}`
 
-// Session hierarchy IDs — live canonically here (Phase 9 Known Delta #4
-// collapse: previously split across `types/ids/` and `types/session/ids.ts`
-// with a circular re-export). Convention #2 branded IDs; prefixes mandated
-// by session-hierarchy.md §4. The `types/session/ids.ts` barrel re-exports
-// these for co-location ergonomics.
+// Session hierarchy IDs. Convention #2 branded IDs; prefixes mandated by the
+// five-layer hierarchy (Project → Thread → Session → SubSession → Run). The
+// `types/session/ids.ts` barrel re-exports these for co-location ergonomics.
 export type ProjectId = `prj_${string}`
+export type ThreadId = `thd_${string}`
 export type SubSessionId = `sub_${string}`
 export type HandoffId = `hof_${string}`
 export type WorkspaceId = `wsp_${string}`
 export type SummaryId = `sum_${string}`
 export type DeliverableId = `del_${string}`
 
-/**
- * @deprecated Use {@link ProjectId}. Alias retained for the 0.2.x migration
- * window; will be removed in 0.3.0. See session-hierarchy.md §13.3.1.
- */
-export type ThreadId = ProjectId
-
 /**
  * Sentinel {@link TenantId} for legacy pre-0.2.0 runs rehomed by the
- * boot-time filesystem migration (session-hierarchy.md §13.4.1). Consumers
- * with strict tenant enforcement should either tag these records on first
- * access or reject them until a real tenant is assigned — the kernel
- * surfaces the sentinel but does not prescribe policy (Convention #17).
+ * boot-time filesystem migration. Consumers with strict tenant enforcement
+ * should either tag these records on first access or reject them until a
+ * real tenant is assigned — the kernel surfaces the sentinel but does not
+ * prescribe policy (Convention #17).
  */
 export const UNKNOWN_TENANT_ID = 'tnt_unknown_legacy' as TenantId

package/src/types/rag/retrieval.ts

@@ -1,4 +1,5 @@
-import type { KnowledgeBaseId, ThreadId } from '../ids/index.js'
+import type { KnowledgeBaseId } from '../ids/index.js'
+import type { ProjectId } from '../session/ids.js'
 import type { TenantScope } from './scope.js'
 import type { VectorSearchResult } from './vector.js'
 
@@ -13,8 +14,8 @@ export interface RetrievalConfig {
 
 export interface RetrievalQuery {
 	text: string
-	threadId?: ThreadId
-	threadMessages?: string[]
+	projectId?: ProjectId
+	recentMessages?: string[]
 	config?: Partial<RetrievalConfig>
 }
 

package/src/types/run/config.ts

@@ -2,7 +2,7 @@ import type { ModelPricing } from '../../utils/cost.js'
 import type { Logger } from '../../utils/logger.js'
 import type { RunId, SessionId, TenantId } from '../ids/index.js'
 import type { PermissionMode } from '../permission/index.js'
-import type { ProjectId } from '../session/ids.js'
+import type { ProjectId, ThreadId } from '../session/ids.js'
 
 export interface AgentRunConfig {
 	model: string
@@ -22,10 +22,10 @@ export interface AgentRunConfig {
 }
 
 /**
- * Config for {@link RunPersistence}. Phase 6 promotes `sessionId`, `tenantId`,
- * and `projectId` to required — every Run must be attributed to a Session
- * under a Project within a Tenant (session-hierarchy.md §12.1). The legacy
- * `threadId`-only shape is gone.
+ * Config for {@link RunPersistence}. `sessionId`, `threadId`, `tenantId`,
+ * and `projectId` are required — every Run is attributed across the full
+ * five-layer scope (Tenant → Project → Thread → Session → Run,
+ * Convention #17).
  */
 export interface RunPersistenceConfig {
 	runId: RunId
@@ -38,6 +38,7 @@ export interface RunPersistenceConfig {
 	log: Logger
 
 	sessionId: SessionId
+	threadId: ThreadId
 	tenantId: TenantId
 	projectId: ProjectId
 

package/src/types/run/metadata.ts

@@ -1,33 +1,20 @@
 import type { AgentStatus, CostInfo, TokenUsage } from '../common/index.js'
-import type { RunId, TaskId, TenantId, ThreadId } from '../ids/index.js'
+import type { RunId, TaskId, TenantId } from '../ids/index.js'
 import type { ProjectId } from '../session/ids.js'
 import type { StopReason } from './stop-reason.js'
 
 /**
  * Denormalized metadata for a run.
  *
- * See session-hierarchy.md §4.6, §10.1, and §12.1.
- *
- * 0.2.0 promotes `projectId` and `tenantId` to required fields. `threadId`
- * remains as a deprecated mirror of `projectId` for the 0.2.x migration
- * window — consumers should prefer `projectId` and fall back to `threadId`
- * only for legacy records. 0.3.x removes `threadId` entirely (§13.1).
+ * `projectId` and `tenantId` are required per Convention #17 — every run is
+ * attributed to a Project within a Tenant.
  */
 export interface RunMetadata {
 	id: RunId
-	/**
-	 * Long-lived goal scope. Required in 0.2.0. Replaces the root-scope role
-	 * `threadId` played in 0.1.x.
-	 */
+	/** Long-lived goal scope. Required. */
 	projectId: ProjectId
-	/** Isolation boundary (Convention #17). Required in 0.2.0. */
+	/** Isolation boundary (Convention #17). Required. */
 	tenantId: TenantId
-	/**
-	 * @deprecated Use {@link RunMetadata.projectId}. Mirror retained for the
-	 * 0.2.x migration window; scheduled for removal in 0.3.0 per
-	 * session-hierarchy.md §13.1.
-	 */
-	threadId: ThreadId
 	agentId: string
 	agentName: string
 	status: AgentStatus

package/src/types/session/ids.ts

@@ -1,16 +1,14 @@
 /**
  * Session hierarchy branded ID re-export barrel.
  *
- * Canonical definitions live in `../ids/index.ts` (Phase 9 Known Delta #4
- * collapse: previously this file declared ProjectId/SubSessionId/etc. and
- * `types/ids/` re-exported them — a circular re-export that TypeScript
- * resolved cleanly but smelled). All session IDs now live in one place;
- * this barrel exists solely for ergonomic co-location with session-scoped
- * callers (they already import from `types/session/`).
+ * Canonical definitions live in `../ids/index.ts`. This barrel exists solely
+ * for ergonomic co-location with session-scoped callers (they already import
+ * from `types/session/`).
  */
 
 export type {
 	ProjectId,
+	ThreadId,
 	SubSessionId,
 	HandoffId,
 	WorkspaceId,
@@ -22,13 +20,4 @@ export type {
 	AgentId,
 	UserId,
 	TaskId,
-	ThreadId,
 } from '../ids/index.js'
-
-import type { ProjectId } from '../ids/index.js'
-
-/**
- * @deprecated Use {@link ProjectId}. Alias kept for one version migration
- * window; scheduled for removal in 0.3.0 per session-hierarchy.md §13.3.1.
- */
-export type ThreadIdDeprecated = ProjectId

package/src/types/session/index.ts

@@ -4,6 +4,7 @@
 
 export type {
 	ProjectId,
+	ThreadId,
 	SubSessionId,
 	HandoffId,
 	WorkspaceId,
@@ -15,8 +16,6 @@ export type {
 	AgentId,
 	UserId,
 	TaskId,
-	ThreadId,
-	ThreadIdDeprecated,
 } from './ids.js'
 
 export type {

package/src/types/session/store.ts

@@ -1,14 +1,9 @@
 /**
  * SessionStore — canonical persistence contract for the session hierarchy.
  *
- * Replaces `ConversationStore` (deprecated; `types/conversation/index.ts`).
- * Per session-hierarchy.md §4 Entity Model, §10.4 Parent-Child Linkage, §12
- * Multi-Tenant and Security — every accessor takes explicit {@link TenantId}
- * (Convention #17). Cross-tenant access rejects with `TenantIsolationError`.
- *
- * Minimum surface — covers downstream phases 4 (handoff), 5 (summary), and
- * 6 (sub-session spawn) plus the drill primitive (§14.3). Extensions land in
- * paired phases alongside their consumers (Convention #0: no speculative API).
+ * Every accessor takes explicit {@link TenantId} (Convention #17). Cross-tenant
+ * access rejects with `TenantIsolationError`. Convention #0: no speculative
+ * API — extensions land alongside their consumers.
  */
 
 import type { ActorRef } from '../../session/hierarchy/actor.js'
@@ -24,13 +19,22 @@ import type { SessionSummaryRef } from '../../session/summary/ref.js'
 import type { SessionMessage } from '../../store/session/messages.js'
 import type { MessageId, SessionId, TenantId } from '../ids/index.js'
 import type { Message } from '../message/index.js'
-import type { ProjectId, SubSessionId, SummaryId } from '../session/ids.js'
+import type { ProjectId, SubSessionId, SummaryId, ThreadId } from '../session/ids.js'
 
 /**
  * Params for {@link SessionStore.createSession}. The store owns id generation,
- * `ownerVersion` initialization, and timestamps. See session-hierarchy.md §4.3.
+ * `ownerVersion` initialization, and timestamps.
+ *
+ * Both `threadId` and `projectId` are required. `projectId` must equal the
+ * `projectId` of the thread identified by `threadId`; the store does NOT
+ * perform that cross-store consistency check (it has no ThreadStore handle
+ * by design — see the store-boundary rationale in {@link ThreadStore}). The
+ * caller is the authority; typically spawn and handoff paths copy both from
+ * a freshly-loaded `Thread` record or from their own context which already
+ * tracks both.
  */
 export interface CreateSessionParams {
+	threadId: ThreadId
 	projectId: ProjectId
 	/**
 	 * Initial owner of the session. May be `null` for bootstrap scenarios where
@@ -103,6 +107,25 @@ export interface SessionStore {
 
 	updateSession(session: Session, tenantId: TenantId): Promise<void>
 
+	/**
+	 * List every Session that belongs to the given Thread for the caller's
+	 * tenant, ordered by `createdAt` ascending. Returns an empty array when
+	 * none exist.
+	 *
+	 * Thread-scoped queries rely on `session.threadId` (set at creation, never
+	 * rewritten). Cross-tenant sessions that happen to share the supplied
+	 * `threadId` are silently skipped — the listing is tenant-scoped, not an
+	 * isolation violation (the caller did not request a specific record).
+	 *
+	 * Exists to back ThreadManager's archival + delete preconditions
+	 * ({@link import('../../manager/thread/lifecycle.js').ThreadManager.archive}
+	 * rejects when any session is in a non-terminal state; `delete` rejects
+	 * while any session still references the thread). Keeping this primitive
+	 * on {@link SessionStore} preserves the store-ownership boundary —
+	 * ThreadStore stays unaware of session layout (Convention #0).
+	 */
+	listSessions(threadId: ThreadId, tenantId: TenantId): Promise<readonly Session[]>
+
 	/**
 	 * Hard-delete a session. Idempotent — absent sessions succeed as a no-op.
 	 * Rejects with `TenantIsolationError` on cross-tenant access.
@@ -137,7 +160,7 @@ export interface SessionStore {
 	 */
 	deleteSubSession(subSessionId: SubSessionId, tenantId: TenantId): Promise<void>
 
-	// Messages (replaces ConversationStore surface) ---------------------------
+	// Messages -----------------------------------------------------------------
 
 	/**
 	 * Append a single message to the session's message log. Returns the

package/src/types/thread/index.ts

@@ -0,0 +1,5 @@
+// Sub-barrel for the Thread type surface (Convention #4).
+// Concrete types live in sibling files; re-export them here so consumers
+// import via `../types/thread/index.js`.
+
+export type { ThreadStore, CreateThreadParams } from './store.js'

package/src/types/thread/store.ts

@@ -0,0 +1,92 @@
+/**
+ * ThreadStore — canonical persistence contract for the Thread topic layer
+ * (Project → **Thread** → Session → SubSession → Run).
+ *
+ * Threads are pure containers (Phase 0 decision B.1). They have no own
+ * message stream and no fan-in `deriveStatus()` — status is owner-managed
+ * (`'open' | 'archived'`). Every accessor takes explicit {@link TenantId};
+ * cross-tenant access rejects with `TenantIsolationError` (Convention #17).
+ *
+ * Read accessors return `null` when the resource does not exist for the
+ * supplied tenant (deny-by-default surface). Callers branch on missing
+ * explicitly — no fallback substitution.
+ *
+ * `deleteThread` is intentionally a dumb record-delete at this layer:
+ * it does NOT walk session ownership. The "reject when sessions attached"
+ * precondition lives in {@link import('../../manager/thread/lifecycle.js').ThreadManager}
+ * where both stores are in scope. Keeping ThreadStore free of cross-store
+ * awareness preserves the single-boundary ownership boundary that Phase 2
+ * has just introduced for this layer (Convention #0).
+ */
+
+import type { Thread } from '../../session/hierarchy/thread.js'
+import type { TenantId } from '../ids/index.js'
+import type { ProjectId, ThreadId } from '../session/ids.js'
+
+/**
+ * Params for {@link ThreadStore.createThread}. The store owns id generation,
+ * `ownerVersion` initialization (0 at create), and timestamps.
+ */
+export interface CreateThreadParams {
+	projectId: ProjectId
+	/**
+	 * User-facing display label. Not unique within the project — see
+	 * {@link Thread} JSDoc. Empty strings are permitted; callers that require
+	 * a label should validate at the API layer.
+	 */
+	title: string
+}
+
+/**
+ * Canonical persistence contract for the Thread layer. Every accessor takes
+ * explicit `tenantId`; cross-tenant reads/writes reject with
+ * `TenantIsolationError` (`session/errors.ts`, Convention #17).
+ */
+export interface ThreadStore {
+	/**
+	 * Persist a new Thread under the given project. Returns the minted
+	 * {@link Thread} with `ownerVersion: 0` and freshly-generated
+	 * {@link ThreadId}. Callers must ensure the parent project exists and
+	 * belongs to the same tenant — the store does not validate project
+	 * ownership (that is a cross-store precondition owned by the manager).
+	 */
+	createThread(params: CreateThreadParams, tenantId: TenantId): Promise<Thread>
+
+	/**
+	 * Read a Thread by id. Returns `null` when absent. Cross-tenant reads
+	 * reject with `TenantIsolationError`.
+	 */
+	getThread(threadId: ThreadId, tenantId: TenantId): Promise<Thread | null>
+
+	/**
+	 * Persist a mutation to a Thread record. CAS on `ownerVersion`: if the
+	 * supplied `thread.ownerVersion` does not match the persisted version,
+	 * rejects with `StaleThreadError`. On success the write commits with
+	 * `ownerVersion + 1` and a refreshed `updatedAt`.
+	 *
+	 * Archival transition (`status: 'open' → 'archived'`) shares this path;
+	 * the caller is responsible for verifying that no non-terminal Sessions
+	 * are attached before flipping (see ThreadManager.archiveThread).
+	 */
+	updateThread(thread: Thread, tenantId: TenantId): Promise<void>
+
+	/**
+	 * Hard-delete a Thread record. Idempotent — absent threads succeed as a
+	 * no-op. Rejects with `TenantIsolationError` on cross-tenant access.
+	 *
+	 * **Does NOT cascade to child Sessions** — the caller (typically
+	 * ThreadManager) enforces the precondition that no Sessions reference
+	 * this thread. Convention #5: deny-by-default, no implicit cascade.
+	 */
+	deleteThread(threadId: ThreadId, tenantId: TenantId): Promise<void>
+
+	/**
+	 * List all Threads under a project for the given tenant, ordered by
+	 * `createdAt` ascending. Returns an empty array when none exist.
+	 * Cross-tenant reads reject with `TenantIsolationError`.
+	 *
+	 * The return shape is a concrete snapshot — callers that mutate the
+	 * result array do not affect store state.
+	 */
+	listThreads(projectId: ProjectId, tenantId: TenantId): Promise<readonly Thread[]>
+}

package/src/utils/id.ts

@@ -55,17 +55,12 @@ function generateId<T extends string>(prefix: T, length = 12): `${T}${string}` {
 	return `${prefix}${suffix}` as `${T}${string}`
 }
 
-/**
- * @deprecated Prefer {@link generateProjectId}. `ThreadId` is an alias of
- * `ProjectId` during the 0.2.x migration window; this helper emits the new
- * `prj_` prefix and will be removed in 0.3.0. See session-hierarchy.md §13.
- */
-export function generateThreadId(): ThreadId {
+export function generateProjectId(): ProjectId {
 	return generateId('prj_')
 }
 
-export function generateProjectId(): ProjectId {
-	return generateId('prj_')
+export function generateThreadId(): ThreadId {
+	return generateId('thd_')
 }
 
 export function generateRunId(): RunId {
@@ -199,22 +194,6 @@ function parseId<T extends string>(raw: string, prefix: string, typeName: string
 	return raw as T
 }
 
-/**
- * @deprecated Parses either the legacy `thd_*` prefix or the new `prj_*`
- * prefix during the 0.2.x migration window. 0.3.x will only accept `prj_*`.
- * See session-hierarchy.md §13.3.1.
- */
-export function parseThreadId(raw: string): ThreadId {
-	if (raw.startsWith('prj_')) {
-		return raw as ThreadId
-	}
-	if (raw.startsWith('thd_')) {
-		// Read-accept legacy prefix; a proper coercion pipeline lands in Phase 7.
-		return raw as unknown as ThreadId
-	}
-	throw new Error(`Invalid ThreadId: expected "prj_" or "thd_" prefix, got "${raw}"`)
-}
-
 export function parseProjectId(raw: string): ProjectId {
 	return parseId<ProjectId>(raw, 'prj_', 'ProjectId')
 }