@namzu/sdk 35.0.0 → 37.0.0

package/src/session/handoff/capacity.ts

@@ -62,7 +62,7 @@ export interface CapacityValidator {
 	): Promise<void>
 
 	/**
-	 * Asserts `existingDirectChildren + pendingNewChildren ≤ projectMaxWidth`
+	 * Asserts `liveDirectChildren + pendingNewChildren ≤ projectMaxWidth`
 	 * under `parentSessionId`. The width cap applies to a single spawn call —
 	 * a broadcast of N recipients passes `pendingNewChildren = N`.
 	 */
@@ -77,7 +77,7 @@ export interface CapacityValidator {
 /**
  * Default validator backed by {@link SessionStore}. Uses `getAncestry` for
  * depth (root-to-self chain length) and `getChildren` for width (count of
- * existing direct sub-sessions).
+ * pending or active direct sub-sessions). Historical edges stay queryable.
  */
 export class DefaultCapacityValidator implements CapacityValidator {
 	constructor(private readonly store: SessionStore) {}
@@ -108,7 +108,11 @@ export class DefaultCapacityValidator implements CapacityValidator {
 		tenantId: TenantId,
 	): Promise<void> {
 		const existing = await this.store.getChildren(parentSessionId, tenantId)
-		const total = existing.length + pendingNewChildren
+		const live = existing.filter(
+			(child) =>
+				child.status !== 'idle' && child.status !== 'failed' && child.status !== 'archived',
+		)
+		const total = live.length + pendingNewChildren
 		if (total > projectMaxWidth) {
 			throw new DelegationCapacityExceeded({
 				dimension: 'width',

package/src/store/memory/disk.ts

@@ -6,16 +6,24 @@ import type {
 	CreateMemoryParams,
 	MemoryContent,
 	MemoryIndexEntry,
+	MemoryRecord,
 	MemorySearchParams,
 	MemorySearchResult,
 	MemoryStore,
+	UpdateMemoryParams,
 } from '../../types/memory/index.js'
+import { assertMemoryStatus } from '../../types/memory/index.js'
 import { generateMemoryId, isEntityId } from '../../utils/id.js'
 import { SCOPE_ATTRIBUTE } from '../../utils/log/types.js'
 import { type Logger, resolveLogger } from '../../utils/logger.js'
 import { DiskRecordStore } from '../kv/record-store.js'
 import { defineSchema } from '../schema.js'
-import { InMemoryMemoryIndex } from './index.js'
+import { InMemoryMemoryIndex, searchMemoryEntries } from './index.js'
+import {
+	DEFAULT_MEMORY_LOCK_TIMEOUT_MS,
+	acquireMemoryOperationLock,
+	validateMemoryLockTimeout,
+} from './operation-lock.js'
 
 /**
  * This store's on-disk format, versioned as a unit — which is how a
@@ -32,27 +40,6 @@ interface StorageLocation {
 	readonly contentDir: string
 }
 
-const operationTails = new Map<string, Promise<void>>()
-
-/** Serialize every operation over one canonical disk projection in this process. */
-async function withMemoryOperationLock<T>(key: string, operation: () => Promise<T>): Promise<T> {
-	const previous = operationTails.get(key) ?? Promise.resolve()
-	let release = () => {}
-	const current = new Promise<void>((resolveCurrent) => {
-		release = resolveCurrent
-	})
-	const tail = previous.then(() => current)
-	operationTails.set(key, tail)
-
-	await previous
-	try {
-		return await operation()
-	} finally {
-		release()
-		if (operationTails.get(key) === tail) operationTails.delete(key)
-	}
-}
-
 function invalidIndex(
 	reason: string,
 	details: { entryIndex?: number; field?: string } = {},
@@ -163,11 +150,14 @@ function assertMemoryContent(value: unknown, expectedId: MemoryId): asserts valu
 export interface DiskMemoryStoreConfig {
 	baseDir: string
 	logger?: Logger
+	/** Maximum wait for another process's operation; default 10 seconds. Never breaks stale locks. */
+	lockTimeoutMs?: number
 }
 
 export class DiskMemoryStore implements MemoryStore {
 	private readonly baseDir: string
 	private readonly log: Logger
+	private readonly lockTimeoutMs: number
 	private readonly index = new InMemoryMemoryIndex()
 	private location?: StorageLocation
 	// Two instances of one primitive rather than two copies of its body.
@@ -180,6 +170,8 @@ export class DiskMemoryStore implements MemoryStore {
 	constructor(config: DiskMemoryStoreConfig) {
 		this.baseDir = join(config.baseDir, 'memory')
 		this.log = resolveLogger(config.logger).child({ [SCOPE_ATTRIBUTE]: 'store/memory/disk' })
+		this.lockTimeoutMs = config.lockTimeoutMs ?? DEFAULT_MEMORY_LOCK_TIMEOUT_MS
+		validateMemoryLockTimeout(this.lockTimeoutMs)
 	}
 
 	private get contentDir(): string {
@@ -235,10 +227,16 @@ export class DiskMemoryStore implements MemoryStore {
 		operation: (location: StorageLocation) => Promise<T>,
 	): Promise<T> {
 		const location = await this.storageLocation()
-		return withMemoryOperationLock(location.indexPath, async () => {
+		const release = await acquireMemoryOperationLock(
+			join(dirname(location.indexPath), 'operation.lock'),
+			this.lockTimeoutMs,
+		)
+		try {
 			await this.reloadIndex(location)
-			return operation(location)
-		})
+			return await operation(location)
+		} finally {
+			await release()
+		}
 	}
 
 	private async readContent(location: StorageLocation, id: MemoryId): Promise<MemoryContent> {
@@ -307,10 +305,17 @@ export class DiskMemoryStore implements MemoryStore {
 		})
 	}
 
-	async update(
-		id: MemoryId,
-		updates: Partial<CreateMemoryParams>,
-	): Promise<MemoryIndexEntry | undefined> {
+	async getRecord(id: MemoryId): Promise<MemoryRecord | undefined> {
+		return this.withAuthoritativeIndex(async (location) => {
+			assertStorageMemoryId(id, (reason) => invalidContent(id, reason, { field: 'id' }))
+			const entry = this.index.getEntry(id)
+			if (!entry) return undefined
+			return structuredClone({ entry, content: await this.readContent(location, id) })
+		})
+	}
+
+	async update(id: MemoryId, updates: UpdateMemoryParams): Promise<MemoryIndexEntry | undefined> {
+		if (updates.status !== undefined) assertMemoryStatus(updates.status)
 		return this.withAuthoritativeIndex(async (location) => {
 			assertStorageMemoryId(id, (reason) => invalidContent(id, reason, { field: 'id' }))
 			const existing = this.index.getEntry(id)
@@ -321,6 +326,7 @@ export class DiskMemoryStore implements MemoryStore {
 				title: updates.title ?? existing.title,
 				summary: updates.summary ?? existing.summary,
 				tags: updates.tags ? [...updates.tags] : existing.tags,
+				status: updates.status ?? existing.status,
 				updatedAt: Date.now(),
 			}
 			const updatesContent =
@@ -367,7 +373,23 @@ export class DiskMemoryStore implements MemoryStore {
 	}
 
 	async list(params?: MemorySearchParams): Promise<MemorySearchResult> {
-		return this.withAuthoritativeIndex(async () => this.index.search(params ?? {}))
+		return this.withAuthoritativeIndex(async (location) => {
+			if (!params?.query?.trim() && !params?.requiredIdentifiers?.length)
+				return this.index.search(params ?? {})
+			// Search the current bodies inside the same operation as the index
+			// snapshot. No retained cache can hide another process's update.
+			const candidates = this.index.search({
+				...params,
+				query: undefined,
+				limit: undefined,
+				requiredIdentifiers: undefined,
+			})
+			const contents = new Map<MemoryId, string>()
+			for (const entry of candidates.entries) {
+				contents.set(entry.id, (await this.readContent(location, entry.id)).content)
+			}
+			return searchMemoryEntries(candidates.entries, params, (id) => contents.get(id) ?? '')
+		})
 	}
 
 	getIndex(): InMemoryMemoryIndex {

package/src/store/memory/index.ts

@@ -6,37 +6,85 @@ import type {
 	MemorySearchResult,
 } from '../../types/memory/index.js'
 
-export class InMemoryMemoryIndex implements MemoryIndex {
-	private entries = new Map<string, MemoryIndexEntry>()
-
-	search(params: MemorySearchParams): MemorySearchResult {
-		let results = Array.from(this.entries.values())
-
-		if (params.query) {
-			const q = params.query.toLowerCase()
-			results = results.filter(
-				(e) => e.title.toLowerCase().includes(q) || e.summary.toLowerCase().includes(q),
-			)
-		}
-
-		if (params.tags && params.tags.length > 0) {
-			const requiredTags = params.tags
-			results = results.filter((e) => requiredTags.every((tag) => e.tags.includes(tag)))
-		}
+function terms(text: string): Set<string> {
+	return new Set(
+		text
+			.normalize('NFKC')
+			.toLowerCase()
+			.match(/[\p{L}\p{N}]+/gu) ?? [],
+	)
+}
 
-		if (params.status) {
-			results = results.filter((e) => e.status === params.status)
-		}
+/** Exact normalized word membership; no substring, stemming or alias inference. */
+export function matchesMemoryIdentifier(text: string, identifiers: ReadonlySet<string>): boolean {
+	for (const match of text
+		.normalize('NFKC')
+		.toLowerCase()
+		.matchAll(/[\p{L}\p{N}_]+/gu)) {
+		if (identifiers.has(match[0])) return true
+	}
+	return false
+}
 
-		results.sort((a, b) => b.updatedAt - a.updatedAt)
+/** Shared lexical ranking; a caller-owned index can omit body content. */
+export function searchMemoryEntries(
+	entries: readonly MemoryIndexEntry[],
+	params: MemorySearchParams,
+	contentOf: (id: MemoryId) => string = () => '',
+): MemorySearchResult {
+	const query = terms(params.query ?? '')
+	const identifiers = new Set(
+		params.requiredIdentifiers?.map((id) => id.normalize('NFKC').toLowerCase()),
+	)
+	if (params.query?.trim() && query.size === 0) return { entries: [], totalCount: 0 }
+	const ranked = entries
+		.filter(
+			(entry) =>
+				(!params.status || entry.status === params.status) &&
+				(!params.tags?.length || params.tags.every((tag) => entry.tags.includes(tag))),
+		)
+		.filter(
+			(entry) =>
+				!identifiers.size ||
+				[entry.id, entry.title, entry.summary, contentOf(entry.id)].some((text) =>
+					matchesMemoryIdentifier(text, identifiers),
+				),
+		)
+		.map((entry) => {
+			let coverage = 0
+			let score = 0
+			if (query.size > 0) {
+				const title = terms(entry.title)
+				const summary = terms(entry.summary)
+				const body = terms(contentOf(entry.id))
+				for (const term of query) {
+					const weight =
+						(title.has(term) ? 8 : 0) + (summary.has(term) ? 4 : 0) + (body.has(term) ? 1 : 0)
+					if (weight > 0) coverage++
+					score += weight
+				}
+			}
+			return { entry, coverage, score }
+		})
+		.filter(({ coverage }) => query.size === 0 || coverage > 0)
+		.sort(
+			(a, b) =>
+				b.coverage - a.coverage ||
+				b.score - a.score ||
+				b.entry.updatedAt - a.entry.updatedAt ||
+				(a.entry.id < b.entry.id ? -1 : a.entry.id > b.entry.id ? 1 : 0),
+		)
+	return {
+		entries: ranked.slice(0, params.limit ?? ranked.length).map(({ entry }) => entry),
+		totalCount: ranked.length,
+	}
+}
 
-		const totalCount = results.length
-		const limit = params.limit ?? totalCount
+export class InMemoryMemoryIndex implements MemoryIndex {
+	private entries = new Map<string, MemoryIndexEntry>()
 
-		return {
-			entries: results.slice(0, limit),
-			totalCount,
-		}
+	search(params: MemorySearchParams): MemorySearchResult {
+		return searchMemoryEntries([...this.entries.values()], params)
 	}
 
 	getEntry(id: MemoryId): MemoryIndexEntry | undefined {

package/src/store/memory/memory.ts

@@ -3,12 +3,15 @@ import type {
 	CreateMemoryParams,
 	MemoryContent,
 	MemoryIndexEntry,
+	MemoryRecord,
 	MemorySearchParams,
 	MemorySearchResult,
 	MemoryStore,
+	UpdateMemoryParams,
 } from '../../types/memory/index.js'
+import { assertMemoryStatus } from '../../types/memory/index.js'
 import { generateMemoryId } from '../../utils/id.js'
-import { InMemoryMemoryIndex } from './index.js'
+import { InMemoryMemoryIndex, searchMemoryEntries } from './index.js'
 
 export class InMemoryMemoryStore implements MemoryStore {
 	private content = new Map<string, MemoryContent>()
@@ -47,10 +50,14 @@ export class InMemoryMemoryStore implements MemoryStore {
 		return this.content.get(id)
 	}
 
-	async update(
-		id: MemoryId,
-		updates: Partial<CreateMemoryParams>,
-	): Promise<MemoryIndexEntry | undefined> {
+	async getRecord(id: MemoryId): Promise<MemoryRecord | undefined> {
+		const entry = this.index.getEntry(id)
+		const content = this.content.get(id)
+		return entry && content ? structuredClone({ entry, content }) : undefined
+	}
+
+	async update(id: MemoryId, updates: UpdateMemoryParams): Promise<MemoryIndexEntry | undefined> {
+		if (updates.status !== undefined) assertMemoryStatus(updates.status)
 		const existing = this.index.getEntry(id)
 		if (!existing) return undefined
 
@@ -61,6 +68,7 @@ export class InMemoryMemoryStore implements MemoryStore {
 			title: updates.title ?? existing.title,
 			summary: updates.summary ?? existing.summary,
 			tags: updates.tags ? [...updates.tags] : existing.tags,
+			status: updates.status ?? existing.status,
 			updatedAt: now,
 		}
 
@@ -94,7 +102,11 @@ export class InMemoryMemoryStore implements MemoryStore {
 	}
 
 	async list(params?: MemorySearchParams): Promise<MemorySearchResult> {
-		return this.index.search(params ?? {})
+		return searchMemoryEntries(
+			this.index.allEntries(),
+			params ?? {},
+			(id) => this.content.get(id)?.content ?? '',
+		)
 	}
 
 	getIndex(): InMemoryMemoryIndex {

package/src/store/memory/operation-lock.ts

@@ -0,0 +1,99 @@
+import { randomUUID } from 'node:crypto'
+import { type FileHandle, lstat, open, readFile, unlink } from 'node:fs/promises'
+import { setTimeout as delay } from 'node:timers/promises'
+
+import { NamzuError } from '../../types/errors/index.js'
+
+/** Wait bound, not a lease: a slow or crashed owner is never silently replaced. */
+export const DEFAULT_MEMORY_LOCK_TIMEOUT_MS = 10_000
+
+export function validateMemoryLockTimeout(timeoutMs: number): void {
+	if (!Number.isSafeInteger(timeoutMs) || timeoutMs <= 0) {
+		throw new NamzuError({
+			code: 'invalid_config',
+			message: 'DiskMemoryStore lockTimeoutMs must be a positive safe integer.',
+			retryable: false,
+		})
+	}
+}
+
+function lockError(path: string, reason: string, timeoutMs: number): NamzuError {
+	return new NamzuError({
+		code: 'storage_error',
+		message: `Memory operation lock ${path}: ${reason}. Stop all processes using this memory store and inspect the lock owner before removing a stale lock; it is never broken automatically.`,
+		details: { lockPath: path, timeoutMs },
+		retryable: false,
+	})
+}
+
+/**
+ * Local-filesystem exclusion for cooperating processes. Atomic rename of the
+ * index alone cannot serialize the index/content read-modify-write transaction.
+ * An abandoned lock fails closed; guessing a lease expired would permit two
+ * live writers to overwrite each other again.
+ */
+export async function acquireMemoryOperationLock(
+	path: string,
+	timeoutMs: number,
+): Promise<() => Promise<void>> {
+	const deadline = performance.now() + timeoutMs
+	let attempted = false
+	for (;;) {
+		if (attempted && performance.now() >= deadline) {
+			throw lockError(path, `acquisition timed out after ${timeoutMs} ms`, timeoutMs)
+		}
+		attempted = true
+		let handle: FileHandle
+		try {
+			handle = await open(path, 'wx', 0o600)
+		} catch (error) {
+			if ((error as NodeJS.ErrnoException).code !== 'EEXIST') throw error
+			const existing = await lstat(path).catch((statError: NodeJS.ErrnoException) => {
+				if (statError.code === 'ENOENT') return undefined
+				throw statError
+			})
+			if (!existing) continue
+			if (!existing.isFile() || existing.isSymbolicLink()) {
+				throw lockError(path, 'the occupied lock is not a regular file', timeoutMs)
+			}
+			if (performance.now() >= deadline) {
+				throw lockError(path, `acquisition timed out after ${timeoutMs} ms`, timeoutMs)
+			}
+			await delay(Math.min(25, Math.max(1, deadline - performance.now())))
+			continue
+		}
+
+		const owner = `${JSON.stringify({ pid: process.pid, token: randomUUID(), acquiredAt: Date.now() })}\n`
+		const identity = await handle.stat().catch(async (error: unknown) => {
+			await handle.close()
+			// Exclusive create happened, but ownership could not be established.
+			// Leave the path for explicit recovery rather than unlink an unknown inode.
+			throw error
+		})
+		try {
+			await handle.writeFile(owner, 'utf8')
+			await handle.sync()
+		} catch (error) {
+			await handle.close()
+			const current = await lstat(path).catch(() => undefined)
+			if (current?.dev === identity.dev && current.ino === identity.ino) {
+				await unlink(path).catch(() => undefined)
+			}
+			throw error
+		}
+		await handle.close()
+		return async () => {
+			const current = await lstat(path)
+			if (
+				!current.isFile() ||
+				current.isSymbolicLink() ||
+				current.dev !== identity.dev ||
+				current.ino !== identity.ino ||
+				(await readFile(path, 'utf8')) !== owner
+			) {
+				throw lockError(path, 'the lock owner changed before release', timeoutMs)
+			}
+			await unlink(path)
+		}
+	}
+}