1use chord_delta::Op;
4use serde::{Deserialize, Deserializer, Serialize, Serializer};
5use serde_json::{Map, Value};
6
7pub type JsonObject = Map<String, Value>;
9
10pub 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 Seq,
30);
31
32pub const ROOT_CONVERSATION_ID: ConversationId = ConversationId(1);
34
35pub const MAX_SAFE_ID: u64 = (1 << 53) - 1;
37
38fn 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 #[serde(default, skip_serializing_if = "Option::is_none")]
53 pub parent: Option<ConversationParent>,
54 #[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#[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#[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#[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#[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 pub kind: String,
192 pub version: u64,
193 pub input: Value,
194 #[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 #[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#[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 #[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#[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#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
282pub struct DocumentCreate {
283 pub id: DocumentId,
285 pub kind: String,
286 #[serde(default, skip_serializing_if = "Option::is_none")]
288 pub key: Option<String>,
289 pub scope: DocumentScope,
290 #[serde(default, skip_serializing_if = "Option::is_none")]
292 pub history: Option<DocumentHistory>,
293 #[serde(default, skip_serializing_if = "Option::is_none")]
295 pub fork: Option<DocumentFork>,
296}
297
298impl DocumentCreate {
299 pub fn is_current_only(&self) -> bool {
301 !matches!(self.scope, DocumentScope::Conversation { .. }) || self.history == Some(DocumentHistory::Latest)
302 }
303}
304
305#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
307#[serde(rename_all = "camelCase")]
308pub struct DocumentRecord {
309 #[serde(flatten)]
310 pub identity: DocumentCreate,
311 pub created_at: Seq,
313 #[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#[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#[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#[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#[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 #[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#[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 pub order: Option<ScanOrder>,
454}
455
456#[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 #[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#[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#[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#[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#[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#[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 pub deltas_since_base: usize,
534}