@namzu/sdk 27.0.0 → 28.0.0

package/src/store/feedback/conformance.ts

@@ -0,0 +1,193 @@
+import type { MessageId, RunId } from '../../types/ids/index.js'
+import type { MessageFeedbackStore } from './types.js'
+
+/**
+ * The feedback-store contract, as a suite either implementation runs.
+ *
+ * Two built-in stores that agree by inspection is not the same as two that
+ * agree. The checkpoint stores diverged at exactly their enforcement point
+ * once already — the in-memory one accepted a write the disk one refused,
+ * and the class documented as "the reference a host reads" was the one
+ * carrying the defect. Reading a reference cannot catch that; running it
+ * can.
+ *
+ * The rules here are the ones no type states: that a stale write is refused
+ * and changes nothing, that exactly one of two racing writers wins, that a
+ * rating aimed at a message the run never produced is refused, and that a
+ * listing answers for the run it was asked about and no other.
+ *
+ * Takes its runner as an argument for the same reason the checkpoint suite
+ * does: this file imports no test framework, so the package gains no test
+ * dependency from shipping it, and a caller can pass RECORDING functions
+ * and run the whole contract as ordinary code.
+ */
+
+export interface FeedbackConformanceOptions {
+	readonly describe: (name: string, body: () => void) => void
+	readonly it: (name: string, body: () => Promise<void> | void) => void
+	readonly expect: (actual: unknown) => {
+		toBe(expected: unknown): void
+		toEqual(expected: unknown): void
+		toHaveLength(n: number): void
+	}
+	readonly label: string
+	/** A fresh store, plus the ids its message check will accept. */
+	readonly makeStore: () => Promise<{
+		store: MessageFeedbackStore
+		runId: RunId
+		knownMessageId: MessageId
+		/** Syntactically valid and never produced by `runId`. */
+		unknownMessageId: MessageId
+		otherRunId: RunId
+		otherKnownMessageId: MessageId
+	}>
+}
+
+export function defineMessageFeedbackConformance(options: FeedbackConformanceOptions): void {
+	const { describe, it, expect, makeStore } = options
+
+	describe(`message feedback contract: ${options.label}`, () => {
+		it('starts a record at version 1', async () => {
+			const { store, runId, knownMessageId } = await makeStore()
+
+			const record = await store.putMessageFeedback({
+				runId,
+				messageId: knownMessageId,
+				rating: 'good',
+				expectedVersion: 0,
+			})
+
+			expect(record.ownerVersion).toBe(1)
+			expect(record.rating).toBe('good')
+		})
+
+		it('refuses a stale write and leaves the record untouched', async () => {
+			// Re-read after the throw, deliberately. A store that threw AFTER
+			// writing would satisfy "it throws" and have already lost the
+			// first rater's answer.
+			const { store, runId, knownMessageId } = await makeStore()
+			await store.putMessageFeedback({
+				runId,
+				messageId: knownMessageId,
+				rating: 'good',
+				expectedVersion: 0,
+			})
+
+			let threw = false
+			try {
+				await store.putMessageFeedback({
+					runId,
+					messageId: knownMessageId,
+					rating: 'bad',
+					expectedVersion: 0,
+				})
+			} catch (err) {
+				threw = true
+				expect((err as { details?: { expectedVersion: number } }).details?.expectedVersion).toBe(0)
+				expect((err as { details?: { actualVersion: number } }).details?.actualVersion).toBe(1)
+			}
+
+			expect(threw).toBe(true)
+			const listed = await store.listMessageFeedback({ runId })
+			expect(listed).toHaveLength(1)
+			expect(listed[0]?.rating).toBe('good')
+			expect(listed[0]?.ownerVersion).toBe(1)
+		})
+
+		it('lets exactly one of two racing writers through', async () => {
+			// Both start from version 0, which is what two raters who each
+			// read "no feedback yet" actually hold. Under last-write-wins both
+			// succeed and the surviving version is 1 by coincidence rather
+			// than by exclusion, so the version is asserted numerically.
+			const { store, runId, knownMessageId } = await makeStore()
+			const attempts = ['good', 'bad'].map((rating) =>
+				store
+					.putMessageFeedback({
+						runId,
+						messageId: knownMessageId,
+						rating: rating as 'good' | 'bad',
+						expectedVersion: 0,
+					})
+					.then(
+						() => 'ok' as const,
+						() => 'refused' as const,
+					),
+			)
+			const outcomes = await Promise.all(attempts)
+
+			expect(outcomes.filter((o) => o === 'ok')).toHaveLength(1)
+			expect(outcomes.filter((o) => o === 'refused')).toHaveLength(1)
+			const listed = await store.listMessageFeedback({ runId })
+			expect(listed).toHaveLength(1)
+			expect(listed[0]?.ownerVersion).toBe(1)
+		})
+
+		it('advances the version on a correct update', async () => {
+			const { store, runId, knownMessageId } = await makeStore()
+			await store.putMessageFeedback({
+				runId,
+				messageId: knownMessageId,
+				rating: 'good',
+				expectedVersion: 0,
+			})
+
+			const second = await store.putMessageFeedback({
+				runId,
+				messageId: knownMessageId,
+				rating: 'bad',
+				note: 'changed my mind',
+				expectedVersion: 1,
+			})
+
+			expect(second.ownerVersion).toBe(2)
+			expect(second.rating).toBe('bad')
+			expect(second.note).toBe('changed my mind')
+		})
+
+		it('refuses a message the run never produced, and writes nothing', async () => {
+			const { store, runId, unknownMessageId } = await makeStore()
+
+			let threw = false
+			try {
+				await store.putMessageFeedback({
+					runId,
+					messageId: unknownMessageId,
+					rating: 'good',
+					expectedVersion: 0,
+				})
+			} catch {
+				threw = true
+			}
+
+			expect(threw).toBe(true)
+			expect(await store.listMessageFeedback({ runId })).toHaveLength(0)
+		})
+
+		it('answers for the run it was asked about and no other', async () => {
+			const { store, runId, knownMessageId, otherRunId, otherKnownMessageId } = await makeStore()
+			await store.putMessageFeedback({
+				runId,
+				messageId: knownMessageId,
+				rating: 'good',
+				expectedVersion: 0,
+			})
+			await store.putMessageFeedback({
+				runId: otherRunId,
+				messageId: otherKnownMessageId,
+				rating: 'bad',
+				expectedVersion: 0,
+			})
+
+			const mine = await store.listMessageFeedback({ runId })
+
+			expect(mine).toHaveLength(1)
+			expect(mine[0]?.messageId).toBe(knownMessageId)
+		})
+
+		it('lists nothing for a run with no feedback', async () => {
+			const { store, otherRunId } = await makeStore()
+
+			expect(await store.listMessageFeedback({ runId: otherRunId })).toHaveLength(0)
+		})
+	})
+}

