Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
@@ -0,0 +1,174 @@
import { mkdtemp, readFile, rm, stat } from 'node:fs/promises'
import { tmpdir } from 'node:os'
import { join } from 'node:path'
import { afterEach, beforeEach, describe, expect, it } from 'vitest'
import Database from '../../sqlite/sync-database'
import { journalPragmaNumber, openJournalDatabase, runJournalTransaction } from './journal-database'
import {
createAgentSessionRecordTablesSql,
createJournalTablesSql,
JOURNAL_DB_SCHEMA_VERSION
} from './journal-database-schema'
import { journalDatabasePath } from './journal-host-database'
import {
closeTestJournalHostDatabases,
openTestJournalHostDatabase
} from './journal-host-database-test-support'
import { insertCommandReceiptIfAbsent, readCommandReceipt } from './command-receipt-table'
import { commandReceiptScope } from './command-receipt-schema'
import {
commandReceiptFixture,
writeCommandReceiptTestRecord
} from './command-receipt-test-support'
import { AgentSessionJournalError } from './journal-write-guards'
import { buildCommandReceiptTransaction } from './command-receipt-transaction'

let root: string
let dbPath: string
const scope = commandReceiptScope('caller-1', 'global')

beforeEach(async () => {
root = await mkdtemp(join(tmpdir(), 'orca-command-receipt-schema-'))
dbPath = journalDatabasePath(root)
})

afterEach(async () => {
closeTestJournalHostDatabases()
await rm(root, { recursive: true, force: true })
})

function hasReceiptTable(db: Database.Database): boolean {
return Boolean(
db
.prepare("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = ?")
.get('agent_session_command_receipts')
)
}

describe('command receipt schema at writable open', () => {
it('creates the operation/caller primary key and session index on a fresh host database', () => {
const database = openTestJournalHostDatabase(root)
expect(hasReceiptTable(database.db)).toBe(true)
expect(journalPragmaNumber(database.db, 'user_version')).toBe(JOURNAL_DB_SCHEMA_VERSION)
expect(database.db.prepare('PRAGMA table_info(agent_session_command_receipts)').all()).toEqual([
expect.objectContaining({ name: 'operation_id', pk: 1 }),
expect.objectContaining({ name: 'session_id', pk: 0 }),
expect.objectContaining({ name: 'caller_key', pk: 2 }),
expect.objectContaining({ name: 'method', pk: 0 }),
expect.objectContaining({ name: 'fingerprint', pk: 0 }),
expect.objectContaining({ name: 'status', pk: 0 }),
expect.objectContaining({ name: 'result_json', pk: 0 }),
expect.objectContaining({ name: 'rejection_json', pk: 0 }),
expect.objectContaining({ name: 'accepted_at', pk: 0 })
])
const indexes = database.db.prepare('PRAGMA index_list(agent_session_command_receipts)').all()
expect(indexes).toHaveLength(2)
expect(indexes).toEqual(
expect.arrayContaining([
expect.objectContaining({
name: 'sqlite_autoindex_agent_session_command_receipts_1',
origin: 'pk'
}),
expect.objectContaining({ name: 'agent_session_command_receipts_session', origin: 'c' })
])
)
expect(
database.db.prepare('PRAGMA index_info(agent_session_command_receipts_session)').all()
).toEqual([expect.objectContaining({ name: 'session_id' })])
expect(
database.db.prepare('PRAGMA foreign_key_list(agent_session_command_receipts)').all()
).toEqual([
expect.objectContaining({
table: 'agent_session_records',
from: 'session_id',
to: 'session_id',
on_delete: 'CASCADE'
})
])
})

it.each([3, 4])('adds the table to an older-shaped version %i database', (version) => {
const seeded = new Database(dbPath)
seeded.exec(createJournalTablesSql())
if (version === 4) {
seeded.exec(createAgentSessionRecordTablesSql())
writeCommandReceiptTestRecord(seeded)
}
seeded.pragma(`user_version = ${version}`)
expect(hasReceiptTable(seeded)).toBe(false)
seeded.close()

for (let open = 0; open < 2; open += 1) {
const { db, readOnly } = openJournalDatabase(dbPath)
try {
expect(readOnly).toBe(false)
expect(hasReceiptTable(db)).toBe(true)
expect(journalPragmaNumber(db, 'user_version')).toBe(4)
if (version === 4) {
expect(db.prepare('SELECT session_id FROM agent_session_records').all()).toEqual([
{ session_id: 'session-1' }
])
}
} finally {
db.close()
}
}
})
})

