@namzu/sdk 0.1.7 → 0.2.0

package/src/session/__tests__/integration/tenant-isolation.test.ts

@@ -0,0 +1,282 @@
+/**
+ * Integration — multi-tenant isolation enforcement at every store accessor
+ * and cross-store boundary.
+ *
+ * Covers roadmap §5 invariants: §12 `tenantId` denormalized on every
+ * persisted entity, §12.2 cross-tenant rejection (TenantIsolationError at
+ * every accessor), broadcast handoff rejecting when recipient tenant
+ * differs.
+ *
+ * Every assertion here crosses a kernel boundary with a mismatched tenantId
+ * and checks that the SDK rejects rather than silently re-scoping.
+ */
+
+import { describe, expect, it } from 'vitest'
+import { InMemorySessionStore } from '../../../store/session/memory.js'
+import { createUserMessage } from '../../../types/message/index.js'
+import type { ProjectId, SubSessionId, SummaryId } from '../../../types/session/ids.js'
+import { TenantIsolationError } from '../../errors.js'
+import { DEFAULT_TENANT, OTHER_TENANT, agentActor, userActor } from './_fixtures.js'
+
+async function seedTenantAResources() {
+	const store = new InMemorySessionStore()
+	const project = await store.createProject(
+		{ tenantId: DEFAULT_TENANT, name: 'tenA' },
+		DEFAULT_TENANT,
+	)
+	const parent = await store.createSession(
+		{ projectId: project.id, currentActor: userActor('usr_a') },
+		DEFAULT_TENANT,
+	)
+	const child = await store.createSession(
+		{ projectId: project.id, currentActor: agentActor('agt_a') },
+		DEFAULT_TENANT,
+	)
+	const sub = await store.createSubSession(
+		{
+			parentSessionId: parent.id,
+			childSessionId: child.id,
+			kind: 'agent_spawn',
+			spawnedBy: userActor('usr_a'),
+		},
+		DEFAULT_TENANT,
+	)
+	return { store, project, parent, child, sub }
+}
+
+describe('Integration — tenant isolation', () => {
+	it('getProject with wrong tenantId → TenantIsolationError', async () => {
+		const { store, project } = await seedTenantAResources()
+		await expect(store.getProject(project.id, OTHER_TENANT)).rejects.toBeInstanceOf(
+			TenantIsolationError,
+		)
+	})
+
+	it('getSession with wrong tenantId → TenantIsolationError', async () => {
+		const { store, parent } = await seedTenantAResources()
+		await expect(store.getSession(parent.id, OTHER_TENANT)).rejects.toBeInstanceOf(
+			TenantIsolationError,
+		)
+	})
+
+	it('getSubSession with wrong tenantId → TenantIsolationError', async () => {
+		const { store, sub } = await seedTenantAResources()
+		await expect(store.getSubSession(sub.id, OTHER_TENANT)).rejects.toBeInstanceOf(
+			TenantIsolationError,
+		)
+	})
+
+	it('updateSession with wrong tenantId → TenantIsolationError', async () => {
+		const { store, parent } = await seedTenantAResources()
+		await expect(
+			store.updateSession({ ...parent, status: 'active' }, OTHER_TENANT),
+		).rejects.toBeInstanceOf(TenantIsolationError)
+	})
+
+	it('createSubSession from a session owned by another tenant → TenantIsolationError', async () => {
+		const { store, parent, child } = await seedTenantAResources()
+		await expect(
+			store.createSubSession(
+				{
+					parentSessionId: parent.id,
+					childSessionId: child.id,
+					kind: 'agent_spawn',
+					spawnedBy: userActor('usr_intruder', OTHER_TENANT),
+				},
+				OTHER_TENANT,
+			),
+		).rejects.toBeInstanceOf(TenantIsolationError)
+	})
+
+	it('appendMessage with wrong tenantId → TenantIsolationError', async () => {
+		const { store, child } = await seedTenantAResources()
+		await expect(
+			store.appendMessage(child.id, createUserMessage('intruder'), OTHER_TENANT),
+		).rejects.toBeInstanceOf(TenantIsolationError)
+	})
+
+	it('loadSessionMessages cross-tenant → TenantIsolationError', async () => {
+		const { store, child } = await seedTenantAResources()
+		await store.appendMessage(child.id, createUserMessage('legit'), DEFAULT_TENANT)
+		await expect(store.loadSessionMessages(child.id, OTHER_TENANT)).rejects.toBeInstanceOf(
+			TenantIsolationError,
+		)
+	})
+
+	it('loadMessages cross-tenant → TenantIsolationError', async () => {
+		const { store, child } = await seedTenantAResources()
+		await store.appendMessage(child.id, createUserMessage('legit'), DEFAULT_TENANT)
+		await expect(store.loadMessages(child.id, OTHER_TENANT)).rejects.toBeInstanceOf(
+			TenantIsolationError,
+		)
+	})
+
+	it('drill(sessionId, OTHER_TENANT) on an existing session → TenantIsolationError (pattern doc §12.2 hard reject)', async () => {
+		const { store, parent } = await seedTenantAResources()
+		// Existing session owned by DEFAULT_TENANT, caller supplies OTHER_TENANT.
+		// Pattern doc §12 specifies hard reject — no silent null masking.
+		await expect(store.drill(parent.id, OTHER_TENANT)).rejects.toBeInstanceOf(TenantIsolationError)
+	})
+
+	it('drill on a missing session returns null (deny-by-default surface without leaking tenant info)', async () => {
+		const { store } = await seedTenantAResources()
+		const view = await store.drill(
+			'ses_never_existed' as Parameters<typeof store.drill>[0],
+			OTHER_TENANT,
+		)
+		// Missing session for the queried tenant returns null (Convention #5).
+		// The tenant check is conditional on the resource existing; absent
+		// resources don't leak tenant info via a thrown isolation error.
+		expect(view).toBeNull()
+	})
+
+	it('getChildren cross-tenant → TenantIsolationError', async () => {
+		const { store, parent } = await seedTenantAResources()
+		await expect(store.getChildren(parent.id, OTHER_TENANT)).rejects.toBeInstanceOf(
+			TenantIsolationError,
+		)
+	})
+
+	it('getAncestry cross-tenant → TenantIsolationError', async () => {
+		const { store, parent } = await seedTenantAResources()
+		await expect(store.getAncestry(parent.id, OTHER_TENANT)).rejects.toBeInstanceOf(
+			TenantIsolationError,
+		)
+	})
+
+	it('recordSummary with mismatched payload tenantId → TenantIsolationError', async () => {
+		const { store, parent } = await seedTenantAResources()
+		// Attempt to record a summary whose payload tenantId differs from the
+		// caller tenantId — runtime guard rejects.
+		await expect(
+			store.recordSummary(
+				{
+					id: 'sum_intruder' as SummaryId,
+					sessionRef: parent.id,
+					tenantId: OTHER_TENANT,
+					outcome: { status: 'succeeded' },
+					deliverables: [],
+					agentSummary: '',
+					keyDecisions: [],
+					at: new Date(),
+					materializedBy: 'kernel',
+				},
+				DEFAULT_TENANT,
+			),
+		).rejects.toBeInstanceOf(TenantIsolationError)
+	})
+
+	it('getSummary cross-tenant → TenantIsolationError when a summary exists', async () => {
+		const { store, parent } = await seedTenantAResources()
+		await store.updateSession({ ...parent, status: 'active' }, DEFAULT_TENANT)
+		await store.recordSummary(
+			{
+				id: 'sum_ok' as SummaryId,
+				sessionRef: parent.id,
+				tenantId: DEFAULT_TENANT,
+				outcome: { status: 'succeeded' },
+				deliverables: [],
+				agentSummary: '',
+				keyDecisions: [],
+				at: new Date(),
+				materializedBy: 'kernel',
+			},
+			DEFAULT_TENANT,
+		)
+
+		await expect(store.getSummary(parent.id, OTHER_TENANT)).rejects.toBeInstanceOf(
+			TenantIsolationError,
+		)
+	})
+
+	it('createProject with params.tenantId ≠ caller tenantId → TenantIsolationError (deep check)', async () => {
+		const store = new InMemorySessionStore()
+		await expect(
+			store.createProject({ tenantId: OTHER_TENANT, name: 'mismatch' }, DEFAULT_TENANT),
+		).rejects.toBeInstanceOf(TenantIsolationError)
+	})
+
+	it('createSession with project owned by another tenant → TenantIsolationError', async () => {
+		const { store, project } = await seedTenantAResources()
+		await expect(
+			store.createSession(
+				{ projectId: project.id, currentActor: userActor('usr_intruder', OTHER_TENANT) },
+				OTHER_TENANT,
+			),
+		).rejects.toBeInstanceOf(TenantIsolationError)
+	})
+
+	it('tenant denormalization: Session, SubSession records carry tenantId explicitly', async () => {
+		const { store, parent, sub } = await seedTenantAResources()
+		const parentReloaded = await store.getSession(parent.id, DEFAULT_TENANT)
+		expect(parentReloaded?.tenantId).toBe(DEFAULT_TENANT)
+
+		// SubSession record itself does not carry tenantId in its shape — the
+		// isolation is stored via the parent record tuple (subSessions map:
+		// { tenantId, subSession }). Getting it via the correct tenant succeeds;
+		// via the wrong tenant rejects — already covered above. This test just
+		// confirms the successful access path.
+		const reloaded = await store.getSubSession(sub.id, DEFAULT_TENANT)
+		expect(reloaded?.id).toBe(sub.id)
+	})
+
+	it('broadcast-style cross-tenant attempt: cannot createSubSession linking parents owned by another tenant', async () => {
+		// Pattern doc §12 requires recipient & source to share tenant. The
+		// store-level guard here catches the shape violation — createSubSession
+		// refuses to link parent/child across tenants.
+		const { store, parent } = await seedTenantAResources()
+
+		// Create a session in OTHER_TENANT with its own project.
+		const otherProject = await store.createProject(
+			{ tenantId: OTHER_TENANT, name: 'other' },
+			OTHER_TENANT,
+		)
+		const otherChild = await store.createSession(
+			{ projectId: otherProject.id, currentActor: userActor('usr_other', OTHER_TENANT) },
+			OTHER_TENANT,
+		)
+
+		await expect(
+			store.createSubSession(
+				{
+					parentSessionId: parent.id, // DEFAULT_TENANT
+					childSessionId: otherChild.id, // OTHER_TENANT
+					kind: 'agent_spawn',
+					spawnedBy: userActor('usr_a'),
+				},
+				DEFAULT_TENANT,
+			),
+		).rejects.toBeInstanceOf(TenantIsolationError)
+	})
+
+	it('deleteSubSession cross-tenant → TenantIsolationError', async () => {
+		const { store, sub } = await seedTenantAResources()
+		await expect(store.deleteSubSession(sub.id, OTHER_TENANT)).rejects.toBeInstanceOf(
+			TenantIsolationError,
+		)
+	})
+
+	it('deleteSession cross-tenant → TenantIsolationError', async () => {
+		const { store } = await seedTenantAResources()
+		// Parent has a sub-session attached → deleteSession would fail anyway,
+		// but the tenant guard fires first. Use a standalone session.
+		const project: ProjectId = (
+			await store.createProject({ tenantId: DEFAULT_TENANT, name: 'del' }, DEFAULT_TENANT)
+		).id
+		const lonely = await store.createSession(
+			{ projectId: project, currentActor: userActor('usr_lonely') },
+			DEFAULT_TENANT,
+		)
+		await expect(store.deleteSession(lonely.id, OTHER_TENANT)).rejects.toBeInstanceOf(
+			TenantIsolationError,
+		)
+	})
+
+	it('missing sub-session returns null for correct tenant (not a leak channel)', async () => {
+		const { store } = await seedTenantAResources()
+		// Missing id via correct tenant → null, not thrown. Confirms the
+		// missing-resource fast-path doesn't pre-empt the tenant check.
+		const missing = await store.getSubSession('sub_never_existed' as SubSessionId, DEFAULT_TENANT)
+		expect(missing).toBeNull()
+	})
+})