package/src/store/feedback/disk.ts

@@ -0,0 +1,184 @@
+import { mkdir, writeFile } from 'node:fs/promises'
+import { join } from 'node:path'
+
+import type { MessageId, RunId } from '../../types/ids/index.js'
+import { DiskRecordStore } from '../kv/record-store.js'
+import { readRunEventsIn } from '../run/disk.js'
+import { defineSchema, stamp } from '../schema.js'
+import type { MessageExistenceCheck } from './memory.js'
+import {
+	type MessageFeedback,
+	type MessageFeedbackStore,
+	type PutMessageFeedbackInput,
+	StaleFeedbackError,
+	UnknownMessageError,
+} from './types.js'
+
+const SCHEMA = defineSchema({ kind: 'feedback-store', current: 1, migrations: {} })
+
+const records = new DiskRecordStore<MessageFeedback>(SCHEMA)
+
+/**
+ * Feedback on disk, one file per rated message.
+ *
+ * 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.
+ */
+export interface DiskMessageFeedbackStoreConfig {
+	/** Where feedback lives. Sibling of the run tree, not inside it. */
+	readonly rootDir: string
+	/**
+	 * Where run transcripts live, for validating that a rated message exists.
+	 *
+	 * Separate from `rootDir` because feedback outlives a run directory a
+	 * host may prune, and because a store told to validate against a tree it
+	 * cannot see should say so rather than accept everything.
+	 */
+	readonly runsDir?: string
+}
+
+/** Filesystem-safe file name for one rated message. */
+function fileName(messageId: MessageId): string {
+	// Message ids are `msg_` + an alphabet with no separators, so this is a
+	// pass-through today. Written as a function anyway: the day an id gains
+	// a `/` is the day this silently starts writing outside its directory.
+	return `${messageId.replace(/[^a-zA-Z0-9_-]/g, '_')}.json`
+}
+
+/**
+ * Does this run's transcript mention this message?
+ *
+ * Reads the run's own event log, which is the only record of what a run
+ * actually produced. A `messageId` that appears nowhere in it is either a
+ * typo or a fabrication, and both are worth refusing — a feedback row
+ * pointing at a message nobody can find is unreviewable and
+ * indistinguishable from a real one.
+ */
+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)
+	}
+}
+
+export class DiskMessageFeedbackStore implements MessageFeedbackStore {
+	private readonly rootDir: string
+	private readonly messageExists: MessageExistenceCheck
+
+	constructor(
+		config: DiskMessageFeedbackStoreConfig,
+		messageExists?: MessageExistenceCheck,
+		private readonly now: () => number = Date.now,
+	) {
+		this.rootDir = config.rootDir
+		this.messageExists =
+			messageExists ??
+			// No `runsDir` means nothing to validate against. Accepting
+			// everything would be the quiet degradation this repo's rule
+			// forbids, so a store built that way refuses every write and names
+			// the missing configuration.
+			(config.runsDir
+				? runEventMessageCheck(config.runsDir)
+				: async (runId, messageId) => {
+						throw new UnknownMessageError({ runId, messageId })
+					})
+	}
+
+	private runDir(runId: RunId): string {
+		return join(this.rootDir, 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 })
+		}
+
+		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,
+			})
+		}
+
+		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,
+		}
+
+		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)
+				throw new StaleFeedbackError({
+					runId: input.runId,
+					messageId: input.messageId,
+					expectedVersion: input.expectedVersion,
+					actualVersion: winner?.ownerVersion ?? 1,
+				})
+			}
+			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
+	}
+
+	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) {
+			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)
+		}
+		return out
+	}
+}

