@namzu/sdk 48.3.1 → 50.0.0

package/src/store/memory/index.ts

@@ -26,6 +26,56 @@ export function matchesMemoryIdentifier(text: string, identifiers: ReadonlySet<s
 	return false
 }
 
+interface MemoryScanSelection {
+	readonly entries: readonly MemoryIndexEntry[]
+	readonly truncated: boolean
+	readonly scannedCount: number
+	readonly nextScanOffset?: number
+}
+
+/** Select a bounded, resumable snapshot of indexed candidates before reading any bodies. */
+export function selectMemorySearchCandidates(
+	entries: readonly MemoryIndexEntry[],
+	params: MemorySearchParams,
+): MemoryScanSelection {
+	if (
+		params.maxScanned !== undefined &&
+		(!Number.isSafeInteger(params.maxScanned) || params.maxScanned < 1)
+	) {
+		throw new RangeError('maxScanned must be a positive safe integer')
+	}
+	if (
+		params.scanOffset !== undefined &&
+		(!Number.isSafeInteger(params.scanOffset) || params.scanOffset < 0)
+	) {
+		throw new RangeError('scanOffset must be a nonnegative safe integer')
+	}
+	const query = terms(params.query ?? '')
+	if (params.query?.trim() && query.size === 0)
+		return { entries: [], truncated: false, scannedCount: 0 }
+	const bodySearch =
+		query.size > 0 ||
+		Boolean(params.requiredIdentifiers?.length) ||
+		params.maxScanned !== undefined ||
+		params.scanOffset !== undefined
+	if (!bodySearch) return { entries, truncated: false, scannedCount: 0 }
+	const ordered = [...entries].sort(
+		(a, b) => b.updatedAt - a.updatedAt || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0),
+	)
+	const start = params.scanOffset ?? 0
+	const selected = ordered.slice(
+		start,
+		params.maxScanned === undefined ? undefined : start + params.maxScanned,
+	)
+	const next = start + selected.length
+	return {
+		entries: selected,
+		truncated: next < ordered.length,
+		scannedCount: selected.length,
+		...(next < ordered.length ? { nextScanOffset: next } : {}),
+	}
+}
+
 /** Shared lexical ranking; a caller-owned index can omit body content. */
 export function searchMemoryEntries(
 	entries: readonly MemoryIndexEntry[],
@@ -36,13 +86,13 @@ export function searchMemoryEntries(
 	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))),