package/src/session/errors.ts

@@ -0,0 +1,70 @@
+/**
+ * Typed errors for the session hierarchy module.
+ *
+ * See session-hierarchy.md §12.2 (cross-tenant rejection), §6.2 (workspace
+ * backend operation failures), §4.5 (intervention DAG). Each error carries a
+ * structured `details` payload so consumers can route without string parsing
+ * (Convention #5: deny-by-default, fail fast).
+ */
+
+import type { SessionId, TenantId } from '../types/ids/index.js'
+import type { WorkspaceBackendKind } from './workspace/driver.js'
+
+/**
+ * Raised by {@link SessionStore} accessors when the supplied {@link TenantId}
+ * does not match the tenant owning the target resource. Convention #17:
+ * cross-tenant access is a hard error at the kernel boundary — there is no
+ * escape hatch. See session-hierarchy.md §12.2.
+ */
+export class TenantIsolationError extends Error {
+	readonly details: {
+		requested: TenantId
+		resource: string
+	}
+
+	constructor(details: { requested: TenantId; resource: string }) {
+		super(`Tenant isolation violation: ${details.requested} accessed ${details.resource}`)
+		this.name = 'TenantIsolationError'
+		this.details = details
+	}
+}
+
+/**
+ * Raised by {@link SessionStore.getAncestry} / {@link SessionStore.drill}
+ * when walking parent sub-session links encounters a revisit. Indicates store
+ * corruption — the write path enforces acyclicity (session-hierarchy.md §4.5).
+ */
+export class AncestryCycleError extends Error {
+	readonly details: {
+		sessionId: SessionId
+		cyclePath: readonly SessionId[]
+	}
+
+	constructor(details: { sessionId: SessionId; cyclePath: readonly SessionId[] }) {
+		super(
+			`Ancestry cycle detected starting at ${details.sessionId}: ${details.cyclePath.join(' -> ')}`,
+		)
+		this.name = 'AncestryCycleError'
+		this.details = details
+	}
+}
+
+/**
+ * Raised by {@link WorkspaceBackendDriver} implementations on any I/O or
+ * invariant failure. Wraps the underlying cause; callers can match on
+ * `details.op` + `details.kind` for routing (Convention #0: no silent
+ * fallbacks — surface the failure). See session-hierarchy.md §6.2 / §7.
+ */
+export class WorkspaceBackendError extends Error {
+	readonly details: {
+		op: string
+		kind: WorkspaceBackendKind
+		cause?: unknown
+	}
+
+	constructor(details: { op: string; kind: WorkspaceBackendKind; cause?: unknown }) {
+		super(`Workspace backend ${details.kind} failed on ${details.op}`)
+		this.name = 'WorkspaceBackendError'
+		this.details = details
+	}
+}

