Route queued edit holds through the SQL writer

This commit is contained in:
Brennan Benson
2026-11-08 13:08:39 -08:00
parent 2cc0bb4d22
commit 7ee94d50f1
11 changed files with 205 additions and 54 deletions
@@ -203,10 +203,6 @@ export function applyJournalDomainQueueCommand(
inputChanged: changes.length > 0 || placements.length > 0,
...(referencedUploads?.length ? { referencedUploads } : {})
}
if (!commit.inputChanged) {
retireHolds(db, target, retire, commit, savedAt)
return commit
}
const sequence = cursor.sequence + 1
for (const { prior, card, holdOnly } of changes) {
if (!prior) {
@@ -221,6 +217,9 @@ export function applyJournalDomainQueueCommand(
placeJournalDomainQueueRow(db, target, messageId, position)
}
retireHolds(db, target, retire, commit, savedAt)
if (!commit.inputChanged) {
return commit
}
appendJournalSqlEvent(db, target, sequence, savedAt, {
items: [],
submissions: [],
@@ -238,6 +237,7 @@ function retireHolds(
now: number
): void {
if (retireJournalDomainEditHolds(db, target, messageIds)) {
commit.inputChanged = true
commit.editDeadline = journalDomainEditLeaseDeadline(db, target, now)
}
}
@@ -16,6 +16,7 @@ import { applyJournalDomainGenerationSettlement } from './journal-domain-generat
import { applyJournalDomainLifecycleOperation } from './journal-domain-taken-stop'
import { applyJournalDomainPromptMutation } from './journal-domain-prompt-mutation'
import { applyJournalSqlStepCommand } from './journal-sql-step-command'
import { applyJournalSqlEditLeaseCommand } from './journal-sql-edit-lease-command'
/** Every command decides against current rows at its position on the sole writer. */
export class JournalSqlCommand {
@@ -32,6 +33,13 @@ export class JournalSqlCommand {
command = { ...command, savedAt }
const { operation, target } = command
switch (operation.kind) {
case 'edit-lease':
return applyJournalSqlEditLeaseCommand(
this.db,
this.stateDirectory,
{ ...command, operation },
savedAt
)
case 'item':
case 'item-claiming':
return applyJournalSqlItemCommand(
@@ -0,0 +1,56 @@
import type Database from '../../sqlite/sync-database'
import { applyJournalDomainEditLease } from './journal-domain-edit-leases'
import type { JournalWriterCommand } from './journal-writer-command'
import type { JournalWriterCommit } from './journal-writer-changes'
import { appendJournalSqlEvent } from './journal-sql-event-tail'
import { finishJournalSqlCommand } from './journal-sql-command-result'
export function applyJournalSqlEditLeaseCommand(
db: Database.Database,
stateDirectory: string,
command: JournalWriterCommand & {
operation: Extract<JournalWriterCommand['operation'], { kind: 'edit-lease' }>
},
savedAt: number
): JournalWriterCommit {
if (command.effects?.length) {
throw new Error('edit holds carry no operation receipt')
}
const { target, operation } = command
const head = db
.prepare('SELECT last_sequence FROM journal_chat_state WHERE session_id=? AND epoch=?')
.get(target.sessionId, target.epoch)
if (!head) {
throw new Error('edit hold targets a retired chat epoch')
}
const outcome = applyJournalDomainEditLease(
db,
target,
target.ownerToken,
operation.operation,
savedAt
)
const sequence = Number(head.last_sequence) + (outcome.changed ? 1 : 0)
if (outcome.changed) {
appendJournalSqlEvent(db, target, sequence, savedAt, {
items: [],
submissions: [],
cards: []
})
}
return finishJournalSqlCommand(
db,
stateDirectory,
command,
{
cursor: { epoch: target.epoch, sequence },
items: [],
cards: [],
receipts: [],
inputChanged: outcome.changed,
editDeadline: outcome.nextDeadline
},
outcome,
[]
)
}
@@ -1,40 +1,68 @@
import {
QueuedMessageEditLeases,
type EditLeaseKey
} from './queued-messages/queued-message-edit-leases'
import type { QueuedMessageRow } from './queued-messages/queued-message-table'
import type { EditLeaseKey } from './queued-messages/queued-message-edit-leases'
import type {
JournalDomainEditLeaseOperation,
JournalDomainEditLeaseOutcome
} from './journal-domain-edit-leases'
/** The existing ephemeral owner; card reads stay on the SQL reader. */
/** The deadline wakes the chat lane; only committed SQL rows decide which editors hold a card. */
export class SqlQueuedMessageEditLeases {
private readonly owner = new QueuedMessageEditLeases()
private deadline: number | null = null
private timer: ReturnType<typeof setTimeout> | undefined
private wake: (() => void) | undefined
private disposed = false
constructor(private readonly get: (id: string) => Promise<QueuedMessageRow | null>) {}
constructor(
private readonly write: (
operation: JournalDomainEditLeaseOperation
) => Promise<JournalDomainEditLeaseOutcome>,
private readonly now: () => number
) {}
onDeadline = (wake: () => void): void => this.owner.onDeadline(wake)
version = (): number => this.owner.version()
snapshot = () => this.owner.snapshot()
release = (key: EditLeaseKey, messageId: string): void => this.owner.release(key, messageId)
retire = (messageId: string): void => this.owner.retire(messageId)
dispose = (): void => this.owner.dispose()
onDeadline(wake: () => void): void {
this.wake = wake
this.schedule()
}
adoptDeadline(deadline: number | null): void {
this.deadline = deadline
this.schedule()
}
async acquire(key: EditLeaseKey, input: { messageId: string; fingerprint: string }) {
return this.owner.acquire(key, input, await this.rows(input.messageId))
return (await this.write({ kind: 'acquire', ...key, ...input })).result!
}
async renew(key: EditLeaseKey, messageId: string) {
return this.owner.renew(key, messageId, await this.rows(messageId))
return (await this.write({ kind: 'renew', ...key, messageId })).result!
}
async heldIds(rows?: readonly QueuedMessageRow[]): Promise<ReadonlySet<string>> {
return this.owner.heldIds(rows ?? (await this.rows()))
async release(key: EditLeaseKey, messageId: string): Promise<void> {
await this.write({ kind: 'release', ...key, messageId })
}
private async rows(messageId?: string): Promise<QueuedMessageRow[]> {
const ids = new Set(this.owner.snapshot().map((lease) => lease.messageId))
if (messageId !== undefined) {
ids.add(messageId)
async expire(): Promise<void> {
await this.write({ kind: 'expire' })
}
dispose(): void {
this.disposed = true
clearTimeout(this.timer)
this.timer = undefined
}
private schedule(): void {
clearTimeout(this.timer)
this.timer = undefined
if (this.disposed || !this.wake || this.deadline === null) {
return
}
const rows = await Promise.all([...ids].map(this.get))
return rows.filter((row) => row !== null)
this.timer = setTimeout(
() => {
this.timer = undefined
this.wake?.()
},
Math.max(1, this.deadline - this.now())
)
this.timer.unref()
}
}
@@ -14,7 +14,10 @@ import type {
QueuedMessageRow
} from './queued-messages/queued-message-table'
import type { QueuedMessageUpdate } from './queued-messages/queued-message-update'
import type { QueuedMessageEditLease } from './queued-messages/queued-message-edit-leases'
import type {
JournalDomainEditLeaseOperation,
JournalDomainEditLeaseOutcome
} from './journal-domain-edit-leases'
import { journalDomainQueueRow } from './journal-domain-queue-rows'
import {
journalDomainQueueAwaitsReopen,
@@ -32,8 +35,6 @@ import { SqlQueuedMessageEditLeases } from './journal-sql-edit-leases'
/** Host-memory facts a queue read needs, sent as data like the writer's facts. */
export type JournalSqlQueueFacts = {
reopenFloor: AgentJournalCursor | null
/** Writer-session transport only; reads select persisted holds. */
editLeases?: readonly QueuedMessageEditLease[]
mail?: readonly (readonly [string, boolean])[]
}
@@ -42,7 +43,7 @@ export type JournalSqlQueueRead = { facts: JournalSqlQueueFacts } & (
| { kind: 'get'; messageId: string }
| { kind: 'revision' }
| { kind: 'cleared-through' }
| { kind: 'next-input-card'; automatic: boolean; steer: boolean }
| { kind: 'next-input-card'; automatic: boolean; steer: boolean; now: number }
| { kind: 'failure-holds' }
| { kind: 'pauses' }
| { kind: 'user-stop-in-force' }
@@ -101,7 +102,7 @@ export function readJournalSqlQueue(
kind: 'next-input-card',
card: nextJournalDomainQueueCard(db, target, {
reopenFloor: facts.reopenFloor,
now: Date.now(),
now: operation.now,
steer: operation.steer,
automatic: operation.automatic,
mailUnavailable: (card) => {
@@ -160,6 +161,7 @@ export type JournalSqlQueuePort = {
operation: Extract<JournalSqlQueueRead, { kind: K }>
) => Promise<JournalSqlQueueReadResult>
write: (operation: JournalSqlQueueWrite, receipt?: JournalOperationReceipt) => Promise<unknown>
edit: (operation: JournalDomainEditLeaseOperation) => Promise<JournalDomainEditLeaseOutcome>
}
export type JournalSqlQueueWrite =
@@ -191,17 +193,16 @@ export class SqlJournalQueuedMessages {
constructor(
private readonly port: JournalSqlQueuePort,
private readonly reopenFloor: () => AgentJournalCursor | null
private readonly reopenFloor: () => AgentJournalCursor | null,
private readonly now: () => number
) {
this.editLeases = new SqlQueuedMessageEditLeases((id) => this.get(id))
this.editLeases = new SqlQueuedMessageEditLeases(port.edit, now)
}
/** The host facts every queue read and write carries. */
facts(mail?: readonly (readonly [string, boolean])[]): JournalSqlQueueFacts {
const editLeases = this.editLeases.snapshot()
return {
reopenFloor: this.reopenFloor(),
...(editLeases.length ? { editLeases } : {}),
...(mail?.length ? { mail } : {})
}
}
@@ -240,6 +241,7 @@ export class SqlJournalQueuedMessages {
kind: 'next-input-card',
automatic: true,
steer,
now: this.now(),
facts: this.facts()
})
return result.kind === 'mail-needed' ? this.answerMail([result.card]) : []
@@ -252,6 +254,7 @@ export class SqlJournalQueuedMessages {
kind: 'next-input-card',
automatic,
steer,
now: this.now(),
facts: this.facts(mail)
})
if (result.kind === 'next-input-card') {
@@ -286,7 +289,6 @@ export class SqlJournalQueuedMessages {
kind: 'queue-update',
input
})) as AgentSessionQueuedMessageUpdateResult
this.editLeases.retire(input.messageId)
return result
}
@@ -57,15 +57,52 @@ async function open(root: string) {
return opened
}
async function fixture() {
async function fixture(now: () => number = () => 100) {
const root = await mkdtemp(join(tmpdir(), 'journal-sql-store-'))
roots.push(root)
const { journalDatabase: database, records } = await open(root)
expect(records.records.size).toBe(0)
const journal = await SqlAgentSessionJournal.open({ database, identity, now: () => 100 })
const journal = await SqlAgentSessionJournal.open({ database, identity, now })
return { root, database, journal }
}
it('holds automatic delivery for every editor until committed release, expiry or handle close', async () => {
let now = 100
const { database, journal } = await fixture(() => now)
const card = await journal.queuedMessages.insert({
messageId: 'draft',
body: { kind: 'message', role: 'user', blocks: [{ type: 'text', text: 'hello' }] }
})
const desktop = { callerKey: 'desktop', editId: 'editing' }
const phone = { callerKey: 'phone', editId: 'editing' }
await journal.queuedMessages.editLeases.acquire(desktop, {
messageId: 'draft',
fingerprint: card.fingerprint
})
now = 200
expect(
await journal.queuedMessages.editLeases.acquire(phone, {
messageId: 'draft',
fingerprint: card.fingerprint
})
).toMatchObject({ status: 'held', remainingMs: 120_000 })
await journal.queuedMessages.editLeases.release(desktop, 'draft')
expect(await journal.queuedMessages.nextInputCard()).toBeNull()
now = 120_200
await journal.queuedMessages.editLeases.expire()
expect(await journal.queuedMessages.nextInputCard()).toMatchObject({ messageId: 'draft' })
await journal.queuedMessages.editLeases.acquire(phone, {
messageId: 'draft',
fingerprint: card.fingerprint
})
await journal.close()
const reopened = await SqlAgentSessionJournal.open({ database, identity, now: () => now })
expect(await reopened.queuedMessages.editLeases.renew(phone, 'draft')).toEqual({
status: 'expired'
})
await reopened.close()
})
function receipt(adopt: (committed: boolean) => void, draft = 'retained'): JournalOperationReceipt {
return {
write: () => {
@@ -436,7 +473,7 @@ it('drops a revoked history invocation after worker dispatch and preserves dedup
})
})
const lock = new Database(journalDatabasePath(root))
let pending: Promise<unknown> | undefined
let pending: ReturnType<typeof journal.appendSteps> | undefined
lock.exec('BEGIN IMMEDIATE')
try {
pending = journal.appendSteps([step])
@@ -446,11 +483,11 @@ it('drops a revoked history invocation after worker dispatch and preserves dedup
lock.exec('ROLLBACK')
lock.close()
}
expect(await pending).toEqual({ outcomes: [{ kind: 'dropped' }] })
expect((await pending)?.outcomes).toEqual([{ kind: 'dropped' }])
expect(journal.physicalCursor()).toEqual(cursor)
expect(await journal.reads.item('orca:history')).toBeNull()
Atomics.store(permit, 0, 1)
expect(await journal.appendSteps([step])).toEqual({
expect(await journal.appendSteps([step])).toMatchObject({
outcomes: [{ kind: 'committed', wrote: true }]
})
expect(await journal.reads.item('orca:history')).toMatchObject({
@@ -458,7 +495,7 @@ it('drops a revoked history invocation after worker dispatch and preserves dedup
body: { text: 'Recovered outside turn' }
})
Atomics.store(permit, 0, 0)
expect(await journal.appendSteps([step])).toEqual({
expect(await journal.appendSteps([step])).toMatchObject({
outcomes: [{ kind: 'committed', wrote: false }]
})
expect((await journal.reads.item('orca:history'))?.revision).toBe(1)
@@ -517,7 +554,7 @@ it('resolves related-item placement after an earlier step settles its saved turn
reservedBytes: 4096
}
])
).toEqual({
).toMatchObject({
outcomes: [
{ kind: 'committed', wrote: true },
{ kind: 'dropped', reason: 'turn-settled', turnItemId: 'orca:turn' },
@@ -588,7 +625,7 @@ it('refuses stale running items on the writer while permitting completion of exi
reservedBytes: 4096
}
])
).toEqual({
).toMatchObject({
outcomes: [
{ kind: 'dropped', reason: 'item-settled' },
{ kind: 'dropped', reason: 'turn-settled', turnItemId: 'orca:turn' },
@@ -25,6 +25,7 @@ import { SqlJournalAppends } from './journal-sql-appends'
import type { JournalCurrentWorkAuthority } from './journal-observer-read'
import type { JournalWorkRead, JournalWorkAnswer } from './journal-work-read'
import type { JournalDomainHistoryRequest } from './journal-domain-history-page'
import type { JournalDomainEditLeaseOutcome } from './journal-domain-edit-leases'
/** Every writer command a live handle sends; the open command belongs to the database. */
export type JournalSqlStoreOperation = Exclude<JournalWriterOperation, { kind: 'open' }>
@@ -51,6 +52,7 @@ export class SqlAgentSessionJournal extends SqlJournalAppends {
private readonly openedThrough: AgentJournalCursor
private acknowledged: AgentJournalCursor
private closed = false
private closing: Promise<void> | undefined
private admitted: Promise<unknown> = Promise.resolve()
private listener: ((commit: JournalWriterCommit) => void) | undefined
readonly epochReplacements = new JournalEpochReplacements()
@@ -70,9 +72,14 @@ export class SqlAgentSessionJournal extends SqlJournalAppends {
{
read: (operation) => this.reads.queue(operation),
write: async (operation: JournalSqlQueueWrite, receipt) =>
(await this.write(operation, receipt && (() => ({ receipt })))).value
(await this.write(operation, receipt && (() => ({ receipt })))).value,
edit: (operation) =>
this.answerOf<JournalDomainEditLeaseOutcome>(
this.write({ kind: 'edit-lease', operation })
)
},
this.reopenFloor
this.reopenFloor,
now
)
// The open operation returns its physical position before ordinary recovery.
// oxlint-disable-next-line typescript/consistent-type-assertions -- SAFETY: the open command returns the physical cursor captured before recovery.
@@ -86,13 +93,15 @@ export class SqlAgentSessionJournal extends SqlJournalAppends {
now?: () => number
}): Promise<SqlAgentSessionJournal> {
const { target, commit } = await options.database.openSession(options.identity)
return new SqlAgentSessionJournal(
const journal = new SqlAgentSessionJournal(
options.database,
options.identity,
target,
options.now ?? Date.now,
commit
)
await journal.queuedMessages.editLeases.expire()
return journal
}
/** The immutable physical position this handle opened at; never the reopen floor. */
@@ -178,6 +187,11 @@ export class SqlAgentSessionJournal extends SqlJournalAppends {
this.goalAttachments.adopt(commit.goals)
}
this.acknowledged = { ...commit.cursor }
if (commit.publication?.editDeadline !== undefined) {
this.queuedMessages.editLeases.adoptDeadline(commit.publication.editDeadline)
} else if (operation.kind === 'epoch-replace') {
this.queuedMessages.editLeases.adoptDeadline(null)
}
this.listener?.(commit)
return commit
})
@@ -230,9 +244,14 @@ export class SqlAgentSessionJournal extends SqlJournalAppends {
/** Refuse admission now; already admitted work retains its ownership until it drains. */
close(): Promise<void> {
if (this.closing) {
return this.closing
}
this.queuedMessages.editLeases.dispose()
const released = this.write({ kind: 'edit-lease', operation: { kind: 'release-owner' } })
this.closed = true
return this.admitted.then(() => undefined)
this.closing = released.then(() => undefined)
return this.closing
}
private admit<T>(
@@ -37,6 +37,7 @@ import type { JournalStopEvent } from './durable-rows/journal-row-schema'
import type { JournalWriterEffect } from './journal-writer-effects'
import type { JournalWriterHostFacts } from './journal-writer-host-facts'
import type { JournalWriterStep } from './writing/journal-writer-step'
import type { JournalDomainEditLeaseOperation } from './journal-domain-edit-leases'
/** The writer chooses the projection epoch; callers identify only their live open handle. */
export type JournalWriterTarget = { sessionId: string; epoch: string; ownerToken: string }
@@ -75,6 +76,7 @@ export type JournalWriterCommand = {
}
export type JournalWriterInputOperation =
| { kind: 'edit-lease'; operation: JournalDomainEditLeaseOperation }
| {
kind: 'submission'
input: JournalSubmissionInput
@@ -8,7 +8,6 @@ import type { JournalGoalAttachmentSnapshot } from './writing/journal-goal-attac
import type { UsageLimitContinueIdentity } from '../../../shared/agent-session/lifecycle/agent-session-usage-limit-continue'
import type { JournalWriterEffect } from './journal-writer-effects'
import type { JournalStopSettle } from './queued-messages/queued-message-pause-marks'
import type { QueuedMessageEditLease } from './queued-messages/queued-message-edit-leases'
export type JournalWriterStoreEffect = Extract<JournalWriterEffect, { kind: 'store' }>
@@ -19,7 +18,6 @@ export type JournalWriterHostFacts = {
openedThrough?: AgentJournalCursor
/** This handle's unmarked reopen boundary. */
reopenFloor?: AgentJournalCursor | null
editLeases?: readonly QueuedMessageEditLease[]
/** Orchestration senders (by `journalMailSenderKey`) and whether their mail is unavailable now. */
mail?: readonly (readonly [string, boolean])[]
/** The handover answer, asked only after the writer validated the consumed card. */
@@ -86,7 +86,7 @@ export function holdQueuedStructuredAgentMessageEdit(
return context.serialize(sessionId, async () => {
if (params.action === 'release') {
const journal = context.sessions.get(sessionId)?.journal
journal?.queuedMessages.editLeases.release(key, messageId)
await journal?.queuedMessages.editLeases.release(key, messageId)
if (journal) {
republish(context, sessionId, journal)
}
@@ -116,7 +116,7 @@ export function holdQueuedStructuredAgentMessageEdit(
})
}
/** Publish/wake explicitly for nonjournaled leases; publication failure cannot revoke them. */
/** Publication failure cannot revoke a committed edit hold. */
export function republish(
context: StructuredAgentSessionMutationContext,
sessionId: string,
@@ -100,6 +100,7 @@ export function wireStructuredAgentSessionQueuedMessages(
void context()
.serialize(sessionId, async () => {
if (sessions.get(sessionId)?.journal === journal) {
await journal.queuedMessages.editLeases.expire()
republish(context(), sessionId, journal)
}
})