Adopt acknowledged store rows before receipt callbacks

This commit is contained in:
Brennan Benson
2026-11-08 14:14:53 -08:00
parent b7a48daf6a
commit 74a79991a7
10 changed files with 354 additions and 74 deletions
@@ -78,6 +78,11 @@ export class JournalSqlDatabase {
this.writer.onFault = listener
}
/** An invalid acknowledged result cannot become a stale base for another write. */
fault(error: Error): void {
this.writer.fault(error)
}
/** Start after runtime activity has been installed, so startup work never outruns live chats. */
startMaintenance(): Promise<void> {
this.assertOpen()
@@ -36,6 +36,10 @@ export class JournalSqlOwner {
private closed: Promise<void> | undefined
onFault: (error: Error) => void = () => {}
fault(error: Error): void {
this.fail(error)
}
constructor(
filename: string,
stateDirectory: string,
@@ -1,10 +1,7 @@
import { agentSessionAttachmentStoreRoot } from '../agent-session-attachments/agent-session-attachment-references'
import type Database from '../../sqlite/sync-database'
import type { AgentSessionStoreRowWrites } from '../../runtime/agent-session/records/agent-session-store-draft'
import {
insertAgentSessionOperationRowsIfAbsent,
writeAgentSessionStoreRows
} from '../../runtime/agent-session/records/agent-session-record-rows'
import { applyJournalWriterStoreEffect } from './journal-writer-store-effect'
import {
claimAgentSessionAttachmentsInTransaction,
finishUploadSweep,
@@ -63,6 +60,13 @@ export type JournalWriterEffectResult =
| boolean
| number
| null
| JournalWriterStoreResult
export type JournalWriterStoreResult = {
kind: 'store'
disposition: 'applied' | 'noop'
writes: AgentSessionStoreRowWrites
}
/** Host-computed values still recheck uniqueness and sweep authority on the sole connection. */
export function applyJournalWriterEffect(
@@ -72,19 +76,8 @@ export function applyJournalWriterEffect(
rows: readonly (JournalRow | JournalWriterCoordinate)[] = []
): JournalWriterEffectResult {
switch (effect.kind) {
case 'store': {
const { writes } = effect
if (effect.insertOperationsIfAbsent) {
insertAgentSessionOperationRowsIfAbsent(db, writes.operations.upsert)
}
writeAgentSessionStoreRows(
db,
effect.insertOperationsIfAbsent
? { ...writes, operations: { ...writes.operations, upsert: [] } }
: writes
)
return null
}
case 'store':
return applyJournalWriterStoreEffect(db, effect)
case 'receipt': {
const row = effect.row && (effect.row.at === 'first' ? rows[0] : rows.at(-1))
const receipt = effect.row ? boundReceipt(effect.receipt, effect.row, row) : effect.receipt
@@ -0,0 +1,59 @@
import type Database from '../../sqlite/sync-database'
import type { AgentSessionStoreRowWrites } from '../../runtime/agent-session/records/agent-session-store-draft'
import {
insertAgentSessionOperationRowsIfAbsent,
writeAgentSessionStoreRows
} from '../../runtime/agent-session/records/agent-session-record-rows'
import type { JournalWriterEffect, JournalWriterStoreResult } from './journal-writer-effects'
/** Return the touched rows at the writer position, never a host's provisional copy. */
export function applyJournalWriterStoreEffect(
db: Database.Database,
effect: Extract<JournalWriterEffect, { kind: 'store' }>
): JournalWriterStoreResult {
const { writes } = effect
if (effect.insertOperationsIfAbsent) {
insertAgentSessionOperationRowsIfAbsent(db, writes.operations.upsert)
}
writeAgentSessionStoreRows(
db,
effect.insertOperationsIfAbsent
? { ...writes, operations: { ...writes.operations, upsert: [] } }
: writes
)
return {
kind: 'store',
disposition: 'applied',
writes: {
...writes,
records: resolvedRows(writes.records, (key) =>
db
.prepare('SELECT record_json AS json FROM agent_session_records WHERE session_id=?')
.get(key)
),
operations: resolvedRows(writes.operations, (key) =>
db
.prepare('SELECT row_json AS json FROM agent_session_operations WHERE operation_key=?')
.get(key)
)
}
}
}
function resolvedRows(
touched: AgentSessionStoreRowWrites['records'],
read: (key: string) => { json?: unknown } | undefined
): AgentSessionStoreRowWrites['records'] {
const result: AgentSessionStoreRowWrites['records'] = { upsert: [], remove: [] }
for (const key of new Set([...touched.upsert.map(([id]) => id), ...touched.remove])) {
const row = read(key)
if (!row) {
result.remove.push(key)
} else if (typeof row.json === 'string') {
result.upsert.push([key, row.json])
} else {
throw new Error('a written store row has no saved form')
}
}
return result
}
@@ -24,6 +24,8 @@ export type JournalReceiptStage = { savedAt: number; row?: JournalRow['kind'] }
* COMMIT with this receipt's results, or with undefined after a rollback or an unwritten receipt. */
export type JournalStagedReceipt = {
effects: readonly JournalWriterEffect[]
/** Resolve every co-staged store draft before any committed callback runs. */
adopt?: (results: readonly JournalWriterEffectResult[] | undefined) => void
settle: (results: readonly JournalWriterEffectResult[] | undefined) => void
}
@@ -59,15 +61,39 @@ async function stageJournalOperationReceipts(
staged.forEach((entry) => entry.settle(undefined))
throw error
}
const adopt: NonNullable<JournalStagedReceipt['adopt']> = (results) => {
let offset = 0
for (const entry of staged) {
const count = entry.effects.length
entry.adopt?.(results?.slice(offset, offset + count))
offset += count
}
}
return {
effects: staged.flatMap((entry) => entry.effects),
adopt,
settle: (results) => {
let failure: unknown
let adoptionFailed = false
try {
adopt(results)
} catch (error) {
failure = error
adoptionFailed = true
}
let offset = 0
for (const entry of staged) {
const count = entry.effects.length
entry.settle(results?.slice(offset, offset + count))
try {
entry.settle(adoptionFailed ? undefined : results?.slice(offset, offset + count))
} catch (error) {
failure ??= error
}
offset += count
}
if (failure !== undefined) {
throw failure
}
}
}
}
@@ -94,6 +120,7 @@ export function onJournalReceiptCommitted(
const staged = await stage(context)
return {
effects: staged.effects,
adopt: staged.adopt,
settle: (results) => {
staged.settle(results)
if (results !== undefined) {
@@ -54,6 +54,7 @@ export function createAgentSessionFoundingStore(
const staged = await receipt.stage(context)
return {
effects: staged.effects,
adopt: staged.adopt,
settle: (results) => {
staged.settle(results)
if (results) {
@@ -0,0 +1,45 @@
import { decodePersistedAgentSessionRecord } from '../../../../shared/agent-session/lifecycle/agent-session-record-stored-form'
import { AgentSessionTabTable } from '../agent-session-tab-table'
import type { AgentSessionStoreRowWrites } from './agent-session-store-draft'
import type { AgentSessionStoreState } from './agent-session-store-state'
import {
isReadableAgentSessionStoreOperation,
isReadableAgentSessionStoreRecord
} from './agent-session-store-row-rules'
/** Live adoption preserves the saved lease; startup's unreconciled policy does not apply. */
export function adoptAgentSessionStoreResolvedRows(
draft: AgentSessionStoreState,
writes: AgentSessionStoreRowWrites
): void {
for (const [id, json] of writes.records.upsert) {
const saved: unknown = JSON.parse(json)
if (!isReadableAgentSessionStoreRecord(id, saved)) {
throw new Error('the writer returned an unreadable record')
}
draft.records.set(id, decodePersistedAgentSessionRecord(saved).record)
}
for (const id of writes.records.remove) {
draft.records.delete(id)
}
for (const [key, json] of writes.operations.upsert) {
const saved: unknown = JSON.parse(json)
if (!isReadableAgentSessionStoreOperation(key, saved)) {
throw new Error('the writer returned an unreadable operation')
}
draft.operations.set(key, saved)
}
for (const key of writes.operations.remove) {
draft.operations.delete(key)
}
if (writes.retiredClaimKeys !== null) {
draft.retiredClaimKeys = writes.retiredClaimKeys
}
if (writes.sessionTabs !== null) {
draft.sessionTabs = writes.sessionTabs.recorded
? new AgentSessionTabTable(
writes.sessionTabs.tabs.map(({ tabId, sessionId }) => [tabId, sessionId])
)
: null
}
}
@@ -4,7 +4,10 @@ import { tmpdir } from 'node:os'
import { join } from 'node:path'
import { afterEach, beforeEach, describe, expect, it } from 'vitest'
import type { AgentSessionRecord } from '../../../../shared/agent-session/lifecycle/agent-session-record'
import { composeJournalOperationReceipts } from '../../../native-chat/agent-session-journal/writing/journal-row-writer'
import {
composeJournalOperationReceipts,
onJournalReceiptCommitted
} from '../../../native-chat/agent-session-journal/writing/journal-row-writer'
import type { AgentSessionRecordStore } from './agent-session-record-store'
import {
closeTestAgentSessionRecordStores,
@@ -196,7 +199,8 @@ describe('a receipt', () => {
expect(store.getOperationRow('client-1', operationId)?.outcome.status).toBe('pending')
const committed = await store.operationOutcomeReceipt(args).stage!({ savedAt: NOW })
committed.settle([null])
const database = await openTestAgentSessionDatabase(root)
committed.settle(await database.effects(committed.effects))
expect(store.getRecord('chat-a-0001')).toMatchObject({
conversationName: 'after',
usageLimitContinueCancel: cancel
@@ -229,4 +233,74 @@ describe('a receipt', () => {
)
expect(await persistedStatus()).toBe('succeeded')
})
it('publishes actual writer rows before co-staged callbacks and the next store transaction', async () => {
const store = await pendingOperation()
const forkedFrom = {
sessionId: 'chat-parent',
itemId: 'turn-1',
childBoundary: { kind: 'start' as const }
}
const actual = {
usageLimitContinueCancel: cancel,
forkedFrom,
options: { interactionMode: 'plan' }
}
const composed = composeJournalOperationReceipts(
onJournalReceiptCommitted(
store.operationOutcomeReceipt({
callerKey: 'client-1',
operationId,
outcome,
record: change
}),
() => {
expect(store.getRecord('chat-a-0001')).toMatchObject(actual)
expect(store.getRecord('chat-a-0001')?.lease.unreconciled).toBe(false)
}
),
store.conversationReceipts.forkBoundary('chat-a-0001', forkedFrom)
)
const staged = await composed.stage!({ savedAt: NOW })
const later = store.setConversationName('chat-a-0001', 'after')
await withTestAgentSessionDatabase(root, (db) =>
db.exec(
"CREATE TRIGGER bind_record AFTER UPDATE ON agent_session_records BEGIN UPDATE agent_session_records SET record_json=json_set(NEW.record_json, '$.options.interactionMode', 'plan') WHERE session_id=NEW.session_id; END"
)
)
const database = await openTestAgentSessionDatabase(root)
const results = await database.effects(staged.effects)
await withTestAgentSessionDatabase(root, (db) => db.exec('DROP TRIGGER bind_record'))
staged.settle(results)
await later
expect(store.getRecord('chat-a-0001')).toMatchObject({ ...actual, conversationName: 'after' })
expect((await openTestAgentSessionRecordStore(root)).getRecord('chat-a-0001')).toMatchObject({
...actual,
conversationName: 'after'
})
})
it('fences later writes when a committed store acknowledgement has no resolved rows', async () => {
const store = await pendingOperation()
const staged = await store.operationOutcomeReceipt({
callerKey: 'client-1',
operationId,
outcome,
record: change
}).stage!({ savedAt: NOW })
const database = await openTestAgentSessionDatabase(root)
await database.effects(staged.effects)
expect(() => staged.settle([])).toThrow('missing store results')
expect(store.getRecord('chat-a-0001')?.usageLimitContinueCancel).toBeUndefined()
await expect(store.setConversationName('chat-a-0001', 'stale')).rejects.toThrow(
'missing store results'
)
await withTestAgentSessionDatabase(root, (db) => {
const row = db
.prepare('SELECT record_json FROM agent_session_records WHERE session_id=?')
.get('chat-a-0001')!
expect(JSON.parse(String(row.record_json))).toMatchObject({
usageLimitContinueCancel: cancel
})
expect(JSON.parse(String(row.record_json)).conversationName).not.toBe('stale')
})
})
})
@@ -1,4 +1,5 @@
import { sessionCrewChanges } from '../../orchestration/crew/crew-changes'
import { isDeepStrictEqual } from 'node:util'
import type { JournalSqlDatabase } from '../../../native-chat/agent-session-journal/database/journal-sql-database'
import type { JournalWriterEffectResult } from '../../../native-chat/agent-session-journal/journal-writer-effects'
import type { JournalOperationReceipt } from '../../../native-chat/agent-session-journal/writing/journal-row-writer'
@@ -166,7 +167,14 @@ export class AgentSessionStoreTransactions {
refusal: () => (this.journalDatabase.readOnly ? readOnlyStoreRefusal() : undefined),
lanes: this.writerLanes,
stage: (run, base) => this.stage(run, base),
admit: (sessionId) => this.admitSend(sessionId)
admit: (sessionId) => this.admitSend(sessionId),
publish: (draft) =>
this.publish(
draft,
this.published,
agentSessionStoreDraftRowWrites(this.published, draft)
),
fault: (error) => this.journalDatabase.fault(error)
},
{ apply, ...options },
context
@@ -226,52 +234,60 @@ export class AgentSessionStoreTransactions {
result,
draft,
writes,
adopt: () => {
if (writes) {
freezeRows(draft, writes)
if (changesAgentSenderIdentity(published, draft, writes)) {
this.senderIdentityRevision++
}
this.published = draft
const lineageChanged =
writes.records.remove.length > 0 ||
writes.records.upsert.some(([id]) => {
const before = published.records.get(id)
return before?.conversationCommand !== draft.records.get(id)?.conversationCommand
})
if (lineageChanged) {
this.lineage = {}
}
const topologyChanged =
writes.sessionTabs !== null ||
writes.records.remove.length > 0 ||
writes.records.upsert.some(([id]) => {
const before = published.records.get(id)
const after = draft.records.get(id)
return (
!before ||
!after ||
before.lease.claimStatus !== after.lease.claimStatus ||
before.provider !== after.provider ||
before.location !== after.location ||
before.conversationCommand !== after.conversationCommand
)
})
const renamed = writes.records.upsert
.filter(
([id]) =>
published.records.get(id)?.conversationName !==
draft.records.get(id)?.conversationName
)
.map(([id]) => id)
if (topologyChanged) {
sessionCrewChanges.notify(new Set(['records']))
} else if (renamed.length) {
sessionCrewChanges.notify(
Object.assign(new Set(['names'] as const), { recordIds: renamed })
)
}
}
adopt: () => this.publish(draft, published, writes)
}
}
private publish(
draft: AgentSessionStoreState,
published: AgentSessionStoreState,
writes: AgentSessionStoreRowWrites | null
): void {
if (writes) {
freezeRows(draft, writes)
if (changesAgentSenderIdentity(published, draft, writes)) {
this.senderIdentityRevision++
}
this.published = draft
const lineageChanged =
writes.records.remove.length > 0 ||
writes.records.upsert.some(([id]) => {
const before = published.records.get(id)
return !isDeepStrictEqual(
before?.conversationCommand,
draft.records.get(id)?.conversationCommand
)
})
if (lineageChanged) {
this.lineage = {}
}
const topologyChanged =
writes.sessionTabs !== null ||
writes.records.remove.length > 0 ||
writes.records.upsert.some(([id]) => {
const before = published.records.get(id)
const after = draft.records.get(id)
return (
!before ||
!after ||
before.lease.claimStatus !== after.lease.claimStatus ||
before.provider !== after.provider ||
!isDeepStrictEqual(before.location, after.location) ||
!isDeepStrictEqual(before.conversationCommand, after.conversationCommand)
)
})
const renamed = writes.records.upsert
.filter(
([id]) =>
published.records.get(id)?.conversationName !== draft.records.get(id)?.conversationName
)
.map(([id]) => id)
if (topologyChanged) {
sessionCrewChanges.notify(new Set(['records']))
} else if (renamed.length) {
sessionCrewChanges.notify(
Object.assign(new Set(['names'] as const), { recordIds: renamed })
)
}
}
}
@@ -7,9 +7,15 @@ import {
type AgentSessionStoreState
} from './agent-session-store-state'
import type { StagedStoreTransaction } from './agent-session-store-transactions'
import { draftAgentSessionStoreState } from './agent-session-store-draft'
import { adoptAgentSessionStoreResolvedRows } from './agent-session-store-resolved-rows'
type StoreWriterLane = {
draft: AgentSessionStoreState
resolved: AgentSessionStoreState
pending: number
committed: boolean
failed: boolean
/** Staged receipts not yet settled; the lane releases when none remain. */
open: number
release: () => void
@@ -47,7 +53,16 @@ export class AgentSessionStoreWriterLanes {
this.enqueue(
() =>
new Promise<void>((release) => {
const lane = { draft: this.published(), open: 0, release }
const draft = this.published()
const lane = {
draft,
resolved: draftAgentSessionStoreState(draft),
pending: 0,
committed: false,
failed: false,
open: 0,
release
}
this.lanes.set(context, lane)
resolve(lane)
})
@@ -73,6 +88,8 @@ export async function stageAgentSessionStoreReceipt(
base: AgentSessionStoreState
) => StagedStoreTransaction<void>
admit: (sessionId: string) => void
publish: (draft: AgentSessionStoreState) => void
fault: (error: Error) => void
},
receipt: {
apply: (draft: AgentSessionStoreState) => void
@@ -99,21 +116,60 @@ export async function stageAgentSessionStoreReceipt(
}
lane.draft = staged.draft
lane.open++
lane.pending++
const { writes } = staged
let resolved = false
let settled = false
const adopt: NonNullable<JournalStagedReceipt['adopt']> = (results) => {
if (resolved) {
return
}
resolved = true
lane.pending--
try {
if (results !== undefined) {
if (results.length !== (writes ? 1 : 0)) {
throw new Error('the writer returned missing store results')
}
for (const result of results) {
if (
!result ||
typeof result !== 'object' ||
!('kind' in result) ||
result.kind !== 'store'
) {
throw new Error('the writer returned a different store result')
}
adoptAgentSessionStoreResolvedRows(lane.resolved, result.writes)
}
lane.committed = true
}
if (lane.pending === 0 && lane.committed && !lane.failed) {
deps.publish(lane.resolved)
}
} catch (error) {
lane.failed = true
deps.fault(error instanceof Error ? error : new Error(String(error)))
throw error
}
}
return {
effects: writes
? [{ kind: 'store', writes, insertOperationsIfAbsent: !!receipt.insertOperationsIfAbsent }]
: [],
adopt,
settle: (results) => {
lane.open--
if (settled) {
return
}
settled = true
try {
if (results) {
staged.adopt()
if (admitted) {
deps.admit(admitted)
}
adopt(results)
if (results !== undefined && !lane.failed && admitted) {
deps.admit(admitted)
}
} finally {
lane.open--
deps.lanes.settle(context, lane)
}
}