@namzu/sdk 30.2.0 → 31.0.0

package/src/store/run/memory.ts

@@ -1,7 +1,12 @@
 import type { AuditEvent } from '../../types/run/audit.js'
 import type { Run } from '../../types/run/entity.js'
 import type { PersistedRunEvent, RunEvent } from '../../types/run/events.js'
-import type { CompletedToolRecord, ReadRunEventsOptions, RunStore } from '../../types/run/store.js'
+import type {
+	CompletedToolRecord,
+	ReadRunEventsOptions,
+	RunMessageSnapshot,
+	RunStore,
+} from '../../types/run/store.js'
 
 /**
  * Process-local {@link RunStore}: a run's evidence with no filesystem.
@@ -22,6 +27,7 @@ export class InMemoryRunStore implements RunStore {
 	private parentRunId: string | undefined
 	private meta: Run | null = null
 	private messages: Run['messages'] = []
+	private messagesThroughEventSeq: number | null = null
 	private report: string | null = null
 	private events: PersistedRunEvent[] = []
 	private auditEvents: AuditEvent[] = []
@@ -36,6 +42,7 @@ export class InMemoryRunStore implements RunStore {
 		if (this.runId !== null && this.runId !== runId) {
 			this.meta = null
 			this.messages = []
+			this.messagesThroughEventSeq = null
 			this.report = null
 			this.events = []
 			this.auditEvents = []
@@ -72,9 +79,22 @@ export class InMemoryRunStore implements RunStore {
 		this.meta = structuredClone(run)
 	}
 
-	async writeMessages(run: Run): Promise<void> {
+	async writeMessages(run: Run, throughEventSeq: number): Promise<void> {
 		this.requireInit()
 		this.messages = structuredClone(run.messages)
+		this.messagesThroughEventSeq = throughEventSeq
+	}
+
+	async readMessages(): Promise<RunMessageSnapshot> {
+		this.requireInit()
+		if (this.messagesThroughEventSeq === null) {
+			return { kind: 'unavailable', reason: 'not-persisted' }
+		}
+		return {
+			kind: 'available',
+			throughEventSeq: this.messagesThroughEventSeq,
+			messages: structuredClone(this.messages),
+		}
 	}
 
 	async appendEvent(event: RunEvent): Promise<void> {

package/src/store/session/disk.ts

@@ -83,13 +83,36 @@ import type { LinkageView } from './linkage.js'
  */
 const SCHEMA = defineSchema({
 	kind: 'session-store',
-	current: 3,
+	current: 4,
 	migrations: {
 		1: migrateSessionStoreThreadIdToTopicId,
 		2: migrateSessionStoreTopicIdPrefix,
+		3: migrateSessionStoreMessageRecordKind,
 	},
 })
 
