@namzu/sdk 27.1.0 → 29.0.0

package/src/store/memory/disk.ts

@@ -1,4 +1,4 @@
-import { mkdir, readFile, unlink } from 'node:fs/promises'
+import { mkdir, unlink } from 'node:fs/promises'
 import { join } from 'node:path'
 import type { MemoryId } from '../../types/ids/index.js'
 import type {
@@ -9,10 +9,11 @@ import type {
 	MemorySearchResult,
 	MemoryStore,
 } from '../../types/memory/index.js'
-import { atomicWriteFile } from '../../utils/atomic-write.js'
 import { generateMemoryId } from '../../utils/id.js'
-import { type Logger, getRootLogger } from '../../utils/logger.js'
-import { defineSchema, migrate, stamp } from '../schema.js'
+import { SCOPE_ATTRIBUTE } from '../../utils/log/types.js'
+import { type Logger, resolveLogger } from '../../utils/logger.js'
+import { DiskRecordStore } from '../kv/record-store.js'
+import { defineSchema } from '../schema.js'
 import { InMemoryMemoryIndex } from './index.js'
 
 /**
@@ -35,10 +36,16 @@ export class DiskMemoryStore implements MemoryStore {
 	private log: Logger
 	private index = new InMemoryMemoryIndex()
 	private initialized = false
+	// Two instances of one primitive rather than two copies of its body.
+	// Typed separately because the index file holds an ARRAY and a content
+	// file holds one record, and a single `DiskRecordStore<unknown>` would
+	// have put the cast back at every call site.
+	private readonly records = new DiskRecordStore<MemoryContent>(SCHEMA)
+	private readonly indexRecords = new DiskRecordStore<readonly MemoryIndexEntry[]>(SCHEMA)
 
 	constructor(config: DiskMemoryStoreConfig) {
 		this.baseDir = join(config.baseDir, 'memory')
-		this.log = (config.logger ?? getRootLogger()).child({ component: 'DiskMemoryStore' })
+		this.log = resolveLogger(config.logger).child({ [SCOPE_ATTRIBUTE]: 'store/memory/disk' })
 	}
 
 	private get indexPath(): string {
@@ -59,18 +66,19 @@ export class DiskMemoryStore implements MemoryStore {
 		await mkdir(this.contentDir, { recursive: true })
 
 		try {
-			const raw = await readFile(this.indexPath, 'utf-8')
-			const entries = migrate<MemoryIndexEntry[]>(SCHEMA, JSON.parse(raw))
-			this.index.rebuild(entries)
-			this.log.info('Memory index loaded', { count: entries.length })
-		} catch (err) {
-			const isNotFound =
-				typeof err === 'object' && err !== null && (err as NodeJS.ErrnoException).code === 'ENOENT'
-			if (!isNotFound) {
-				this.log.warn('Failed to read memory index — starting fresh', {
-					error: String(err),
-				})
+			// `null` for "no index yet", which is an ordinary first-run state
+			// and not something to warn about. The catch below is now only
+			// for a real IO or parse failure — the distinction this method
+			// used to draw by hand with an ENOENT comparison.
+			const entries = await this.indexRecords.read(this.indexPath)
+			if (entries !== null) {
+				this.index.rebuild([...entries])
+				this.log.info('Memory index loaded', { 'namzu.store.count': entries.length })
 			}
+		} catch (err) {
+			this.log.warn('Failed to read memory index — starting fresh', {
+				'exception.message': String(err),
+			})
 		}
 
 		this.initialized = true
@@ -103,9 +111,9 @@ export class DiskMemoryStore implements MemoryStore {
 
 		this.index.set(entry)
 		await this.persistIndex()
-		await atomicWriteJson(this.contentPath(id), memoryContent)
+		await this.records.write(this.contentPath(id), memoryContent)
 
-		this.log.info('Memory created', { memoryId: id, title: params.title })
+		this.log.info('Memory created', { 'namzu.memory.id': id, 'namzu.store.title': params.title })
 
 		return { entry, content: memoryContent }
 	}
@@ -116,10 +124,9 @@ export class DiskMemoryStore implements MemoryStore {
 		if (!this.index.getEntry(id)) return undefined
 
 		try {
-			const raw = await readFile(this.contentPath(id), 'utf-8')
-			return migrate<MemoryContent>(SCHEMA, JSON.parse(raw))
+			return (await this.records.read(this.contentPath(id))) ?? undefined
 		} catch {
-			this.log.warn('Failed to read memory content', { memoryId: id })
+			this.log.warn('Failed to read memory content', { 'namzu.memory.id': id })
 			return undefined
 		}
 	}
@@ -152,8 +159,8 @@ export class DiskMemoryStore implements MemoryStore {
 			updates.metadata !== undefined
 		) {
 			try {
-				const raw = await readFile(this.contentPath(id), 'utf-8')
-				const existingContent = migrate<MemoryContent>(SCHEMA, JSON.parse(raw))
+				const existingContent = await this.records.read(this.contentPath(id))
+				if (existingContent === null) throw new Error('memory content is missing')
 
 				const updatedContent: MemoryContent = {
 					...existingContent,
@@ -163,13 +170,13 @@ export class DiskMemoryStore implements MemoryStore {
 						updates.metadata !== undefined ? { ...updates.metadata } : existingContent.metadata,
 				}
 
-				await atomicWriteJson(this.contentPath(id), updatedContent)
+				await this.records.write(this.contentPath(id), updatedContent)
 			} catch {
-				this.log.warn('Failed to update memory content', { memoryId: id })
+				this.log.warn('Failed to update memory content', { 'namzu.memory.id': id })
 			}
 		}
 
-		this.log.info('Memory updated', { memoryId: id })
+		this.log.info('Memory updated', { 'namzu.memory.id': id })
 		return updated
 	}
 
@@ -182,7 +189,7 @@ export class DiskMemoryStore implements MemoryStore {
 		await this.persistIndex()
 		await unlink(this.contentPath(id)).catch(() => undefined)
 
-		this.log.info('Memory deleted', { memoryId: id })
+		this.log.info('Memory deleted', { 'namzu.memory.id': id })
 		return true
 	}
 
@@ -197,10 +204,6 @@ export class DiskMemoryStore implements MemoryStore {
 
 	private async persistIndex(): Promise<void> {
 		const entries = this.index.allEntries()
-		await atomicWriteJson(this.indexPath, entries)
+		await this.indexRecords.write(this.indexPath, entries)
 	}
 }
-
-async function atomicWriteJson(filePath: string, value: unknown): Promise<void> {
-	await atomicWriteFile(filePath, JSON.stringify(stamp(SCHEMA, value), null, 2))
-}

package/src/store/run/checkpoint-disk.ts

@@ -7,12 +7,12 @@ import type {
 	CheckpointListingScope,
 	CheckpointRunScope,
 	CheckpointStore,
-	ClaimFence,
 	ClaimRunOptions,
 	DurableRunEntry,
 	DurableRunPage,
+	FencingToken,
 	ListDurableRunsOptions,
-	RunClaim,
+	RunLease,
 } from '../../types/run/checkpoint-store.js'
 import type { RunStoreConfig } from '../../types/run/index.js'
 import type { ProjectId } from '../../types/session/ids.js'
@@ -97,7 +97,7 @@ export class DiskCheckpointStore implements CheckpointStore {
 	async writeCheckpoint(
 		scope: CheckpointRunScope,
 		checkpoint: IterationCheckpoint,
-		fence?: ClaimFence,
+		fence?: FencingToken,
 	): Promise<void> {
 		const store = await this.bind(scope)
 		if (fence !== undefined) {
@@ -113,11 +113,11 @@ export class DiskCheckpointStore implements CheckpointStore {
 		await store.writeCheckpoint(checkpoint)
 	}
 
-	async claimRun(scope: CheckpointRunScope, options: ClaimRunOptions): Promise<RunClaim | null> {
+	async claimRun(scope: CheckpointRunScope, options: ClaimRunOptions): Promise<RunLease | null> {
 		return acquireClaim(this.runDir(scope), options)
 	}
 
-	async releaseRun(scope: CheckpointRunScope, fence: ClaimFence): Promise<void> {
+	async releaseRun(scope: CheckpointRunScope, fence: FencingToken): Promise<void> {
 		await releaseClaim(this.runDir(scope), fence)
 	}
 
@@ -247,7 +247,28 @@ export class DiskCheckpointStore implements CheckpointStore {
 	private async readRunDirs(dir: string): Promise<RunId[]> {
 		try {
 			const found = await readdir(dir, { withFileTypes: true })
-			return found.filter((e) => e.isDirectory()).map((e) => e.name as RunId)
+			// Filtered by prefix, not just by "is a directory", so the declared
+			// `RunId[]` is true of what comes back. An editor's scratch folder or
+			// a `tmp-` left by a crashed write is not a run, and the assertion
+			// below is what let it be returned as one.
+			//
+			// **Unobservable through `listDurableRuns` today, and kept
+			// deliberately.** Measured, not assumed: removing this filter, and
+			// separately weakening it to `startsWith('r')`, leaves every test in
+			// this package green. `toDurableRunEntry` returns undefined for a
+			// directory with no checkpoints in it, so a junk name is already
+			// dropped one layer down — the filter saves the `readdir` and the
+			// parse, not a wrong answer. It is here because `readRunDirs` is a
+			// private helper with two callers and a declared element type, and
+			// the next caller inherits the type rather than the accident that
+			// currently covers for it.
+			//
+			// Filtered rather than refused, whatever the reach: a scan that
+			// threw on one piece of junk could not list the runs that are fine,
+			// during exactly the incident this listing exists for.
+			return found
+				.filter((e) => e.isDirectory() && e.name.startsWith('run_'))
+				.map((e) => e.name as RunId)
 		} catch (err) {
 			if ((err as NodeJS.ErrnoException).code === 'ENOENT') return []
 			throw err

package/src/store/run/checkpoint-memory.ts

@@ -3,12 +3,12 @@ import type {
 	CheckpointListingScope,
 	CheckpointRunScope,
 	CheckpointStore,
-	ClaimFence,
 	ClaimRunOptions,
 	DurableRunEntry,
 	DurableRunPage,
+	FencingToken,
 	ListDurableRunsOptions,
-	RunClaim,
+	RunLease,
 } from '../../types/run/checkpoint-store.js'
 import {
 	assertContiguousListingScope,
@@ -45,7 +45,7 @@ export class InMemoryCheckpointStore implements CheckpointStore {
 	}
 
 	/** `tenant/project/session/run` → the run's current holding, if any. */
-	private readonly claims = new Map<string, RunClaim>()
+	private readonly claims = new Map<string, RunLease>()
 
 	/**
 	 * The highest fence ever issued per run, kept separately from the claim.
@@ -61,9 +61,9 @@ export class InMemoryCheckpointStore implements CheckpointStore {
 	 * must agree, because this class is what a host reads when writing a
 	 * backend of its own.
 	 */
-	private readonly highWater = new Map<string, ClaimFence>()
+	private readonly highWater = new Map<string, FencingToken>()
 
-	async claimRun(scope: CheckpointRunScope, options: ClaimRunOptions): Promise<RunClaim | null> {
+	async claimRun(scope: CheckpointRunScope, options: ClaimRunOptions): Promise<RunLease | null> {
 		const key = this.key(scope)
 		const now = options.now ?? Date.now()
 		const held = this.claims.get(key)
@@ -80,13 +80,13 @@ export class InMemoryCheckpointStore implements CheckpointStore {
 		// released run has no claim, and computing from that absence is what
 		// rewound the counter to 1 on every release.
 		const fence = (this.highWater.get(key) ?? 0) + 1
-		const claim: RunClaim = { holder: options.holder, fence, expiresAt: now + options.ttlMs }
+		const claim: RunLease = { holder: options.holder, fence, expiresAt: now + options.ttlMs }
 		this.highWater.set(key, fence)
 		this.claims.set(key, claim)
 		return claim
 	}
 
-	async releaseRun(scope: CheckpointRunScope, fence: ClaimFence): Promise<void> {
+	async releaseRun(scope: CheckpointRunScope, fence: FencingToken): Promise<void> {
 		const key = this.key(scope)
 		const held = this.claims.get(key)
 		// A stale fence releases nothing. A worker that stalled past its lease
@@ -112,7 +112,7 @@ export class InMemoryCheckpointStore implements CheckpointStore {
 	async writeCheckpoint(
 		scope: CheckpointRunScope,
 		checkpoint: IterationCheckpoint,
-		fence?: ClaimFence,
+		fence?: FencingToken,
 	): Promise<void> {
 		const key = this.key(scope)
 		// An unfenced write is allowed even on a claimed run: a host adopting

package/src/store/run/claim-disk.ts

@@ -95,8 +95,9 @@
 
 import { link, mkdir, readFile, readdir, stat, unlink, writeFile } from 'node:fs/promises'
 import { join } from 'node:path'
+import { invariants } from '../../invariants/index.js'
 import { NamzuError } from '../../types/errors/index.js'
-import type { ClaimFence, ClaimRunOptions, RunClaim } from '../../types/run/checkpoint-store.js'
+import type { ClaimRunOptions, FencingToken, RunLease } from '../../types/run/checkpoint-store.js'
 
 /** Directory holding one file per holding, named for its fence. */
 const CLAIMS_DIR = 'claims'
@@ -153,7 +154,7 @@ function isErrno(err: unknown, code: string): boolean {
  * could tell a clean release from a damaged record, and **nothing ever asked**
  * — the only reader was an exported `isReleased` with no caller anywhere, not
  * re-exported from the package and absent from the public surface baseline.
- * `ClaimSummary`, which is the type a listing row actually carries, never
+ * `LeaseSummary`, which is the type a listing row actually carries, never
  * gained a field for it, so the distinction the flag was written for was never
  * available at the place it was meant to serve.
  *
@@ -206,7 +207,7 @@ function isClaimBody(value: unknown): value is ClaimBody {
  */
 const NAME = /^([0-9]{1,15})\.json$/
 
-function nameFor(fence: ClaimFence): string {
+function nameFor(fence: FencingToken): string {
 	return `${fence}.json`
 }
 
@@ -251,7 +252,7 @@ let attempts = 0
  * acquisition the moment the store's base directory is a mount of its own.
  * That is a rule, not a preference.
  */
-function tempNameFor(fence: ClaimFence): string {
+function tempNameFor(fence: FencingToken): string {
 	attempts += 1
 	return `.tmp-${process.pid}-${attempts}-${Math.random().toString(36).slice(2, 10)}-${fence}`
 }
@@ -284,7 +285,7 @@ const NO_LINK = new Set(['EPERM', 'ENOTSUP', 'EOPNOTSUPP', 'ENOSYS', 'EXDEV', 'E
  * volume was available to measure; the error says so rather than implying a
  * diagnosis it did not make.
  */
-async function publish(claimsDir: string, fence: ClaimFence, body: ClaimBody): Promise<void> {
+async function publish(claimsDir: string, fence: FencingToken, body: ClaimBody): Promise<void> {
 	const tmp = join(claimsDir, tempNameFor(fence))
 
 	try {
@@ -354,7 +355,7 @@ async function publish(claimsDir: string, fence: ClaimFence, body: ClaimBody): P
  * deadline has to read the body, and {@link readClaim} is the only thing that
  * does.
  */
-async function listHoldings(runDir: string): Promise<{ name: string; fence: ClaimFence }[]> {
+async function listHoldings(runDir: string): Promise<{ name: string; fence: FencingToken }[]> {
 	let names: string[]
 	try {
 		names = await readdir(join(runDir, CLAIMS_DIR))
@@ -363,7 +364,7 @@ async function listHoldings(runDir: string): Promise<{ name: string; fence: Clai
 		throw err
 	}
 
-	const found: { name: string; fence: ClaimFence }[] = []
+	const found: { name: string; fence: FencingToken }[] = []
 	for (const name of names) {
 		const match = NAME.exec(name)
 		if (!match) continue
@@ -380,7 +381,7 @@ async function listHoldings(runDir: string): Promise<{ name: string; fence: Clai
  * asks, because a name cannot be half-written: a file either exists or does
  * not, where a body can be observed mid-write.
  */
-export async function currentFence(runDir: string): Promise<ClaimFence> {
+export async function currentFence(runDir: string): Promise<FencingToken> {
 	const holdings = await listHoldings(runDir)
 	return holdings[0]?.fence ?? 0
 }
@@ -397,7 +398,7 @@ export async function currentFence(runDir: string): Promise<ClaimFence> {
  * Failures are swallowed: pruning is housekeeping, and a run must not fail
  * because a tidy-up lost a race with another worker doing the same tidy-up.
  */
-async function prune(claimsDir: string, max: ClaimFence): Promise<void> {
+async function prune(claimsDir: string, max: FencingToken): Promise<void> {
 	let names: string[]
 	try {
 		names = await readdir(claimsDir)
@@ -454,7 +455,7 @@ async function prune(claimsDir: string, max: ClaimFence): Promise<void> {
  * details are unavailable", and the caller's response is to take the NEXT
  * number rather than to give up. Nothing is inferred from the absence.
  */
-export async function readClaim(runDir: string): Promise<RunClaim | null> {
+export async function readClaim(runDir: string): Promise<RunLease | null> {
 	const [top] = await listHoldings(runDir)
 	if (!top) return null
 
@@ -476,7 +477,7 @@ export async function readClaim(runDir: string): Promise<RunClaim | null> {
 	// leaves a run permanently unclaimable, which is the failure a lease
 	// exists to prevent — and the taker is safe regardless, because it takes
 	// the next fence and the write check compares numbers.
-	const claim: RunClaim = { holder: '', fence: top.fence, expiresAt: 0 }
+	const claim: RunLease = { holder: '', fence: top.fence, expiresAt: 0 }
 
 	let raw: string
 	try {
@@ -521,7 +522,7 @@ export async function readClaim(runDir: string): Promise<RunClaim | null> {
 export async function acquireClaim(
 	runDir: string,
 	options: ClaimRunOptions,
-): Promise<RunClaim | null> {
+): Promise<RunLease | null> {
 	const now = options.now ?? Date.now()
 	const claimsDir = join(runDir, CLAIMS_DIR)
 	await mkdir(claimsDir, { recursive: true })
@@ -571,7 +572,7 @@ export async function acquireClaim(
  * A stale fence releases nothing — a worker that stalled past its lease must
  * not be able to hand away a run somebody else now holds.
  */
-export async function releaseClaim(runDir: string, fence: ClaimFence): Promise<void> {
+export async function releaseClaim(runDir: string, fence: FencingToken): Promise<void> {
 	const held = await readClaim(runDir)
 	if (!held || held.fence !== fence) return
 
@@ -591,3 +592,47 @@ export async function releaseClaim(runDir: string, fence: ClaimFence): Promise<v
 		if (!isErrno(err, 'EEXIST')) throw err
 	}
 }
+
+/**
+ * Ctx for `store.run:single-open-writer`, registered just below: the fence
+ * a specific writer is about to act under, checked against the run's
+ * actual current fence. This is the same comparison
+ * `DiskCheckpointStore.writeCheckpoint` already makes inline before every
+ * write (see `checkpoint-disk.ts`), asked here as a query rather than an
+ * enforcement, so it can be answered without a write attached and so a
+ * violation has a name and a counter. The write path's own refusal is
+ * untouched — it still enforces on its own, unconditionally, because a
+ * write that could only be refused by first asking a registry would be the
+ * false pass `an-optional-dependency-may-not-degrade-a-check` describes if
+ * that registry were ever skipped.
+ */
+interface SingleOpenWriterContext {
+	readonly runDir: string
+	readonly presentedFence: FencingToken
+}
+
+invariants.register<SingleOpenWriterContext | undefined>(
+	'store.run',
+	'single-open-writer',
+	async (ctx) => {
+		if (!ctx) {
+			return {
+				state: 'unknown',
+				reason:
+					'no run directory given — this invariant is evaluated per run, not for the process as a whole',
+			}
+		}
+		const current = await currentFence(ctx.runDir)
+		if (ctx.presentedFence < current) {
+			const held = await readClaim(ctx.runDir)
+			const holderNote = held?.holder ? ` (now held by "${held.holder}")` : ''
+			return {
+				state: 'violated',
+				detail:
+					`presented fence ${ctx.presentedFence} is behind this run's current fence ` +
+					`${current}${holderNote} — another worker has taken this run over`,
+			}
+		}
+		return { state: 'holds' }
+	},
+)

package/src/store/run/conformance.ts

@@ -60,8 +60,9 @@
 
 import type { CostInfo } from '../../types/common/index.js'
 import type { IterationCheckpoint } from '../../types/hitl/index.js'
-import type { CheckpointId, ProjectId, RunId, SessionId, TenantId } from '../../types/ids/index.js'
+import type { ProjectId, SessionId, TenantId } from '../../types/ids/index.js'
 import type { CheckpointStore } from '../../types/run/checkpoint-store.js'
+import { asCheckpointId, asProjectId, asRunId, asSessionId, asTenantId } from '../../utils/id.js'
 import { claimRun, listDurableRuns, releaseRun } from './listing.js'
 
 /**
@@ -166,13 +167,13 @@ export interface CheckpointStoreConformanceOptions {
 
 /** The tenant/project/session every case addresses unless it needs a second. */
 const BINDING: CheckpointStoreBinding = {
-	tenantId: 'tnt_conformance' as TenantId,
-	projectId: 'prj_conformance' as ProjectId,
-	sessionId: 'ses_conformance' as SessionId,
+	tenantId: asTenantId('tnt_conformance'),
+	projectId: asProjectId('prj_conformance'),
+	sessionId: asSessionId('ses_conformance'),
 }
 
 /** A tenant no backend under test holds runs for. */
-const FOREIGN_TENANT = 'tnt_conformance_other' as TenantId
+const FOREIGN_TENANT = asTenantId('tnt_conformance_other')
 
 /** Fixed instant, so every expiry in a case is judged against one clock. */
 const NOW = 5_000_000
@@ -195,8 +196,8 @@ let checkpointSeq = 0
 function checkpoint(runId: string): IterationCheckpoint {
 	checkpointSeq += 1
 	return {
-		id: `cp_conformance_${checkpointSeq}` as CheckpointId,
-		runId: runId as RunId,
+		id: asCheckpointId(`cp_conformance_${checkpointSeq}`),
+		runId: asRunId(runId),
 		iteration: 1,
 		messages: [],
 		tokenUsage: {
@@ -213,7 +214,7 @@ function checkpoint(runId: string): IterationCheckpoint {
 }
 
 function runScope(binding: CheckpointStoreBinding, runId = 'run_conformance_a') {
-	return { ...binding, runId: runId as RunId }
+	return { ...binding, runId: asRunId(runId) }
 }
 
 /**
@@ -580,7 +581,7 @@ export function defineCheckpointStoreConformance(options: CheckpointStoreConform
 
 						const foreign = await listDurableRuns(store, {
 							tenantId: BINDING.tenantId,
-							projectId: 'prj_conformance_other' as ProjectId,
+							projectId: asProjectId('prj_conformance_other'),
 						})
 						expect(foreign.entries.map((e) => e.runId)).toEqual([])
 					}),
@@ -648,7 +649,7 @@ export function defineCheckpointStoreConformance(options: CheckpointStoreConform
 									tenantId: FOREIGN_TENANT,
 									projectId: BINDING.projectId,
 									sessionId: BINDING.sessionId,
-									runId: 'run_conformance_z' as RunId,
+									runId: asRunId('run_conformance_z'),
 								},
 								checkpoint('run_conformance_z'),
 							)

package/src/store/run/disk.ts

@@ -1,10 +1,17 @@
 import { appendFile, mkdir, readFile, readdir, unlink } from 'node:fs/promises'
 import { join } from 'node:path'
 import type { CheckpointId, IterationCheckpoint } from '../../types/hitl/index.js'
-import type { PersistedRunEvent, Run, RunEvent, RunStoreConfig } from '../../types/run/index.js'
+import type {
+	AuditEvent,
+	PersistedRunEvent,
+	Run,
+	RunEvent,
+	RunStoreConfig,
+} from '../../types/run/index.js'
 import type { CompletedToolRecord, ReadRunEventsOptions, RunStore } from '../../types/run/store.js'
 import { atomicWriteFile } from '../../utils/atomic-write.js'
-import { type Logger, getRootLogger } from '../../utils/logger.js'
+import { SCOPE_ATTRIBUTE } from '../../utils/log/types.js'
+import { type Logger, resolveLogger } from '../../utils/logger.js'
 import { defineSchema, migrate, stamp } from '../schema.js'
 
 /**
@@ -34,7 +41,7 @@ export class RunDiskStore implements RunStore {
 
 	constructor(config: RunStoreConfig) {
 		this.baseDir = config.baseDir
-		this.log = (config.logger ?? getRootLogger()).child({ component: 'RunDiskStore' })
+		this.log = resolveLogger(config.logger).child({ [SCOPE_ATTRIBUTE]: 'store/run/disk' })
 	}
 
 	private requireInit(): string {
@@ -52,7 +59,8 @@ export class RunDiskStore implements RunStore {
 		}
 		await mkdir(this.runDir, { recursive: true })
 		await healTornTranscript(this.runDir)
-		this.log.info(`Run directory created: ${this.runDir}`)
+		await healTornAuditTrail(this.runDir)
+		this.log.info('Run directory created', { 'namzu.run.dir': this.runDir })
 		return this.runDir
 	}
 
@@ -71,6 +79,47 @@ export class RunDiskStore implements RunStore {
 		return readRunEventsIn(this.requireInit(), options)
 	}
 
+	async appendAuditEvent(event: AuditEvent): Promise<void> {
+		const dir = this.requireInit()
+		// One JSON object per line, exactly like `transcript.jsonl` — but its
+		// own file, on its own sequence space (`AuditEvent.seq`), because an
+		// audit trail sharing bytes with an operational log inherits that
+		// log's operational habits (rotation, truncation) whether or not
+		// anyone intended them to apply here.
+		await appendFile(join(dir, 'audit.jsonl'), `${JSON.stringify(event)}\n`, 'utf-8')
+	}
+
+	async readAuditEvents(): Promise<readonly AuditEvent[]> {
+		const dir = this.requireInit()
+		let raw: string
+		try {
+			raw = await readFile(join(dir, 'audit.jsonl'), 'utf-8')
+		} catch (err) {
+			if (isFileNotFound(err)) return []
+			throw err
+		}
+
+		const events: AuditEvent[] = []
+		for (const line of raw.split('\n')) {
+			if (line.length === 0) continue
+			try {
+				events.push(JSON.parse(line) as AuditEvent)
+			} catch {
+				// A torn last line is the normal shape of a file that was being
+				// appended to when the process died — the same failure mode
+				// `readRunEventsIn` skips past for `transcript.jsonl`, and for
+				// the same reason: every whole line before it is still good,
+				// and refusing the whole trail over one incomplete tail entry
+				// would discard evidence the crash did not actually destroy.
+				//
+				// Deliberately empty: the skip IS the handling. There was a
+				// `continue` here, which read as intent but sat last in the
+				// loop body and did nothing.
+			}
+		}
+		return events
+	}
+
 	/**
 	 * Every tool call this run has already finished, keyed by `toolUseId`.
 	 *
@@ -165,7 +214,7 @@ export class RunDiskStore implements RunStore {
 
 		const reportPath = join(dir, 'report.md')
 		await atomicWriteFile(reportPath, content)
-		this.log.info(`Report written: ${reportPath}`)
+		this.log.info('Report written', { 'namzu.run.report_path': reportPath })
 		return reportPath
 	}
 
@@ -400,6 +449,29 @@ async function healTornTranscript(runDir: string): Promise<void> {
 	await appendFile(path, '\n', 'utf-8')
 }
 
+/**
+ * Terminate an audit trail whose last line was cut off mid-write.
+ *
+ * Same failure mode {@link healTornTranscript} exists for, on `audit.jsonl`'s
+ * own file: a process killed mid-`appendFile` leaves a fragment with no
+ * newline, and the NEXT append would land on that same line — merging a
+ * whole, correct event into an unparsable one and losing BOTH rather than
+ * just the fragment. Called from `initRun`, the only moment the store knows
+ * nothing is mid-write, exactly like its transcript counterpart.
+ */
+async function healTornAuditTrail(runDir: string): Promise<void> {
+	const path = join(runDir, 'audit.jsonl')
+	let raw: string
+	try {
+		raw = await readFile(path, 'utf-8')
+	} catch (err) {
+		if (isFileNotFound(err)) return
+		throw err
+	}
+	if (raw.length === 0 || raw.endsWith('\n')) return
+	await appendFile(path, '\n', 'utf-8')
+}
+
 /**
  * Every checkpoint stored under one run directory, ascending by `createdAt`.
  *

package/src/store/run/listing.ts

@@ -14,16 +14,16 @@ import type {
 	CheckpointListingScope,
 	CheckpointRunScope,
 	CheckpointStore,
-	ClaimFence,
 	ClaimRunOptions,
-	ClaimSummary,
 	DurableRunEntry,
 	DurableRunOrder,
 	DurableRunPage,
+	FencingToken,
+	LeaseSummary,
 	ListDurableRunsOptions,
 	ParkState,
 	ParkSummary,
-	RunClaim,
+	RunLease,
 } from '../../types/run/checkpoint-store.js'
 
 /** Page size when the caller names none. */
@@ -341,7 +341,7 @@ export async function claimRun(
 	store: CheckpointStore,
 	scope: CheckpointRunScope,
 	options: ClaimRunOptions,
-): Promise<RunClaim | null> {
+): Promise<RunLease | null> {
 	if (typeof store.claimRun !== 'function') {
 		throw new NamzuError({
 			code: 'capability_unavailable',
@@ -370,7 +370,7 @@ export async function claimRun(
 export async function releaseRun(
 	store: CheckpointStore,
 	scope: CheckpointRunScope,
-	fence: ClaimFence,
+	fence: FencingToken,
 ): Promise<void> {
 	if (typeof store.releaseRun !== 'function') {
 		throw new NamzuError({
@@ -409,7 +409,7 @@ export function fencedOut(
  * Whether a recorded claim still holds at `now`, and the summary a listing
  * reports for it.
  */
-export function toClaimSummary(claim: RunClaim, now: number): ClaimSummary {
+export function toClaimSummary(claim: RunLease, now: number): LeaseSummary {
 	return {
 		holder: claim.holder,
 		fence: claim.fence,