@namzu/sdk 14.0.6 → 15.0.0

package/src/store/__tests__/checkpoint-versioning.test.ts

@@ -1,194 +0,0 @@
-import { mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises'
-import { tmpdir } from 'node:os'
-import { join } from 'node:path'
-import { afterEach, beforeEach, describe, expect, it } from 'vitest'
-
-import type { CheckpointId, IterationCheckpoint } from '../../types/hitl/index.js'
-import type { RunId } from '../../types/ids/index.js'
-import { RunDiskStore } from '../run/disk.js'
-
-/**
- * A checkpoint was written bare and read with a cast. Two consequences,
- * one latent and one live.
- *
- * Latent: an unstamped record is read as version 1 by definition, which is
- * correct only while version 1 is the only version there has ever been.
- * The moment a second exists, a file written by the newer build is read by
- * the older one as if it were the older shape, and the refusal that exists
- * to prevent exactly that never fires. There was no chain to hang a
- * migration on.
- *
- * Live: the read validated `id`, `iteration`, `createdAt` and `messages`
- * and skipped the budget fields — which a resume dereferences before its
- * first iteration. A run recalled at $4.80 of a $5 cap whose `costInfo`
- * came back malformed continues with `NaN`, which compares false against
- * every limit, so the guard that exists to stop it never stops it.
- */
-
-const RID = 'run_1' as RunId
-
-function checkpoint(overrides: Partial<IterationCheckpoint> = {}): IterationCheckpoint {
-	return {
-		id: 'cp_1' as CheckpointId,
-		runId: RID,
-		iteration: 2,
-		messages: [],
-		tokenUsage: {
-			promptTokens: 100,
-			completionTokens: 50,
-			totalTokens: 150,
-			cachedTokens: 0,
-			cacheWriteTokens: 0,
-		},
-		costInfo: { totalCost: 4.8 } as never,
-		guardState: { iterationCount: 2, elapsedMs: 1_000 },
-		createdAt: Date.now(),
-		...overrides,
-	}
-}
-
-describe('a checkpoint on disk', () => {
-	let dir: string
-	let store: RunDiskStore
-
-	beforeEach(async () => {
-		dir = await mkdtemp(join(tmpdir(), 'namzu-cpver-'))
-		store = new RunDiskStore({ baseDir: dir })
-		await store.initRun(RID)
-	})
-
-	afterEach(async () => {
-		await rm(dir, { recursive: true, force: true })
-	})
-
-	const writeRaw = async (name: string, record: unknown) => {
-		const cpDir = join(dir, RID, 'checkpoints')
-		await mkdir(cpDir, { recursive: true })
-		await writeFile(join(cpDir, `${name}.json`), JSON.stringify(record), 'utf-8')
-	}
-
-	it('is stamped ON DISK with the schema version it was written at', async () => {
-		await store.writeCheckpoint(checkpoint())
-
-		// Read the file, not the store: the reader re-stamps whatever it
-		// parses, so asking the store back cannot tell a stamped file from
-		// an unstamped one. The stamp only does its job if it is in the
-		// bytes another build will read.
-		const raw = JSON.parse(await readFile(join(dir, RID, 'checkpoints', 'cp_1.json'), 'utf-8')) as {
-			schemaVersion?: number
-		}
-		expect(raw.schemaVersion).toBe(1)
-	})
-
-	it('round-trips through the stamp without losing anything', async () => {
-		const original = checkpoint({ iteration: 7 })
-		await store.writeCheckpoint(original)
-
-		const read = await store.readCheckpoint(original.id)
-		expect(read?.iteration).toBe(7)
-		expect(read?.tokenUsage.totalTokens).toBe(150)
-	})
-
-	it('reads an unstamped record written before this existed', async () => {
-		// Optional-additive is the established practice here; an older file
-		// must keep working.
-		const { ...bare } = checkpoint({ id: 'cp_old' as CheckpointId })
-		await writeRaw('cp_old', bare)
-
-		expect((await store.readCheckpoint('cp_old' as CheckpointId))?.iteration).toBe(2)
-	})
-
-	it('refuses a record from a future version rather than reading it partially', async () => {
-		await writeRaw('cp_future', {
-			...checkpoint({ id: 'cp_future' as CheckpointId }),
-			schemaVersion: 99,
-		})
-
-		// Reading it with today's parser silently drops the fields this
-		// build does not know about, and writing it back loses them.
-		await expect(store.readCheckpoint('cp_future' as CheckpointId)).rejects.toThrow(
-			/schema version 99/,
-		)
-	})
-})
-
-describe('budget state a resume dereferences', () => {
-	let dir: string
-	let store: RunDiskStore
-
-	beforeEach(async () => {
-		dir = await mkdtemp(join(tmpdir(), 'namzu-cpbudget-'))
-		store = new RunDiskStore({ baseDir: dir })
-		await store.initRun(RID)
-	})
-
-	afterEach(async () => {
-		await rm(dir, { recursive: true, force: true })
-	})
-
-	const writeRaw = async (name: string, record: unknown) => {
-		const cpDir = join(dir, RID, 'checkpoints')
-		await mkdir(cpDir, { recursive: true })
-		await writeFile(join(cpDir, `${name}.json`), JSON.stringify(record), 'utf-8')
-	}
-
-	it('refuses a checkpoint with no cost information', async () => {
-		const { costInfo: _dropped, ...rest } = checkpoint({ id: 'cp_nocost' as CheckpointId })
-		await writeRaw('cp_nocost', rest)
-
-		// A run that resumes with an undefined cap is worse than one that
-		// refuses to resume: it looks healthy and never stops.
-		await expect(store.readCheckpoint('cp_nocost' as CheckpointId)).rejects.toThrow(
-			/malformed budget state/,
-		)
-	})
-
-	it('refuses a NaN budget, which compares false against every limit', async () => {
-		await writeRaw('cp_nan', {
-			...checkpoint({ id: 'cp_nan' as CheckpointId }),
-			// JSON has no NaN; this is what a serialized one becomes.
-			costInfo: { totalCost: null },
-		})
-
-		await expect(store.readCheckpoint('cp_nan' as CheckpointId)).rejects.toThrow(
-			/malformed budget state/,
-		)
-	})
-
-	it('refuses a missing guard state', async () => {
-		const { guardState: _dropped, ...rest } = checkpoint({ id: 'cp_noguard' as CheckpointId })
-		await writeRaw('cp_noguard', rest)
-
-		await expect(store.readCheckpoint('cp_noguard' as CheckpointId)).rejects.toThrow(
-			/malformed budget state/,
-		)
-	})
-
-	it('applies the same refusal to the listing path', async () => {
-		// Two read paths disagreeing about whether damage matters is how the
-		// lenient one gets trusted.
-		const { costInfo: _dropped, ...rest } = checkpoint({ id: 'cp_listed' as CheckpointId })
-		await writeRaw('cp_listed', rest)
-
-		await expect(store.listCheckpoints()).rejects.toThrow(/malformed budget state/)
-	})
-
-	it('accepts a zero budget, which is a real value', async () => {
-		await store.writeCheckpoint(
-			checkpoint({
-				id: 'cp_zero' as CheckpointId,
-				tokenUsage: {
-					promptTokens: 0,
-					completionTokens: 0,
-					totalTokens: 0,
-					cachedTokens: 0,
-					cacheWriteTokens: 0,
-				},
-				costInfo: { totalCost: 0 } as never,
-				guardState: { iterationCount: 0, elapsedMs: 0 },
-			}),
-		)
-
-		expect(await store.readCheckpoint('cp_zero' as CheckpointId)).not.toBeNull()
-	})
-})

package/src/store/__tests__/schema-adoption.test.ts

@@ -1,118 +0,0 @@
-import { mkdtempSync, rmSync } from 'node:fs'
-import { readFile, writeFile } from 'node:fs/promises'
-import { tmpdir } from 'node:os'
-import { join } from 'node:path'
-import { afterEach, beforeEach, describe, expect, it } from 'vitest'
-
-import type { ProjectId, SessionId, TenantId, ThreadId, UserId } from '../../types/ids/index.js'
-import { createUserMessage } from '../../types/message/index.js'
-import type { ActorRef } from '../../types/session/actor.js'
-import { DiskSessionStore } from '../session/disk.js'
-
-/**
- * The primitive is unit-tested next door. What matters here is that a store
- * actually goes through it — a version that is stamped but never checked,
- * or checked but never stamped, is the same silent read it replaces.
- */
-
-const TENANT = 'tnt_schema' as TenantId
-const THREAD = 'thd_schema' as ThreadId
-
-const actor = (): ActorRef => ({ kind: 'user', userId: 'usr_a' as UserId, tenantId: TENANT })
-
-let rootDir: string
-let store: DiskSessionStore
-
-beforeEach(() => {
-	rootDir = mkdtempSync(join(tmpdir(), 'namzu-schema-'))
-	store = new DiskSessionStore({ rootDir })
-})
-
-afterEach(() => {
-	rmSync(rootDir, { recursive: true, force: true })
-})
-
-async function seed(): Promise<{ projectId: ProjectId; sessionId: SessionId }> {
-	const project = await store.createProject({ tenantId: TENANT, name: 'p' }, TENANT)
-	const session = await store.createSession(
-		{ threadId: THREAD, projectId: project.id, currentActor: actor() },
-		TENANT,
-	)
-	return { projectId: project.id, sessionId: session.id }
-}
-
-const sessionPath = (projectId: ProjectId, sessionId: SessionId) =>
-	join(rootDir, 'projects', projectId, 'sessions', sessionId, 'session.json')
-
-describe('what lands on disk', () => {
-	it('stamps a session record', async () => {
-		const { projectId, sessionId } = await seed()
-		const raw = JSON.parse(await readFile(sessionPath(projectId, sessionId), 'utf-8'))
-		expect(raw.schemaVersion).toBe(1)
-	})
-
-	it('stamps every line of the append-only message log', async () => {
-		const { projectId, sessionId } = await seed()
-		await store.appendMessage(sessionId, createUserMessage('one'), TENANT)
-		await store.appendMessage(sessionId, createUserMessage('two'), TENANT)
-
-		const log = await readFile(
-			join(rootDir, 'projects', projectId, 'sessions', sessionId, 'messages.jsonl'),
-			'utf-8',
-		)
-		const lines = log.split('\n').filter((l) => l.length > 0)
-		expect(lines).toHaveLength(2)
-		// An append-only log is written by many builds over its lifetime, so
-		// its lines can legitimately differ in version — each carries its own.
-		for (const line of lines) expect(JSON.parse(line).schemaVersion).toBe(1)
-	})
-})
-
-describe('what comes back off disk', () => {
-	it('reads a legacy record that predates the stamp', async () => {
-		const { projectId, sessionId } = await seed()
-		const path = sessionPath(projectId, sessionId)
-		const record = JSON.parse(await readFile(path, 'utf-8'))
-		record.schemaVersion = undefined
-		await writeFile(path, JSON.stringify(record), 'utf-8')
-
-		// Every file written before this mechanism existed looks exactly
-		// like this, and has to keep opening.
-		expect(await store.getSession(sessionId, TENANT)).not.toBeNull()
-	})
-
-	it('refuses a record from a build that knew more than this one', async () => {
-		const { projectId, sessionId } = await seed()
-		const path = sessionPath(projectId, sessionId)
-		const record = JSON.parse(await readFile(path, 'utf-8'))
-		record.schemaVersion = 99
-		record.somethingThisBuildDoesNotKnow = { important: true }
-		await writeFile(path, JSON.stringify(record), 'utf-8')
-
-		// Reading it would drop the unknown field, and the next write would
-		// destroy it. A refusal is recoverable by upgrading.
-		await expect(store.getSession(sessionId, TENANT)).rejects.toThrow(/schema version 99/)
-	})
-
-	it('refuses a message line from the future rather than skipping it', async () => {
-		const { projectId, sessionId } = await seed()
-		await store.appendMessage(sessionId, createUserMessage('fine'), TENANT)
-
-		const path = join(rootDir, 'projects', projectId, 'sessions', sessionId, 'messages.jsonl')
-		const line = JSON.parse((await readFile(path, 'utf-8')).trim())
-		await writeFile(path, `${JSON.stringify({ ...line, schemaVersion: 42 })}\n`, 'utf-8')
-
-		// Silently dropping a message the build cannot read would hand the
-		// model a conversation with a hole in it.
-		await expect(store.loadMessages(sessionId, TENANT)).rejects.toThrow(/schema version 42/)
-	})
-
-	it('still round-trips a normal write and read', async () => {
-		const { sessionId } = await seed()
-		await store.appendMessage(sessionId, createUserMessage('hello'), TENANT)
-		await store.appendMessage(sessionId, createUserMessage('world'), TENANT)
-
-		const loaded = await store.loadMessages(sessionId, TENANT)
-		expect(loaded.map((m) => m.content)).toEqual(['hello', 'world'])
-	})
-})

package/src/store/__tests__/schema.test.ts

@@ -1,119 +0,0 @@
-import { describe, expect, it } from 'vitest'
-
-import {
-	INITIAL_SCHEMA_VERSION,
-	SchemaVersionError,
-	defineSchema,
-	migrate,
-	stamp,
-} from '../schema.js'
-
-/**
- * Every persisted read was `JSON.parse(raw) as T`. A record from an older
- * build arrived with fields missing and nothing said so; a record from a
- * NEWER build was read partially and, once written back, permanently lost
- * whatever this build did not understand.
- */
-
-const V1 = defineSchema({ kind: 'thing', current: 1, migrations: {} })
-
-const V3 = defineSchema({
-	kind: 'thing',
-	current: 3,
-	migrations: {
-		1: (r) => ({ ...r, addedInV2: true }),
-		2: (r) => ({ ...r, addedInV3: true }),
-	},
-})
-
-describe('reading an older record', () => {
-	it('treats an unstamped record as the first version', () => {
-		// Every file written before this mechanism existed IS version 1 —
-		// by definition, not by assumption.
-		const migrated = migrate<Record<string, unknown>>(V3, { name: 'legacy' })
-		expect(migrated.addedInV2).toBe(true)
-		expect(migrated.addedInV3).toBe(true)
-		expect(migrated.schemaVersion).toBe(3)
-	})
-
-	it('runs only the steps that are missing', () => {
-		const migrated = migrate<Record<string, unknown>>(V3, { schemaVersion: 2, name: 'x' })
-		expect(migrated.addedInV2).toBeUndefined()
-		expect(migrated.addedInV3).toBe(true)
-	})
-
-	it('leaves a current record alone apart from the stamp', () => {
-		const migrated = migrate<Record<string, unknown>>(V3, { schemaVersion: 3, name: 'x' })
-		expect(migrated).toEqual({ schemaVersion: 3, name: 'x' })
-	})
-})
-
-describe('reading a newer record', () => {
-	it('refuses rather than reading it partially', () => {
-		expect(() => migrate(V1, { schemaVersion: 2, name: 'from the future' })).toThrow(
-			SchemaVersionError,
-		)
-	})
-
-	it('says what it found and what it understands', () => {
-		try {
-			migrate(V1, { schemaVersion: 7 })
-			expect.unreachable()
-		} catch (err) {
-			const e = err as SchemaVersionError
-			expect(e.found).toBe(7)
-			expect(e.supported).toBe(1)
-			// A refusal is recoverable by upgrading. A partial read that
-			// gets written back is not.
-			expect(e.message).toContain('Upgrade')
-		}
-	})
-})
-
-describe('declaring a schema', () => {
-	it('rejects a gap in the migration chain at declaration time', () => {
-		// Discovered here, not in production by a user whose session will
-		// not open.
-		expect(() => defineSchema({ kind: 'gappy', current: 3, migrations: { 1: (r) => r } })).toThrow(
-			/no migration from version 2 to 3/,
-		)
-	})
-
-	it('rejects a version below the first one', () => {
-		expect(() => defineSchema({ kind: 'x', current: 0, migrations: {} })).toThrow(/integer >= 1/)
-	})
-
-	it('accepts a schema that has never migrated', () => {
-		expect(() =>
-			defineSchema({ kind: 'x', current: INITIAL_SCHEMA_VERSION, migrations: {} }),
-		).not.toThrow()
-	})
-})
-
-describe('stamping', () => {
-	it('marks a record with the version this build writes', () => {
-		expect(stamp(V3, { a: 1 })).toEqual({ a: 1, schemaVersion: 3 })
-	})
-
-	it('leaves an array untouched', () => {
-		// There is nowhere on an array to put a field that survives
-		// `JSON.stringify`, and wrapping it would change every file already
-		// written.
-		const list = [{ a: 1 }, { a: 2 }]
-		expect(stamp(V3, list)).toEqual(list)
-	})
-
-	it('round-trips through JSON', () => {
-		const written = JSON.stringify(stamp(V1, { name: 'x' }))
-		expect(migrate<Record<string, unknown>>(V1, JSON.parse(written))).toEqual({
-			name: 'x',
-			schemaVersion: 1,
-		})
-	})
-
-	it('passes a non-object through both ways', () => {
-		expect(stamp(V3, null)).toBeNull()
-		expect(migrate(V3, null)).toBeNull()
-		expect(migrate(V3, [1, 2])).toEqual([1, 2])
-	})
-})

package/src/store/session/__tests__/a-session-has-one-writer.test.ts

@@ -1,116 +0,0 @@
-import { describe, expect, it } from 'vitest'
-
-import { StaleSessionError } from '../../../session/errors.js'
-import type { TenantId } from '../../../types/ids/index.js'
-import type { Session } from '../../../types/session/entity.js'
-import { InMemorySessionStore } from '../memory.js'
-
-/**
- * `Session.ownerVersion` was documented as the CAS counter for handoff, and
- * nothing enforced it.
- *
- * Both stores overwrote unconditionally, so the only check was in the handoff
- * path — where it compared a snapshot read several awaits earlier against
- * itself. Two concurrent handoffs on one idle session both passed, both
- * provisioned a worktree, and one silently erased the other.
- *
- * The store is the arbiter now, because it is the only party that can compare
- * against the value at the instant of the write.
- */
-
-const TENANT = 'tnt_cas' as TenantId
-
-async function seed(): Promise<{ store: InMemorySessionStore; session: Session }> {
-	const store = new InMemorySessionStore()
-	const project = await store.createProject({ tenantId: TENANT, name: 'cas' }, TENANT)
-	const session = await store.createSession(
-		{ threadId: 'thd_cas' as never, projectId: project.id, currentActor: null },
-		TENANT,
-	)
-	return { store, session }
-}
-
-describe('a session write can require that nobody else wrote first', () => {
-	it('accepts a write naming the version the store holds', async () => {
-		const { store, session } = await seed()
-
-		await store.updateSession({ ...session, status: 'locked' }, TENANT, session.ownerVersion)
-
-		expect((await store.getSession(session.id, TENANT))?.status).toBe('locked')
-	})
-
-	it('refuses a write naming a version that has moved on', async () => {
-		const { store, session } = await seed()
-
-		// Somebody else takes it first.
-		await store.updateSession({ ...session, ownerVersion: 1 }, TENANT, 0)
-
-		await expect(
-			store.updateSession({ ...session, status: 'locked' }, TENANT, 0),
-		).rejects.toBeInstanceOf(StaleSessionError)
-	})
-
-	it('reports what the store holds, not what the caller sent', async () => {
-		// The caller already knows what it sent; the useful half of the answer
-		// is how far behind it is.
-		const { store, session } = await seed()
-		await store.updateSession({ ...session, ownerVersion: 7 }, TENANT, 0)
-
-		await store
-			.updateSession({ ...session, status: 'locked' }, TENANT, 3)
-			.then(() => expect.unreachable('the stale write should have been refused'))
-			.catch((err: StaleSessionError) => {
-				expect(err.details.expectedVersion).toBe(3)
-				expect(err.details.actualVersion).toBe(7)
-			})
-	})
-
-	it('compares against the STORED version, not the payload', async () => {
-		// The payload is the caller's own copy. Comparing it to itself is the
-		// check the handoff path was already making and getting nothing from,
-		// so a write whose payload agrees with itself must still be refused
-		// when the store has moved.
-		const { store, session } = await seed()
-		await store.updateSession({ ...session, ownerVersion: 5 }, TENANT, 0)
-
-		const selfConsistentButStale: Session = { ...session, ownerVersion: 2, status: 'locked' }
-
-		await expect(store.updateSession(selfConsistentButStale, TENANT, 2)).rejects.toBeInstanceOf(
-			StaleSessionError,
-		)
-	})
-
-	it('writes unconditionally when no version is named', async () => {
-		// The compatibility promise: every caller that existed before this
-		// parameter behaves exactly as it did.
-		const { store, session } = await seed()
-		await store.updateSession({ ...session, ownerVersion: 9 }, TENANT, 0)
-
-		await store.updateSession({ ...session, status: 'locked' }, TENANT)
-
-		expect((await store.getSession(session.id, TENANT))?.status).toBe('locked')
-	})
-
-	it('lets exactly one of two concurrent writers win', async () => {
-		// The defect, in the shape it actually took: two writers holding the
-		// same snapshot, racing for the same session.
-		const { store, session } = await seed()
-		const snapshot = session.ownerVersion
-
-		const results = await Promise.allSettled([
-			store.updateSession(
-				{ ...session, status: 'locked', ownerVersion: snapshot + 1 },
-				TENANT,
-				snapshot,
-			),
-			store.updateSession(
-				{ ...session, status: 'locked', ownerVersion: snapshot + 1 },
-				TENANT,
-				snapshot,
-			),
-		])
-
-		expect(results.filter((r) => r.status === 'fulfilled')).toHaveLength(1)
-		expect(results.filter((r) => r.status === 'rejected')).toHaveLength(1)
-	})
-})