package/src/store/feedback/index.ts

@@ -0,0 +1,13 @@
+export { defineMessageFeedbackConformance } from './conformance.js'
+export type { FeedbackConformanceOptions } from './conformance.js'
+export { DiskMessageFeedbackStore, runEventMessageCheck } from './disk.js'
+export type { DiskMessageFeedbackStoreConfig } from './disk.js'
+export { acceptAnyMessage, InMemoryMessageFeedbackStore } from './memory.js'
+export type { MessageExistenceCheck } from './memory.js'
+export { StaleFeedbackError, UnknownMessageError } from './types.js'
+export type {
+	FeedbackRating,
+	MessageFeedback,
+	MessageFeedbackStore,
+	PutMessageFeedbackInput,
+} from './types.js'

package/src/store/feedback/types.ts

@@ -0,0 +1,107 @@
+import type { MessageId, RunId } from '../../types/ids/index.js'
+
+/**
+ * Was that answer any good — recorded per message, durably.
+ *
+ * Nothing in this tree stored a per-message judgment, and every ingredient
+ * for one already existed: `MessageId` is a branded type, run events carry
+ * it, and the versioned-store idiom with compare-and-set is established in
+ * three neighbouring stores. So every consumer — the CLI, a gateway, a
+ * future UI — had to invent its own side table to answer the most basic
+ * question there is, which is also the input to session review, support
+ * triage and eval collection.
+ */
+
+/**
+ * Two values, closed.
+ *
+ * Not a number, and not an open string. A 1–5 scale invites a mean nobody
+ * can interpret across raters, and an open string turns every consumer into
+ * a parser of somebody else's vocabulary. Widening this later is then a
+ * deliberate `major` with a migration, rather than the accident that a
+ * `number` would have made inevitable.
+ */
+export type FeedbackRating = 'good' | 'bad'
+
+export interface MessageFeedback {
+	readonly runId: RunId
+	readonly messageId: MessageId
+	readonly rating: FeedbackRating
+	/** Whatever the rater wanted to say. Absent is different from empty. */
+	readonly note?: string
+	/**
+	 * Compare-and-set counter, starting at 1 for a record's first write.
+	 *
+	 * The same mechanism the topic store uses, and for the same reason: two
+	 * writers racing on one record must not have the second silently
+	 * overwrite the first. A rating is exactly the kind of value where
+	 * last-write-wins loses information nobody notices is gone.
+	 */
+	readonly ownerVersion: number
+	readonly createdAt: number
+	readonly updatedAt: number
+}
+
+export interface PutMessageFeedbackInput {
+	readonly runId: RunId
+	readonly messageId: MessageId
+	readonly rating: FeedbackRating
+	readonly note?: string
+	/**
+	 * The version the caller believes is current — `0` for a first write.
+	 *
+	 * Required rather than optional. An optional expected version reads as
+	 * "I do not care", and a caller who does not care is the caller whose
+	 * write silently discards somebody else's.
+	 */
+	readonly expectedVersion: number
+}
+
+export interface MessageFeedbackStore {
+	putMessageFeedback(input: PutMessageFeedbackInput): Promise<MessageFeedback>
+	listMessageFeedback(query: { readonly runId: RunId }): Promise<readonly MessageFeedback[]>
+}
+
+/** A write whose `expectedVersion` no longer matches what is stored. */
+export class StaleFeedbackError extends Error {
+	readonly details: {
+		runId: RunId
+		messageId: MessageId
+		expectedVersion: number
+		actualVersion: number
+	}
+
+	constructor(details: {
+		runId: RunId
+		messageId: MessageId
+		expectedVersion: number
+		actualVersion: number
+	}) {
+		super(
+			`Stale feedback for ${details.messageId} in ${details.runId}: expected ownerVersion=${details.expectedVersion}, actual=${details.actualVersion}`,
+		)
+		this.name = 'StaleFeedbackError'
+		this.details = details
+	}
+}
+
+/**
+ * A rating aimed at a message the named run never produced.
+ *
+ * Refused rather than stored, per `refuse-do-not-degrade`. A feedback table
+ * is read later to answer "which answers were bad" — a row pointing at a
+ * message that does not exist cannot be reviewed, cannot be traced back to
+ * what was said, and is indistinguishable from a real one. Storing it costs
+ * nothing at write time and poisons every read after it.
+ */
+export class UnknownMessageError extends Error {
+	readonly details: { runId: RunId; messageId: MessageId }
+
+	constructor(details: { runId: RunId; messageId: MessageId }) {
+		super(
+			`No message ${details.messageId} in run ${details.runId}: feedback must name a message the run actually produced.`,
+		)
+		this.name = 'UnknownMessageError'
+		this.details = details
+	}
+}

