@namzu/sdk 27.0.0 → 28.0.0

package/src/types/session/store.ts

@@ -19,22 +19,22 @@ import type {
 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'
+import type { ProjectId, SubSessionId, SummaryId, TopicId } from '../session/ids.js'
 
 /**
  * Params for {@link SessionStore.createSession}. The store owns id generation,
  * `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
+ * Both `topicId` and `projectId` are required. `projectId` must equal the
+ * `projectId` of the topic identified by `topicId`; the store does NOT
+ * perform that cross-store consistency check (it has no TopicStore handle
+ * by design — see the store-boundary rationale in {@link import('../topic/store.js').TopicStore}). 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
+ * a freshly-loaded `Topic` record or from their own context which already
  * tracks both.
  */
 export interface CreateSessionParams {
-	threadId: ThreadId
+	topicId: TopicId
 	projectId: ProjectId
 	/**
 	 * Initial owner of the session. May be `null` for bootstrap scenarios where
@@ -101,6 +101,19 @@ export interface CreateProjectParams {
 	 * workspaces is for.
 	 */
 	config?: ProjectConfigInput
+
+	/**
+	 * The directory this project's work happens in. Canonicalized through
+	 * `realpath` before storage, so a symlink or a trailing slash cannot
+	 * produce a second record for one directory.
+	 *
+	 * A second project for the same canonical directory is REFUSED, not
+	 * deduplicated into the first — a caller who wanted the existing one
+	 * should say so with {@link SessionStore.findProjectByRootPath}, and
+	 * silently returning it would hide that their `name` and `config` were
+	 * discarded.
+	 */
+	rootPath?: string
 }
 
 /**
@@ -132,6 +145,19 @@ export interface SessionStore {
 
 	getProject(projectId: ProjectId, tenantId: TenantId): Promise<Project | null>
 
+	/**
+	 * The project bound to a directory, or `null`. OPTIONAL.
+	 *
+	 * Optional for the reason `updateProjectConfig` below gives: this
+	 * interface is implemented by hosts, and a required method stops them
+	 * compiling for a capability they never asked for.
+	 *
+	 * The argument is canonicalized here too, so a caller may pass whatever
+	 * they have — a relative path, a symlink, a trailing slash — and get the
+	 * same answer the writer got.
+	 */
+	findProjectByRootPath?(rootPath: string, tenantId: TenantId): Promise<Project | null>
+
 	/**
 	 * Change a Project's limits after it exists. OPTIONAL.
 	 *
@@ -218,32 +244,37 @@ export interface SessionStore {
 	updateSession(session: Session, tenantId: TenantId, expectedOwnerVersion?: number): Promise<void>
 
 	/**
-	 * List every Session that belongs to the given Thread for the caller's
+	 * List every Session that belongs to the given Topic 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).
+	 * Renamed from `listSessions` alongside the `threadId` → `topicId` field
+	 * rename (NZ-TOPIC-03) — a query method named after the retired word
+	 * would have kept pointing at the concept this whole chain exists to
+	 * rename. Topic-scoped queries rely on `session.topicId` (set at
+	 * creation, never rewritten). Cross-tenant sessions that happen to share
+	 * the supplied `topicId` 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}
+	 * Exists to back TopicManager's archival + delete preconditions
+	 * ({@link import('../../manager/topic/lifecycle.js').TopicManager.archive}
 	 * rejects when any session is in a non-terminal state; `delete` rejects
-	 * while any session still references the thread). Keeping this primitive
+	 * while any session still references the topic). Keeping this primitive
 	 * on {@link SessionStore} preserves the store-ownership boundary —
-	 * ThreadStore stays unaware of session layout (Convention #0).
+	 * TopicStore stays unaware of session layout (Convention #0).
 	 */
-	listSessions(threadId: ThreadId, tenantId: TenantId): Promise<readonly Session[]>
+	listSessionsByTopic(topicId: TopicId, tenantId: TenantId): Promise<readonly Session[]>
 
 	/**
 	 * Every Session attached to a workspace, oldest first. OPTIONAL.
 	 *
-	 * The project-scoped sibling of {@link SessionStore.listSessions}, and the
-	 * one the archive precondition reads: closing a workspace has to know what
-	 * is still running in it, and "what is running in this thread" was never
-	 * the question — a project can hold sessions across many threads, and after
-	 * the Thread level is removed it is the only grouping left.
+	 * The project-scoped sibling of {@link SessionStore.listSessionsByTopic},
+	 * and the one the archive precondition reads: closing a workspace has to
+	 * know what is still running in it, and "what is running in this topic"
+	 * was never the question — a project can hold sessions across many
+	 * topics, and after the Topic level is removed it is the only grouping
+	 * left.
 	 */
 	listSessionsByProject?(projectId: ProjectId, tenantId: TenantId): Promise<readonly Session[]>
 

package/src/types/session/sub-session.ts

@@ -5,23 +5,56 @@ 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
- * state machine in §4.4.1. Absence of a `closed` state is load-bearing —
- * completed sub-sessions land on `idle` and stay there for drill-down
- * (Decision #5).
+ * The lifecycle of the DELEGATION — the edge from parent to child, not the
+ * child.
+ *
+ * This is the distinction the eleven-variant union lost. A `SubSession`
+ * record describes one parent's handoff to one child; the child is an
+ * ordinary `Session` in `SessionStore` with its own `SessionStatus`. Both
+ * unions carry `active`, `idle` and `archived`, and `SessionStatus`
+ * additionally carries `awaiting_merge` — so "is this thing active" had two
+ * answers and nothing said which record to ask.
+ *
+ * Ask this one about the delegation: has the parent handed off yet, is the
+ * child working, did the handoff fail, has the edge been retired. Ask
+ * `SessionStatus` about the child's own work.
+ *
+ * These five are every value the kernel produces. Absence of a `closed`
+ * state is load-bearing: a completed sub-session lands on `idle` and stays
+ * there so it can still be drilled into.
+ */
+export type SubSessionDelegationStatus = 'pending' | 'active' | 'idle' | 'failed' | 'archived'
+
+/**
+ * @deprecated Use {@link SubSessionDelegationStatus}. Removal is a later
+ * major, and the six extra members go with it.
+ *
+ * The merge half of this union was declared and never driven. Grepping
+ * `packages/sdk` and `packages/cli` for each of `awaiting_merge`,
+ * `pending_merge`, `merging`, `merged`, `merge_conflict` and
+ * `merge_rejected` AS A SUB-SESSION STATUS finds no writer at all — the
+ * many hits on `awaiting_merge` are `SessionStatus`, which is the shadowing
+ * this type's replacement exists to end. Two of them (`merged`,
+ * `merge_rejected`) had a READER: they sat in `ARCHIVABLE_STATUSES`, a set
+ * that could never match on them.
+ *
+ * The union stays this wide for one release so a host that persisted one of
+ * these values still typechecks while it migrates.
  */
 export type SubSessionStatus =
-	| 'pending'
-	| 'active'
-	| 'idle'
-	| 'failed'
+	| SubSessionDelegationStatus
+	/** @deprecated no producer since ratification */
 	| 'awaiting_merge'
+	/** @deprecated no producer since ratification */
 	| 'pending_merge'
+	/** @deprecated no producer since ratification */
 	| 'merging'
+	/** @deprecated no producer since ratification */
 	| 'merged'
+	/** @deprecated no producer since ratification */
 	| 'merge_conflict'
+	/** @deprecated no producer since ratification */
 	| 'merge_rejected'
-	| 'archived'
 
 /**
  * Discriminator for how a sub-session was created. Pattern doc §4.4
@@ -65,6 +98,14 @@ export interface SubSession {
 	parentSessionId: SessionId
 	childSessionId: SessionId
 	kind: SubSessionKind
+	/**
+	 * The DELEGATION's lifecycle, not the child's. The child session has its
+	 * own {@link import('./entity.js').SessionStatus}; when the two disagree
+	 * this one is authoritative about whether the parent still has a live
+	 * handoff, and that one is authoritative about whether the child is
+	 * working. Typed as the wide alias for one more release; every value the
+	 * kernel writes is a {@link SubSessionDelegationStatus}.
+	 */
 	status: SubSessionStatus
 	spawnedBy: ActorRef
 	spawnedAt: Date

package/src/types/skills/index.ts

@@ -1,3 +1,19 @@
+/**
+ * Who may reach for a skill.
+ *
+ * Every skill was offered to the model and to nobody else, and the two
+ * halves of that are both wrong. A skill that only an operator can
+ * meaningfully run — "collect a support bundle", "rotate the deploy key" —
+ * sat in the model's manifest as something to attempt, and the model would
+ * attempt it. A skill that is purely model guidance had no way to be
+ * offered to an operator at all.
+ *
+ * `both` is the default because it is what every existing skill silently
+ * was, and narrowing one is a decision its author makes rather than one a
+ * version bump makes for them.
+ */
+export type SkillInvocation = 'model' | 'operator' | 'both'
+
 export interface SkillMetadata {
 	name: string
 
@@ -9,9 +25,43 @@ export interface SkillMetadata {
 
 	allowedTools?: string
 
+	/**
+	 * Who may invoke this skill. Absent means {@link SKILL_INVOCATION_DEFAULT}.
+	 *
+	 * Optional rather than required, so that a `SkillMetadata` written
+	 * before this existed still type-checks — and resolved through
+	 * {@link skillInvocation} rather than with `?? 'both'` at each reader,
+	 * because the default is one decision and four copies of it is three
+	 * chances to disagree.
+	 */
+	invocation?: SkillInvocation
+
 	metadata?: Record<string, string>
 }
 
+/** What a skill that says nothing means. */
+export const SKILL_INVOCATION_DEFAULT: SkillInvocation = 'both'
+
+/** The skill's stated policy, or the default. */
+export function skillInvocation(skill: { metadata: SkillMetadata }): SkillInvocation {
+	return skill.metadata.invocation ?? SKILL_INVOCATION_DEFAULT
+}
+
+/**
+ * May this audience reach for this skill?
+ *
+ * `both` satisfies either side, which is the only reason the third value
+ * exists — a two-value policy would force every author to pick a side for a
+ * skill that genuinely serves both.
+ */
+export function isInvocableBy(
+	skill: { metadata: SkillMetadata },
+	audience: 'model' | 'operator',
+): boolean {
+	const policy = skillInvocation(skill)
+	return policy === 'both' || policy === audience
+}
+
 export interface Skill {
 	metadata: SkillMetadata
 

package/src/types/tool/index.ts

@@ -1,9 +1,16 @@
 import type { z } from 'zod'
 import type { Logger } from '../../utils/logger.js'
+import type { CodeNavigationProvider } from '../code-navigation/index.js'
+// Type-only, and circular by design: a tool-result guardrail is described in
+// terms of the tool that produced the result, and the registry that holds
+// the guardrails is described here. Erased at compile time, so neither
+// module exists at runtime to depend on the other.
+import type { ToolResultGuardrailSpec } from '../guardrail/index.js'
 import type { RunId } from '../ids/index.js'
 import type { InvocationState } from '../invocation/index.js'
 import type { PermissionMode } from '../permission/index.js'
 import type { Sandbox } from '../sandbox/index.js'
+import type { ToolPresentation } from './presentation.js'
 
 export interface ToolRegistryRef {
 	searchDeferred(query: string): ToolDefinition[]
@@ -11,6 +18,72 @@ export interface ToolRegistryRef {
 	getAvailability(name: string): ToolAvailability
 }
 
+/**
+ * The slice of the background job registry a tool is given.
+ *
+ * A structural reference rather than the class, for the reason
+ * `ToolRegistryRef` exists: this type file is imported by everything, and
+ * naming the implementation here would drag a `node:child_process` module
+ * into every consumer's type graph. `owner` is not on this surface at all —
+ * the executor binds it to the run, so a tool cannot start a job that
+ * outlives, or is billed to, somebody else's run.
+ */
+/**
+ * The slice of the skills registry a tool is given.
+ *
+ * Structural for the reason `ToolRegistryRef` is: this file is imported by
+ * everything, and naming `SkillRegistry` here would drag the skill loader's
+ * filesystem imports into every consumer's type graph.
+ */
+export interface SkillRegistryRef {
+	/**
+	 * Load a skill's full body, or `undefined` for a name nobody registered.
+	 *
+	 * Full disclosure by design: a tool call asking for a skill is asking
+	 * for its instructions, and returning metadata the model already has in
+	 * its manifest would answer a question it did not ask.
+	 */
+	load(name: string): Promise<
+		| {
+				skill: {
+					metadata: {
+						name: string
+						description: string
+						allowedTools?: string
+						/**
+						 * The literal union, not `string`. Widening it here would
+						 * let a ref satisfy this interface while carrying a value
+						 * `isInvocableBy` cannot read, and the failure would be a
+						 * silent `both` — the fail-open answer.
+						 */
+						invocation?: 'model' | 'operator' | 'both'
+					}
+					body?: string
+				}
+		  }
+		| undefined
+	>
+	/** Every registered name, for a "did you mean" that names real options. */
+	names(): readonly string[]
+}
+
+export interface BackgroundJobRegistryRef {
+	start(params: { command: string; workingDirectory: string }): { id: string; status: string }
+	get(id: string): { id: string; status: string; exitCode?: number }
+	read(
+		id: string,
+		opts?: { fromOffset?: number },
+	): {
+		chunk: string
+		nextOffset: number
+		droppedBytes: number
+		status: string
+		exitCode?: number
+	}
+	kill(id: string): Promise<{ id: string; status: string }>
+	list(): readonly { id: string; command: string; status: string }[]
+}
+
 /**
  * Tracks which files the agent has read in the current run.
  * Write tool consults this to enforce the "read before overwrite" invariant
@@ -115,8 +188,93 @@ export interface ToolContext {
 	 */
 	allowedTools?: readonly string[]
 	sandbox?: Sandbox
+	/**
+	 * Symbol resolution for this run, when a host wired one up.
+	 *
+	 * Absent means the `lsp` tool is not registered at all — see
+	 * `tools/builtins/lsp.ts` for why a tool that is always present and
+	 * always says "unavailable" is worse than one that is not there.
+	 */
+	codeNavigation?: CodeNavigationProvider
 	fileReadTracker?: FileReadTracker
 
+	/**
+	 * Where work that outlives this call is held.
+	 *
+	 * Absent means the host has provided nowhere to put a background job, and
+	 * a tool asked for one must REFUSE rather than fall back to `cmd &`. The
+	 * fallback is not a lesser version of this — under the local sandbox's
+	 * `linux-namespace` tier the wrapping `sh` is PID 1 of a fresh PID
+	 * namespace, so a backgrounded grandchild dies the moment that shell
+	 * exits, on the successful path. It returns in milliseconds looking like
+	 * it worked, with the work already dead.
+	 */
+	backgroundJobs?: BackgroundJobRegistryRef
+
+	/**
+	 * Where the `skill` tool reads from.
+	 *
+	 * Absent means the run has no skills, and the tool says so rather than
+	 * reporting an empty list — "no skills here" and "no registry" are
+	 * different answers.
+	 */
+	skills?: SkillRegistryRef
+
+	/**
+	 * How this run reaches the web.
+	 *
+	 * Two independent halves, and either may be absent. This kernel ships a
+	 * guarded fetch provider and NO search backend, so `search` missing is
+	 * the ordinary case rather than a failure — the tools say which piece is
+	 * missing so an operator can tell a wiring decision from a fault.
+	 */
+	web?: {
+		readonly fetch?: {
+			fetch(request: { url: string; signal?: AbortSignal }): Promise<{
+				url: string
+				status: number
+				contentType?: string
+				body: string
+				truncated: boolean
+				redirects: readonly string[]
+			}>
+		}
+		readonly search?: {
+			search(request: { query: string; limit?: number; signal?: AbortSignal }): Promise<{
+				query: string
+				hits: readonly { title: string; url: string; snippet?: string }[]
+			}>
+		}
+	}
+
+	/**
+	 * Adopt the tool scope a skill declared.
+	 *
+	 * Called by the `skill` tool when a loaded skill names `allowed-tools`.
+	 * The scope INTERSECTS what the turn already allows and takes effect from
+	 * the next batch — a skill loaded alongside other calls must not
+	 * retroactively refuse them.
+	 */
+	adoptSkillScope?: (scope: { skill: string; allowedTools: readonly string[] }) => void
+
+	/**
+	 * Run another tool through the same dispatch this call came through.
+	 *
+	 * For `run_code`, whose whole purpose is calling tools in a loop. NOT
+	 * added to {@link ToolRegistryRef}: that ref is about discovering and
+	 * activating tools, and putting `execute` on it would make "can dispatch"
+	 * a property of holding a registry reference rather than a capability a
+	 * host wired deliberately.
+	 *
+	 * Available to every tool, which is worth being explicit about rather
+	 * than quietly true. Tools are host-installed code — the model cannot add
+	 * one — so the trust boundary this protects is the MODEL's reach, and
+	 * that is bounded where it has always been: `allowedTools` is enforced at
+	 * dispatch, so a tool calling through here reaches exactly what a
+	 * `tool_use` block would have.
+	 */
+	dispatchTool?: (name: string, input: unknown) => Promise<ToolResult>
+
 	/**
 	 * The `tool_use_id` of the assistant block that triggered this
 	 * execution. Tools that spawn background work (e.g. coordinator
@@ -217,7 +375,7 @@ export interface ToolResult {
 	retryable?: boolean
 }
 
-export interface ToolDefinition<TInput = unknown> {
+export interface ToolDefinition<TInput = unknown> extends ToolPresentation<TInput> {
 	name: string
 	description: string
 	inputSchema: z.ZodType<TInput, z.ZodTypeDef, unknown>
@@ -390,6 +548,16 @@ export interface ToolTierConfig {
 export interface ToolRegistryConfig {
 	logger?: Logger
 	tierConfig?: ToolTierConfig
+	/**
+	 * Screens run against every tool result before anything downstream
+	 * reads it — the output budget, compaction, and the model itself are
+	 * all past this point.
+	 *
+	 * Absent means no screening, which is what shipped before this existed:
+	 * a connected server's text reached the model unexamined. See
+	 * {@link ToolResultGuardrailSpec}.
+	 */
+	resultGuardrails?: readonly ToolResultGuardrailSpec[]
 }
 
 export interface ToolExecutionResult extends ToolResult {
@@ -435,3 +603,5 @@ export interface ToolRegistryContract {
 }
 
 export * from './repair.js'
+
+export type { ToolCallView, ToolPresentation, ToolResultView } from './presentation.js'

package/src/types/tool/presentation.ts

@@ -0,0 +1,48 @@
+import type { ToolResult } from './index.js'
+
+/**
+ * How a tool call should be shown, decided by the tool.
+ *
+ * Presentation lived in one host as four free functions switching on a
+ * lowercased tool NAME: `name === 'write'` and `name === 'edit'` got a
+ * diff, everything else got a truncated string. So a tool the host had
+ * never heard of — an MCP server's, a plugin's, a second host's — could
+ * not get a diff no matter what it did, and every new host started from
+ * the raw arguments and rebuilt the same switch.
+ *
+ * The tool knows what it is doing; the host knows how its surface renders.
+ * These are the three shapes one host had already found it needed, closed
+ * deliberately: an open union would let a tool ask for a rendering no host
+ * has, which is a request that fails silently at the far end.
+ */
+export type ToolCallView =
+	/** A line of text. What everything that is not a diff or a command gets. */
+	| { readonly kind: 'generic'; readonly label: string }
+	/**
+	 * A change to a document. `path` is optional because not every diff is
+	 * a file — a tool patching a remote record has a before and an after
+	 * and no path a host could open.
+	 */
+	| {
+			readonly kind: 'diff'
+			readonly path?: string
+			readonly before: string
+			readonly after: string
+	  }
+	/** A command and what it printed. */
+	| { readonly kind: 'terminal'; readonly command?: string; readonly output: string }
+
+/** The same three shapes, for what a call produced. */
+export type ToolResultView = ToolCallView
+
+/**
+ * Optional presentation hooks on a tool definition.
+ *
+ * Both may return `undefined`, which means "no opinion" and is different
+ * from returning a generic view: the first defers to the host's fallback,
+ * the second asserts that a plain label is the right rendering.
+ */
+export interface ToolPresentation<TInput = unknown> {
+	presentCall?(input: TInput): ToolCallView | undefined
+	presentResult?(input: TInput, result: ToolResult): ToolResultView | undefined
+}

package/src/types/{thread → topic}/entity.ts

@@ -1,51 +1,57 @@
 import type { TenantId } from '../ids/index.js'
-import type { ProjectId, ThreadId } from '../session/ids.js'
+import type { ProjectId, TopicId } from '../session/ids.js'
 
 /**
- * Lifecycle state of a Thread.
+ * Lifecycle state of a Topic.
  *
  * - `open` — accepts new Sessions and new Runs under existing Sessions.
  * - `archived` — read-only tombstone. No new Sessions may be created; existing
  *   Sessions remain navigable. Transitioning `open → archived` requires that
- *   no Session under the Thread is in a non-terminal state (guarded at the
+ *   no Session under the Topic is in a non-terminal state (guarded at the
  *   store level by listing + status fan-in).
  *
- * There is no `active` variant — Thread does NOT derive status from its child
- * Sessions the way a Session does from its Runs. Thread is a pure container
- * (Phase 0 decision B.1: Thread is container-only, no message stream, no
+ * There is no `active` variant — Topic does NOT derive status from its child
+ * Sessions the way a Session does from its Runs. Topic is a pure container
+ * (Phase 0 decision B.1: Topic is container-only, no message stream, no
  * fan-in). Its status is an explicit owner action.
  */
-export type ThreadStatus = 'open' | 'archived'
+export type TopicStatus = 'open' | 'archived'
 
 /**
  * Topic-level container sitting between {@link ProjectId Project} and
  * {@link import('../session/ids.js').SessionId Session} in the five-layer hierarchy
- * (Project → Thread → Session → SubSession → Run).
+ * (Project → Topic → Session → SubSession → Run).
  *
- * A Thread groups together many Sessions that address the same coherent
+ * NZ-TOPIC-01 renamed this entity from `Thread` to `Topic` — its own docstring
+ * already called it a "Topic-level container" before the identifier caught up.
+ * NZ-TOPIC-04 narrows the exported {@link import('../ids/index.js').TopicId}
+ * from the pre-0.2.0 `thd_` shape to `top_`; on-disk records written under
+ * the old prefix are migrated on read (`store/session/disk.ts`).
+ *
+ * A Topic groups together many Sessions that address the same coherent
  * topic or line-of-work within a Project (e.g. "auth refactor", "billing
- * incident"). Sessions under the same Thread share Project-level shared
+ * incident"). Sessions under the same Topic share Project-level shared
  * resources (memory, vaults, knowledge bases) but have independent actor
  * state, handoff history, and Run streams.
  *
- * ## Why Thread is a first-class layer (A2A-connection surface)
+ * ## Why Topic is a first-class layer (A2A-connection surface)
  *
  * The layer exists because of how enterprise sharing works in Namzu:
  *
  * - **Project is the folder-bound sharing unit.** An enterprise team shares
  *   a Project (`.namzu/` in a repo, a long-lived goal scope). Everyone with
  *   Project access sees its shape but not necessarily its active work.
- * - **Thread is the path-independent, A2A-attachable topic surface.** A
- *   Project can have multiple Threads — one per objective or line-of-work —
- *   and the Threads can be partitioned by device, user, or agent identity.
- *   A2A (agent-to-agent) connections attach at the Thread level: connecting
- *   to a Thread exposes every Session under it and the ability to join the
+ * - **Topic is the path-independent, A2A-attachable topic surface.** A
+ *   Project can have multiple Topics — one per objective or line-of-work —
+ *   and the Topics can be partitioned by device, user, or agent identity.
+ *   A2A (agent-to-agent) connections attach at the Topic level: connecting
+ *   to a Topic exposes every Session under it and the ability to join the
  *   ongoing work.
  * - **Sessions are the immediate work unit.** A user or agent enters a
- *   Thread and opens/resumes Sessions for the concrete interval of work.
+ *   Topic and opens/resumes Sessions for the concrete interval of work.
  *
  * This is the mental model ses_001 ratified (Phase 0, 2026-04-18). The
- * Thread layer has no counterpart elsewhere — it is Namzu's answer to
+ * Topic layer has no counterpart elsewhere — it is Namzu's answer to
  * the question "how do you expose a multi-session topic to A2A without
  * coupling it to the Project's filesystem identity?".
  *
@@ -55,23 +61,25 @@ export type ThreadStatus = 'open' | 'archived'
  *   - Container only. No own message stream, no own Run stream. Messages
  *     live in Sessions (Phase 0 decision B.1).
  *   - `title` is a user-facing label. **Titles are NOT unique within a
- *     Project.** Callers disambiguate by {@link ThreadId}; the title is
+ *     Project.** Callers disambiguate by {@link TopicId}; the title is
  *     freeform display text. If a product surface needs uniqueness (e.g.
  *     a human-typed slug), that constraint lives at the API layer, not in
  *     the kernel.
- *   - `ownerVersion` is the CAS counter for mutations — `updateThread` and
+ *   - `ownerVersion` is the CAS counter for mutations — `updateTopic` and
  *     archival transitions require a matching version and reject
- *     {@link StaleThreadError} on mismatch. Mirrors the
- *     {@link import('./entity.js').Session} handoff CAS pattern (§6.1).
+ *     {@link import('../../session/errors.js').StaleThreadError} on mismatch
+ *     (error class name is unchanged this release — see NZ-TOPIC-01 risks).
+ *     Mirrors the {@link import('./entity.js').Session} handoff CAS pattern
+ *     (§6.1).
  *   - No fan-in `deriveStatus()` helper — status is owner-managed, not
- *     Run-derived. This is the Thread-vs-Session contract boundary.
+ *     Run-derived. This is the Topic-vs-Session contract boundary.
  */
-export interface Thread {
-	id: ThreadId
+export interface Topic {
+	id: TopicId
 	projectId: ProjectId
 	tenantId: TenantId
 	title: string
-	status: ThreadStatus
+	status: TopicStatus
 	ownerVersion: number
 	createdAt: Date
 	updatedAt: Date

package/src/types/topic/index.ts

@@ -0,0 +1,23 @@
+// Sub-barrel for the Topic type surface (Convention #4).
+// Concrete types live in sibling files; re-export them here so consumers
+// import via `../types/topic/index.js`.
+//
+// NZ-TOPIC-01: this barrel used to be `types/thread/index.ts`, exporting
+// `ThreadStore`/`CreateThreadParams`/`Thread`/`ThreadStatus`. None of those
+// four names was ever part of the SDK's public surface (verified against
+// public-runtime.ts / public-types.ts, including their wildcard re-export
+// chains), so they were free to rename outright with no deprecated alias.
+
+export type { TopicStore, CreateTopicParams } from './store.js'
+export type { Topic, TopicStatus } from './entity.js'
+
+export { StaleObjectiveError } from './objective.js'
+export type {
+	ObjectiveAdvance,
+	ObjectiveAdvanceResult,
+	ObjectiveBlock,
+	ObjectivePhase,
+	ObjectiveRefusal,
+	ObjectiveRoundVerdict,
+	TopicObjective,
+} from './objective.js'