Migrate frozen data contracts and authored source to schema 4

crates/oa-core/src/language.rs

@@ -1,4 +1,4 @@
-//! Typed OA/SA language, tolerant source analysis, and explicit V1/V2 migration.
+//! Typed OA/SA language, tolerant source analysis, and explicit V1/V2/V3 migration.
 #[path = "migration_v2/source.rs"]
 mod v2_source;
 use crate::*;
@@ -340,6 +340,8 @@ fn reference_field(key: &str) -> bool {
             | "referenced"
             | "local"
             | "field"
+            | "path"
+            | "supertype"
             | "sender"
             | "receiver"
             | "action"
@@ -378,10 +380,14 @@ fn enum_field(key: &str) -> bool {
             | "message_kind"
             | "transition_kind"
             | "side"
+            | "mechanism"
+            | "storage"
+            | "transmission"
+            | "acquisition"
     )
 }
 
-/// Parse V3, or explicitly migrate a valid V1/V2 source candidate. Parsing never
+/// Parse V4, or explicitly migrate a valid V1/V2/V3 source candidate. Parsing never
 /// adopts a model and never overwrites an editor draft.
 pub fn parse(source: &str) -> Result<Project, Vec<Diagnostic>> {
     parse_limited(source, ParseLimits::UNLIMITED)
@@ -546,7 +552,7 @@ fn offset_for(source: &str, line: usize, column: usize) -> usize {
 /// nested records are ordinary language fields; JSON documents are not embedded.
 pub fn format(project: &Project) -> String {
     let mut out = std::format!(
-        "arcadia 3;\nproject {} {} id \"{}\" {{\n    description {};\n\n",
+        "arcadia 4;\nproject {} {} id \"{}\" {{\n    description {};\n\n",
         project.alias,
         quote(&project.name),
         project.id,
@@ -1337,12 +1343,12 @@ impl Parser<'_> {
                     .map(|(key, span)| ((d.id, key.clone()), span.start)),
             );
         }
-        let project =
+        let decoded =
             resolve_declarations(header.project, &unit.declarations, &aliases, self.limits)
                 .map_err(|(_, error)| error)?;
         Ok(ParsedDocument {
-            project,
-            migration: None,
+            project: decoded.project,
+            migration: decoded.migration,
             locations,
             fields,
         })
@@ -1350,9 +1356,11 @@ impl Parser<'_> {
     fn unit(&mut self, entry: bool, includes_allowed: bool) -> Result<SourceUnit, Error> {
         let mut header = if entry {
             self.take("arcadia")?;
-            if self.text() != "3" {
-                return Err(self.error("Unsupported schema version: expected 'arcadia 3;'."));
+            if !matches!(self.text(), "3" | "4") {
+                return Err(self
+                    .error("Unsupported schema version: expected 'arcadia 3;' or 'arcadia 4;'."));
             }
+            let schema_version = if self.text() == "3" { 3 } else { 4 };
             self.cursor += 1;
             self.take(";")?;
             let start = self.current().span.start;
@@ -1365,7 +1373,7 @@ impl Parser<'_> {
             self.take("{")?;
             Some(SourceHeader {
                 project: Project {
-                    schema_version: SCHEMA_VERSION,
+                    schema_version,
                     id,
                     alias,
                     name,
@@ -1540,7 +1548,9 @@ pub(crate) fn resolve_declarations(
     declarations: &[Declaration],
     aliases: &BTreeMap<String, Id>,
     limits: ParseLimits,
-) -> Result<Project, (usize, Error)> {
+) -> Result<crate::persistence::DecodeResult, (usize, Error)> {
+    let legacy = project.schema_version == 3;
+    let mut legacy_elements = serde_json::Map::new();
     let mut nodes = Vec::new();
     for (index, declaration) in declarations.iter().enumerate() {
         (|| -> Result<(), Error> {
@@ -1561,6 +1571,9 @@ pub(crate) fn resolve_declarations(
             };
             match d.kind {
                 DeclKind::Element(kind, layer) => {
+                    if legacy && !crate::persistence::v3::element_allowed(serde_json::to_value(kind).unwrap().as_str().unwrap()) {
+                        return Err(conversion_error("Element constructor was not part of schema3.".into()));
+                    }
                     let description =
                         take_string(&mut fields, "description", "").map_err(&conversion_error)?;
                     let explicit_parent = d.fields.contains_key("parent");
@@ -1601,9 +1614,17 @@ pub(crate) fn resolve_declarations(
                         *viewpoint = ScenarioViewpoint::MixedLegacy;
                     }
                     let mut body = serde_json::to_value(initial).unwrap();
-                    let body_fields =
-                        merge_fields(payload(&body), fields).map_err(&conversion_error)?;
+                    let defaults = if legacy {
+                        crate::persistence::v3::legacy_defaults(kind)
+                            .and_then(|value| value.as_object().cloned())
+                            .unwrap_or_else(|| payload(&body))
+                    } else { payload(&body) };
+                    let body_fields = merge_fields(defaults, fields).map_err(&conversion_error)?;
                     replace_payload(&mut body, body_fields);
+                    if legacy {
+                        legacy_elements.insert(d.id.to_string(), serde_json::json!({"id":d.id,"alias":d.alias,"name":d.name,"description":description,"parent":parent,"body":body}));
+                        return Ok(());
+                    }
                     let body: ElementBody = serde_json::from_value(body)
                         .map_err(|e| conversion_error(e.to_string()))?;
                     if body.kind() != kind || body.layer() != layer {
@@ -1624,6 +1645,9 @@ pub(crate) fn resolve_declarations(
                     );
                 }
                 DeclKind::Relation(kind) => {
+                    if legacy && !crate::persistence::v3::relation_allowed(serde_json::to_value(kind).unwrap().as_str().unwrap()) {
+                        return Err(conversion_error("Relation constructor was not part of schema3.".into()));
+                    }
                     let description =
                         take_string(&mut fields, "description", "").map_err(&conversion_error)?;
                     let required: &[&str] = if kind == RelationKind::FunctionalExchange {
@@ -1725,6 +1749,58 @@ pub(crate) fn resolve_declarations(
             .map_err(|error| (index, error))?;
         target.nodes.insert(node.id, node);
     }
+    if legacy {
+        let mut value = serde_json::to_value(&project).expect("project serialization");
+        value["elements"] = Value::Object(legacy_elements);
+        let migrated = serde_json::from_value(value)
+            .map_err(crate::persistence::FileError::Json)
+            .and_then(|old| crate::persistence::v3::migrate(old, limits))
+            .map_err(|error| {
+                let issue = if let crate::persistence::FileError::Model { issues, .. } = &error {
+                    issues.first()
+                } else {
+                    None
+                };
+                let index = issue
+                    .and_then(|issue| issue.element)
+                    .and_then(|id| declarations.iter().position(|d| d.id == id))
+                    .unwrap_or(usize::MAX);
+                let offset = declarations.get(index).map_or(0, |d| {
+                    issue
+                        .and_then(|issue| issue.field.as_ref())
+                        .and_then(|field| d.field_spans.get(field))
+                        .map_or(d.offset, |span| span.start)
+                });
+                (
+                    index,
+                    Error {
+                        code: if matches!(error, crate::persistence::FileError::Limit(_)) {
+                            "model_limit"
+                        } else {
+                            "migration_error"
+                        },
+                        offset,
+                        message: error.to_string(),
+                    },
+                )
+            })?;
+        for (index, d) in declarations.iter().enumerate() {
+            if let DeclKind::Element(kind, layer) = d.kind {
+                let body = &migrated.project.elements[&d.id].body;
+                if body.kind() != kind || body.layer() != layer {
+                    return Err((
+                        index,
+                        Error {
+                            code: "invalid_source",
+                            offset: d.offset,
+                            message: "Declaration kind disagrees with its typed body.".into(),
+                        },
+                    ));
+                }
+            }
+        }
+        return Ok(migrated);
+    }
     limits.check_model(&project).map_err(|message| {
         (
             usize::MAX,
@@ -1735,7 +1811,10 @@ pub(crate) fn resolve_declarations(
             },
         )
     })?;
-    Ok(project)
+    Ok(crate::persistence::DecodeResult {
+        project,
+        migration: None,
+    })
 }
 
 fn header(fields: &mut Map<String, Value>, d: &Declaration, named: bool) {

crates/oa-core/src/language_nesting_tests.rs

@@ -3,7 +3,7 @@ use crate::source_project::{ProjectLimits, SourceBundle, compile_bundle, lint_bu
 
 fn project_source(body: &str) -> String {
     format!(
-        "arcadia 3; project model \"Model\" id \"00000000-0000-0000-0000-000000000001\" {{\n{body}\n}}"
+        "arcadia 4; project model \"Model\" id \"00000000-0000-0000-0000-000000000001\" {{\n{body}\n}}"
     )
 }
 
@@ -177,7 +177,7 @@ fn nested_fragment_id_stabilization_preserves_comments_and_indexes_real_bytes()
         files: BTreeMap::from([
             (
                 "project.arcadia".into(),
-                "arcadia 3; project model \"Model\" { include \"children.arcadia\"; }".into(),
+                "arcadia 4; project model \"Model\" { include \"children.arcadia\"; }".into(),
             ),
             (
                 "children.arcadia".into(),
@@ -300,7 +300,7 @@ fn deep_declaration_parsing_and_positions_use_a_bounded_rust_stack() {
 
 #[test]
 fn tolerant_nested_analysis_retains_closed_children_before_an_unfinished_sibling() {
-    let source = "arcadia 3; project model \"航海\" {\noa_activity outer_one \"Outer\" {\n oa_activity ready \"Ready\" { description \"} is text\"; }\n oa_activity unfinished \"Unfinished\" { description \"unterminated";
+    let source = "arcadia 4; project model \"航海\" {\noa_activity outer_one \"Outer\" {\n oa_activity ready \"Ready\" { description \"} is text\"; }\n oa_activity unfinished \"Unfinished\" { description \"unterminated";
     let analysis = analyze(source);
     let ready = analysis
         .declarations
@@ -406,12 +406,34 @@ fn checked_in_source_project() -> SourceBundle {
 fn checked_in_nested_example_has_stable_ids_typed_exchanges_and_three_clear_views() {
     let input = checked_in_source_project();
     let compiled = compile_bundle(&input, ProjectLimits::default()).unwrap();
-    assert_eq!(
-        compiled.bundle, input,
-        "every example identity is already explicit"
-    );
+    assert_eq!(compiled.decoded.migration.as_ref().unwrap().from_schema, 3);
+    for (path, source) in &input.files {
+        let unit = parse_unit(source, path == &input.entry, ParseLimits::UNLIMITED).unwrap();
+        assert!(
+            unit.header
+                .as_ref()
+                .is_none_or(|header| header.id_insertion.is_none())
+        );
+        for declaration in unit.declarations {
+            assert!(
+                declaration.id_insertion.is_none(),
+                "every example identity is already explicit"
+            );
+            assert_eq!(
+                identity(&compiled.decoded.project, &declaration.alias),
+                declaration.id
+            );
+        }
+    }
+    let reopened = compile_bundle(&compiled.bundle, ProjectLimits::default()).unwrap();
+    assert_eq!(reopened.bundle, compiled.bundle);
+    assert!(reopened.decoded.migration.is_none());
+    assert_eq!(compiled.diagnostics.len(), 2);
     assert!(
-        compiled.diagnostics.is_empty(),
+        compiled
+            .diagnostics
+            .iter()
+            .all(|issue| issue.diagnostic.code == "unspecified_exchange_mechanism"),
         "{:?}",
         compiled.diagnostics
     );
@@ -473,7 +495,15 @@ fn checked_in_example_supports_cross_file_reparent_without_changing_allocations(
         ProjectLimits::default(),
     )
     .unwrap();
-    assert!(result.diagnostics.is_empty(), "{:?}", result.diagnostics);
+    assert_eq!(result.diagnostics.len(), 2);
+    assert!(
+        result
+            .diagnostics
+            .iter()
+            .all(|issue| issue.diagnostic.code == "unspecified_exchange_mechanism"),
+        "{:?}",
+        result.diagnostics
+    );
     assert_eq!(
         result.index.declarations[&assess].path,
         "sa/assurance.arcadia"
@@ -500,6 +530,6 @@ fn checked_in_example_supports_cross_file_reparent_without_changing_allocations(
         "sa/participants.arcadia",
         "views.arcadia",
     ] {
-        assert_eq!(result.bundle.files[path], input.files[path]);
+        assert_eq!(result.bundle.files[path], compiled.bundle.files[path]);
     }
 }

crates/oa-core/src/migration_v2/README.md

@@ -11,10 +11,12 @@ but constructs and validates the frozen DTO, preserves located old-contract
 errors, then calls `adapter.rs`. Original staged scenario/state defaults and
 generic port/optional FE endpoint contracts therefore remain explicit.
 
-`adapter.rs` budgets generated data, validates V2, transforms only the changed
-payloads, and validates schema 3. Serialization between the two typed DTOs copies
-unchanged fields; original input bytes are never deserialized into the new
-`Project`. V1 normalization also constructs this V2 DTO before the shared stage.
+`adapter.rs` budgets generated data, validates V2 and transforms only the changed
+port/endpoint payloads into an explicit schema 3 candidate. The schema 3 reader
+then performs the data-contract upgrade and validates schema 4. Serialization
+between compatibility DTOs copies unchanged fields; original input bytes are
+never deserialized into the new `Project`. V1 normalization also constructs this
+V2 DTO before the shared stages. Combined generation stays within one budget.
 
 Do not update these frozen shapes when extending the current model. Add another
 versioned migration when the persistent contract changes again. Golden V2

crates/oa-core/src/migration_v2/adapter.rs

@@ -62,16 +62,9 @@ pub(crate) fn migrate(
             }],
         });
     }
-    let mut report = MigrationReport {
-        from_schema: 2,
-        to_schema: 3,
-        preserved_ports: vec![],
-        generated_endpoints: vec![],
-        orientation_defaults: vec![],
-        required_resolutions: vec![],
-    };
+    let mut report = MigrationReport::data_upgrade(2);
     let mut value = serde_json::to_value(&old)?;
-    value["schema_version"] = Value::from(SCHEMA_VERSION);
+    value["schema_version"] = Value::from(3);
     for element in old.elements.values() {
         if let Some(super::model::SharedBody::Port {
             direction,
@@ -204,11 +197,23 @@ pub(crate) fn migrate(
             _ => {}
         }
     }
-    let project: Project = serde_json::from_value(value)?;
-    limits.check_model(&project).map_err(FileError::Limit)?;
-    super::super::validate_project(&project)?;
+    // Carry the endpoint-generation reference charge into the next migration;
+    // independent per-stage checks would undercount the combined generated graph.
+    let data_limits = ParseLimits {
+        max_step_references: limits
+            .max_step_references
+            .saturating_sub(additional_references),
+        ..limits
+    };
+    let migrated = super::super::v3::migrate(serde_json::from_value(value)?, data_limits)?;
+    let data = migrated
+        .migration
+        .expect("the schema3 adapter reports its defaults");
+    report.semantic_defaults = data.semantic_defaults;
+    report.generated_interface_allocations = data.generated_interface_allocations;
+    report.unresolved_message_values = data.unresolved_message_values;
     Ok(DecodeResult {
-        project,
+        project: migrated.project,
         migration: Some(report),
     })
 }

crates/oa-core/src/migration_v3/README.md

@@ -0,0 +1,33 @@
+# Schema 3 to 4 reader
+
+Schema 3 is a real compatibility input. Its shapes were frozen at `5ce3eef`.
+The small DTOs in `mod.rs` own the changed data payloads and old message values;
+closed element/relation constructor lists prevent new vocabulary from entering
+the old reader. Unchanged ports, diagram placements/routes, artifacts and traces
+reuse their typed records. The intermediate JSON bridge rejects duplicate keys.
+
+Nature, bounded types, field defaults/direction/storage, and single supertypes
+receive explicit documented defaults. Interface lists become identified ordered
+allocations with UUID v5 namespace equal to the project UUID and name
+`v2-interface-item:<interface-uuid>:<item-uuid>`. The name remains the same for
+V2 and V3 inputs so the migration route cannot change the generated identity.
+Existing IDs never move; deterministic collisions fail with a located diagnostic.
+Aliases use the normal deterministic collision suffix. Unique legacy message
+paths are qualified; ambiguous annotations retain their expression and warning.
+
+V1 first normalizes to the frozen V2 DTO. V2 port/endpoint normalization emits
+an explicit schema3 candidate and then runs this reader before current decoding.
+Generated object, record and reference budgets cover the combined stages.
+
+`language::resolve_declarations` shares lexical/AST parsing, including nesting,
+but chooses frozen source3 payload defaults and rejects new constructors. Both
+single-file parsing and `source_project::compile_bundle` take this explicit path.
+The bundle compiler first stabilizes omitted IDs, then performs targeted token
+edits in `source_project/source_migration.rs`. Original files, includes, lexical
+ownership and comments survive. New allocation declarations stay in the source
+interface's module. The returned source and index describe schema4 bytes; loading
+does not rewrite original disk files. Canonical output and second-save stability
+are schema4. No whole-project formatting fallback handles authored source3.
+
+Frozen source/JSON fixtures live under `tests/fixtures/v3-data-contract.*`; the
+original V2 golden files remain unchanged.

crates/oa-core/src/migration_v3/mod.rs

@@ -0,0 +1,630 @@
+//! Explicit schema-3 compatibility. Only changed payloads are frozen here;
+//! unchanged typed records are shared after a closed old-constructor check.
+use crate::language::ParseLimits;
+use crate::persistence::{DecodeResult, FileError, MigrationReport};
+use crate::*;
+use serde::{Deserialize, Serialize};
+use serde_json::{Value, json};
+use std::collections::{BTreeMap, BTreeSet};
+
+#[derive(Deserialize, Serialize)]
+#[serde(deny_unknown_fields)]
+pub(crate) struct Project3 {
+    pub schema_version: u32,
+    pub id: Id,
+    pub alias: String,
+    pub name: String,
+    pub description: String,
+    #[serde(deserialize_with = "crate::unique_id_map")]
+    pub elements: BTreeMap<Id, Element3>,
+    #[serde(deserialize_with = "crate::unique_id_map")]
+    pub relations: BTreeMap<Id, Relation3>,
+    #[serde(deserialize_with = "crate::unique_id_map")]
+    pub diagrams: BTreeMap<Id, Diagram>,
+    #[serde(deserialize_with = "crate::unique_id_map")]
+    pub artifact_links: BTreeMap<Id, ArtifactLink>,
+    #[serde(deserialize_with = "crate::unique_id_map")]
+    pub traces: BTreeMap<Id, Trace>,
+}
+#[derive(Deserialize, Serialize)]
+#[serde(deny_unknown_fields)]
+pub(crate) struct Element3 {
+    pub id: Id,
+    pub alias: String,
+    pub name: String,
+    pub description: String,
+    pub parent: Option<Id>,
+    #[serde(deserialize_with = "strict_value")]
+    pub body: Value,
+}
+#[derive(Deserialize, Serialize)]
+#[serde(deny_unknown_fields)]
+pub(crate) struct Relation3 {
+    pub id: Id,
+    pub alias: String,
+    pub name: String,
+    pub description: String,
+    #[serde(deserialize_with = "strict_value")]
+    pub body: Value,
+}
+
+// A Value bridge must retain the strict duplicate-field behavior of typed DTOs.
+fn strict_value<'de, D: serde::Deserializer<'de>>(d: D) -> Result<Value, D::Error> {
+    struct Strict;
+    impl<'de> serde::de::Visitor<'de> for Strict {
+        type Value = Value;
+        fn expecting(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+            f.write_str("a value with unique object fields")
+        }
+        fn visit_bool<E: serde::de::Error>(self, v: bool) -> Result<Value, E> {
+            Ok(v.into())
+        }
+        fn visit_i64<E: serde::de::Error>(self, v: i64) -> Result<Value, E> {
+            Ok(v.into())
+        }
+        fn visit_u64<E: serde::de::Error>(self, v: u64) -> Result<Value, E> {
+            Ok(v.into())
+        }
+        fn visit_f64<E: serde::de::Error>(self, v: f64) -> Result<Value, E> {
+            serde_json::Number::from_f64(v)
+                .map(Value::Number)
+                .ok_or_else(|| E::custom("Non-finite number"))
+        }
+        fn visit_str<E: serde::de::Error>(self, v: &str) -> Result<Value, E> {
+            Ok(v.into())
+        }
+        fn visit_string<E: serde::de::Error>(self, v: String) -> Result<Value, E> {
+            Ok(v.into())
+        }
+        fn visit_unit<E: serde::de::Error>(self) -> Result<Value, E> {
+            Ok(Value::Null)
+        }
+        fn visit_none<E: serde::de::Error>(self) -> Result<Value, E> {
+            Ok(Value::Null)
+        }
+        fn visit_seq<A: serde::de::SeqAccess<'de>>(self, mut a: A) -> Result<Value, A::Error> {
+            let mut out = Vec::new();
+            while let Some(v) = a.next_element::<StrictValue>()? {
+                out.push(v.0);
+            }
+            Ok(Value::Array(out))
+        }
+        fn visit_map<A: serde::de::MapAccess<'de>>(self, mut a: A) -> Result<Value, A::Error> {
+            let mut out = serde_json::Map::new();
+            while let Some((k, v)) = a.next_entry::<String, StrictValue>()? {
+                if out.insert(k.clone(), v.0).is_some() {
+                    return Err(serde::de::Error::custom(format!("Duplicate field '{k}'")));
+                }
+            }
+            Ok(Value::Object(out))
+        }
+    }
+    d.deserialize_any(Strict)
+}
+struct StrictValue(Value);
+impl<'de> Deserialize<'de> for StrictValue {
+    fn deserialize<D: serde::Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
+        strict_value(d).map(Self)
+    }
+}
+
+#[derive(Deserialize)]
+enum ItemKind3 {
+    Information,
+    Material,
+    Energy,
+    Event,
+}
+#[derive(Deserialize)]
+#[serde(deny_unknown_fields)]
+enum Definition3 {
+    Boolean,
+    Integer,
+    Real,
+    String,
+    Enumeration { literals: Vec<String> },
+    Record,
+}
+#[derive(Deserialize)]
+#[serde(deny_unknown_fields)]
+struct Item3 {
+    kind: ItemKind3,
+}
+#[derive(Deserialize)]
+#[serde(deny_unknown_fields)]
+struct Type3 {
+    definition: Definition3,
+}
+#[derive(Deserialize)]
+#[serde(deny_unknown_fields)]
+struct Field3 {
+    type_ref: TypeRef,
+    minimum: u32,
+    maximum: Option<u32>,
+    unit: String,
+}
+#[derive(Deserialize)]
+#[serde(deny_unknown_fields)]
+struct Interface3 {
+    items: Vec<Id>,
+}
+#[derive(Deserialize)]
+#[serde(deny_unknown_fields)]
+struct MessageValue3 {
+    field: Id,
+    expression: String,
+}
+
+pub(crate) fn relation_allowed(name: &str) -> bool {
+    matches!(
+        name,
+        "Allocation"
+            | "PortAllocation"
+            | "Interaction"
+            | "CapabilityInvolvement"
+            | "ChainInvolvement"
+            | "RoleRealization"
+            | "RoleAssignment"
+            | "FunctionalExchange"
+            | "BoundaryExchange"
+            | "MissionCapability"
+            | "CapabilityInclude"
+            | "CapabilityExtend"
+            | "CapabilityGeneralization"
+            | "MissionInvolvement"
+            | "SequenceLink"
+            | "StateTransition"
+            | "Availability"
+            | "ExchangeAllocation"
+            | "InterfaceProvision"
+            | "InterfaceRequirement"
+            | "StateAction"
+    )
+}
+pub(crate) fn element_allowed(name: &str) -> bool {
+    matches!(
+        name,
+        "Entity"
+            | "Actor"
+            | "Role"
+            | "Activity"
+            | "Capability"
+            | "OperationalMission"
+            | "Process"
+            | "System"
+            | "SystemActor"
+            | "Function"
+            | "SystemCapability"
+            | "Mission"
+            | "FunctionalChain"
+            | "ExchangeItem"
+            | "DataType"
+            | "DataField"
+            | "Interface"
+            | "Port"
+            | "Scenario"
+            | "Lifeline"
+            | "Occurrence"
+            | "StateMachine"
+            | "Region"
+            | "State"
+            | "Mode"
+            | "Initial"
+            | "Final"
+            | "Choice"
+            | "Junction"
+            | "Fork"
+            | "Join"
+            | "ShallowHistory"
+            | "DeepHistory"
+            | "EntryPoint"
+            | "ExitPoint"
+            | "Terminate"
+            | "Event"
+            | "Constraint"
+    )
+}
+pub(crate) fn legacy_defaults(kind: Kind) -> Option<Value> {
+    Some(match kind {
+        Kind::ExchangeItem => json!({"kind":"Information"}),
+        Kind::DataType => json!({"definition":"String"}),
+        Kind::DataField => json!({"type_ref":"String","minimum":1,"maximum":1,"unit":""}),
+        Kind::Interface => json!({"items":[]}),
+        _ => return None,
+    })
+}
+
+fn at(id: Id, field: &str, code: &str, message: impl Into<String>) -> FileError {
+    let message = message.into();
+    FileError::Model {
+        message: format!("V3 {code} at {id}.{field}: {message}"),
+        issues: vec![validation::Issue {
+            severity: validation::Severity::Error,
+            element: Some(id),
+            code: code.into(),
+            field: Some(field.into()),
+            message,
+        }],
+    }
+}
+fn singleton(value: &Value) -> Option<(&str, &Value)> {
+    let object = value.as_object()?;
+    (object.len() == 1)
+        .then(|| object.iter().next().unwrap())
+        .map(|(k, v)| (k.as_str(), v))
+}
+fn old_payload<T: serde::de::DeserializeOwned>(
+    id: Id,
+    field: &str,
+    value: Value,
+) -> Result<T, FileError> {
+    serde_json::from_value(value).map_err(|error| at(id, field, "legacy_shape", error.to_string()))
+}
+
+pub(crate) fn migrate(old: Project3, limits: ParseLimits) -> Result<DecodeResult, FileError> {
+    if old.schema_version != 3 {
+        return Err(FileError::Invalid("Expected schema_version 3.".into()));
+    }
+    let graph = old.elements.len().saturating_add(old.relations.len());
+    let records = graph
+        .saturating_add(old.diagrams.len())
+        .saturating_add(old.diagrams.values().map(|d| d.nodes.len()).sum::<usize>())
+        .saturating_add(old.traces.len())
+        .saturating_add(old.artifact_links.len())
+        .saturating_add(1);
+    limits
+        .check_counts(graph, records, 0)
+        .map_err(FileError::Limit)?;
+    let mut report = MigrationReport::data_upgrade(3);
+    let mut value = serde_json::to_value(&old)?;
+    let mut allocations = Vec::new();
+    for (key, e) in &old.elements {
+        if *key != e.id {
+            return Err(at(
+                e.id,
+                "id",
+                "identity",
+                "Element map key differs from its identity.",
+            ));
+        }
+        let mut body = e.body.clone();
+        let (layer, inner) = singleton(&body)
+            .filter(|(name, _)| matches!(*name, "Oa" | "Sa"))
+            .ok_or_else(|| {
+                at(
+                    e.id,
+                    "body",
+                    "legacy_shape",
+                    "Expected one OA or SA constructor.",
+                )
+            })?;
+        let layer = layer.to_owned();
+        let outer = inner
+            .as_str()
+            .or_else(|| singleton(inner).map(|(name, _)| name));
+        if !outer.is_some_and(|name| {
+            if layer == "Oa" {
+                matches!(
+                    name,
+                    "Entity"
+                        | "Actor"
+                        | "Role"
+                        | "Activity"
+                        | "Capability"
+                        | "Mission"
+                        | "Process"
+                        | "Shared"
+                )
+            } else {
+                matches!(
+                    name,
+                    "System"
+                        | "Actor"
+                        | "Function"
+                        | "Capability"
+                        | "Mission"
+                        | "FunctionalChain"
+                        | "Shared"
+                )
+            }
+        }) {
+            return Err(at(
+                e.id,
+                "body",
+                "legacy_shape",
+                "Unknown schema3 layer constructor.",
+            ));
+        }
+        if let Some(("Shared", shared)) = singleton(inner) {
+            let name = shared
+                .as_str()
+                .or_else(|| singleton(shared).map(|(name, _)| name))
+                .ok_or_else(|| {
+                    at(
+                        e.id,
+                        "body",
+                        "legacy_shape",
+                        "Expected one schema3 shared constructor.",
+                    )
+                })?
+                .to_owned();
+            if !matches!(
+                name.as_str(),
+                "ExchangeItem"
+                    | "DataType"
+                    | "DataField"
+                    | "Interface"
+                    | "Port"
+                    | "Scenario"
+                    | "Lifeline"
+                    | "Occurrence"
+                    | "StateMachine"
+                    | "Event"
+                    | "Region"
+                    | "State"
+                    | "Constraint"
+            ) {
+                return Err(at(
+                    e.id,
+                    "body",
+                    "legacy_shape",
+                    format!("Unknown schema3 shared constructor '{name}'."),
+                ));
+            }
+            let payload = shared.get(&name).cloned().unwrap_or(Value::Null);
+            let changed = match name.as_str() {
+                "ExchangeItem" => {
+                    let old: Item3 = old_payload(e.id, "body.kind", payload)?;
+                    let (kind, mechanism) = match old.kind {
+                        ItemKind3::Information => ("Information", "Unspecified"),
+                        ItemKind3::Material => ("Material", "Unspecified"),
+                        ItemKind3::Energy => ("Energy", "Unspecified"),
+                        ItemKind3::Event => ("Information", "Event"),
+                    };
+                    Some(json!({"kind":kind,"mechanism":mechanism,"supertype":null}))
+                }
+                "DataType" => {
+                    let old: Type3 = old_payload(e.id, "body.definition", payload)?;
+                    let definition = match old.definition {
+                        Definition3::Boolean => json!("Boolean"),
+                        Definition3::Integer => json!({"Integer":{"minimum":null,"maximum":null}}),
+                        Definition3::Real => json!({"Real":{"minimum":null,"maximum":null}}),
+                        Definition3::String => {
+                            json!({"String":{"minimum_length":0,"maximum_length":null}})
+                        }
+                        Definition3::Enumeration { literals } => {
+                            json!({"Enumeration":{"literals":literals}})
+                        }
+                        Definition3::Record => json!({"Record":{"supertype":null}}),
+                    };
+                    Some(json!({"definition":definition,"default":null,"unit":""}))
+                }
+                "DataField" => {
+                    let old: Field3 = old_payload(e.id, "body", payload)?;
+                    Some(
+                        json!({"type_ref":old.type_ref,"minimum":old.minimum,"maximum":old.maximum,"unit":old.unit,"direction":"Unspecified","storage":"Value","default":null}),
+                    )
+                }
+                "Interface" => {
+                    let old: Interface3 = old_payload(e.id, "items", payload)?;
+                    let mut seen = BTreeSet::new();
+                    for (order, item) in old.items.into_iter().enumerate() {
+                        if !seen.insert(item) {
+                            return Err(at(
+                                e.id,
+                                "items",
+                                "duplicate_reference",
+                                "Interface items must be unique.",
+                            ));
+                        }
+                        allocations.push((e.id, item, order));
+                    }
+                    Some(json!({"supertype":null}))
+                }
+                "Occurrence" => {
+                    let mut payload = payload;
+                    if let Some(values) = payload.pointer_mut("/body/Exchange/values") {
+                        let old: Vec<MessageValue3> =
+                            old_payload(e.id, "body.values", values.clone())?;
+                        *values=Value::Array(old.into_iter().map(|v|json!({"field":v.field,"expression":v.expression,"path":[]})).collect());
+                    }
+                    Some(payload)
+                }
+                _ => None,
+            };
+            if let Some(changed) = changed {
+                let description = match name.as_str() {
+                    "ExchangeItem" if changed["mechanism"] == "Event" => {
+                        "Legacy Event nature becomes Information with Event mechanism; supertype is absent."
+                    }
+                    "ExchangeItem" => {
+                        "Nature is retained; mechanism is Unspecified and supertype is absent."
+                    }
+                    "DataType" => {
+                        "Existing type is retained with unbounded numeric/string limits, no scalar default or unit, and no Record supertype."
+                    }
+                    "DataField" => {
+                        "Type, ownership, multiplicity and unit are retained; direction is Unspecified, storage is Value and default is absent."
+                    }
+                    "Interface" => {
+                        "Items become identified ordered allocations with Unspecified protocols; supertype is absent."
+                    }
+                    _ => {
+                        "Value expressions are retained; unique enclosing field paths are resolved and ambiguous legacy paths remain unresolved."
+                    }
+                };
+                body[&layer]["Shared"][&name] = changed;
+                report
+                    .semantic_defaults
+                    .push(crate::persistence::SemanticDefault {
+                        object: e.id,
+                        field: "body".into(),
+                        description: description.into(),
+                    });
+            }
+        }
+        // Current deserialization checks the reused, unchanged outer/typed parts.
+        let _: ElementBody = serde_json::from_value(body.clone())
+            .map_err(|error| at(e.id, "body", "legacy_shape", error.to_string()))?;
+        value["elements"][key.to_string()]["body"] = body;
+    }
+    for (key, r) in &old.relations {
+        if *key != r.id {
+            return Err(at(
+                r.id,
+                "id",
+                "identity",
+                "Relation map key differs from its identity.",
+            ));
+        }
+        if !singleton(&r.body).is_some_and(|(name, _)| relation_allowed(name)) {
+            return Err(at(
+                r.id,
+                "body",
+                "legacy_shape",
+                "Relation constructor was not part of schema3.",
+            ));
+        }
+    }
+    value["schema_version"] = SCHEMA_VERSION.into();
+    let mut project: Project = serde_json::from_value(value)?;
+    let mut references = project
+        .elements
+        .values()
+        .map(|e| e.steps().map_or(0, Vec::len))
+        .sum::<usize>()
+        .saturating_add(allocations.len().saturating_mul(2));
+    limits
+        .check_counts(
+            project
+                .elements
+                .len()
+                .saturating_add(project.relations.len())
+                .saturating_add(allocations.len()),
+            project.identities().len().saturating_add(allocations.len()),
+            references,
+        )
+        .map_err(FileError::Limit)?;
+    let mut ids: BTreeSet<_> = project.identities().into_iter().map(|(id, _)| id).collect();
+    for (source, target, order) in allocations {
+        let id = Id::new_v5(
+            &project.id,
+            format!("v2-interface-item:{source}:{target}").as_bytes(),
+        );
+        if !ids.insert(id) {
+            return Err(at(
+                source,
+                "items",
+                "identity_collision",
+                format!(
+                    "Deterministic interface allocation {id} already belongs to another object."
+                ),
+            ));
+        }
+        let name = format!("{} · {}", project.named(source), project.named(target));
+        let alias = project.fresh_alias(
+            &format!(
+                "{}_{}_allocation",
+                project
+                    .elements
+                    .get(&source)
+                    .map_or("interface", |e| e.alias.as_str()),
+                project
+                    .elements
+                    .get(&target)
+                    .map_or("item", |e| e.alias.as_str())
+            ),
+            "interface_item_allocation",
+            id,
+        );
+        project.relations.insert(
+            id,
+            Relation {
+                id,
+                alias: alias.clone(),
+                name,
+                description: String::new(),
+                body: RelationBody::InterfaceItemAllocation {
+                    source,
+                    target,
+                    order: order.try_into().map_err(|_| {
+                        at(source, "items", "model_limit", "Too many interface items.")
+                    })?,
+                    transmission: TransmissionProtocol::Unspecified,
+                    acquisition: AcquisitionProtocol::Unspecified,
+                },
+            },
+        );
+        report.generated_interface_allocations.push(
+            crate::persistence::GeneratedInterfaceAllocation {
+                id,
+                source,
+                target,
+                alias,
+                order: order as u32,
+            },
+        );
+    }
+    let annotations: Vec<_> = project
+        .elements
+        .values()
+        .filter_map(|e| match e.shared() {
+            Some(SharedBody::Occurrence {
+                body:
+                    OccurrenceBody::Exchange {
+                        exchange: Some(exchange),
+                        values,
+                        ..
+                    },
+                ..
+            }) => Some((e.id, *exchange, values.clone())),
+            _ => None,
+        })
+        .collect();
+    for (owner, exchange, values) in annotations {
+        let Some(relation) = project.relations.get(&exchange) else {
+            continue;
+        };
+        for (index, value) in values.into_iter().enumerate() {
+            let resolution =
+                crate::data::resolve_legacy_field_path(&project, relation, value.field)
+                    .map_err(|message| at(owner, "body.values", "model_limit", message))?;
+            if let crate::data::LegacyFieldPathResolution::Unique(path) = resolution {
+                if !path.is_empty() {
+                    references = references.saturating_add(path.len());
+                    limits
+                        .check_counts(
+                            project
+                                .elements
+                                .len()
+                                .saturating_add(project.relations.len()),
+                            project.identities().len(),
+                            references,
+                        )
+                        .map_err(FileError::Limit)?;
+                    if let Some(SharedBody::Occurrence {
+                        body: OccurrenceBody::Exchange { values, .. },
+                        ..
+                    }) = project
+                        .elements
+                        .get_mut(&owner)
+                        .and_then(Element::shared_mut)
+                    {
+                        values[index].path = path;
+                    }
+                }
+            } else if matches!(
+                resolution,
+                crate::data::LegacyFieldPathResolution::Ambiguous
+            ) {
+                report.unresolved_message_values.push(crate::persistence::UnresolvedMessageValue { occurrence:owner,field:value.field,reason:"Several carried paths reach this legacy field; choose an explicit argument path.".into() });
+            }
+        }
+    }
+    limits.check_model(&project).map_err(FileError::Limit)?;
+    super::validate_project(&project)?;
+    Ok(DecodeResult {
+        project,
+        migration: Some(report),
+    })
+}

crates/oa-core/src/persistence.rs

@@ -5,6 +5,8 @@ use thiserror::Error;
 #[path = "migration_v2/mod.rs"]
 pub(crate) mod v2;
 pub(crate) use v2::adapter::migrate as migrate_v2_limited;
+#[path = "migration_v3/mod.rs"]
+pub(crate) mod v3;
 
 #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
 #[serde(deny_unknown_fields)]
@@ -15,6 +17,50 @@ pub struct MigrationReport {
     pub generated_endpoints: Vec<GeneratedEndpoint>,
     pub orientation_defaults: Vec<OrientationDefault>,
     pub required_resolutions: Vec<Id>,
+    #[serde(default)]
+    pub semantic_defaults: Vec<SemanticDefault>,
+    #[serde(default)]
+    pub generated_interface_allocations: Vec<GeneratedInterfaceAllocation>,
+    #[serde(default)]
+    pub unresolved_message_values: Vec<UnresolvedMessageValue>,
+}
+impl MigrationReport {
+    pub(crate) fn data_upgrade(from_schema: u32) -> Self {
+        Self {
+            from_schema,
+            to_schema: SCHEMA_VERSION,
+            preserved_ports: vec![],
+            generated_endpoints: vec![],
+            orientation_defaults: vec![],
+            required_resolutions: vec![],
+            semantic_defaults: vec![],
+            generated_interface_allocations: vec![],
+            unresolved_message_values: vec![],
+        }
+    }
+}
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct SemanticDefault {
+    pub object: Id,
+    pub field: String,
+    pub description: String,
+}
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct GeneratedInterfaceAllocation {
+    pub id: Id,
+    pub source: Id,
+    pub target: Id,
+    pub alias: String,
+    pub order: u32,
+}
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct UnresolvedMessageValue {
+    pub occurrence: Id,
+    pub field: Id,
+    pub reason: String,
 }
 #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
 #[serde(deny_unknown_fields)]
@@ -101,13 +147,14 @@ pub fn decode_with_report_limited(
                 migrate_v1_with_report_limited(old, limits)?
             }
             Some(2) => migrate_v2_limited(serde_json::from_slice(bytes)?, limits)?,
-            Some(3) => DecodeResult {
+            Some(3) => v3::migrate(serde_json::from_slice(bytes)?, limits)?,
+            Some(4) => DecodeResult {
                 project: serde_json::from_slice(bytes)?,
                 migration: None,
             },
             _ => {
                 return Err(FileError::Invalid(
-                    "Unsupported or missing schema_version; expected 1, 2 or 3.".into(),
+                    "Unsupported or missing schema_version; expected 1, 2, 3 or 4.".into(),
                 ));
             }
         }

crates/oa-core/src/source_files.rs

@@ -999,7 +999,7 @@ mod transaction_tests {
         let directory = tempfile::tempdir().unwrap();
         fs::write(
             directory.path().join("project.arcadia"),
-            "arcadia 3; project p \"P\" { include \"a.arcadia\"; include \"b.arcadia\"; }",
+            "arcadia 4; project p \"P\" { include \"a.arcadia\"; include \"b.arcadia\"; }",
         )
         .unwrap();
         fs::write(directory.path().join("a.arcadia"), "oa_activity a \"A\" {}").unwrap();

crates/oa-core/src/source_project.rs

@@ -1,9 +1,11 @@
-//! Pure, bounded source3 projects. All includes resolve against supplied UTF-8
+//! Pure, bounded source projects. All includes resolve against supplied UTF-8
 //! documents; this module never reads a filesystem, URL, or process directory.
 use crate::{Id, Kind, Project, language, persistence::DecodeResult, validation};
 use language::{Diagnostic, ParseLimits, Span};
 use serde::{Deserialize, Serialize};
 use std::collections::{BTreeMap, BTreeSet};
+#[path = "source_project/source_migration.rs"]
+mod source_migration;
 #[path = "source_project/source_structure.rs"]
 mod source_structure;
 
@@ -278,21 +280,24 @@ pub fn lint_bundle(bundle: &SourceBundle, limits: ProjectLimits) -> Vec<SourceDi
     }
 }
 
-/// Compile all reachable files as one source3 model and stabilize omitted UUIDs.
+/// Compile reachable source3/4 files, explicitly upgrade data contracts, and stabilize UUIDs.
 /// Missing/unreachable files and every admission or engineering error leave the
 /// input untouched. V1/V2 single-file migration remains in `language::parse`.
 pub fn compile_bundle(
     bundle: &SourceBundle,
     limits: ProjectLimits,
 ) -> Result<CompiledSourceProject, Vec<SourceDiagnostic>> {
-    let (compiled, insertions) = compile_once(bundle, limits)?;
-    if insertions.is_empty() {
-        return Ok(compiled);
+    let (mut compiled, insertions) = compile_once(bundle, limits)?;
+    if !insertions.is_empty() {
+        let mut stable = bundle.clone();
+        apply_edits(&mut stable, insertions)?;
+        // Re-index actual returned bytes before performing the schema upgrade.
+        compiled = compile_once(&stable, limits)?.0;
     }
-    let mut stable = bundle.clone();
-    apply_edits(&mut stable, insertions)?;
-    // Re-index the actual returned bytes. Never expose offsets into pre-ID text.
-    compile_once(&stable, limits).map(|(compiled, _)| compiled)
+    if compiled.decoded.migration.is_some() {
+        return source_migration::upgrade(&compiled, limits);
+    }
+    Ok(compiled)
 }
 
 fn compile_once(
@@ -568,7 +573,7 @@ fn compile_once(
             span,
         }),
     };
-    let project =
+    let decoded =
         language::resolve_declarations(header.project, &declarations, &aliases, limits.model)
             .map_err(|(index, error)| {
                 let path = declaration_paths.get(index).unwrap_or(&bundle.entry);
@@ -578,7 +583,7 @@ fn compile_once(
                     related: Vec::new(),
                 }]
             })?;
-    let diagnostics = model_diagnostics(bundle, &index, &project);
+    let diagnostics = model_diagnostics(bundle, &index, &decoded.project);
     let errors: Vec<_> = diagnostics
         .iter()
         .filter(|issue| issue.diagnostic.severity == validation::Severity::Error)
@@ -590,10 +595,7 @@ fn compile_once(
     Ok((
         CompiledSourceProject {
             bundle: bundle.clone(),
-            decoded: DecodeResult {
-                project,
-                migration: None,
-            },
+            decoded,
             index,
             diagnostics,
         },
@@ -718,7 +720,7 @@ fn apply_edits(bundle: &mut SourceBundle, edits: Edits) -> Result<(), Vec<Source
     Ok(())
 }
 
-/// Canonical, readable source3 export. Like `language::format`, the caller is
+/// Canonical, readable source4 export. Like `language::format`, the caller is
 /// responsible for supplying a valid model; compilation checks the result.
 /// Existing source layout is preserved by `update_bundle`, not this formatter.
 pub fn format_bundle(project: &Project) -> SourceBundle {
@@ -734,7 +736,7 @@ pub fn format_bundle(project: &Project) -> SourceBundle {
             .push_str(&unindent(&declaration));
     }
     let mut entry = format!(
-        "arcadia 3;\n{}{{\n    description {};\n",
+        "arcadia 4;\n{}{{\n    description {};\n",
         project_header(project),
         quote(&project.description)
     );
@@ -923,6 +925,7 @@ pub fn update_bundle_with_identity_map(
                 after: new_text,
                 old_aliases: &old_aliases,
                 new_aliases: &new_aliases,
+                legacy_value_paths: false,
             };
             let local = edits.entry(path.clone()).or_default();
             update.header(&actual.header, &previous.header, &next.header, local);
@@ -951,6 +954,7 @@ pub fn update_bundle_with_identity_map(
             after: &after,
             old_aliases: &old_aliases,
             new_aliases: &new_aliases,
+            legacy_value_paths: false,
         };
         let mut local = Vec::new();
         update.header(
@@ -1119,6 +1123,9 @@ struct SyntaxUpdate<'a> {
     after: &'a str,
     old_aliases: &'a BTreeMap<String, String>,
     new_aliases: &'a BTreeMap<String, String>,
+    // Source3 migration only adds path qualification; the existing field identity
+    // must keep its authored argument trivia during that one-time transformation.
+    legacy_value_paths: bool,
 }
 impl SyntaxUpdate<'_> {
     fn header(
@@ -1338,11 +1345,11 @@ impl SyntaxUpdate<'_> {
         let previous = before.unwrap_or(&[]);
         let old_keys: Option<Vec<_>> = previous
             .iter()
-            .map(|item| item_key(item, self.before, self.old_aliases))
+            .map(|item| item_key(item, self.before, self.old_aliases, self.legacy_value_paths))
             .collect();
         let new_keys: Option<Vec<_>> = after
             .iter()
-            .map(|item| item_key(item, self.after, self.new_aliases))
+            .map(|item| item_key(item, self.after, self.new_aliases, self.legacy_value_paths))
             .collect();
         let keyed = old_keys.zip(new_keys).filter(|(old, new)| {
             old.iter().collect::<BTreeSet<_>>().len() == old.len()
@@ -1449,6 +1456,7 @@ fn item_key(
     value: &language::EditValue,
     source: &str,
     aliases: &BTreeMap<String, String>,
+    legacy_value_paths: bool,
 ) -> Option<String> {
     use language::EditKind;
     match &value.kind {
@@ -1462,7 +1470,31 @@ fn item_key(
             .find_map(|key| {
                 fields.get(key).and_then(|field| {
                     if let EditKind::Reference(alias) = &field.value.kind {
-                        aliases.get(alias).map(|id| format!("{key}:{id}"))
+                        aliases.get(alias).map(|id| {
+                            if key == "field" && !legacy_value_paths {
+                                let path = fields
+                                    .get("path")
+                                    .and_then(|field| {
+                                        if let EditKind::List(path) = &field.value.kind {
+                                            path.iter()
+                                                .map(|hop| {
+                                                    if let EditKind::Reference(alias) = &hop.kind {
+                                                        aliases.get(alias).cloned()
+                                                    } else {
+                                                        None
+                                                    }
+                                                })
+                                                .collect::<Option<Vec<_>>>()
+                                        } else {
+                                            None
+                                        }
+                                    })
+                                    .unwrap_or_default();
+                                format!("field:{}:{id}", path.join("/"))
+                            } else {
+                                format!("{key}:{id}")
+                            }
+                        })
                     } else {
                         None
                     }

crates/oa-core/src/source_project/source_migration.rs

@@ -0,0 +1,125 @@
+//! Source3 data upgrade through token edits; authored modules, nesting and trivia survive.
+use super::*;
+
+pub(super) fn upgrade(
+    current: &CompiledSourceProject,
+    limits: ProjectLimits,
+) -> Result<CompiledSourceProject, Vec<SourceDiagnostic>> {
+    let report = current
+        .decoded
+        .migration
+        .as_ref()
+        .expect("an explicit source migration report");
+    let project = &current.decoded.project;
+    let canonical: BTreeMap<_, _> = language::format_declarations(project).into_iter().collect();
+    let changed: BTreeSet<_> = report
+        .semantic_defaults
+        .iter()
+        .map(|default| default.object)
+        .collect();
+    let aliases: BTreeMap<_, _> = project
+        .identities()
+        .into_iter()
+        .map(|(id, alias)| (alias.to_owned(), id.to_string()))
+        .collect();
+    let mut edits: Edits = BTreeMap::new();
+    for (path, source) in &current.bundle.files {
+        let declarations =
+            language::edit_declarations(source, path == &current.bundle.entry, limits.model)
+                .map_err(|diagnostic| {
+                    vec![SourceDiagnostic {
+                        path: path.clone(),
+                        diagnostic: *diagnostic,
+                        related: vec![],
+                    }]
+                })?;
+        for (id, actual) in declarations {
+            if !changed.contains(&id) {
+                continue;
+            }
+            let Some(after) = canonical.get(&id) else {
+                continue;
+            };
+            let mut next = language::edit_declaration(after).map_err(|diagnostic| {
+                vec![SourceDiagnostic {
+                    path: path.clone(),
+                    diagnostic: *diagnostic,
+                    related: vec![],
+                }]
+            })?;
+            if actual.lexical_owner.is_some()
+                && let language::EditKind::Record(fields) = &actual.fields.kind
+                && !fields.contains_key("parent")
+                && let language::EditKind::Record(fields) = &mut next.fields.kind
+            {
+                fields.remove("parent");
+            }
+            let update = SyntaxUpdate {
+                source,
+                before: source,
+                after,
+                old_aliases: &aliases,
+                new_aliases: &aliases,
+                legacy_value_paths: true,
+            };
+            update.value(
+                &actual.fields,
+                Some(&actual.fields),
+                &next.fields,
+                edits.entry(path.clone()).or_default(),
+            );
+        }
+    }
+    let source = &current.bundle.files[&current.bundle.entry];
+    let version = significant(source)
+        .get(1)
+        .map(|token| token.span)
+        .expect("a parsed version token");
+    edits
+        .entry(current.bundle.entry.clone())
+        .or_default()
+        .push((version, "4".into()));
+    // New allocation relations are emitted into the allocating interface's
+    // existing module, outside its lexical element body. Existing source never moves.
+    let mut added: BTreeMap<String, String> = BTreeMap::new();
+    for allocation in &report.generated_interface_allocations {
+        let path = current
+            .index
+            .declarations
+            .get(&allocation.source)
+            .map(|location| location.path.clone())
+            .unwrap_or_else(|| current.bundle.entry.clone());
+        let ending = newline(&current.bundle.files[&path]);
+        let text = added.entry(path).or_default();
+        text.push_str(ending);
+        text.push_str(&canonical[&allocation.id].replace('\n', ending));
+    }
+    for (path, text) in added {
+        let offset = if path == current.bundle.entry {
+            current.index.project_body.span.end
+        } else {
+            current.bundle.files[&path].len()
+        };
+        edits.entry(path).or_default().push((
+            Span {
+                start: offset,
+                end: offset,
+            },
+            text,
+        ));
+    }
+    let mut bundle = current.bundle.clone();
+    apply_edits(&mut bundle, edits)?;
+    let (mut result, insertions) = compile_once(&bundle, limits)?;
+    if !insertions.is_empty() || result.decoded.project != *project {
+        return Err(vec![problem(
+            &bundle,
+            &bundle.entry,
+            Span::default(),
+            "migration_source_mismatch",
+            "Targeted source3 upgrade did not reproduce the migrated project.",
+        )]);
+    }
+    result.decoded.migration = Some(report.clone());
+    Ok(result)
+}