@namzu/sdk 13.1.0 → 14.0.0

package/src/session/migration/filesystem.ts

@@ -248,6 +248,34 @@ export class DefaultFilesystemMigrator implements FilesystemMigrator {
 
 				const legacyThreadId = entry
 				const suffix = legacyThreadId.slice('thd_'.length)
+
+				// The suffix comes off the filesystem, and `startsWith('thd_')`
+				// is the only thing it has passed. A folder named `thd_Not An
+				// Id` mints `prj_legacy_Not An Id`: structurally a `ProjectId`,
+				// accepted by no validator, and now a directory name in the new
+				// layout. The migration is the one place a project id is built
+				// from data rather than generated, so it is the one place the
+				// id contract has to be checked.
+				//
+				// (Not a containment check — it cannot be one. `readdir` yields
+				// path components, which hold no separator, and `..` is never
+				// among them; `prj_legacy_..` is a literal name, not a parent
+				// reference. Nothing here can leave the root.)
+				//
+				// It refuses rather than skipping. A skipped folder is a legacy
+				// thread whose runs are still on disk and no longer addressable,
+				// with nothing in the result saying so — and the marker would be
+				// written as if the migration were complete.
+				if (!/^[a-z0-9]+$/.test(suffix)) {
+					throw new FilesystemMigrationError({
+						op: 'validate_thread_id',
+						path: join(threadsDir, legacyThreadId),
+						cause: new Error(
+							`Legacy thread folder '${legacyThreadId}' is not a thread id: expected 'thd_' followed by lowercase alphanumerics. It is refused rather than migrated because the name is used as a directory name.`,
+						),
+					})
+				}
+
 				const newProjectId = `${LEGACY_DEFAULT_PROJECT_PREFIX}${suffix}` as ProjectId
 
 				const legacyRunsDir = join(threadsDir, legacyThreadId, 'runs')

package/src/store/session/disk.ts

@@ -23,11 +23,11 @@
 
 import { appendFile, mkdir, readFile, readdir, rm } from 'node:fs/promises'
 import { join } from 'node:path'
-import { StaleSessionError, TenantIsolationError } from '../../session/errors.js'
+import { StaleProjectError, StaleSessionError, TenantIsolationError } from '../../session/errors.js'
 import { SessionAlreadySummarizedError } from '../../session/summary/errors.js'
 import type { MessageId, SessionId, TenantId } from '../../types/ids/index.js'
 import type { Message } from '../../types/message/index.js'
-import type { Project } from '../../types/project/entity.js'
+import type { Project, ProjectStatus } from '../../types/project/entity.js'
 import type { Session } from '../../types/session/entity.js'
 import type { ProjectId, SubSessionId, SummaryId, ThreadId } from '../../types/session/ids.js'
 import type { SessionMessage } from '../../types/session/messages.js'
@@ -80,6 +80,10 @@ interface PersistedProject {
 	tenantId: TenantId
 	name: string
 	config: Project['config']
+	/** Absent in files written before the workspace gained a status. */
+	status?: ProjectStatus
+	/** Absent in files written before the workspace gained a CAS counter. */
+	ownerVersion?: number
 	createdAt: string
 	updatedAt: string
 }
@@ -198,6 +202,8 @@ export class DiskSessionStore implements SessionStore {
 				maxDelegationWidth: params.config?.maxDelegationWidth ?? 8,
 				maxInterventionDepth: 10,
 			},
+			status: 'open',
+			ownerVersion: 0,
 			createdAt: now,
 			updatedAt: now,
 		}
@@ -245,6 +251,35 @@ export class DiskSessionStore implements SessionStore {
 		return project
 	}
 