+/**
+ * v3 → v4: distinguish ordinary message appends from atomic replacements.
+ *
+ * The schema migrator runs over every record kind in this store, so the
+ * predicate names the fields unique to a message-log line and leaves project,
+ * session, sub-session and summary records byte-for-byte alone.
+ */
+export function migrateSessionStoreMessageRecordKind(
+	record: Record<string, unknown>,
+): Record<string, unknown> {
+	if (
+		record.recordKind !== undefined ||
+		typeof record.id !== 'string' ||
+		typeof record.sessionId !== 'string' ||
+		!('message' in record) ||
+		typeof record.at !== 'string'
+	) {
+		return record
+	}
+	return { ...record, recordKind: 'message' }
+}
+
 /**
  * Read, write and list, through the one implementation.
  *
@@ -216,6 +239,7 @@ interface PersistedSubSession {
 }
 
 interface PersistedMessageLine {
+	recordKind: 'message'
 	id: MessageId
 	sessionId: SessionId
 	tenantId: TenantId
@@ -223,6 +247,26 @@ interface PersistedMessageLine {
 	at: string
 }
 
+/**
+ * One atomic projection change inside the append-only message log.
+ *
+ * Writing the replacement as several ordinary lines would expose a prefix if
+ * the process died between appends. One line is the transaction boundary: a
+ * reader sees the old conversation or the complete compacted one.
+ */
+interface PersistedMessageReplacementLine {
+	recordKind: 'replacement'
+	sessionId: SessionId
+	tenantId: TenantId
+	messages: readonly {
+		readonly id: MessageId
+		readonly message: Message
+		readonly at: string
+	}[]
+}
+
+type PersistedMessageRecord = PersistedMessageLine | PersistedMessageReplacementLine
+
 interface PersistedSummary {
 	id: SummaryId
 	sessionRef: SessionId
@@ -738,6 +782,7 @@ export class DiskSessionStore implements SessionStore {
 
 		const id = generateMessageId()
 		const entry: PersistedMessageLine = {
+			recordKind: 'message',
 			id,
 			sessionId,
 			tenantId,
@@ -755,6 +800,36 @@ export class DiskSessionStore implements SessionStore {
 		return id
 	}
 
+	async replaceMessages(
+		sessionId: SessionId,
+		messages: readonly Message[],
+		tenantId: TenantId,
+	): Promise<void> {
+		const located = await this.locateSession(sessionId)
+		if (!located) throw new Error(`Session ${sessionId} not found`)
+
+		const session = await records.read<PersistedSession>(join(located.path, 'session.json'))
+		if (!session) throw new Error(`Session ${sessionId} not found on disk`)
+		this.assertTenant(session.tenantId, tenantId, `session(${sessionId})`)
+
+		const at = new Date().toISOString()
+		const entry: PersistedMessageReplacementLine = {
+			recordKind: 'replacement',
+			sessionId,
+			tenantId,
+			messages: messages.map((message) => ({ id: generateMessageId(), message, at })),
+		}
+		// One append, however many projected messages. If the process dies before
+		// this line lands, readers see the old projection; after it lands, they
+		// see the whole replacement. There is no prefix state to mistake for a
+		// successful compaction.
+		await appendFile(
+			join(located.path, 'messages.jsonl'),
+			`${JSON.stringify(stamp(SCHEMA, entry))}\n`,
+			'utf-8',
+		)
+	}
+
 	async loadMessages(sessionId: SessionId, tenantId: TenantId): Promise<readonly Message[]> {
 		const rows = await this.loadSessionMessages(sessionId, tenantId)
 		return rows.map((r) => r.message)
@@ -781,16 +856,28 @@ export class DiskSessionStore implements SessionStore {
 			throw err
 		}
 		const lines = raw.split('\n').filter((l) => l.length > 0)
-		return lines.map((line) => {
-			const persisted = migrate<PersistedMessageLine>(SCHEMA, JSON.parse(line))
-			return {
+		let projected: SessionMessage[] = []
+		for (const line of lines) {
+			const persisted = migrate<PersistedMessageRecord>(SCHEMA, JSON.parse(line))
+			if (persisted.recordKind === 'replacement') {
+				projected = persisted.messages.map((entry) => ({
+					id: entry.id,
+					sessionId: persisted.sessionId,
+					tenantId: persisted.tenantId,
+					message: entry.message,
+					at: new Date(entry.at),
+				}))
+				continue
+			}
+			projected.push({
 				id: persisted.id,
 				sessionId: persisted.sessionId,
 				tenantId: persisted.tenantId,
 				message: persisted.message,
 				at: new Date(persisted.at),
-			}
-		})
+			})
+		}
+		return projected
 	}
 
 	// Linkage -----------------------------------------------------------------

package/src/store/session/memory.ts

@@ -424,6 +424,28 @@ export class InMemorySessionStore implements SessionStore {
 		return id
 	}
 
+	async replaceMessages(
+		sessionId: SessionId,
+		messages: readonly Message[],
+		tenantId: TenantId,
+	): Promise<void> {
+		const record = this.sessions.get(sessionId)
+		if (!record) throw new Error(`Session ${sessionId} not found`)
+		this.assertTenant(record.tenantId, tenantId, `session(${sessionId})`)
+
+		const at = new Date()
+		this.messages.set(
+			sessionId,
+			messages.map((message) => ({
+				id: generateMessageId(),
+				sessionId,
+				tenantId,
+				message,
+				at,
+			})),
+		)
+	}
+
 	async loadMessages(sessionId: SessionId, tenantId: TenantId): Promise<readonly Message[]> {
 		const record = this.sessions.get(sessionId)
 		if (!record) return []

package/src/store/topic/memory.ts

@@ -4,8 +4,7 @@
  *
  * Mirrors the write-time CAS contract of the disk store: every
  * `updateTopic` compares the supplied `ownerVersion` against the persisted
- * copy and rejects with `StaleThreadError` on mismatch (class name
- * unchanged this release — see NZ-TOPIC-01 risks). Convention #17:
+ * copy and rejects with `StaleTopicError` on mismatch. Convention #17:
  * cross-tenant access throws `TenantIsolationError` with no fallback.
  *
  * NZ-TOPIC-01 renamed this from `InMemoryThreadStore` (moved from
@@ -15,7 +14,7 @@
  * `InMemoryTopicStore` now.
  */
 
-import { StaleThreadError, TenantIsolationError } from '../../session/errors.js'
+import { StaleTopicError, TenantIsolationError } from '../../session/errors.js'
 import type { TenantId } from '../../types/ids/index.js'
 import type { ProjectId, TopicId } from '../../types/session/ids.js'
 import type { Topic } from '../../types/topic/entity.js'
@@ -70,8 +69,8 @@ export class InMemoryTopicStore implements TopicStore {
 		// Any drift means another writer already advanced the record; the caller
 		// must re-read + re-apply + retry.
 		if (topic.ownerVersion !== existing.topic.ownerVersion) {
-			throw new StaleThreadError({
-				threadId: topic.id,
+			throw new StaleTopicError({
+				topicId: topic.id,
 				expectedVersion: topic.ownerVersion,
 				actualVersion: existing.topic.ownerVersion,
 			})

package/src/store/topic/objective.ts

@@ -1,6 +1,6 @@
-import { mkdir } from 'node:fs/promises'
 import { join } from 'node:path'
 
+import { TenantIsolationError } from '../../session/errors.js'
 import type { TenantId, TopicId } from '../../types/ids/index.js'
 import {
 	type ObjectivePhase,
@@ -8,7 +8,13 @@ import {
 	StaleObjectiveError,
 	type TopicObjective,
 } from '../../types/topic/objective.js'
-import { DiskRecordStore } from '../kv/record-store.js'
+import {
+	DiskRevisionRecordStore,
+	type RevisionMutation,
+	type RevisionedRecordLocation,
+	legacyRevisionFileSegment,
+	revisionFileSegment,
+} from '../kv/revision-record-store.js'
 import { defineSchema } from '../schema.js'
 
 /**
@@ -22,8 +28,16 @@ import { defineSchema } from '../schema.js'
  * have nothing to say to each other.
  */
 
-const SCHEMA = defineSchema({ kind: 'topic-objective', current: 1, migrations: {} })
-const records = new DiskRecordStore<TopicObjective>(SCHEMA)
+const SCHEMA = defineSchema({
+	kind: 'topic-objective',
+	current: 1,
+	migrations: {},
+})
+const revisionRecords = new DiskRevisionRecordStore<TopicObjective>(
+	SCHEMA,
+	'topic objective store',
+	(record) => record.revision,
+)
 
 export interface CreateObjectiveParams {
 	readonly id: string
@@ -109,6 +123,31 @@ function missing(id: string): Error {
 	return new Error(`No objective ${id}.`)
 }
 
+function assertTenant(record: TopicObjective, tenantId: TenantId): void {
+	if (record.tenantId !== tenantId) {
+		throw new TenantIsolationError({
+			requested: tenantId,
+			resource: `objective(${record.id})`,
+		})
+	}
+}
+
+interface ObjectiveBackend {
+	readonly read: (id: string) => Promise<TopicObjective | null>
+	readonly transact: <R>(
+		id: string,
+		mutate: (current: TopicObjective | null) => RevisionMutation<TopicObjective, R>,
+	) => Promise<R>
+}
+
+const objectiveBackends = new WeakMap<object, ObjectiveBackend>()
+
+function backendFor(store: object): ObjectiveBackend {
+	const backend = objectiveBackends.get(store)
+	if (!backend) throw new Error('Objective store backend was not initialized.')
+	return backend
+}
+
 /**
  * The shared write logic.
  *
@@ -121,35 +160,49 @@ function missing(id: string): Error {
 abstract class ObjectiveStoreBase implements TopicObjectiveStore {
 	protected constructor(protected readonly now: () => number) {}
 
-	abstract getObjective(id: string, tenantId: TenantId): Promise<TopicObjective | null>
+	/**
+	 * Commit seam for the shared domain transitions. Shipped implementations
+	 * enforce an exact next revision here; keeping every transition on this
+	 * path also preserves a subclass observer without letting it replace the
+	 * domain rules above.
+	 */
 	protected abstract put(record: TopicObjective): Promise<void>
 
+	async getObjective(id: string, tenantId: TenantId): Promise<TopicObjective | null> {
+		const found = await backendFor(this).read(id)
+		// Enumeration-style reads deliberately hide another tenant's record.
+		// Mutations reject instead: treating it as absent would overwrite it.
+		return found && found.tenantId === tenantId ? found : null
+	}
+
 	async createObjective(
 		params: CreateObjectiveParams,
 		tenantId: TenantId,
 	): Promise<TopicObjective> {
-		if (await this.getObjective(params.id, tenantId)) {
-			throw new ObjectiveExistsError({ id: params.id })
-		}
-		if (params.maxRounds < 1) {
+		if (!Number.isSafeInteger(params.maxRounds) || params.maxRounds < 1) {
 			// A cap of zero is an objective that can never run. Accepting it
 			// would produce a record that blocks on its own first round, which
 			// reads as a runaway that was stopped rather than a caller mistake.
-			throw new Error(`maxRounds must be at least 1, got ${params.maxRounds}.`)
+			throw new Error(`maxRounds must be a positive safe integer, got ${params.maxRounds}.`)
 		}
-		const record: TopicObjective = {
-			id: params.id,
-			topicId: params.topicId,
-			tenantId,
-			revision: 1,
-			objective: params.objective,
-			phase: 'active',
-			maxRounds: params.maxRounds,
-			roundsStarted: 0,
-			updatedAt: this.now(),
-		}
-		await this.put(record)
-		return record
+		return await backendFor(this).transact(params.id, (existing) => {
+			if (existing) {
+				assertTenant(existing, tenantId)
+				throw new ObjectiveExistsError({ id: params.id })
+			}
+			const record: TopicObjective = {
+				id: params.id,
+				topicId: params.topicId,
+				tenantId,
+				revision: 1,
+				objective: params.objective,
+				phase: 'active',
+				maxRounds: params.maxRounds,
+				roundsStarted: 0,
+				updatedAt: this.now(),
+			}
+			return { record, result: record }
+		})
 	}
 
 	async beginRound(
@@ -157,36 +210,46 @@ abstract class ObjectiveStoreBase implements TopicObjectiveStore {
 		tenantId: TenantId,
 		opts: { revision: number },
 	): Promise<TopicObjective> {
-		const existing = await this.getObjective(id, tenantId)
-		if (!existing) throw missing(id)
-		assertFresh(id, existing, opts.revision)
-		if (existing.phase !== 'active') {
-			throw new Error(`Objective ${id} is ${existing.phase}, not active.`)
-		}
-		if (existing.roundsStarted >= existing.maxRounds) {
-			// Blocked BEFORE the throw. A caller that swallows this error, or a
-			// process that dies on it, must not leave a record that still says
-			// `active` — the next reader would start the round this refused.
-			await this.put({
+		const outcome = await backendFor(this).transact<{
+			record: TopicObjective
+			exhausted: boolean
+		}>(id, (existing) => {
+			if (!existing) throw missing(id)
+			assertTenant(existing, tenantId)
+			assertFresh(id, existing, opts.revision)
+			if (existing.phase !== 'active') {
+				throw new Error(`Objective ${id} is ${existing.phase}, not active.`)
+			}
+			if (existing.roundsStarted >= existing.maxRounds) {
+				const record: TopicObjective = {
+					...existing,
+					revision: existing.revision + 1,
+					phase: 'blocked',
+					blockedReason: {
+						code: 'round_cap',
+						message: `Reached the ${existing.maxRounds}-round cap.`,
+					},
+					updatedAt: this.now(),
+				}
+				return { record, result: { record, exhausted: true as const } }
+			}
+			const record: TopicObjective = {
 				...existing,
 				revision: existing.revision + 1,
-				phase: 'blocked',
-				blockedReason: {
-					code: 'round_cap',
-					message: `Reached the ${existing.maxRounds}-round cap.`,
-				},
+				roundsStarted: existing.roundsStarted + 1,
 				updatedAt: this.now(),
+			}
+			return { record, result: { record, exhausted: false as const } }
+		})
+		if (outcome.exhausted) {
+			// Blocked BEFORE the throw. The committed result is what a reader sees
+			// even if this exception is swallowed or the caller exits on it.
+			throw new ObjectiveExhaustedError({
+				id,
+				maxRounds: outcome.record.maxRounds,
 			})
-			throw new ObjectiveExhaustedError({ id, maxRounds: existing.maxRounds })
-		}
-		const record: TopicObjective = {
-			...existing,
-			revision: existing.revision + 1,
-			roundsStarted: existing.roundsStarted + 1,
-			updatedAt: this.now(),
 		}
-		await this.put(record)
-		return record
+		return outcome.record
 	}
 
 	async settleRound(
@@ -195,19 +258,20 @@ abstract class ObjectiveStoreBase implements TopicObjectiveStore {
 		verdict: ObjectiveRoundVerdict,
 		opts: { revision: number },
 	): Promise<TopicObjective> {
-		const existing = await this.getObjective(id, tenantId)
-		if (!existing) throw missing(id)
-		assertFresh(id, existing, opts.revision)
-		const record: TopicObjective = {
-			...existing,
-			revision: existing.revision + 1,
-			phase: verdict.phase ?? existing.phase,
-			...(verdict.blockedReason ? { blockedReason: verdict.blockedReason } : {}),
-			...(verdict.runId ? { lastRunId: verdict.runId } : {}),
-			updatedAt: this.now(),
-		}
-		await this.put(record)
-		return record
+		return await backendFor(this).transact(id, (existing) => {
+			if (!existing) throw missing(id)
+			assertTenant(existing, tenantId)
+			assertFresh(id, existing, opts.revision)
+			const record: TopicObjective = {
+				...existing,
+				revision: existing.revision + 1,
+				phase: verdict.phase ?? existing.phase,
+				...(verdict.blockedReason ? { blockedReason: verdict.blockedReason } : {}),
+				...(verdict.runId ? { lastRunId: verdict.runId } : {}),
+				updatedAt: this.now(),
+			}
+			return { record, result: record }
+		})
 	}
 
 	async setPhase(
@@ -216,29 +280,30 @@ abstract class ObjectiveStoreBase implements TopicObjectiveStore {
 		phase: ObjectivePhase,
 		opts: { revision: number },
 	): Promise<TopicObjective> {
-		const existing = await this.getObjective(id, tenantId)
-		if (!existing) throw missing(id)
-		assertFresh(id, existing, opts.revision)
-		if (existing.phase === 'complete' && phase !== 'complete') {
-			// One-way. Reopening a finished objective by writing a phase would
-			// let a stale caller restart work somebody already signed off, and
-			// the round counter it would run against is the one already spent.
-			throw new Error(`Objective ${id} is complete; it cannot be moved to ${phase}.`)
-		}
-		// A move off `blocked` drops the reason. Carrying it would describe a
-		// running objective as blocked by something it no longer is, and that
-		// stale sentence is what an operator reads to decide whether to
-		// intervene.
-		const { blockedReason, ...rest } = existing
-		const record: TopicObjective = {
-			...rest,
-			revision: existing.revision + 1,
-			phase,
-			...(phase === 'blocked' && blockedReason ? { blockedReason } : {}),
-			updatedAt: this.now(),
-		}
-		await this.put(record)
-		return record
+		return await backendFor(this).transact(id, (existing) => {
+			if (!existing) throw missing(id)
+			assertTenant(existing, tenantId)
+			assertFresh(id, existing, opts.revision)
+			if (existing.phase === 'complete' && phase !== 'complete') {
+				// One-way. Reopening a finished objective by writing a phase would
+				// let a stale caller restart work somebody already signed off, and
+				// the round counter it would run against is the one already spent.
+				throw new Error(`Objective ${id} is complete; it cannot be moved to ${phase}.`)
+			}
+			// A move off `blocked` drops the reason. Carrying it would describe a
+			// running objective as blocked by something it no longer is, and that
+			// stale sentence is what an operator reads to decide whether to
+			// intervene.
+			const { blockedReason, ...rest } = existing
+			const record: TopicObjective = {
+				...rest,
+				revision: existing.revision + 1,
+				phase,
+				...(phase === 'blocked' && blockedReason ? { blockedReason } : {}),
+				updatedAt: this.now(),
+			}
+			return { record, result: record }
+		})
 	}
 }
 
@@ -247,16 +312,34 @@ export class InMemoryTopicObjectiveStore extends ObjectiveStoreBase {
 
 	constructor(now: () => number = Date.now) {
 		super(now)
-	}
-
-	async getObjective(id: string, tenantId: TenantId): Promise<TopicObjective | null> {
-		const found = this.objectives.get(id)
-		// Another tenant's record reads as absent rather than as an error, for
-		// the reason the project listing gives: refusing confirms it is there.
-		return found && found.tenantId === tenantId ? found : null
+		objectiveBackends.set(this, {
+			read: async (id) => this.objectives.get(id) ?? null,
+			transact: async <R>(
+				id: string,
+				mutate: (current: TopicObjective | null) => RevisionMutation<TopicObjective, R>,
+			): Promise<R> => {
+				// Deliberately no await: read, domain checks and publish are one JS
+				// turn. `put` executes its map check/set before its returned promise
+				// settles; awaiting an async get before this point would let two callers
+				// capture the same revision.
+				const proposal = mutate(this.objectives.get(id) ?? null)
+				await this.put(proposal.record)
+				return proposal.result
+			},
+		})
 	}
 
 	protected async put(record: TopicObjective): Promise<void> {
+		const existing = this.objectives.get(record.id)
+		if (existing) assertTenant(existing, record.tenantId)
+		const expected = (existing?.revision ?? 0) + 1
+		if (record.revision !== expected) {
+			throw new StaleObjectiveError({
+				id: record.id,
+				expectedRevision: record.revision - 1,
+				actualRevision: existing?.revision ?? 0,
+			})
+		}
 		this.objectives.set(record.id, record)
 	}
 }
@@ -272,19 +355,51 @@ export class DiskTopicObjectiveStore extends ObjectiveStoreBase {
 		now: () => number = Date.now,
 	) {
 		super(now)
+		objectiveBackends.set(this, {
+			read: async (id) => await revisionRecords.read(this.location(id)),
+			transact: async <R>(
+				id: string,
+				mutate: (current: TopicObjective | null) => RevisionMutation<TopicObjective, R>,
+			): Promise<R> => {
+				const location = this.location(id)
+				const proposal = mutate(await revisionRecords.read(location))
+				try {
+					await this.put(proposal.record)
+				} catch (err) {
+					if (err instanceof StaleObjectiveError) {
+						// Re-run only the domain guard against the durable winner. Creation
+						// must report ObjectiveExistsError, while an ordinary mutation keeps
+						// the stale error and its actual revision.
+						mutate(await revisionRecords.read(location))
+					}
+					throw err
+				}
+				return proposal.result
+			},
+		})
 	}
 
-	private path(id: string): string {
-		return join(this.config.rootDir, 'objectives', `${id}.json`)
-	}
-
-	async getObjective(id: string, tenantId: TenantId): Promise<TopicObjective | null> {
-		const found = await records.read(this.path(id))
-		return found && found.tenantId === tenantId ? found : null
+	private location(id: string): RevisionedRecordLocation {
+		const root = join(this.config.rootDir, 'objectives')
+		const segment = revisionFileSegment(id)
+		return {
+			legacyPath: join(root, `${legacyRevisionFileSegment(id)}.json`),
+			revisionsDir: join(root, '.revisions', segment),
+		}
 	}
 
 	protected async put(record: TopicObjective): Promise<void> {
-		await mkdir(join(this.config.rootDir, 'objectives'), { recursive: true })
-		await records.write(this.path(record.id), record)
+		await revisionRecords.transact(this.location(record.id), (existing) => {
+			if (existing) assertTenant(existing, record.tenantId)
+			const actual = existing?.revision ?? 0
+			if (record.revision !== actual + 1) {
+				throw new StaleObjectiveError({
+					id: record.id,
+					expectedRevision: record.revision - 1,
+					actualRevision: actual,
+				})
+			}
+			return { record, result: undefined }
+		})
 	}
 }