refactor: add named chat context and item removal transactions

Context clear, rewind and epoch replacement now run as named writer
transactions over the current chat rows. Removal deletes the current item
and keeps a higher tombstone, removed-turn membership and every independent
original (attempts, receipts, aliases, queue rows) in the same transaction,
refreshing Stop notes, queue failure holds, turn scope and the failure
boundary. Epoch replacement starts a new context in the same physical epoch.
Production still uses the existing journal path.
This commit is contained in:
Brennan Benson
2026-11-08 10:01:45 -08:00
parent 4f0ad9d46d
commit 38b5c59c2c
6 changed files with 1000 additions and 0 deletions
@@ -0,0 +1,195 @@
import { afterEach, expect, it } from 'vitest'
import type { AgentJournalItemBody } from '../../../shared/agent-session/journal/agent-session-journal-types'
import { runJournalTransaction } from './database/journal-database'
import { applyJournalDomainItem } from './journal-domain-item'
import { applyJournalDomainTombstone } from './journal-domain-item-removal'
import {
applyJournalDomainContextCommand,
type JournalDomainContextOperation
} from './journal-domain-context-command'
import { readJournalDomainQueueFailure } from './journal-domain-queue-failures'
import { messageFixture, target } from './journal-sql-message.test-fixture'
const close: (() => void)[] = []
afterEach(() => close.splice(0).forEach((fn) => fn()))
const say = (text: string): AgentJournalItemBody => ({
kind: 'message',
role: 'assistant',
blocks: [{ type: 'text', text }]
})
function fixture() {
const value = messageFixture()
close.push(() => value.db.close())
const { db } = value
const write = (clientMessageId: string, body: AgentJournalItemBody, turnItemId?: string) =>
runJournalTransaction(db, () =>
applyJournalDomainItem(
db,
target,
{
kind: 'item',
identity: { provider: 'orca', clientMessageId },
body,
options: {
fence: 1,
turnScope: turnItemId ? { kind: 'turn', turnItemId } : { kind: 'thread' }
}
},
100
)
)
const context = (operation: JournalDomainContextOperation) =>
runJournalTransaction(db, () => applyJournalDomainContextCommand(db, target, operation, 200))
const remove = (clientMessageId: string) =>
runJournalTransaction(db, () =>
applyJournalDomainTombstone(
db,
target,
{ kind: 'tombstone', identity: { provider: 'orca', clientMessageId }, fence: 1 },
300
)
)
const clear = () =>
context({
kind: 'context-clear',
boundary: { operationId: 'clear-1', afterFence: 1, clearedAt: 150 }
})
const ids = () =>
db
.prepare('SELECT item_id FROM journal_items ORDER BY sequence, sequence_index, ordinal')
.all()
.map((row) => String(row.item_id))
const one = (sql: string, ...args: string[]) => db.prepare(sql).get(...args)
return { ...value, write, context, remove, clear, ids, one }
}
it('rewinds the suffix after its floor, keeping removed-turn membership and resurrecting replayed items', () => {
const { db, write, context, clear, ids, one } = fixture()
write('kept', say('before the clear'))
const cleared = clear()
write('turn-1', { kind: 'turn', turnId: 'turn-1', state: 'completed' })
write('answer', say('stale answer'), 'orca:turn-1')
const floor = { epoch: cleared.cursor.epoch, sequence: cleared.cursor.sequence }
const rewound = context({
kind: 'context-rewind',
floor,
fence: 1,
items: [
{
identity: { provider: 'orca', clientMessageId: 'answer' },
body: say('replayed answer'),
ownerFence: 1
}
]
})
expect(rewound.removedItemIds).toEqual(['orca:turn-1', 'orca:answer'])
expect(rewound.removedTurnIds).toEqual(['turn-1'])
expect(ids()).toEqual(['orca:kept', 'orca:context-clear%3Aclear-1', 'orca:answer'])
// The replay outranks its own tombstone and is current and visible again.
expect(one('SELECT revision, hidden FROM journal_items WHERE item_id=?', 'orca:answer')).toEqual({
revision: 3,
hidden: 0
})
expect(
one('SELECT COUNT(*) AS n FROM journal_item_tombstones WHERE item_id=?', 'orca:answer')
).toEqual({ n: 0 })
expect(
one('SELECT revision FROM journal_item_tombstones WHERE item_id=?', 'orca:turn-1')
).toEqual({ revision: 2 })
expect(rewound.cursor).toEqual({ epoch: floor.epoch, sequence: rewound.physicalCursor.sequence })
expect(rewound.clear).toMatchObject({ operationId: 'clear-1', lifted: true })
// Removed-turn membership is independent of the item: reinserting the turn keeps it.
write('turn-1', { kind: 'turn', turnId: 'turn-1', state: 'running' })
expect(one('SELECT revision FROM journal_items WHERE item_id=?', 'orca:turn-1')).toEqual({
revision: 3
})
expect(db.prepare('SELECT turn_id FROM journal_removed_turns').all()).toEqual([
{ turn_id: 'turn-1' }
])
// Replaying an item at or before the floor refuses before any write.
expect(() =>
context({
kind: 'context-rewind',
floor,
fence: 1,
items: [
{
identity: { provider: 'orca', clientMessageId: 'kept' },
body: say('x'),
ownerFence: 1
}
]
})
).toThrow('agent_session_rewind:proof-mismatch')
})
it('lifts and restores a command turn failure hold as its report is removed and reinserted', () => {
const { write, remove, db } = fixture()
write('command-turn:send-1', {
kind: 'turn',
turnId: 'compact:send-1',
state: 'completed',
outcome: 'failure'
})
const report = { kind: 'status', text: 'Agent failed.', tone: 'error' } as const
write('report', report, 'orca:command-turn%3Asend-1')
const held = readJournalDomainQueueFailure(db, target)
expect(held).toBeGreaterThan(0)
const removed = remove('report')
expect(removed.removedItemIds).toEqual(['orca:report'])
expect(readJournalDomainQueueFailure(db, target)).toBe(0)
write('report', report, 'orca:command-turn%3Asend-1')
expect(readJournalDomainQueueFailure(db, target)).toBeGreaterThan(0)
})
it('rolls back an epoch replacement completely when one replacement write fails', () => {
const { db, write, context, ids, one } = fixture()
write('old', say('old history'))
const before = {
head: one(
'SELECT last_sequence, context_boundary, derived_turn_item_id FROM journal_chat_state'
),
events: db.prepare('SELECT sequence FROM journal_events ORDER BY sequence').all(),
tombstones: db.prepare('SELECT * FROM journal_item_tombstones').all()
}
db.exec(`CREATE TRIGGER reject_replacement BEFORE INSERT ON journal_items
WHEN NEW.item_id='orca:bad' BEGIN SELECT RAISE(ABORT, 'replacement failed'); END`)
const replace = (clientMessageIds: string[]) =>
context({
kind: 'epoch-replace',
reason: 'legacy_import',
fence: 1,
items: clientMessageIds.map((clientMessageId) => ({
identity: { provider: 'orca', clientMessageId },
body: say(clientMessageId),
ownerFence: 1
}))
})
expect(() => replace(['good', 'bad'])).toThrow('replacement failed')
expect(ids()).toEqual(['orca:old'])
expect(
one('SELECT last_sequence, context_boundary, derived_turn_item_id FROM journal_chat_state')
).toEqual(before.head)
expect(db.prepare('SELECT sequence FROM journal_events ORDER BY sequence').all()).toEqual(
before.events
)
expect(db.prepare('SELECT * FROM journal_item_tombstones').all()).toEqual(before.tombstones)
const replaced = replace(['good'])
expect(ids()).toEqual(['orca:good'])
expect(replaced.contextBoundary).toBe(replaced.physicalCursor.sequence - 1)
expect(replaced.cursor.epoch).not.toBe(target.epoch)
expect(one('SELECT epoch, context_boundary FROM journal_chat_state')).toEqual({
epoch: target.epoch,
context_boundary: replaced.contextBoundary
})
})
@@ -0,0 +1,133 @@
import type Database from '../../sqlite/sync-database'
import type { AgentSessionProviderContextBoundary } from '../../../shared/agent-session/agent-session-provider-context'
import { applyJournalDomainItem } from './journal-domain-item'
import {
SELECT_JOURNAL_DOMAIN_QUEUE_ROW,
readJournalDomainQueueRow,
replaceJournalDomainQueueRow
} from './journal-domain-queue-rows'
import {
journalDomainEditLeaseDeadline,
retireJournalDomainEditHolds
} from './journal-domain-edit-leases'
import { appendJournalSqlEvent } from './journal-sql-event-tail'
import {
journalDomainPublicCursor,
replaceJournalDomainContext,
type JournalDomainContextCommit,
type JournalDomainContextReplacement
} from './journal-domain-context-replacement'
import { writeJournalDomainQueueClear } from './journal-domain-queue-clear'
type Target = { sessionId: string; epoch: string }
export type JournalDomainContextOperation =
| { kind: 'context-clear'; boundary: AgentSessionProviderContextBoundary }
| JournalDomainContextReplacement
/** Runs only on the owning writer connection, inside its command SAVEPOINT. */
export function applyJournalDomainContextCommand(
db: Database.Database,
target: Target,
operation: JournalDomainContextOperation,
savedAt: number
): JournalDomainContextCommit {
if (!db.isTransaction) {
throw new Error('journal context command requires its writer transaction')
}
return operation.kind === 'context-clear'
? clearJournalDomainContext(db, target, operation.boundary, savedAt)
: replaceJournalDomainContext(db, target, operation, savedAt)
}
function clearJournalDomainContext(
db: Database.Database,
target: Target,
boundary: AgentSessionProviderContextBoundary,
savedAt: number
): JournalDomainContextCommit {
const fence = boundary.afterFence
const divider = applyJournalDomainItem(
db,
target,
{
kind: 'item',
identity: { provider: 'orca', clientMessageId: `context-clear:${boundary.operationId}` },
body: {
kind: 'status',
text: 'Context cleared',
presentation: 'context-cleared',
contextClear: boundary
},
options: { fence, turnScope: { kind: 'thread' } }
},
savedAt
)
const sequence = divider.cursor.sequence + 1
const unsettled = db
.prepare(`${SELECT_JOURNAL_DOMAIN_QUEUE_ROW} WHERE session_id=? AND epoch=?
AND state IN ('waiting','returned') ORDER BY position, message_id`)
.all(target.sessionId, target.epoch)
.map((row) => readJournalDomainQueueRow(target.sessionId, row))
// Commands belong to the ended context and must move with its divider.
const withdrawn = unsettled.flatMap((prior) => {
if (!prior.card.body.command) {
return []
}
const card = { ...prior.card, state: 'withdrawn' as const, holdReason: null }
replaceJournalDomainQueueRow(db, target, prior, card)
return [card]
})
const clear = writeJournalDomainQueueClear(db, target, sequence, {
operationId: boundary.operationId,
messageIds: unsettled
.filter(({ card }) => card.state === 'waiting' && !card.body.command)
.map(({ card }) => card.messageId)
})
const commit: JournalDomainContextCommit = {
cursor: { epoch: '', sequence },
physicalCursor: { epoch: target.epoch, sequence },
contextBoundary: null,
coordinates: [
{ kind: 'context-item', cursor: divider.cursor, fence, observedAt: savedAt },
{
kind: 'queue-clear',
cursor: { epoch: target.epoch, sequence },
fence,
observedAt: savedAt
}
],
items: divider.items,
removedItemIds: [],
removedTurnIds: [],
cards: [...divider.cards, ...withdrawn],
clear,
receipts: divider.receipts,
inputChanged: true,
...(divider.acceptedInputs ? { acceptedInputs: divider.acceptedInputs } : {}),
...(divider.editDeadline !== undefined ? { editDeadline: divider.editDeadline } : {})
}
if (
retireJournalDomainEditHolds(
db,
target,
withdrawn.map((card) => card.messageId)
)
) {
commit.editDeadline = journalDomainEditLeaseDeadline(db, target, savedAt)
}
appendJournalSqlEvent(
db,
target,
sequence,
savedAt,
{
items: [],
submissions: [],
cards: [...new Set([...withdrawn.map((card) => card.messageId), ...clear.messageIds])]
},
{ fence, observedAt: savedAt }
)
commit.cursor = journalDomainPublicCursor(db, target, sequence)
return commit
}
@@ -0,0 +1,307 @@
import type Database from '../../sqlite/sync-database'
import type { AgentJournalCursor } from '../../../shared/agent-session/journal/agent-session-journal-identity'
import {
agentJournalItemKey,
parseAgentJournalItemKey
} from '../../../shared/agent-session/journal/agent-session-journal-item-key'
import {
agentJournalLinkageFields,
isRootAgentJournalItem
} from '../../../shared/agent-session/journal/agent-session-journal-producer'
import type {
AgentJournalAcceptanceReceipt,
AgentJournalRenderItem
} from '../../../shared/agent-session/journal/agent-session-journal-types'
import { isQueuedAgentJournalSubmission } from '../../../shared/agent-session/requests/agent-session-queued-submission'
import type { AgentJournalEpochReason } from './durable-rows/journal-row-schema'
import { journalContextEpoch } from './context-epochs/journal-context-cursor'
import type { JournalReplacementItem } from './context-epochs/journal-epoch-replacement'
import { writeJournalDomainCurrentItem } from './journal-domain-current-item'
import { journalDomainEventItem, removeJournalDomainItem } from './journal-domain-item-removal'
import type { JournalSqlAcceptedInputs } from './journal-sql-accepted-inputs'
import { appendJournalSqlEvent } from './journal-sql-event-tail'
import { JournalDerivedTurnScope } from './projection/journal-derived-turn-scope'
import { journalItemRevisionValue } from './projection/journal-item-fold'
import type { QueuedMessageRow } from './queued-messages/queued-message-table'
import { assertJournalFence } from './writing/journal-write-guards'
import {
queueClearRestatement,
writeJournalDomainQueueClear,
type JournalDomainQueueClear
} from './journal-domain-queue-clear'
import { restoreRetainedFailures, retainedFailures } from './journal-domain-retained-failures'
type Target = { sessionId: string; epoch: string }
export type JournalDomainContextReplacement =
| {
kind: 'context-rewind'
floor: AgentJournalCursor
fence: number
items: readonly JournalReplacementItem[]
}
| {
kind: 'epoch-replace'
reason: AgentJournalEpochReason
fence: number
items: readonly JournalReplacementItem[]
}
export type JournalDomainContextCoordinate = {
kind: 'context-item' | 'context-removal' | 'replacement-item' | 'queue-clear'
cursor: AgentJournalCursor
fence: number
observedAt: number
}
export type JournalDomainContextCommit = {
/** Public context identity at the last position, as the conversation receipt binds it. */
cursor: AgentJournalCursor
physicalCursor: AgentJournalCursor
/** Set only when this command started a new context in the same physical epoch. */
contextBoundary: number | null
coordinates: JournalDomainContextCoordinate[]
items: AgentJournalRenderItem[]
removedItemIds: string[]
/** Turns this command removed; membership persists independently of their items. */
removedTurnIds: string[]
cards: QueuedMessageRow[]
clear: JournalDomainQueueClear | null
receipts: AgentJournalAcceptanceReceipt[]
inputChanged: boolean
acceptedInputs?: JournalSqlAcceptedInputs
editDeadline?: number | null
}
export function readJournalDomainContextHead(db: Database.Database, target: Target) {
const head = db
.prepare(`SELECT last_sequence, highest_fence, context_boundary, queue_clear_operation_id,
queue_failure_boundary FROM journal_chat_state WHERE session_id=? AND epoch=?`)
.get(target.sessionId, target.epoch)
if (!head) {
throw new Error('journal context command targets a retired chat epoch')
}
return {
lastSequence: Number(head.last_sequence),
highestFence: Number(head.highest_fence),
contextBoundary: Number(head.context_boundary),
cleared: head.queue_clear_operation_id !== null,
failureBoundary: Number(head.queue_failure_boundary)
}
}
export function replaceJournalDomainContext(
db: Database.Database,
target: Target,
operation: JournalDomainContextReplacement,
savedAt: number
): JournalDomainContextCommit {
const prefix = [target.sessionId, target.epoch] as const
const head = readJournalDomainContextHead(db, target)
const floor = operation.kind === 'context-rewind' ? operation.floor : null
if (
floor &&
(journalContextEpoch(target.epoch, head.contextBoundary) !== floor.epoch || !head.cleared)
) {
throw new Error('agent_session_rewind:stale-context')
}
assertJournalFence(operation.fence, head.highestFence)
const { fence } = operation
const itemIds = operation.items.map((item) => agentJournalItemKey(item.identity))
const current = db.prepare(`SELECT payload_json, ordinal, hidden, sequence, owner_fence,
execution_owner FROM journal_items WHERE session_id=? AND epoch=? AND item_id=?`)
for (const itemId of itemIds) {
const existing = current.get(...prefix, itemId)
if (floor && existing && Number(existing.sequence) <= floor.sequence) {
throw new Error('agent_session_rewind:proof-mismatch')
}
}
const restatement = head.cleared ? queueClearRestatement(db, target) : null
const retained = retainedFailures(db, target, itemIds, head.failureBoundary)
const removalSequence = head.lastSequence + 1
const coordinate = (
kind: JournalDomainContextCoordinate['kind'],
at: number
): JournalDomainContextCoordinate => ({
kind,
cursor: { epoch: target.epoch, sequence: at },
fence,
observedAt: savedAt
})
const commit: JournalDomainContextCommit = {
cursor: { epoch: '', sequence: removalSequence },
physicalCursor: { epoch: target.epoch, sequence: removalSequence },
contextBoundary: null,
coordinates: [coordinate('context-removal', removalSequence)],
items: [],
removedItemIds: [],
removedTurnIds: [],
cards: [],
clear: null,
receipts: [],
inputChanged: true
}
const revisions = new Map<string, number>()
const after = db
.prepare(`SELECT item_id FROM journal_items WHERE session_id=? AND epoch=? AND sequence>?
ORDER BY sequence, sequence_index, ordinal`)
.all(...prefix, floor?.sequence ?? 0)
.map((row) => String(row.item_id))
for (const itemId of after) {
if (queuedJournalDomainSubmission(db, target, itemId)) {
continue
}
const removal = removeJournalDomainItem(db, target, itemId, removalSequence, revisions)
commit.removedItemIds.push(removal.itemId)
commit.items.push(...removal.items)
const turnId = removal.removed?.body.kind === 'turn' ? removal.removed.body.turnId : undefined
if (turnId !== undefined) {
commit.removedTurnIds.push(turnId)
}
}
if (operation.kind === 'epoch-replace') {
// A new context in the same physical epoch: its public identity changes, its rows do not move.
db.prepare(`UPDATE journal_chat_state SET context_boundary=?, derived_turn_item_id=NULL
WHERE session_id=? AND epoch=?`).run(removalSequence, ...prefix)
commit.contextBoundary = removalSequence
}
appendJournalSqlEvent(
db,
target,
removalSequence,
savedAt,
{
items: commit.items.map(journalDomainEventItem),
submissions: [],
cards: [],
...(commit.removedItemIds.length ? { removedItemIds: commit.removedItemIds } : {})
},
{ fence, observedAt: savedAt }
)
// Replacement history derives absent scopes from its own order, not the removed suffix.
const scope = new JournalDerivedTurnScope()
let sequence = removalSequence
const alias = db.prepare(`SELECT echo_declared FROM journal_item_aliases
WHERE session_id=? AND epoch=? AND provider_item_id=?`)
for (const [index, item] of operation.items.entries()) {
sequence += 1
const itemId = itemIds[index]!
const stored = current.get(...prefix, itemId)
const previous: AgentJournalRenderItem | undefined = stored
? JSON.parse(String(stored.payload_json))
: undefined
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(
revisions.get(itemId) ?? 0,
Number(tombstone?.revision ?? 0),
previous?.revision ?? 0
) + 1
revisions.set(itemId, revision)
const turnScope = item.turnScope ?? scope.scopeFor(item.body)
scope.observe(itemId, isRootAgentJournalItem(item), undefined, item.body)
const rendered: AgentJournalRenderItem = {
itemId,
revision,
body: item.body,
sequence,
observedAt: item.observedAt ?? savedAt,
turnScope,
...agentJournalLinkageFields(item)
}
const written = writeJournalDomainCurrentItem(db, target, {
item: previous ? journalItemRevisionValue(previous, rendered) : rendered,
...(previous
? {
previous: {
item: previous,
ordinal: Number(stored!.ordinal),
hidden: Boolean(stored!.hidden)
}
}
: {}),
ordinal: stored ? Number(stored.ordinal) : sequence,
hidden: Boolean(stored?.hidden),
writtenSequence: sequence,
ownerFence: item.ownerFence,
executionOwner: item.executionOwner ?? null
})
if (tombstone) {
db.prepare(
'DELETE FROM journal_item_tombstones WHERE session_id=? AND epoch=? AND item_id=?'
).run(...prefix, itemId)
}
if (Object.hasOwn(item, 'echoOf') && !alias.get(...prefix, itemId)?.echo_declared) {
db.prepare(`INSERT INTO journal_item_aliases(session_id,epoch,provider_item_id,item_id,echo_declared,echo_json)
VALUES(?,?,?,?,1,?) ON CONFLICT(session_id,epoch,provider_item_id)
DO UPDATE SET echo_declared=1, echo_json=excluded.echo_json`).run(
...prefix,
itemId,
itemId,
JSON.stringify(item.echoOf ?? null)
)
}
commit.items.push(...written)
commit.coordinates.push(coordinate('replacement-item', sequence))
appendJournalSqlEvent(
db,
target,
sequence,
savedAt,
{ items: written.map(journalDomainEventItem), submissions: [], cards: [] },
{ fence, observedAt: savedAt }
)
}
restoreRetainedFailures(db, target, retained)
if (restatement) {
sequence += 1
commit.clear = writeJournalDomainQueueClear(db, target, sequence, restatement)
commit.coordinates.push(coordinate('queue-clear', sequence))
appendJournalSqlEvent(
db,
target,
sequence,
savedAt,
{ items: [], submissions: [], cards: commit.clear.messageIds },
{ fence, observedAt: savedAt }
)
}
commit.physicalCursor = { epoch: target.epoch, sequence }
commit.cursor = journalDomainPublicCursor(db, target, sequence)
return commit
}
export function journalDomainPublicCursor(
db: Database.Database,
target: Target,
sequence: number
): AgentJournalCursor {
return {
epoch: journalContextEpoch(
target.epoch,
readJournalDomainContextHead(db, target).contextBoundary
),
sequence
}
}
/** Queued sends survive the rewind; their own handover still owns their placement. */
function queuedJournalDomainSubmission(
db: Database.Database,
target: Target,
itemId: string
): boolean {
const identity = parseAgentJournalItemKey(itemId)
if (identity?.provider !== 'orca') {
return false
}
const row = db
.prepare(`SELECT payload_json FROM journal_submission_attempts
WHERE session_id=? AND epoch=? AND message_id=? AND current=1`)
.get(target.sessionId, target.epoch, identity.clientMessageId)
return row !== undefined && isQueuedAgentJournalSubmission(JSON.parse(String(row.payload_json)))
}
@@ -0,0 +1,208 @@
import type Database from '../../sqlite/sync-database'
import type { AgentJournalItemIdentity } from '../../../shared/agent-session/journal/agent-session-journal-identity'
import { agentJournalItemKey } from '../../../shared/agent-session/journal/agent-session-journal-item-key'
import type { AgentJournalRenderItem } from '../../../shared/agent-session/journal/agent-session-journal-types'
import { readAgentJournalTurn } from '../../../shared/agent-session/lifecycle/agent-session-turn-record'
import { refreshJournalDomainStopNotes } from './journal-domain-stop-notes'
import { refreshJournalDomainQueueFailureReports } from './journal-domain-queue-failures'
import { observeJournalDomainTurnScope } from './journal-domain-turn-scope'
import { appendJournalSqlEvent } from './journal-sql-event-tail'
import { assertJournalFence } from './writing/journal-write-guards'
type Target = { sessionId: string; epoch: string }
export type JournalDomainItemRemoval = {
itemId: string
revision: number
/** The removed current body, when the item was current; its originals stay on their own rows. */
removed: AgentJournalRenderItem | null
/** Dependent Stop notes whose display this removal restored. */
items: AgentJournalRenderItem[]
}
/** Deletes the current row, keeps a higher tombstone revision and every independent original:
* attempts, receipts, aliases, queue rows and removed-turn membership. */
export function removeJournalDomainItem(
db: Database.Database,
target: Target,
key: string,
sequence: number,
revisions?: Map<string, number>
): JournalDomainItemRemoval {
if (!db.isTransaction) {
throw new Error('journal item removal requires its writer transaction')
}
const prefix = [target.sessionId, target.epoch] as const
const alias = db
.prepare(`SELECT item_id FROM journal_item_aliases
WHERE session_id=? AND epoch=? AND provider_item_id=?`)
.get(...prefix, key)
const itemId = alias ? String(alias.item_id) : key
const row = db
.prepare(`SELECT payload_json, revision, sequence, sequence_index, turn_marker,
queue_failure_report_turn_item_id FROM journal_items WHERE session_id=? AND epoch=? AND item_id=?`)
.get(...prefix, itemId)
const tombstone = db
.prepare(
'SELECT revision FROM journal_item_tombstones WHERE session_id=? AND epoch=? AND item_id=?'
)
.get(...prefix, itemId)
const revision =
(revisions?.get(itemId) ??
Math.max(Number(row?.revision ?? 0), Number(tombstone?.revision ?? 0))) + 1
revisions?.set(itemId, revision)
db.prepare(`INSERT INTO journal_item_tombstones(session_id,epoch,item_id,revision) VALUES(?,?,?,?)
ON CONFLICT(session_id,epoch,item_id) DO UPDATE SET revision=excluded.revision`).run(
...prefix,
itemId,
revision
)
if (!row) {
return { itemId, revision, removed: null, items: [] }
}
const removed: AgentJournalRenderItem = JSON.parse(String(row.payload_json))
if (row.turn_marker) {
exposeJournalDomainFailureBoundary(
db,
target,
{ sequence: Number(row.sequence), sequenceIndex: Number(row.sequence_index) },
itemId,
sequence
)
}
db.prepare('DELETE FROM journal_items WHERE session_id=? AND epoch=? AND item_id=?').run(
...prefix,
itemId
)
db.prepare(
'DELETE FROM journal_item_subagent_names WHERE session_id=? AND epoch=? AND item_id=?'
).run(...prefix, itemId)
observeJournalDomainTurnScope(db, target, itemId, removed, undefined)
const turn = readAgentJournalTurn(removed.body)
if (turn) {
db.prepare(`INSERT OR IGNORE INTO journal_removed_turns(session_id,epoch,turn_id)
VALUES(?,?,?)`).run(...prefix, turn.turnId)
}
// A delete bypasses the shared item write, so it refreshes the reported command turn itself.
if (row.queue_failure_report_turn_item_id !== null) {
refreshJournalDomainQueueFailureReports(
db,
target,
[String(row.queue_failure_report_turn_item_id)],
sequence
)
}
return {
itemId,
revision,
removed,
items: turn ? refreshJournalDomainStopNotes(db, target, [itemId]) : []
}
}
/** Removing a turn or clear at or after the newest ordinary one exposes the failure beneath it. */
function exposeJournalDomainFailureBoundary(
db: Database.Database,
target: Target,
row: { sequence: number; sequenceIndex: number },
itemId: string,
sequence: number
): void {
const anchor = db
.prepare(`SELECT sequence, sequence_index, item_id FROM journal_items INDEXED BY journal_items_turn_marker
WHERE session_id=? AND epoch=? AND hidden=0 AND turn_marker=1 AND queue_command_turn=0
ORDER BY sequence DESC, sequence_index DESC, item_id DESC LIMIT 1`)
.get(target.sessionId, target.epoch)
const order = anchor
? row.sequence - Number(anchor.sequence) ||
row.sequenceIndex - Number(anchor.sequence_index) ||
itemId.localeCompare(String(anchor.item_id))
: 0
if (order >= 0) {
db.prepare(`UPDATE journal_chat_state SET queue_failure_boundary=?
WHERE session_id=? AND epoch=?`).run(sequence, target.sessionId, target.epoch)
}
}
export type JournalDomainTombstoneOperation =
| { kind: 'tombstone'; identity: AgentJournalItemIdentity; fence: number }
| {
kind: 'goal-withdraw'
identity: AgentJournalItemIdentity
fence: number
/** Claims the host's live goal proof says no other goal still holds, read just before. */
releasedUploads: readonly string[]
}
export type JournalDomainTombstoneCommit = {
cursor: { epoch: string; sequence: number }
fence: number
observedAt: number
items: AgentJournalRenderItem[]
removedItemIds: string[]
releasedUploads: string[]
}
/** One named removal command and its one identity event; the caller owns the SAVEPOINT. */
export function applyJournalDomainTombstone(
db: Database.Database,
target: Target,
operation: JournalDomainTombstoneOperation,
savedAt: number
): JournalDomainTombstoneCommit {
if (!db.isTransaction) {
throw new Error('journal tombstone requires its writer transaction')
}
const head = db
.prepare(`SELECT last_sequence, highest_fence FROM journal_chat_state
WHERE session_id=? AND epoch=?`)
.get(target.sessionId, target.epoch)
if (!head) {
throw new Error('journal tombstone targets a retired chat epoch')
}
assertJournalFence(operation.fence, Number(head.highest_fence))
const sequence = Number(head.last_sequence) + 1
const removal = removeJournalDomainItem(
db,
target,
agentJournalItemKey(operation.identity),
sequence
)
const releasedUploads = operation.kind === 'goal-withdraw' ? [...operation.releasedUploads] : []
const release = db.prepare(
'DELETE FROM agent_session_attachment_claims WHERE upload_id=? AND session_id=?'
)
for (const uploadId of releasedUploads) {
release.run(uploadId, target.sessionId)
}
appendJournalSqlEvent(
db,
target,
sequence,
savedAt,
{
items: removal.items.map(journalDomainEventItem),
submissions: [],
cards: [],
removedItemIds: [removal.itemId]
},
{ fence: operation.fence, observedAt: savedAt }
)
return {
cursor: { epoch: target.epoch, sequence },
fence: operation.fence,
observedAt: savedAt,
items: removal.items,
removedItemIds: [removal.itemId],
releasedUploads
}
}
export function journalDomainEventItem(item: AgentJournalRenderItem) {
return {
itemId: item.itemId,
revision: item.revision,
sequence: item.sequence,
sequenceIndex: item.sequenceIndex ?? 0
}
}
@@ -0,0 +1,77 @@
import type Database from '../../sqlite/sync-database'
import { readJournalDomainQueuePauseContext } from './journal-domain-queue-pauses'
import { readJournalDomainQueueRow } from './journal-domain-queue-rows'
import {
deriveQueuePauses,
journalQueuePauseRestatement
} from './queued-messages/queued-message-pause'
type Target = { sessionId: string; epoch: string }
export type JournalDomainQueueClear = {
sequence: number
operationId: string
messageIds: string[]
lifted?: true
}
/** The clear restated over its still-held members; held members are a bounded queue subset. */
export function queueClearRestatement(
db: Database.Database,
target: Target
): Omit<JournalDomainQueueClear, 'sequence'> | null {
const members = db
.prepare(`SELECT card.message_id, card.revision, card.state, card.position, card.payload_json
FROM journal_queue_clear_members member JOIN journal_queue_cards card
ON card.session_id=member.session_id AND card.epoch=member.epoch AND card.message_id=member.message_id
WHERE member.session_id=? AND member.epoch=?`)
.all(target.sessionId, target.epoch)
.map((row) => readJournalDomainQueueRow(target.sessionId, row).card)
const context = readJournalDomainQueuePauseContext(
db,
target,
null,
members.map((card) => card.messageId)
)
const cleared = context.marks.cleared
if (!cleared) {
return null
}
const marks = {
...context.marks,
cleared: { ...cleared, messageIds: [...context.clearMembers] }
}
const { cleared: restated } = journalQueuePauseRestatement(
marks,
context.latestAcceptedTurnSequence,
deriveQueuePauses({ ...context, marks, cards: members }),
context.latestPersonAcceptedTurnSequence
)
return restated ?? null
}
export function writeJournalDomainQueueClear(
db: Database.Database,
target: Target,
sequence: number,
clear: Omit<JournalDomainQueueClear, 'sequence'>
): JournalDomainQueueClear {
const prefix = [target.sessionId, target.epoch] as const
db.prepare(`UPDATE journal_chat_state SET queue_clear_sequence=?, queue_clear_operation_id=?,
queue_clear_lifted=? WHERE session_id=? AND epoch=?`).run(
sequence,
clear.operationId,
Number(clear.lifted === true),
...prefix
)
db.prepare('DELETE FROM journal_queue_clear_members WHERE session_id=? AND epoch=?').run(
...prefix
)
const insert =
db.prepare(`INSERT OR IGNORE INTO journal_queue_clear_members(session_id,epoch,message_id)
VALUES(?,?,?)`)
for (const messageId of clear.messageIds) {
insert.run(...prefix, messageId)
}
return { ...clear, messageIds: [...clear.messageIds], sequence }
}
@@ -0,0 +1,80 @@
import type Database from '../../sqlite/sync-database'
import { isDeepStrictEqual } from 'node:util'
import { agentJournalLinkageFields } from '../../../shared/agent-session/journal/agent-session-journal-producer'
import type { AgentJournalRenderItem } from '../../../shared/agent-session/journal/agent-session-journal-types'
type Target = { sessionId: string; epoch: string }
export type RetainedFailure = {
itemId: string
item: AgentJournalRenderItem
at: number
reports: number
}
/** Only known, unchanged replacement turns carry failure chronology across the rewrite. */
export function retainedFailures(
db: Database.Database,
target: Target,
itemIds: readonly string[],
boundary: number
): RetainedFailure[] {
const prefix = [target.sessionId, target.epoch] as const
const failed = db.prepare(`SELECT payload_json, queue_failed_at, queue_failure_witnessed_through
FROM journal_items WHERE session_id=? AND epoch=? AND item_id=? AND queue_failed_at>0`)
return itemIds.flatMap((itemId) => {
const row = failed.get(...prefix, itemId)
if (!row) {
return []
}
const failedAt = Number(row.queue_failed_at)
return [
{
itemId,
item: JSON.parse(String(row.payload_json)),
at: Math.max(
failedAt,
boundary > Number(row.queue_failure_witnessed_through) ? boundary : 0
),
reports: reportCount(db, target, itemId)
}
]
})
}
export function restoreRetainedFailures(
db: Database.Database,
target: Target,
retained: readonly RetainedFailure[]
): void {
const prefix = [target.sessionId, target.epoch] as const
const kept = db.prepare(`SELECT payload_json FROM journal_items
WHERE session_id=? AND epoch=? AND item_id=? AND queue_failed_at>0`)
for (const { itemId, item, at, reports } of retained) {
const row = kept.get(...prefix, itemId)
const next: AgentJournalRenderItem | undefined = row
? JSON.parse(String(row.payload_json))
: undefined
if (
!next ||
!isDeepStrictEqual(item.body, next.body) ||
!isDeepStrictEqual(item.turnScope, next.turnScope) ||
!isDeepStrictEqual(agentJournalLinkageFields(item), agentJournalLinkageFields(next)) ||
reportCount(db, target, itemId) !== reports
) {
continue
}
db.prepare(`UPDATE journal_items SET queue_failed_at=?, queue_failure_witnessed_through=(
SELECT queue_failure_boundary FROM journal_chat_state WHERE session_id=? AND epoch=?)
WHERE session_id=? AND epoch=? AND item_id=?`).run(at, ...prefix, ...prefix, itemId)
}
}
function reportCount(db: Database.Database, target: Target, turnItemId: string): number {
return Number(
db
.prepare(`SELECT COUNT(*) AS n FROM journal_items WHERE session_id=? AND epoch=? AND hidden=0
AND queue_failure_report_turn_item_id=?`)
.get(target.sessionId, target.epoch, turnItemId)!.n
)
}