@namzu/sdk 42.0.2 → 44.0.0

package/src/store/feedback/conformance.ts

@@ -1,4 +1,4 @@
-import type { MessageId, RunId } from '../../types/ids/index.js'
+import type { MessageId, SessionId } from '../../types/ids/index.js'
 import type { MessageFeedbackStore } from './types.js'
 
 /**
@@ -13,8 +13,8 @@ import type { MessageFeedbackStore } from './types.js'
  *
  * 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.
+ * rating aimed at a message the session log does not hold is refused, and that
+ * a listing answers for the session 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
@@ -34,11 +34,11 @@ export interface FeedbackConformanceOptions {
 	/** A fresh store, plus the ids its message check will accept. */
 	readonly makeStore: () => Promise<{
 		store: MessageFeedbackStore
-		runId: RunId
+		sessionId: SessionId
 		knownMessageId: MessageId
-		/** Syntactically valid and never produced by `runId`. */
+		/** Syntactically valid and absent from `sessionId`'s log. */
 		unknownMessageId: MessageId
-		otherRunId: RunId
+		otherSessionId: SessionId
 		otherKnownMessageId: MessageId
 	}>
 }
@@ -48,10 +48,10 @@ export function defineMessageFeedbackConformance(options: FeedbackConformanceOpt
 
 	describe(`message feedback contract: ${options.label}`, () => {
 		it('starts a record at version 1', async () => {
-			const { store, runId, knownMessageId } = await makeStore()
+			const { store, sessionId, knownMessageId } = await makeStore()
 
 			const record = await store.putMessageFeedback({
-				runId,
+				sessionId,
 				messageId: knownMessageId,
 				rating: 'good',
 				expectedVersion: 0,
@@ -65,9 +65,9 @@ export function defineMessageFeedbackConformance(options: FeedbackConformanceOpt
 			// 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()
+			const { store, sessionId, knownMessageId } = await makeStore()
 			await store.putMessageFeedback({
-				runId,
+				sessionId,
 				messageId: knownMessageId,
 				rating: 'good',
 				expectedVersion: 0,
@@ -76,7 +76,7 @@ export function defineMessageFeedbackConformance(options: FeedbackConformanceOpt
 			let threw = false
 			try {
 				await store.putMessageFeedback({
-					runId,
+					sessionId,
 					messageId: knownMessageId,
 					rating: 'bad',
 					expectedVersion: 0,
@@ -88,7 +88,7 @@ export function defineMessageFeedbackConformance(options: FeedbackConformanceOpt
 			}
 
 			expect(threw).toBe(true)
-			const listed = await store.listMessageFeedback({ runId })
+			const listed = await store.listMessageFeedback({ sessionId })
 			expect(listed).toHaveLength(1)
 			expect(listed[0]?.rating).toBe('good')
 			expect(listed[0]?.ownerVersion).toBe(1)
@@ -99,11 +99,11 @@ export function defineMessageFeedbackConformance(options: FeedbackConformanceOpt
 			// 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 { store, sessionId, knownMessageId } = await makeStore()
 			const attempts = ['good', 'bad'].map((rating) =>
 				store
 					.putMessageFeedback({
-						runId,
+						sessionId,
 						messageId: knownMessageId,
 						rating: rating as 'good' | 'bad',
 						expectedVersion: 0,
@@ -117,15 +117,15 @@ export function defineMessageFeedbackConformance(options: FeedbackConformanceOpt
 
 			expect(outcomes.filter((o) => o === 'ok')).toHaveLength(1)
 			expect(outcomes.filter((o) => o === 'refused')).toHaveLength(1)
-			const listed = await store.listMessageFeedback({ runId })
+			const listed = await store.listMessageFeedback({ sessionId })
 			expect(listed).toHaveLength(1)
 			expect(listed[0]?.ownerVersion).toBe(1)
 		})
 
 		it('lets exactly one of two racing updates advance a stored version', async () => {
-			const { store, runId, knownMessageId } = await makeStore()
+			const { store, sessionId, knownMessageId } = await makeStore()
 			await store.putMessageFeedback({
-				runId,
+				sessionId,
 				messageId: knownMessageId,
 				rating: 'good',
 				expectedVersion: 0,
@@ -137,7 +137,7 @@ export function defineMessageFeedbackConformance(options: FeedbackConformanceOpt
 			].map((candidate) =>
 				store
 					.putMessageFeedback({
-						runId,
+						sessionId,
 						messageId: knownMessageId,
 						...candidate,
 						expectedVersion: 1,
@@ -154,7 +154,7 @@ export function defineMessageFeedbackConformance(options: FeedbackConformanceOpt
 			expect(outcomes.filter((outcome) => outcome.kind === 'refused')).toHaveLength(1)
 			const winner = winners[0]
 			if (winner?.kind !== 'ok') throw new Error('expected one feedback update winner')
-			const listed = await store.listMessageFeedback({ runId })
+			const listed = await store.listMessageFeedback({ sessionId })
 			expect(listed).toHaveLength(1)
 			expect(listed[0]?.ownerVersion).toBe(2)
 			expect(listed[0]?.rating).toBe(winner.record.rating)
@@ -162,16 +162,16 @@ export function defineMessageFeedbackConformance(options: FeedbackConformanceOpt
 		})
 
 		it('advances the version on a correct update', async () => {
-			const { store, runId, knownMessageId } = await makeStore()
+			const { store, sessionId, knownMessageId } = await makeStore()
 			await store.putMessageFeedback({
-				runId,
+				sessionId,
 				messageId: knownMessageId,
 				rating: 'good',
 				expectedVersion: 0,
 			})
 
 			const second = await store.putMessageFeedback({
-				runId,
+				sessionId,
 				messageId: knownMessageId,
 				rating: 'bad',
 				note: 'changed my mind',
@@ -183,50 +183,52 @@ export function defineMessageFeedbackConformance(options: FeedbackConformanceOpt
 			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()
+		it('refuses a message the session log does not hold, and writes nothing', async () => {
+			const { store, sessionId, unknownMessageId } = await makeStore()
 
 			let threw = false
 			try {
 				await store.putMessageFeedback({
-					runId,
+					sessionId,
 					messageId: unknownMessageId,
 					rating: 'good',
 					expectedVersion: 0,
 				})
-			} catch {
+			} catch (err) {
 				threw = true
+				expect((err as Error).name).toBe('UnknownMessageError')
 			}
 
 			expect(threw).toBe(true)
-			expect(await store.listMessageFeedback({ runId })).toHaveLength(0)
+			expect(await store.listMessageFeedback({ sessionId })).toHaveLength(0)
 		})
 
-		it('answers for the run it was asked about and no other', async () => {
-			const { store, runId, knownMessageId, otherRunId, otherKnownMessageId } = await makeStore()
+		it('answers for the session it was asked about and no other', async () => {
+			const { store, sessionId, knownMessageId, otherSessionId, otherKnownMessageId } =
+				await makeStore()
 			await store.putMessageFeedback({
-				runId,
+				sessionId,
 				messageId: knownMessageId,
 				rating: 'good',
 				expectedVersion: 0,
 			})
 			await store.putMessageFeedback({
-				runId: otherRunId,
+				sessionId: otherSessionId,
 				messageId: otherKnownMessageId,
 				rating: 'bad',
 				expectedVersion: 0,
 			})
 
-			const mine = await store.listMessageFeedback({ runId })
+			const mine = await store.listMessageFeedback({ sessionId })
 
 			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()
+		it('lists nothing for a session with no feedback', async () => {
+			const { store, otherSessionId } = await makeStore()
 
-			expect(await store.listMessageFeedback({ runId: otherRunId })).toHaveLength(0)
+			expect(await store.listMessageFeedback({ sessionId: otherSessionId })).toHaveLength(0)
 		})
 	})
 }

package/src/store/feedback/disk.ts

@@ -1,18 +1,18 @@
 import { join } from 'node:path'
 
+import type { SessionPaths } from '../../session/paths.js'
 import { NamzuError } from '../../types/errors/index.js'
-import type { MessageId, RunId } from '../../types/ids/index.js'
-import { asMessageId, asRunId } from '../../utils/id.js'
+import type { MessageId, SessionId } from '../../types/ids/index.js'
+import { asMessageId, asSessionId } 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 } from '../schema.js'
+import { streamSessionLog } from '../session-log/disk.js'
 import type { MessageExistenceCheck } from './memory.js'
 import {
 	type MessageFeedback,
@@ -44,16 +44,13 @@ const revisionRecords = new DiskRevisionRecordStore<MessageFeedback>(
  * file remains only a checked, best-effort compatibility projection.
  */
 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.
+	 * The project's layout. Feedback on a session lives in
+	 * `<session-id>/feedback/` (one `<message-id>.json` plus `.revisions/`),
+	 * beside the session's log — the log is what a rating is checked against,
+	 * so the two are kept and removed together.
 	 */
-	readonly runsDir?: string
+	readonly paths: Pick<SessionPaths, 'feedback' | 'sessionLog'>
 }
 
 /** Filesystem-safe file name for one rated message. */
@@ -64,25 +61,35 @@ function fileName(messageId: MessageId): string {
 }
 
 /**
- * Does this run's transcript mention this message?
+ * `hasMessage`, answered by the session's log: does it hold a `message`
+ * record with this id?
  *
- * 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.
+ * The log is the only record of what a session actually said. 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. The walk verifies the
+ * hash chain as it goes, so a log that was edited by hand refuses the rating
+ * rather than vouching for it. A host with a `SessionIndex` at hand can pass
+ * its own check instead; the answer must be the same.
  */
-export function runEventMessageCheck(runsDir: string): MessageExistenceCheck {
-	return async (runId: RunId, messageId: MessageId): Promise<boolean> => {
-		const checkedRunId = asRunId(runId)
+export function sessionLogMessageCheck(
+	paths: Pick<SessionPaths, 'sessionLog'>,
+): MessageExistenceCheck {
+	return async (sessionId: SessionId, messageId: MessageId): Promise<boolean> => {
+		const checkedSessionId = asSessionId(sessionId)
 		const checkedMessageId = asMessageId(messageId)
-		const events = await readRunEventsIn(join(runsDir, legacyRevisionFileSegment(checkedRunId)))
-		return events.some((event) => (event as { messageId?: string }).messageId === checkedMessageId)
+		const walk = streamSessionLog(paths.sessionLog({ sessionId: checkedSessionId }), {
+			sessionId: checkedSessionId,
+		})
+		for await (const { record } of walk) {
+			if (record.type === 'message' && record.messageId === checkedMessageId) return true
+		}
+		return false
 	}
 }
 
 export class DiskMessageFeedbackStore implements MessageFeedbackStore {
-	private readonly rootDir: string
+	private readonly paths: Pick<SessionPaths, 'feedback' | 'sessionLog'>
 	private readonly messageExists: MessageExistenceCheck
 
 	constructor(
@@ -90,49 +97,40 @@ export class DiskMessageFeedbackStore implements MessageFeedbackStore {
 		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 })
-					})
+		this.paths = config.paths
+		// The session's own log is the default authority on what it said.
+		this.messageExists = messageExists ?? sessionLogMessageCheck(config.paths)
 	}
 
-	private runDir(runId: RunId): string {
-		return join(this.rootDir, legacyRevisionFileSegment(asRunId(runId)))
+	private feedbackDir(sessionId: SessionId): string {
+		return this.paths.feedback({ sessionId: asSessionId(sessionId) })
 	}
 
-	private revisionsDir(runId: RunId): string {
-		return join(this.runDir(runId), '.revisions')
+	private revisionsDir(sessionId: SessionId): string {
+		return join(this.feedbackDir(sessionId), '.revisions')
 	}
 
-	private location(runId: RunId, messageId: MessageId): RevisionedRecordLocation {
+	private location(sessionId: SessionId, 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)),
+			legacyPath: join(this.feedbackDir(sessionId), legacyName),
+			revisionsDir: join(this.revisionsDir(sessionId), revisionFileSegment(checkedMessageId)),
 			// Preserve the projection guard from the previous layout. Checked ids
 			// now retain their spelling; unsafe custom suffixes are rejected above.
 			publishLegacyProjection: legacyName === `${checkedMessageId}.json`,
 		}
 	}
 
-	private assertKey(record: MessageFeedback, runId: RunId, messageId: MessageId): void {
-		if (record.runId !== runId || record.messageId !== messageId) {
+	private assertKey(record: MessageFeedback, sessionId: SessionId, messageId: MessageId): void {
+		if (record.sessionId !== sessionId || 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.`,
+				message: `Message feedback record key mismatch: expected ${sessionId}/${messageId}, found ${record.sessionId}/${record.messageId}. Repair or restore the record before retrying.`,
 				details: {
-					expectedRunId: runId,
+					expectedSessionId: sessionId,
 					expectedMessageId: messageId,
-					actualRunId: record.runId,
+					actualSessionId: record.sessionId,
 					actualMessageId: record.messageId,
 				},
 				retryable: false,
@@ -144,23 +142,23 @@ export class DiskMessageFeedbackStore implements MessageFeedbackStore {
 		// 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 sessionId = asSessionId(input.sessionId)
 		const messageId = asMessageId(input.messageId)
-		const location = this.location(runId, messageId)
+		const location = this.location(sessionId, messageId)
 
 		// 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 })
+		if (!(await this.messageExists(sessionId, messageId))) {
+			throw new UnknownMessageError({ sessionId, messageId })
 		}
 
 		return await revisionRecords.transact(location, (existing) => {
-			if (existing) this.assertKey(existing, runId, messageId)
+			if (existing) this.assertKey(existing, sessionId, messageId)
 			const actualVersion = existing?.ownerVersion ?? 0
 			if (input.expectedVersion !== actualVersion) {
 				throw new StaleFeedbackError({
-					runId,
+					sessionId,
 					messageId,
 					expectedVersion: input.expectedVersion,
 					actualVersion,
@@ -169,7 +167,7 @@ export class DiskMessageFeedbackStore implements MessageFeedbackStore {
 
 			const timestamp = this.now()
 			const record: MessageFeedback = {
-				runId,
+				sessionId,
 				messageId,
 				rating: input.rating,
 				...(input.note !== undefined ? { note: input.note } : {}),
@@ -181,9 +179,9 @@ export class DiskMessageFeedbackStore implements MessageFeedbackStore {
 		})
 	}
 
-	async listMessageFeedback(query: { runId: RunId }): Promise<readonly MessageFeedback[]> {
-		const runId = asRunId(query.runId)
-		const dir = this.runDir(runId)
+	async listMessageFeedback(query: { sessionId: SessionId }): Promise<readonly MessageFeedback[]> {
+		const sessionId = asSessionId(query.sessionId)
+		const dir = this.feedbackDir(sessionId)
 		const ids = new Map<string, MessageId>()
 
 		// Old single-file records are still authoritative until their first
@@ -194,12 +192,12 @@ export class DiskMessageFeedbackStore implements MessageFeedbackStore {
 			const record = await records.read(join(dir, name))
 			if (record === null) continue
 			const messageId = asMessageId(record.messageId)
-			this.assertKey(record, runId, messageId)
+			this.assertKey(record, sessionId, 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 },
+					details: { sessionId, messageId, name },
 					retryable: false,
 				})
 			}
@@ -209,7 +207,7 @@ export class DiskMessageFeedbackStore implements MessageFeedbackStore {
 		// 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), '')) {
+		for (const segment of await records.scanNames(this.revisionsDir(sessionId), '')) {
 			const decoded = decodeRevisionFileSegment(segment)
 			if (decoded === null) continue
 			const messageId = asMessageId(decoded)
@@ -218,9 +216,9 @@ export class DiskMessageFeedbackStore implements MessageFeedbackStore {
 
 		const out: MessageFeedback[] = []
 		for (const messageId of [...ids.values()].sort((a, b) => a.localeCompare(b))) {
-			const record = await revisionRecords.read(this.location(runId, messageId))
+			const record = await revisionRecords.read(this.location(sessionId, messageId))
 			if (record === null) continue
-			this.assertKey(record, runId, messageId)
+			this.assertKey(record, sessionId, messageId)
 			out.push(record)
 		}
 		return out

package/src/store/feedback/index.ts

@@ -1,6 +1,6 @@
 export { defineMessageFeedbackConformance } from './conformance.js'
 export type { FeedbackConformanceOptions } from './conformance.js'
-export { DiskMessageFeedbackStore, runEventMessageCheck } from './disk.js'
+export { DiskMessageFeedbackStore, sessionLogMessageCheck } from './disk.js'
 export type { DiskMessageFeedbackStoreConfig } from './disk.js'
 export { acceptAnyMessage, InMemoryMessageFeedbackStore } from './memory.js'
 export type { MessageExistenceCheck } from './memory.js'

package/src/store/feedback/types.ts

@@ -1,11 +1,11 @@
-import type { MessageId, RunId } from '../../types/ids/index.js'
+import type { MessageId, SessionId } 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
+ * for one already existed: `MessageId` is a branded type, the session log's
+ * `message` records 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
@@ -24,7 +24,8 @@ import type { MessageId, RunId } from '../../types/ids/index.js'
 export type FeedbackRating = 'good' | 'bad'
 
 export interface MessageFeedback {
-	readonly runId: RunId
+	/** The session whose log holds the rated message. */
+	readonly sessionId: SessionId
 	readonly messageId: MessageId
 	readonly rating: FeedbackRating
 	/** Whatever the rater wanted to say. Absent is different from empty. */
@@ -43,7 +44,7 @@ export interface MessageFeedback {
 }
 
 export interface PutMessageFeedbackInput {
-	readonly runId: RunId
+	readonly sessionId: SessionId
 	readonly messageId: MessageId
 	readonly rating: FeedbackRating
 	readonly note?: string
@@ -59,26 +60,26 @@ export interface PutMessageFeedbackInput {
 
 export interface MessageFeedbackStore {
 	putMessageFeedback(input: PutMessageFeedbackInput): Promise<MessageFeedback>
-	listMessageFeedback(query: { readonly runId: RunId }): Promise<readonly MessageFeedback[]>
+	listMessageFeedback(query: { readonly sessionId: SessionId }): Promise<readonly MessageFeedback[]>
 }
 
 /** A write whose `expectedVersion` no longer matches what is stored. */
 export class StaleFeedbackError extends Error {
 	readonly details: {
-		runId: RunId
+		sessionId: SessionId
 		messageId: MessageId
 		expectedVersion: number
 		actualVersion: number
 	}
 
 	constructor(details: {
-		runId: RunId
+		sessionId: SessionId
 		messageId: MessageId
 		expectedVersion: number
 		actualVersion: number
 	}) {
 		super(
-			`Stale feedback for ${details.messageId} in ${details.runId}: expected ownerVersion=${details.expectedVersion}, actual=${details.actualVersion}`,
+			`Stale feedback for ${details.messageId} in session ${details.sessionId}: expected ownerVersion=${details.expectedVersion}, actual=${details.actualVersion}`,
 		)
 		this.name = 'StaleFeedbackError'
 		this.details = details
@@ -86,7 +87,7 @@ export class StaleFeedbackError extends Error {
 }
 
 /**
- * A rating aimed at a message the named run never produced.
+ * A rating aimed at a message the named session's log does not hold.
  *
  * 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
@@ -95,11 +96,11 @@ export class StaleFeedbackError extends Error {
  * nothing at write time and poisons every read after it.
  */
 export class UnknownMessageError extends Error {
-	readonly details: { runId: RunId; messageId: MessageId }
+	readonly details: { sessionId: SessionId; messageId: MessageId }
 
-	constructor(details: { runId: RunId; messageId: MessageId }) {
+	constructor(details: { sessionId: SessionId; messageId: MessageId }) {
 		super(
-			`No message ${details.messageId} in run ${details.runId}: feedback must name a message the run actually produced.`,
+			`No message ${details.messageId} in session ${details.sessionId}: feedback must name a message the session log holds.`,
 		)
 		this.name = 'UnknownMessageError'
 		this.details = details

package/src/store/index.ts

@@ -1,34 +1,6 @@
 export { InMemoryStore } from './InMemoryStore.js'
 export type { Identifiable, Timestamped } from './InMemoryStore.js'
 
-export { RunDiskStore, readRunEventsIn, readRunMessagesIn } from './run/disk.js'
-export { InMemoryRunStore } from './run/memory.js'
-export { DiskCheckpointStore } from './run/checkpoint-disk.js'
-export type { DiskCheckpointStoreAttribution } from './run/checkpoint-disk.js'
-export { InMemoryCheckpointStore } from './run/checkpoint-memory.js'
-export { DiskTokenBudgetStore, openTokenBudget } from './run/token-budget-disk.js'
-export type { DiskTokenBudgetStoreConfig, OpenTokenBudgetOptions } from './run/token-budget-disk.js'
-// The refusing entry point to the optional listing capability, plus the two
-// projections a host implementing its own backend actually calls: one turns
-// a run's checkpoints into a row, the other applies the contract's filter,
-// ordering and cursor. Re-deriving either is how two stores start
-// disagreeing about what "outstanding" means or where a page ends.
-//
-// `summarizePark` and `DEFAULT_DURABLE_RUN_LIMIT` are deliberately NOT here.
-// The first is an internal of `toDurableRunEntry` and no caller wants half a
-// row; the second is a number a host reads by omitting `limit`. A name a
-// host has no use for is surface to keep correct forever for nobody.
-export {
-	assertContiguousListingScope,
-	claimRun,
-	fencedOut,
-	listDurableRuns,
-	paginateDurableRuns,
-	releaseRun,
-	toClaimSummary,
-	toDurableRunEntry,
-} from './run/listing.js'
-
 export { ActivityStore } from './activity/memory.js'
 export type { ActivityEvent, ActivityEventListener } from './activity/memory.js'
 
@@ -40,6 +12,30 @@ 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'
+export { MarkdownMemoryStore } from './memory/markdown.js'
+export type {
+	MarkdownMemoryStoreConfig,
+	MemoryImportOutcome,
+} from './memory/markdown.js'
+export {
+	MEMORY_INDEX_LINE_MAX_CHARS,
+	MEMORY_INDEX_MAX_LINES,
+	memoryIndexLine,
+	renderMemoryIndex,
+} from './memory/index-file.js'
+export type { RenderedMemoryIndex } from './memory/index-file.js'
+export {
+	MEMORY_VERIFY_NOTICE,
+	describeMemoryAge,
+	memoryLinkNames,
+} from './memory/links.js'
+export {
+	MemoryContentRejectedError,
+	MemoryNameConflictError,
+	isMemoryName,
+	slugifyMemoryName,
+} from './memory/naming.js'
+export type { MemoryContentRejection } from './memory/naming.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

package/src/store/memory/digest.ts

@@ -0,0 +1,35 @@
+import { createHash } from 'node:crypto'
+
+import type { MemoryStore } from '../../types/memory/index.js'
+
+/** Tag prefix both derived-memory writers (the session memory promoter and consolidation) put their content digest under. */
+export const KNOWLEDGE_TAG_PREFIX = 'knowledge:'
+
+export function knowledgeDigest(value: unknown): string {
+	return createHash('sha256').update(JSON.stringify(value)).digest('hex')
+}
+
+/**
+ * Whether `store` already holds a record carrying `digest` — archived ones
+ * included, so a claim deliberately retired is not written back.
+ *
+ * The tag narrows the search and the metadata confirms it, because a tag is
+ * free text anyone can write and the digest in metadata is what the writer
+ * recorded. Best-effort: this read and the caller's create are two store
+ * operations, not one, so two processes can still both write.
+ */
+export async function holdsKnowledgeDigest(
+	store: MemoryStore,
+	tags: readonly string[],
+	digest: string,
+	isWriter: (metadata: Record<string, unknown> | undefined) => boolean,
+): Promise<boolean> {
+	const existing = await store.list({
+		tags: [...tags, `${KNOWLEDGE_TAG_PREFIX}${digest}`],
+	})
+	for (const entry of existing.entries) {
+		const full = await store.get(entry.id)
+		if (full?.metadata?.knowledgeDigest === digest && isWriter(full.metadata)) return true
+	}
+	return false
+}