+	async setProjectStatus(
+		projectId: ProjectId,
+		status: ProjectStatus,
+		tenantId: TenantId,
+		expectedOwnerVersion: number,
+	): Promise<Project | null> {
+		const existing = await this.getProject(projectId, tenantId)
+		if (!existing) return null
+		// Against the version on disk, not the caller's copy of it.
+		if (existing.ownerVersion !== expectedOwnerVersion) {
+			throw new StaleProjectError({
+				projectId,
+				expectedOwnerVersion,
+				actualOwnerVersion: existing.ownerVersion,
+			})
+		}
+		const project: Project = {
+			...existing,
+			status,
+			ownerVersion: existing.ownerVersion + 1,
+			updatedAt: new Date(),
+		}
+		await atomicWriteJson(
+			join(this.projectDir(projectId), 'project.json'),
+			serializeProject(project),
+		)
+		return project
+	}
+
 	async listProjects(tenantId: TenantId): Promise<readonly Project[]> {
 		// Read from the directory rather than the lazily-built index: the index
 		// only knows about projects this instance has already touched, so a
@@ -369,6 +404,40 @@ export class DiskSessionStore implements SessionStore {
 		return results
 	}
 
+	async listSessionsByProject(
+		projectId: ProjectId,
+		tenantId: TenantId,
+	): Promise<readonly Session[]> {
+		// One directory, not the whole root: sessions live under their project,
+		// so this is the cheap direction. `listSessions` has to scan every
+		// project precisely because `threadId` is denormalised onto the record
+		// rather than expressed in the layout.
+		const sessionsRoot = join(this.projectDir(projectId), 'sessions')
+		let sessionDirs: string[]
+		try {
+			sessionDirs = await readdir(sessionsRoot)
+		} catch (err) {
+			const code = (err as NodeJS.ErrnoException).code
+			if (code === 'ENOENT') return []
+			throw err
+		}
+
+		const results: Session[] = []
+		for (const rawSessionId of sessionDirs) {
+			if (!rawSessionId.startsWith('ses_')) continue
+			const path = join(sessionsRoot, rawSessionId)
+			const raw = await readJson<PersistedSession>(join(path, 'session.json'))
+			if (!raw) continue
+			if (raw.tenantId !== tenantId) continue
+			results.push(deserializeSession(raw))
+			this.sessionIndex.set(raw.id, { sessionId: raw.id, projectId, path })
+		}
+		results.sort(
+			(a, b) => a.createdAt.getTime() - b.createdAt.getTime() || a.id.localeCompare(b.id),
+		)
+		return results
+	}
+
 	async updateSession(
 		session: Session,
 		tenantId: TenantId,
@@ -910,6 +979,8 @@ function serializeProject(p: Project): PersistedProject {
 		tenantId: p.tenantId,
 		name: p.name,
 		config: p.config,
+		status: p.status,
+		ownerVersion: p.ownerVersion,
 		createdAt: p.createdAt.toISOString(),
 		updatedAt: p.updatedAt.toISOString(),
 	}
@@ -921,6 +992,12 @@ function deserializeProject(p: PersistedProject): Project {
 		tenantId: p.tenantId,
 		name: p.name,
 		config: p.config,
+		// A project.json written before these fields existed reads as an open
+		// workspace at version 0, which is what it was. Leaving `ownerVersion`
+		// undefined would be worse than a wrong default: every compare-and-set
+		// against it would fail, so an existing store could never be closed.
+		status: p.status ?? 'open',
+		ownerVersion: p.ownerVersion ?? 0,
 		createdAt: new Date(p.createdAt),
 		updatedAt: new Date(p.updatedAt),
 	}

package/src/store/session/memory.ts

@@ -8,11 +8,11 @@
  * (Convention #5 deny-by-default, session-hierarchy.md §12.2).
  */
 
-import { StaleSessionError, TenantIsolationError } from '../../session/errors.js'
+import { StaleProjectError, StaleSessionError, TenantIsolationError } from '../../session/errors.js'
 import { SessionAlreadySummarizedError } from '../../session/summary/errors.js'
 import type { MessageId, SessionId, TenantId } from '../../types/ids/index.js'
 import type { Message } from '../../types/message/index.js'
-import type { Project } from '../../types/project/entity.js'
+import type { Project, ProjectStatus } from '../../types/project/entity.js'
 import type { Session } from '../../types/session/entity.js'
 import type { ProjectId, SubSessionId, ThreadId } from '../../types/session/ids.js'
 import type { SessionMessage } from '../../types/session/messages.js'
@@ -93,6 +93,8 @@ export class InMemorySessionStore implements SessionStore {
 				maxDelegationWidth: params.config?.maxDelegationWidth ?? 8,
 				maxInterventionDepth: 10,
 			},
+			status: 'open',
+			ownerVersion: 0,
 			createdAt: now,
 			updatedAt: now,
 		}
@@ -134,6 +136,35 @@ export class InMemorySessionStore implements SessionStore {
 		return project
 	}
 
+	async setProjectStatus(
+		projectId: ProjectId,
+		status: ProjectStatus,
+		tenantId: TenantId,
+		expectedOwnerVersion: number,
+	): Promise<Project | null> {
+		const record = this.projects.get(projectId)
+		if (!record) return null
+		this.assertTenant(record.tenantId, tenantId, `project(${projectId})`)
+		// Against the STORED version, not the caller's copy of it — comparing a
+		// value against itself is the shape the session CAS was written wrong in
+		// the first time.
+		if (record.project.ownerVersion !== expectedOwnerVersion) {
+			throw new StaleProjectError({
+				projectId,
+				expectedOwnerVersion,
+				actualOwnerVersion: record.project.ownerVersion,
+			})
+		}
+		const project: Project = {
+			...record.project,
+			status,
+			ownerVersion: record.project.ownerVersion + 1,
+			updatedAt: new Date(),
+		}
+		this.projects.set(projectId, { tenantId, project })
+		return project
+	}
+
 	async listProjects(tenantId: TenantId): Promise<readonly Project[]> {
 		const matches: Project[] = []
 		for (const record of this.projects.values()) {
@@ -195,6 +226,22 @@ export class InMemorySessionStore implements SessionStore {
 		return matches
 	}
 
+	async listSessionsByProject(
+		projectId: ProjectId,
+		tenantId: TenantId,
+	): Promise<readonly Session[]> {
+		const matches: Session[] = []
+		for (const record of this.sessions.values()) {
+			if (record.tenantId !== tenantId) continue
+			if (record.session.projectId !== projectId) continue
+			matches.push(record.session)
+		}
+		matches.sort(
+			(a, b) => a.createdAt.getTime() - b.createdAt.getTime() || a.id.localeCompare(b.id),
+		)
+		return matches
+	}
+
 	async updateSession(
 		session: Session,
 		tenantId: TenantId,

package/src/types/project/entity.ts

@@ -27,15 +27,33 @@ export interface ProjectConfig {
 	retentionPolicy?: RetentionPolicy
 }
 
+/**
+ * Whether the workspace accepts new work.
+ *
+ * Owner-managed, like the status it replaces: a project does not derive
+ * `archived` from having no live sessions, because "empty right now" and
+ * "closed" are different facts and only one of them is a decision.
+ */
+export type ProjectStatus = 'open' | 'archived'
+
 /**
  * Long-lived goal scope that owns shared memory, vaults, knowledge bases,
  * and deliverables across sessions. See session-hierarchy.md §4.2.
+ *
+ * `status` is the gate the ingress paths read: an archived project accepts no
+ * new session and no handoff. It lives here rather than on Thread because the
+ * project is the thing a tenant actually closes — a workspace with its own
+ * limits, its own environment, and its own memory — and closing it has to mean
+ * something to the code, not only to a listing.
  */
 export interface Project {
 	id: ProjectId
 	tenantId: TenantId
 	name: string
 	config: ProjectConfig
+	status: ProjectStatus
+	/** CAS counter for status transitions. Mirrors `Session.ownerVersion`. */
+	ownerVersion: number
 	createdAt: Date
 	updatedAt: Date
 }

package/src/types/session/store.ts

@@ -6,7 +6,7 @@
  * API — extensions land alongside their consumers.
  */
 
-import type { Project } from '../../types/project/entity.js'
+import type { Project, ProjectStatus } from '../../types/project/entity.js'
 import type { ActorRef } from '../../types/session/actor.js'
 import type { Session } from '../../types/session/entity.js'
 import type { SessionMessage } from '../../types/session/messages.js'
@@ -159,6 +159,29 @@ export interface SessionStore {
 	 */
 	listProjects?(tenantId: TenantId): Promise<readonly Project[]>
 
+	/**
+	 * Open or close a workspace. OPTIONAL, same reasoning as the two above.
+	 *
+	 * Compare-and-set on {@link Project.ownerVersion}: pass the version you
+	 * read, and a concurrent writer makes this throw `StaleProjectError`
+	 * instead of silently winning. On success the stored version is bumped.
+	 *
+	 * Both directions, because a workspace is long-lived and closing one by
+	 * mistake should not be permanent — unlike the Thread status this replaces,
+	 * which only ever went one way. Returns `null` if the project does not
+	 * exist; writing to another tenant's project throws.
+	 *
+	 * This is the store-level write. The precondition that no live session is
+	 * attached belongs to {@link import('../../manager/project/lifecycle.js').ProjectManager},
+	 * because the store deliberately holds no view of what is running.
+	 */
+	setProjectStatus?(
+		projectId: ProjectId,
+		status: ProjectStatus,
+		tenantId: TenantId,
+		expectedOwnerVersion: number,
+	): Promise<Project | null>
+
 	// Session CRUD ------------------------------------------------------------
 
 	createSession(params: CreateSessionParams, tenantId: TenantId): Promise<Session>
@@ -213,6 +236,17 @@ export interface SessionStore {
 	 */
 	listSessions(threadId: ThreadId, 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.
+	 */
+	listSessionsByProject?(projectId: ProjectId, tenantId: TenantId): Promise<readonly Session[]>
+
 	/**
 	 * Hard-delete a session. Idempotent — absent sessions succeed as a no-op.
 	 * Rejects with `TenantIsolationError` on cross-tenant access.