package/src/session/events/index.ts

@@ -0,0 +1,16 @@
+// Sub-barrel for session-hierarchy run-event surface.
+// Convention #4: concrete types live in sibling files; re-export them here.
+//
+// Phase 2 scope is limited to the sub-session lifecycle variants that are
+// spliced into `RunEvent`. A dedicated `SessionHierarchyEvent` top-level
+// union lands in a later phase (see session-hierarchy.md §10.2).
+
+export { RUN_EVENT_SCHEMA_VERSION } from './schema-version.js'
+export type { RunEventSchemaVersion } from './schema-version.js'
+
+export type {
+	SubsessionSpawnedEvent,
+	SubsessionMessagedEvent,
+	SubsessionIdledEvent,
+	SubsessionLifecycleEvent,
+} from './types.js'

package/src/session/events/schema-version.ts

@@ -0,0 +1,13 @@
+/**
+ * RunEvent envelope schema version. Bumped on breaking envelope change.
+ *
+ * - v1: pre-0.2.0 (implicit; untagged events are treated as v1 by consumers).
+ * - v2: 0.2.0+ — adds `schemaVersion`, `lineage`, and sub-session lifecycle
+ *   events.
+ *
+ * See session-hierarchy.md §10.1 (Event-schema evolution contract) and
+ * §13.3.2 (`schemaVersion` back-compat).
+ */
+export const RUN_EVENT_SCHEMA_VERSION = 2 as const
+
+export type RunEventSchemaVersion = typeof RUN_EVENT_SCHEMA_VERSION

