@namzu/sdk 0.1.8 → 0.2.0

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

@@ -0,0 +1,92 @@
+import type { SessionId } from '../../types/ids/index.js'
+import type { SubSessionId, SummaryId, WorkspaceId } from '../../types/session/ids.js'
+import type { ArchiveBackendRef } from '../retention/archive-backend-ref.js'
+import type { DeliverableRef } from '../summary/deliverable.js'
+import type { ActorRef } from './actor.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).
+ */
+export type SubSessionStatus =
+	| 'pending'
+	| 'active'
+	| 'idle'
+	| 'failed'
+	| 'awaiting_merge'
+	| 'pending_merge'
+	| 'merging'
+	| 'merged'
+	| 'merge_conflict'
+	| 'merge_rejected'
+	| 'archived'
+
+/**
+ * Discriminator for how a sub-session was created. Pattern doc §4.4
+ * enumerates four variants; the three kept here collapse `user_handoff`
+ * and `user_broadcast` into the single `user_handoff` kind (multi-recipient
+ * flows are encoded via `broadcastGroupId` in later phases).
+ */
+export type SubSessionKind = 'agent_spawn' | 'user_handoff' | 'intervention'
+
+/**
+ * Per-spawn failure policy for parallel fan-out. See session-hierarchy.md
+ * §4.4. Default is `delegate` — siblings continue and the parent agent
+ * decides what to do with partial results.
+ */
+export type FailureMode = 'fail_fast' | 'delegate'
+
+/**
+ * Completion contract the parent expects. See session-hierarchy.md §9.
+ *
+ * `summary_ref` is the default for agent delegation and interventions.
+ * `merge_back` is used by multi-user handoff; full spec lives in
+ * `collaboration-primitives.md`.
+ */
+export type CompletionMode = 'summary_ref' | 'merge_back'
+
+/**
+ * Re-export of the real {@link DeliverableRef} discriminated union. The
+ * concrete shape lives in `../summary/deliverable.ts` — see
+ * session-hierarchy.md §4.7 / §8.1. Phase 5 (this phase) replaced the Phase 1
+ * `unknown` placeholder with the real type.
+ */
+export type { DeliverableRef }
+
+/**
+ * Edge between a parent {@link Session} and a child session, carrying the
+ * delegation metadata. The child session itself lives in `SessionStore`
+ * like any other session — see session-hierarchy.md §4.4.
+ */
+export interface SubSession {
+	id: SubSessionId
+	parentSessionId: SessionId
+	childSessionId: SessionId
+	kind: SubSessionKind
+	status: SubSessionStatus
+	spawnedBy: ActorRef
+	spawnedAt: Date
+	failureMode: FailureMode
+	completionMode: CompletionMode
+	workspaceId: WorkspaceId | null
+	/**
+	 * For interventions, the immutable artifact being addressed. Chains form
+	 * a strict acyclic DAG — see session-hierarchy.md §4.5.
+	 */
+	prevArtifactRef?: DeliverableRef
+	/** Fan-out bookkeeping for broadcasts (§4.4). */
+	broadcastGroupId?: string
+	/** Populated by {@link SessionSummaryMaterializer} on terminalization (§8). */
+	summaryRef?: SummaryId
+	/**
+	 * Pointer to the archive bundle for this sub-session. Present iff
+	 * `status === 'archived'` (pattern doc §12.3). The paired
+	 * {@link archivedAt} timestamp captures when the bundle was sealed.
+	 * Cleared by {@link ArchivalManager.restore}.
+	 */
+	archiveRef?: ArchiveBackendRef
+	archivedAt?: Date
+	updatedAt: Date
+}

package/src/session/hierarchy/tenant.ts

@@ -0,0 +1,13 @@
+import type { TenantId } from '../../types/ids/index.js'
+
+/**
+ * Tenancy boundary for everything in the hierarchy.
+ *
+ * Intentionally thin — naming, billing, SSO, and quotas live outside the SDK
+ * (session-hierarchy.md §4.1 Convention #17). No API surface crosses
+ * {@link TenantId}.
+ */
+export interface Tenant {
+	id: TenantId
+	createdAt: Date
+}

package/src/session/index.ts