package/src/store/index.ts

@@ -38,3 +38,8 @@ export { InMemoryMemoryIndex } from './memory/index.js'
 export { InMemoryMemoryStore } from './memory/memory.js'
 export { DiskMemoryStore } from './memory/disk.js'
 export type { DiskMemoryStoreConfig } from './memory/disk.js'
+
+// Was that answer any good — recorded per message, durably, with
+// compare-and-set. Every consumer used to invent its own side table for the
+// most basic feedback loop there is.
+export * from './feedback/index.js'

package/src/store/kv/record-store.ts

@@ -0,0 +1,91 @@
+import { readFile, readdir } from 'node:fs/promises'
+import { join } from 'node:path'
+
+import { atomicWriteFile } from '../../utils/atomic-write.js'
+import { type SchemaDefinition, migrate, stamp } from '../schema.js'
+
+/**
+ * Read a record, write a record, walk a directory of them — once.
+ *
+ * Four disk stores each carried a private copy of the same twenty lines:
+ * a `readFile` + `JSON.parse` + `migrate` with ENOENT collapsed to null, an
+ * `atomicWriteFile` of `stamp`ed JSON, and a `readdir` filtered by prefix.
+ * Every property fixed in one of them had to be remembered into the other
+ * three, and the properties are not obvious ones — that a missing file is
+ * an empty read rather than an error, that a record from a NEWER build is
+ * refused rather than read partially and written back with the difference
+ * gone, that a listing needs a stable order.
+ *
+ * Internal to the package. It is a shape four call sites already agree on,
+ * not a contract offered to hosts, and exporting it would freeze an
+ * argument list nobody outside has asked for.
+ */
+export class DiskRecordStore<T> {
+	constructor(private readonly schema: SchemaDefinition) {}
+
+	/**
+	 * `null` for a file that is not there — the convention every copy of
+	 * this already used, and the one worth stating once. A store asking
+	 * "does this exist" through an exception has to distinguish ENOENT from
+	 * a real IO failure at every call site, and the copies that got it
+	 * right did so independently.
+	 */
+	async read<U = T>(path: string): Promise<U | null> {
+		try {
+			const raw = await readFile(path, 'utf-8')
+			// Through the schema, never a bare cast: a record from an older
+			// build is brought forward, and one from a NEWER build is refused
+			// rather than read partially and written back with the difference
+			// silently gone.
+			return migrate<U>(this.schema, JSON.parse(raw))
+		} catch (err) {
+			if ((err as NodeJS.ErrnoException).code === 'ENOENT') return null
+			throw err
+		}
+	}
+
+	/**
+	 * Stamped with the current schema version, written atomically.
+	 *
+	 * `U` defaults to the store's own `T`, and widening it is what lets one
+	 * schema cover a tree that holds several record shapes — the session
+	 * store keeps projects, sessions, sub-sessions and a path index under
+	 * one `session-store` schema, and they version together on purpose.
+	 */
+	async write<U = T>(path: string, value: U): Promise<void> {
+		await atomicWriteFile(path, `${JSON.stringify(stamp(this.schema, value), null, 2)}\n`)
+	}
+
+	/**
+	 * Entry names under `dir`, prefix-filtered and SORTED.
+	 *
+	 * The sort is not decoration. `readdir` order is filesystem-dependent,
+	 * so a listing that skipped it would return records in an order that
+	 * differs between a developer's machine and a container — which turns a
+	 * pagination bug into one that reproduces nowhere.
+	 *
+	 * A missing directory lists as empty, for the same reason a missing
+	 * file reads as null: "nothing has been written yet" is an ordinary
+	 * state of a store, not a failure.
+	 */
+	async scanNames(dir: string, prefix: string): Promise<string[]> {
+		try {
+			const entries = await readdir(dir)
+			return entries.filter((name) => name.startsWith(prefix)).sort()
+		} catch (err) {
+			if ((err as NodeJS.ErrnoException).code === 'ENOENT') return []
+			throw err
+		}
+	}
+
+	/** Every record under `dir` whose name starts with `prefix`, in name order. */
+	async *scan(dir: string, prefix: string, file = 'record.json'): AsyncIterable<T> {
+		for (const name of await this.scanNames(dir, prefix)) {
+			const record = await this.read(join(dir, name, file))
+			// A directory whose record is absent or unreadable is skipped, not
+			// fatal: a half-written entry from a crashed writer must not make
+			// the whole listing unavailable.
+			if (record !== null) yield record
+		}
+	}
+}