@namzu/sdk 0.1.7 → 0.2.0

package/src/types/session/store.ts

@@ -0,0 +1,229 @@
+/**
+ * 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).
+ */
+
+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 {
+	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'
+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'
+
+/**
+ * Params for {@link SessionStore.createSession}. The store owns id generation,
+ * `ownerVersion` initialization, and timestamps. See session-hierarchy.md §4.3.
+ */
+export interface CreateSessionParams {
+	projectId: ProjectId
+	/**
+	 * Initial owner of the session. May be `null` for bootstrap scenarios where
+	 * the first Run attaches an actor; the store rejects mutations against
+	 * actor-less sessions from downstream consumers.
+	 */
+	currentActor: ActorRef | null
+}
+
+/**
+ * Params for {@link SessionStore.createSubSession}. `workspaceId` is optional
+ * because Phase 3 does not yet wire workspace creation into spawn — Phase 6
+ * makes the two atomic. `summaryRef` is populated by the materializer in
+ * Phase 5, never by callers of this API.
+ */
+export interface CreateSubSessionParams {
+	parentSessionId: SessionId
+	childSessionId: SessionId
+	kind: SubSessionKind
+	spawnedBy: ActorRef
+	failureMode?: FailureMode
+	completionMode?: CompletionMode
+}
+
+/**
+ * Minimal Project surface needed by the store in Phase 3. The full Project
+ * entity lives in `session/hierarchy/project.ts`; a dedicated `ProjectStore`
+ * is out of scope for this phase (session-hierarchy.md §11 defers the project
+ * store to a later phase).
+ */
+export interface CreateProjectParams {
+	tenantId: TenantId
+	name: string
+}
+
+/**
+ * Return shape for {@link SessionStore.drill}. See session-hierarchy.md §14.3.
+ * The fields are final — consumers may rely on exhaustiveness (Convention #6).
+ *
+ * `ancestry` is root-to-self. `children` lists direct sub-sessions only
+ * (recursive drill-down is the consumer's responsibility).
+ */
+export interface SessionView {
+	session: Session
+	children: readonly SubSession[]
+	ancestry: readonly SessionId[]
+}
+
+/**
+ * Canonical persistence contract. Every accessor takes explicit `tenantId`.
+ * Cross-tenant reads/writes must reject with `TenantIsolationError`
+ * (see `session/errors.ts`).
+ *
+ * Read accessors return `null` when the resource does not exist for the
+ * supplied tenant — this is the deny-by-default surface (Convention #5):
+ * callers never get a fallback and must branch on missing explicitly.
+ */
+export interface SessionStore {
+	// Project CRUD ------------------------------------------------------------
+
+	createProject(params: CreateProjectParams, tenantId: TenantId): Promise<Project>
+
+	getProject(projectId: ProjectId, tenantId: TenantId): Promise<Project | null>
+
+	// Session CRUD ------------------------------------------------------------
+
+	createSession(params: CreateSessionParams, tenantId: TenantId): Promise<Session>
+
+	getSession(sessionId: SessionId, tenantId: TenantId): Promise<Session | null>
+
+	updateSession(session: Session, tenantId: TenantId): Promise<void>
+
+	/**
+	 * Hard-delete a session. Idempotent — absent sessions succeed as a no-op.
+	 * Rejects with `TenantIsolationError` on cross-tenant access.
+	 *
+	 * Closes the Phase 4 Known Delta (broadcast rollback previously had to
+	 * flip status to `'archived'` as a stopgap). Used by:
+	 *   - Broadcast rollback (compensating cleanup — pattern doc §6.2)
+	 *   - Archival tombstone consolidation when a caller prefers deletion
+	 *     over the in-slot tombstone (uncommon — default is in-slot).
+	 *
+	 * Policy: rejects when the session still has sub-sessions attached —
+	 * callers must delete children first. This keeps the operation a single,
+	 * locally-reasoning write rather than an implicit recursive cascade
+	 * (Convention #5 deny-by-default).
+	 */
+	deleteSession(sessionId: SessionId, tenantId: TenantId): Promise<void>
+
+	// SubSession CRUD ---------------------------------------------------------
+
+	createSubSession(params: CreateSubSessionParams, tenantId: TenantId): Promise<SubSession>
+
+	getSubSession(subSessionId: SubSessionId, tenantId: TenantId): Promise<SubSession | null>
+
+	updateSubSession(subSession: SubSession, tenantId: TenantId): Promise<void>
+
+	/**
+	 * Hard-delete a sub-session record. Idempotent — absent sub-sessions
+	 * succeed as a no-op. Rejects with `TenantIsolationError` on cross-tenant
+	 * access. Does not cascade to the owned child session; the caller owns
+	 * that (typical broadcast-rollback flow deletes the sub-session first,
+	 * then the child session).
+	 */
+	deleteSubSession(subSessionId: SubSessionId, tenantId: TenantId): Promise<void>
+
+	// Messages (replaces ConversationStore surface) ---------------------------
+
+	/**
+	 * Append a single message to the session's message log. Returns the
+	 * assigned {@link MessageId}. Write is append-only; the store never
+	 * rewrites or reorders previously persisted messages.
+	 */
+	appendMessage(sessionId: SessionId, message: Message, tenantId: TenantId): Promise<MessageId>
+
+	/**
+	 * Load the full message history for a session in insertion order.
+	 * Returns an empty array when the session has no messages.
+	 *
+	 * Returns payload-only {@link Message} records. Callers that need the
+	 * full persistence envelope (including {@link MessageId} and timestamp)
+	 * should use {@link SessionStore.loadSessionMessages} instead.
+	 */
+	loadMessages(sessionId: SessionId, tenantId: TenantId): Promise<readonly Message[]>
+
+	/**
+	 * Load the full {@link SessionMessage} envelope for every persisted
+	 * message in insertion order (Phase 9 Known Delta #7). Unlike
+	 * {@link SessionStore.loadMessages} this preserves the original
+	 * {@link MessageId} and timestamp — required for full-fidelity archival
+	 * round-trips via {@link ArchivalManager.archive}.
+	 *
+	 * Returns an empty array when the session has no messages; cross-tenant
+	 * reads reject with `TenantIsolationError` (Convention #17).
+	 */
+	loadSessionMessages(sessionId: SessionId, tenantId: TenantId): Promise<readonly SessionMessage[]>
+
+	// Linkage (pattern doc §10.4 / §14.3) ------------------------------------
+
+	/**
+	 * Direct children of the session (one level). Returns an empty array when
+	 * the session has no delegations.
+	 */
+	getChildren(sessionId: SessionId, tenantId: TenantId): Promise<readonly SubSession[]>
+
+	/**
+	 * Session id chain from root to self, inclusive. Walks parent sub-session
+	 * links. Rejects on cycle via `session/errors.ts#AncestryCycleError` —
+	 * the write path enforces acyclicity, so a cycle here indicates store
+	 * corruption.
+	 */
+	getAncestry(sessionId: SessionId, tenantId: TenantId): Promise<readonly SessionId[]>
+
+	/**
+	 * Single-round navigation primitive. Returns `null` when the session does
+	 * not exist for the tenant. See session-hierarchy.md §14.3.
+	 */
+	drill(sessionId: SessionId, tenantId: TenantId): Promise<SessionView | null>
+
+	// Summary (pattern doc §4.7 / §8.1) --------------------------------------
+
+	/**
+	 * @internal Kernel-internal. Call through
+	 * `SessionSummaryMaterializer.materialize`, never directly. The
+	 * `materializedBy: 'kernel'` constraint on the argument type ensures
+	 * external callers cannot construct a valid input — the only mint site for
+	 * `SummaryId` is `generateSummaryId` inside the Materializer.
+	 *
+	 * Atomic write-then-status-flip (Convention #8): persists the summary and
+	 * transitions the owning Session's status to `'idle'` if it was in a
+	 * non-terminal state (`'active' | 'locked' | 'awaiting_merge'`). The two
+	 * writes commit as one logical unit; mid-crash recovery is replay via
+	 * `SessionSummaryMaterializer.recover()`.
+	 *
+	 * Rejects with {@link SessionAlreadySummarizedError} if a summary already
+	 * exists for the session (re-materialization forbidden; see
+	 * session-hierarchy.md §4.7 immutability invariant).
+	 */
+	recordSummary(
+		summary: SessionSummaryRef & { materializedBy: 'kernel' },
+		tenantId: TenantId,
+	): Promise<void>
+
+	/**
+	 * Loads the persisted summary for a session. Returns `null` when none has
+	 * been materialized. Cross-tenant reads reject with `TenantIsolationError`
+	 * (Convention #17).
+	 */
+	getSummary(sessionId: SessionId, tenantId: TenantId): Promise<SessionSummaryRef | null>
+}
+
+/**
+ * Re-export of {@link SummaryId} so downstream consumers importing from
+ * `types/session/store.js` pick up the brand alongside the store contract.
+ */
+export type { SummaryId }

package/src/utils/id.ts

@@ -8,10 +8,12 @@ import type {
 	ConnectorId,
 	ConnectorInstanceId,
 	CredentialId,
+	DeliverableId,
 	DocumentId,
 	EmergencySaveId,
 	EnvironmentId,
 	ExecutionContextId,
+	HandoffId,
 	KnowledgeBaseId,
 	MCPClientId,
 	MCPServerId,
@@ -20,13 +22,17 @@ import type {
 	MessageId,
 	PlanId,
 	PluginId,
+	ProjectId,
 	RunId,
 	SandboxId,
 	SessionId,
+	SubSessionId,
+	SummaryId,
 	TaskId,
 	TenantId,
 	ThreadId,
 	ToolCallId,
+	WorkspaceId,
 } from '../types/ids/index.js'
 
 const ALPHABET = '0123456789abcdefghijklmnopqrstuvwxyz'
@@ -49,8 +55,17 @@ 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 {
-	return generateId('thd_')
+	return generateId('prj_')
+}
+
+export function generateProjectId(): ProjectId {
+	return generateId('prj_')
 }
 
 export function generateRunId(): RunId {
@@ -62,7 +77,7 @@ export function generateMessageId(): MessageId {
 }
 
 export function generateSessionId(): SessionId {
-	return generateId('sess_')
+	return generateId('ses_')
 }
 
 export function generateToolCallId(): ToolCallId {
@@ -102,7 +117,7 @@ export function generateConnectorInstanceId(): ConnectorInstanceId {
 }
 
 export function generateTenantId(): TenantId {
-	return generateId('ten_')
+	return generateId('tnt_')
 }
 
 export function generateCredentialId(): CredentialId {
@@ -157,6 +172,26 @@ export function generateSandboxId(): SandboxId {
 	return generateId('sbx_')
 }
 
+export function generateWorkspaceId(): WorkspaceId {
+	return generateId('wsp_')
+}
+
+export function generateSubSessionId(): SubSessionId {
+	return generateId('sub_')
+}
+
+export function generateSummaryId(): SummaryId {
+	return generateId('sum_')
+}
+
+export function generateHandoffId(): HandoffId {
+	return generateId('hof_')
+}
+
+export function generateDeliverableId(): DeliverableId {
+	return generateId('del_')
+}
+
 function parseId<T extends string>(raw: string, prefix: string, typeName: string): T {
 	if (!raw.startsWith(prefix)) {
 		throw new Error(`Invalid ${typeName}: expected "${prefix}" prefix, got "${raw}"`)
@@ -164,8 +199,24 @@ 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 {
-	return parseId<ThreadId>(raw, 'thd_', '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')
 }
 export function parseRunId(raw: string): RunId {
 	return parseId<RunId>(raw, 'run_', 'RunId')