@@ -0,0 +1,15 @@
+// Top-level barrel for the session hierarchy module.
+// Phase 1 populates `hierarchy/`; Phase 2 adds `events/`; Phase 3 adds
+// `workspace/` + `errors.ts`; Phase 4 adds `handoff/`; Phase 5 adds
+// `summary/` + `intervention/`; Phase 7 adds `migration/`; Phase 8 adds
+// `retention/`.
+
+export * from './hierarchy/index.js'
+export * from './events/index.js'
+export * from './workspace/index.js'
+export * from './handoff/index.js'
+export * from './summary/index.js'
+export * from './intervention/index.js'
+export * from './migration/index.js'
+export * from './retention/index.js'
+export { TenantIsolationError, WorkspaceBackendError, AncestryCycleError } from './errors.js'

package/src/session/intervention/__tests__/prev-artifact.test.ts

@@ -0,0 +1,234 @@
+import { describe, expect, it } from 'vitest'
+import type { SessionId } from '../../../types/ids/index.js'
+import type { DeliverableId, SubSessionId, SummaryId } from '../../../types/session/ids.js'
+import type { DeliverableRef, SessionSummaryDeliverable } from '../../summary/deliverable.js'
+import {
+	ArtifactRefCycleError,
+	type InterventionChainLoader,
+	InterventionDepthExceeded,
+	type PrevArtifactNode,
+	validatePrevArtifactChain,
+} from '../prev-artifact.js'
+
+// Helpers -------------------------------------------------------------------
+
+function sessionId(n: number): SessionId {
+	return `ses_${n}` as SessionId
+}
+
+function subId(n: number): SubSessionId {
+	return `sub_${n}` as SubSessionId
+}
+
+function summaryDeliverable(targetSession: SessionId): SessionSummaryDeliverable {
+	return {
+		id: 'del_test' as DeliverableId,
+		kind: 'session_summary',
+		sessionId: targetSession,
+		summaryRef: 'sum_test' as SummaryId,
+		at: new Date('2026-04-17T00:00:00Z'),
+	}
+}
+
+/**
+ * Build a loader that walks a pre-configured chain. `chain[i]` is the node
+ * returned for the i'th step (keyed by the session id the previous step
+ * targeted). `nodesBySession` keys the loader by `sessionId`.
+ */
+function buildLoader(
+	nodes: Array<PrevArtifactNode & { bySession: SessionId }>,
+): InterventionChainLoader {
+	const map = new Map<SessionId, PrevArtifactNode>()
+	for (const n of nodes) {
+		map.set(n.bySession, {
+			subSessionId: n.subSessionId,
+			sessionId: n.sessionId,
+			...(n.prevArtifactRef !== undefined && { prevArtifactRef: n.prevArtifactRef }),
+		})
+	}
+	return {
+		loadAncestor: async (sid) => map.get(sid) ?? null,
+	}
+}
+
+describe('validatePrevArtifactChain', () => {
+	it('accepts a depth-1 chain (direct parent only)', async () => {
+		const loader = buildLoader([
+			{
+				bySession: sessionId(1),
+				subSessionId: subId(1),
+				sessionId: sessionId(1),
+				// No prevArtifactRef — chain terminates here.
+			},
+		])
+		const chain = await validatePrevArtifactChain(
+			loader,
+			subId(100),
+			summaryDeliverable(sessionId(1)),
+			10,
+		)
+		expect(chain).toEqual([subId(1)])
+	})
+
+	it('accepts a depth-2 chain', async () => {
+		const loader = buildLoader([
+			{
+				bySession: sessionId(1),
+				subSessionId: subId(1),
+				sessionId: sessionId(1),
+				prevArtifactRef: summaryDeliverable(sessionId(2)),
+			},
+			{
+				bySession: sessionId(2),
+				subSessionId: subId(2),
+				sessionId: sessionId(2),
+			},
+		])
+		const chain = await validatePrevArtifactChain(
+			loader,
+			subId(100),
+			summaryDeliverable(sessionId(1)),
+			10,
+		)
+		expect(chain).toEqual([subId(1), subId(2)])
+	})
+
+	it('accepts a chain exactly at the depth limit', async () => {
+		// 10-deep chain with maxDepth = 10.
+		const nodes: Array<PrevArtifactNode & { bySession: SessionId }> = []
+		for (let i = 1; i <= 10; i++) {
+			nodes.push({
+				bySession: sessionId(i),
+				subSessionId: subId(i),
+				sessionId: sessionId(i),
+				...(i < 10 && { prevArtifactRef: summaryDeliverable(sessionId(i + 1)) }),
+			})
+		}
+		const loader = buildLoader(nodes)
+		const chain = await validatePrevArtifactChain(
+			loader,
+			subId(100),
+			summaryDeliverable(sessionId(1)),
+			10,
+		)
+		expect(chain).toHaveLength(10)
+	})
+
+	it('rejects a chain that would exceed the depth limit', async () => {
+		// 11-deep chain with maxDepth = 10.
+		const nodes: Array<PrevArtifactNode & { bySession: SessionId }> = []
+		for (let i = 1; i <= 11; i++) {
+			nodes.push({
+				bySession: sessionId(i),
+				subSessionId: subId(i),
+				sessionId: sessionId(i),
+				...(i < 11 && { prevArtifactRef: summaryDeliverable(sessionId(i + 1)) }),
+			})
+		}
+		const loader = buildLoader(nodes)
+		await expect(
+			validatePrevArtifactChain(loader, subId(100), summaryDeliverable(sessionId(1)), 10),
+		).rejects.toBeInstanceOf(InterventionDepthExceeded)
+	})
+
+	it('rejects self-reference as a cycle', async () => {
+		// proposedChild's prev points at a node whose subSessionId == proposedChild.
+		const loader = buildLoader([
+			{
+				bySession: sessionId(1),
+				subSessionId: subId(100), // SAME id as proposedChild
+				sessionId: sessionId(1),
+			},
+		])
+		await expect(
+			validatePrevArtifactChain(loader, subId(100), summaryDeliverable(sessionId(1)), 10),
+		).rejects.toBeInstanceOf(ArtifactRefCycleError)
+	})
+
+	it('rejects a 2-cycle (A -> B -> A)', async () => {
+		const loader = buildLoader([
+			{
+				bySession: sessionId(1),
+				subSessionId: subId(1),
+				sessionId: sessionId(1),
+				prevArtifactRef: summaryDeliverable(sessionId(2)),
+			},
+			{
+				bySession: sessionId(2),
+				subSessionId: subId(2),
+				sessionId: sessionId(2),
+				prevArtifactRef: summaryDeliverable(sessionId(1)),
+			},
+		])
+		await expect(
+			validatePrevArtifactChain(loader, subId(100), summaryDeliverable(sessionId(1)), 10),
+		).rejects.toBeInstanceOf(ArtifactRefCycleError)
+	})
+
+	it('rejects a 3-cycle (A -> B -> C -> A)', async () => {
+		const loader = buildLoader([
+			{
+				bySession: sessionId(1),
+				subSessionId: subId(1),
+				sessionId: sessionId(1),
+				prevArtifactRef: summaryDeliverable(sessionId(2)),
+			},
+			{
+				bySession: sessionId(2),
+				subSessionId: subId(2),
+				sessionId: sessionId(2),
+				prevArtifactRef: summaryDeliverable(sessionId(3)),
+			},
+			{
+				bySession: sessionId(3),
+				subSessionId: subId(3),
+				sessionId: sessionId(3),
+				prevArtifactRef: summaryDeliverable(sessionId(1)),
+			},
+		])
+		await expect(
+			validatePrevArtifactChain(loader, subId(100), summaryDeliverable(sessionId(1)), 10),
+		).rejects.toBeInstanceOf(ArtifactRefCycleError)
+	})
+
+	it('returns an empty chain for a non-session_summary deliverable', async () => {
+		const fileRef: DeliverableRef = {
+			id: 'del_file' as DeliverableId,
+			kind: 'file',
+			path: 'a.txt',
+			contentHash: 'abc',
+			sizeBytes: 0,
+		}
+		const loader: InterventionChainLoader = {
+			loadAncestor: async () => null,
+		}
+		const chain = await validatePrevArtifactChain(loader, subId(100), fileRef, 10)
+		expect(chain).toEqual([])
+	})
+
+	it('terminates cleanly on unknown ancestor (archived/tombstoned)', async () => {
+		const loader = buildLoader([
+			// no matching node — loadAncestor returns null for any id
+		])
+		const chain = await validatePrevArtifactChain(
+			loader,
+			subId(100),
+			summaryDeliverable(sessionId(42)),
+			10,
+		)
+		expect(chain).toEqual([])
+	})
+
+	it('rejects zero/negative maxDepth as depth-exceeded up front', async () => {
+		const loader = buildLoader([
+			{
+				bySession: sessionId(1),
+				subSessionId: subId(1),
+				sessionId: sessionId(1),
+			},
+		])
+		await expect(
+			validatePrevArtifactChain(loader, subId(100), summaryDeliverable(sessionId(1)), 0),
+		).rejects.toBeInstanceOf(InterventionDepthExceeded)
+	})
+})

