Skip to main content

type_bridge_migration/
spec.rs

1//! Serde migration specification types.
2
3use serde::{Deserialize, Serialize};
4use type_bridge_orm::_schema::info::{
5    AttributeSchemaEntry, EntitySchemaEntry, OwnedAttributeEntry, RelationSchemaEntry, RoleEntry,
6    SchemaInfo,
7};
8
9/// Reference to a migration that must be ordered before another migration.
10#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
11pub struct MigrationDependencySpec {
12    /// Application or migration package label.
13    pub app_label: String,
14    /// Migration file stem, such as `0001_initial`.
15    pub migration_name: String,
16}
17
18/// One migration lowered from the Python authoring API.
19#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
20pub struct MigrationSpec {
21    /// Application or migration package label.
22    pub app_label: String,
23    /// Migration file stem, such as `0001_initial`.
24    pub name: String,
25    /// Ordered dependency references.
26    #[serde(default)]
27    pub dependencies: Vec<MigrationDependencySpec>,
28    /// Ordered operations in this migration.
29    #[serde(default)]
30    pub operations: Vec<OperationSpec>,
31    /// Optional loader checksum for later drift detection.
32    #[serde(default)]
33    pub checksum: Option<String>,
34    /// Optional exact raw Python-source digest for locale-independent drift checks.
35    #[serde(default, skip_serializing_if = "Option::is_none")]
36    pub source_sha256: Option<String>,
37    /// Whether the migration is declared reversible by Python.
38    pub reversible: bool,
39}
40
41/// Ordered migration container.
42///
43/// Full graph validation is deliberately left to sub-plan 04.
44#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
45pub struct MigrationGraph {
46    /// Migrations in discovery order.
47    pub migrations: Vec<MigrationSpec>,
48}
49
50/// Operation variants covering the frozen Python `ops.*` authoring surface.
51#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
52#[serde(tag = "kind", rename_all = "snake_case")]
53pub enum OperationSpec {
54    /// Define the complete schema for a model-based initial migration.
55    DefineSchema {
56        /// Complete model schema.
57        schema: SchemaInfo,
58    },
59    /// Add a standalone attribute type.
60    AddAttribute {
61        /// Attribute schema payload.
62        attribute: AttributeSchemaEntry,
63    },
64    /// Remove a standalone attribute type.
65    RemoveAttribute {
66        /// Attribute type name.
67        attr_name: String,
68    },
69    /// Add an entity type.
70    AddEntity {
71        /// Entity schema payload.
72        entity: EntitySchemaEntry,
73    },
74    /// Remove an entity type.
75    RemoveEntity {
76        /// Entity type name.
77        type_name: String,
78    },
79    /// Add a relation type.
80    AddRelation {
81        /// Relation schema payload.
82        relation: RelationSchemaEntry,
83    },
84    /// Remove a relation type.
85    RemoveRelation {
86        /// Relation type name.
87        type_name: String,
88    },
89    /// Add attribute ownership to an entity or relation.
90    AddOwnership {
91        /// Owning entity or relation type name.
92        owner_type: String,
93        /// Owned attribute payload.
94        attribute: OwnedAttributeEntry,
95    },
96    /// Remove attribute ownership from an entity or relation.
97    RemoveOwnership {
98        /// Owning entity or relation type name.
99        owner_type: String,
100        /// Attribute type name.
101        attr_name: String,
102    },
103    /// Modify ownership annotations.
104    ModifyOwnership {
105        /// Owning entity or relation type name.
106        owner_type: String,
107        /// Attribute type name.
108        attr_name: String,
109        /// Previous annotations as authored by Python.
110        old_annotations: String,
111        /// New annotations as authored by Python.
112        new_annotations: String,
113    },
114    /// Modify `@doc`/`@meta` annotations on an entity, relation, or attribute
115    /// type (TypeDB 3.12+).
116    ModifyTypeAnnotations {
117        /// Type name (entity, relation, or attribute type).
118        type_name: String,
119        /// Previous `@doc` value.
120        #[serde(default)]
121        old_doc: Option<String>,
122        /// New `@doc` value.
123        #[serde(default)]
124        new_doc: Option<String>,
125        /// Previous `@meta` annotations, keyed by meta key.
126        #[serde(default)]
127        old_meta: std::collections::BTreeMap<String, String>,
128        /// New `@meta` annotations, keyed by meta key.
129        #[serde(default)]
130        new_meta: std::collections::BTreeMap<String, String>,
131    },
132    /// Modify `@doc`/`@meta` annotations on a relation role (TypeDB 3.12+).
133    ModifyRoleAnnotations {
134        /// Relation type name.
135        relation_type: String,
136        /// Role name.
137        role_name: String,
138        /// Previous `@doc` value.
139        #[serde(default)]
140        old_doc: Option<String>,
141        /// New `@doc` value.
142        #[serde(default)]
143        new_doc: Option<String>,
144        /// Previous `@meta` annotations, keyed by meta key.
145        #[serde(default)]
146        old_meta: std::collections::BTreeMap<String, String>,
147        /// New `@meta` annotations, keyed by meta key.
148        #[serde(default)]
149        new_meta: std::collections::BTreeMap<String, String>,
150    },
151    /// Add a role to a relation.
152    /// Parent ordering is checked from graph declarations, otherwise inferred from the child.
153    AddRole {
154        /// Relation type name.
155        relation_type: String,
156        /// Role payload.
157        role: RoleEntry,
158    },
159    /// Remove a role from a relation.
160    RemoveRole {
161        /// Relation type name.
162        relation_type: String,
163        /// Role name.
164        role_name: String,
165    },
166    /// Add a player type to a role.
167    AddRolePlayer {
168        /// Relation type name.
169        relation_type: String,
170        /// Role name.
171        role_name: String,
172        /// Player type name.
173        player_type_name: String,
174    },
175    /// Remove a player type from a role.
176    RemoveRolePlayer {
177        /// Relation type name.
178        relation_type: String,
179        /// Role name.
180        role_name: String,
181        /// Player type name.
182        player_type_name: String,
183    },
184    /// Execute authored TypeQL without interpreting it in this sub-plan.
185    RunTypeql {
186        /// Forward TypeQL text.
187        forward: String,
188        /// Optional rollback TypeQL text.
189        #[serde(default)]
190        reverse: Option<String>,
191    },
192    /// Rename an attribute type.
193    RenameAttribute {
194        /// Previous attribute type name.
195        old_name: String,
196        /// New attribute type name.
197        new_name: String,
198        /// TypeDB value type.
199        value_type: String,
200    },
201    /// Copy an attribute from source to dest on every instance of the owner type.
202    ///
203    /// This is a DML (write-typed) backfill operation — it inserts attribute values, not
204    /// schema.  The forward TypeQL is an insert-if-absent backfill; the reverse deletes the
205    /// destination attribute.
206    ///
207    /// Two wire forms exist. The lowered form carries only `forward`/`reverse`
208    /// TypeQL (what `.py` execution lowers to); the structured form carries
209    /// `owner`/`source`/`dest`(/`filter`) and lets the authoring core
210    /// synthesize the TypeQL via [`copy_attribute_typeql`] and render a
211    /// faithful `ops.CopyAttribute(...)` in the generated `.py`. Sidecars
212    /// written by the authoring core always carry the synthesized strings, so
213    /// the executor keeps running carried TypeQL.
214    CopyAttribute {
215        /// Owner type label (structured portable form).
216        #[serde(default, skip_serializing_if = "Option::is_none")]
217        owner: Option<String>,
218        /// Source attribute label (structured portable form).
219        #[serde(default, skip_serializing_if = "Option::is_none")]
220        source: Option<String>,
221        /// Destination attribute label (structured portable form).
222        #[serde(default, skip_serializing_if = "Option::is_none")]
223        dest: Option<String>,
224        /// Optional extra match constraint line (structured portable form).
225        #[serde(default, skip_serializing_if = "Option::is_none")]
226        filter: Option<String>,
227        /// Forward backfill TypeQL. Absent only in the structured form before
228        /// normalization; the executor derives its count queries from this
229        /// string's match clause.
230        #[serde(default, skip_serializing_if = "Option::is_none")]
231        forward: Option<String>,
232        /// Reverse (rollback) TypeQL from `to_rollback_typeql()`, or `None` when
233        /// the migration is irreversible.
234        #[serde(default)]
235        reverse: Option<String>,
236    },
237}
238
239/// Resolve the executable forward/reverse TypeQL of a `copy_attribute` op.
240///
241/// Carried TypeQL wins when present (it is the frozen Python
242/// `CopyAttribute.to_typeql()` output); otherwise the structured
243/// `owner`/`source`/`dest` fields synthesize it through the official AST.
244/// New synthesis preserves the released query meaning; carried text stays exact.
245///
246/// # Errors
247///
248/// [`crate::error::MigrationError::AuthoringInput`] when neither the carried
249/// TypeQL nor the complete structured form is present.
250pub fn copy_attribute_typeql(op: &OperationSpec) -> crate::Result<(String, Option<String>)> {
251    let OperationSpec::CopyAttribute {
252        owner,
253        source,
254        dest,
255        filter,
256        forward,
257        reverse,
258    } = op
259    else {
260        return Err(crate::error::MigrationError::AuthoringInput {
261            message: "copy_attribute_typeql called on a non-copy_attribute operation".to_string(),
262        });
263    };
264    if let Some(forward) = forward {
265        return Ok((forward.clone(), reverse.clone()));
266    }
267    let (Some(owner), Some(source), Some(dest)) = (owner, source, dest) else {
268        return Err(crate::error::MigrationError::AuthoringInput {
269            message: "copy_attribute requires either forward TypeQL or the structured \
270                      owner/source/dest fields"
271                .to_string(),
272        });
273    };
274    use type_bridge_core_lib::__internal as tql;
275    let mut patterns = vec![
276        tql::thing(
277            "x",
278            vec![tql::isa(owner, false)?, tql::has(source, tql::var("v")?)?],
279        )?,
280        tql::not(vec![tql::thing(
281            "x",
282            vec![tql::has(dest, tql::var("d")?)?],
283        )?]),
284    ];
285    if let Some(filter) = filter {
286        patterns.extend(tql::parse_patterns(filter)?);
287    }
288    let synthesized_forward = tql::render(&tql::pipeline(vec![
289        tql::match_stage(patterns),
290        tql::insert(vec![tql::thing(
291            "x",
292            vec![tql::has_comparison(dest, "==", tql::var("v")?)?],
293        )?]),
294    ]))?;
295    let synthesized_reverse = tql::render(&tql::pipeline(vec![
296        tql::match_stage(vec![tql::thing(
297            "x",
298            vec![tql::isa(owner, false)?, tql::has(dest, tql::var("v")?)?],
299        )?]),
300        tql::delete(vec![tql::delete_has("x", "v")?]),
301    ]))?;
302    Ok((
303        synthesized_forward,
304        Some(reverse.clone().unwrap_or(synthesized_reverse)),
305    ))
306}
307
308impl OperationSpec {
309    /// Return the operation with any structured `copy_attribute` filled in
310    /// with its synthesized executable TypeQL. Other variants pass through.
311    ///
312    /// # Errors
313    ///
314    /// [`crate::error::MigrationError::AuthoringInput`] when a
315    /// `copy_attribute` carries neither TypeQL nor the structured fields.
316    pub fn normalized(self) -> crate::Result<OperationSpec> {
317        if !matches!(self, OperationSpec::CopyAttribute { .. }) {
318            return Ok(self);
319        }
320        let (forward, reverse) = copy_attribute_typeql(&self)?;
321        let OperationSpec::CopyAttribute {
322            owner,
323            source,
324            dest,
325            filter,
326            ..
327        } = self
328        else {
329            unreachable!("guarded by the matches! check above");
330        };
331        Ok(OperationSpec::CopyAttribute {
332            owner,
333            source,
334            dest,
335            filter,
336            forward: Some(forward),
337            reverse,
338        })
339    }
340}
341
342#[cfg(test)]
343mod tests {
344    use std::collections::BTreeMap;
345
346    use super::*;
347    use type_bridge_orm::_entity::Annotation;
348    use type_bridge_orm::ValueType;
349
350    fn attribute(name: &str) -> AttributeSchemaEntry {
351        AttributeSchemaEntry::new(name, ValueType::String)
352    }
353
354    fn schema() -> SchemaInfo {
355        let mut schema = SchemaInfo::default();
356        schema
357            .attributes
358            .insert("name".to_string(), attribute("name"));
359        schema.entities.insert(
360            "person".to_string(),
361            EntitySchemaEntry {
362                type_name: "person".to_string(),
363                is_abstract: false,
364                parent_type: None,
365                owned_attributes: vec![OwnedAttributeEntry {
366                    attr_name: "name".to_string(),
367                    value_type: ValueType::String,
368                    annotations: vec![Annotation::Key],
369                    is_ordered: false,
370                    doc: None,
371                    meta: Default::default(),
372                }],
373                plays_cardinalities: BTreeMap::new(),
374                doc: None,
375                meta: Default::default(),
376            },
377        );
378        schema
379    }
380
381    #[test]
382    fn define_schema_operation_round_trips_json() {
383        let operation = OperationSpec::DefineSchema { schema: schema() };
384
385        let json = serde_json::to_string(&operation).unwrap();
386        assert!(json.contains("\"kind\":\"define_schema\""));
387
388        let parsed: OperationSpec = serde_json::from_str(&json).unwrap();
389        assert_eq!(parsed, operation);
390    }
391
392    #[test]
393    fn schema_bearing_operation_round_trips_json() {
394        let operation = OperationSpec::AddOwnership {
395            owner_type: "person".to_string(),
396            attribute: OwnedAttributeEntry {
397                attr_name: "name".to_string(),
398                value_type: ValueType::String,
399                annotations: vec![Annotation::Key],
400                is_ordered: false,
401                doc: None,
402                meta: Default::default(),
403            },
404        };
405
406        let parsed: OperationSpec =
407            serde_json::from_str(&serde_json::to_string(&operation).unwrap()).unwrap();
408
409        assert_eq!(parsed, operation);
410    }
411
412    #[test]
413    fn run_typeql_operation_round_trips_json() {
414        let operation = OperationSpec::RunTypeql {
415            forward: "define attribute nickname, value string;".to_string(),
416            reverse: Some("undefine attribute nickname;".to_string()),
417        };
418
419        let json = serde_json::to_value(&operation).unwrap();
420        assert_eq!(json["kind"], "run_typeql");
421
422        let parsed: OperationSpec = serde_json::from_value(json).unwrap();
423        assert_eq!(parsed, operation);
424    }
425
426    fn lowered_copy_attribute(forward: &str, reverse: Option<&str>) -> OperationSpec {
427        OperationSpec::CopyAttribute {
428            owner: None,
429            source: None,
430            dest: None,
431            filter: None,
432            forward: Some(forward.to_string()),
433            reverse: reverse.map(str::to_string),
434        }
435    }
436
437    fn structured_copy_attribute(filter: Option<&str>) -> OperationSpec {
438        OperationSpec::CopyAttribute {
439            owner: Some("person".to_string()),
440            source: Some("old-name".to_string()),
441            dest: Some("new-name".to_string()),
442            filter: filter.map(str::to_string),
443            forward: None,
444            reverse: None,
445        }
446    }
447
448    #[test]
449    fn copy_attribute_operation_round_trips_json() {
450        let operation = lowered_copy_attribute(
451            "match\n  $x isa person, has old-name $v;\n  not { $x has new-name $d; };\ninsert\n  $x has new-name == $v;",
452            Some("match $x isa person, has new-name $v;\ndelete $v of $x;"),
453        );
454
455        let json = serde_json::to_value(&operation).unwrap();
456        assert_eq!(json["kind"], "copy_attribute");
457        assert!(
458            json["forward"]
459                .as_str()
460                .unwrap()
461                .contains("has new-name == $v")
462        );
463        // Absent structured fields stay off the wire so the lowered form
464        // serializes exactly as it did before the structured form existed.
465        assert!(json.get("owner").is_none());
466
467        let parsed: OperationSpec = serde_json::from_value(json).unwrap();
468        assert_eq!(parsed, operation);
469    }
470
471    #[test]
472    fn copy_attribute_without_reverse_round_trips_json() {
473        let operation = lowered_copy_attribute(
474            "match\n  $x isa company, has legacy-id $v;\n  not { $x has new-id $d; };\ninsert\n  $x has new-id == $v;",
475            None,
476        );
477
478        let json = serde_json::to_value(&operation).unwrap();
479        assert_eq!(json["kind"], "copy_attribute");
480        // reverse is None → omitted (serde default).
481
482        let parsed: OperationSpec = serde_json::from_value(json).unwrap();
483        assert_eq!(parsed, operation);
484    }
485
486    #[test]
487    fn legacy_copy_attribute_sidecar_json_still_parses() {
488        // Sidecars written before the structured form carry only the TypeQL.
489        let json = r#"{"kind":"copy_attribute","forward":"match ...;","reverse":null}"#;
490
491        let parsed: OperationSpec = serde_json::from_str(json).unwrap();
492        assert_eq!(parsed, lowered_copy_attribute("match ...;", None));
493    }
494
495    #[test]
496    fn structured_copy_attribute_round_trips_json() {
497        let operation = structured_copy_attribute(Some("$x has age $a;"));
498
499        let json = serde_json::to_value(&operation).unwrap();
500        assert_eq!(json["kind"], "copy_attribute");
501        assert_eq!(json["owner"], "person");
502        assert!(json.get("forward").is_none());
503
504        let parsed: OperationSpec = serde_json::from_value(json).unwrap();
505        assert_eq!(parsed, operation);
506    }
507
508    #[test]
509    fn structured_copy_attribute_synthesizes_python_shaped_typeql() {
510        let (forward, reverse) = copy_attribute_typeql(&structured_copy_attribute(None)).unwrap();
511
512        assert_typeql_eq!(
513            forward,
514            "match\n  $x isa person, has old-name $v;\n  not { $x has new-name $d; };\ninsert\n  $x has new-name == $v;"
515        );
516        assert_typeql_eq!(
517            reverse.as_deref(),
518            Some("match $x isa person, has new-name $v;\ndelete $v of $x;")
519        );
520    }
521
522    #[test]
523    fn structured_copy_attribute_synthesizes_filter_line() {
524        // The template appends the terminating `;`, mirroring the Python
525        // `CopyAttribute.to_typeql()` filter line.
526        let (forward, _) =
527            copy_attribute_typeql(&structured_copy_attribute(Some("$x has age $a"))).unwrap();
528
529        assert_typeql_eq!(
530            forward,
531            "match\n  $x isa person, has old-name $v;\n  not { $x has new-name $d; };\n  $x has age $a;\ninsert\n  $x has new-name == $v;"
532        );
533    }
534
535    #[test]
536    fn carried_typeql_wins_over_structured_fields() {
537        let operation = OperationSpec::CopyAttribute {
538            owner: Some("person".to_string()),
539            source: Some("old-name".to_string()),
540            dest: Some("new-name".to_string()),
541            filter: None,
542            forward: Some("match carried;".to_string()),
543            reverse: Some("match carried-reverse;".to_string()),
544        };
545
546        let (forward, reverse) = copy_attribute_typeql(&operation).unwrap();
547        assert_eq!(forward, "match carried;");
548        assert_eq!(reverse.as_deref(), Some("match carried-reverse;"));
549    }
550
551    #[test]
552    fn copy_attribute_without_typeql_or_fields_is_rejected() {
553        let operation = OperationSpec::CopyAttribute {
554            owner: Some("person".to_string()),
555            source: None,
556            dest: Some("new-name".to_string()),
557            filter: None,
558            forward: None,
559            reverse: None,
560        };
561
562        let error = copy_attribute_typeql(&operation).unwrap_err();
563        assert!(matches!(
564            error,
565            crate::error::MigrationError::AuthoringInput { .. }
566        ));
567    }
568
569    #[test]
570    fn normalized_fills_structured_copy_attribute_and_passes_others_through() {
571        let normalized = structured_copy_attribute(None).normalized().unwrap();
572        let OperationSpec::CopyAttribute {
573            owner,
574            forward,
575            reverse,
576            ..
577        } = &normalized
578        else {
579            panic!("normalized must stay a copy_attribute");
580        };
581        assert_eq!(owner.as_deref(), Some("person"));
582        assert!(forward.as_deref().unwrap().contains("has new-name == $v"));
583        assert!(reverse.as_deref().unwrap().contains("delete has $v of $x"));
584
585        let passthrough = OperationSpec::RunTypeql {
586            forward: "match $x isa person;".to_string(),
587            reverse: None,
588        };
589        assert_eq!(passthrough.clone().normalized().unwrap(), passthrough);
590    }
591
592    #[test]
593    fn graph_preserves_spec_order() {
594        let graph = MigrationGraph {
595            migrations: vec![
596                MigrationSpec {
597                    app_label: "app".to_string(),
598                    name: "0001_initial".to_string(),
599                    dependencies: vec![],
600                    operations: vec![OperationSpec::DefineSchema { schema: schema() }],
601                    checksum: Some("aaa".to_string()),
602                    source_sha256: None,
603                    reversible: true,
604                },
605                MigrationSpec {
606                    app_label: "app".to_string(),
607                    name: "0002_custom".to_string(),
608                    dependencies: vec![MigrationDependencySpec {
609                        app_label: "app".to_string(),
610                        migration_name: "0001_initial".to_string(),
611                    }],
612                    operations: vec![OperationSpec::RunTypeql {
613                        forward: "define attribute nickname, value string;".to_string(),
614                        reverse: None,
615                    }],
616                    checksum: Some("bbb".to_string()),
617                    source_sha256: None,
618                    reversible: false,
619                },
620            ],
621        };
622
623        let parsed: MigrationGraph =
624            serde_json::from_str(&serde_json::to_string(&graph).unwrap()).unwrap();
625
626        assert_eq!(parsed.migrations[0].name, "0001_initial");
627        assert_eq!(parsed.migrations[1].name, "0002_custom");
628        assert_eq!(parsed, graph);
629    }
630
631    #[test]
632    fn absent_raw_digest_preserves_the_legacy_sidecar_wire_shape() {
633        let spec = MigrationSpec {
634            app_label: "app".to_string(),
635            name: "0001_initial".to_string(),
636            dependencies: vec![],
637            operations: vec![],
638            checksum: Some("aaa".to_string()),
639            source_sha256: None,
640            reversible: true,
641        };
642
643        assert_eq!(
644            serde_json::to_string(&spec).unwrap(),
645            r#"{"app_label":"app","name":"0001_initial","dependencies":[],"operations":[],"checksum":"aaa","reversible":true}"#,
646        );
647    }
648
649    #[test]
650    fn annotation_operations_round_trip_json() {
651        let operations = vec![
652            OperationSpec::ModifyTypeAnnotations {
653                type_name: "person".to_string(),
654                old_doc: None,
655                new_doc: Some("A person.".to_string()),
656                old_meta: BTreeMap::new(),
657                new_meta: BTreeMap::from([("owner".to_string(), "core".to_string())]),
658            },
659            OperationSpec::ModifyRoleAnnotations {
660                relation_type: "employment".to_string(),
661                role_name: "employee".to_string(),
662                old_doc: Some("old".to_string()),
663                new_doc: None,
664                old_meta: BTreeMap::new(),
665                new_meta: BTreeMap::new(),
666            },
667        ];
668        for operation in operations {
669            let json = serde_json::to_string(&operation).expect("serialize");
670            let back: OperationSpec = serde_json::from_str(&json).expect("deserialize");
671            assert_eq!(back, operation);
672        }
673        // Kind tags follow the snake_case convention of the frozen surface.
674        let json = serde_json::to_string(&OperationSpec::ModifyTypeAnnotations {
675            type_name: "person".to_string(),
676            old_doc: None,
677            new_doc: None,
678            old_meta: BTreeMap::new(),
679            new_meta: BTreeMap::new(),
680        })
681        .expect("serialize");
682        assert!(json.contains("\"kind\":\"modify_type_annotations\""));
683    }
684}