describe('command receipts on a newer database', () => {
it('reads receipts, refuses writes with the journal guard and leaves the file byte-identical', async () => {
const seeded = openJournalDatabase(dbPath).db
const receipt = commandReceiptFixture()
runJournalTransaction(seeded, (db) => {
writeCommandReceiptTestRecord(db)
insertCommandReceiptIfAbsent(db, scope, receipt)
})
seeded.pragma(`user_version = ${JOURNAL_DB_SCHEMA_VERSION + 1}`)
seeded.close()
const before = await readFile(dbPath)

const { db, readOnly } = openJournalDatabase(dbPath)
try {
expect(readOnly).toBe(true)
expect(readCommandReceipt(db, scope, receipt.operationId)).toEqual({
verdict: 'readable',
receipt
})
const write = () => insertCommandReceiptIfAbsent(db, scope, receipt)
expect(write).toThrow(AgentSessionJournalError)
expect(write).toThrow(expect.objectContaining({ code: 'journal_read_only' }))
expect(() => buildCommandReceiptTransaction(scope, receipt).write(db)).toThrow(
expect.objectContaining({ code: 'journal_read_only' })
)
} finally {
db.close()
}

expect(await readFile(dbPath)).toEqual(before)
expect((await stat(`${dbPath}-wal`).catch(() => null))?.size ?? 0).toBe(0)
})

it('does not create a missing table or mistake unavailable proof for an absent command', async () => {
const seeded = new Database(dbPath)
seeded.exec(createJournalTablesSql())
seeded.exec(createAgentSessionRecordTablesSql())
seeded.pragma(`user_version = ${JOURNAL_DB_SCHEMA_VERSION + 1}`)
seeded.close()
const before = await readFile(dbPath)

const { db } = openJournalDatabase(dbPath)
try {
const receipt = commandReceiptFixture()
expect(hasReceiptTable(db)).toBe(false)
expect(readCommandReceipt(db, scope, receipt.operationId)).toEqual({
verdict: 'unreadable',
scope,
operationId: receipt.operationId
})
} finally {
db.close()
}
expect(await readFile(dbPath)).toEqual(before)
})
})
Original file line number Diff line number Diff line change
@@ -0,0 +1,96 @@
import { isDeepStrictEqual } from 'node:util'
import { z } from 'zod'
import type Database from '../../sqlite/sync-database'
import { readAgentSessionRefusalReference } from '../../../shared/agent-session-wire-refusals'

export const commandReceiptScopeSchema = z.discriminatedUnion('kind', [
z.strictObject({ kind: z.literal('global') }),
z.strictObject({ kind: z.literal('caller'), callerKey: z.string().min(1) })
])

export type CommandReceiptScope = z.infer<typeof commandReceiptScopeSchema>

/** Sends look across callers; other methods look up only the authenticated caller's row. */
export function commandReceiptScope(
callerKey: string,
operationIdScope?: 'global'
): CommandReceiptScope {
return operationIdScope === 'global' ? { kind: 'global' } : { kind: 'caller', callerKey }
}

/** The pointer locates the result; if its row is gone, the command stays spent: read what remains, else unknown, never rerun. */
export const commandReceiptResultSchema = z.discriminatedUnion('kind', [
z.strictObject({
kind: z.literal('journal-row'),
epoch: z.string().min(1),
sequence: z.int().positive()
}),
z.strictObject({
kind: z.literal('no-op'),
outcome: z.discriminatedUnion('kind', [
z.strictObject({
kind: z.literal('cancel'),
cancelled: z.literal(false),
turnId: z.string().optional()
}),
z.strictObject({ kind: z.literal('queue-resume'), resumed: z.literal(false) })
])
})
])

export type CommandReceiptResult = z.infer<typeof commandReceiptResultSchema>

const rejectionSchema = z
.strictObject({ reference: z.unknown(), message: z.string().optional() })
.transform((value, ctx) => {
const reference = readAgentSessionRefusalReference(value.reference)
if (!reference || !isDeepStrictEqual(reference, value.reference)) {
ctx.addIssue({ code: 'custom', message: 'unreadable command refusal' })
return z.NEVER
}
return { reference, ...(value.message !== undefined ? { message: value.message } : {}) }
})

const receiptIdentity = {
operationId: z.string().min(1),
sessionId: z.string().min(1),
callerKey: z.string().min(1),
method: z.string().min(1),
fingerprint: z.string().min(1),
acceptedAt: z.int().nonnegative()
}

export const commandReceiptSchema = z.discriminatedUnion('status', [
z.strictObject({
...receiptIdentity,
status: z.literal('accepted'),
result: commandReceiptResultSchema
}),
z.strictObject({
...receiptIdentity,
status: z.literal('rejected'),
rejection: rejectionSchema
})
])

export type CommandReceipt = z.infer<typeof commandReceiptSchema>

/** Additive and inert until cutover; a version bump here would prevent older builds writing. */
export function ensureCommandReceiptsTable(db: Database.Database): void {
db.exec(`
CREATE TABLE IF NOT EXISTS agent_session_command_receipts (
operation_id TEXT NOT NULL,
session_id TEXT NOT NULL REFERENCES agent_session_records(session_id) ON DELETE CASCADE,
caller_key TEXT NOT NULL,
method TEXT NOT NULL,
fingerprint TEXT NOT NULL,
status TEXT NOT NULL,
result_json TEXT,
rejection_json TEXT,
accepted_at INTEGER NOT NULL,
PRIMARY KEY (operation_id, caller_key)
);
CREATE INDEX IF NOT EXISTS agent_session_command_receipts_session
ON agent_session_command_receipts (session_id);
`)
}
Loading
Loading