Skip to main content

type_bridge_migration/
plan.rs

1//! Pure migration planner.
2//!
3//! Lowers a validated [`MigrationGraph`] and applied-state into an ordered
4//! [`ExecutionPlan`] of [`ExecutionStep`]s, each carrying its [`TxType`] and
5//! the executable TypeQL to run.  No database connection, no async, no TypeDB
6//! driver is touched here.
7
8use std::collections::BTreeSet;
9
10use serde::{Deserialize, Serialize};
11use type_bridge_core_lib::__internal as tql;
12use type_bridge_orm::_schema::annotations::{
13    AnnotationToken, AnnotationTokenDiff, diff_annotation_tokens, split_annotation_tokens,
14};
15use type_bridge_orm::_schema::info::{
16    AttributeSchemaEntry, EntitySchemaEntry, OwnedAttributeEntry, RelationSchemaEntry, RoleEntry,
17    SchemaInfo,
18};
19use type_bridge_orm::TxType;
20
21use crate::checksum::check_checksum_drift;
22use crate::error::MigrationError;
23use crate::graph::{AppliedMigrationRecord, validate_graph};
24use crate::spec::{MigrationGraph, OperationSpec, copy_attribute_typeql};
25
26/// The kind of execution step, controlling how the executor dispatches it.
27///
28/// `Schema` and `Write` run the carried TypeQL directly.  `Backfill` is a
29/// write-typed step that additionally derives matched/inserted/skipped counts
30/// via bracketing `reduce $c = count;` read queries.
31#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, Default)]
32#[serde(rename_all = "snake_case")]
33pub enum StepKind {
34    /// Schema DDL step — opened under a schema transaction.
35    #[default]
36    Schema,
37    /// Data-write step — opened under a write transaction.
38    Write,
39    /// Backfill step — write transaction + bracketing count derivation.
40    Backfill,
41}
42
43/// Authored operation kind from which an execution step was lowered.
44///
45/// This discriminant is carried separately from [`StepKind`]: `StepKind`
46/// controls transaction dispatch, while `OperationKind` preserves the stable
47/// artifact-level operation identity used by per-step recovery.
48#[derive(
49    Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize, Default,
50)]
51#[serde(rename_all = "snake_case")]
52pub enum OperationKind {
53    /// Arbitrary authored TypeQL.
54    #[default]
55    RunTypeql,
56    /// Define a complete initial schema.
57    DefineSchema,
58    /// Add an attribute type.
59    AddAttribute,
60    /// Remove an attribute type.
61    RemoveAttribute,
62    /// Add an entity type.
63    AddEntity,
64    /// Remove an entity type.
65    RemoveEntity,
66    /// Add a relation type.
67    AddRelation,
68    /// Remove a relation type.
69    RemoveRelation,
70    /// Add an ownership capability.
71    AddOwnership,
72    /// Remove an ownership capability.
73    RemoveOwnership,
74    /// Modify ownership annotations.
75    ModifyOwnership,
76    /// Modify type annotations.
77    ModifyTypeAnnotations,
78    /// Modify role annotations.
79    ModifyRoleAnnotations,
80    /// Add a relation role.
81    AddRole,
82    /// Remove a relation role.
83    RemoveRole,
84    /// Add a role player capability.
85    AddRolePlayer,
86    /// Remove a role player capability.
87    RemoveRolePlayer,
88    /// Rename an attribute type.
89    RenameAttribute,
90    /// Copy attribute values as a backfill.
91    CopyAttribute,
92}
93
94impl OperationKind {
95    /// Stable snake-case token used in deterministic step identities.
96    pub const fn as_str(self) -> &'static str {
97        match self {
98            Self::RunTypeql => "run_typeql",
99            Self::DefineSchema => "define_schema",
100            Self::AddAttribute => "add_attribute",
101            Self::RemoveAttribute => "remove_attribute",
102            Self::AddEntity => "add_entity",
103            Self::RemoveEntity => "remove_entity",
104            Self::AddRelation => "add_relation",
105            Self::RemoveRelation => "remove_relation",
106            Self::AddOwnership => "add_ownership",
107            Self::RemoveOwnership => "remove_ownership",
108            Self::ModifyOwnership => "modify_ownership",
109            Self::ModifyTypeAnnotations => "modify_type_annotations",
110            Self::ModifyRoleAnnotations => "modify_role_annotations",
111            Self::AddRole => "add_role",
112            Self::RemoveRole => "remove_role",
113            Self::AddRolePlayer => "add_role_player",
114            Self::RemoveRolePlayer => "remove_role_player",
115            Self::RenameAttribute => "rename_attribute",
116            Self::CopyAttribute => "copy_attribute",
117        }
118    }
119
120    fn from_spec(operation: &OperationSpec) -> Self {
121        match operation {
122            OperationSpec::RunTypeql { .. } => Self::RunTypeql,
123            OperationSpec::DefineSchema { .. } => Self::DefineSchema,
124            OperationSpec::AddAttribute { .. } => Self::AddAttribute,
125            OperationSpec::RemoveAttribute { .. } => Self::RemoveAttribute,
126            OperationSpec::AddEntity { .. } => Self::AddEntity,
127            OperationSpec::RemoveEntity { .. } => Self::RemoveEntity,
128            OperationSpec::AddRelation { .. } => Self::AddRelation,
129            OperationSpec::RemoveRelation { .. } => Self::RemoveRelation,
130            OperationSpec::AddOwnership { .. } => Self::AddOwnership,
131            OperationSpec::RemoveOwnership { .. } => Self::RemoveOwnership,
132            OperationSpec::ModifyOwnership { .. } => Self::ModifyOwnership,
133            OperationSpec::ModifyTypeAnnotations { .. } => Self::ModifyTypeAnnotations,
134            OperationSpec::ModifyRoleAnnotations { .. } => Self::ModifyRoleAnnotations,
135            OperationSpec::AddRole { .. } => Self::AddRole,
136            OperationSpec::RemoveRole { .. } => Self::RemoveRole,
137            OperationSpec::AddRolePlayer { .. } => Self::AddRolePlayer,
138            OperationSpec::RemoveRolePlayer { .. } => Self::RemoveRolePlayer,
139            OperationSpec::RenameAttribute { .. } => Self::RenameAttribute,
140            OperationSpec::CopyAttribute { .. } => Self::CopyAttribute,
141        }
142    }
143}
144
145/// One executable step within a migration.
146///
147/// Carries the transaction type and the forward (and optional reverse) TypeQL.
148/// Every step maps to exactly one TypeDB transaction.
149#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
150pub struct ExecutionStep {
151    /// Transaction type to open for this step.
152    pub tx_type: TxType,
153    /// Discriminant controlling executor dispatch.
154    ///
155    /// Defaults to [`StepKind::Schema`] for backwards-compatible deserialization
156    /// of steps persisted before this field was introduced.
157    #[serde(default)]
158    pub kind: StepKind,
159    /// Artifact operation kind that produced this step.
160    ///
161    /// Defaults to [`OperationKind::RunTypeql`] when deserializing legacy
162    /// persisted plans that predate per-step recovery metadata.
163    #[serde(default)]
164    pub operation_kind: OperationKind,
165    /// Forward (apply) TypeQL text.
166    pub forward: String,
167    /// Reverse (rollback) TypeQL text, or `None` when the step is
168    /// non-reversible.
169    pub reverse: Option<String>,
170}
171
172/// Whether a migration execution is an apply or a rollback.
173#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
174#[serde(rename_all = "snake_case")]
175pub enum MigrationAction {
176    /// Apply the migration forward.
177    Apply,
178    /// Roll the migration back.
179    Rollback,
180}
181
182/// One migration scheduled for execution, together with its assembled steps.
183#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
184pub struct MigrationExecution {
185    /// Application or migration package label.
186    pub app_label: String,
187    /// Migration file stem, such as `0001_initial`.
188    pub name: String,
189    /// Apply or rollback.
190    pub action: MigrationAction,
191    /// Ordered execution steps.
192    pub steps: Vec<ExecutionStep>,
193    /// Whether every step in this migration has a reverse.
194    ///
195    /// `false` when the migration contains a `DefineSchema` op (model-initial
196    /// schema; no reverse) or any op whose reverse is `None`.
197    pub reversible: bool,
198}
199
200/// Ordered execution plan produced by [`plan`].
201#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
202pub struct ExecutionPlan {
203    /// Migrations to apply, in graph (dependency) order.
204    pub to_apply: Vec<MigrationExecution>,
205    /// Migrations to roll back, in reverse discovery order.
206    pub to_rollback: Vec<MigrationExecution>,
207}
208
209/// Produce an ordered [`ExecutionPlan`] from a validated graph and applied state.
210///
211/// # Errors
212///
213/// - [`MigrationError::Planning`] – graph validation found one or more errors.
214/// - [`MigrationError::ChecksumDrift`] – an applied migration's checksum has
215///   drifted (hard gate; no plan is produced).
216/// - [`MigrationError::UnloweredOperation`] – the graph contains an
217///   [`OperationSpec`] variant that is intentionally unsupported by the Rust
218///   planner.
219pub fn plan(
220    graph: &MigrationGraph,
221    applied: &[AppliedMigrationRecord],
222    target: Option<&str>,
223) -> crate::Result<ExecutionPlan> {
224    // Gate 1: structural graph validation (04).
225    let errors = validate_graph(graph, applied);
226    if !errors.is_empty() {
227        return Err(MigrationError::Planning { errors });
228    }
229
230    // Gate 2: checksum drift (04 gate, hard stop before any step assembly).
231    check_checksum_drift(graph, applied)?;
232    validate_role_ordering(graph)?;
233
234    // Build an applied-key set for O(1) membership checks.
235    let applied_keys: std::collections::BTreeSet<(&str, &str)> = applied
236        .iter()
237        .map(|r| (r.app_label.as_str(), r.name.as_str()))
238        .collect();
239
240    let (to_apply, to_rollback) = if let Some(target_name) = target {
241        // Find the target index by name (or app_label::name).
242        let target_idx = graph
243            .migrations
244            .iter()
245            .position(|m| {
246                m.name == target_name || format!("{}::{}", m.app_label, m.name) == target_name
247            })
248            .ok_or_else(|| MigrationError::TargetNotFound {
249                target: target_name.to_string(),
250            })?;
251
252        let mut apply = Vec::new();
253        let mut rollback = Vec::new();
254
255        for (i, migration) in graph.migrations.iter().enumerate() {
256            let is_applied =
257                applied_keys.contains(&(migration.app_label.as_str(), migration.name.as_str()));
258            if i <= target_idx && !is_applied {
259                apply.push(migration);
260            } else if i > target_idx && is_applied {
261                rollback.push(migration);
262            }
263        }
264
265        // Rollbacks go in reverse order (matches Python _create_plan).
266        rollback.reverse();
267        (apply, rollback)
268    } else {
269        // Apply all pending migrations.
270        let apply: Vec<_> = graph
271            .migrations
272            .iter()
273            .filter(|m| !applied_keys.contains(&(m.app_label.as_str(), m.name.as_str())))
274            .collect();
275        (apply, Vec::new())
276    };
277
278    // Assemble MigrationExecution objects for the apply list.
279    let mut apply_executions = Vec::with_capacity(to_apply.len());
280    for migration in to_apply {
281        let steps = assemble_steps(&migration.operations, migration.reversible)?;
282        let reversible = steps.iter().all(|s| s.reverse.is_some());
283        apply_executions.push(MigrationExecution {
284            app_label: migration.app_label.clone(),
285            name: migration.name.clone(),
286            action: MigrationAction::Apply,
287            steps,
288            reversible,
289        });
290    }
291
292    // Assemble MigrationExecution objects for the rollback list.
293    let mut rollback_executions = Vec::with_capacity(to_rollback.len());
294    for migration in to_rollback {
295        let steps = assemble_steps(&migration.operations, migration.reversible)?;
296        let reversible = steps.iter().all(|s| s.reverse.is_some());
297        rollback_executions.push(MigrationExecution {
298            app_label: migration.app_label.clone(),
299            name: migration.name.clone(),
300            action: MigrationAction::Rollback,
301            steps,
302            reversible,
303        });
304    }
305
306    Ok(ExecutionPlan {
307        to_apply: apply_executions,
308        to_rollback: rollback_executions,
309    })
310}
311
312// Released AddRole has no live schema input. Validate facts supplied in the
313// graph, and leave absent parent declarations to provider validation.
314fn validate_role_ordering(graph: &MigrationGraph) -> crate::Result<()> {
315    let mut relations = std::collections::BTreeMap::new();
316    let mut roles = std::collections::BTreeMap::new();
317    for operation in graph
318        .migrations
319        .iter()
320        .flat_map(|migration| &migration.operations)
321    {
322        let mut added_roles = Vec::new();
323        match operation {
324            OperationSpec::DefineSchema { schema } => {
325                for relation in schema.relations.values() {
326                    relations.insert(relation.type_name.as_str(), relation.parent_type.as_deref());
327                    for role in &relation.roles {
328                        roles.insert((relation.type_name.as_str(), role.role_name.as_str()), role);
329                        added_roles.push((relation.type_name.as_str(), role));
330                    }
331                }
332            }
333            OperationSpec::AddRelation { relation } => {
334                relations.insert(relation.type_name.as_str(), relation.parent_type.as_deref());
335                for role in &relation.roles {
336                    roles.insert((relation.type_name.as_str(), role.role_name.as_str()), role);
337                    added_roles.push((relation.type_name.as_str(), role));
338                }
339            }
340            OperationSpec::AddRole {
341                relation_type,
342                role,
343            } => {
344                roles.insert((relation_type.as_str(), role.role_name.as_str()), role);
345                added_roles.push((relation_type.as_str(), role));
346            }
347            OperationSpec::RemoveRelation { type_name } => {
348                relations.remove(type_name.as_str());
349                roles.retain(|(relation, _), _| *relation != type_name);
350            }
351            OperationSpec::RemoveRole {
352                relation_type,
353                role_name,
354            } => {
355                roles.remove(&(relation_type.as_str(), role_name.as_str()));
356            }
357            _ => {}
358        }
359        for (relation, role) in added_roles {
360            let Some(parent_role) = role.overrides.as_deref() else {
361                continue;
362            };
363            let parent_role = parent_role.strip_suffix("[]").unwrap_or(parent_role);
364            let mut ancestor = relations.get(relation).copied().flatten();
365            let mut visited = BTreeSet::new();
366            while let Some(parent) = ancestor {
367                if !visited.insert(parent) {
368                    break;
369                }
370                if let Some(parent_role) = roles.get(&(parent, parent_role)) {
371                    if role.ordered != parent_role.ordered {
372                        return Err(MigrationError::AuthoringInput {
373                            message: format!(
374                                "role {relation}:{} has different ordering from parent {parent}:{}",
375                                role.role_name, parent_role.role_name
376                            ),
377                        });
378                    }
379                    break;
380                }
381                ancestor = relations.get(parent).copied().flatten();
382            }
383        }
384    }
385    Ok(())
386}
387
388/// Relation labels deleted wholesale by a `RemoveRelation` in this migration.
389fn removed_relation_labels(operations: &[OperationSpec]) -> BTreeSet<&str> {
390    operations
391        .iter()
392        .filter_map(|op| match op {
393            OperationSpec::RemoveRelation { type_name } => Some(type_name.as_str()),
394            _ => None,
395        })
396        .collect()
397}
398
399/// True when `op` is a relation-scoped granular removal shadowed by a
400/// `RemoveRelation` of the same relation in the same migration.
401///
402/// Legacy v1.5.x artifacts decomposed whole-relation deletion into
403/// `RemoveRolePlayer`/`RemoveRole`/`RemoveOwnership` before the final
404/// `RemoveRelation`. Executed step-per-transaction, committing the last
405/// role's removal violates TypeDB's commit-time rule that a concrete
406/// relation must relate at least one role, stranding the migration after
407/// partial schema changes (#168). `undefine <relation>` already cascades
408/// roles, player capabilities, and ownerships in one schema transaction, so
409/// the shadowed steps are dropped at plan time — the artifact bytes and
410/// checksum are never touched.
411fn shadowed_by_remove_relation(op: &OperationSpec, removed: &BTreeSet<&str>) -> bool {
412    match op {
413        OperationSpec::RemoveRole { relation_type, .. }
414        | OperationSpec::RemoveRolePlayer { relation_type, .. } => {
415            removed.contains(relation_type.as_str())
416        }
417        OperationSpec::RemoveOwnership { owner_type, .. } => removed.contains(owner_type.as_str()),
418        _ => false,
419    }
420}
421
422/// Render the retained Python operation String API without changing its AST.
423///
424/// These helpers historically rely on provider cascades and declaration order;
425/// execution planning keeps its explicit cleanup and canonical ordering.
426#[doc(hidden)]
427pub fn render_operation_typeql_steps(
428    operation: &OperationSpec,
429) -> crate::Result<Vec<ExecutionStep>> {
430    let mut steps = assemble_steps(std::slice::from_ref(operation), true)?;
431    match operation {
432        OperationSpec::AddRelation { relation } => {
433            let mut nodes = vec![type_bridge_orm::_schema::generator::relation_node(
434                relation, None,
435            )?];
436            for role in &relation.roles {
437                for player in &role.player_type_names {
438                    nodes.push(tql::schema_type(
439                        None,
440                        player,
441                        vec![],
442                        vec![tql::schema_plays(
443                            &relation.type_name,
444                            &role.role_name,
445                            vec![],
446                        )?],
447                    )?);
448                }
449            }
450            steps[0].forward = render_query(tql::schema_define(nodes))?;
451            steps[0].reverse = Some(undefine_relation(&relation.type_name)?);
452        }
453        OperationSpec::AddRole {
454            relation_type,
455            role,
456        } => {
457            steps[0].reverse = Some(render_query(tql::schema_undefine(vec![
458                tql::schema_undefine_capability(
459                    relation_type,
460                    tql::schema_relates(&role.role_name, role.ordered, None, vec![])?,
461                )?,
462            ]))?);
463        }
464        _ => {}
465    }
466    Ok(steps)
467}
468
469/// Lower a slice of [`OperationSpec`] into [`ExecutionStep`]s.
470fn assemble_steps(
471    operations: &[OperationSpec],
472    migration_reversible: bool,
473) -> crate::Result<Vec<ExecutionStep>> {
474    let removed_relations = removed_relation_labels(operations);
475    let mut steps = Vec::with_capacity(operations.len());
476    for op in operations {
477        if shadowed_by_remove_relation(op, &removed_relations) {
478            continue;
479        }
480        let mut op_steps: Vec<ExecutionStep> = match op {
481            OperationSpec::RunTypeql { forward, reverse } => {
482                let tx_type = run_typeql_tx_type(forward);
483                vec![ExecutionStep {
484                    tx_type,
485                    kind: if tx_type == TxType::Write {
486                        StepKind::Write
487                    } else {
488                        StepKind::Schema
489                    },
490                    operation_kind: OperationKind::RunTypeql,
491                    forward: forward.clone(),
492                    reverse: reverse.clone(),
493                }]
494            }
495            OperationSpec::DefineSchema { schema } => {
496                // Route through the existing canonical Rust generator
497                // (SchemaInfo::to_typeql → generator::generate_define_block).
498                // This is the only TypeQL generation in plan.rs — no per-variant
499                // re-derivation for any other OperationSpec (invariant 2).
500                let forward = schema
501                    .to_typeql()
502                    .map_err(|e| MigrationError::SchemaGeneration {
503                        message: e.to_string(),
504                    })?;
505                vec![ExecutionStep {
506                    tx_type: TxType::Schema,
507                    kind: StepKind::Schema,
508                    operation_kind: OperationKind::DefineSchema,
509                    forward,
510                    // Model-initial migrations are non-reversible.
511                    reverse: None,
512                }]
513            }
514            OperationSpec::AddAttribute { attribute } => vec![schema_step(
515                define_attribute(attribute)?,
516                Some(undefine_attribute(&attribute.attr_name)?),
517            )],
518            OperationSpec::RemoveAttribute { attr_name } => {
519                vec![schema_step(undefine_attribute(attr_name)?, None)]
520            }
521            OperationSpec::AddEntity { entity } => vec![schema_step(
522                define_entity(entity)?,
523                Some(undefine_entity(&entity.type_name)?),
524            )],
525            OperationSpec::RemoveEntity { type_name } => {
526                vec![schema_step(undefine_entity(type_name)?, None)]
527            }
528            OperationSpec::AddRelation { relation } => vec![schema_step(
529                define_relation(relation)?,
530                Some(undefine_relation_with_players(relation)?),
531            )],
532            OperationSpec::RemoveRelation { type_name } => {
533                vec![schema_step(undefine_relation(type_name)?, None)]
534            }
535            OperationSpec::AddOwnership {
536                owner_type,
537                attribute,
538            } => vec![schema_step(
539                define_ownership(owner_type, attribute)?,
540                Some(undefine_known_ownership(owner_type, attribute)?),
541            )],
542            OperationSpec::RemoveOwnership {
543                owner_type,
544                attr_name,
545            } => vec![schema_step(
546                undefine_ownership(owner_type, attr_name)?,
547                None,
548            )],
549            OperationSpec::ModifyOwnership {
550                owner_type,
551                attr_name,
552                old_annotations,
553                new_annotations,
554            } => annotation_token_steps(
555                owner_type,
556                Some(tql::schema_owns_source(attr_name, vec![])?),
557                &diff_annotation_tokens(
558                    &split_annotation_tokens(old_annotations),
559                    &split_annotation_tokens(new_annotations),
560                ),
561            )?,
562            OperationSpec::ModifyTypeAnnotations {
563                type_name,
564                old_doc,
565                new_doc,
566                old_meta,
567                new_meta,
568            } => annotation_token_steps(
569                type_name,
570                None,
571                &diff_annotation_tokens(
572                    &doc_meta_tokens(old_doc.as_deref(), old_meta),
573                    &doc_meta_tokens(new_doc.as_deref(), new_meta),
574                ),
575            )?,
576            OperationSpec::ModifyRoleAnnotations {
577                relation_type,
578                role_name,
579                old_doc,
580                new_doc,
581                old_meta,
582                new_meta,
583            } => annotation_token_steps(
584                relation_type,
585                Some(tql::schema_relates_source(role_name, vec![])?),
586                &diff_annotation_tokens(
587                    &doc_meta_tokens(old_doc.as_deref(), old_meta),
588                    &doc_meta_tokens(new_doc.as_deref(), new_meta),
589                ),
590            )?,
591            OperationSpec::AddRole {
592                relation_type,
593                role,
594            } => vec![schema_step(
595                define_role(relation_type, role)?,
596                Some(undefine_role_with_players(relation_type, role)?),
597            )],
598            OperationSpec::RemoveRole {
599                relation_type,
600                role_name,
601            } => vec![schema_step(undefine_role(relation_type, role_name)?, None)],
602            OperationSpec::AddRolePlayer {
603                relation_type,
604                role_name,
605                player_type_name,
606            } => vec![schema_step(
607                define_role_player(relation_type, role_name, player_type_name)?,
608                Some(undefine_role_player(
609                    relation_type,
610                    role_name,
611                    player_type_name,
612                )?),
613            )],
614            OperationSpec::RemoveRolePlayer {
615                relation_type,
616                role_name,
617                player_type_name,
618            } => vec![schema_step(
619                undefine_role_player(relation_type, role_name, player_type_name)?,
620                Some(define_role_player(
621                    relation_type,
622                    role_name,
623                    player_type_name,
624                )?),
625            )],
626            copy @ OperationSpec::CopyAttribute { .. } => {
627                // Carried TypeQL (the frozen `CopyAttribute.to_typeql()` output)
628                // executes verbatim; the structured portable form synthesizes the
629                // identical template. `backfill.rs` composes its count queries
630                // from this `forward` text's match clause.
631                let (forward, reverse) = copy_attribute_typeql(copy)?;
632                vec![ExecutionStep {
633                    tx_type: TxType::Write,
634                    kind: StepKind::Backfill,
635                    operation_kind: OperationKind::CopyAttribute,
636                    forward,
637                    reverse,
638                }]
639            }
640            other @ OperationSpec::RenameAttribute { .. } => {
641                return Err(MigrationError::UnloweredOperation {
642                    kind: op_kind_name(other).to_string(),
643                });
644            }
645        };
646        if !migration_reversible {
647            for step in &mut op_steps {
648                step.reverse = None;
649            }
650        }
651        let operation_kind = OperationKind::from_spec(op);
652        for step in &mut op_steps {
653            step.operation_kind = operation_kind;
654        }
655        steps.append(&mut op_steps);
656    }
657    Ok(steps)
658}
659
660/// Lower an annotation-set change on `subject` into execution steps.
661///
662/// TypeDB 3.12 semantics (verified live): `define`/`undefine` blocks accept
663/// multiple statements per query, while `redefine` mutates exactly one schema
664/// element per query; parameterless annotations (`@key`, `@unique`,
665/// `@distinct`) can only be defined or undefined, never redefined. Removals
666/// therefore group into one `undefine` step, additions into one `define`
667/// step, and each value change becomes its own `redefine` step. Removals run
668/// first — adding `@key` while a conflicting explicit `@card` is still
669/// declared fails schema validation. Reverse steps restore the prior state
670/// with the mirrored verb.
671fn annotation_definition(
672    subject: &str,
673    capability: Option<&tql::SchemaCapability>,
674    token: &AnnotationToken,
675) -> crate::Result<tql::SchemaDefinition> {
676    let annotation = tql::schema_annotation(&token.name, token.args.as_deref())?;
677    let (head, capabilities) = if let Some(capability) = capability {
678        (vec![], vec![capability.clone().annotated(vec![annotation])])
679    } else {
680        (vec![annotation], vec![])
681    };
682    Ok(tql::schema_type(None, subject, head, capabilities)?)
683}
684fn annotation_undefinition(
685    subject: &str,
686    capability: Option<&tql::SchemaCapability>,
687    token: &AnnotationToken,
688) -> crate::Result<tql::SchemaUndefinition> {
689    let key = token.meta_key();
690    Ok(tql::schema_undefine_annotation(
691        &token.name,
692        key.as_deref(),
693        subject,
694        capability.cloned(),
695    )?)
696}
697fn annotation_token_steps(
698    subject: &str,
699    capability: Option<tql::SchemaCapability>,
700    diff: &AnnotationTokenDiff,
701) -> crate::Result<Vec<ExecutionStep>> {
702    let mut steps = Vec::new();
703    if !diff.removed.is_empty() {
704        let removed = diff
705            .removed
706            .iter()
707            .map(|token| annotation_undefinition(subject, capability.as_ref(), token))
708            .collect::<crate::Result<Vec<_>>>()?;
709        let restore = diff
710            .removed
711            .iter()
712            .map(|token| annotation_definition(subject, capability.as_ref(), token))
713            .collect::<crate::Result<Vec<_>>>()?;
714        steps.push(schema_step(
715            render_query(tql::schema_undefine(removed))?,
716            Some(render_query(tql::schema_define(restore))?),
717        ));
718    }
719    for (old, new) in &diff.changed {
720        let forward = annotation_definition(subject, capability.as_ref(), new)?;
721        let reverse = annotation_definition(subject, capability.as_ref(), old)?;
722        steps.push(schema_step(
723            render_query(tql::schema_redefine(vec![forward]))?,
724            Some(render_query(tql::schema_redefine(vec![reverse]))?),
725        ));
726    }
727    if !diff.added.is_empty() {
728        let added = diff
729            .added
730            .iter()
731            .map(|token| annotation_definition(subject, capability.as_ref(), token))
732            .collect::<crate::Result<Vec<_>>>()?;
733        let remove = diff
734            .added
735            .iter()
736            .map(|token| annotation_undefinition(subject, capability.as_ref(), token))
737            .collect::<crate::Result<Vec<_>>>()?;
738        steps.push(schema_step(
739            render_query(tql::schema_define(added))?,
740            Some(render_query(tql::schema_undefine(remove))?),
741        ));
742    }
743    Ok(steps)
744}
745
746/// Build the `@doc`/`@meta` token list for one side of a type or role
747/// annotation change.
748fn doc_meta_tokens(
749    doc: Option<&str>,
750    meta: &std::collections::BTreeMap<String, String>,
751) -> Vec<AnnotationToken> {
752    let mut tokens = Vec::new();
753    if let Some(doc) = doc {
754        tokens.push(AnnotationToken::doc(doc));
755    }
756    for (key, value) in meta {
757        tokens.push(AnnotationToken::meta(key, value));
758    }
759    tokens
760}
761
762fn schema_step(forward: String, reverse: Option<String>) -> ExecutionStep {
763    ExecutionStep {
764        tx_type: TxType::Schema,
765        kind: StepKind::Schema,
766        operation_kind: OperationKind::RunTypeql,
767        forward,
768        reverse,
769    }
770}
771
772fn run_typeql_tx_type(forward: &str) -> TxType {
773    let first_statement = forward
774        .lines()
775        .map(str::trim)
776        .find(|line| !line.is_empty() && !line.starts_with('#') && !line.starts_with("//"))
777        .unwrap_or_default()
778        .to_ascii_lowercase();
779    if first_statement.starts_with("define")
780        || first_statement.starts_with("undefine")
781        || first_statement.starts_with("redefine")
782    {
783        TxType::Schema
784    } else {
785        TxType::Write
786    }
787}
788
789fn render_query(query: tql::Query) -> crate::Result<String> {
790    Ok(tql::render(&query)?)
791}
792fn schema_to_typeql(schema: &SchemaInfo) -> crate::Result<String> {
793    schema
794        .to_typeql()
795        .map_err(|error| MigrationError::SchemaGeneration {
796            message: error.to_string(),
797        })
798}
799fn define_attribute(attribute: &AttributeSchemaEntry) -> crate::Result<String> {
800    let mut schema = SchemaInfo::default();
801    schema
802        .attributes
803        .insert(attribute.attr_name.clone(), attribute.clone());
804    schema_to_typeql(&schema)
805}
806fn undefine_attribute(name: &str) -> crate::Result<String> {
807    render_query(tql::schema_undefine(vec![tql::schema_undefine_type(name)?]))
808}
809fn define_entity(entity: &EntitySchemaEntry) -> crate::Result<String> {
810    let mut schema = SchemaInfo::default();
811    schema
812        .entities
813        .insert(entity.type_name.clone(), entity.clone());
814    schema_to_typeql(&schema)
815}
816fn undefine_entity(name: &str) -> crate::Result<String> {
817    undefine_attribute(name)
818}
819fn define_relation(relation: &RelationSchemaEntry) -> crate::Result<String> {
820    let mut schema = SchemaInfo::default();
821    schema
822        .relations
823        .insert(relation.type_name.clone(), relation.clone());
824    schema_to_typeql(&schema)
825}
826fn undefine_relation(name: &str) -> crate::Result<String> {
827    undefine_attribute(name)
828}
829fn undefine_relation_with_players(relation: &RelationSchemaEntry) -> crate::Result<String> {
830    let mut nodes = Vec::new();
831    for role in &relation.roles {
832        for player in &role.player_type_names {
833            nodes.push(tql::schema_undefine_capability(
834                player,
835                tql::schema_plays(&relation.type_name, &role.role_name, vec![])?,
836            )?);
837        }
838    }
839    nodes.push(tql::schema_undefine_type(&relation.type_name)?);
840    render_query(tql::schema_undefine(nodes))
841}
842fn define_ownership(owner: &str, attribute: &OwnedAttributeEntry) -> crate::Result<String> {
843    let values = tql::schema_annotations_source(&attribute.flags_string())?;
844    render_query(tql::schema_define(vec![tql::schema_type(
845        None,
846        owner,
847        vec![],
848        vec![tql::schema_owns(
849            &attribute.attr_name,
850            attribute.is_ordered,
851            values,
852        )?],
853    )?]))
854}
855fn undefine_ownership(owner: &str, name: &str) -> crate::Result<String> {
856    render_query(tql::schema_undefine(vec![tql::schema_undefine_capability(
857        owner,
858        tql::schema_owns_source(name, vec![])?,
859    )?]))
860}
861fn undefine_known_ownership(owner: &str, attribute: &OwnedAttributeEntry) -> crate::Result<String> {
862    render_query(tql::schema_undefine(vec![tql::schema_undefine_capability(
863        owner,
864        tql::schema_owns(&attribute.attr_name, attribute.is_ordered, vec![])?,
865    )?]))
866}
867fn role_capability(role: &RoleEntry) -> crate::Result<tql::SchemaCapability> {
868    let mut annotations = Vec::new();
869    if role.is_abstract {
870        annotations.push(tql::schema_flag("abstract")?);
871    }
872    if role.distinct {
873        annotations.push(tql::schema_flag("distinct")?);
874    }
875    if let Some((min, max)) = role.cardinality {
876        annotations.push(tql::schema_card(u64::from(min), max.map(u64::from))?);
877    }
878    Ok(tql::schema_relates_with_parent_source(
879        &role.role_name,
880        role.ordered,
881        role.overrides.as_deref(),
882        annotations,
883    )?)
884}
885fn define_role(relation: &str, role: &RoleEntry) -> crate::Result<String> {
886    let mut nodes = vec![tql::schema_type(
887        None,
888        relation,
889        vec![],
890        vec![role_capability(role)?],
891    )?];
892    for player in &role.player_type_names {
893        nodes.push(tql::schema_type(
894            None,
895            player,
896            vec![],
897            vec![tql::schema_plays(relation, &role.role_name, vec![])?],
898        )?);
899    }
900    render_query(tql::schema_define(nodes))
901}
902fn undefine_role(relation: &str, role: &str) -> crate::Result<String> {
903    render_query(tql::schema_undefine(vec![tql::schema_undefine_capability(
904        relation,
905        tql::schema_relates_source(role, vec![])?,
906    )?]))
907}
908fn undefine_role_with_players(relation: &str, role: &RoleEntry) -> crate::Result<String> {
909    let mut nodes = Vec::new();
910    for player in &role.player_type_names {
911        nodes.push(tql::schema_undefine_capability(
912            player,
913            tql::schema_plays(relation, &role.role_name, vec![])?,
914        )?);
915    }
916    nodes.push(tql::schema_undefine_capability(
917        relation,
918        tql::schema_relates(&role.role_name, role.ordered, None, vec![])?,
919    )?);
920    render_query(tql::schema_undefine(nodes))
921}
922fn define_role_player(relation: &str, role: &str, player: &str) -> crate::Result<String> {
923    render_query(tql::schema_define(vec![tql::schema_type(
924        None,
925        player,
926        vec![],
927        vec![tql::schema_plays(relation, role, vec![])?],
928    )?]))
929}
930fn undefine_role_player(relation: &str, role: &str, player: &str) -> crate::Result<String> {
931    render_query(tql::schema_undefine(vec![tql::schema_undefine_capability(
932        player,
933        tql::schema_plays(relation, role, vec![])?,
934    )?]))
935}
936
937/// Return a stable string name for an [`OperationSpec`] variant.
938///
939/// Used only in error messages.
940fn op_kind_name(op: &OperationSpec) -> &'static str {
941    match op {
942        OperationSpec::RunTypeql { .. } => "RunTypeql",
943        OperationSpec::DefineSchema { .. } => "DefineSchema",
944        OperationSpec::AddAttribute { .. } => "AddAttribute",
945        OperationSpec::RemoveAttribute { .. } => "RemoveAttribute",
946        OperationSpec::AddEntity { .. } => "AddEntity",
947        OperationSpec::RemoveEntity { .. } => "RemoveEntity",
948        OperationSpec::AddRelation { .. } => "AddRelation",
949        OperationSpec::RemoveRelation { .. } => "RemoveRelation",
950        OperationSpec::AddOwnership { .. } => "AddOwnership",
951        OperationSpec::RemoveOwnership { .. } => "RemoveOwnership",
952        OperationSpec::ModifyOwnership { .. } => "ModifyOwnership",
953        OperationSpec::ModifyTypeAnnotations { .. } => "ModifyTypeAnnotations",
954        OperationSpec::ModifyRoleAnnotations { .. } => "ModifyRoleAnnotations",
955        OperationSpec::AddRole { .. } => "AddRole",
956        OperationSpec::RemoveRole { .. } => "RemoveRole",
957        OperationSpec::AddRolePlayer { .. } => "AddRolePlayer",
958        OperationSpec::RemoveRolePlayer { .. } => "RemoveRolePlayer",
959        OperationSpec::RenameAttribute { .. } => "RenameAttribute",
960        OperationSpec::CopyAttribute { .. } => "CopyAttribute",
961    }
962}
963
964#[cfg(test)]
965mod tests {
966    use std::collections::BTreeMap;
967
968    use super::*;
969    use type_bridge_orm::_entity::Annotation;
970    use type_bridge_orm::_schema::info::{
971        AttributeSchemaEntry, EntitySchemaEntry, OwnedAttributeEntry, RelationSchemaEntry,
972        RoleEntry, SchemaInfo,
973    };
974    use type_bridge_orm::ValueType;
975
976    use crate::graph::AppliedMigrationRecord;
977    use crate::spec::{MigrationDependencySpec, MigrationGraph, MigrationSpec, OperationSpec};
978
979    // ── helpers ──────────────────────────────────────────────────────────────
980
981    fn run_typeql(forward: &str, reverse: Option<&str>) -> OperationSpec {
982        OperationSpec::RunTypeql {
983            forward: forward.to_string(),
984            reverse: reverse.map(str::to_string),
985        }
986    }
987
988    fn define_schema_op() -> OperationSpec {
989        let mut schema = SchemaInfo::default();
990        schema.attributes.insert(
991            "name".to_string(),
992            AttributeSchemaEntry::new("name", ValueType::String),
993        );
994        schema.entities.insert(
995            "person".to_string(),
996            EntitySchemaEntry {
997                type_name: "person".to_string(),
998                is_abstract: false,
999                parent_type: None,
1000                owned_attributes: vec![OwnedAttributeEntry {
1001                    attr_name: "name".to_string(),
1002                    value_type: ValueType::String,
1003                    annotations: vec![Annotation::Key],
1004                    is_ordered: false,
1005                    doc: None,
1006                    meta: Default::default(),
1007                }],
1008                plays_cardinalities: BTreeMap::new(),
1009                doc: None,
1010                meta: Default::default(),
1011            },
1012        );
1013        OperationSpec::DefineSchema { schema }
1014    }
1015
1016    fn owned_attr(
1017        attr_name: &str,
1018        value_type: ValueType,
1019        annotations: Vec<Annotation>,
1020    ) -> OwnedAttributeEntry {
1021        OwnedAttributeEntry {
1022            attr_name: attr_name.to_string(),
1023            value_type,
1024            annotations,
1025            is_ordered: false,
1026            doc: None,
1027            meta: Default::default(),
1028        }
1029    }
1030
1031    fn entity_entry(type_name: &str) -> EntitySchemaEntry {
1032        EntitySchemaEntry {
1033            type_name: type_name.to_string(),
1034            is_abstract: false,
1035            parent_type: None,
1036            owned_attributes: vec![owned_attr("name", ValueType::String, vec![Annotation::Key])],
1037            plays_cardinalities: BTreeMap::new(),
1038            doc: None,
1039            meta: Default::default(),
1040        }
1041    }
1042
1043    fn relation_entry(type_name: &str) -> RelationSchemaEntry {
1044        RelationSchemaEntry {
1045            type_name: type_name.to_string(),
1046            is_abstract: false,
1047            parent_type: None,
1048            owned_attributes: vec![],
1049            roles: vec![RoleEntry {
1050                role_name: "employee".to_string(),
1051                player_type_names: vec!["person".to_string()],
1052                cardinality: None,
1053                overrides: None,
1054                is_abstract: false,
1055                ordered: false,
1056                distinct: false,
1057                doc: None,
1058                meta: Default::default(),
1059            }],
1060            plays_cardinalities: BTreeMap::new(),
1061            doc: None,
1062            meta: Default::default(),
1063        }
1064    }
1065
1066    fn migration(name: &str, ops: Vec<OperationSpec>, deps: Vec<(&str, &str)>) -> MigrationSpec {
1067        MigrationSpec {
1068            app_label: "app".to_string(),
1069            name: name.to_string(),
1070            dependencies: deps
1071                .into_iter()
1072                .map(|(app, dep_name)| MigrationDependencySpec {
1073                    app_label: app.to_string(),
1074                    migration_name: dep_name.to_string(),
1075                })
1076                .collect(),
1077            operations: ops,
1078            checksum: Some(format!("{name}-csum")),
1079            source_sha256: None,
1080            reversible: true,
1081        }
1082    }
1083
1084    fn applied(name: &str) -> AppliedMigrationRecord {
1085        AppliedMigrationRecord {
1086            app_label: "app".to_string(),
1087            name: name.to_string(),
1088            checksum: format!("{name}-csum"),
1089            applied_at: None,
1090        }
1091    }
1092
1093    fn graph(migrations: Vec<MigrationSpec>) -> MigrationGraph {
1094        MigrationGraph { migrations }
1095    }
1096
1097    // ── test: pending-only ordering (target=None) ────────────────────────────
1098
1099    #[test]
1100    fn pending_only_all_pending_applies_in_order() {
1101        let g = graph(vec![
1102            migration(
1103                "0001_initial",
1104                vec![run_typeql("define attribute a, value string;", None)],
1105                vec![],
1106            ),
1107            migration(
1108                "0002_add",
1109                vec![run_typeql(
1110                    "define attribute b, value string;",
1111                    Some("undefine attribute b;"),
1112                )],
1113                vec![("app", "0001_initial")],
1114            ),
1115        ]);
1116
1117        let result = plan(&g, &[], None).expect("plan should succeed");
1118
1119        assert_eq!(result.to_apply.len(), 2);
1120        assert_eq!(result.to_rollback.len(), 0);
1121        assert_eq!(result.to_apply[0].name, "0001_initial");
1122        assert_eq!(result.to_apply[1].name, "0002_add");
1123    }
1124
1125    #[test]
1126    fn pending_only_already_applied_excluded() {
1127        let g = graph(vec![
1128            migration(
1129                "0001_initial",
1130                vec![run_typeql("define attribute a, value string;", None)],
1131                vec![],
1132            ),
1133            migration(
1134                "0002_add",
1135                vec![run_typeql(
1136                    "define attribute b, value string;",
1137                    Some("undefine attribute b;"),
1138                )],
1139                vec![("app", "0001_initial")],
1140            ),
1141        ]);
1142
1143        let result = plan(&g, &[applied("0001_initial")], None).expect("plan should succeed");
1144
1145        assert_eq!(result.to_apply.len(), 1);
1146        assert_eq!(result.to_apply[0].name, "0002_add");
1147        assert_eq!(result.to_rollback.len(), 0);
1148    }
1149
1150    // ── test: target-based apply/rollback split ───────────────────────────────
1151
1152    #[test]
1153    fn target_applies_up_to_and_including_target() {
1154        let g = graph(vec![
1155            migration(
1156                "0001_initial",
1157                vec![run_typeql("define attribute a, value string;", None)],
1158                vec![],
1159            ),
1160            migration(
1161                "0002_add",
1162                vec![run_typeql(
1163                    "define attribute b, value string;",
1164                    Some("undefine attribute b;"),
1165                )],
1166                vec![("app", "0001_initial")],
1167            ),
1168            migration(
1169                "0003_more",
1170                vec![run_typeql(
1171                    "define attribute c, value string;",
1172                    Some("undefine attribute c;"),
1173                )],
1174                vec![("app", "0002_add")],
1175            ),
1176        ]);
1177
1178        // target = 0002_add; none applied yet.
1179        let result = plan(&g, &[], Some("0002_add")).expect("plan should succeed");
1180
1181        assert_eq!(result.to_apply.len(), 2);
1182        assert_eq!(result.to_apply[0].name, "0001_initial");
1183        assert_eq!(result.to_apply[1].name, "0002_add");
1184        assert_eq!(result.to_rollback.len(), 0);
1185    }
1186
1187    #[test]
1188    fn target_rolls_back_past_target_in_reverse_order() {
1189        let g = graph(vec![
1190            migration(
1191                "0001_initial",
1192                vec![run_typeql("define attribute a, value string;", None)],
1193                vec![],
1194            ),
1195            migration(
1196                "0002_add",
1197                vec![run_typeql(
1198                    "define attribute b, value string;",
1199                    Some("undefine attribute b;"),
1200                )],
1201                vec![("app", "0001_initial")],
1202            ),
1203            migration(
1204                "0003_more",
1205                vec![run_typeql(
1206                    "define attribute c, value string;",
1207                    Some("undefine attribute c;"),
1208                )],
1209                vec![("app", "0002_add")],
1210            ),
1211        ]);
1212
1213        // All three applied; target = 0001_initial → rollback 0002 and 0003.
1214        let result = plan(
1215            &g,
1216            &[
1217                applied("0001_initial"),
1218                applied("0002_add"),
1219                applied("0003_more"),
1220            ],
1221            Some("0001_initial"),
1222        )
1223        .expect("plan should succeed");
1224
1225        assert_eq!(result.to_apply.len(), 0);
1226        // rollback list must be in reverse order: 0003, then 0002
1227        assert_eq!(result.to_rollback.len(), 2);
1228        assert_eq!(result.to_rollback[0].name, "0003_more");
1229        assert_eq!(result.to_rollback[1].name, "0002_add");
1230    }
1231
1232    // ── test: rollback reverse ordering for steps ─────────────────────────────
1233
1234    #[test]
1235    fn rollback_execution_action_is_rollback() {
1236        let g = graph(vec![
1237            migration(
1238                "0001_initial",
1239                vec![run_typeql("define attribute a, value string;", None)],
1240                vec![],
1241            ),
1242            migration(
1243                "0002_add",
1244                vec![run_typeql(
1245                    "define attribute b, value string;",
1246                    Some("undefine attribute b;"),
1247                )],
1248                vec![("app", "0001_initial")],
1249            ),
1250        ]);
1251
1252        let result = plan(
1253            &g,
1254            &[applied("0001_initial"), applied("0002_add")],
1255            Some("0001_initial"),
1256        )
1257        .expect("plan should succeed");
1258
1259        assert_eq!(result.to_rollback[0].action, MigrationAction::Rollback);
1260    }
1261
1262    // ── test: DefineSchema carries non-empty TypeQL from the generator ─────────
1263
1264    #[test]
1265    fn define_schema_step_carries_typeql_from_generator() {
1266        let g = graph(vec![migration(
1267            "0001_initial",
1268            vec![define_schema_op()],
1269            vec![],
1270        )]);
1271
1272        let result = plan(&g, &[], None).expect("plan should succeed");
1273
1274        let exec = &result.to_apply[0];
1275        assert_eq!(exec.steps.len(), 1);
1276        let step = &exec.steps[0];
1277        // Forward must be non-empty TypeQL produced by SchemaInfo::to_typeql().
1278        assert!(
1279            !step.forward.is_empty(),
1280            "DefineSchema forward must be non-empty"
1281        );
1282        assert!(
1283            step.forward.contains("define"),
1284            "DefineSchema forward must contain 'define'"
1285        );
1286        // DefineSchema is non-reversible — no reverse.
1287        assert!(step.reverse.is_none());
1288    }
1289
1290    #[test]
1291    fn define_schema_step_tx_type_is_schema() {
1292        let g = graph(vec![migration(
1293            "0001_initial",
1294            vec![define_schema_op()],
1295            vec![],
1296        )]);
1297
1298        let result = plan(&g, &[], None).expect("plan should succeed");
1299        assert_eq!(result.to_apply[0].steps[0].tx_type, TxType::Schema);
1300    }
1301
1302    // ── test: per-step TxType is Schema for RunTypeql ─────────────────────────
1303
1304    #[test]
1305    fn run_typeql_step_tx_type_is_schema() {
1306        let g = graph(vec![migration(
1307            "0001_add",
1308            vec![run_typeql("define attribute a, value string;", None)],
1309            vec![],
1310        )]);
1311
1312        let result = plan(&g, &[], None).expect("plan should succeed");
1313        assert_eq!(result.to_apply[0].steps[0].tx_type, TxType::Schema);
1314    }
1315
1316    #[test]
1317    fn data_run_typeql_step_tx_type_is_write() {
1318        let g = graph(vec![migration(
1319            "0002_seed",
1320            vec![run_typeql(
1321                r#"match $a isa account, has account-id "acct-001";
1322insert $a has email "ops@example.com";"#,
1323                Some(
1324                    r#"match $a isa account, has email "ops@example.com";
1325delete $a has email "ops@example.com";"#,
1326                ),
1327            )],
1328            vec![],
1329        )]);
1330
1331        let result = plan(&g, &[], None).expect("plan should succeed");
1332        let step = &result.to_apply[0].steps[0];
1333        assert_eq!(step.tx_type, TxType::Write);
1334        assert_eq!(step.kind, StepKind::Write);
1335    }
1336
1337    // ── tests: typed OperationSpec variants lower in Rust ─────────────────────
1338
1339    #[test]
1340    fn typed_attribute_operations_lower_to_schema_steps() {
1341        let g = graph(vec![migration(
1342            "0001_attrs",
1343            vec![
1344                OperationSpec::AddAttribute {
1345                    attribute: AttributeSchemaEntry::new("score", ValueType::Long),
1346                },
1347                OperationSpec::RemoveAttribute {
1348                    attr_name: "legacy-score".to_string(),
1349                },
1350            ],
1351            vec![],
1352        )]);
1353
1354        let result = plan(&g, &[], None).expect("plan should succeed");
1355        let steps = &result.to_apply[0].steps;
1356
1357        assert_eq!(steps.len(), 2);
1358        assert!(steps[0].forward.contains("attribute score, value integer;"));
1359        assert_typeql_eq!(steps[0].reverse.as_deref(), Some("undefine\nscore;"));
1360        assert_typeql_eq!(steps[1].forward, "undefine\nlegacy-score;");
1361        assert!(steps[1].reverse.is_none());
1362        assert!(!result.to_apply[0].reversible);
1363    }
1364
1365    #[test]
1366    fn typed_entity_and_relation_operations_lower_to_schema_steps() {
1367        let g = graph(vec![migration(
1368            "0001_types",
1369            vec![
1370                OperationSpec::AddEntity {
1371                    entity: entity_entry("person"),
1372                },
1373                OperationSpec::AddRelation {
1374                    relation: relation_entry("employment"),
1375                },
1376            ],
1377            vec![],
1378        )]);
1379
1380        let result = plan(&g, &[], None).expect("plan should succeed");
1381        let steps = &result.to_apply[0].steps;
1382
1383        assert!(steps[0].forward.contains("entity person,"));
1384        assert!(steps[0].forward.contains("owns name @key;"));
1385        assert_typeql_eq!(steps[0].reverse.as_deref(), Some("undefine\nperson;"));
1386        assert!(steps[1].forward.contains("relation employment,"));
1387        assert!(steps[1].forward.contains("relates employee;"));
1388        assert!(
1389            steps[1]
1390                .forward
1391                .contains("person, plays employment:employee;")
1392        );
1393        assert!(
1394            steps[1]
1395                .reverse
1396                .as_deref()
1397                .unwrap()
1398                .contains("plays employment:employee from person;")
1399        );
1400        assert!(steps[1].reverse.as_deref().unwrap().contains("employment;"));
1401    }
1402
1403    #[test]
1404    fn add_entity_with_parent_outside_singleton_schema_lowers_without_panic() {
1405        // Lowering AddEntity builds a singleton SchemaInfo containing only the
1406        // child; the parent named by `sub` lives outside it. Planning must not
1407        // panic and the define step must keep the `sub` clause (#190).
1408        let mut child = entity_entry("person");
1409        child.parent_type = Some("animal".to_string());
1410        let g = graph(vec![migration(
1411            "0001_sub_entity",
1412            vec![OperationSpec::AddEntity { entity: child }],
1413            vec![],
1414        )]);
1415
1416        let result = plan(&g, &[], None).expect("plan should succeed");
1417        let steps = &result.to_apply[0].steps;
1418
1419        assert_eq!(steps.len(), 1);
1420        assert!(steps[0].forward.contains("entity person, sub animal,"));
1421        assert_typeql_eq!(steps[0].reverse.as_deref(), Some("undefine\nperson;"));
1422    }
1423
1424    #[test]
1425    fn typed_ownership_operations_lower_to_schema_steps() {
1426        let g = graph(vec![migration(
1427            "0001_ownership",
1428            vec![
1429                OperationSpec::AddOwnership {
1430                    owner_type: "person".to_string(),
1431                    attribute: owned_attr("email", ValueType::String, vec![Annotation::Key]),
1432                },
1433                OperationSpec::RemoveOwnership {
1434                    owner_type: "person".to_string(),
1435                    attr_name: "legacy-email".to_string(),
1436                },
1437                OperationSpec::ModifyOwnership {
1438                    owner_type: "person".to_string(),
1439                    attr_name: "nickname".to_string(),
1440                    old_annotations: "@card(0..1)".to_string(),
1441                    new_annotations: "@card(1..1)".to_string(),
1442                },
1443            ],
1444            vec![],
1445        )]);
1446
1447        let result = plan(&g, &[], None).expect("plan should succeed");
1448        let steps = &result.to_apply[0].steps;
1449
1450        assert_typeql_eq!(steps[0].forward, "define\nperson owns email @key;");
1451        assert_typeql_eq!(
1452            steps[0].reverse.as_deref(),
1453            Some("undefine\nowns email from person;")
1454        );
1455        assert_typeql_eq!(steps[1].forward, "undefine\nowns legacy-email from person;");
1456        assert!(steps[1].reverse.is_none());
1457        assert_typeql_eq!(
1458            steps[2].forward,
1459            "redefine\nperson owns nickname @card(1..1);"
1460        );
1461        assert_typeql_eq!(
1462            steps[2].reverse.as_deref(),
1463            Some("redefine\nperson owns nickname @card(0..1);")
1464        );
1465    }
1466
1467    #[test]
1468    fn modify_ownership_decomposes_parameterless_transitions() {
1469        // @key can never be redefined (REX28): swapping @card(0..1) for
1470        // @key must lower to an undefine step followed by a define step,
1471        // removals first (defining @key beside a conflicting explicit
1472        // @card fails schema validation).
1473        let g = graph(vec![migration(
1474            "0002_key",
1475            vec![OperationSpec::ModifyOwnership {
1476                owner_type: "person".to_string(),
1477                attr_name: "nickname".to_string(),
1478                old_annotations: "@card(0..1)".to_string(),
1479                new_annotations: "@key".to_string(),
1480            }],
1481            vec![],
1482        )]);
1483
1484        let result = plan(&g, &[], None).expect("plan should succeed");
1485        let steps = &result.to_apply[0].steps;
1486
1487        assert_eq!(steps.len(), 2);
1488        assert_typeql_eq!(
1489            steps[0].forward,
1490            "undefine\n@card from person owns nickname;"
1491        );
1492        assert_typeql_eq!(
1493            steps[0].reverse.as_deref(),
1494            Some("define\nperson owns nickname @card(0..1);")
1495        );
1496        assert_typeql_eq!(steps[1].forward, "define\nperson owns nickname @key;");
1497        assert_typeql_eq!(
1498            steps[1].reverse.as_deref(),
1499            Some("undefine\n@key from person owns nickname;")
1500        );
1501    }
1502
1503    #[test]
1504    fn modify_ownership_from_plain_defines_and_identical_sets_lower_to_nothing() {
1505        let g = graph(vec![migration(
1506            "0002_tighten",
1507            vec![
1508                OperationSpec::ModifyOwnership {
1509                    owner_type: "person".to_string(),
1510                    attr_name: "nickname".to_string(),
1511                    old_annotations: String::new(),
1512                    new_annotations: "@key".to_string(),
1513                },
1514                OperationSpec::ModifyOwnership {
1515                    owner_type: "person".to_string(),
1516                    attr_name: "email".to_string(),
1517                    old_annotations: "@unique".to_string(),
1518                    new_annotations: "@unique".to_string(),
1519                },
1520            ],
1521            vec![],
1522        )]);
1523
1524        let result = plan(&g, &[], None).expect("plan should succeed");
1525        let steps = &result.to_apply[0].steps;
1526
1527        // The no-op transition contributes zero steps.
1528        assert_eq!(steps.len(), 1);
1529        assert_typeql_eq!(steps[0].forward, "define\nperson owns nickname @key;");
1530        assert_typeql_eq!(
1531            steps[0].reverse.as_deref(),
1532            Some("undefine\n@key from person owns nickname;")
1533        );
1534    }
1535
1536    #[test]
1537    fn typed_role_operations_lower_to_schema_steps() {
1538        let role = RoleEntry {
1539            role_name: "reviewer".to_string(),
1540            player_type_names: vec!["person".to_string()],
1541            cardinality: Some((0, Some(2))),
1542            overrides: None,
1543            is_abstract: false,
1544            ordered: false,
1545            distinct: false,
1546            doc: None,
1547            meta: Default::default(),
1548        };
1549        let g = graph(vec![migration(
1550            "0001_roles",
1551            vec![
1552                OperationSpec::AddRole {
1553                    relation_type: "employment".to_string(),
1554                    role,
1555                },
1556                OperationSpec::RemoveRole {
1557                    relation_type: "employment".to_string(),
1558                    role_name: "legacy".to_string(),
1559                },
1560                OperationSpec::AddRolePlayer {
1561                    relation_type: "employment".to_string(),
1562                    role_name: "employee".to_string(),
1563                    player_type_name: "contractor".to_string(),
1564                },
1565                OperationSpec::RemoveRolePlayer {
1566                    relation_type: "employment".to_string(),
1567                    role_name: "employee".to_string(),
1568                    player_type_name: "company".to_string(),
1569                },
1570            ],
1571            vec![],
1572        )]);
1573
1574        let result = plan(&g, &[], None).expect("plan should succeed");
1575        let steps = &result.to_apply[0].steps;
1576
1577        assert_typeql_eq!(
1578            steps[0].forward,
1579            "define\nemployment relates reviewer @card(0..2);\nperson plays employment:reviewer;"
1580        );
1581        assert_typeql_eq!(
1582            steps[0].reverse.as_deref(),
1583            Some(
1584                "undefine\nplays employment:reviewer from person;\nrelates reviewer from employment;"
1585            )
1586        );
1587        assert_typeql_eq!(
1588            steps[1].forward,
1589            "undefine\nrelates legacy from employment;"
1590        );
1591        assert!(steps[1].reverse.is_none());
1592        assert_typeql_eq!(
1593            steps[2].forward,
1594            "define\ncontractor plays employment:employee;"
1595        );
1596        assert_typeql_eq!(
1597            steps[2].reverse.as_deref(),
1598            Some("undefine\nplays employment:employee from contractor;")
1599        );
1600        assert_typeql_eq!(
1601            steps[3].forward,
1602            "undefine\nplays employment:employee from company;"
1603        );
1604        assert_typeql_eq!(
1605            steps[3].reverse.as_deref(),
1606            Some("define\ncompany plays employment:employee;")
1607        );
1608    }
1609
1610    #[test]
1611    fn migration_reversible_flag_drops_typed_operation_reverses() {
1612        let mut spec = migration(
1613            "0001_non_reversible",
1614            vec![OperationSpec::AddAttribute {
1615                attribute: AttributeSchemaEntry::new("score", ValueType::Long),
1616            }],
1617            vec![],
1618        );
1619        spec.reversible = false;
1620        let g = graph(vec![spec]);
1621
1622        let result = plan(&g, &[], None).expect("plan should succeed");
1623
1624        assert!(result.to_apply[0].steps[0].reverse.is_none());
1625        assert!(!result.to_apply[0].reversible);
1626    }
1627
1628    // ── test: intentionally unsupported operation returns Err ────────────────
1629
1630    #[test]
1631    fn unlowered_op_returns_err() {
1632        let g = graph(vec![migration(
1633            "0001_rename_attr",
1634            vec![OperationSpec::RenameAttribute {
1635                old_name: "old-score".to_string(),
1636                new_name: "new-score".to_string(),
1637                value_type: "string".to_string(),
1638            }],
1639            vec![],
1640        )]);
1641
1642        let err = plan(&g, &[], None).expect_err("should fail for unsupported op");
1643        match err {
1644            MigrationError::UnloweredOperation { kind } => {
1645                assert_eq!(kind, "RenameAttribute");
1646            }
1647            other => panic!("expected UnloweredOperation, got {other:?}"),
1648        }
1649    }
1650
1651    // ── test: validation failure short-circuits ────────────────────────────────
1652
1653    #[test]
1654    fn validation_failure_returns_planning_error() {
1655        // 0002 depends on 0001 which is not in the graph.
1656        let g = graph(vec![migration(
1657            "0002_next",
1658            vec![run_typeql("define attribute b, value string;", None)],
1659            vec![("app", "0001_initial")],
1660        )]);
1661
1662        let err = plan(&g, &[], None).expect_err("should fail on validation error");
1663        assert!(
1664            matches!(err, MigrationError::Planning { .. }),
1665            "expected Planning error, got {err:?}"
1666        );
1667    }
1668
1669    // ── test: checksum drift short-circuits ───────────────────────────────────
1670
1671    #[test]
1672    fn checksum_drift_returns_error() {
1673        let g = graph(vec![migration(
1674            "0001_initial",
1675            vec![run_typeql("define attribute a, value string;", None)],
1676            vec![],
1677        )]);
1678
1679        // Record "0001_initial" with a wrong checksum.
1680        let bad_applied = AppliedMigrationRecord {
1681            app_label: "app".to_string(),
1682            name: "0001_initial".to_string(),
1683            checksum: "wrong-checksum".to_string(),
1684            applied_at: None,
1685        };
1686
1687        let err = plan(&g, &[bad_applied], None).expect_err("should fail on drift");
1688        assert!(
1689            matches!(err, MigrationError::ChecksumDrift { .. }),
1690            "expected ChecksumDrift error, got {err:?}"
1691        );
1692    }
1693
1694    // ── test: reversible flag ─────────────────────────────────────────────────
1695
1696    #[test]
1697    fn migration_with_no_reverse_is_marked_not_reversible() {
1698        let g = graph(vec![migration(
1699            "0001_initial",
1700            // reverse is None
1701            vec![run_typeql("define attribute a, value string;", None)],
1702            vec![],
1703        )]);
1704
1705        let result = plan(&g, &[], None).expect("plan should succeed");
1706        assert!(!result.to_apply[0].reversible);
1707    }
1708
1709    #[test]
1710    fn migration_with_all_reverses_is_reversible() {
1711        let g = graph(vec![migration(
1712            "0001_add",
1713            vec![run_typeql(
1714                "define attribute a, value string;",
1715                Some("undefine attribute a;"),
1716            )],
1717            vec![],
1718        )]);
1719
1720        let result = plan(&g, &[], None).expect("plan should succeed");
1721        assert!(result.to_apply[0].reversible);
1722    }
1723
1724    #[test]
1725    fn define_schema_migration_is_not_reversible() {
1726        // DefineSchema never has a reverse.
1727        let g = graph(vec![migration(
1728            "0001_initial",
1729            vec![define_schema_op()],
1730            vec![],
1731        )]);
1732
1733        let result = plan(&g, &[], None).expect("plan should succeed");
1734        assert!(!result.to_apply[0].reversible);
1735    }
1736
1737    // ── test: target not found returns TargetNotFound ─────────────────────────
1738
1739    #[test]
1740    fn unknown_target_returns_target_not_found_error() {
1741        let g = graph(vec![migration(
1742            "0001_initial",
1743            vec![run_typeql("define attribute a, value string;", None)],
1744            vec![],
1745        )]);
1746
1747        let err = plan(&g, &[], Some("nonexistent_migration"))
1748            .expect_err("should fail for missing target");
1749        assert!(
1750            matches!(err, MigrationError::TargetNotFound { .. }),
1751            "expected TargetNotFound, got {err:?}"
1752        );
1753    }
1754
1755    // ── test: CopyAttribute lowers to Write-typed Backfill step ───────────────
1756
1757    #[test]
1758    fn copy_attribute_lowers_to_write_typed_backfill_step() {
1759        // The carried forward/reverse mirror `CopyAttribute.to_typeql()` /
1760        // `to_rollback_typeql()`; assemble_steps must pass them through verbatim
1761        // under a Write/Backfill step (no re-synthesis — invariant 2).
1762        let forward = "match\n  $x isa person, has old-name $v;\n  \
1763            not { $x has new-name $d; };\ninsert\n  $x has new-name == $v;";
1764        let reverse = "match $x isa person, has new-name $v;\ndelete $v of $x;";
1765        let g = graph(vec![migration(
1766            "0002_backfill",
1767            vec![OperationSpec::CopyAttribute {
1768                owner: None,
1769                source: None,
1770                dest: None,
1771                filter: None,
1772                forward: Some(forward.to_string()),
1773                reverse: Some(reverse.to_string()),
1774            }],
1775            vec![],
1776        )]);
1777
1778        let result = plan(&g, &[], None).expect("plan should succeed");
1779
1780        let exec = &result.to_apply[0];
1781        assert_eq!(exec.steps.len(), 1);
1782        let step = &exec.steps[0];
1783
1784        assert_eq!(
1785            step.tx_type,
1786            TxType::Write,
1787            "CopyAttribute step must use Write tx"
1788        );
1789        assert_eq!(
1790            step.kind,
1791            StepKind::Backfill,
1792            "CopyAttribute step kind must be Backfill"
1793        );
1794        // The carried strings are passed through unchanged.
1795        assert_eq!(step.forward, forward, "forward must be carried verbatim");
1796        assert_eq!(
1797            step.reverse.as_deref(),
1798            Some(reverse),
1799            "reverse must be carried verbatim"
1800        );
1801    }
1802
1803    #[test]
1804    fn structured_copy_attribute_lowers_to_the_same_backfill_step() {
1805        // The structured portable form synthesizes the exact TypeQL the
1806        // carried form would have contained.
1807        let g = graph(vec![migration(
1808            "0002_backfill",
1809            vec![OperationSpec::CopyAttribute {
1810                owner: Some("person".to_string()),
1811                source: Some("old-name".to_string()),
1812                dest: Some("new-name".to_string()),
1813                filter: None,
1814                forward: None,
1815                reverse: None,
1816            }],
1817            vec![],
1818        )]);
1819
1820        let result = plan(&g, &[], None).expect("plan should succeed");
1821
1822        let step = &result.to_apply[0].steps[0];
1823        assert_eq!(step.tx_type, TxType::Write);
1824        assert_eq!(step.kind, StepKind::Backfill);
1825        assert_typeql_eq!(
1826            step.forward,
1827            "match\n  $x isa person, has old-name $v;\n  \
1828             not { $x has new-name $d; };\ninsert\n  $x has new-name == $v;"
1829        );
1830        assert_typeql_eq!(
1831            step.reverse.as_deref(),
1832            Some("match $x isa person, has new-name $v;\ndelete $v of $x;")
1833        );
1834    }
1835
1836    #[test]
1837    fn step_kind_default_is_schema_for_serde_backcompat() {
1838        // Simulate a legacy JSON step without the `kind` field.
1839        let json =
1840            r#"{"tx_type":"Schema","forward":"define attribute a, value string;","reverse":null}"#;
1841        let step: ExecutionStep =
1842            serde_json::from_str(json).expect("should deserialize legacy step");
1843        assert_eq!(
1844            step.kind,
1845            StepKind::Schema,
1846            "missing `kind` field must default to Schema for backward compat"
1847        );
1848        assert_eq!(step.operation_kind, OperationKind::RunTypeql);
1849    }
1850
1851    // ── test: whole-relation removal normalization (#168) ───────────────────
1852
1853    /// The exact operation shape v1.5.5/v1.5.6 generators authored for a
1854    /// whole-relation deletion: granular unwind, then `RemoveRelation`.
1855    fn legacy_remove_relation_ops(relation: &str) -> Vec<OperationSpec> {
1856        vec![
1857            OperationSpec::RemoveRolePlayer {
1858                relation_type: relation.to_string(),
1859                role_name: "subject".to_string(),
1860                player_type_name: "person".to_string(),
1861            },
1862            OperationSpec::RemoveRole {
1863                relation_type: relation.to_string(),
1864                role_name: "subject".to_string(),
1865            },
1866            OperationSpec::RemoveRolePlayer {
1867                relation_type: relation.to_string(),
1868                role_name: "badge".to_string(),
1869                player_type_name: "temporary-badge".to_string(),
1870            },
1871            OperationSpec::RemoveRole {
1872                relation_type: relation.to_string(),
1873                role_name: "badge".to_string(),
1874            },
1875            OperationSpec::RemoveOwnership {
1876                owner_type: relation.to_string(),
1877                attr_name: "legacy-link-id".to_string(),
1878            },
1879            OperationSpec::RemoveRelation {
1880                type_name: relation.to_string(),
1881            },
1882        ]
1883    }
1884
1885    #[test]
1886    fn legacy_decomposed_relation_removal_normalizes_to_single_step() {
1887        let g = graph(vec![migration(
1888            "0005_remove_legacy_link",
1889            legacy_remove_relation_ops("legacy-link"),
1890            vec![],
1891        )]);
1892
1893        let result = plan(&g, &[], None).expect("plan should succeed");
1894
1895        let exec = &result.to_apply[0];
1896        assert_eq!(
1897            exec.steps.len(),
1898            1,
1899            "granular removals shadowed by RemoveRelation must be dropped"
1900        );
1901        assert_typeql_eq!(exec.steps[0].forward, "undefine\nlegacy-link;");
1902        assert_eq!(exec.steps[0].tx_type, TxType::Schema);
1903    }
1904
1905    #[test]
1906    fn surviving_relation_granular_removals_are_kept() {
1907        // No RemoveRelation for `employment`: granular ops must lower 1:1.
1908        let ops = vec![
1909            OperationSpec::RemoveRolePlayer {
1910                relation_type: "employment".to_string(),
1911                role_name: "employee".to_string(),
1912                player_type_name: "contractor".to_string(),
1913            },
1914            OperationSpec::RemoveRole {
1915                relation_type: "employment".to_string(),
1916                role_name: "reviewer".to_string(),
1917            },
1918            OperationSpec::RemoveOwnership {
1919                owner_type: "employment".to_string(),
1920                attr_name: "note".to_string(),
1921            },
1922        ];
1923        let g = graph(vec![migration("0002_trim_employment", ops, vec![])]);
1924
1925        let result = plan(&g, &[], None).expect("plan should succeed");
1926
1927        assert_eq!(result.to_apply[0].steps.len(), 3);
1928    }
1929
1930    #[test]
1931    fn normalization_is_scoped_to_the_removed_relation() {
1932        // One relation is removed wholesale while another one is trimmed in
1933        // the same migration; only ops scoped to the removed relation drop.
1934        let mut ops = legacy_remove_relation_ops("legacy-link");
1935        ops.push(OperationSpec::RemoveRolePlayer {
1936            relation_type: "employment".to_string(),
1937            role_name: "employee".to_string(),
1938            player_type_name: "contractor".to_string(),
1939        });
1940        ops.push(OperationSpec::RemoveOwnership {
1941            owner_type: "person".to_string(),
1942            attr_name: "nickname".to_string(),
1943        });
1944        let g = graph(vec![migration("0006_mixed_removals", ops, vec![])]);
1945
1946        let result = plan(&g, &[], None).expect("plan should succeed");
1947
1948        let forwards: Vec<&str> = result.to_apply[0]
1949            .steps
1950            .iter()
1951            .map(|s| s.forward.as_str())
1952            .collect();
1953        assert_typeql_eq!(
1954            forwards,
1955            vec![
1956                "undefine\nlegacy-link;",
1957                "undefine\nplays employment:employee from contractor;",
1958                "undefine\nowns nickname from person;",
1959            ]
1960        );
1961    }
1962
1963    #[test]
1964    fn modify_ownership_lowers_per_annotation_steps() {
1965        // Mixed add/update/remove including parameterless @key/@unique, which
1966        // can never be redefined (REX28) — they must go through define/undefine.
1967        let g = graph(vec![migration(
1968            "0001_annotations",
1969            vec![OperationSpec::ModifyOwnership {
1970                owner_type: "person".to_string(),
1971                attr_name: "name".to_string(),
1972                old_annotations: "@key @doc(\"old doc\") @meta(\"x\", \"1\")".to_string(),
1973                new_annotations: "@unique @doc(\"new doc\") @meta(\"y\", \"2\")".to_string(),
1974            }],
1975            vec![],
1976        )]);
1977
1978        let result = plan(&g, &[], None).expect("plan should succeed");
1979        let steps = &result.to_apply[0].steps;
1980        assert_eq!(steps.len(), 3);
1981
1982        // Removals run first: adding @unique while the conflicting @key is
1983        // still declared would fail schema validation.
1984        assert_typeql_eq!(
1985            steps[0].forward,
1986            "undefine\n@key from person owns name;\n@meta(\"x\") from person owns name;"
1987        );
1988        assert_typeql_eq!(
1989            steps[0].reverse.as_deref(),
1990            Some("define\nperson owns name @key;\nperson owns name @meta(\"x\", \"1\");")
1991        );
1992        assert_typeql_eq!(
1993            steps[1].forward,
1994            "redefine\nperson owns name @doc(\"new doc\");"
1995        );
1996        assert_typeql_eq!(
1997            steps[1].reverse.as_deref(),
1998            Some("redefine\nperson owns name @doc(\"old doc\");")
1999        );
2000        assert_typeql_eq!(
2001            steps[2].forward,
2002            "define\nperson owns name @meta(\"y\", \"2\");\nperson owns name @unique;"
2003        );
2004        assert_typeql_eq!(
2005            steps[2].reverse.as_deref(),
2006            Some("undefine\n@meta(\"y\") from person owns name;\n@unique from person owns name;")
2007        );
2008        // added order: "meta:y" < "unique" in identity order.
2009    }
2010
2011    #[test]
2012    fn modify_ownership_with_identical_annotations_lowers_to_no_steps() {
2013        let g = graph(vec![migration(
2014            "0001_noop",
2015            vec![OperationSpec::ModifyOwnership {
2016                owner_type: "person".to_string(),
2017                attr_name: "name".to_string(),
2018                old_annotations: "@key @doc(\"same\")".to_string(),
2019                new_annotations: "@key @doc(\"same\")".to_string(),
2020            }],
2021            vec![],
2022        )]);
2023
2024        let result = plan(&g, &[], None).expect("plan should succeed");
2025        assert!(result.to_apply[0].steps.is_empty());
2026    }
2027
2028    #[test]
2029    fn modify_type_annotations_lowers_add_update_remove() {
2030        let g = graph(vec![migration(
2031            "0001_type_annotations",
2032            vec![OperationSpec::ModifyTypeAnnotations {
2033                type_name: "person".to_string(),
2034                old_doc: Some("old type doc".to_string()),
2035                new_doc: Some("new type doc".to_string()),
2036                old_meta: BTreeMap::from([("gone".to_string(), "1".to_string())]),
2037                new_meta: BTreeMap::from([("added".to_string(), "2".to_string())]),
2038            }],
2039            vec![],
2040        )]);
2041
2042        let result = plan(&g, &[], None).expect("plan should succeed");
2043        let steps = &result.to_apply[0].steps;
2044        assert_eq!(steps.len(), 3);
2045        assert_typeql_eq!(steps[0].forward, "undefine\n@meta(\"gone\") from person;");
2046        assert_typeql_eq!(
2047            steps[0].reverse.as_deref(),
2048            Some("define\nperson @meta(\"gone\", \"1\");")
2049        );
2050        assert_typeql_eq!(steps[1].forward, "redefine\nperson @doc(\"new type doc\");");
2051        assert_typeql_eq!(
2052            steps[1].reverse.as_deref(),
2053            Some("redefine\nperson @doc(\"old type doc\");")
2054        );
2055        assert_typeql_eq!(steps[2].forward, "define\nperson @meta(\"added\", \"2\");");
2056        assert_typeql_eq!(
2057            steps[2].reverse.as_deref(),
2058            Some("undefine\n@meta(\"added\") from person;")
2059        );
2060    }
2061
2062    #[test]
2063    fn modify_role_annotations_lowers_on_relates_subject() {
2064        let g = graph(vec![migration(
2065            "0001_role_annotations",
2066            vec![OperationSpec::ModifyRoleAnnotations {
2067                relation_type: "employment".to_string(),
2068                role_name: "employee".to_string(),
2069                old_doc: None,
2070                new_doc: Some("The employed party.".to_string()),
2071                old_meta: BTreeMap::new(),
2072                new_meta: BTreeMap::new(),
2073            }],
2074            vec![],
2075        )]);
2076
2077        let result = plan(&g, &[], None).expect("plan should succeed");
2078        let steps = &result.to_apply[0].steps;
2079        assert_eq!(steps.len(), 1);
2080        assert_typeql_eq!(
2081            steps[0].forward,
2082            "define\nemployment relates employee @doc(\"The employed party.\");"
2083        );
2084        assert_typeql_eq!(
2085            steps[0].reverse.as_deref(),
2086            Some("undefine\n@doc from employment relates employee;")
2087        );
2088    }
2089}