package/src/session/events/types.ts

@@ -0,0 +1,71 @@
+import type { MessageId, RunId, SessionId } from '../../types/ids/index.js'
+import type { SubSessionId } from '../../types/session/ids.js'
+import type { ActorRef } from '../hierarchy/actor.js'
+import type { Lineage } from '../hierarchy/lineage.js'
+import type { RunEventSchemaVersion } from './schema-version.js'
+
+/**
+ * Sub-session lifecycle events that splice into {@link RunEvent}.
+ *
+ * See session-hierarchy.md §10.4 (Parent-Child Linkage). These cover the
+ * in-flight visibility gap that the terminal-only `SessionSummaryRef` does
+ * not address. Every sub-session emission carries the full {@link Lineage}
+ * chain — consumers can reconstruct the delegation tree without walking the
+ * store (§10.4 invariant).
+ *
+ * Note: these events are spliced into the `RunEvent` union in
+ * `types/run/events.ts` rather than kept as a separate top-level union.
+ * A dedicated `SessionHierarchyEvent` top-level type lands in Phase 3+.
+ */
+
+/**
+ * Emitted when the kernel creates a new sub-session. Precedes the child
+ * session's `run_started`. See §10.4 / §10.5 example stream.
+ */
+export interface SubsessionSpawnedEvent {
+	type: 'subsession_spawned'
+	runId: RunId
+	subSessionId: SubSessionId
+	parentSessionId: SessionId
+	spawnedBy: ActorRef
+	lineage: Lineage
+	schemaVersion: RunEventSchemaVersion
+	at: Date
+}
+
+/**
+ * Emitted each time the child session's Run appends a message. Gives parents
+ * and platform consumers in-flight visibility without requiring a drill into
+ * the child transcript. See §10.4.
+ */
+export interface SubsessionMessagedEvent {
+	type: 'subsession_messaged'
+	runId: RunId
+	subSessionId: SubSessionId
+	parentSessionId: SessionId
+	messageId: MessageId
+	lineage: Lineage
+	schemaVersion: RunEventSchemaVersion
+	at: Date
+}
+
+/**
+ * Emitted when the child session transitions to `idle` (terminal persistent
+ * state per §5.3 — sub-sessions never close). A separate
+ * `sub_session.summarized` event carries the `SessionSummaryRef` (§8); this
+ * event only reports the lifecycle transition.
+ */
+export interface SubsessionIdledEvent {
+	type: 'subsession_idled'
+	runId: RunId
+	subSessionId: SubSessionId
+	parentSessionId: SessionId
+	lineage: Lineage
+	schemaVersion: RunEventSchemaVersion
+	at: Date
+}
+
+export type SubsessionLifecycleEvent =
+	| SubsessionSpawnedEvent
+	| SubsessionMessagedEvent
+	| SubsessionIdledEvent