@namzu/sdk 30.2.0 → 31.1.0

package/src/store/feedback/disk.ts

@@ -1,10 +1,18 @@
-import { mkdir, writeFile } from 'node:fs/promises'
 import { join } from 'node:path'
 
+import { NamzuError } from '../../types/errors/index.js'
 import type { MessageId, RunId } from '../../types/ids/index.js'
+import { asMessageId, asRunId } from '../../utils/id.js'
 import { DiskRecordStore } from '../kv/record-store.js'
+import {
+	DiskRevisionRecordStore,
+	type RevisionedRecordLocation,
+	decodeRevisionFileSegment,
+	legacyRevisionFileSegment,
+	revisionFileSegment,
+} from '../kv/revision-record-store.js'
 import { readRunEventsIn } from '../run/disk.js'
-import { defineSchema, stamp } from '../schema.js'
+import { defineSchema } from '../schema.js'
 import type { MessageExistenceCheck } from './memory.js'
 import {
 	type MessageFeedback,
@@ -14,18 +22,26 @@ import {
 	UnknownMessageError,
 } from './types.js'
 
-const SCHEMA = defineSchema({ kind: 'feedback-store', current: 1, migrations: {} })
+const SCHEMA = defineSchema({
+	kind: 'feedback-store',
+	current: 1,
+	migrations: {},
+})
 
 const records = new DiskRecordStore<MessageFeedback>(SCHEMA)
+const revisionRecords = new DiskRevisionRecordStore<MessageFeedback>(
+	SCHEMA,
+	'message feedback store',
+	(record) => record.ownerVersion,
+)
 
 /**
- * Feedback on disk, one file per rated message.
+ * Feedback on disk, one immutable commit per accepted owner version.
  *
- * One file rather than one appended log per run, because a rating is a
- * RECORD — it is replaced, not accumulated — and compare-and-set on a
- * record is what stops two raters silently overwriting each other. An
- * append log would have to be replayed to answer "what is the rating now",
- * and two appends racing would both succeed.
+ * A rating is a RECORD — readers want its current value — but replacing one
+ * mutable file cannot make the preceding version comparison atomic. The
+ * revision directory elects exactly one writer for N+1; the former single
+ * file remains only a checked, best-effort compatibility projection.
  */
 export interface DiskMessageFeedbackStoreConfig {
 	/** Where feedback lives. Sibling of the run tree, not inside it. */
@@ -59,8 +75,10 @@ function fileName(messageId: MessageId): string {
  */
 export function runEventMessageCheck(runsDir: string): MessageExistenceCheck {
 	return async (runId: RunId, messageId: MessageId): Promise<boolean> => {
-		const events = await readRunEventsIn(join(runsDir, runId))
-		return events.some((event) => (event as { messageId?: string }).messageId === messageId)
+		const checkedRunId = asRunId(runId)
+		const checkedMessageId = asMessageId(messageId)
+		const events = await readRunEventsIn(join(runsDir, legacyRevisionFileSegment(checkedRunId)))
+		return events.some((event) => (event as { messageId?: string }).messageId === checkedMessageId)
 	}
 }
 
@@ -88,96 +106,124 @@ export class DiskMessageFeedbackStore implements MessageFeedbackStore {
 	}
 
 	private runDir(runId: RunId): string {
-		return join(this.rootDir, runId)
+		return join(this.rootDir, legacyRevisionFileSegment(asRunId(runId)))
 	}
 
-	async putMessageFeedback(input: PutMessageFeedbackInput): Promise<MessageFeedback> {
-		// Validated BEFORE the version check, so a rating aimed at a message
-		// that does not exist is refused for what it is rather than reported
-		// as a version conflict.
-		if (!(await this.messageExists(input.runId, input.messageId))) {
-			throw new UnknownMessageError({ runId: input.runId, messageId: input.messageId })
+	private revisionsDir(runId: RunId): string {
+		return join(this.runDir(runId), '.revisions')
+	}
+
+	private location(runId: RunId, messageId: MessageId): RevisionedRecordLocation {
+		const checkedMessageId = asMessageId(messageId)
+		const legacyName = fileName(checkedMessageId)
+		return {
+			legacyPath: join(this.runDir(runId), legacyName),
+			revisionsDir: join(this.revisionsDir(runId), revisionFileSegment(checkedMessageId)),
+			// The previous filename replacement is lossy for punctuation and
+			// separators. Read such a legacy path forward if it exists, but never
+			// publish a new projection that could overwrite another message's file.
+			publishLegacyProjection: legacyName === `${checkedMessageId}.json`,
 		}
+	}
 
-		const dir = this.runDir(input.runId)
-		const path = join(dir, fileName(input.messageId))
-		const existing = await records.read(path)
-		const actualVersion = existing?.ownerVersion ?? 0
-
-		if (input.expectedVersion !== actualVersion) {
-			throw new StaleFeedbackError({
-				runId: input.runId,
-				messageId: input.messageId,
-				expectedVersion: input.expectedVersion,
-				actualVersion,
+	private assertKey(record: MessageFeedback, runId: RunId, messageId: MessageId): void {
+		if (record.runId !== runId || record.messageId !== messageId) {
+			throw new NamzuError({
+				code: 'storage_error',
+				message: `Message feedback record key mismatch: expected ${runId}/${messageId}, found ${record.runId}/${record.messageId}. Repair or restore the record before retrying.`,
+				details: {
+					expectedRunId: runId,
+					expectedMessageId: messageId,
+					actualRunId: record.runId,
+					actualMessageId: record.messageId,
+				},
+				retryable: false,
 			})
 		}
+	}
+
+	async putMessageFeedback(input: PutMessageFeedbackInput): Promise<MessageFeedback> {
+		// Runtime ids cross a public JS boundary. The nominal TypeScript brand can
+		// still be asserted, so validate before either an injected callback or a
+		// filesystem path sees the values.
+		const runId = asRunId(input.runId)
+		const messageId = asMessageId(input.messageId)
+		const location = this.location(runId, messageId)
 
-		const timestamp = this.now()
-		const record: MessageFeedback = {
-			runId: input.runId,
-			messageId: input.messageId,
-			rating: input.rating,
-			...(input.note !== undefined ? { note: input.note } : {}),
-			ownerVersion: actualVersion + 1,
-			createdAt: existing?.createdAt ?? timestamp,
-			updatedAt: timestamp,
+		// Validated BEFORE the version check, so a rating aimed at a message
+		// that does not exist is refused for what it is rather than reported
+		// as a version conflict.
+		if (!(await this.messageExists(runId, messageId))) {
+			throw new UnknownMessageError({ runId, messageId })
 		}
 
-		await mkdir(dir, { recursive: true })
-
-		if (actualVersion === 0) {
-			// EXCLUSIVE create for the first write, and this is the whole
-			// compare-and-set on a filesystem. A read-then-write is not
-			// atomic: two raters who each read "no feedback yet" both see
-			// version 0, both pass the check above, and both write — the
-			// second silently discarding the first. `wx` makes the kernel
-			// the arbiter, so exactly one of them lands.
-			//
-			// Found by the conformance suite on the day it was written, with
-			// the in-memory store passing the same rule for free because
-			// nothing awaits between its read and its write.
-			try {
-				await writeFile(path, `${JSON.stringify(stamp(SCHEMA, record), null, 2)}\n`, {
-					encoding: 'utf-8',
-					flag: 'wx',
-				})
-			} catch (err) {
-				if ((err as NodeJS.ErrnoException).code !== 'EEXIST') throw err
-				// Somebody else got there between the read and here. Report
-				// what is actually stored now, rather than the 0 we read.
-				const winner = await records.read(path)
+		return await revisionRecords.transact(location, (existing) => {
+			if (existing) this.assertKey(existing, runId, messageId)
+			const actualVersion = existing?.ownerVersion ?? 0
+			if (input.expectedVersion !== actualVersion) {
 				throw new StaleFeedbackError({
-					runId: input.runId,
-					messageId: input.messageId,
+					runId,
+					messageId,
 					expectedVersion: input.expectedVersion,
-					actualVersion: winner?.ownerVersion ?? 1,
+					actualVersion,
 				})
 			}
-			return record
-		}
 
-		// An UPDATE is written through the ordinary atomic replace. Two
-		// concurrent updates from separate PROCESSES can still interleave
-		// between the read above and this write — the file already exists, so
-		// there is no exclusive-create to arbitrate, and feedback carries no
-		// fencing token the way a run claim does. Said plainly rather than
-		// implied by the `expectedVersion` parameter, which reads like a
-		// stronger guarantee than a filesystem gives without one.
-		await records.write(path, record)
-		return record
+			const timestamp = this.now()
+			const record: MessageFeedback = {
+				runId,
+				messageId,
+				rating: input.rating,
+				...(input.note !== undefined ? { note: input.note } : {}),
+				ownerVersion: actualVersion + 1,
+				createdAt: existing?.createdAt ?? timestamp,
+				updatedAt: timestamp,
+			}
+			return { record, result: record }
+		})
 	}
 
 	async listMessageFeedback(query: { runId: RunId }): Promise<readonly MessageFeedback[]> {
-		const dir = this.runDir(query.runId)
-		const names = await records.scanNames(dir, '')
-		const out: MessageFeedback[] = []
-		for (const name of names) {
+		const runId = asRunId(query.runId)
+		const dir = this.runDir(runId)
+		const ids = new Map<string, MessageId>()
+
+		// Old single-file records are still authoritative until their first
+		// current write. Read the body's id rather than attempting to reverse the
+		// old lossy filename mapping.
+		for (const name of await records.scanNames(dir, '')) {
 			if (!name.endsWith('.json')) continue
 			const record = await records.read(join(dir, name))
-			// A half-written entry from a crashed writer must not make the
-			// whole listing unavailable.
-			if (record !== null) out.push(record)
+			if (record === null) continue
+			const messageId = asMessageId(record.messageId)
+			this.assertKey(record, runId, messageId)
+			if (fileName(messageId) !== name) {
+				throw new NamzuError({
+					code: 'storage_error',
+					message: `Message feedback projection filename ${name} does not match record ${messageId}. Repair or restore the record before retrying.`,
+					details: { runId, messageId, name },
+					retryable: false,
+				})
+			}
+			ids.set(messageId, messageId)
+		}
+
+		// The immutable commit is the success boundary. Projection publication is
+		// deliberately best-effort, so enumerate canonical revision directories
+		// too or a successful first rating can disappear after a crash.
+		for (const segment of await records.scanNames(this.revisionsDir(runId), '')) {
+			const decoded = decodeRevisionFileSegment(segment)
+			if (decoded === null) continue
+			const messageId = asMessageId(decoded)
+			ids.set(messageId, messageId)
+		}
+
+		const out: MessageFeedback[] = []
+		for (const messageId of [...ids.values()].sort((a, b) => a.localeCompare(b))) {
+			const record = await revisionRecords.read(this.location(runId, messageId))
+			if (record === null) continue
+			this.assertKey(record, runId, messageId)
+			out.push(record)
 		}
 		return out
 	}