package/src/session/intervention/index.ts

@@ -0,0 +1,16 @@
+// Sub-barrel for the intervention DAG module (Convention #4).
+//
+// See session-hierarchy.md §4.5 — intervention chains via `prevArtifactRef`
+// form a strict acyclic DAG capped by
+// `Project.config.maxInterventionDepth`. This module owns the pre-commit
+// validator + typed errors; sub-session wiring is Phase 6.
+
+export {
+	ArtifactRefCycleError,
+	InterventionDepthExceeded,
+	validatePrevArtifactChain,
+} from './prev-artifact.js'
+export type {
+	InterventionChainLoader,
+	PrevArtifactNode,
+} from './prev-artifact.js'

package/src/session/intervention/prev-artifact.ts

@@ -0,0 +1,180 @@
+/**
+ * prevArtifactRef DAG primitives — acyclic walker, cycle detection, depth
+ * enforcement. See session-hierarchy.md §4.5.
+ *
+ * Intervention chains link successive follow-up sub-sessions via
+ * `SubSession.prevArtifactRef`, forming a strict acyclic DAG over prior
+ * completed sessions. This module supplies the pre-commit validator that
+ * rejects any insertion that would close a cycle or overflow
+ * {@link Project.config.maxInterventionDepth} (default 10).
+ *
+ * Convention #5: deny-by-default. Cycle or depth violation rejects with a
+ * typed error; callers never get a silently-truncated chain.
+ *
+ * Convention #0: no silent fallbacks. The walker surfaces corruption as
+ * `ArtifactRefCycleError` rather than infinite-looping.
+ */
+
+import type { SessionId } from '../../types/ids/index.js'
+import type { SubSessionId } from '../../types/session/ids.js'
+import type { DeliverableRef } from '../summary/deliverable.js'
+
+/**
+ * Minimal record the validator needs to step ancestrally from one
+ * sub-session to its predecessor. Concrete stores provide this projection.
+ *
+ * `sessionId` is the completed session this node represents (the one the
+ * incoming {@link DeliverableRef} pointed at). `subSessionId` is its own
+ * sub-session edge id — used for the visited-set so intervention chains form
+ * an acyclic DAG over sub-session identities.
+ */
+export interface PrevArtifactNode {
+	readonly subSessionId: SubSessionId
+	readonly sessionId: SessionId
+	readonly prevArtifactRef?: DeliverableRef
+}
+
+/**
+ * Raised when {@link validatePrevArtifactChain} detects a cycle — revisiting
+ * a sub-session id already in the ancestry set. Indicates a bug in the caller
+ * (or pre-existing store corruption); the write must be rejected.
+ */
+export class ArtifactRefCycleError extends Error {
+	readonly details: {
+		readonly startSubSessionId: SubSessionId
+		readonly cyclePath: readonly SubSessionId[]
+	}
+
+	constructor(details: {
+		startSubSessionId: SubSessionId
+		cyclePath: readonly SubSessionId[]
+	}) {
+		super(
+			`prevArtifactRef cycle starting at ${details.startSubSessionId}: ${details.cyclePath.join(' -> ')}`,
+		)
+		this.name = 'ArtifactRefCycleError'
+		this.details = details
+	}
+}
+
+/**
+ * Raised when the resolved chain length exceeds the configured intervention
+ * depth limit (`Project.config.maxInterventionDepth`). Convention #5
+ * deny-by-default — the kernel does not auto-truncate.
+ */
+export class InterventionDepthExceeded extends Error {
+	readonly details: {
+		readonly subSessionId: SubSessionId
+		readonly depth: number
+		readonly limit: number
+	}
+
+	constructor(details: { subSessionId: SubSessionId; depth: number; limit: number }) {
+		super(
+			`Intervention chain depth ${details.depth} exceeds limit ${details.limit} at ${details.subSessionId}`,
+		)
+		this.name = 'InterventionDepthExceeded'
+		this.details = details
+	}
+}
+
+/**
+ * Loader surface the validator queries to walk ancestry. Returning `null`
+ * means "no further ancestor" — the chain terminates cleanly. The loader is
+ * injected so tests can fake a chain without standing up a full
+ * {@link SessionStore}.
+ */
+export interface InterventionChainLoader {
+	/**
+	 * Resolves the ancestor node for the supplied {@link SessionId} — the
+	 * session that the last step's `SessionSummaryDeliverable.sessionId` named.
+	 * Returns `null` when no sub-session edge exists for that session (root
+	 * session, or an archived/tombstoned ancestor — see §12.3).
+	 */
+	loadAncestor(sessionId: SessionId): Promise<PrevArtifactNode | null>
+}
+
+/**
+ * Pre-commit validator for adding a `prevArtifactRef` on a proposed child
+ * sub-session. Walks from `candidateAncestor` backwards through
+ * `loader.loadAncestor`, seeding the visited-set with `proposedChild` so a
+ * cycle (the candidate chain loops back to the child) is rejected
+ * immediately.
+ *
+ * Returns the resolved ancestry chain (oldest last, length ≤ `maxDepth`),
+ * excluding `proposedChild` itself. The chain is ordered from
+ * immediate-ancestor to furthest-ancestor (reverse-chronological per §4.5).
+ *
+ * Throws:
+ * - {@link ArtifactRefCycleError} if the walk revisits `proposedChild` or
+ *   any already-visited ancestor.
+ * - {@link InterventionDepthExceeded} if the chain would exceed `maxDepth`.
+ *
+ * Non-session_summary deliverables (file / message / artifact_blob) do not
+ * form chain links — the walker terminates cleanly when it encounters one,
+ * since only `kind: 'session_summary'` references another sub-session's
+ * ancestry.
+ */
+export async function validatePrevArtifactChain(
+	loader: InterventionChainLoader,
+	proposedChild: SubSessionId,
+	candidateAncestor: DeliverableRef,
+	maxDepth: number,
+): Promise<readonly SubSessionId[]> {
+	if (maxDepth <= 0) {
+		throw new InterventionDepthExceeded({
+			subSessionId: proposedChild,
+			depth: 1,
+			limit: maxDepth,
+		})
+	}
+
+	// Non-session_summary refs are leaves — no chain links.
+	if (candidateAncestor.kind !== 'session_summary') {
+		return []
+	}
+
+	const visited = new Set<SubSessionId>([proposedChild])
+	const chain: SubSessionId[] = []
+
+	let currentRef: DeliverableRef | undefined = candidateAncestor
+
+	while (currentRef !== undefined) {
+		if (currentRef.kind !== 'session_summary') {
+			// Chain terminates on non-session deliverable.
+			return chain
+		}
+
+		// `SessionSummaryDeliverable.sessionId` names the completed session the
+		// ref points at. The loader resolves that to the sub-session edge
+		// carrying its own `prevArtifactRef` (if any), giving us the next step.
+		const ancestorNode = await loader.loadAncestor(currentRef.sessionId)
+		if (!ancestorNode) {
+			// Unknown ancestor (root session, or archived / tombstoned). Chain
+			// ends cleanly — absence is not a cycle.
+			return chain
+		}
+
+		if (visited.has(ancestorNode.subSessionId)) {
+			throw new ArtifactRefCycleError({
+				startSubSessionId: proposedChild,
+				cyclePath: [...chain, ancestorNode.subSessionId],
+			})
+		}
+
+		visited.add(ancestorNode.subSessionId)
+		chain.push(ancestorNode.subSessionId)
+
+		if (chain.length > maxDepth) {
+			throw new InterventionDepthExceeded({
+				subSessionId: proposedChild,
+				depth: chain.length,
+				limit: maxDepth,
+			})
+		}
+
+		currentRef = ancestorNode.prevArtifactRef
+	}
+
+	return chain
+}