Skip to main content

durable/
records.rs

1//! Durable record, write, and query shapes. Field names and tags serialize exactly as upstream `types.ts`.
2
3use chord_delta::Op;
4use serde::{Deserialize, Deserializer, Serialize, Serializer};
5use serde_json::{Map, Value};
6
7/// JSON object used as the root of every durable document.
8pub type JsonObject = Map<String, Value>;
9
10/// Backend-owned continuation state that callers only round-trip to the same scan.
11pub type Cursor = JsonObject;
12
13macro_rules! id_types {
14    ($($(#[$doc:meta])* $name:ident),* $(,)?) => {$(
15        $(#[$doc])*
16        #[derive(Clone, Copy, Debug, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize)]
17        #[serde(transparent)]
18        pub struct $name(pub u64);
19    )*};
20}
21
22id_types!(
23    ConversationId,
24    EntryId,
25    TaskId,
26    SubmissionId,
27    DocumentId,
28    /// Strictly increasing sequence of one atomic storage commit; gaps are permitted.
29    Seq,
30);
31
32/// The root conversation always uses this reserved ID.
33pub const ROOT_CONVERSATION_ID: ConversationId = ConversationId(1);
34
35/// Largest ID a JavaScript number holds exactly; minting stops past it so IDs stay interchangeable with upstream.
36pub const MAX_SAFE_ID: u64 = (1 << 53) - 1;
37
38/// `Some(value)` for a present field, `null` included: `data: null` is a stored value, not an absent one.
39fn present<'de, D: Deserializer<'de>>(deserializer: D) -> Result<Option<Value>, D::Error> {
40    Value::deserialize(deserializer).map(Some)
41}
42
43fn is_false(value: &bool) -> bool {
44    !value
45}
46
47#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
48#[serde(rename_all = "camelCase", deny_unknown_fields)]
49pub struct ConversationRecord {
50    pub id: ConversationId,
51    /// Fork source and inclusive parent entry through which history is inherited.
52    #[serde(default, skip_serializing_if = "Option::is_none")]
53    pub parent: Option<ConversationParent>,
54    /// Creator edge used for attribution, subtree abort, and subtree idle waits.
55    #[serde(default, skip_serializing_if = "Option::is_none")]
56    pub owner: Option<ConversationOwner>,
57}
58
59#[derive(Clone, Copy, Debug, PartialEq, Serialize, Deserialize)]
60#[serde(rename_all = "camelCase", deny_unknown_fields)]
61pub struct ConversationParent {
62    pub conversation_id: ConversationId,
63    pub at: EntryId,
64}
65
66#[derive(Clone, Copy, Debug, PartialEq, Serialize, Deserialize)]
67#[serde(rename_all = "camelCase", deny_unknown_fields)]
68pub struct ConversationOwner {
69    pub conversation_id: ConversationId,
70    pub task_id: TaskId,
71}
72
73/// Immutable transcript event. `model` and `edits` stay JSON until the message model is ported (phase 4).
74#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
75#[serde(rename_all = "camelCase", deny_unknown_fields)]
76pub struct EntryRecord {
77    pub id: EntryId,
78    pub conversation_id: ConversationId,
79    pub kind: String,
80    #[serde(default, skip_serializing_if = "Option::is_none")]
81    pub model: Option<Vec<Value>>,
82    #[serde(default, deserialize_with = "present", skip_serializing_if = "Option::is_none")]
83    pub data: Option<Value>,
84    #[serde(default, skip_serializing_if = "Option::is_none")]
85    pub head: Option<EntryId>,
86    #[serde(default, skip_serializing_if = "Option::is_none")]
87    pub edits: Option<Vec<Value>>,
88    #[serde(default, skip_serializing_if = "Option::is_none")]
89    pub by_task_id: Option<TaskId>,
90}
91
92#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
93#[serde(rename_all = "camelCase")]
94pub enum TaskStatus {
95    Pending,
96    Running,
97    Waiting,
98    Completing,
99    Terminal,
100}
101
102#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
103#[serde(rename_all = "camelCase")]
104pub enum JoinPolicy {
105    FailFast,
106    AllSettled,
107}
108
109/// Complete durable execution state of a task.
110#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
111#[serde(tag = "status", rename_all = "camelCase", deny_unknown_fields)]
112pub enum TaskState {
113    Pending {
114        checkpoint: Value,
115    },
116    Running {
117        checkpoint: Value,
118    },
119    Waiting {
120        checkpoint: Value,
121        on: Vec<TaskId>,
122        policy: JoinPolicy,
123    },
124    Completing {
125        outcome: TaskOutcome,
126    },
127    Terminal {
128        outcome: TaskOutcome,
129    },
130}
131
132impl TaskState {
133    pub fn status(&self) -> TaskStatus {
134        match self {
135            TaskState::Pending { .. } => TaskStatus::Pending,
136            TaskState::Running { .. } => TaskStatus::Running,
137            TaskState::Waiting { .. } => TaskStatus::Waiting,
138            TaskState::Completing { .. } => TaskStatus::Completing,
139            TaskState::Terminal { .. } => TaskStatus::Terminal,
140        }
141    }
142}
143
144/// Durable reason and optional result recorded when a task becomes terminal.
145#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
146#[serde(tag = "status", rename_all = "camelCase", deny_unknown_fields)]
147pub enum TaskOutcome {
148    Completed {
149        result: Value,
150    },
151    Failed {
152        error: TaskOutcomeError,
153        #[serde(default, deserialize_with = "present", skip_serializing_if = "Option::is_none")]
154        result: Option<Value>,
155    },
156    Aborted {
157        #[serde(default, skip_serializing_if = "Option::is_none")]
158        reason: Option<String>,
159        #[serde(default, deserialize_with = "present", skip_serializing_if = "Option::is_none")]
160        result: Option<Value>,
161    },
162    Orphaned {
163        reason: String,
164    },
165    Faulted {
166        error: TaskOutcomeError,
167    },
168}
169
170#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
171#[serde(deny_unknown_fields)]
172pub struct TaskOutcomeError {
173    pub message: String,
174    #[serde(default, deserialize_with = "present", skip_serializing_if = "Option::is_none")]
175    pub detail: Option<Value>,
176}
177
178#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
179#[serde(rename_all = "camelCase")]
180pub enum AbortReason {
181    Restart,
182}
183
184/// Complete replacement record for one durable task state machine.
185#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
186#[serde(rename_all = "camelCase", deny_unknown_fields)]
187pub struct TaskRecord {
188    pub id: TaskId,
189    pub conversation_id: ConversationId,
190    /// Registered task definition name.
191    pub kind: String,
192    pub version: u64,
193    pub input: Value,
194    /// Owning task of a child task; absent for a task its conversation owns.
195    #[serde(default, skip_serializing_if = "Option::is_none")]
196    pub owner: Option<TaskId>,
197    pub background: bool,
198    pub abort_requested: bool,
199    #[serde(default, skip_serializing_if = "Option::is_none")]
200    pub abort_reason: Option<AbortReason>,
201    #[serde(default, skip_serializing_if = "is_false")]
202    pub abandon_on_restart: bool,
203    #[serde(default, skip_serializing_if = "Option::is_none")]
204    pub started_at: Option<u64>,
205    #[serde(default, skip_serializing_if = "Option::is_none")]
206    pub ended_at: Option<u64>,
207    pub state: TaskState,
208    /// Small first-writer-wins values retained while the task can run.
209    #[serde(default, skip_serializing_if = "Option::is_none")]
210    pub memos: Option<JsonObject>,
211}
212
213#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
214#[serde(rename_all = "camelCase")]
215pub enum SubmissionType {
216    Input,
217    Write,
218}
219
220#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
221#[serde(rename_all = "camelCase")]
222pub enum SubmissionStatus {
223    Queued,
224    Placed,
225    Done,
226    Unanswered,
227}
228
229/// Durable lifecycle of one admitted user input or passive entry write. The Session supplies valid transitions.
230#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
231#[serde(rename_all = "camelCase", deny_unknown_fields)]
232pub struct SubmissionRecord {
233    pub id: SubmissionId,
234    pub conversation_id: ConversationId,
235    /// Host-provided deduplication key, scoped to the conversation.
236    #[serde(default, skip_serializing_if = "Option::is_none")]
237    pub request_id: Option<String>,
238    #[serde(rename = "type")]
239    pub kind: SubmissionType,
240    pub status: SubmissionStatus,
241    #[serde(default, skip_serializing_if = "Option::is_none")]
242    pub entry: Option<EntryId>,
243    #[serde(default, skip_serializing_if = "Option::is_none")]
244    pub answer: Option<EntryId>,
245    #[serde(default, skip_serializing_if = "Option::is_none")]
246    pub reason: Option<String>,
247    #[serde(default, deserialize_with = "present", skip_serializing_if = "Option::is_none")]
248    pub detail: Option<Value>,
249}
250
251/// Who owns a document.
252#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
253#[serde(
254    tag = "kind",
255    rename_all = "camelCase",
256    rename_all_fields = "camelCase",
257    deny_unknown_fields
258)]
259pub enum DocumentScope {
260    Session,
261    Conversation { conversation_id: ConversationId },
262    Task { task_id: TaskId },
263}
264
265#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
266#[serde(rename_all = "camelCase")]
267pub enum DocumentHistory {
268    Latest,
269    Rewindable,
270}
271
272#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
273#[serde(rename_all = "camelCase")]
274pub enum DocumentFork {
275    AsOf,
276    Current,
277    Initial,
278}
279
280/// Fields supplied when storage creates and stamps a new [`DocumentRecord`].
281#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
282pub struct DocumentCreate {
283    /// Unique incarnation ID; never reused when the same logical document is recreated.
284    pub id: DocumentId,
285    pub kind: String,
286    /// Family member key; absent for singleton documents.
287    #[serde(default, skip_serializing_if = "Option::is_none")]
288    pub key: Option<String>,
289    pub scope: DocumentScope,
290    /// Conversation documents only.
291    #[serde(default, skip_serializing_if = "Option::is_none")]
292    pub history: Option<DocumentHistory>,
293    /// Conversation documents only.
294    #[serde(default, skip_serializing_if = "Option::is_none")]
295    pub fork: Option<DocumentFork>,
296}
297
298impl DocumentCreate {
299    /// Session and task documents, and `latest` conversation documents, keep no history.
300    pub fn is_current_only(&self) -> bool {
301        !matches!(self.scope, DocumentScope::Conversation { .. }) || self.history == Some(DocumentHistory::Latest)
302    }
303}
304
305/// Persisted lifecycle record of one create-to-retire document incarnation.
306#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
307#[serde(rename_all = "camelCase")]
308pub struct DocumentRecord {
309    #[serde(flatten)]
310    pub identity: DocumentCreate,
311    /// Commit that created the incarnation.
312    pub created_at: Seq,
313    /// Commit that retired the incarnation; absent while it is current.
314    #[serde(default, skip_serializing_if = "Option::is_none")]
315    pub retired_at: Option<Seq>,
316}
317
318impl DocumentRecord {
319    pub fn is_alive_at(&self, at: DocumentPoint) -> bool {
320        match at {
321            DocumentPoint::Current => self.retired_at.is_none(),
322            DocumentPoint::At(seq) => self.created_at <= seq && self.retired_at.is_none_or(|retired| seq < retired),
323        }
324    }
325}
326
327/// Complete checkpoint or Chord operation batch.
328#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
329#[serde(tag = "kind", rename_all = "camelCase", deny_unknown_fields)]
330pub enum DocumentContent {
331    Base {
332        version: u64,
333        value: JsonObject,
334    },
335    Delta {
336        version: u64,
337        #[serde(serialize_with = "ops_out", deserialize_with = "ops_in")]
338        ops: Vec<Op>,
339    },
340}
341
342impl DocumentContent {
343    pub fn version(&self) -> u64 {
344        match self {
345            DocumentContent::Base { version, .. } | DocumentContent::Delta { version, .. } => *version,
346        }
347    }
348}
349
350fn ops_out<S: Serializer>(ops: &[Op], serializer: S) -> Result<S::Ok, S::Error> {
351    serializer.collect_seq(ops.iter().map(Op::to_json))
352}
353
354fn ops_in<'de, D: Deserializer<'de>>(deserializer: D) -> Result<Vec<Op>, D::Error> {
355    Vec::<Value>::deserialize(deserializer)?
356        .iter()
357        .map(|op| Op::from_json(op).map_err(serde::de::Error::custom))
358        .collect()
359}
360
361/// Current state or one historical commit, for document membership and content reads.
362#[derive(Clone, Copy, Debug, PartialEq, Eq)]
363pub enum DocumentPoint {
364    Current,
365    At(Seq),
366}
367
368impl Serialize for DocumentPoint {
369    fn serialize<S: Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
370        match self {
371            DocumentPoint::Current => serializer.serialize_str("current"),
372            DocumentPoint::At(seq) => seq.serialize(serializer),
373        }
374    }
375}
376
377impl<'de> Deserialize<'de> for DocumentPoint {
378    fn deserialize<D: Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
379        match Value::deserialize(deserializer)? {
380            Value::String(text) if text == "current" => Ok(DocumentPoint::Current),
381            Value::Number(number) if number.as_u64().is_some() => {
382                Ok(DocumentPoint::At(Seq(number.as_u64().unwrap_or(0))))
383            }
384            other => Err(serde::de::Error::custom(format!("invalid document point: {other}"))),
385        }
386    }
387}
388
389/// Exact persisted source of a definition-free document copy.
390#[derive(Clone, Copy, Debug, PartialEq, Serialize, Deserialize)]
391#[serde(deny_unknown_fields)]
392pub struct DocumentCopySource {
393    pub id: DocumentId,
394    pub at: DocumentPoint,
395}
396
397/// One record or document mutation in an atomic storage commit.
398#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
399#[serde(tag = "type", deny_unknown_fields)]
400#[expect(
401    clippy::large_enum_variant,
402    reason = "writes are short-lived batch items; boxing adds an allocation each"
403)]
404pub enum StorageWrite {
405    #[serde(rename = "conversation")]
406    Conversation { value: ConversationRecord },
407    #[serde(rename = "entry")]
408    Entry { value: EntryRecord },
409    #[serde(rename = "task")]
410    Task { value: TaskRecord },
411    #[serde(rename = "submission")]
412    Submission { value: SubmissionRecord },
413    /// `content` must be a base.
414    #[serde(rename = "document.create")]
415    DocumentCreate {
416        record: DocumentCreate,
417        content: DocumentContent,
418    },
419    #[serde(rename = "document.copy")]
420    DocumentCopy {
421        record: DocumentCreate,
422        source: DocumentCopySource,
423    },
424    #[serde(rename = "document.change")]
425    DocumentChange { id: DocumentId, content: DocumentContent },
426    #[serde(rename = "document.retire")]
427    DocumentRetire { id: DocumentId },
428}
429
430/// ID order of a scan: `Ascending` is oldest first.
431#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
432#[serde(rename_all = "camelCase")]
433pub enum ScanOrder {
434    Ascending,
435    Descending,
436}
437
438impl ScanOrder {
439    pub fn as_str(self) -> &'static str {
440        match self {
441            ScanOrder::Ascending => "ascending",
442            ScanOrder::Descending => "descending",
443        }
444    }
445}
446
447#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
448#[serde(rename_all = "camelCase", deny_unknown_fields)]
449pub struct ConversationQuery {
450    pub owner_conversation_id: Option<ConversationId>,
451    pub owner_task_id: Option<TaskId>,
452    /// Default ascending; with a cursor, the cursor's order.
453    pub order: Option<ScanOrder>,
454}
455
456/// Inclusive ID bounds for a scan of one conversation's fork-aware history.
457#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
458#[serde(rename_all = "camelCase", deny_unknown_fields)]
459pub struct EntryQuery {
460    pub conversation_id: ConversationId,
461    #[serde(default)]
462    pub min_entry_id: Option<EntryId>,
463    #[serde(default)]
464    pub max_entry_id: Option<EntryId>,
465    /// Default descending; with a cursor, the cursor's order.
466    #[serde(default)]
467    pub order: Option<ScanOrder>,
468}
469
470#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
471#[serde(rename_all = "camelCase", deny_unknown_fields)]
472pub struct TaskQuery {
473    pub conversation_id: Option<ConversationId>,
474    pub kind: Option<String>,
475    pub status: Option<TaskStatus>,
476    pub abort_requested: Option<bool>,
477    pub background: Option<bool>,
478    pub order: Option<ScanOrder>,
479}
480
481#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
482#[serde(rename_all = "camelCase", deny_unknown_fields)]
483pub struct SubmissionQuery {
484    pub conversation_id: Option<ConversationId>,
485    pub status: Option<SubmissionStatus>,
486    pub order: Option<ScanOrder>,
487}
488
489/// Exact logical identity of a singleton (`key` absent) or one keyed family member.
490#[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
491#[serde(deny_unknown_fields)]
492pub struct DocumentAddress {
493    pub kind: String,
494    pub scope: DocumentScope,
495    #[serde(default)]
496    pub key: Option<String>,
497}
498
499/// Incarnations alive in one exact scope at one point.
500#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
501#[serde(deny_unknown_fields)]
502pub struct DocumentQuery {
503    pub scope: DocumentScope,
504    pub at: DocumentPoint,
505    #[serde(default)]
506    pub kind: Option<String>,
507}
508
509/// One ordered scan result and its optional continuation.
510#[derive(Clone, Debug, PartialEq, Serialize)]
511pub struct Page<T> {
512    pub items: Vec<T>,
513    #[serde(skip_serializing_if = "Option::is_none")]
514    pub next: Option<Cursor>,
515}
516
517/// An entry and the sequence of the commit that persisted it.
518#[derive(Clone, Debug, PartialEq, Serialize)]
519#[serde(rename_all = "camelCase")]
520pub struct StoredEntry {
521    pub entry: EntryRecord,
522    pub commit_seq: Seq,
523}
524
525/// Materialized value and stored definition version at a selected point.
526#[derive(Clone, Debug, PartialEq, Serialize)]
527#[serde(rename_all = "camelCase")]
528pub struct StoredDocument {
529    pub record: DocumentRecord,
530    pub version: u64,
531    pub value: JsonObject,
532    /// Deltas replayed after the selected base to materialize `value`.
533    pub deltas_since_base: usize,
534}