Skip to main content

durable/
transaction.rs

1//! One Session commit callback's transaction: table reads before the first table write, staged table writes,
2//! document acquisition and retirement, fork copies, and the atomic batch assembled from them.
3//!
4//! Port of `packages/durable/src/session/{transaction,forks}.ts`. Every Tx operation runs synchronously while the
5//! commit holds the Session line.
6
7use crate::documents::{
8    Doc, Owner, Resolved, address_id, address_of, check_record_scope, check_record_version, document_create,
9    materialize_value, object, resolve_address,
10};
11use crate::session::{CommitChange, Inner, LineState, Loaded, LoadedDocument, Result, SessionError, lock};
12use crate::{
13    ConversationId, ConversationOwner, ConversationParent, ConversationQuery, ConversationRecord, Cursor,
14    DocumentContent, DocumentCopySource, DocumentCreate, DocumentFork, DocumentId, DocumentPoint, DocumentQuery,
15    DocumentRecord, DocumentScope, EntryId, EntryQuery, EntryRecord, Page, ROOT_CONVERSATION_ID, Seq, StorageWrite,
16    SubmissionId, SubmissionRecord, SubmissionStatus, SubmissionType, TaskId, TaskQuery, TaskRecord, TaskState,
17    TaskStatus,
18};
19use chord_delta::{Draft, Prepared, Tracker};
20use indexmap::IndexMap;
21use serde_json::Value;
22use std::collections::{HashMap, HashSet};
23use std::sync::{Arc, Mutex};
24
25const INTERNAL_SCAN_PAGE_SIZE: usize = 256;
26
27/// Executable task definition as far as the Session needs it: its registered name, version, and first checkpoint.
28pub struct TaskDefinition {
29    pub name: String,
30    pub version: u64,
31    pub initial: Box<dyn Fn(&Value) -> Value + Send + Sync>,
32}
33
34impl TaskDefinition {
35    pub fn new(name: &str, version: u64, initial: impl Fn(&Value) -> Value + Send + Sync + 'static) -> Self {
36        TaskDefinition {
37            name: name.to_owned(),
38            version,
39            initial: Box::new(initial),
40        }
41    }
42}
43
44/// Who owns a task: its conversation (a top-level task) or another task of the same conversation.
45#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
46pub enum TaskOwnership {
47    #[default]
48    Conversation,
49    Task(TaskId),
50}
51
52/// Creation options for a durable task.
53#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
54pub struct TaskOptions {
55    pub ownership: TaskOwnership,
56    /// Default: the owner task's conversation, or the transaction's bound conversation.
57    pub conversation_id: Option<ConversationId>,
58    /// Conversation-owned tasks only.
59    pub background: bool,
60    pub abandon_on_restart: bool,
61}
62
63/// Ownership selected explicitly whenever a conversation is created.
64#[derive(Clone, Copy, Debug, PartialEq, Eq)]
65pub enum ConversationOwnership {
66    Ownerless,
67    Task(TaskId),
68}
69
70/// First entry of the active context an entry selects; `SelfId` is the entry's own, newly assigned ID.
71#[derive(Clone, Copy, Debug, PartialEq, Eq)]
72pub enum EntryHead {
73    Entry(EntryId),
74    SelfId,
75}
76
77/// Entry content supplied before the Session assigns identity and task attribution.
78#[derive(Clone, Debug, Default, PartialEq)]
79pub struct EntryDraft {
80    pub kind: String,
81    pub model: Option<Vec<Value>>,
82    pub data: Option<Value>,
83    pub head: Option<EntryHead>,
84    pub edits: Option<Vec<Value>>,
85}
86
87impl EntryDraft {
88    pub fn new(kind: &str) -> EntryDraft {
89        EntryDraft {
90            kind: kind.to_owned(),
91            ..EntryDraft::default()
92        }
93    }
94}
95
96/// Submission fields supplied before the Session assigns an ID. No admission rules apply to a raw creation.
97#[derive(Clone, Debug, PartialEq)]
98pub struct SubmissionCreate {
99    pub conversation_id: ConversationId,
100    pub request_id: Option<String>,
101    pub kind: SubmissionType,
102    pub status: SubmissionStatus,
103    pub entry: Option<EntryId>,
104    pub answer: Option<EntryId>,
105    pub reason: Option<String>,
106    pub detail: Option<Value>,
107}
108
109/// Terminal status staged for a submission.
110#[derive(Clone, Debug, PartialEq)]
111pub enum SubmissionSettlement {
112    Done { answer: EntryId },
113    Unanswered { reason: String, detail: Option<Value> },
114}
115
116enum SubmissionChange {
117    Settle(SubmissionSettlement),
118    Place(EntryId),
119}
120
121/// Complete record after one change: placement turns a queued input `placed` and a queued write `done`; only a placed
122/// input can be answered; a settled record stays.
123fn apply_submission_change(current: &SubmissionRecord, change: &SubmissionChange) -> Result<SubmissionRecord> {
124    if matches!(current.status, SubmissionStatus::Done | SubmissionStatus::Unanswered) {
125        return Ok(current.clone());
126    }
127    let mut next = current.clone();
128    match change {
129        SubmissionChange::Place(entry) => {
130            if current.status != SubmissionStatus::Queued {
131                return Err(SessionError::Error(format!(
132                    "Submission {} is not queued",
133                    current.id.0
134                )));
135            }
136            next.status = match current.kind {
137                SubmissionType::Input => SubmissionStatus::Placed,
138                SubmissionType::Write => SubmissionStatus::Done,
139            };
140            next.entry = Some(*entry);
141        }
142        SubmissionChange::Settle(SubmissionSettlement::Done { answer }) => {
143            if current.status != SubmissionStatus::Placed {
144                return Err(SessionError::Error(format!(
145                    "Submission {} is not a placed input",
146                    current.id.0
147                )));
148            }
149            next.status = SubmissionStatus::Done;
150            next.answer = Some(*answer);
151        }
152        SubmissionChange::Settle(SubmissionSettlement::Unanswered { reason, detail }) => {
153            next.status = SubmissionStatus::Unanswered;
154            next.reason = Some(reason.clone());
155            next.detail = detail.clone();
156        }
157    }
158    Ok(next)
159}
160
161/// Defaults a commit binds to: the `create_task` conversation and the task attributed to appended entries.
162#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
163pub struct TxScope {
164    pub conversation_id: Option<ConversationId>,
165    pub task_id: Option<TaskId>,
166}
167
168#[derive(Clone, Copy, PartialEq, Eq)]
169enum TaskWrite {
170    Create,
171    Replace,
172}
173
174#[derive(Default)]
175struct TxTask {
176    committed: Option<Option<TaskRecord>>,
177    write: Option<(TaskWrite, TaskRecord)>,
178    publication_conversation: Option<ConversationId>,
179}
180
181/// Storage/cache provenance of one staged incarnation.
182enum Target {
183    Loaded(Loaded),
184    Created {
185        record: DocumentCreate,
186        version: u64,
187        tracker: Tracker,
188    },
189    ForkCopy {
190        record: DocumentCreate,
191        source: DocumentCopySource,
192    },
193}
194
195/// One incarnation acquired, created, copied, or retired by this transaction.
196struct DocEntry {
197    address_id: String,
198    /// Absent for definition-free fork copies.
199    definition: Option<Doc>,
200    draft: Option<Draft>,
201    target: Option<Target>,
202    retire: bool,
203}
204
205enum PlanRecord {
206    New(DocumentCreate),
207    Committed(DocumentRecord),
208}
209
210impl PlanRecord {
211    fn identity(&self) -> &DocumentCreate {
212        match self {
213            PlanRecord::New(record) => record,
214            PlanRecord::Committed(record) => &record.identity,
215        }
216    }
217}
218
219enum PlanTracker {
220    Created(Tracker),
221    Loaded(Loaded),
222}
223
224struct PlanChange {
225    tracker: PlanTracker,
226    prepared: Prepared,
227    version: u64,
228    definition: Option<Doc>,
229}
230
231/// What one staged incarnation writes and publishes, decided before Storage admission so adoption only applies it.
232pub(crate) struct Plan {
233    address_id: String,
234    record: PlanRecord,
235    retire: bool,
236    content: Option<StorageWrite>,
237    change: Option<PlanChange>,
238    conversation_id: Option<ConversationId>,
239}
240
241impl Plan {
242    /// Every creation, copy, and retirement publishes, and a loaded incarnation that writes content (a
243    /// migration-only base included, so observers of the older shape receive the new value).
244    fn publishes(&self) -> bool {
245        self.retire
246            || !matches!(
247                self.change,
248                Some(PlanChange {
249                    tracker: PlanTracker::Loaded(_),
250                    ..
251                })
252            )
253            || self.content.is_some()
254    }
255}
256
257fn object_of(value: &Value) -> crate::JsonObject {
258    value.as_object().cloned().expect("document values are objects")
259}
260
261/// The transaction of one Session commit callback. Table reads fail with [`SessionError::ReadAfterWrite`] after the
262/// first table write; document access stays available.
263pub struct Tx<'a> {
264    inner: &'a Inner,
265    line: &'a mut LineState,
266    scope: TxScope,
267    has_table_write: bool,
268    /// Conversation and entry writes, staged eagerly in order.
269    writes: Vec<StorageWrite>,
270    created_conversations: HashSet<ConversationId>,
271    fork_source_conversations: HashSet<ConversationId>,
272    fork_source_documents: HashSet<DocumentId>,
273    tasks: IndexMap<TaskId, TxTask>,
274    submissions: IndexMap<SubmissionId, SubmissionRecord>,
275    submission_changes: Vec<(SubmissionId, SubmissionChange)>,
276    documents: Vec<DocEntry>,
277    /// Latest entry (index into `documents`) at each logical address.
278    latest: HashMap<String, usize>,
279}
280
281impl<'a> Tx<'a> {
282    pub(crate) fn new(inner: &'a Inner, line: &'a mut LineState, scope: TxScope) -> Tx<'a> {
283        Tx {
284            inner,
285            line,
286            scope,
287            has_table_write: false,
288            writes: Vec::new(),
289            created_conversations: HashSet::new(),
290            fork_source_conversations: HashSet::new(),
291            fork_source_documents: HashSet::new(),
292            tasks: IndexMap::new(),
293            submissions: IndexMap::new(),
294            submission_changes: Vec::new(),
295            documents: Vec::new(),
296            latest: HashMap::new(),
297        }
298    }
299
300    fn read<T>(&mut self, call: impl FnOnce(&mut dyn crate::Storage) -> crate::Result<T>) -> Result<T> {
301        self.inner.guard(self.line, true, call)
302    }
303
304    /// A read of committed Storage that ignores the read-after-write rule: the conversation runtime and the task
305    /// scheduler (`crates/harness`) read inside their own commit callbacks, as upstream's read Storage directly.
306    pub fn committed<T>(&mut self, read: impl FnOnce(&dyn crate::Storage) -> crate::Result<T>) -> Result<T> {
307        self.read(|storage| read(storage))
308    }
309
310    /// Latest candidate of every task this transaction created or replaced, in first-write order.
311    pub fn staged_tasks(&self) -> Vec<TaskRecord> {
312        self.tasks
313            .values()
314            .filter_map(|task| task.write.as_ref().map(|(_, record)| record.clone()))
315            .collect()
316    }
317
318    /// Every conversation this transaction created or forked, in order.
319    pub fn staged_conversations(&self) -> Vec<ConversationRecord> {
320        self.writes
321            .iter()
322            .filter_map(|write| match write {
323                StorageWrite::Conversation { value } => Some(value.clone()),
324                _ => None,
325            })
326            .collect()
327    }
328
329    /// Create the ownerless root conversation at its reserved ID.
330    pub fn create_root_conversation(&mut self) -> Result<ConversationRecord> {
331        self.has_table_write = true;
332        let record = ConversationRecord {
333            id: ROOT_CONVERSATION_ID,
334            parent: None,
335            owner: None,
336        };
337        self.created_conversations.insert(record.id);
338        self.writes.push(StorageWrite::Conversation { value: record.clone() });
339        Ok(record)
340    }
341
342    fn mint(&mut self) -> Result<u64> {
343        self.inner.guard(self.line, false, |storage| storage.mint_id())
344    }
345
346    fn table_read(&self, method: &'static str) -> Result<()> {
347        if self.has_table_write {
348            Err(SessionError::ReadAfterWrite(method))
349        } else {
350            Ok(())
351        }
352    }
353
354    pub fn conversation(&mut self, id: ConversationId) -> Result<Option<ConversationRecord>> {
355        self.table_read("conversation")?;
356        self.read(|storage| storage.conversation(id))
357    }
358
359    pub fn entry(&mut self, id: EntryId) -> Result<Option<EntryRecord>> {
360        self.table_read("entry")?;
361        Ok(self.read(|storage| storage.entry(id))?.map(|stored| stored.entry))
362    }
363
364    /// `None` when the entry is absent or has another kind.
365    pub fn entry_of(&mut self, kind: &str, id: EntryId) -> Result<Option<EntryRecord>> {
366        Ok(self.entry(id)?.filter(|entry| entry.kind == kind))
367    }
368
369    pub fn task(&mut self, id: TaskId) -> Result<Option<TaskRecord>> {
370        self.table_read("task")?;
371        self.committed_task(id)
372    }
373
374    pub fn scan_conversations(
375        &mut self,
376        query: &ConversationQuery,
377        limit: usize,
378        cursor: Option<&Cursor>,
379    ) -> Result<Page<ConversationRecord>> {
380        self.table_read("scanConversations")?;
381        self.read(|storage| storage.scan_conversations(query, limit, cursor))
382    }
383
384    pub fn scan_entries(
385        &mut self,
386        query: &EntryQuery,
387        limit: usize,
388        cursor: Option<&Cursor>,
389    ) -> Result<Page<EntryRecord>> {
390        self.table_read("scanEntries")?;
391        self.read(|storage| storage.scan_entries(query, limit, cursor))
392    }
393
394    /// Newest visible entry of the conversation that carries a `head`.
395    pub fn latest_head_marker(&mut self, conversation_id: ConversationId) -> Result<Option<EntryRecord>> {
396        self.table_read("latestHeadMarker")?;
397        self.read(|storage| storage.find_latest_head_marker(conversation_id, None))
398    }
399
400    pub fn scan_tasks(&mut self, query: &TaskQuery, limit: usize, cursor: Option<&Cursor>) -> Result<Page<TaskRecord>> {
401        self.table_read("scanTasks")?;
402        self.read(|storage| storage.scan_tasks(query, limit, cursor))
403    }
404
405    pub fn submission(&mut self, id: SubmissionId) -> Result<Option<SubmissionRecord>> {
406        self.table_read("submission")?;
407        self.read(|storage| storage.submission(id))
408    }
409
410    /// Committed submission with a conversation-scoped request ID, for host deduplication.
411    pub fn submission_by_request(
412        &mut self,
413        conversation_id: ConversationId,
414        request_id: &str,
415    ) -> Result<Option<SubmissionRecord>> {
416        self.table_read("submissionByRequest")?;
417        self.read(|storage| storage.submission_by_request(conversation_id, request_id))
418    }
419
420    pub fn create_conversation(&mut self, ownership: ConversationOwnership) -> Result<ConversationRecord> {
421        self.has_table_write = true;
422        self.stage_conversation(None, ownership)
423    }
424
425    /// Fork history at one visible entry; conversation documents are copied by their fork policy.
426    pub fn fork_conversation(
427        &mut self,
428        parent: ConversationId,
429        at: EntryId,
430        ownership: ConversationOwnership,
431    ) -> Result<ConversationRecord> {
432        self.has_table_write = true;
433        self.stage_conversation(
434            Some(ConversationParent {
435                conversation_id: parent,
436                at,
437            }),
438            ownership,
439        )
440    }
441
442    fn stage_conversation(
443        &mut self,
444        parent: Option<ConversationParent>,
445        ownership: ConversationOwnership,
446    ) -> Result<ConversationRecord> {
447        let id = ConversationId(self.mint()?);
448        let owner = match ownership {
449            ConversationOwnership::Ownerless => None,
450            ConversationOwnership::Task(task_id) => {
451                let Some(task) = self.current_task(task_id)? else {
452                    return Err(SessionError::Error(format!(
453                        "Conversation owner task {} does not exist",
454                        task_id.0
455                    )));
456                };
457                Some(ConversationOwner {
458                    conversation_id: task.conversation_id,
459                    task_id,
460                })
461            }
462        };
463        let record = ConversationRecord { id, parent, owner };
464        if let Some(parent) = parent {
465            for (copy, source) in self.fork_copies(parent.conversation_id, parent.at, id)? {
466                self.fork_source_documents.insert(source.id);
467                let address = address_of(&copy);
468                let entry = DocEntry {
469                    address_id: address_id(&address),
470                    definition: None,
471                    draft: None,
472                    target: Some(Target::ForkCopy { record: copy, source }),
473                    retire: false,
474                };
475                self.latest.insert(entry.address_id.clone(), self.documents.len());
476                self.documents.push(entry);
477            }
478            self.fork_source_conversations.insert(parent.conversation_id);
479        }
480        self.created_conversations.insert(id);
481        self.writes.push(StorageWrite::Conversation { value: record.clone() });
482        Ok(record)
483    }
484
485    /// Every persisted conversation document one fork copies: `asOf` documents of the entry's own conversation at the
486    /// entry's commit, then `current` documents of the immediate parent (upstream `prepareForkDocumentCopies`).
487    fn fork_copies(
488        &mut self,
489        parent: ConversationId,
490        at: EntryId,
491        child: ConversationId,
492    ) -> Result<Vec<(DocumentCreate, DocumentCopySource)>> {
493        let Some(entry) = self.read(|storage| storage.visible_entry(parent, at))? else {
494            return Err(SessionError::Error(format!(
495                "Entry {} is not visible from conversation {}",
496                at.0, parent.0
497            )));
498        };
499        let mut copies = Vec::new();
500        let mut copied = HashSet::new();
501        let selections = [
502            (
503                entry.entry.conversation_id,
504                DocumentPoint::At(entry.commit_seq),
505                DocumentFork::AsOf,
506            ),
507            (parent, DocumentPoint::Current, DocumentFork::Current),
508        ];
509        for (conversation_id, point, policy) in selections {
510            let query = DocumentQuery {
511                scope: DocumentScope::Conversation { conversation_id },
512                at: point,
513                kind: None,
514            };
515            let mut cursor: Option<Cursor> = None;
516            loop {
517                let page =
518                    self.read(|storage| storage.scan_documents(&query, INTERNAL_SCAN_PAGE_SIZE, cursor.as_ref()))?;
519                for source in page.items {
520                    if !matches!(source.identity.scope, DocumentScope::Conversation { .. })
521                        || source.identity.fork != Some(policy)
522                    {
523                        continue;
524                    }
525                    let id = DocumentId(self.mint()?);
526                    let record = DocumentCreate {
527                        id,
528                        kind: source.identity.kind.clone(),
529                        key: source.identity.key.clone(),
530                        scope: DocumentScope::Conversation { conversation_id: child },
531                        history: source.identity.history,
532                        fork: source.identity.fork,
533                    };
534                    if !copied.insert(address_id(&address_of(&record))) {
535                        let member = match &record.key {
536                            None => record.kind.clone(),
537                            Some(key) => format!("{}/{}", record.kind, key),
538                        };
539                        return Err(SessionError::Error(format!(
540                            "Fork selects multiple source documents for {member}"
541                        )));
542                    }
543                    copies.push((
544                        record,
545                        DocumentCopySource {
546                            id: source.identity.id,
547                            at: point,
548                        },
549                    ));
550                }
551                match page.next {
552                    Some(next) => cursor = Some(next),
553                    None => break,
554                }
555            }
556        }
557        Ok(copies)
558    }
559
560    /// Append an entry; `head: SelfId` starts the active context at the new entry.
561    pub fn append_entry(&mut self, conversation_id: ConversationId, draft: EntryDraft) -> Result<EntryRecord> {
562        self.has_table_write = true;
563        self.require_conversation(conversation_id)?;
564        let id = EntryId(self.mint()?);
565        let record = EntryRecord {
566            id,
567            conversation_id,
568            kind: draft.kind,
569            model: draft.model,
570            data: draft.data,
571            head: draft.head.map(|head| match head {
572                EntryHead::Entry(entry) => entry,
573                EntryHead::SelfId => id,
574            }),
575            edits: draft.edits,
576            by_task_id: self.scope.task_id,
577        };
578        self.writes.push(StorageWrite::Entry { value: record.clone() });
579        Ok(record)
580    }
581
582    pub fn create_task(&mut self, task: &TaskDefinition, input: Value, options: TaskOptions) -> Result<TaskId> {
583        self.has_table_write = true;
584        let owner = match options.ownership {
585            TaskOwnership::Conversation => None,
586            TaskOwnership::Task(owner_id) => {
587                // Validated again against the owner's final candidate during assembly.
588                let Some(owner) = self.current_task(owner_id)? else {
589                    return Err(SessionError::Error(format!("Task owner {} does not exist", owner_id.0)));
590                };
591                if options.background {
592                    return Err(SessionError::Type("A child task cannot be background".into()));
593                }
594                if options.conversation_id.is_some_and(|id| id != owner.conversation_id) {
595                    return Err(SessionError::Error(format!(
596                        "A child task lives in its owner's conversation {}",
597                        owner.conversation_id.0
598                    )));
599                }
600                Some(owner)
601            }
602        };
603        let Some(conversation_id) = owner
604            .as_ref()
605            .map(|owner| owner.conversation_id)
606            .or(options.conversation_id)
607            .or(self.scope.conversation_id)
608        else {
609            return Err(SessionError::Type(
610                "Tx.createTask() requires options.conversationId".into(),
611            ));
612        };
613        self.require_conversation(conversation_id)?;
614        let checkpoint = (task.initial)(&input);
615        let id = TaskId(self.mint()?);
616        let record = TaskRecord {
617            id,
618            conversation_id,
619            kind: task.name.clone(),
620            version: task.version,
621            input,
622            owner: owner.map(|owner| owner.id),
623            background: options.background,
624            abort_requested: false,
625            abort_reason: None,
626            abandon_on_restart: options.abandon_on_restart,
627            started_at: None,
628            ended_at: None,
629            state: TaskState::Pending { checkpoint },
630            memos: None,
631        };
632        self.tasks.insert(
633            id,
634            TxTask {
635                write: Some((TaskWrite::Create, record)),
636                ..TxTask::default()
637            },
638        );
639        Ok(id)
640    }
641
642    /// Create a raw submission record with a fresh ID. No admission rules apply.
643    pub fn create_submission(&mut self, create: SubmissionCreate) -> Result<SubmissionRecord> {
644        self.has_table_write = true;
645        self.require_conversation(create.conversation_id)?;
646        let id = SubmissionId(self.mint()?);
647        let record = SubmissionRecord {
648            id,
649            conversation_id: create.conversation_id,
650            request_id: create.request_id,
651            kind: create.kind,
652            status: create.status,
653            entry: create.entry,
654            answer: create.answer,
655            reason: create.reason,
656            detail: create.detail,
657        };
658        self.submissions.insert(id, record.clone());
659        Ok(record)
660    }
661
662    /// Settle a queued or placed submission; resolved during assembly against this transaction's latest record.
663    pub fn settle_submission(&mut self, id: SubmissionId, settlement: SubmissionSettlement) {
664        self.has_table_write = true;
665        self.submission_changes.push((id, SubmissionChange::Settle(settlement)));
666    }
667
668    /// Place a queued submission at `entry`: an input becomes `placed`, a write `done`.
669    pub fn place_submission(&mut self, id: SubmissionId, entry: EntryId) {
670        self.has_table_write = true;
671        self.submission_changes.push((id, SubmissionChange::Place(entry)));
672    }
673
674    /// Replace one task record completely, stamping `startedAt` on its first change to `running` and `endedAt` on the
675    /// change to `terminal`.
676    pub fn set_task(&mut self, value: TaskRecord) -> Result<()> {
677        self.has_table_write = true;
678        let now = &self.inner.now;
679        let task = self.tasks.entry(value.id).or_default();
680        let candidate = task.write.as_ref().map(|(_, record)| record);
681        if let Some(candidate) = candidate {
682            if candidate.state.status() == TaskStatus::Terminal {
683                return Err(SessionError::Error(format!(
684                    "Task {} already has a terminal candidate",
685                    value.id.0
686                )));
687            }
688            if candidate.conversation_id != value.conversation_id {
689                return Err(SessionError::Error(format!(
690                    "Task {} cannot change conversations",
691                    value.id.0
692                )));
693            }
694        }
695        let status = value.state.status();
696        let started_at = candidate
697            .and_then(|candidate| candidate.started_at)
698            .or(value.started_at)
699            .or_else(|| (status == TaskStatus::Running).then(now));
700        let ended_at = candidate
701            .and_then(|candidate| candidate.ended_at)
702            .or(value.ended_at)
703            .or_else(|| (status == TaskStatus::Terminal).then(now));
704        let kind = match task.write {
705            Some((TaskWrite::Create, _)) => TaskWrite::Create,
706            _ => TaskWrite::Replace,
707        };
708        task.write = Some((
709            kind,
710            TaskRecord {
711                started_at,
712                ended_at,
713                ..value
714            },
715        ));
716        Ok(())
717    }
718
719    /// Acquire a draft of a singleton document, creating it from `initial` when absent.
720    pub fn doc(&mut self, doc: &Doc, owner: Owner) -> Result<Draft> {
721        let resolved = resolve_address(doc.definition(), owner)?;
722        if let DocumentScope::Task { task_id } = resolved.address.scope
723            && self
724                .tasks
725                .get(&task_id)
726                .and_then(|task| task.write.as_ref())
727                .is_some_and(|(_, record)| record.state.status() == TaskStatus::Terminal)
728        {
729            return Err(SessionError::Error(format!("Task {} is terminal", task_id.0)));
730        }
731        let latest = self.latest.get(&resolved.id).copied();
732        if let Some(index) = latest
733            && !self.documents[index].retire
734        {
735            if let Some(draft) = &self.documents[index].draft {
736                return Ok(draft.clone());
737            }
738            if matches!(self.documents[index].target, Some(Target::ForkCopy { .. })) {
739                return self.acquire_fork_copy(index, doc);
740            }
741        }
742        let skip_load = latest.is_some_and(|index| self.documents[index].retire);
743        let (target, draft) = self.acquire(doc, &resolved, skip_load)?;
744        self.latest.insert(resolved.id.clone(), self.documents.len());
745        self.documents.push(DocEntry {
746            address_id: resolved.id,
747            definition: Some(doc.clone()),
748            draft: Some(draft.clone()),
749            target: Some(target),
750            retire: false,
751        });
752        Ok(draft)
753    }
754
755    fn acquire(&mut self, doc: &Doc, resolved: &Resolved, skip_load: bool) -> Result<(Target, Draft)> {
756        let definition = doc.definition();
757        let loaded = if skip_load {
758            None
759        } else {
760            self.inner
761                .load(self.line, definition, &resolved.id, &resolved.address)?
762        };
763        if let Some(loaded) = loaded {
764            let draft = {
765                let document = lock(&loaded);
766                check_record_scope(definition, &document.record.identity)?;
767                check_record_version(definition, &document.record.identity, document.stored_version)?;
768                document.tracker.begin_change()?
769            };
770            return Ok((Target::Loaded(loaded), draft));
771        }
772        match resolved.address.scope {
773            DocumentScope::Conversation { conversation_id } => self.require_conversation(conversation_id)?,
774            DocumentScope::Task { task_id } => match self.current_task(task_id)? {
775                None => return Err(SessionError::Error(format!("Task {} does not exist", task_id.0))),
776                Some(task) if task.state.status() == TaskStatus::Terminal => {
777                    return Err(SessionError::Error(format!("Task {} is terminal", task_id.0)));
778                }
779                Some(_) => {}
780            },
781            DocumentScope::Session => {}
782        }
783        let value = object((definition.initial)(&Value::Null), &definition.kind)?;
784        let id = DocumentId(self.mint()?);
785        let tracker = Tracker::new(value);
786        let draft = tracker.begin_change()?;
787        let record = document_create(definition, &resolved.address, id);
788        Ok((
789            Target::Created {
790                record,
791                version: definition.version,
792                tracker,
793            },
794            draft,
795        ))
796    }
797
798    /// Hydrate a staged fork copy from its exact source for typed access; the copy then writes a creation base.
799    fn acquire_fork_copy(&mut self, index: usize, doc: &Doc) -> Result<Draft> {
800        let Some(Target::ForkCopy { record, source }) = &self.documents[index].target else {
801            unreachable!("checked by the caller");
802        };
803        let (record, source) = (record.clone(), *source);
804        let Some(stored) = self.read(|storage| storage.document(source.id, source.at))? else {
805            return Err(SessionError::Error(format!(
806                "Fork source document {} cannot be read",
807                source.id.0
808            )));
809        };
810        let original = &stored.record.identity;
811        if !matches!(original.scope, DocumentScope::Conversation { .. })
812            || original.kind != record.kind
813            || original.key != record.key
814            || original.history != record.history
815            || original.fork != record.fork
816        {
817            return Err(SessionError::Error(format!(
818                "Fork source document {} does not match the copied record",
819                source.id.0
820            )));
821        }
822        let definition = doc.definition();
823        let value = materialize_value(definition, &record, stored.version, &stored.value)?;
824        let tracker = Tracker::new(value);
825        let draft = tracker.begin_change()?;
826        let entry = &mut self.documents[index];
827        entry.definition = Some(doc.clone());
828        entry.target = Some(Target::Created {
829            record,
830            version: definition.version,
831            tracker,
832        });
833        entry.draft = Some(draft.clone());
834        Ok(draft)
835    }
836
837    /// Revoke every draft without writing anything.
838    pub(crate) fn discard(&self) {
839        for entry in &self.documents {
840            if let Some(draft) = &entry.draft {
841                draft.abort();
842            }
843        }
844    }
845
846    /// Prepare every draft (revoking it) and assemble the atomic batch and the adoption plans. Any failure writes
847    /// nothing and leaves every committed revision unchanged.
848    pub(crate) fn settle(mut self) -> Result<(Vec<StorageWrite>, Vec<Plan>)> {
849        let result = self.assemble();
850        if result.is_err() {
851            self.discard();
852        }
853        result
854    }
855
856    fn assemble(&mut self) -> Result<(Vec<StorageWrite>, Vec<Plan>)> {
857        let mut plans = Vec::new();
858        for entry in std::mem::take(&mut self.documents) {
859            if let Some(plan) = plan_document(entry)? {
860                plans.push(plan);
861            }
862        }
863        self.reject_fork_source_writes(&plans)?;
864        self.validate_owners()?;
865        let replaced: Vec<(TaskId, ConversationId)> = self
866            .tasks
867            .iter()
868            .filter_map(|(id, task)| match &task.write {
869                Some((TaskWrite::Replace, record)) => Some((*id, record.conversation_id)),
870                _ => None,
871            })
872            .collect();
873        for (id, conversation_id) in replaced {
874            let Some(committed) = self.committed_task(id)? else {
875                return Err(SessionError::Error(format!("Task {} does not exist", id.0)));
876            };
877            if committed.state.status() == TaskStatus::Terminal {
878                return Err(SessionError::Error(format!("Task {} is already terminal", id.0)));
879            }
880            if committed.conversation_id != conversation_id {
881                return Err(SessionError::Error(format!(
882                    "Task {} cannot change conversations",
883                    id.0
884                )));
885            }
886        }
887
888        // Terminal settlement retires every task document, including ones created by this transaction.
889        let terminal: Vec<(TaskId, bool)> = self
890            .tasks
891            .values()
892            .filter_map(|task| match &task.write {
893                Some((kind, record)) if record.state.status() == TaskStatus::Terminal => {
894                    Some((record.id, *kind == TaskWrite::Create))
895                }
896                _ => None,
897            })
898            .collect();
899        if !terminal.is_empty() {
900            let mut retiring = HashSet::new();
901            for plan in &mut plans {
902                if let DocumentScope::Task { task_id } = plan.record.identity().scope
903                    && terminal.iter().any(|(id, _)| *id == task_id)
904                {
905                    plan.retire = true;
906                    retiring.insert(plan.record.identity().id);
907                }
908            }
909            for (task_id, created) in terminal {
910                if created {
911                    continue;
912                }
913                let query = DocumentQuery {
914                    scope: DocumentScope::Task { task_id },
915                    at: DocumentPoint::Current,
916                    kind: None,
917                };
918                let mut cursor: Option<Cursor> = None;
919                loop {
920                    let page =
921                        self.read(|storage| storage.scan_documents(&query, INTERNAL_SCAN_PAGE_SIZE, cursor.as_ref()))?;
922                    for record in page.items {
923                        if !retiring.insert(record.identity.id) {
924                            continue;
925                        }
926                        plans.push(Plan {
927                            address_id: address_id(&address_of(&record.identity)),
928                            record: PlanRecord::Committed(record),
929                            retire: true,
930                            content: None,
931                            change: None,
932                            conversation_id: None,
933                        });
934                    }
935                    match page.next {
936                        Some(next) => cursor = Some(next),
937                        None => break,
938                    }
939                }
940            }
941        }
942
943        // Resolve publication ownership before Storage admission so adoption needs no reads.
944        for plan in &mut plans {
945            if !plan.publishes() {
946                continue;
947            }
948            match plan.record.identity().scope {
949                DocumentScope::Conversation { conversation_id } => plan.conversation_id = Some(conversation_id),
950                DocumentScope::Task { task_id } => {
951                    let known = self.tasks.get(&task_id).and_then(|task| task.publication_conversation);
952                    let conversation = match known {
953                        Some(conversation) => Some(conversation),
954                        None => self.current_task(task_id)?.map(|task| task.conversation_id),
955                    };
956                    if let Some(conversation) = conversation {
957                        self.tasks.entry(task_id).or_default().publication_conversation = Some(conversation);
958                    }
959                    plan.conversation_id = conversation;
960                }
961                DocumentScope::Session => {}
962            }
963        }
964
965        for (id, change) in std::mem::take(&mut self.submission_changes) {
966            let current = match self.submissions.get(&id) {
967                Some(current) => Some(current.clone()),
968                None => self.read(|storage| storage.submission(id))?,
969            };
970            let Some(current) = current else {
971                return Err(SessionError::Error(format!("Submission {} does not exist", id.0)));
972            };
973            let next = apply_submission_change(&current, &change)?;
974            if next != current {
975                self.submissions.insert(id, next);
976            }
977        }
978
979        let mut writes = std::mem::take(&mut self.writes);
980        writes.extend(
981            self.submissions
982                .values()
983                .map(|value| StorageWrite::Submission { value: value.clone() }),
984        );
985        for task in self.tasks.values() {
986            if let Some((_, record)) = &task.write {
987                writes.push(StorageWrite::Task { value: record.clone() });
988            }
989        }
990        for plan in &mut plans {
991            // Checkpoint predicates run last, after every validation.
992            if let (
993                Some(StorageWrite::DocumentChange {
994                    id,
995                    content: DocumentContent::Delta { .. },
996                }),
997                Some(PlanChange {
998                    tracker: PlanTracker::Loaded(loaded),
999                    prepared,
1000                    version,
1001                    definition: Some(doc),
1002                }),
1003            ) = (&plan.content, &plan.change)
1004                && let Some(predicate) = &doc.definition().checkpoint_when
1005            {
1006                let info = crate::documents::CheckpointInfo {
1007                    deltas_since_base: lock(loaded).deltas_since_base,
1008                };
1009                if predicate(doc.definition(), &prepared.value, &prepared.ops, info).map_err(SessionError::Error)? {
1010                    plan.content = Some(StorageWrite::DocumentChange {
1011                        id: *id,
1012                        content: DocumentContent::Base {
1013                            version: *version,
1014                            value: object_of(&prepared.value),
1015                        },
1016                    });
1017                }
1018            }
1019            if let Some(content) = &plan.content {
1020                writes.push(content.clone());
1021            }
1022            if plan.retire {
1023                writes.push(StorageWrite::DocumentRetire {
1024                    id: plan.record.identity().id,
1025                });
1026            }
1027        }
1028        Ok((writes, plans))
1029    }
1030
1031    /// New owned work needs a live owner, judged on its final candidate: not `completing`, terminal, or abort-marked.
1032    fn validate_owners(&mut self) -> Result<()> {
1033        let mut owners: Vec<(&'static str, TaskId)> = Vec::new();
1034        for write in &self.writes {
1035            if let StorageWrite::Conversation { value } = write
1036                && let Some(owner) = value.owner
1037            {
1038                owners.push(("Conversation owner task", owner.task_id));
1039            }
1040        }
1041        for task in self.tasks.values() {
1042            if let Some((TaskWrite::Create, record)) = &task.write
1043                && let Some(owner) = record.owner
1044            {
1045                owners.push(("Task owner", owner));
1046            }
1047        }
1048        for (what, task_id) in owners {
1049            let Some(task) = self.current_task(task_id)? else {
1050                return Err(SessionError::Error(format!("{what} {} does not exist", task_id.0)));
1051            };
1052            match task.state.status() {
1053                TaskStatus::Terminal => return Err(SessionError::Error(format!("{what} {} is terminal", task_id.0))),
1054                TaskStatus::Completing => {
1055                    return Err(SessionError::Error(format!("{what} {} is completing", task_id.0)));
1056                }
1057                _ => {}
1058            }
1059            if task.abort_requested {
1060                return Err(SessionError::Error(format!("{what} {} is abort-marked", task_id.0)));
1061            }
1062        }
1063        Ok(())
1064    }
1065
1066    fn reject_fork_source_writes(&self, plans: &[Plan]) -> Result<()> {
1067        for plan in plans {
1068            if plan.content.is_none() && !plan.retire {
1069                continue;
1070            }
1071            let record = plan.record.identity();
1072            if self.fork_source_documents.contains(&record.id) {
1073                return Err(SessionError::Error(format!(
1074                    "Cannot change fork source document {} in the fork transaction",
1075                    record.id.0
1076                )));
1077            }
1078            if let DocumentScope::Conversation { conversation_id } = record.scope
1079                && self.fork_source_conversations.contains(&conversation_id)
1080                && record.fork == Some(DocumentFork::Current)
1081            {
1082                return Err(SessionError::Error(format!(
1083                    "Cannot fork conversation {} while changing its current-policy documents",
1084                    conversation_id.0
1085                )));
1086            }
1087        }
1088        Ok(())
1089    }
1090
1091    fn require_conversation(&mut self, id: ConversationId) -> Result<()> {
1092        if self.created_conversations.contains(&id) || self.read(|storage| storage.conversation(id))?.is_some() {
1093            Ok(())
1094        } else {
1095            Err(SessionError::Error(format!("Conversation {} does not exist", id.0)))
1096        }
1097    }
1098
1099    /// Latest candidate task record, falling back to committed state; not a caller table read.
1100    fn current_task(&mut self, id: TaskId) -> Result<Option<TaskRecord>> {
1101        if let Some((_, record)) = self.tasks.get(&id).and_then(|task| task.write.as_ref()) {
1102            return Ok(Some(record.clone()));
1103        }
1104        self.committed_task(id)
1105    }
1106
1107    fn committed_task(&mut self, id: TaskId) -> Result<Option<TaskRecord>> {
1108        if let Some(Some(committed)) = self.tasks.get(&id).map(|task| &task.committed) {
1109            return Ok(committed.clone());
1110        }
1111        let committed = self.read(|storage| storage.task(id))?;
1112        self.tasks.entry(id).or_default().committed = Some(committed.clone());
1113        Ok(committed)
1114    }
1115}
1116
1117/// Plan of one staged document: its record, content write, and prepared change. Retirement is decided later.
1118fn plan_document(entry: DocEntry) -> Result<Option<Plan>> {
1119    let DocEntry {
1120        address_id,
1121        definition,
1122        draft,
1123        target,
1124        retire,
1125        ..
1126    } = entry;
1127    let Some(target) = target else {
1128        return Ok(None);
1129    };
1130    let prepared = match &draft {
1131        Some(draft) => Some(draft.prepare()?),
1132        None => None,
1133    };
1134    let plan = |record, content, change| Plan {
1135        address_id: address_id.clone(),
1136        record,
1137        retire,
1138        content,
1139        change,
1140        conversation_id: None,
1141    };
1142    Ok(Some(match target {
1143        Target::Created {
1144            record,
1145            version,
1146            tracker,
1147        } => {
1148            let prepared = prepared.expect("a created incarnation has a draft");
1149            let content = StorageWrite::DocumentCreate {
1150                record: record.clone(),
1151                content: DocumentContent::Base {
1152                    version,
1153                    value: object_of(&prepared.value),
1154                },
1155            };
1156            plan(
1157                PlanRecord::New(record),
1158                Some(content),
1159                Some(PlanChange {
1160                    tracker: PlanTracker::Created(tracker),
1161                    prepared,
1162                    version,
1163                    definition,
1164                }),
1165            )
1166        }
1167        Target::ForkCopy { record, source } => {
1168            let content = StorageWrite::DocumentCopy {
1169                record: record.clone(),
1170                source,
1171            };
1172            plan(PlanRecord::New(record), Some(content), None)
1173        }
1174        Target::Loaded(loaded) => {
1175            let prepared = prepared.expect("a loaded incarnation has a draft");
1176            let doc = definition.expect("a loaded incarnation has a definition");
1177            let version = doc.definition().version;
1178            let (record, stored_version) = {
1179                let document = lock(&loaded);
1180                (document.record.clone(), document.stored_version)
1181            };
1182            let id = record.identity.id;
1183            // A version change stores a base even without operations; otherwise only a change stores a delta.
1184            let content = if stored_version < version {
1185                Some(DocumentContent::Base {
1186                    version,
1187                    value: object_of(&prepared.value),
1188                })
1189            } else if !prepared.ops.is_empty() {
1190                Some(DocumentContent::Delta {
1191                    version,
1192                    ops: prepared.ops.clone(),
1193                })
1194            } else {
1195                None
1196            };
1197            plan(
1198                PlanRecord::Committed(record),
1199                content.map(|content| StorageWrite::DocumentChange { id, content }),
1200                Some(PlanChange {
1201                    tracker: PlanTracker::Loaded(loaded),
1202                    prepared,
1203                    version,
1204                    definition: Some(doc),
1205                }),
1206            )
1207        }
1208    }))
1209}
1210
1211/// Adopt every prepared change after Storage acknowledged `seq`, install new incarnations, evict retired ones, and
1212/// describe the document publication.
1213pub(crate) fn adopt(inner: &Inner, plans: Vec<Plan>, seq: Seq) -> Result<Vec<CommitChange>> {
1214    let mut publications = Vec::new();
1215    for plan in plans {
1216        let publishes = plan.publishes();
1217        let committed = matches!(plan.record, PlanRecord::Committed(_));
1218        let mut record = match plan.record {
1219            PlanRecord::Committed(record) => record,
1220            PlanRecord::New(identity) => DocumentRecord {
1221                identity,
1222                created_at: seq,
1223                retired_at: None,
1224            },
1225        };
1226        if plan.retire {
1227            record.retired_at = Some(seq);
1228        }
1229        let mut published = None;
1230        if let Some(change) = plan.change {
1231            let PlanChange {
1232                tracker,
1233                prepared,
1234                version,
1235                ..
1236            } = change;
1237            match tracker {
1238                PlanTracker::Created(mut tracker) => {
1239                    // A new incarnation is adopted unless it retires in the same commit.
1240                    if !plan.retire {
1241                        tracker.adopt(&prepared)?;
1242                        let loaded = LoadedDocument {
1243                            record: record.clone(),
1244                            stored_version: version,
1245                            value_version: version,
1246                            deltas_since_base: 0,
1247                            tracker,
1248                        };
1249                        lock(&inner.documents).insert(plan.address_id.clone(), Arc::new(Mutex::new(loaded)));
1250                    }
1251                    published = Some((version, prepared.value, Vec::new()));
1252                }
1253                PlanTracker::Loaded(loaded) => {
1254                    let mut document = lock(&loaded);
1255                    if !prepared.ops.is_empty() {
1256                        document.tracker.adopt(&prepared)?;
1257                    }
1258                    if document.stored_version < version {
1259                        document.stored_version = version;
1260                    }
1261                    if let Some(StorageWrite::DocumentChange { content, .. }) = &plan.content {
1262                        match content {
1263                            DocumentContent::Base { .. } => document.deltas_since_base = 0,
1264                            DocumentContent::Delta { .. } => document.deltas_since_base += 1,
1265                        }
1266                    }
1267                    published = Some((version, prepared.value, prepared.ops));
1268                }
1269            }
1270        }
1271        if plan.retire {
1272            if committed {
1273                let mut documents = lock(&inner.documents);
1274                if documents
1275                    .get(&plan.address_id)
1276                    .is_some_and(|loaded| lock(loaded).record.identity.id == record.identity.id)
1277                {
1278                    documents.remove(&plan.address_id);
1279                }
1280            }
1281            publications.push(CommitChange::Document {
1282                record,
1283                conversation_id: plan.conversation_id,
1284                version: None,
1285                value: None,
1286                ops: Vec::new(),
1287            });
1288        } else if let Some(StorageWrite::DocumentCopy { source, .. }) = plan.content {
1289            let conversation_id = plan.conversation_id.expect("copies are conversation documents");
1290            publications.push(CommitChange::DocumentCopy {
1291                record,
1292                conversation_id,
1293                source,
1294            });
1295        } else if let Some((version, value, ops)) = published
1296            && publishes
1297        {
1298            publications.push(CommitChange::Document {
1299                record,
1300                conversation_id: plan.conversation_id,
1301                version: Some(version),
1302                value: Some(value),
1303                ops,
1304            });
1305        }
1306    }
1307    Ok(publications)
1308}