Merge commit '878cc5c14af' into brennanb2025/native-chat-sqlite-host

This commit is contained in:
Brennan Benson
2026-11-08 10:52:20 -08:00
21 changed files with 2749 additions and 179 deletions
@@ -1,4 +1,7 @@
import { journalDomainItemReadColumns } from './journal-domain-item-read-columns'
import {
journalDomainItemReadColumns,
journalDomainItemLifecycleColumns
} from './journal-domain-item-read-columns'
import { journalDomainItemPlacement } from './journal-domain-item-placement'
import type Database from '../../sqlite/sync-database'
import type { AgentJournalRenderItem } from '../../../shared/agent-session/journal/agent-session-journal-types'
@@ -11,6 +14,8 @@ import {
refreshJournalDomainQueueFailureReports
} from './journal-domain-queue-failures'
import { reportedTurnItemId } from './queued-messages/journal-queue-failure-policy'
import type { JournalStopSettleFact } from './journal-writer-host-facts'
import { normalizeJournalDomainItemBody } from './journal-domain-item-normalization'
import { observeJournalDomainTurnScope } from './journal-domain-turn-scope'
export type JournalDomainCurrentItemWrite = {
@@ -21,6 +26,7 @@ export type JournalDomainCurrentItemWrite = {
ownerFence: number
executionOwner?: number | null
writtenSequence?: number
stopSettle?: JournalStopSettleFact
}
export function nextJournalDomainItemOrdinal(
@@ -48,9 +54,17 @@ export function writeJournalDomainCurrentItem(
throw new Error('journal item persistence requires its writer transaction')
}
const prefix = [target.sessionId, target.epoch] as const
const stopNote = journalDomainStopNote(input.item, (id) => {
const body = normalizeJournalDomainItemBody(
db,
target,
input.item,
input.previous?.item,
input.stopSettle
)
const item = body === input.item.body ? input.item : { ...input.item, body }
const stopNote = journalDomainStopNote(item, (id) => {
if (id === input.item.itemId) {
return input.item
return item
}
const row = db
.prepare(`SELECT payload_json FROM journal_items
@@ -75,8 +89,8 @@ export function writeJournalDomainCurrentItem(
db.prepare(`INSERT INTO journal_items(session_id,epoch,item_id,ordinal,revision,sequence,sequence_index,owner_fence,execution_owner,payload_json,
hidden,root,subagent_row,subagent_group_key,turn_marker,wire_bytes,turn_item_id,original_stop_note_json,
queue_command_turn,queue_failed_outcome,queue_failed_at,queue_failure_witnessed_through,queue_failure_report_turn_item_id,
placement_json,kind,message_role,turn_id,opener_item_id,context_clear,goal_transition,producer_agent_id,producer_parent_ref,producer_attempt,prompt,signed_out)
VALUES(?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?) ON CONFLICT(session_id,epoch,item_id) DO UPDATE SET
placement_json,kind,message_role,turn_id,opener_item_id,context_clear,goal_transition,producer_agent_id,producer_parent_ref,producer_attempt,prompt,signed_out,lifecycle_state,live_work,context_window,unverified_end,turn_completed_at)
VALUES(?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?) ON CONFLICT(session_id,epoch,item_id) DO UPDATE SET
ordinal=excluded.ordinal, revision=excluded.revision, sequence=excluded.sequence, sequence_index=excluded.sequence_index,
owner_fence=excluded.owner_fence, execution_owner=excluded.execution_owner, payload_json=excluded.payload_json,
hidden=excluded.hidden, root=excluded.root, subagent_row=excluded.subagent_row, subagent_group_key=excluded.subagent_group_key,
@@ -89,7 +103,8 @@ export function writeJournalDomainCurrentItem(
turn_id=excluded.turn_id,opener_item_id=excluded.opener_item_id,context_clear=excluded.context_clear,
goal_transition=excluded.goal_transition,producer_agent_id=excluded.producer_agent_id,
producer_parent_ref=excluded.producer_parent_ref,producer_attempt=excluded.producer_attempt,
prompt=excluded.prompt,signed_out=excluded.signed_out`).run(
prompt=excluded.prompt,signed_out=excluded.signed_out,lifecycle_state=excluded.lifecycle_state,live_work=excluded.live_work,
context_window=excluded.context_window,unverified_end=excluded.unverified_end,turn_completed_at=excluded.turn_completed_at`).run(
...prefix,
next.itemId,
input.ordinal,
@@ -113,7 +128,8 @@ export function writeJournalDomainCurrentItem(
failure.witnessedThrough,
failure.reportTurnItemId,
journalDomainItemPlacement(next),
...journalDomainItemReadColumns(next)
...journalDomainItemReadColumns(next),
...journalDomainItemLifecycleColumns(next)
)
writeJournalDomainItemNames(
db,
@@ -0,0 +1,190 @@
import type Database from '../../sqlite/sync-database'
import type {
AgentJournalRenderItem,
AgentJournalSubmission
} from '../../../shared/agent-session/journal/agent-session-journal-types'
import { readAgentJournalTurn } from '../../../shared/agent-session/lifecycle/agent-session-turn-record'
import { structuredAgentSessionStartFailureRowIdentity } from '../../../shared/agent-session/failures/structured-agent-session-start-failure-row-key'
import { agentJournalItemKey } from '../../../shared/agent-session/journal/agent-session-journal-item-key'
import { isHistoricalProviderTimelineItem } from '../agent-session-timeline/provider-timeline-history'
import {
journalDomainLatestStop,
journalDomainStopDecidesTurn
} from './journal-domain-item-normalization'
import { journalDomainContextHead } from './journal-sql-continuation-context'
import type { JournalStopSettleFact } from './journal-writer-host-facts'
/** Select current lifecycle obligations and their named turn/opener evidence, in render order. */
export function readJournalDomainGeneration(
db: Database.Database,
target: { sessionId: string; epoch: string },
startKey: string | undefined,
stopSettle?: JournalStopSettleFact,
exitScope?: { completedAt: number; ownerFence: number }
) {
const prefix = [target.sessionId, target.epoch] as const
const selected = new Map<
string,
{ item: AgentJournalRenderItem; ordinal: number; fence: number | undefined }
>()
const include = (row: Record<string, unknown>) => {
const item: AgentJournalRenderItem = JSON.parse(String(row.payload_json))
selected.set(item.itemId, {
item,
ordinal: Number(row.ordinal),
fence: row.fence == null ? undefined : Number(row.fence)
})
return item
}
const point = (key: string): AgentJournalRenderItem | null => {
const known = selected.get(key)
if (known) {
return known.item
}
const row = db
.prepare(`SELECT payload_json,ordinal,COALESCE(execution_owner,owner_fence) AS fence
FROM journal_items WHERE session_id=? AND epoch=? AND hidden=0 AND item_id=COALESCE(
(SELECT item_id FROM journal_item_aliases WHERE session_id=? AND epoch=? AND provider_item_id=?),?)`)
.get(...prefix, ...prefix, key, key)
return row ? include(row) : null
}
const dependencies = (item: AgentJournalRenderItem) => {
const parent = item.turnScope?.kind === 'turn' ? point(item.turnScope.turnItemId) : null
for (const turnItem of [item, parent]) {
const opener = readAgentJournalTurn(turnItem?.body)?.userItemId
if (opener) {
point(opener)
}
}
}
for (const [index, predicate] of [
[
'journal_items_unsettled',
`hidden=0 AND (lifecycle_state IN ('running','pending') OR live_work=1)`
],
[
'journal_items_unverifiable_turn',
`hidden=0 AND kind IN ('turn','status') AND lifecycle_state='unverifiable'`
],
['journal_items_unverified_end', `hidden=0 AND unverified_end=1`]
]) {
let after: [number, string] | undefined
for (;;) {
const rows = db
.prepare(`SELECT payload_json,ordinal,item_id,COALESCE(execution_owner,owner_fence) AS fence
FROM journal_items INDEXED BY ${index} WHERE session_id=? AND epoch=? AND ${predicate}
${after ? 'AND (ordinal,item_id)>(?,?)' : ''} ORDER BY ordinal,item_id LIMIT 128`)
.all(...prefix, ...(after ?? []))
for (const row of rows) {
include(row)
}
if (rows.length < 128) {
break
}
const last = rows.at(-1)!
after = [Number(last.ordinal), String(last.item_id)]
}
}
for (const { item } of selected.values()) {
dependencies(item)
}
if (exitScope) {
let after: [number, number, number, string] | undefined
let found = false
for (;;) {
const rows = db
.prepare(`SELECT payload_json,ordinal,item_id,sequence,sequence_index,COALESCE(execution_owner,owner_fence) AS fence
FROM journal_items INDEXED BY journal_items_interrupted_root WHERE session_id=? AND epoch=? AND hidden=0 AND root=1 AND kind IN ('turn','status')
AND lifecycle_state='interrupted' AND turn_completed_at IS NOT NULL AND turn_completed_at=?
${after ? 'AND (sequence,sequence_index,ordinal,item_id)<(?,?,?,?)' : ''}
ORDER BY sequence DESC,sequence_index DESC,ordinal DESC,item_id DESC LIMIT 128`)
.all(...prefix, exitScope.completedAt, ...(after ?? []))
for (const row of rows) {
const fence = row.fence == null ? undefined : Number(row.fence)
if (fence !== undefined && fence < exitScope.ownerFence) {
continue
}
const item = include(row)
dependencies(item)
if (!isHistoricalProviderTimelineItem(item, point)) {
found = true
break
}
}
if (found || rows.length < 128) {
break
}
const last = rows.at(-1)!
after = [
Number(last.sequence),
Number(last.sequence_index),
Number(last.ordinal),
String(last.item_id)
]
}
}
if (startKey !== undefined) {
point(agentJournalItemKey(structuredAgentSessionStartFailureRowIdentity(startKey)))
}
const items = [...selected.values()]
.sort(
(a, b) =>
a.item.sequence - b.item.sequence ||
(a.item.sequenceIndex ?? 0) - (b.item.sequenceIndex ?? 0) ||
a.ordinal - b.ordinal
)
.map((row) => row.item)
const submissions: AgentJournalSubmission[] = []
let afterSend: [number, string] | undefined
for (;;) {
const rows = db
.prepare(`SELECT payload_json,ordinal,message_id FROM journal_submission_attempts INDEXED BY journal_submission_recovery
WHERE session_id=? AND epoch=? AND current=1 AND (dispatch_state='pending' OR (dispatch_state='unknown' AND recovered=0))
${afterSend ? 'AND (ordinal,message_id)>(?,?)' : ''} ORDER BY ordinal,message_id LIMIT 128`)
.all(...prefix, ...(afterSend ?? []))
for (const row of rows) {
submissions.push(JSON.parse(String(row.payload_json)))
}
if (rows.length < 128) {
break
}
const last = rows.at(-1)!
afterSend = [Number(last.ordinal), String(last.message_id)]
}
return {
statusRead: () => ({ items, submissions: [] }),
snapshot: () => ({
items,
submissions: [],
sessionId: target.sessionId,
cursor: journalDomainContextHead(db, target)
}),
inputOrder: { recoverableSubmissions: () => submissions },
submissions: () => submissions,
submission: (messageId: string) =>
submissions.find((send) => send.clientMessageId === messageId),
itemBody: (key: string) => point(key)?.body ?? null,
itemFence: (key: string) => {
point(key)
return selected.get(key)?.fence
},
stopMarks: {
latest: () => journalDomainLatestStop(db, target, stopSettle),
personStopDecides: (turnId: string | null, endedAt?: number) =>
journalDomainStopDecidesTurn(
journalDomainLatestStop(db, target, stopSettle),
turnId,
endedAt
)
},
lastProviderActivityAt: (fence: number): number | undefined => {
const row = db
.prepare(
`SELECT last_activity_at FROM journal_provider_activity WHERE session_id=? AND epoch=? AND fence=?`
)
.get(...prefix, fence)
return row ? Number(row.last_activity_at) : undefined
},
cursor: () => journalDomainContextHead(db, target)
}
}
@@ -0,0 +1,186 @@
import type Database from '../../sqlite/sync-database'
import type { JournalWriterOperation } from './journal-writer-command'
import type { JournalStopSettleFact } from './journal-writer-host-facts'
import type { JournalLifecycleBatchInput } from './journal-store-contracts'
import {
planStaleStructuredAgentSessionState,
type StaleStructuredAgentSessionStateJournal
} from '../agent-session-wire/termination/structured-agent-session-stale-state-settlement'
import { planStructuredAgentSessionDeadGeneration } from '../agent-session-wire/termination/structured-agent-session-dead-generation-settlement'
import { runningTurnLifecycleRevisions } from '../agent-session-wire/termination/structured-agent-session-stale-turn-verdict'
import type { DeadGenerationJournal } from '../agent-session-wire/termination/structured-agent-session-unfinished-work'
import { STALE_SESSION_ROW_PREFIX } from '../../../shared/agent-session/lifecycle/agent-session-stop-row-identity'
import { isRootAgentJournalItem } from '../../../shared/agent-session/journal/agent-session-journal-producer'
import { isQueuedAgentJournalSubmission } from '../../../shared/agent-session/requests/agent-session-queued-submission'
import { readAgentJournalTurn } from '../../../shared/agent-session/lifecycle/agent-session-turn-record'
import { journalStartFailureRow } from './writing/journal-start-failure-settlement'
import { readJournalDomainSubmissionAttempt } from './journal-domain-submission-records'
import {
applyJournalDomainLifecycle,
hasJournalDomainSettlement,
journalDomainLifecycleCommit,
type JournalDomainLifecycleCommit
} from './journal-domain-lifecycle'
import { readJournalDomainGeneration } from './journal-domain-generation-reads'
import { journalDomainTimelineReads } from './journal-domain-timeline-reads'
type Operation = Extract<
JournalWriterOperation,
{
kind: 'stale-settle' | 'dead-generation-settle' | 'unheld-turns-settle' | 'start-failure-settle'
}
>
/** No producer snapshot decides recovery: evidence is applied to the current lifecycle rows. */
export function applyJournalDomainGenerationSettlement(
db: Database.Database,
target: { sessionId: string; epoch: string },
operation: Operation,
savedAt: number,
stopSettle?: JournalStopSettleFact
): JournalDomainLifecycleCommit & { value: number | undefined } {
const empty = journalDomainLifecycleCommit(db, target)
let batch: JournalLifecycleBatchInput
let value: number | undefined
if (operation.kind === 'start-failure-settle') {
const input = operation.input
const settlementId = `start-failure:${input.startKey}`
if (hasJournalDomainSettlement(db, target, settlementId)) {
return { ...empty, value }
}
if (input.clientMessageId !== null) {
const attempt = readJournalDomainSubmissionAttempt(db, target, input.clientMessageId)
if (!attempt || !isQueuedAgentJournalSubmission(attempt.submission)) {
return { ...empty, value }
}
}
batch = {
settlementId,
fence: input.fence,
recovered: true,
keepFailedStart: true,
mutations: [journalStartFailureRow(input.startKey, input)],
dispatches:
input.clientMessageId === null
? []
: [
{
clientMessageId: input.clientMessageId,
fence: input.fence,
state: 'rejected',
recovered: true,
reason: input.reason,
rejection: input.rejection
}
]
}
} else if (operation.kind === 'unheld-turns-settle') {
const input = operation.input
const settlementId = `unheld-turns:${input.sessionId}:${input.fence}:${input.generation}`
if (hasJournalDomainSettlement(db, target, settlementId)) {
return { ...empty, value }
}
const view = journalDomainTimelineReads(db, target, stopSettle)
const unheld = [...view.unsettled(null)].filter((item) => {
const turn = readAgentJournalTurn(item.body)
if (
item.body.kind !== 'turn' ||
turn?.state !== 'running' ||
turn.turnId === input.liveTurnId ||
!isRootAgentJournalItem(item)
) {
return false
}
const row = db
.prepare(
`SELECT COALESCE(execution_owner,owner_fence) AS fence FROM journal_items WHERE session_id=? AND epoch=? AND item_id=?`
)
.get(target.sessionId, target.epoch, item.itemId)
return Number(row?.fence) === input.fence
})
batch = {
settlementId,
fence: input.fence,
recovered: true,
mutations: runningTurnLifecycleRevisions(unheld, { state: 'interrupted' })
}
} else {
const input = operation.input
const exit = operation.kind === 'dead-generation-settle' ? operation.input.exit : undefined
const generation =
operation.kind === 'stale-settle'
? (operation.input.acquisitionGeneration ?? `seq-${empty.cursor.sequence}`)
: `seq-${empty.cursor.sequence}`
const settlementId = exit
? `dead-generation:${exit.settlementId}`
: `${STALE_SESSION_ROW_PREFIX}${input.sessionId}:${input.fence}:${generation}`
if (hasJournalDomainSettlement(db, target, settlementId)) {
return { ...empty, value: 0 }
}
const reads = readJournalDomainGeneration(
db,
target,
exit?.exitedDuringStartup
? (exit.exitedDuringStartup.generation ?? exit.settlementId)
: undefined,
stopSettle,
exit?.verdict.state === 'interrupted' && typeof exit.verdict.completedAt === 'number'
? { completedAt: exit.verdict.completedAt, ownerFence: exit.ownerFence }
: undefined
)
// The existing pure planner signatures include unused journal mutation methods.
const journal = reads as unknown as StaleStructuredAgentSessionStateJournal &
DeadGenerationJournal
if (operation.kind === 'stale-settle') {
const plan = planStaleStructuredAgentSessionState({ ...operation.input, journal })
value = plan.mutations.length
batch = { ...operation.input, settlementId, recovered: true, ...plan }
} else {
const authority = operation.input
const exited = exit
? planStructuredAgentSessionDeadGeneration(
{ ...exit, journal, sessionId: input.sessionId, fence: input.fence },
(owner) => owner === undefined || owner >= exit.ownerFence,
authority
)
: { mutations: [], dispatches: [] }
const settled = new Set(exited.dispatches.map((entry) => entry.clientMessageId))
const stale = planStaleStructuredAgentSessionState({
...authority,
journal,
acquisitionGeneration: null
})
const continuing = new Set(authority.continuingInputs)
const finalizing = new Set(
authority.finalizingInputs
.filter((entry) => !entry.settlementOwner)
.map((entry) => entry.clientMessageId)
)
const pending = new Set(
reads.inputOrder
.recoverableSubmissions()
.filter((send) => send.dispatchState === 'pending')
.map((send) => send.clientMessageId)
)
const mutations = [...exited.mutations, ...stale.mutations]
const dispatches = [
...exited.dispatches,
...stale.dispatches.filter((entry) => !settled.has(entry.clientMessageId))
].filter(
(entry) =>
!(continuing.has(entry.clientMessageId) && pending.has(entry.clientMessageId)) &&
(entry.state === 'rejected' || !finalizing.has(entry.clientMessageId))
)
value = mutations.length + dispatches.length
batch = {
settlementId,
fence: input.fence,
recovered: true,
keepFailedStart: exit?.exitedDuringStartup !== undefined,
mutations,
dispatches
}
}
}
return { ...applyJournalDomainLifecycle(db, target, batch, savedAt, stopSettle), value }
}
@@ -0,0 +1,270 @@
import { afterEach, expect, it } from 'vitest'
import {
domainLifecycleFixture,
lifecycleIdentity as identity,
lifecycleOptions as options,
lifecycleTarget as target
} from './journal-domain-lifecycle.test-fixture'
import { journalDomainTimelineReads } from './journal-domain-timeline-reads'
const cleanups: (() => void)[] = []
afterEach(() => {
for (const cleanup of cleanups.splice(0)) {
cleanup()
}
})
it('refines only proven effective owners and settles reasoning without broadening timeline policy', async () => {
const f = domainLifecycleFixture(cleanups)
for (const id of ['matching', 'other']) {
await f.run({
kind: 'item',
identity: identity(id),
body: {
kind: 'tool-call',
name: 'read',
input: {},
state: 'failed',
endedAs: 'unverifiable'
},
options
})
}
f.db.prepare(`UPDATE journal_items SET execution_owner=2 WHERE item_id='orca:other'`).run()
await f.run({
kind: 'item',
identity: identity('legacy'),
body: {
kind: 'status',
text: 'turn',
turnLifecycle: { turnId: 'legacy', state: 'unverifiable' }
},
options
})
await f.run({
kind: 'item',
identity: identity('reasoning'),
body: {
kind: 'message',
role: 'reasoning',
state: 'running',
blocks: [{ type: 'text', text: 'thinking' }]
},
options
})
expect([...journalDomainTimelineReads(f.db, target).unsettled(null)]).toEqual([])
await f.run({
kind: 'stale-settle',
input: {
sessionId: 'chat',
fence: 1,
acquisitionGeneration: 'recovered',
deathEvidence: { kind: 'exit-observed', ownerFence: 1, observedAt: 150, detail: '' }
}
})
expect(f.item('orca:matching')?.body).toMatchObject({ state: 'failed', endedAs: 'interrupted' })
expect(f.item('orca:other')?.body).toMatchObject({ state: 'failed', endedAs: 'unverifiable' })
expect(f.item('orca:legacy')?.body).toMatchObject({
kind: 'turn',
state: 'interrupted',
completedAt: 150
})
expect(f.item('orca:reasoning')?.body).toMatchObject({ state: 'completed' })
})
it('inherits the named settled parent outcome instead of inventing an unverified tool ending', async () => {
const f = domainLifecycleFixture(cleanups)
await f.run({
kind: 'item',
identity: identity('parent'),
body: { kind: 'turn', turnId: 'parent', state: 'interrupted', completedAt: 75 },
options
})
await f.run({
kind: 'item',
identity: identity('tool'),
body: { kind: 'tool-call', name: 'read', input: {}, state: 'running' },
options: { ...options, turnScope: { kind: 'turn', turnItemId: 'orca:parent' } }
})
await f.run({
kind: 'stale-settle',
input: { sessionId: 'chat', fence: 1, acquisitionGeneration: 'parent', deathEvidence: null }
})
expect(f.item('orca:tool')?.body).toMatchObject({ state: 'failed', endedAs: 'interrupted' })
})
it('scopes a pending-send-only exit notice to the eligible root already interrupted at that exact time', async () => {
const f = domainLifecycleFixture(cleanups)
await f.run({
kind: 'item',
identity: identity('root'),
body: { kind: 'turn', turnId: 'root', state: 'interrupted', completedAt: 150 },
options
})
await f.run({
kind: 'item',
identity: identity('older-owner'),
body: { kind: 'turn', turnId: 'older-owner', state: 'interrupted', completedAt: 150 },
options
})
f.db.prepare(`UPDATE journal_items SET execution_owner=0 WHERE item_id='orca:older-owner'`).run()
await f.run({
kind: 'submission',
input: {
clientMessageId: 'send',
body: { kind: 'message', role: 'user', blocks: [{ type: 'text', text: 'pending' }] },
fence: 1,
payloadFingerprint: 'send',
handoverRecorded: true,
source: { kind: 'user' },
origin: 'client'
}
})
await f.run({
kind: 'dispatch',
input: { clientMessageId: 'send', fence: 1, state: 'pending', turnScope: { kind: 'thread' } }
})
await f.run({
kind: 'dead-generation-settle',
input: {
sessionId: 'chat',
fence: 1,
deathEvidence: null,
below: 1,
continuingInputs: [],
finalizingInputs: [],
exit: {
ownerFence: 1,
settlementId: 'exit',
verdict: { state: 'interrupted', completedAt: 150 },
pendingSubmissionReason: 'ended'
}
}
})
expect(f.item('orca:exit')).toMatchObject({
turnScope: { kind: 'turn', turnItemId: 'orca:root' }
})
})
it('updates legacy context presence with visibility, replacement and removal and seeks absent eligible subsets', async () => {
const f = domainLifecycleFixture(cleanups)
const view = journalDomainTimelineReads(f.db, target)
await f.run({
kind: 'item',
identity: identity('window'),
body: {
kind: 'status',
text: 'legacy',
turnLifecycle: {
turnId: 'window',
state: 'completed',
contextUsage: { window: { tokens: 0, capturedAt: 0 } }
}
},
options
})
expect(view.contextWindowHeld()).toBe(true)
f.db.prepare(`UPDATE journal_items SET hidden=1 WHERE item_id='orca:window'`).run()
expect(view.contextWindowHeld()).toBe(false)
f.db.prepare(`UPDATE journal_items SET hidden=0 WHERE item_id='orca:window'`).run()
await f.run({ kind: 'epoch-replace', reason: 'legacy_import', fence: 1, items: [] })
expect(view.contextWindowHeld()).toBe(false)
await f.run({
kind: 'item',
identity: identity('window'),
body: {
kind: 'turn',
turnId: 'window',
state: 'completed',
contextUsage: { window: { tokens: 100, capturedAt: 100 } }
},
options
})
await f.run({ kind: 'tombstone', identity: identity('window'), fence: 1 })
expect(view.contextWindowHeld()).toBe(false)
for (const [predicate, index] of [
[`hidden=0 AND context_window=1`, 'journal_items_context_window'],
[
`hidden=0 AND (lifecycle_state IN ('running','pending') OR live_work=1)`,
'journal_items_unsettled'
],
[
`hidden=0 AND kind IN ('turn','status') AND lifecycle_state='unverifiable'`,
'journal_items_unverifiable_turn'
],
[`hidden=0 AND unverified_end=1`, 'journal_items_unverified_end'],
[
`hidden=0 AND root=1 AND kind IN ('turn','status') AND lifecycle_state='interrupted' AND turn_completed_at IS NOT NULL AND turn_completed_at=150`,
'journal_items_interrupted_root'
]
]) {
const plan = f.db
.prepare(
`EXPLAIN QUERY PLAN SELECT 1 FROM journal_items INDEXED BY ${index} WHERE session_id=? AND epoch=? AND ${predicate} LIMIT 1`
)
.all('chat', 'epoch')
expect(plan.map((row) => row.detail).join('\n')).toContain(index)
}
})
it('uses the visible named opener to preserve historical replay instead of settling it as live work', async () => {
const f = domainLifecycleFixture(cleanups)
const turn = {
provider: 'legacy' as const,
agent: 'grok',
sessionId: 'thread',
recordId: 'turn-lifecycle:p:hist:t'
}
const opener = {
provider: 'legacy' as const,
agent: 'grok',
sessionId: 'thread',
recordId: 'item:p:hist:hist/user%3A1'
}
const turnKey = 'legacy:grok:thread:turn-lifecycle%3Ap%3Ahist%3At'
const openerKey = 'legacy:grok:thread:item%3Ap%3Ahist%3Ahist%2Fuser%253A1'
await f.run({
kind: 'item',
identity: opener,
body: { kind: 'message', role: 'user', blocks: [{ type: 'text', text: 'historical' }] },
options: { ...options, turnScope: { kind: 'turn', turnItemId: turnKey } }
})
await f.run({
kind: 'item',
identity: turn,
body: { kind: 'turn', turnId: 'p:hist:t', userItemId: openerKey, state: 'running' },
options
})
await f.run({
kind: 'item',
identity: identity('historical-tool'),
body: { kind: 'tool-call', name: 'read', input: {}, state: 'running' },
options: { ...options, turnScope: { kind: 'turn', turnItemId: turnKey } }
})
await f.run({
kind: 'stale-settle',
input: {
sessionId: 'chat',
fence: 1,
acquisitionGeneration: 'historical',
deathEvidence: { kind: 'exit-observed', ownerFence: 1, observedAt: 150, detail: '' }
}
})
expect(f.item(turnKey)?.body).toMatchObject({ state: 'running' })
expect(f.item('orca:historical-tool')?.body).toMatchObject({ state: 'running' })
await f.run({ kind: 'tombstone', identity: opener, fence: 1 })
await f.run({
kind: 'stale-settle',
input: {
sessionId: 'chat',
fence: 1,
acquisitionGeneration: 'no-opener',
deathEvidence: { kind: 'exit-observed', ownerFence: 1, observedAt: 150, detail: '' }
}
})
expect(f.item(turnKey)?.body).toMatchObject({ state: 'interrupted' })
expect(f.item('orca:historical-tool')?.body).toMatchObject({
state: 'failed',
endedAs: 'interrupted'
})
})
@@ -0,0 +1,71 @@
import type Database from '../../sqlite/sync-database'
import type {
AgentJournalItemBody,
AgentJournalRenderItem
} from '../../../shared/agent-session/journal/agent-session-journal-types'
import type { JournalStopSettleFact } from './journal-writer-host-facts'
import type { JournalLatestStop } from './context-epochs/journal-stop-turn-end'
import { personStopDecidesTurn, turnEndAfterStop } from './context-epochs/journal-stop-turn-end'
import { boundRunningToolOutput } from './item-lifecycle/journal-payload-bounds'
export function journalDomainLatestStop(
db: Database.Database,
target: { sessionId: string; epoch: string },
stopSettle?: JournalStopSettleFact
): JournalLatestStop | null {
const row = db
.prepare(`SELECT queue_latest_stop_json FROM journal_chat_state
WHERE session_id=? AND epoch=?`)
.get(target.sessionId, target.epoch)
const stop: JournalLatestStop | null =
row?.queue_latest_stop_json == null ? null : JSON.parse(String(row.queue_latest_stop_json))
if (!stop) {
return null
}
const { settle: _savedOverlay, ...saved } = stop
return stopSettle?.sequence === stop.sequence ? { ...saved, settle: stopSettle.settle } : saved
}
export function journalDomainStopDecidesTurn(
stop: JournalLatestStop | null,
turnId: string | null,
endedAt?: number
): boolean {
// The pure Stop policy reads only this mark; collection members are never consulted.
return personStopDecidesTurn(
{
items: new Map(),
submissions: new Map(),
aliases: new Map(),
queuePauseMarks: { latestStop: stop, resumedSequence: 0, reopenedSequence: 0 }
},
turnId,
endedAt
)
}
/** Every current-item owner applies the same bounded body and write-time Stop policy. */
export function normalizeJournalDomainItemBody(
db: Database.Database,
target: { sessionId: string; epoch: string },
item: AgentJournalRenderItem,
previous: AgentJournalRenderItem | undefined,
stopSettle?: JournalStopSettleFact
): AgentJournalItemBody {
let body = item.body
if (body.kind === 'turn' && body.state === 'interrupted' && body.outcome === undefined) {
const latestStop = journalDomainLatestStop(db, target, stopSettle)
// A one-row policy input is temporary command data, never a reconstructed session.
body = turnEndAfterStop(
{
items: new Map(previous ? [[item.itemId, previous]] : []),
submissions: new Map(),
aliases: new Map(),
queuePauseMarks: { latestStop, resumedSequence: 0, reopenedSequence: 0 }
},
item.itemId,
body
)
}
return boundRunningToolOutput(body)
}
@@ -1,3 +1,4 @@
import { journalContextEpoch } from './context-epochs/journal-context-cursor'
import type Database from '../../sqlite/sync-database'
import {
agentJournalItemKey,
@@ -15,6 +16,7 @@ import type {
AgentJournalAcceptanceReceipt
} from '../../../shared/agent-session/journal/agent-session-journal-types'
import { agentJournalLinkageFields } from '../../../shared/agent-session/journal/agent-session-journal-producer'
import type { JournalStopSettleFact } from './journal-writer-host-facts'
import type { JournalItemAppendOptions } from './journal-store-contracts'
import { journalItemRevisionValue } from './projection/journal-item-fold'
import { isProviderUserMessageEcho } from './projection/journal-item-echo'
@@ -57,6 +59,7 @@ export type JournalDomainItemWrite = JournalDomainItemFields &
export type JournalDomainItemCommit = {
cursor: AgentJournalCursor
publicCursor?: AgentJournalCursor
outcome:
| { kind: 'committed'; wrote: boolean }
| { kind: 'dropped'; reason: 'turn-settled'; turnItemId: string }
@@ -73,7 +76,8 @@ export function applyJournalDomainItem(
db: Database.Database,
target: { sessionId: string; epoch: string },
input: JournalDomainItemWrite,
savedAt: number
savedAt: number,
stopSettle?: JournalStopSettleFact
): JournalDomainItemCommit {
if (!db.isTransaction) {
throw new Error('journal message requires its writer transaction')
@@ -91,6 +95,7 @@ export function applyJournalDomainItem(
const cursor = { epoch, sequence: Number(head.last_sequence) }
const empty: JournalDomainItemCommit = {
cursor,
publicCursor: { ...cursor, epoch: journalContextEpoch(epoch, Number(head.context_boundary)) },
outcome: { kind: 'committed', wrote: false },
items: [],
receipts: [],
@@ -201,6 +206,7 @@ export function applyJournalDomainItem(
ordinal: stored ? Number(stored.ordinal) : nextJournalDomainItemOrdinal(db, target),
hidden: Boolean(stored?.hidden),
writtenSequence: sequence,
stopSettle,
ownerFence: row.ownerFence!,
executionOwner:
row.executionOwner ??
@@ -208,6 +214,7 @@ export function applyJournalDomainItem(
})
const result: JournalDomainItemCommit = {
cursor: { epoch, sequence },
publicCursor: { epoch: journalContextEpoch(epoch, Number(head.context_boundary)), sequence },
outcome: { kind: 'committed', wrote: true },
items,
receipts: [],
@@ -0,0 +1,124 @@
import type Database from '../../sqlite/sync-database'
import type { JournalLifecycleBatchInput } from './journal-store-contracts'
import type { JournalDomainLifecycleCommit } from './journal-domain-lifecycle'
import { applyJournalDomainDispatch } from './journal-domain-dispatch'
import {
readJournalDomainSubmissionAttempt,
readJournalDomainSubmissionBody
} from './journal-domain-submission-records'
import { insertJournalDomainQueueRow, journalDomainQueueRow } from './journal-domain-queue-rows'
import { isQueuedAgentJournalSubmission } from '../../../shared/agent-session/requests/agent-session-queued-submission'
import { agentSessionSendBodyFingerprint } from '../../../shared/agent-session/requests/structured-agent-session-send-mutation'
import { appendJournalSqlEvent } from './journal-sql-event-tail'
/** A failed start returns only the person's direct text; dispatch still owns its rejection. */
export function applyJournalDomainLifecycleDispatches(
db: Database.Database,
target: { sessionId: string; epoch: string },
input: JournalLifecycleBatchInput,
savedAt: number,
result: JournalDomainLifecycleCommit
): boolean {
const dispatches = input.rejectsQueued
? db
.prepare(`SELECT payload_json FROM journal_submission_attempts WHERE session_id=? AND epoch=? AND current=1
AND (dispatch_state='pending' OR (dispatch_state='unknown' AND recovered=0)) ORDER BY ordinal`)
.all(target.sessionId, target.epoch)
.map((row) => JSON.parse(String(row.payload_json)))
.filter(isQueuedAgentJournalSubmission)
.map((send) => ({
clientMessageId: send.clientMessageId,
fence: input.fence,
state: 'rejected' as const,
...input.rejectsQueued!,
recovered: true as const
}))
: [...(input.dispatches ?? [])]
if (input.rejectsQueued && dispatches.length === 0) {
return false
}
if (input.rejectsQueued && input.mutations.length === 0) {
throw new Error('journal_lifecycle_batch_mutation_bound_exceeded')
}
let position =
Math.min(
0,
Number(
db
.prepare(
`SELECT MIN(position) AS position FROM journal_queue_cards WHERE session_id=? AND epoch=?`
)
.get(target.sessionId, target.epoch)?.position ?? 0
)
) - dispatches.length
for (let dispatch of dispatches) {
if (input.keepFailedStart && dispatch.state === 'rejected') {
const attempt = readJournalDomainSubmissionAttempt(db, target, dispatch.clientMessageId)
const body = attempt && readJournalDomainSubmissionBody(db, target, dispatch.clientMessageId)
const personal =
attempt &&
(attempt.admission.sourceKind === 'user' ||
(attempt.admission.sourceKind === null && attempt.admission.origin === 'client'))
if (
attempt &&
personal &&
attempt.admission.familyId === null &&
body?.kind === 'message' &&
!body.command &&
!journalDomainQueueRow(db, target, dispatch.clientMessageId)
) {
const card = {
messageId: dispatch.clientMessageId,
body,
position: position++,
fingerprint: agentSessionSendBodyFingerprint(target.sessionId, body),
state: 'returned' as const,
holdReason: null,
returnedReason: dispatch.reason,
returnedRejection: dispatch.rejection,
consumedAs: null,
queuedAt: { epoch: target.epoch, sequence: attempt.submission.acceptedSequence ?? 0 },
deliveryMode: 'queue' as const,
unattended: !attempt.admittedPersonal,
...(attempt.admission.options ? { options: attempt.admission.options } : {})
}
insertJournalDomainQueueRow(db, target, card)
const sequence = result.cursor.sequence + 1
appendJournalSqlEvent(
db,
target,
sequence,
savedAt,
{ items: [], submissions: [], cards: [card.messageId] },
{ fence: input.fence, observedAt: savedAt }
)
result.cursor = { ...result.cursor, sequence }
result.cards.push(card)
result.inputChanged = true
result.coordinates.push({ kind: 'queue', epoch: target.epoch, seq: sequence })
dispatch = { ...dispatch, keptAsQueuedMessageId: dispatch.clientMessageId }
}
}
const commit = applyJournalDomainDispatch(
db,
target,
{ kind: 'dispatch', input: dispatch },
savedAt
)
result.cursor = { ...result.cursor, sequence: commit.cursor.sequence }
result.items.push(...commit.items)
result.receipts.push(...commit.receipts)
result.cards.push(...commit.cards)
result.removedItemIds.push(...commit.removedItemIds)
result.inputChanged ||= commit.inputChanged
result.acceptedInputs = commit.acceptedInputs ?? result.acceptedInputs
result.coordinates.push(
...commit.coordinates.map((position) => ({
kind: position.kind === 'queue-reopen' ? ('tombstone' as const) : position.kind,
epoch: target.epoch,
seq: position.cursor.sequence
}))
)
}
return true
}
@@ -0,0 +1,135 @@
import type Database from '../../sqlite/sync-database'
import { agentJournalSubmissionKey } from '../../../shared/agent-session/journal/agent-session-journal-item-key'
import type { AgentJournalSubmission } from '../../../shared/agent-session/journal/agent-session-journal-types'
import type { JournalStopSettleFact } from './journal-writer-host-facts'
import type { JournalLifecycleMutationInput } from './writing/journal-lifecycle-mutation'
import { journalLifecycleMutationItemId } from './writing/journal-lifecycle-mutation'
import { readJournalDomainDispatchItem } from './journal-domain-dispatch-placement'
import {
writeJournalDomainCurrentItem,
nextJournalDomainItemOrdinal
} from './journal-domain-current-item'
import { isProviderUserMessageEcho } from './projection/journal-item-echo'
import { journalItemRevisionValue } from './projection/journal-item-fold'
import { journalRenderItem } from './projection/journal-render-item'
import { journalRowBase } from './writing/journal-row-builders'
import {
matchJournalSqlMessageEcho,
acceptJournalSqlMessageEcho
} from './journal-sql-message-effects'
import { readJournalSqlAcceptedInputs } from './journal-sql-accepted-inputs'
import { isJournalProviderActivity } from './projection/journal-provider-activity'
import type { JournalItemRow } from './durable-rows/journal-row-schema'
/** A lifecycle group owns its one event; each current row retains ordinary revision/echo semantics. */
export function writeJournalDomainLifecycleItem(
db: Database.Database,
target: { sessionId: string; epoch: string },
mutation: Extract<JournalLifecycleMutationInput, { kind: 'item' }>,
position: {
fence: number
recovered?: true
sequence: number
sequenceIndex: number
savedAt: number
stopSettle?: JournalStopSettleFact
}
) {
const prefix = [target.sessionId, target.epoch] as const
const rawId = journalLifecycleMutationItemId(mutation)
const alias = db
.prepare(
`SELECT item_id,echo_declared FROM journal_item_aliases WHERE session_id=? AND epoch=? AND provider_item_id=?`
)
.get(...prefix, rawId)
const declaration = Boolean(alias?.echo_declared) || Object.hasOwn(mutation, 'echoOf')
let itemId = alias ? String(alias.item_id) : rawId
let echo: AgentJournalSubmission | undefined
if (
!alias &&
!declaration &&
mutation.body.kind === 'message' &&
isProviderUserMessageEcho(rawId, mutation.body)
) {
const head = db
.prepare(`SELECT context_boundary FROM journal_chat_state WHERE session_id=? AND epoch=?`)
.get(...prefix)!
echo = matchJournalSqlMessageEcho(db, prefix, mutation.body, Number(head.context_boundary))
if (echo) {
itemId = agentJournalSubmissionKey(echo.clientMessageId)
}
}
const previous = readJournalDomainDispatchItem(db, target, itemId)
const tombstone = db
.prepare(
`SELECT revision FROM journal_item_tombstones WHERE session_id=? AND epoch=? AND item_id=?`
)
.get(...prefix, itemId)
const revision = Math.max(previous?.item.revision ?? 0, Number(tombstone?.revision ?? 0)) + 1
const row: JournalItemRow = {
kind: 'item',
itemId: rawId,
revision,
body: mutation.body,
...journalRowBase(
target.epoch,
position.sequence,
position.fence,
mutation.observedAt ?? position.savedAt
),
...(position.recovered ? { recovered: true } : {}),
ownerFence: previous?.ownerFence ?? mutation.ownerFence ?? position.fence,
turnScope: mutation.turnScope
}
const rendered = journalRenderItem(
itemId,
revision,
mutation.body,
row,
mutation.turnScope,
mutation.linkage,
position.sequenceIndex
)
const items = writeJournalDomainCurrentItem(db, target, {
item: previous ? journalItemRevisionValue(previous.item, rendered) : rendered,
...(previous ? { previous } : {}),
ordinal: previous?.ordinal ?? nextJournalDomainItemOrdinal(db, target),
hidden: previous?.hidden ?? false,
ownerFence: row.ownerFence!,
executionOwner: previous?.executionOwner,
writtenSequence: position.sequence,
stopSettle: position.stopSettle
})
if (tombstone) {
db.prepare(
`DELETE FROM journal_item_tombstones WHERE session_id=? AND epoch=? AND item_id=?`
).run(...prefix, itemId)
}
if ((!alias && itemId !== rawId) || (!alias?.echo_declared && declaration)) {
db.prepare(`INSERT INTO journal_item_aliases(session_id,epoch,provider_item_id,item_id,echo_declared,echo_json) VALUES(?,?,?,?,?,?)
ON CONFLICT(session_id,epoch,provider_item_id) DO UPDATE SET echo_declared=excluded.echo_declared,echo_json=excluded.echo_json`).run(
...prefix,
rawId,
itemId,
Number(declaration),
declaration ? JSON.stringify(mutation.echoOf ?? null) : null
)
}
const receipt =
!declaration && itemId !== rawId
? acceptJournalSqlMessageEcho(db, prefix, rawId, itemId, row, echo)
: undefined
if (isJournalProviderActivity(row.recovered, rawId, row.body)) {
db.prepare(`INSERT INTO journal_provider_activity(session_id,epoch,fence,last_activity_at) VALUES(?,?,?,?)
ON CONFLICT(session_id,epoch,fence) DO UPDATE SET last_activity_at=MAX(last_activity_at,excluded.last_activity_at)`).run(
...prefix,
previous?.executionOwner ?? row.ownerFence!,
position.savedAt
)
}
return {
items,
receipts: receipt ? [receipt] : [],
...(receipt ? { acceptedInputs: readJournalSqlAcceptedInputs(db, prefix) } : {})
}
}
@@ -0,0 +1,71 @@
import { mkdtempSync, rmSync } from 'node:fs'
import { tmpdir } from 'node:os'
import { join } from 'node:path'
import Database from '../../sqlite/sync-database'
import type { AgentJournalRenderItem } from '../../../shared/agent-session/journal/agent-session-journal-types'
import type { JournalWriterCommand, JournalWriterOperation } from './journal-writer-command'
import type { JournalWriterHostFacts } from './journal-writer-host-facts'
import { codexProviderHandle } from '../../../shared/agent-session/lifecycle/agent-session-provider-handle-encoding'
import { migrateJournalDomainSchema } from './journal-domain-schema'
import { JournalSqlCommand } from './journal-sql-command'
import { JournalSqlBatch } from './journal-sql-batch'
export const lifecycleTarget = { sessionId: 'chat', epoch: 'epoch', ownerToken: 'owner' }
export const lifecycleOptions = { fence: 1, turnScope: { kind: 'thread' as const } }
export const lifecycleFacts: JournalWriterHostFacts = {
identity: {
sessionId: 'chat',
workspaceId: 'workspace',
hostId: 'host',
agent: 'codex',
providerHandle: codexProviderHandle('thread')
}
}
export const lifecycleIdentity = (clientMessageId: string) => ({
provider: 'orca' as const,
clientMessageId
})
export function domainLifecycleFixture(cleanups: (() => void)[]) {
const directory = mkdtempSync(join(tmpdir(), 'orca-domain-lifecycle-'))
const filename = join(directory, 'journal.sqlite')
let db = new Database(filename)
migrateJournalDomainSchema(db)
db.prepare(
`INSERT INTO journal_chat_state(session_id,workspace_id,epoch,highest_fence) VALUES('chat','workspace','epoch',1)`
).run()
cleanups.push(() => {
db.close()
rmSync(directory, { recursive: true, force: true })
})
return {
directory,
get db() {
return db
},
reopen() {
db.close()
db = new Database(filename)
},
item(key: string): AgentJournalRenderItem | undefined {
const row = db.prepare(`SELECT payload_json FROM journal_items WHERE item_id=?`).get(key)
return row ? JSON.parse(String(row.payload_json)) : undefined
},
async run(
operation: JournalWriterOperation,
facts: JournalWriterHostFacts = lifecycleFacts,
effects?: JournalWriterCommand['effects']
) {
const command = { target: lifecycleTarget, operation, facts, ...(effects ? { effects } : {}) }
const answer = (
await new JournalSqlBatch(db).run([command], (command) =>
new JournalSqlCommand(db, directory).apply(command, 100)
)
).outcomes[0]!
if (!answer.committed) {
throw answer.error
}
return answer.value
}
}
}
@@ -0,0 +1,248 @@
import { afterEach, expect, it } from 'vitest'
import {
domainLifecycleFixture,
lifecycleIdentity as identity,
lifecycleOptions as options,
lifecycleFacts
} from './journal-domain-lifecycle.test-fixture'
import type { JournalLifecycleMutationInput } from './writing/journal-lifecycle-mutation'
import { agentSessionFailureWords } from '../../../shared/agent-session/failures/agent-session-failure-words'
import { journalDomainQueueRow } from './journal-domain-queue-rows'
const cleanups: (() => void)[] = []
afterEach(() => {
for (const cleanup of cleanups.splice(0)) {
cleanup()
}
})
const status = (id: string): JournalLifecycleMutationInput => ({
kind: 'item',
identity: identity(id),
body: { kind: 'status', text: id },
turnScope: { kind: 'thread' }
})
it('publishes complete lifecycle groups and preserves revised placement and durable retry authority', async () => {
const f = domainLifecycleFixture(cleanups)
await f.run({
kind: 'item',
identity: identity('first'),
body: { kind: 'status', text: 'original' },
options
})
const first = f.item('orca:first')!
const result = await f.run({
kind: 'lifecycle',
input: {
settlementId: 'many',
fence: 1,
mutations: [
status('first'),
...Array.from({ length: 200 }, (_, index) => status(`row-${index}`))
]
}
})
expect(result.value).toEqual({ epoch: 'epoch', sequence: 3 })
expect(f.item('orca:first')).toMatchObject({
revision: 2,
sequence: first.sequence,
observedAt: first.observedAt,
body: { text: 'first' }
})
expect(f.item('orca:row-198')).toMatchObject({ sequence: 2, sequenceIndex: 199 })
expect(f.item('orca:row-199')).toMatchObject({ sequence: 3 })
expect(result.publication?.invalidatedItemIds).toContain('orca:first')
f.reopen()
const duplicate = await f.run({
kind: 'lifecycle',
input: { settlementId: 'many', fence: 1, mutations: [status('should-never-appear')] }
})
expect(duplicate.publication?.items).toEqual([])
expect(f.item('orca:should-never-appear')).toBeUndefined()
await f.run({
kind: 'lifecycle',
input: {
settlementId: 'remove-turn',
fence: 1,
mutations: [{ kind: 'tombstone', identity: identity('first') }]
}
})
const restored = await f.run({
kind: 'item',
identity: identity('first'),
body: { kind: 'status', text: 'restored' },
options
})
expect(restored.value).toMatchObject({ revision: 4 })
})
it('publishes a same-command revival as current and a later tombstone as removed', async () => {
const f = domainLifecycleFixture(cleanups)
await f.run({
kind: 'item',
identity: identity('revived'),
body: { kind: 'status', text: 'before' },
options
})
const revived = await f.run({
kind: 'lifecycle',
input: {
settlementId: 'revival',
fence: 1,
mutations: [{ kind: 'tombstone', identity: identity('revived') }, status('revived')]
}
})
expect(revived.publication?.removedItemIds).toEqual([])
expect(revived.publication?.items).toMatchObject([{ itemId: 'orca:revived', revision: 3 }])
const removed = await f.run({
kind: 'lifecycle',
input: {
settlementId: 'removal',
fence: 1,
mutations: [status('revived'), { kind: 'tombstone', identity: identity('revived') }]
}
})
expect(removed.publication?.items).toEqual([])
expect(removed.publication?.removedItemIds).toEqual(['orca:revived'])
})
it('rolls back the entire lifecycle mutation group and its receipt if any write fails', async () => {
const f = domainLifecycleFixture(cleanups)
f.db.exec(
`CREATE TRIGGER refuse_item BEFORE INSERT ON journal_items WHEN NEW.item_id='orca:refuse' BEGIN SELECT RAISE(ABORT,'refused'); END`
)
await expect(
f.run({
kind: 'lifecycle',
input: { settlementId: 'retry', fence: 1, mutations: [status('prefix'), status('refuse')] }
})
).rejects.toThrow('refused')
expect(f.item('orca:prefix')).toBeUndefined()
f.db.exec('DROP TRIGGER refuse_item')
const retried = await f.run({
kind: 'lifecycle',
input: { settlementId: 'retry', fence: 1, mutations: [status('prefix')] }
})
expect(retried.publication?.items).toMatchObject([{ itemId: 'orca:prefix', revision: 1 }])
})
it('keeps FIFO settlement retry authority bounded without reordering a duplicate', async () => {
const f = domainLifecycleFixture(cleanups)
const insert = f.db.prepare(`INSERT INTO journal_settlements VALUES('chat','epoch',?,?)`)
for (let index = 0; index < 4096; index++) {
insert.run(`receipt-${index}`, index + 1)
}
await f.run({
kind: 'lifecycle',
input: { settlementId: 'receipt-0', fence: 1, mutations: [status('duplicate')] }
})
await f.run({
kind: 'lifecycle',
input: { settlementId: 'new', fence: 1, mutations: [status('new')] }
})
expect(f.item('orca:duplicate')).toBeUndefined()
expect(
f.db.prepare(`SELECT settlement_id FROM journal_settlements ORDER BY ordinal LIMIT 1`).get()
).toEqual({ settlement_id: 'receipt-1' })
expect(f.db.prepare(`SELECT COUNT(*) AS total FROM journal_settlements`).get()).toEqual({
total: 4096
})
})
it('returns direct personal input on start failure and lets an earlier handover win', async () => {
const f = domainLifecycleFixture(cleanups)
const failure = agentSessionFailureWords({ kind: 'notSignedIn' }, { surface: 'rejection' })
for (const id of ['queued', 'handed']) {
await f.run({
kind: 'submission',
input: {
clientMessageId: id,
body: { kind: 'message', role: 'user', blocks: [{ type: 'text', text: id }] },
fence: 1,
payloadFingerprint: id,
handoverRecorded: true,
source: { kind: 'user' },
origin: 'client'
}
})
}
await f.run({
kind: 'dispatch',
input: { clientMessageId: 'handed', fence: 1, state: 'pending', turnScope: { kind: 'thread' } }
})
await f.run({
kind: 'start-failure-settle',
input: { startKey: 'ignored', clientMessageId: 'handed', fence: 1, ...failure }
})
const settled = await f.run({
kind: 'start-failure-settle',
input: { startKey: 'failed', clientMessageId: 'queued', fence: 1, ...failure }
})
expect(
journalDomainQueueRow(f.db, { sessionId: 'chat', epoch: 'epoch' }, 'queued')?.card
).toMatchObject({ state: 'returned', body: { blocks: [{ type: 'text', text: 'queued' }] } })
expect(
settled.publication?.items.some(
(item) => item.body.kind === 'status' && item.body.failure?.kind === 'notSignedIn'
)
).toBe(true)
expect(f.item('orca:ignored')).toBeUndefined()
})
it('normalizes direct and lifecycle turn ends from the current Stop plus its matching transient overlay', async () => {
const f = domainLifecycleFixture(cleanups)
await f.run({
kind: 'item',
identity: identity('turn'),
body: { kind: 'turn', turnId: 't', state: 'running' },
options
})
f.db
.prepare(`UPDATE journal_chat_state SET queue_latest_stop_json=?`)
.run(JSON.stringify({ sequence: 1, event: { reason: 'user-stop', at: 50 } }))
const facts = { ...lifecycleFacts, stopSettle: { sequence: 1, settle: { settling: true } } }
await f.run(
{
kind: 'lifecycle',
input: {
settlementId: 'stop',
fence: 1,
mutations: [
{
kind: 'item',
identity: identity('turn'),
body: { kind: 'turn', turnId: 't', state: 'interrupted', completedAt: 70 },
turnScope: { kind: 'thread' }
}
]
}
},
facts
)
expect(f.item('orca:turn')?.body).toMatchObject({ state: 'interrupted', outcome: 'cancellation' })
await f.run(
{
kind: 'item',
identity: identity('new'),
body: { kind: 'turn', turnId: 'new', state: 'interrupted', completedAt: 70 },
options
},
{ ...facts, stopSettle: { sequence: 0, settle: { settling: true } } }
)
expect(f.item('orca:new')?.body).not.toHaveProperty('outcome')
const output = {
head: 'x'.repeat(300000),
byteLength: 300000,
digest: 'saved-digest',
truncated: false
}
await f.run({
kind: 'item',
identity: identity('tool'),
body: { kind: 'tool-call', name: 'read', input: {}, state: 'running', output },
options
})
expect(f.item('orca:tool')?.body).toMatchObject({
output: { head: 'x'.repeat(16384), byteLength: 300000, digest: 'saved-digest', truncated: true }
})
})
@@ -0,0 +1,242 @@
import { applyJournalDomainLifecycleDispatches } from './journal-domain-lifecycle-dispatch'
import { isDeepStrictEqual } from 'node:util'
import type Database from '../../sqlite/sync-database'
import type { AgentJournalCursor } from '../../../shared/agent-session/journal/agent-session-journal-identity'
import type { JournalLifecycleBatchInput } from './journal-store-contracts'
import type { JournalWriterPublication } from './journal-writer-changes'
import type { JournalWriterCoordinate } from './journal-writer-effects'
import type { JournalStopSettleFact } from './journal-writer-host-facts'
import { journalDomainContextHead } from './journal-sql-continuation-context'
import { readJournalDomainDispatchItem } from './journal-domain-dispatch-placement'
import { removeJournalDomainItem, journalDomainEventItem } from './journal-domain-item-removal'
import { agentJournalLinkageFields } from '../../../shared/agent-session/journal/agent-session-journal-producer'
import { journalLifecycleMutationItemId } from './writing/journal-lifecycle-mutation'
import {
partitionJournalLifecycleMutations,
journalLifecycleMutationFitsOneBatch
} from './writing/journal-lifecycle-batch-partition'
import { assertJournalFence } from './writing/journal-write-guards'
import { appendJournalSqlEvent } from './journal-sql-event-tail'
import { spendJournalSqlCommandCards } from './journal-sql-message-effects'
import { writeJournalDomainLifecycleItem } from './journal-domain-lifecycle-item'
export type JournalDomainLifecycleCommit = JournalWriterPublication & {
cursor: AgentJournalCursor
inputChanged: boolean
coordinates: JournalWriterCoordinate[]
removedItemIds: string[]
}
export function journalDomainLifecycleCommit(
db: Database.Database,
target: { sessionId: string; epoch: string }
): JournalDomainLifecycleCommit {
if (!db.isTransaction) {
throw new Error('journal lifecycle requires its writer transaction')
}
return {
cursor: journalDomainContextHead(db, target),
items: [],
receipts: [],
cards: [],
removedItemIds: [],
inputChanged: false,
coordinates: []
}
}
export function hasJournalDomainSettlement(
db: Database.Database,
target: { sessionId: string; epoch: string },
settlementId: string
): boolean {
return Boolean(
db
.prepare(
`SELECT 1 FROM journal_settlements WHERE session_id=? AND epoch=? AND settlement_id=?`
)
.get(target.sessionId, target.epoch, settlementId)
)
}
function recordSettlement(
db: Database.Database,
target: { sessionId: string; epoch: string },
settlementId: string
): void {
const prefix = [target.sessionId, target.epoch] as const
db.prepare(`INSERT OR IGNORE INTO journal_settlements(session_id,epoch,settlement_id,ordinal)
SELECT ?,?,?,COALESCE(MAX(ordinal),0)+1 FROM journal_settlements WHERE session_id=? AND epoch=?`).run(
...prefix,
settlementId,
...prefix
)
db.prepare(`DELETE FROM journal_settlements WHERE session_id=? AND epoch=? AND ordinal <=
(SELECT ordinal FROM journal_settlements WHERE session_id=? AND epoch=? ORDER BY ordinal DESC LIMIT 1 OFFSET 4096)`).run(
...prefix,
...prefix
)
}
/** Current dispatches precede the atomic mutation groups, exactly at this writer position. */
export function applyJournalDomainLifecycle(
db: Database.Database,
target: { sessionId: string; epoch: string },
input: JournalLifecycleBatchInput,
savedAt: number,
stopSettle?: JournalStopSettleFact
): JournalDomainLifecycleCommit {
const result = journalDomainLifecycleCommit(db, target)
if (!input.rejectsQueued && hasJournalDomainSettlement(db, target, input.settlementId)) {
return result
}
if (!applyJournalDomainLifecycleDispatches(db, target, input, savedAt, result)) {
return result
}
if (hasJournalDomainSettlement(db, target, input.settlementId)) {
return result
}
const mutations = input.mutations.map((mutation) =>
mutation.kind === 'item' && mutation.ownerFence === undefined && input.ownerFence !== undefined
? { ...mutation, ownerFence: input.ownerFence }
: mutation
)
const deleted = new Set(result.removedItemIds)
let named = false
const planned = new Set<string>()
for (const chunk of partitionJournalLifecycleMutations(input.settlementId, mutations, {
...input,
epoch: target.epoch
})) {
const only = chunk.mutations.length === 1 ? chunk.mutations[0] : undefined
const oversized =
only &&
!journalLifecycleMutationFitsOneBatch(chunk.settlementId, only, {
...input,
epoch: target.epoch
})
const id = named ? chunk.settlementId : input.settlementId
if (!oversized) {
named = true
}
if (!oversized && hasJournalDomainSettlement(db, target, id)) {
continue
}
const sequence = result.cursor.sequence + 1
const changedItems: JournalWriterPublication['items'] = []
const removedItemIds: string[] = []
const head = db
.prepare(`SELECT highest_fence FROM journal_chat_state WHERE session_id=? AND epoch=?`)
.get(target.sessionId, target.epoch)!
assertJournalFence(input.fence, Number(head.highest_fence))
for (const [index, mutation] of chunk.mutations.entries()) {
const rawId = journalLifecycleMutationItemId(mutation)
const alias = db
.prepare(
`SELECT item_id FROM journal_item_aliases WHERE session_id=? AND epoch=? AND provider_item_id=?`
)
.get(target.sessionId, target.epoch, rawId)
const itemId = alias ? String(alias.item_id) : rawId
const previous = readJournalDomainDispatchItem(db, target, itemId)
const tombstone = db
.prepare(
`SELECT revision FROM journal_item_tombstones WHERE session_id=? AND epoch=? AND item_id=?`
)
.get(target.sessionId, target.epoch, itemId)
const repeated = planned.has(itemId)
planned.add(itemId)
if (
oversized &&
!repeated &&
(mutation.kind === 'tombstone'
? tombstone
: previous &&
isDeepStrictEqual(previous.item.body, mutation.body) &&
(!Object.hasOwn(mutation, 'echoOf') ||
db
.prepare(
`SELECT 1 FROM journal_item_aliases WHERE session_id=? AND epoch=? AND provider_item_id=? AND echo_declared=1`
)
.get(target.sessionId, target.epoch, rawId)) &&
(mutation.linkage === undefined ||
isDeepStrictEqual(
agentJournalLinkageFields(previous.item),
agentJournalLinkageFields(mutation.linkage)
)))
) {
continue
}
if (mutation.kind === 'tombstone') {
const removed = removeJournalDomainItem(db, target, rawId, sequence)
changedItems.splice(
0,
changedItems.length,
...changedItems.filter((item) => item.itemId !== removed.itemId),
...removed.items
)
deleted.add(removed.itemId)
removedItemIds.push(removed.itemId)
} else {
const commit = writeJournalDomainLifecycleItem(db, target, mutation, {
fence: input.fence,
recovered: input.recovered,
sequence,
sequenceIndex: oversized ? 0 : index,
savedAt,
stopSettle
})
const revived = commit.items[0]!.itemId
removedItemIds.splice(
0,
removedItemIds.length,
...removedItemIds.filter((id) => id !== revived)
)
deleted.delete(revived)
changedItems.push(...commit.items)
result.receipts.push(...commit.receipts)
result.inputChanged ||= commit.receipts.length > 0
result.acceptedInputs = commit.acceptedInputs ?? result.acceptedInputs
}
}
if (oversized && changedItems.length === 0 && removedItemIds.length === 0) {
continue
}
const spent = spendJournalSqlCommandCards(db, [target.sessionId, target.epoch], savedAt)
result.cards.push(...spent.cards)
result.inputChanged ||= spent.cards.length > 0
if (spent.editDeadline !== undefined) {
result.editDeadline = spent.editDeadline
}
appendJournalSqlEvent(
db,
target,
sequence,
savedAt,
{
items: changedItems.map(journalDomainEventItem),
removedItemIds,
submissions: result.receipts
.filter((receipt) => receipt.cursor.sequence === sequence)
.map((receipt) => receipt.clientMessageId),
cards: spent.cards.map((card) => card.messageId)
},
{ fence: input.fence, observedAt: savedAt }
)
if (!oversized) {
recordSettlement(db, target, id)
}
result.items.push(...changedItems)
result.removedItemIds.push(...removedItemIds)
result.cursor = { ...result.cursor, sequence }
result.coordinates.push({
kind: oversized ? only!.kind : 'lifecycle-batch',
epoch: target.epoch,
seq: sequence
})
}
result.removedItemIds = [...deleted]
result.items = [...new Map(result.items.map((item) => [item.itemId, item])).values()].filter(
(item) => !deleted.has(item.itemId)
)
return result
}
@@ -0,0 +1,79 @@
import type Database from '../../sqlite/sync-database'
import {
AgentSessionRefusalError,
refuse
} from '../../../shared/agent-session/failures/agent-session-wire-refusals'
import { parseAgentJournalItemKey } from '../../../shared/agent-session/journal/agent-session-journal-item-key'
import type { JournalAppendResult, JournalPromptMutationInput } from './journal-store-contracts'
import { validateJournalPendingPrompt } from './writing/journal-prompt-mutation'
import { applyJournalDomainItem } from './journal-domain-item'
import { journalDomainTimelineReads } from './journal-domain-timeline-reads'
import {
journalDomainLifecycleCommit,
type JournalDomainLifecycleCommit
} from './journal-domain-lifecycle'
import type { JournalStopSettleFact } from './journal-writer-host-facts'
/** Revision and answer ownership are checked after every preceding writer command. */
export function applyJournalDomainPromptMutation(
db: Database.Database,
target: { sessionId: string; epoch: string },
input: JournalPromptMutationInput,
savedAt: number,
stopSettle?: JournalStopSettleFact
): JournalDomainLifecycleCommit & { value: JournalAppendResult } {
const empty = journalDomainLifecycleCommit(db, target)
const current = journalDomainTimelineReads(db, target).item(input.itemId)
if (
input.resolution.state === 'cancelled' &&
(current?.body.kind === 'approval' || current?.body.kind === 'question') &&
current.body.resolution.state === 'cancelled'
) {
return {
...empty,
value: { itemId: current.itemId, revision: current.revision, cursor: empty.cursor }
}
}
const pending = validateJournalPendingPrompt(current ?? undefined, target.sessionId, input)
if (!pending.ok) {
throw new AgentSessionRefusalError(pending.refusal)
}
const identity = parseAgentJournalItemKey(input.itemId)
if (!identity) {
throw new AgentSessionRefusalError(
refuse(
'agent_session_operation_invalid',
{ reason: 'requestMalformed' },
`Item id ${input.itemId} is not a well-formed item key.`
)
)
}
const written = applyJournalDomainItem(
db,
target,
{
kind: 'item',
identity,
body: { ...pending.prompt, resolution: input.resolution },
options: input.options
},
savedAt,
stopSettle
)
const item = written.items.find((item) => item.itemId === current!.itemId)!
const cursor = { ...empty.cursor, sequence: written.cursor.sequence }
return {
...written,
cursor,
removedItemIds: [],
coordinates: [
{
kind: 'item',
epoch: target.epoch,
seq: cursor.sequence,
promptAnswer: { itemId: item.itemId, revision: item.revision, resolution: input.resolution }
}
],
value: { itemId: item.itemId, revision: item.revision, cursor }
}
}
@@ -0,0 +1,235 @@
import { afterEach, expect, it } from 'vitest'
import {
domainLifecycleFixture,
lifecycleIdentity as identity,
lifecycleOptions as options
} from './journal-domain-lifecycle.test-fixture'
import type { JournalWriterStep } from './writing/journal-writer-step'
import type { AgentJournalApprovalItem } from '../../../shared/agent-session/journal/agent-session-journal-types'
const cleanups: (() => void)[] = []
afterEach(() => {
for (const cleanup of cleanups.splice(0)) {
cleanup()
}
})
const literal = (id: string): JournalWriterStep => ({
kind: 'item',
identity: identity(id),
body: { kind: 'status', text: id },
options,
reservedBytes: 4096
})
const pending: AgentJournalApprovalItem = {
kind: 'approval',
title: 'Run?',
detail: null,
options: [{ id: 'allow', label: 'Allow' }],
resolution: { state: 'pending', selectedOptionId: null, resolvedBy: null, resolvedAt: null }
}
it('commits the successful step prefix with only its actual payloads and skips the failed suffix', async () => {
const f = domainLifecycleFixture(cleanups)
f.db.exec(
`CREATE TRIGGER refuse_step BEFORE INSERT ON journal_items WHEN NEW.item_id='orca:refused' BEGIN SELECT RAISE(ABORT,'step refused'); END`
)
const result = await f.run({
kind: 'steps',
steps: [literal('first'), literal('refused'), literal('suffix')]
})
expect(result.value).toMatchObject({
outcomes: [{ kind: 'committed', wrote: true }],
failure: { message: 'step refused' },
cursor: { epoch: 'epoch', sequence: 1 }
})
expect(result.publication?.items.map((item) => item.itemId)).toEqual(['orca:first'])
expect(f.item('orca:refused')).toBeUndefined()
expect(f.item('orca:suffix')).toBeUndefined()
expect(result.publication?.invalidatedItemIds).toEqual(['orca:first'])
})
it('settles current tools and turns and refuses a later provider close or text revival', async () => {
const f = domainLifecycleFixture(cleanups)
const inTurn = { kind: 'turn' as const, turnItemId: 'orca:turn' }
const steps: JournalWriterStep[] = [
{
kind: 'resolved-item',
options,
reservedBytes: 4096,
resolution: {
kind: 'turn-open',
identity: identity('turn'),
body: { kind: 'turn', turnId: 't', state: 'running' }
}
},
{
kind: 'resolved-item',
options: { ...options, turnScope: inTurn },
reservedBytes: 4096,
resolution: {
kind: 'guarded-item',
identity: identity('tool'),
body: { kind: 'tool-call', name: 'read', input: {}, state: 'running' },
change: 'open'
}
},
{
kind: 'settlement',
settlementId: 'ended',
fence: 1,
reservedBytes: 8192,
resolution: {
kind: 'timeline-settlement',
scope: 'session',
keep: [],
ending: { turns: 'running', end: { state: 'interrupted', completedAt: 80 } }
}
},
{
kind: 'resolved-item',
options: { ...options, turnScope: inTurn },
reservedBytes: 4096,
resolution: {
kind: 'guarded-item',
identity: identity('tool'),
body: { kind: 'tool-call', name: 'read', input: {}, state: 'completed' },
change: 'close'
}
},
{
kind: 'resolved-item',
options: { ...options, turnScope: inTurn },
reservedBytes: 4096,
resolution: {
kind: 'text-snapshot',
identity: identity('late-text'),
body: { kind: 'message', role: 'assistant', blocks: [{ type: 'text', text: 'late' }] }
}
}
]
const result = await f.run({ kind: 'steps', steps })
expect(result.value).toMatchObject({
outcomes: [
{ kind: 'committed', wrote: true },
{ kind: 'committed', wrote: true },
{ kind: 'committed', wrote: true },
{ kind: 'dropped', reason: 'item-settled' },
{ kind: 'dropped', reason: 'turn-settled', turnItemId: 'orca:turn' }
]
})
expect(f.item('orca:tool')?.body).toMatchObject({ state: 'failed', endedAs: 'interrupted' })
expect(f.item('orca:turn')?.body).toMatchObject({ state: 'interrupted', completedAt: 80 })
expect(f.item('orca:late-text')).toBeUndefined()
})
it('verifies history authority at the write position and accepts a proven current revision only', async () => {
const f = domainLifecycleFixture(cleanups)
await f.run({ kind: 'item', identity: identity('prompt'), body: pending, options })
const permit = new Int32Array(new SharedArrayBuffer(4))
Atomics.store(permit, 0, 1)
const settlement: JournalWriterStep = {
kind: 'settlement',
settlementId: 'history',
fence: 1,
reservedBytes: 8192,
resolution: {
kind: 'history-catch-up',
expectedCursor: { epoch: 'epoch', sequence: 1 },
expectedItems: [{ key: 'orca:prompt', canonicalItemId: 'orca:prompt', revision: 1 }],
permit,
deadline: Date.now() + 60000,
mutations: [
{
kind: 'item',
identity: identity('prompt'),
body: {
...pending,
resolution: {
state: 'resolved',
selectedOptionId: 'allow',
resolvedBy: 'user',
resolvedAt: 60
}
},
turnScope: { kind: 'thread' }
}
]
}
}
const stale = await f.run({ kind: 'steps', steps: [literal('earlier-write'), settlement] })
expect(stale.value).toMatchObject({
outcomes: [{ kind: 'committed', wrote: true }, { kind: 'dropped' }]
})
expect(f.item('orca:prompt')?.body).toMatchObject({ resolution: { state: 'pending' } })
if (settlement.resolution.kind !== 'history-catch-up') {
throw new Error('expected history')
}
settlement.resolution.expectedCursor = { epoch: 'epoch', sequence: 2 }
const valid = await f.run({ kind: 'steps', steps: [settlement] })
expect(valid.value).toMatchObject({ outcomes: [{ kind: 'committed', wrote: true }] })
expect(f.item('orca:prompt')?.body).toMatchObject({
resolution: { state: 'resolved', selectedOptionId: 'allow' }
})
})
it('chooses request incarnations and lets earlier prompt answers win over a withdrawal', async () => {
const f = domainLifecycleFixture(cleanups)
const request = { agent: 'grok' as const, sessionId: 'chat', generation: 'g1', key: 'p1' }
const open: JournalWriterStep = {
kind: 'resolved-item',
options,
reservedBytes: 4096,
resolution: { kind: 'request-open', request, body: pending, turnItemId: null }
}
const created = await f.run({ kind: 'steps', steps: [open, open] })
expect(created.value).toMatchObject({
outcomes: [{ kind: 'committed', wrote: true }, { kind: 'dropped' }]
})
const item = created.publication!.items[0]!
const answer = await f.run({
kind: 'prompt-mutate',
input: {
itemId: item.itemId,
expectedRevision: 1,
resolution: {
state: 'resolved',
selectedOptionId: 'allow',
resolvedBy: 'user',
resolvedAt: 60
},
options
}
})
expect(answer.value).toMatchObject({ itemId: item.itemId, revision: 2 })
await f.run({
kind: 'steps',
steps: [
{
kind: 'settlement',
settlementId: 'withdraw',
fence: 1,
reservedBytes: 4096,
resolution: { kind: 'request-withdrawn', request }
}
]
})
expect(f.item(item.itemId)?.body).toMatchObject({ resolution: { state: 'resolved' } })
await expect(
f.run({
kind: 'prompt-mutate',
input: {
itemId: item.itemId,
expectedRevision: 1,
resolution: {
state: 'cancelled',
selectedOptionId: null,
resolvedBy: null,
resolvedAt: null
},
options
}
})
).rejects.toMatchObject({ refusal: { code: 'agent_session_item_revision_stale' } })
const next = await f.run({ kind: 'steps', steps: [open] })
expect(next.publication?.items[0]?.itemId).not.toBe(item.itemId)
})
@@ -0,0 +1,105 @@
import type Database from '../../sqlite/sync-database'
import type { AgentJournalRenderItem } from '../../../shared/agent-session/journal/agent-session-journal-types'
import type { JournalTimelineView } from './writing/journal-timeline-view'
import { isUnsettledJournalTimelineItem } from './writing/journal-timeline-view'
import {
journalDomainLatestStop,
journalDomainStopDecidesTurn
} from './journal-domain-item-normalization'
import type { JournalStopSettleFact } from './journal-writer-host-facts'
/** Typed named selections used only during the owning synchronous writer command. */
export function journalDomainTimelineReads(
db: Database.Database,
target: { sessionId: string; epoch: string },
stopSettle?: JournalStopSettleFact
): JournalTimelineView {
const prefix = [target.sessionId, target.epoch] as const
const decode = (row: Record<string, unknown> | undefined): AgentJournalRenderItem | null =>
row ? JSON.parse(String(row.payload_json)) : null
const item = (key: string) =>
decode(
db
.prepare(`SELECT payload_json FROM journal_items
WHERE session_id=? AND epoch=? AND hidden=0 AND item_id=COALESCE((SELECT item_id FROM journal_item_aliases
WHERE session_id=? AND epoch=? AND provider_item_id=?),?)`)
.get(...prefix, ...prefix, key, key)
)
function* withKeyPrefix(keyPrefix: string) {
let after: string | null = null
const matching: Record<string, unknown>[] = []
for (;;) {
const rows = db
.prepare(`SELECT item_id,payload_json,ordinal FROM journal_items WHERE session_id=? AND epoch=? AND hidden=0
AND item_id>=? AND item_id<? ${after === null ? '' : 'AND item_id>?'} ORDER BY item_id LIMIT 64`)
.all(...prefix, keyPrefix, `${keyPrefix}\uffff`, ...(after === null ? [] : [after]))
matching.push(...rows)
if (rows.length < 64) {
break
}
after = String(rows.at(-1)!.item_id)
}
matching.sort((a, b) => Number(a.ordinal) - Number(b.ordinal))
for (const row of matching) {
yield decode(row)!
}
}
function* unsettled(turnItemId: string | null) {
let after: [number, string] | undefined
for (;;) {
const rows = db
.prepare(`SELECT item_id,payload_json,ordinal FROM journal_items INDEXED BY journal_items_unsettled
WHERE session_id=? AND epoch=? AND hidden=0 AND (lifecycle_state IN ('running','pending') OR live_work=1)
${after ? 'AND (ordinal,item_id)>(?,?)' : ''} ORDER BY ordinal,item_id LIMIT 128`)
.all(...prefix, ...(after ?? []))
for (const row of rows) {
const value = decode(row)!
if (
(turnItemId === null ||
(value.turnScope?.kind === 'turn' && value.turnScope.turnItemId === turnItemId)) &&
isUnsettledJournalTimelineItem(value.body)
) {
yield value
}
}
if (rows.length < 128) {
return
}
const last = rows.at(-1)!
after = [Number(last.ordinal), String(last.item_id)]
}
}
return {
item,
itemBody: (key) => item(key)?.body ?? null,
newestTurn: () =>
decode(
db
.prepare(
`SELECT payload_json FROM journal_items WHERE session_id=? AND epoch=? AND hidden=0 AND kind='turn' ORDER BY sequence DESC,ordinal DESC LIMIT 1`
)
.get(...prefix)
),
withKeyPrefix,
newestWithKeyPrefix: (keyPrefix) => {
return decode(
db
.prepare(`SELECT payload_json FROM journal_items
WHERE session_id=? AND epoch=? AND hidden=0 AND item_id>=? AND item_id<?
ORDER BY sequence DESC,ordinal ASC LIMIT 1`)
.get(...prefix, keyPrefix, `${keyPrefix}\uffff`)
)
},
contextWindowHeld: () =>
Boolean(
db
.prepare(
`SELECT 1 FROM journal_items WHERE session_id=? AND epoch=? AND hidden=0 AND context_window=1 LIMIT 1`
)
.get(...prefix)
),
unsettled,
stopDecidesTurn: (turnId, endedAt) =>
journalDomainStopDecidesTurn(journalDomainLatestStop(db, target, stopSettle), turnId, endedAt)
}
}
@@ -0,0 +1,99 @@
import { journalDomainPublicCursor } from './journal-domain-context-replacement'
import { claimJournalSqlItemInputs } from './journal-sql-item-claims'
import type { AgentJournalCursor } from '../../../shared/agent-session/journal/agent-session-journal-identity'
import type Database from '../../sqlite/sync-database'
import type { JournalWriterCommand } from './journal-writer-command'
import type { JournalWriterCommit, JournalWriterPublication } from './journal-writer-changes'
import { applyJournalWriterEffect, type JournalWriterCoordinate } from './journal-writer-effects'
export function finishJournalSqlCommand(
db: Database.Database,
stateDirectory: string,
command: JournalWriterCommand,
result: JournalWriterPublication & {
cursor: JournalWriterCommit['cursor']
publicCursor?: AgentJournalCursor
inputChanged: boolean
},
value: unknown,
coordinates: readonly JournalWriterCoordinate[],
invalidatedItemIds: string[] = []
): JournalWriterCommit {
const physicalEpoch = coordinates.at(-1)?.epoch ?? command.target.epoch
const cursor =
result.publicCursor ??
(result.cursor.epoch !== physicalEpoch
? result.cursor
: journalDomainPublicCursor(
db,
{ sessionId: command.target.sessionId, epoch: physicalEpoch },
result.cursor.sequence
))
const publicCoordinates = coordinates.map((position) => ({ ...position, epoch: cursor.epoch }))
const claims =
coordinates.length > 0
? claimJournalSqlItemInputs(db, stateDirectory, command, result)
: { referencedUploads: result.referencedUploads ?? [] }
const effects =
coordinates.length > 0
? (command.effects ?? []).map((effect) =>
applyJournalWriterEffect(db, stateDirectory, effect, publicCoordinates)
)
: []
const publication = {
...result,
cursor,
receipts: result.receipts.map((receipt) => ({
...receipt,
cursor: { ...receipt.cursor, epoch: cursor.epoch }
})),
invalidatedItemIds,
referencedUploads: claims.referencedUploads
}
return {
cursor,
inputChanged: result.inputChanged,
keys: [],
inputKeys: [],
items: [
...result.items.map((item) => ({
itemId: item.itemId,
deleted: false as const,
revision: item.revision,
sequence: item.sequence,
sequenceIndex: item.sequenceIndex ?? 0
})),
...(result.removedItemIds ?? []).map((itemId) => ({
itemId,
deleted: true as const,
revision: 0
}))
],
publication,
value: publicJournalSqlValue(command, value, cursor),
...('goals' in claims ? { goals: claims.goals } : {}),
effects,
...(coordinates.length > 0 && command.effects ? { receiptWritten: true as const } : {})
}
}
function publicJournalSqlValue(
command: JournalWriterCommand,
value: unknown,
cursor: AgentJournalCursor
): unknown {
switch (command.operation.kind) {
case 'item':
case 'item-claiming':
case 'prompt-mutate':
case 'steps':
return value && typeof value === 'object' ? { ...value, cursor } : value
case 'submission':
case 'dispatch':
case 'lifecycle':
case 'tombstone':
return value == null ? value : cursor
default:
return value
}
}
@@ -1,10 +1,9 @@
import { agentJournalItemKey } from '../../../shared/agent-session/journal/agent-session-journal-item-key'
import { agentSessionJournalProviderHandle } from '../../../shared/agent-session/lifecycle/agent-session-provider-handle-encoding'
import type Database from '../../sqlite/sync-database'
import type { JournalWriterCommand } from './journal-writer-command'
import type { JournalWriterCommit, JournalWriterPublication } from './journal-writer-changes'
import { applyJournalWriterEffect, type JournalWriterCoordinate } from './journal-writer-effects'
import { applyJournalDomainItem } from './journal-domain-item'
import type { JournalWriterCommit } from './journal-writer-changes'
import { finishJournalSqlCommand } from './journal-sql-command-result'
import { applyJournalSqlItemCommand } from './journal-sql-item-command'
import { applyJournalDomainSubmission } from './journal-domain-submission-admission'
import { applyJournalDomainDispatch } from './journal-domain-dispatch'
import { applyJournalDomainQueueCommand } from './journal-domain-queue-command'
@@ -12,7 +11,10 @@ import { applyJournalDomainInputRecovery } from './journal-domain-input-recovery
import { applyJournalDomainCommandTurn } from './journal-domain-command-turn'
import { applyJournalDomainContextCommand } from './journal-domain-context-command'
import { applyJournalDomainTombstone } from './journal-domain-item-removal'
import { applyJournalSqlMessageSteps, type JournalSqlMessage } from './journal-sql-message-commit'
import { applyJournalDomainLifecycle } from './journal-domain-lifecycle'
import { applyJournalDomainGenerationSettlement } from './journal-domain-generation-settlement'
import { applyJournalDomainPromptMutation } from './journal-domain-prompt-mutation'
import { applyJournalSqlStepCommand } from './journal-sql-step-command'
/** Every command decides against current rows at its position on the sole writer. */
export class JournalSqlCommand {
@@ -26,40 +28,17 @@ export class JournalSqlCommand {
throw new Error('journal SQL command requires its transaction')
}
const savedAt = command.savedAt ?? now
command = { ...command, savedAt }
const { operation, target } = command
switch (operation.kind) {
case 'item':
case 'item-claiming': {
const result = applyJournalDomainItem(
case 'item-claiming':
return applyJournalSqlItemCommand(
this.db,
target,
{ ...operation, kind: 'item' },
this.stateDirectory,
{ ...command, operation },
savedAt
)
const itemId = agentJournalItemKey(operation.identity)
const written = result.items.find((item) => item.itemId === itemId) ?? result.items[0]
return this.finish(
command,
result,
written
? {
cursor: result.cursor,
itemId: written.itemId,
revision: written.revision
}
: null,
result.outcome.kind === 'committed' && result.outcome.wrote
? [
{
kind: 'item',
epoch: target.epoch,
seq: result.cursor.sequence
}
]
: [],
result.items.map((item) => item.itemId)
)
}
case 'submission': {
if (!command.facts) {
throw new Error('journal submission omitted its identity facts')
@@ -72,7 +51,9 @@ export class JournalSqlCommand {
command.facts,
savedAt
)
return this.finish(
return finishJournalSqlCommand(
this.db,
this.stateDirectory,
command,
result,
result.value,
@@ -88,7 +69,9 @@ export class JournalSqlCommand {
case 'accept-late':
case 'late-dispatch': {
const result = applyJournalDomainDispatch(this.db, target, operation, savedAt)
return this.finish(
return finishJournalSqlCommand(
this.db,
this.stateDirectory,
command,
result,
result.value,
@@ -116,7 +99,9 @@ export class JournalSqlCommand {
command.facts ?? {},
savedAt
)
return this.finish(
return finishJournalSqlCommand(
this.db,
this.stateDirectory,
command,
result,
result.value,
@@ -152,7 +137,9 @@ export class JournalSqlCommand {
: operation,
savedAt
)
return this.finish(
return finishJournalSqlCommand(
this.db,
this.stateDirectory,
command,
result,
result.cursor,
@@ -161,7 +148,7 @@ export class JournalSqlCommand {
position.kind === 'context-item' || position.kind === 'replacement-item'
? 'item'
: 'tombstone',
epoch: result.cursor.epoch,
epoch: position.cursor.epoch,
seq: position.cursor.sequence
})),
[...result.items.map((item) => item.itemId), ...result.removedItemIds]
@@ -169,7 +156,9 @@ export class JournalSqlCommand {
}
case 'tombstone': {
const result = applyJournalDomainTombstone(this.db, target, operation, savedAt)
return this.finish(
return finishJournalSqlCommand(
this.db,
this.stateDirectory,
command,
{ ...result, cards: [], receipts: [], inputChanged: true },
result.cursor,
@@ -199,7 +188,9 @@ export class JournalSqlCommand {
: result.result.kind === 'queue-withdraw'
? result.result.cards
: undefined
return this.finish(
return finishJournalSqlCommand(
this.db,
this.stateDirectory,
command,
{ ...result, items: [], receipts: [] },
value,
@@ -208,91 +199,78 @@ export class JournalSqlCommand {
: []
)
}
case 'steps': {
const text = textSteps(operation.steps)
if (!text) {
throw new Error('journal non-text steps are not migrated')
case 'lifecycle': {
if (command.effects) {
throw new Error('journal lifecycle batches carry no receipt')
}
const result = applyJournalSqlMessageSteps(this.db, {
const result = applyJournalDomainLifecycle(
this.db,
target,
steps: operation.dropped ? [] : text,
savedAt
})
if (operation.dropped) {
result.outcomes = text.map(() => ({ kind: 'dropped' }))
}
return this.finish(
operation.input,
savedAt,
command.facts?.stopSettle
)
return finishJournalSqlCommand(
this.db,
this.stateDirectory,
command,
result,
{
outcomes: result.outcomes,
cursor: result.cursor,
items: result.items,
...(result.failure ? { failure: result.failure } : {})
},
[]
result.cursor,
result.coordinates,
[...result.items.map((item) => item.itemId), ...result.removedItemIds]
)
}
case 'stale-settle':
case 'dead-generation-settle':
case 'unheld-turns-settle':
case 'start-failure-settle': {
if (command.effects) {
throw new Error('journal generation settlements carry no receipt')
}
const result = applyJournalDomainGenerationSettlement(
this.db,
target,
operation,
savedAt,
command.facts?.stopSettle
)
return finishJournalSqlCommand(
this.db,
this.stateDirectory,
command,
result,
result.value,
result.coordinates,
[...result.items.map((item) => item.itemId), ...result.removedItemIds]
)
}
case 'prompt-mutate': {
const result = applyJournalDomainPromptMutation(
this.db,
target,
operation.input,
savedAt,
command.facts?.stopSettle
)
return finishJournalSqlCommand(
this.db,
this.stateDirectory,
command,
result,
result.value,
result.coordinates,
result.items.map((item) => item.itemId)
)
}
case 'steps':
return applyJournalSqlStepCommand(
this.db,
this.stateDirectory,
{ ...command, operation },
savedAt
)
default:
throw new Error(`journal command ${operation.kind} is not migrated`)
}
}
private finish(
command: JournalWriterCommand,
result: JournalWriterPublication & {
cursor: JournalWriterCommit['cursor']
inputChanged: boolean
},
value: unknown,
coordinates: readonly JournalWriterCoordinate[],
invalidatedItemIds: string[] = []
): JournalWriterCommit {
const effects =
coordinates.length > 0
? (command.effects ?? []).map((effect) =>
applyJournalWriterEffect(this.db, this.stateDirectory, effect, coordinates)
)
: []
return {
cursor: result.cursor,
inputChanged: result.inputChanged,
keys: [],
inputKeys: [],
items: [
...result.items.map((item) => ({
itemId: item.itemId,
deleted: false as const,
revision: item.revision,
sequence: item.sequence,
sequenceIndex: item.sequenceIndex ?? 0
})),
...(result.removedItemIds ?? []).map((itemId) => ({
itemId,
deleted: true as const,
revision: 0
}))
],
publication: { ...result, invalidatedItemIds },
value,
effects,
...(coordinates.length > 0 && command.effects ? { receiptWritten: true as const } : {})
}
}
}
function textSteps(
steps: Extract<JournalWriterCommand['operation'], { kind: 'steps' }>['steps']
): JournalSqlMessage[] | null {
if (steps.length === 0) {
return null
}
const messages: JournalSqlMessage[] = []
for (const step of steps) {
if (step.kind !== 'resolved-item' || step.resolution.kind !== 'text-snapshot') {
return null
}
messages.push({ ...step.resolution, options: step.options })
}
return messages
}
@@ -0,0 +1,69 @@
import type Database from '../../sqlite/sync-database'
import { agentJournalItemKey } from '../../../shared/agent-session/journal/agent-session-journal-item-key'
import type { JournalWriterCommand } from './journal-writer-command'
import type { JournalWriterPublication } from './journal-writer-changes'
import { claimAgentSessionAttachmentsInTransaction } from '../agent-session-attachments/agent-session-attachment-claims'
import { JournalGoalAttachmentInverse } from './writing/journal-goal-attachment-inverse'
/** Durable claims commit with input writes; the live inverse is adopted only after acknowledgement. */
export function claimJournalSqlItemInputs(
db: Database.Database,
stateDirectory: string,
command: JournalWriterCommand,
publication: JournalWriterPublication
) {
const { operation, target } = command
const userItems = publication.items.filter(
(item) => item.body.kind === 'message' && item.body.role === 'user'
)
if (operation.kind !== 'item-claiming' && userItems.length === 0) {
return { referencedUploads: publication.referencedUploads ?? [] }
}
const goals = new JournalGoalAttachmentInverse(target.sessionId)
if (command.facts?.goals) {
goals.adopt(command.facts.goals)
}
const referencedUploads = [...(publication.referencedUploads ?? [])]
if (operation.kind === 'item-claiming') {
const itemId = agentJournalItemKey(operation.identity)
const claim = claimAgentSessionAttachmentsInTransaction(db, {
stateDirectory,
sessionId: target.sessionId,
body: operation.body,
required: true,
now: command.savedAt ?? Date.now()
})
goals.acquired(
claim.referenced,
claim.inserted,
operation.body.sentAs === 'goal' ? itemId : undefined
)
referencedUploads.push(...claim.referenced)
} else if (
operation.kind === 'item' ||
operation.kind === 'lifecycle' ||
operation.kind === 'steps' ||
operation.kind === 'prompt-mutate'
) {
for (const item of userItems) {
if (item.body.kind !== 'message' || item.body.role !== 'user' || goals.isLive(item.itemId)) {
continue
}
const claim = claimAgentSessionAttachmentsInTransaction(db, {
stateDirectory,
sessionId: target.sessionId,
body: item.body,
required: false,
now: command.savedAt ?? Date.now()
})
goals.acquired(claim.referenced, claim.inserted)
referencedUploads.push(...claim.referenced)
}
}
return {
referencedUploads,
...(operation.kind === 'item-claiming' || command.facts?.goals
? { goals: goals.snapshot() }
: {})
}
}
@@ -0,0 +1,162 @@
import { mkdirSync, writeFileSync } from 'node:fs'
import { join } from 'node:path'
import { afterEach, expect, it } from 'vitest'
import {
domainLifecycleFixture,
lifecycleFacts as facts,
lifecycleIdentity as identity,
lifecycleOptions as options
} from './journal-domain-lifecycle.test-fixture'
import { readJournalDomainHistoryPage } from './journal-domain-history-page'
import { ensureAgentSessionAttachmentClaimTables } from '../agent-session-attachments/agent-session-attachment-claims'
import { agentSessionAttachmentStoreRoot } from '../agent-session-attachments/agent-session-attachment-references'
import { ensureCommandReceiptsTable } from './writing/command-receipt-schema'
import { JournalGoalAttachmentInverse } from './writing/journal-goal-attachment-inverse'
const cleanups: (() => void)[] = []
afterEach(() => {
for (const cleanup of cleanups.splice(0)) {
cleanup()
}
})
it('publishes and binds ordinary writes to the same public epoch as history after replacement', async () => {
const f = domainLifecycleFixture(cleanups)
f.db.exec(`INSERT INTO agent_session_records VALUES('chat','{}')`)
ensureCommandReceiptsTable(f.db)
await f.run({
kind: 'item',
identity: identity('before'),
body: { kind: 'status', text: 'before' },
options
})
const replaced = await f.run({
kind: 'epoch-replace',
reason: 'legacy_import',
fence: 1,
items: []
})
expect(replaced.cursor.epoch).toBe(
'context-v1:2cb86f27aabffce457946e9c46bd5d771895f95d6379dee0866d667e0ecb7adc'
)
const result = await f.run(
{
kind: 'item',
identity: identity('after'),
body: { kind: 'message', role: 'assistant', blocks: [{ type: 'text', text: 'after' }] },
options
},
facts,
[
{
kind: 'receipt',
scope: { kind: 'caller', callerKey: 'caller' },
receipt: {
operationId: 'op',
sessionId: 'chat',
callerKey: 'caller',
method: 'send',
fingerprint: 'op',
acceptedAt: 100,
status: 'accepted',
result: { kind: 'journal-row', epoch: 'placeholder', sequence: 1 }
},
row: { at: 'last', kinds: ['item'], answer: 'journal-row' }
}
]
)
expect(result.cursor).toEqual({
epoch: 'context-v1:2cb86f27aabffce457946e9c46bd5d771895f95d6379dee0866d667e0ecb7adc',
sequence: 3
})
expect(result.value).toMatchObject({
cursor: {
epoch: 'context-v1:2cb86f27aabffce457946e9c46bd5d771895f95d6379dee0866d667e0ecb7adc',
sequence: 3
}
})
expect(result.effects).toMatchObject([
{
receipt: {
result: {
kind: 'journal-row',
epoch: 'context-v1:2cb86f27aabffce457946e9c46bd5d771895f95d6379dee0866d667e0ecb7adc',
sequence: 3
}
}
}
])
expect(
JSON.parse(
String(
f.db.prepare(`SELECT result_json FROM agent_session_command_receipts`).get()!.result_json
)
)
).toEqual({
kind: 'journal-row',
epoch: 'context-v1:2cb86f27aabffce457946e9c46bd5d771895f95d6379dee0866d667e0ecb7adc',
sequence: 3
})
expect(f.db.prepare(`SELECT DISTINCT epoch FROM journal_events`).all()).toEqual([
{ epoch: 'epoch' }
])
expect(
readJournalDomainHistoryPage(f.db, { sessionId: 'chat', direction: 'tail', limit: 10 }).page
.liveCursor
).toEqual({
epoch: 'context-v1:2cb86f27aabffce457946e9c46bd5d771895f95d6379dee0866d667e0ecb7adc',
sequence: 3
})
})
it('rolls back missing and swept goal attachments and returns committed inverse accounting', async () => {
const f = domainLifecycleFixture(cleanups)
ensureAgentSessionAttachmentClaimTables(f.db)
const upload = '10000000-0000-4000-8000-000000000001'
const root = agentSessionAttachmentStoreRoot(f.directory)
const file = join(root, upload, 'pasted.txt')
const body = {
kind: 'message' as const,
role: 'user' as const,
sentAs: 'goal' as const,
blocks: [{ type: 'text' as const, text: file }]
}
const operation = { kind: 'item-claiming' as const, identity: identity('goal'), body, options }
await expect(f.run(operation)).rejects.toThrow('no longer stored')
expect(f.item('orca:goal')).toBeUndefined()
mkdirSync(join(root, upload), { recursive: true })
writeFileSync(file, 'attachment')
f.db.prepare(`INSERT INTO agent_session_attachment_sweeps VALUES(?,50)`).run(upload)
await expect(f.run(operation)).rejects.toThrow('no longer stored')
expect(f.item('orca:goal')).toBeUndefined()
expect(f.db.prepare(`SELECT last_sequence FROM journal_chat_state`).get()).toEqual({
last_sequence: 0
})
f.db.prepare(`DELETE FROM agent_session_attachment_sweeps WHERE upload_id=?`).run(upload)
const committed = await f.run(operation)
expect(committed.goals).toEqual({
uploads: [[upload, ['orca:goal']]],
goals: [['orca:goal', [upload]]]
})
expect(committed.publication?.referencedUploads).toEqual([upload])
expect(
f.db.prepare(`SELECT upload_id,session_id FROM agent_session_attachment_claims`).all()
).toEqual([{ upload_id: upload, session_id: 'chat' }])
const independent = await f.run(
{
kind: 'item',
identity: identity('independent'),
body: { ...body, sentAs: undefined },
options
},
{ ...facts, goals: committed.goals }
)
const inverse = new JournalGoalAttachmentInverse('chat')
inverse.adopt(independent.goals!)
const withdraw = inverse.withdraw('orca:goal')
withdraw.write(f.db)
withdraw.committed?.()
expect(f.db.prepare(`SELECT upload_id FROM agent_session_attachment_claims`).all()).toEqual([
{ upload_id: upload }
])
})
@@ -0,0 +1,38 @@
import type Database from '../../sqlite/sync-database'
import { agentJournalItemKey } from '../../../shared/agent-session/journal/agent-session-journal-item-key'
import type { JournalWriterCommand } from './journal-writer-command'
import { applyJournalDomainItem } from './journal-domain-item'
import { finishJournalSqlCommand } from './journal-sql-command-result'
/** Claims and the current item share the owning command's transaction and acknowledgement. */
export function applyJournalSqlItemCommand(
db: Database.Database,
stateDirectory: string,
command: JournalWriterCommand & {
operation: Extract<JournalWriterCommand['operation'], { kind: 'item' | 'item-claiming' }>
},
savedAt: number
) {
const { operation, target } = command
const result = applyJournalDomainItem(
db,
target,
{ ...operation, kind: 'item' },
savedAt,
command.facts?.stopSettle
)
const itemId = agentJournalItemKey(operation.identity)
const written = result.items.find((item) => item.itemId === itemId) ?? result.items[0]
const commit = finishJournalSqlCommand(
db,
stateDirectory,
command,
result,
written ? { cursor: result.cursor, itemId: written.itemId, revision: written.revision } : null,
result.outcome.kind === 'committed' && result.outcome.wrote
? [{ kind: 'item', epoch: target.epoch, seq: result.cursor.sequence }]
: [],
result.items.map((item) => item.itemId)
)
return commit
}
@@ -0,0 +1,54 @@
import type Database from '../../sqlite/sync-database'
import type { JournalWriterCommand } from './journal-writer-command'
import { finishJournalSqlCommand } from './journal-sql-command-result'
import { runJournalSqlSteps, journalSqlTextSteps } from './journal-sql-steps'
import { applyJournalSqlMessageSteps } from './journal-sql-message-commit'
/** Sparse text snapshots keep their body-free message route and never invalidate their stream. */
export function applyJournalSqlStepCommand(
db: Database.Database,
stateDirectory: string,
command: JournalWriterCommand & {
operation: Extract<JournalWriterCommand['operation'], { kind: 'steps' }>
},
savedAt: number
) {
if (command.effects) {
throw new Error('journal steps carry no receipt')
}
const { operation, target } = command
const text = journalSqlTextSteps(operation.steps)
if (!text) {
const result = runJournalSqlSteps(db, command, savedAt)
return finishJournalSqlCommand(
db,
stateDirectory,
command,
result,
result.value,
result.coordinates,
result.invalidatedItemIds ?? []
)
}
const result = applyJournalSqlMessageSteps(db, {
target,
steps: operation.dropped ? [] : text,
savedAt
})
if (operation.dropped) {
result.outcomes = text.map(() => ({ kind: 'dropped' }))
}
return finishJournalSqlCommand(
db,
stateDirectory,
command,
result,
{
outcomes: result.outcomes,
cursor: result.cursor,
items: result.items,
...(result.failure ? { failure: result.failure } : {})
},
[]
)
}
@@ -1,72 +1,263 @@
import type { JournalSqlMessage } from './journal-sql-message-commit'
import type Database from '../../sqlite/sync-database'
import { agentJournalItemKey } from '../../../shared/agent-session/journal/agent-session-journal-item-key'
import type { JournalWriterCommand } from './journal-writer-command'
import type { JournalWriterCommit } from './journal-writer-changes'
import type { JournalWriterHostFacts } from './journal-writer-host-facts'
import type { JournalWriterSession } from './journal-writer-session'
import { journalSqlFailure } from './journal-sql-failure'
import type { JournalStepsResult } from './writing/journal-writer-step'
import type {
JournalStepsResult,
JournalStepOutcome,
JournalWriterStep
} from './writing/journal-writer-step'
import { resolveJournalTimelineItem } from './writing/journal-timeline-resolution'
import { resolveProviderTimelineSettlement } from '../agent-session-timeline/provider-timeline-writer-resolution'
import { applyJournalDomainItem } from './journal-domain-item'
import { journalDomainTimelineReads } from './journal-domain-timeline-reads'
import {
applyJournalDomainLifecycle,
hasJournalDomainSettlement,
journalDomainLifecycleCommit,
type JournalDomainLifecycleCommit
} from './journal-domain-lifecycle'
import { journalLifecycleMutationItemId } from './writing/journal-lifecycle-mutation'
import { journalDomainContextHead } from './journal-sql-continuation-context'
/** A failed step discards its whole session; only successful sessions contribute to the prefix. */
export async function runJournalSqlSteps(
export type JournalDomainStepsCommit = JournalDomainLifecycleCommit & { value: JournalStepsResult }
/** Each successful step survives a later failure; failed-step payloads and effects never escape. */
export function runJournalSqlSteps(
db: Database.Database,
command: JournalWriterCommand & { operation: { kind: 'steps' } },
initialFacts: JournalWriterHostFacts,
createSession: (facts: JournalWriterHostFacts) => JournalWriterSession
): Promise<JournalWriterCommit> {
savedAt: number
): JournalDomainStepsCommit {
if (command.effects) {
throw new Error('journal step commands carry no host receipt')
}
const result: JournalStepsResult = { outcomes: [] }
const commits: JournalWriterCommit[] = []
let facts = initialFacts
if (command.operation.dropped) {
result.outcomes = command.operation.steps.map(() => ({ kind: 'dropped' }))
} else {
for (const step of command.operation.steps) {
db.exec('SAVEPOINT journal_step')
try {
const session = createSession(facts)
const outcome = session.collaborators.stepWriter.write({ kind: 'command', step })
const { rows: _rows, goals, ...commit } = await session.finish()
db.exec('RELEASE journal_step')
commits.push({ ...commit, effects: [], ...(facts.goals ? { goals } : {}) })
facts = { ...facts, goals }
result.outcomes.push(outcome)
} catch (error) {
db.exec('ROLLBACK TO journal_step; RELEASE journal_step')
result.failure = journalSqlFailure(error)
break
const result: JournalDomainStepsCommit = {
...journalDomainLifecycleCommit(db, command.target),
value: { outcomes: [] },
invalidatedItemIds: []
}
const { steps, dropped } = command.operation
if (dropped) {
result.value.outcomes = steps.map(() => ({ kind: 'dropped' }))
return result
}
const deleted = new Set<string>()
for (const step of steps) {
db.exec('SAVEPOINT journal_step')
try {
const { commit, outcome } = writeStep(db, command, step, savedAt)
db.exec('RELEASE journal_step')
if (commit) {
result.cursor = commit.cursor
result.items.push(...commit.items)
result.receipts.push(...commit.receipts)
result.cards.push(...commit.cards)
for (const item of commit.items) {
deleted.delete(item.itemId)
}
for (const id of commit.removedItemIds) {
deleted.add(id)
}
result.coordinates.push(...commit.coordinates)
result.inputChanged ||= commit.inputChanged
result.invalidatedItemIds!.push(
...(commit.invalidatedItemIds ?? [
...commit.items.map((item) => item.itemId),
...commit.removedItemIds
])
)
result.acceptedInputs = commit.acceptedInputs ?? result.acceptedInputs
if (commit.editDeadline !== undefined) {
result.editDeadline = commit.editDeadline
}
}
result.value.outcomes.push(outcome)
} catch (error) {
db.exec('ROLLBACK TO journal_step; RELEASE journal_step')
result.value.failure = journalSqlFailure(error)
break
}
}
// Even an empty, dropped or failed-first command must prove target ownership and coverage.
const { rows: _rows, goals, ...final } = await createSession(facts).finish()
const keys = new Map<string, JournalWriterCommit['keys'][number]>()
const items = new Map<string, JournalWriterCommit['items'][number]>()
const inputKeys = new Map<string, boolean>()
for (const commit of commits) {
for (const key of commit.keys) {
keys.set(JSON.stringify([key.collection, key.key]), key)
result.removedItemIds = [...deleted]
result.items = [...new Map(result.items.map((item) => [item.itemId, item])).values()].filter(
(item) => !deleted.has(item.itemId)
)
result.value.cursor = result.cursor
result.value.items = result.items
return result
}
function writeStep(
db: Database.Database,
command: JournalWriterCommand,
step: JournalWriterStep,
savedAt: number
): { commit?: JournalDomainLifecycleCommit; outcome: JournalStepOutcome } {
const { target } = command
const view = journalDomainTimelineReads(db, target, command.facts?.stopSettle)
if (step.kind === 'settlement') {
if (hasJournalDomainSettlement(db, target, step.settlementId)) {
return { outcome: { kind: 'committed', wrote: false } }
}
for (const item of commit.items) {
items.set(item.itemId, item)
const resolution = step.resolution
let mutations
if (resolution.kind === 'history-catch-up') {
const cursor = journalDomainContextHead(db, target)
if (
Atomics.load(resolution.permit, 0) !== 1 ||
Date.now() >= resolution.deadline ||
cursor.epoch !== resolution.expectedCursor.epoch ||
cursor.sequence !== resolution.expectedCursor.sequence
) {
return { outcome: { kind: 'dropped' } }
}
const bytes =
Buffer.byteLength(
JSON.stringify({
settlementId: step.settlementId,
mutations: resolution.mutations,
...(resolution.expectedItems.length ? { expectedItems: resolution.expectedItems } : {})
}),
'utf8'
) + 512
if (bytes > step.reservedBytes) {
throw new Error('structured agent-session transition step exceeded its reserved size')
}
const verified = new Set<string>()
for (const expected of resolution.expectedItems) {
const current = view.item(expected.key)
const canonical = canonicalItemId(db, target, expected.key)
if (
verified.has(expected.key) ||
canonical !== expected.canonicalItemId ||
current?.revision !== expected.revision
) {
return { outcome: { kind: 'dropped' } }
}
verified.add(expected.key)
}
const seen = new Set<string>()
for (const mutation of resolution.mutations) {
const key = agentJournalItemKey(mutation.identity)
const canonical = canonicalItemId(db, target, key)
if (seen.has(canonical) || (!verified.has(key) && view.item(canonical))) {
return { outcome: { kind: 'dropped' } }
}
seen.add(canonical)
}
mutations = resolution.mutations
} else {
mutations = resolveProviderTimelineSettlement(view, resolution)
const seen = new Set<string>()
for (const mutation of mutations) {
const canonical = canonicalItemId(db, target, journalLifecycleMutationItemId(mutation))
if (seen.has(canonical)) {
throw new Error('journal_resolved_lifecycle_batch_names_item_twice')
}
seen.add(canonical)
}
}
const commit = applyJournalDomainLifecycle(
db,
target,
{
settlementId: step.settlementId,
fence: step.fence,
ownerFence: step.ownerFence,
recovered: step.recovered,
mutations
},
savedAt,
command.facts?.stopSettle
)
return { commit, outcome: { kind: 'committed', wrote: commit.coordinates.length > 0 } }
}
let identity
let body
let options = step.options
let stopped: true | undefined
if (step.kind === 'creation-fact') {
const key = agentJournalItemKey(step.identity)
if (
step.epoch !== target.epoch ||
view.item(key) ||
db
.prepare(
`SELECT 1 FROM journal_item_tombstones WHERE session_id=? AND epoch=? AND item_id=?`
)
.get(target.sessionId, target.epoch, key)
) {
return { outcome: { kind: 'dropped' } }
}
for (const [key, present] of commit.inputKeys) {
if (!inputKeys.has(key)) {
inputKeys.set(key, present)
}
identity = step.identity
body = step.body
} else if (step.kind === 'resolved-item') {
const resolved = resolveJournalTimelineItem(
view,
step.resolution,
step.options.turnScope,
step.reservedBytes
)
if (resolved.kind === 'dropped') {
return { outcome: resolved }
}
identity = resolved.item.identity
body = resolved.item.body
options = { ...options, turnScope: resolved.item.turnScope ?? options.turnScope }
stopped = resolved.stopped
} else {
identity = step.identity
body = step.body
}
if (Buffer.byteLength(JSON.stringify({ identity, body }), 'utf8') + 512 > step.reservedBytes) {
throw new Error('structured agent-session transition step exceeded its reserved size')
}
const withdrewCut = commits.findLast((commit) => commit.withdrewCut)?.withdrewCut
return {
...final,
keys: [...keys.values()],
items: [...items.values()],
inputKeys: [...inputKeys],
inputChanged: commits.some((commit) => commit.inputChanged),
effects: [],
value: result,
...(withdrewCut ? { withdrewCut } : {}),
...(command.facts?.goals ? { goals } : {})
const written = applyJournalDomainItem(
db,
target,
{ kind: 'item', identity, body, options },
savedAt,
command.facts?.stopSettle
)
const snapshot = step.kind === 'resolved-item' && step.resolution.kind === 'text-snapshot'
const commit: JournalDomainLifecycleCommit = {
...written,
...(snapshot ? { invalidatedItemIds: [] } : {}),
removedItemIds: [],
coordinates:
written.outcome.kind === 'committed' && written.outcome.wrote
? [{ kind: 'item', epoch: target.epoch, seq: written.cursor.sequence }]
: []
}
return { commit, outcome: { ...written.outcome, ...(stopped ? { stopped } : {}) } }
}
function canonicalItemId(
db: Database.Database,
target: { sessionId: string; epoch: string },
key: string
): string {
const alias = db
.prepare(
`SELECT item_id FROM journal_item_aliases WHERE session_id=? AND epoch=? AND provider_item_id=?`
)
.get(target.sessionId, target.epoch, key)
return alias ? String(alias.item_id) : key
}
export function journalSqlTextSteps(
steps: Extract<JournalWriterCommand['operation'], { kind: 'steps' }>['steps']
): JournalSqlMessage[] | null {
if (steps.length === 0) {
return null
}
const messages: JournalSqlMessage[] = []
for (const step of steps) {
if (step.kind !== 'resolved-item' || step.resolution.kind !== 'text-snapshot') {
return null
}
messages.push({ ...step.resolution, options: step.options })
}
return messages
}