-		)
+	const candidates = entries.filter(
+		(entry) =>
+			(!params.status || entry.status === params.status) &&
+			(!params.tags?.length || params.tags.every((tag) => entry.tags.includes(tag))),
+	)
+	const selection = selectMemorySearchCandidates(candidates, params)
+	const ranked = selection.entries
 		.filter(
 			(entry) =>
 				!identifiers.size ||
@@ -79,6 +129,15 @@ export function searchMemoryEntries(
 	return {
 		entries: ranked.slice(0, params.limit ?? ranked.length).map(({ entry }) => entry),
 		totalCount: ranked.length,
+		...(params.maxScanned !== undefined || params.scanOffset !== undefined
+			? {
+					truncated: selection.truncated,
+					scannedCount: selection.scannedCount,
+					...(selection.nextScanOffset !== undefined
+						? { nextScanOffset: selection.nextScanOffset }
+						: {}),
+				}
+			: {}),
 	}
 }
 

package/src/store/memory/markdown.ts

@@ -5,15 +5,16 @@ import { dirname, join, resolve } from 'node:path'
 import { NamzuError } from '../../types/errors/index.js'
 import type { MemoryId } from '../../types/ids/index.js'
 import type {
+	ConditionalMemoryStore,
 	CreateMemoryParams,
 	MemoryContent,
 	MemoryIndexEntry,
 	MemoryRecord,
 	MemorySearchParams,
 	MemorySearchResult,
-	MemoryStore,
 	MemoryType,
 	UpdateMemoryParams,
+	VersionedMemoryRecord,
 } from '../../types/memory/index.js'
 import { assertMemoryStatus, isMemoryType } from '../../types/memory/index.js'
 import { atomicWriteFile } from '../../utils/atomic-write.js'
@@ -47,6 +48,7 @@ import {
 	acquireMemoryOperationLock,
 	validateMemoryLockTimeout,
 } from './operation-lock.js'
+import { MemoryRevisionConflictError, assertMemoryRevision, memoryRevision } from './revision.js'
 
 /**
  * Versioned like every other record this SDK persists. A memory file carries
@@ -296,7 +298,7 @@ function decodeMemoryFile(
  * holds with {@link MemoryNameConflictError}, and derives a free one from the
  * title when none is given.
  */
-export class MarkdownMemoryStore implements MemoryStore {
+export class MarkdownMemoryStore implements ConditionalMemoryStore {
 	private readonly directory: string
 	private readonly log: Logger
 	private readonly lockTimeoutMs: number
@@ -587,6 +589,15 @@ export class MarkdownMemoryStore implements MemoryStore {
 		})
 	}
 
+	async getVersionedRecord(id: MemoryId): Promise<VersionedMemoryRecord | undefined> {
+		return this.withLoaded(async (_dir, loaded) => {
+			const memory = loaded.get(id)
+			if (!memory) return undefined
+			const record = structuredClone({ entry: memory.entry, content: memory.content })
+			return { ...record, revision: memoryRevision(record) }
+		})
+	}
+
 	/** The current record held under `name`, archived included, or `undefined`. */
 	async getByName(name: string): Promise<MemoryRecord | undefined> {
 		return this.withLoaded(async (_dir, loaded) => {
@@ -603,10 +614,35 @@ export class MarkdownMemoryStore implements MemoryStore {
 	}
 
 	async update(id: MemoryId, updates: UpdateMemoryParams): Promise<MemoryIndexEntry | undefined> {
+		return this.updateInternal(id, updates)
+	}
+
+	async updateIfRevision(
+		id: MemoryId,
+		updates: UpdateMemoryParams,
+		expectedRevision: string,
+	): Promise<MemoryIndexEntry> {
+		const updated = await this.updateInternal(id, updates, expectedRevision)
+		if (!updated) throw new MemoryRevisionConflictError(id)
+		return updated
+	}
+
+	private async updateInternal(
+		id: MemoryId,
+		updates: UpdateMemoryParams,
+		expectedRevision?: string,
+	): Promise<MemoryIndexEntry | undefined> {
 		if (updates.status !== undefined) assertMemoryStatus(updates.status)
 		assertOptionalMemoryFields(updates)
 		return this.mutate(async (dir, loaded) => {
 			const existing = loaded.get(id)
+			if (expectedRevision !== undefined) {
+				assertMemoryRevision(
+					id,
+					existing ? { entry: existing.entry, content: existing.content } : undefined,
+					expectedRevision,
+				)
+			}
 			if (!existing) return undefined
 			const entries = this.entries(loaded)
 			if (updates.name !== undefined) {
@@ -645,8 +681,24 @@ export class MarkdownMemoryStore implements MemoryStore {
 	}
 
 	async delete(id: MemoryId): Promise<boolean> {
+		return this.deleteInternal(id)
+	}
+
+	async deleteIfRevision(id: MemoryId, expectedRevision: string): Promise<void> {
+		const deleted = await this.deleteInternal(id, expectedRevision)
+		if (!deleted) throw new MemoryRevisionConflictError(id)
+	}
+
+	private async deleteInternal(id: MemoryId, expectedRevision?: string): Promise<boolean> {
 		return this.mutate(async (dir, loaded) => {
 			const existing = loaded.get(id)
+			if (expectedRevision !== undefined) {
+				assertMemoryRevision(
+					id,
+					existing ? { entry: existing.entry, content: existing.content } : undefined,
+					expectedRevision,
+				)
+			}
 			if (!existing) return false
 			try {
 				await unlink(existing.path)

package/src/store/memory/memory.ts

@@ -1,13 +1,14 @@
 import type { MemoryId } from '../../types/ids/index.js'
 import type {
+	ConditionalMemoryStore,
 	CreateMemoryParams,
 	MemoryContent,
 	MemoryIndexEntry,
 	MemoryRecord,
 	MemorySearchParams,
 	MemorySearchResult,
-	MemoryStore,
 	UpdateMemoryParams,
+	VersionedMemoryRecord,
 } from '../../types/memory/index.js'
 import { assertMemoryStatus } from '../../types/memory/index.js'
 import { generateMemoryId } from '../../utils/id.js'
@@ -18,8 +19,9 @@ import {
 	nameHolder,
 	withOptionalFields,
 } from './naming.js'
+import { assertMemoryRevision, memoryRevision } from './revision.js'
 
-export class InMemoryMemoryStore implements MemoryStore {
+export class InMemoryMemoryStore implements ConditionalMemoryStore {
 	private content = new Map<string, MemoryContent>()
 	private index = new InMemoryMemoryIndex()
 
@@ -70,10 +72,45 @@ export class InMemoryMemoryStore implements MemoryStore {
 		return entry && content ? structuredClone({ entry, content }) : undefined
 	}
 
+	async getVersionedRecord(id: MemoryId): Promise<VersionedMemoryRecord | undefined> {
+		const entry = this.index.getEntry(id)
+		const content = this.content.get(id)
+		if (!entry || !content) return undefined
+		const record = structuredClone({ entry, content })
+		return { ...record, revision: memoryRevision(record) }
+	}
+
 	async update(id: MemoryId, updates: UpdateMemoryParams): Promise<MemoryIndexEntry | undefined> {
+		return this.updateNow(id, updates)
+	}
+
+	async updateIfRevision(
+		id: MemoryId,
+		updates: UpdateMemoryParams,
+		expectedRevision: string,
+	): Promise<MemoryIndexEntry> {
+		// No await between the check and mutation: one in-memory operation turn.
+		const entry = this.updateNow(id, updates, expectedRevision)
+		if (!entry) throw new Error('A conditional memory update unexpectedly found no record.')
+		return entry
+	}
+
+	private updateNow(
+		id: MemoryId,
+		updates: UpdateMemoryParams,
+		expectedRevision?: string,
+	): MemoryIndexEntry | undefined {
 		if (updates.status !== undefined) assertMemoryStatus(updates.status)
 		assertOptionalMemoryFields(updates)
 		const existing = this.index.getEntry(id)
+		if (expectedRevision !== undefined) {
+			const content = this.content.get(id)
+			assertMemoryRevision(
+				id,
+				existing && content ? { entry: existing, content } : undefined,
+				expectedRevision,
+			)
+		}
 		if (!existing) return undefined
 		if (updates.name !== undefined) {
 			const holder = nameHolder(this.index.allEntries(), updates.name, id)
@@ -118,6 +155,19 @@ export class InMemoryMemoryStore implements MemoryStore {
 	}
 
 	async delete(id: MemoryId): Promise<boolean> {
+		return this.deleteNow(id)
+	}
+
+	async deleteIfRevision(id: MemoryId, expectedRevision: string): Promise<void> {
+		this.deleteNow(id, expectedRevision)
+	}
+
+	private deleteNow(id: MemoryId, expectedRevision?: string): boolean {
+		if (expectedRevision !== undefined) {
+			const entry = this.index.getEntry(id)
+			const content = this.content.get(id)
+			assertMemoryRevision(id, entry && content ? { entry, content } : undefined, expectedRevision)
+		}
 		const existed = this.index.remove(id)
 		this.content.delete(id)
 		return existed

package/src/store/memory/revision.ts

@@ -0,0 +1,158 @@
+import { createHash } from 'node:crypto'
+import { NamzuError } from '../../types/errors/index.js'
+import type { MemoryId } from '../../types/ids/index.js'
+import type { MemoryRecord } from '../../types/memory/index.js'
+
+/** A record can be read, but its metadata cannot be fingerprinted synchronously. */
+export class MemoryRevisionUnavailableError extends Error {
+	constructor() {
+		super('This memory contains metadata that cannot be revision-checked.')
+		this.name = 'MemoryRevisionUnavailableError'
+	}
+}
+
+/**
+ * Encode the same structured-clone snapshot `getRecord` returns. Type tags,
+ * object references and sorted plain-object keys preserve values JSON loses:
+ * BigInt, undefined, Map/Set contents, Date, typed arrays and cycles. Map and
+ * Set order is kept because it is observable. Unknown host objects (notably
+ * Blob, whose bytes need asynchronous reading) fail closed rather than hash as
+ * `{}` and allow a stale conditional write.
+ */
+function canonicalRecord(record: MemoryRecord): string {
+	let snapshot: MemoryRecord
+	try {
+		snapshot = structuredClone(record)
+	} catch {
+		throw new MemoryRevisionUnavailableError()
+	}
+	const seen = new WeakMap<object, number>()
+	let nextId = 0
+
+	function encode(value: unknown): unknown {
+		if (value === null) return ['null']
+		switch (typeof value) {
+			case 'undefined':
+				return ['undefined']
+			case 'string':
+				return ['string', value]
+			case 'boolean':
+				return ['boolean', value]
+			case 'bigint':
+				return ['bigint', value.toString()]
+			case 'number':
+				return ['number', Object.is(value, -0) ? '-0' : String(value)]
+			case 'function':
+			case 'symbol':
+				throw new MemoryRevisionUnavailableError()
+			case 'object':
+				break
+		}
+
+		const object = value as object
+		const previous = seen.get(object)
+		if (previous !== undefined) return ['ref', previous]
+		const id = nextId++
+		seen.set(object, id)
+		if (Array.isArray(object)) {
+			return [
+				'array',
+				id,
+				object.length,
+				Object.keys(object)
+					.sort()
+					.map((key) => [key, encode((object as unknown as Record<string, unknown>)[key])]),
+			]
+		}
+		if (object instanceof Map) {
+			return ['map', id, [...object].map(([key, item]) => [encode(key), encode(item)])]
+		}
+		if (object instanceof Set) return ['set', id, [...object].map(encode)]
+		if (object instanceof Date) return ['date', id, encode(object.getTime())]
+		if (object instanceof RegExp)
+			return ['regexp', id, object.source, object.flags, object.lastIndex]
+		if (object instanceof ArrayBuffer) {
+			const buffer = object as ArrayBuffer & {
+				readonly maxByteLength?: number
+				readonly resizable?: boolean
+			}
+			return [
+				'array-buffer',
+				id,
+				buffer.byteLength,
+				buffer.maxByteLength,
+				buffer.resizable,
+				Buffer.from(buffer).toString('hex'),
+			]
+		}
+		if (ArrayBuffer.isView(object)) {
+			// A view exposes its entire backing buffer through `.buffer`, even
+			// when its visible slice is one byte. Structured cloning keeps that
+			// backing and preserves aliases between multiple views.
+			if (
+				(typeof SharedArrayBuffer !== 'undefined' && object.buffer instanceof SharedArrayBuffer) ||
+				(object.buffer instanceof ArrayBuffer &&
+					(object.buffer as ArrayBuffer & { readonly resizable?: boolean }).resizable === true)
+			)
+				throw new MemoryRevisionUnavailableError()
+			return [
+				'array-buffer-view',
+				id,
+				object.constructor.name,
+				object.byteOffset,
+				object.byteLength,
+				encode(object.buffer),
+			]
+		}
+		if (object instanceof Error) {
+			return ['error', id, object.name, object.message, object.stack, encode(object.cause)]
+		}
+		if (object instanceof Number || object instanceof String || object instanceof Boolean)
+			return ['boxed', id, object.constructor.name, encode(object.valueOf())]
+		if (typeof SharedArrayBuffer !== 'undefined' && object instanceof SharedArrayBuffer)
+			throw new MemoryRevisionUnavailableError()
+		const prototype = Object.getPrototypeOf(object)
+		if (prototype !== Object.prototype && prototype !== null)
+			throw new MemoryRevisionUnavailableError()
+		return [
+			'object',
+			id,
+			Object.keys(object as Record<string, unknown>)
+				.sort()
+				.map((key) => [key, encode((object as Record<string, unknown>)[key])]),
+		]
+	}
+
+	return JSON.stringify(encode(snapshot))
+}
+
+/** A content-derived token; it includes metadata as well as the body. */
+export function memoryRevision(record: MemoryRecord): string {
+	return `m2:${createHash('sha256').update(canonicalRecord(record)).digest('hex')}`
+}
+
+/** The record changed or disappeared after its revision was read. */
+export class MemoryRevisionConflictError extends NamzuError {
+	readonly memoryId: MemoryId
+
+	constructor(memoryId: MemoryId) {
+		super({
+			code: 'storage_error',
+			message: `Memory ${memoryId} changed since it was read. Read it again before changing it.`,
+			details: { memoryId, reason: 'revision_conflict' },
+			retryable: false,
+		})
+		this.name = 'MemoryRevisionConflictError'
+		this.memoryId = memoryId
+	}
+}
+
+export function assertMemoryRevision(
+	id: MemoryId,
+	record: MemoryRecord | undefined,
+	expectedRevision: string,
+): asserts record is MemoryRecord {
+	if (!record || memoryRevision(record) !== expectedRevision) {
+		throw new MemoryRevisionConflictError(id)
+	}
+}

package/src/store/session/disk.ts

@@ -36,7 +36,7 @@
 
 import { createHash } from 'node:crypto'
 import { mkdir, rm } from 'node:fs/promises'
-import { join } from 'node:path'
+import { join, resolve } from 'node:path'
 import {
 	ProjectRootPathTakenError,
 	StaleProjectError,
@@ -44,7 +44,7 @@ import {
 	TenantIsolationError,
 } from '../../session/errors.js'
 import { SessionAlreadySummarizedError } from '../../session/summary/errors.js'
-import type { SessionId, TenantId } from '../../types/ids/index.js'
+import type { SessionId, TenantId, TurnId } from '../../types/ids/index.js'
 import type { Project, ProjectStatus } from '../../types/project/entity.js'
 import type { Session } from '../../types/session/entity.js'
 import type { ProjectId, SubSessionId, SummaryId, TopicId } from '../../types/session/ids.js'
@@ -68,6 +68,7 @@ import {
 	asSessionId,
 	asSubSessionId,
 	asTopicId,
+	asTurnId,
 	generateProjectId,
 	generateSessionId,
 	generateSubSessionId,
@@ -237,6 +238,7 @@ interface PersistedSubSession {
 interface PersistedSummary {
 	id: SummaryId
 	sessionRef: SessionId
+	turnRef?: TurnId
 	tenantId: TenantId
 	outcome: SessionSummaryOutcome
 	deliverables: readonly DeliverableRef[]
@@ -257,6 +259,10 @@ const SUMMARY_TERMINAL_FLIP_STATUSES: ReadonlySet<Session['status']> = new Set([
 	'awaiting_merge',
 ])
 
+// Share the in-process writer guard across store instances addressing the same
+// root. This is not a cross-process lease; external writers remain a host concern.
+const sessionWriters = new Map<string, Promise<void>>()
+
 /**
  * Index of projectId → its directory path. Built lazily on lookup via
  * {@link DiskSessionStore.resolveProjectDir}; populated by create / getProject.
@@ -276,6 +282,8 @@ interface SessionIndexEntry {
 }
 
 export class DiskSessionStore implements SessionStore {
+	readonly supportsInvocationSummaries: boolean = true
+	readonly supportsOwnerVersionCas: boolean = true
 	private readonly rootDir: string
 	private readonly projectIndex = new Map<ProjectId, ProjectIndexEntry>()
 	private readonly sessionIndex = new Map<SessionId, SessionIndexEntry>()
@@ -288,6 +296,24 @@ export class DiskSessionStore implements SessionStore {
 		this.rootDir = config.rootDir
 	}
 
+	private async withSessionWrite<T>(sessionId: SessionId, operation: () => Promise<T>): Promise<T> {
+		const key = resolve(this.rootDir, sessionId)
+		const previous = sessionWriters.get(key) ?? Promise.resolve()
+		let release = () => {}
+		const held = new Promise<void>((resolveWrite) => {
+			release = resolveWrite
+		})
+		const tail = previous.then(() => held)
+		sessionWriters.set(key, tail)
+		await previous
+		try {
+			return await operation()
+		} finally {
+			release()
+			if (sessionWriters.get(key) === tail) sessionWriters.delete(key)
+		}
+	}
+
 	// Project CRUD ------------------------------------------------------------
 
 	async createProject(params: CreateProjectParams, tenantId: TenantId): Promise<Project> {
@@ -654,6 +680,16 @@ export class DiskSessionStore implements SessionStore {
 		session: Session,
 		tenantId: TenantId,
 		expectedOwnerVersion?: number,
+	): Promise<void> {
+		await this.withSessionWrite(session.id, () =>
+			this.updateSessionUnlocked(session, tenantId, expectedOwnerVersion),
+		)
+	}
+
+	private async updateSessionUnlocked(
+		session: Session,
+		tenantId: TenantId,
+		expectedOwnerVersion?: number,
 	): Promise<void> {
 		const located = await this.locateSession(session.id)
 		if (!located) {
@@ -669,10 +705,8 @@ export class DiskSessionStore implements SessionStore {
 		if (existing) {
 			this.assertTenant(existing.tenantId, tenantId, `session(${session.id})`)
 		}
-		// Against what is on disk, not against the payload. The write itself is
-		// atomic; this read-compare-write is NOT a critical section, so two
-		// processes can still both pass — see the contract note on
-		// `SessionStore.updateSession`. In one process it is the real lock.
+		// Against the stored version, under the shared in-process writer guard.
+		// Other processes can still both pass; see SessionStore.updateSession.
 		if (
 			expectedOwnerVersion !== undefined &&
 			existing !== null &&
@@ -862,11 +896,22 @@ export class DiskSessionStore implements SessionStore {
 	 * leaves summary present + session still non-terminal — recovery replays
 	 * the flip via {@link SessionSummaryMaterializer.recover}. Idempotent when
 	 * the same summary is re-presented (recovery path); rejects a *different*
-	 * summary for the same session as {@link SessionAlreadySummarizedError}.
+	 * summary at the same conversation or invocation key as {@link SessionAlreadySummarizedError}.
 	 */
 	async recordSummary(
 		summary: SessionSummaryRef & { materializedBy: 'kernel' },
 		tenantId: TenantId,
+		expectedOwnerVersion?: number,
+	): Promise<void> {
+		await this.withSessionWrite(summary.sessionRef, () =>
+			this.recordSummaryUnlocked(summary, tenantId, expectedOwnerVersion),
+		)
+	}
+
+	private async recordSummaryUnlocked(
+		summary: SessionSummaryRef & { materializedBy: 'kernel' },
+		tenantId: TenantId,
+		expectedOwnerVersion?: number,
 	): Promise<void> {
 		if (summary.tenantId !== tenantId) {
 			throw new TenantIsolationError({
@@ -884,8 +929,15 @@ export class DiskSessionStore implements SessionStore {
 			throw new Error(`Session ${summary.sessionRef} not found on disk`)
 		}
 		this.assertTenant(sessionRaw.tenantId, tenantId, `session(${summary.sessionRef})`)
+		if (expectedOwnerVersion !== undefined && sessionRaw.ownerVersion !== expectedOwnerVersion) {
+			throw new StaleSessionError({
+				sessionId: summary.sessionRef,
+				expectedVersion: expectedOwnerVersion,
+				actualVersion: sessionRaw.ownerVersion,
+			})
+		}
 
-		const summaryPath = join(located.path, 'summary.json')
+		const summaryPath = summaryFile(located.path, summary.turnRef)
 		const existingRaw = await records.read<PersistedSummary>(summaryPath)
 		if (existingRaw) {
 			this.assertTenant(existingRaw.tenantId, tenantId, `summary(${existingRaw.id})`)
@@ -899,6 +951,8 @@ export class DiskSessionStore implements SessionStore {
 			// to the status flip so crash-between-writes is recovered.
 		} else {
 			// Step 1: persist summary.
+			if (summary.turnRef)
+				await mkdir(join(located.path, 'turn-summaries'), { recursive: true, mode: 0o700 })
 			await records.write(summaryPath, serializeSummary(summary))
 		}
 
@@ -913,10 +967,15 @@ export class DiskSessionStore implements SessionStore {
 		}
 	}
 
-	async getSummary(sessionId: SessionId, tenantId: TenantId): Promise<SessionSummaryRef | null> {
+	async getSummary(
+		sessionId: SessionId,
+		tenantId: TenantId,
+		turnId?: TurnId,
+	): Promise<SessionSummaryRef | null> {
+		if (turnId !== undefined) asTurnId(turnId)
 		const located = await this.locateSession(sessionId)
 		if (!located) return null
-		const raw = await records.read<PersistedSummary>(join(located.path, 'summary.json'))
+		const raw = await records.read<PersistedSummary>(summaryFile(located.path, turnId))
 		if (!raw) return null
 		this.assertTenant(raw.tenantId, tenantId, `summary(${raw.id})`)
 		return deserializeSummary(raw)
@@ -1161,6 +1220,7 @@ function serializeSummary(s: SessionSummaryRef): PersistedSummary {
 	return {
 		id: s.id,
 		sessionRef: s.sessionRef,
+		...(s.turnRef ? { turnRef: s.turnRef } : {}),
 		tenantId: s.tenantId,
 		outcome: s.outcome,
 		deliverables: s.deliverables,
@@ -1182,6 +1242,7 @@ function deserializeSummary(s: PersistedSummary): SessionSummaryRef {
 	return {
 		id: s.id,
 		sessionRef: s.sessionRef,
+		...(s.turnRef ? { turnRef: asTurnId(s.turnRef) } : {}),
 		tenantId: s.tenantId,
 		outcome: s.outcome,
 		deliverables: s.deliverables,
@@ -1191,3 +1252,9 @@ function deserializeSummary(s: PersistedSummary): SessionSummaryRef {
 		materializedBy: 'kernel',
 	}
 }
+
+function summaryFile(directory: string, turnId?: TurnId): string {
+	return turnId === undefined
+		? join(directory, 'summary.json')
+		: join(directory, 'turn-summaries', `${asTurnId(turnId)}.json`)
+}