Publish in-progress navigation source and independent canvas reviews

crates/oa-core/src/language.rs

@@ -142,12 +142,87 @@ pub struct Analysis {
     pub declarations: Vec<DeclarationSpan>,
 }
 
+/// Check the decoded spelling required by declaration-header UUID clauses.
+/// This is the shared 36-byte/hyphen shape rule, not a hexadecimal parser:
+/// callers must additionally parse the UUID. Uppercase hex and JSON escapes
+/// that decode to this spelling remain accepted. URN/braced/compact forms do not.
+pub fn has_uuid_header_shape(decoded: &str) -> bool {
+    decoded.len() == 36
+        && [8, 13, 18, 23]
+            .into_iter()
+            .all(|index| decoded.as_bytes()[index] == b'-')
+}
+
+/// Budgets for one original source buffer. Policy is caller-owned; these
+/// limits do not change the grammar or perform model admission.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct OutlineLimits {
+    pub max_source_bytes: usize,
+    pub max_tokens: usize,
+    pub max_declarations: usize,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum OutlineResource {
+    SourceBytes,
+    Tokens,
+    Declarations,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct OutlineLimit {
+    pub resource: OutlineResource,
+    pub limit: usize,
+    pub observed_at_least: usize,
+    /// Original byte offset where admission stopped; never a rewritten offset.
+    pub offset: usize,
+}
+
+/// Roles discovered by the existing tolerant declaration walk. Keeping the
+/// wrapper preserves DeclarationSpan and Analysis as existing public APIs.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct OutlineDeclaration {
+    pub declaration: DeclarationSpan,
+    pub kind_span: Span,
+    pub alias_span: Span,
+    /// Whole quoted header ID token, even if it is not a valid UUID. In that
+    /// case declaration.id is None. Missing/non-string ID values have no span.
+    pub id_literal_span: Option<Span>,
+}
+
+/// A full-file tolerant scan, not a successful parse or validated model. Invalid
+/// text remains available. Lexical errors and unmatched braces are facts only:
+/// their absence does not establish syntactic or semantic validity.
+///
+/// A budget failure returns Err and no partial Outline. Include reachability,
+/// project completeness and editor revision are intentionally not inferred here.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct Outline<'a> {
+    pub source: &'a str,
+    pub tokens: Vec<TokenSpan>,
+    pub declarations: Vec<OutlineDeclaration>,
+    pub has_lexical_errors: bool,
+    pub has_unmatched_braces: bool,
+}
+
 /// Tolerant highlighting tokens cover the whole input, including incomplete
 /// strings and unexpected characters. No model is created or modified.
 pub fn tokenize(source: &str) -> Vec<TokenSpan> {
+    tokenize_with_limit(source, usize::MAX).expect("unlimited token scan")
+}
+
+fn tokenize_with_limit(source: &str, max_tokens: usize) -> Result<Vec<TokenSpan>, OutlineLimit> {
     let mut tokens = Vec::new();
     let mut cursor = 0;
     while cursor < source.len() {
+        if tokens.len() == max_tokens {
+            return Err(OutlineLimit {
+                resource: OutlineResource::Tokens,
+                limit: max_tokens,
+                observed_at_least: tokens.len().saturating_add(1),
+                offset: cursor,
+            });
+        }
         let start = cursor;
         let ch = source[cursor..].chars().next().expect("in bounds");
         let class = if matches!(ch, ' ' | '\t' | '\r' | '\n') {
@@ -224,7 +299,7 @@ pub fn tokenize(source: &str) -> Vec<TokenSpan> {
             span: Span { start, end: cursor },
         });
     }
-    tokens
+    Ok(tokens)
 }
 
 pub fn lint(source: &str) -> Vec<Diagnostic> {
@@ -1230,11 +1305,7 @@ impl Parser<'_> {
         self.cursor += 1;
         let offset = self.current().span.start;
         let value = self.quoted()?;
-        if value.len() != 36
-            || ![8, 13, 18, 23]
-                .into_iter()
-                .all(|i| value.as_bytes()[i] == b'-')
-        {
+        if !has_uuid_header_shape(&value) {
             return Err(Error {
                 code: "invalid_source",
                 offset,
@@ -1962,8 +2033,49 @@ fn take_required_id(fields: &mut Map<String, Value>, key: &str) -> Result<Id, St
 
 /// Analyze an incomplete source buffer without adopting a candidate. Declaration
 /// spans remain available even when a later declaration contains errors.
+/// Invalid compact/braced/URN header IDs retain no authored identity, matching
+/// the declaration parser rather than the UUID crate's broader accepted forms.
 pub fn analyze(source: &str) -> Analysis {
     let tokens = tokenize(source);
+    let (declarations, _) =
+        declaration_outline(source, &tokens, usize::MAX).expect("unlimited declaration walk");
+    Analysis {
+        tokens,
+        diagnostics: lint(source),
+        declarations: declarations.into_iter().map(|d| d.declaration).collect(),
+    }
+}
+
+/// Read exact current text without lint, parsing a model, stabilization or I/O.
+/// Source bytes are admitted before token allocation; token/declaration limits
+/// are checked before lexing the next token or materializing the next record.
+pub fn outline(source: &str, limits: OutlineLimits) -> Result<Outline<'_>, OutlineLimit> {
+    if source.len() > limits.max_source_bytes {
+        return Err(OutlineLimit {
+            resource: OutlineResource::SourceBytes,
+            limit: limits.max_source_bytes,
+            observed_at_least: source.len(),
+            offset: 0,
+        });
+    }
+    let tokens = tokenize_with_limit(source, limits.max_tokens)?;
+    let has_lexical_errors = tokens.iter().any(|token| token.class == TokenClass::Error);
+    let (declarations, has_unmatched_braces) =
+        declaration_outline(source, &tokens, limits.max_declarations)?;
+    Ok(Outline {
+        source,
+        tokens,
+        declarations,
+        has_lexical_errors,
+        has_unmatched_braces,
+    })
+}
+
+fn declaration_outline(
+    source: &str,
+    tokens: &[TokenSpan],
+    max_declarations: usize,
+) -> Result<(Vec<OutlineDeclaration>, bool), OutlineLimit> {
     let significant = tokens
         .iter()
         .filter(|t| !matches!(t.class, TokenClass::Whitespace | TokenClass::Comment))
@@ -1972,17 +2084,21 @@ pub fn analyze(source: &str) -> Analysis {
     // again would make tolerant navigation quadratic on deeply nested drafts.
     let mut body_ends = vec![None; significant.len()];
     let mut bodies = Vec::new();
+    let mut unmatched_close = false;
     for (index, token) in significant.iter().enumerate() {
         match &source[token.span.start..token.span.end] {
             "{" => bodies.push(index),
             "}" => {
                 if let Some(open) = bodies.pop() {
                     body_ends[open] = Some(token.span.end);
+                } else {
+                    unmatched_close = true;
                 }
             }
             _ => {}
         }
     }
+    let has_unmatched_braces = unmatched_close || !bodies.is_empty();
     let mut declarations = Vec::new();
     for (i, t) in significant.iter().enumerate() {
         let word = &source[t.span.start..t.span.end];
@@ -2007,7 +2123,16 @@ pub fn analyze(source: &str) -> Analysis {
             }
             j += 1;
         }
+        if declarations.len() == max_declarations {
+            return Err(OutlineLimit {
+                resource: OutlineResource::Declarations,
+                limit: max_declarations,
+                observed_at_least: declarations.len().saturating_add(1),
+                offset: t.span.start,
+            });
+        }
         let mut id = None;
+        let mut id_literal_span = None;
         if significant
             .get(j)
             .is_some_and(|t| &source[t.span.start..t.span.end] == "id")
@@ -2015,39 +2140,51 @@ pub fn analyze(source: &str) -> Analysis {
             if let Some(value) = significant.get(j + 1)
                 && value.class == TokenClass::String
             {
+                id_literal_span = Some(value.span);
                 let text =
                     serde_json::from_str::<String>(&source[value.span.start..value.span.end])
                         .unwrap();
-                id = Id::parse_str(&text).ok();
+                if has_uuid_header_shape(&text) {
+                    id = Id::parse_str(&text).ok();
+                }
             }
             j += 2;
         }
-        let mut end = significant
-            .get(j)
-            .map_or(alias_token.span.end, |t| t.span.end);
+        // A recognized header ID at EOF must remain inside the whole span.
+        // Keep the old next-token/body behavior; only the EOF fallback changes.
+        let header_end = significant
+            .get(j.saturating_sub(1))
+            .or_else(|| significant.last())
+            .map_or(alias_token.span.end, |token| token.span.end);
+        let mut end = significant.get(j).map_or(header_end, |t| t.span.end);
         if significant
             .get(j)
             .is_some_and(|t| &source[t.span.start..t.span.end] == "{")
         {
             end = body_ends[j].unwrap_or(source.len());
         }
-        declarations.push(DeclarationSpan {
-            alias: alias.into(),
-            id,
-            kind: word.into(),
-            span: Span {
-                start: t.span.start,
-                end,
+        declarations.push(OutlineDeclaration {
+            declaration: DeclarationSpan {
+                alias: alias.into(),
+                id,
+                kind: word.into(),
+                span: Span {
+                    start: t.span.start,
+                    end,
+                },
             },
+            kind_span: t.span,
+            alias_span: alias_token.span,
+            id_literal_span,
         });
     }
-    Analysis {
-        tokens,
-        diagnostics: lint(source),
-        declarations,
-    }
+    Ok((declarations, has_unmatched_braces))
 }
 
+#[cfg(test)]
+#[path = "language_outline_tests.rs"]
+mod outline_tests;
+
 #[cfg(test)]
 #[path = "language_nesting_tests.rs"]
 mod nesting_tests;
@@ -2442,11 +2579,7 @@ pub(crate) mod legacy {
             let value = self.quoted()?;
             // Require the portable 8-4-4-4-12 spelling, not the UUID crate's URN,
             // braces, or compact alternatives. Uppercase hexadecimal is accepted.
-            if value.len() != 36
-                || ![8, 13, 18, 23]
-                    .into_iter()
-                    .all(|index| value.as_bytes()[index] == b'-')
-            {
+            if !super::has_uuid_header_shape(&value) {
                 return Err(Error {
                     code: "invalid_source",
                     offset,

crates/oa-core/src/language_outline_tests.rs

@@ -0,0 +1,386 @@
+//! Prepared outline tests. Explicit compatibility tests additionally exercise
+//! the existing parsers/analyze; the outline entry itself never calls them.
+use super::*;
+
+fn limits() -> OutlineLimits {
+    OutlineLimits {
+        max_source_bytes: 1024 * 1024,
+        max_tokens: 100_000,
+        max_declarations: 1_000,
+    }
+}
+
+fn declaration<'a>(result: &'a Outline<'_>, alias: &str) -> &'a OutlineDeclaration {
+    result
+        .declarations
+        .iter()
+        .find(|d| d.declaration.alias == alias)
+        .unwrap()
+}
+
+fn text(source: &str, span: Span) -> &str {
+    &source[span.start..span.end]
+}
+
+#[test]
+fn outline_roles_preserve_unicode_crlf_and_exact_escaped_uuid_literal() {
+    let source = "// 検査 🚒\r\noa_actor responder \"救助\" id \"\\u00300000000-0000-0000-0000-000000000001\" {}\r\nsource @ // 使用\r\n responder;";
+    let before = source.as_bytes().to_vec();
+    let result = outline(source, limits()).unwrap();
+    assert_eq!(result.source.as_bytes(), before);
+    assert_eq!(result.source.as_ptr(), source.as_ptr());
+    let d = declaration(&result, "responder");
+    assert_eq!(text(source, d.kind_span), "oa_actor");
+    assert_eq!(text(source, d.alias_span), "responder");
+    assert_eq!(
+        text(source, d.id_literal_span.unwrap()),
+        "\"\\u00300000000-0000-0000-0000-000000000001\""
+    );
+    assert_eq!(d.declaration.id, Some(Id::from_u128(1)));
+    assert_eq!(d.declaration.span.start, source.find("oa_actor").unwrap());
+    assert_eq!(d.declaration.span.end, source.find("{}\r\n").unwrap() + 2);
+    let mut end = 0;
+    for token in &result.tokens {
+        assert_eq!(token.span.start, end);
+        assert!(token.span.start < token.span.end);
+        assert!(source.is_char_boundary(token.span.start));
+        assert!(source.is_char_boundary(token.span.end));
+        end = token.span.end;
+    }
+    assert_eq!(end, source.len());
+    assert!(!result.has_lexical_errors);
+    assert!(!result.has_unmatched_braces);
+}
+
+#[test]
+fn closed_id_at_eof_is_inside_the_declaration_extent() {
+    for source in [
+        "oa_actor a \"Actor\" id \"00000000-0000-0000-0000-000000000001\"",
+        "node placed id \"00000000-0000-0000-0000-000000000001\"",
+    ] {
+        let result = outline(source, limits()).unwrap();
+        let d = &result.declarations[0];
+        let literal = d.id_literal_span.unwrap();
+        assert_eq!(d.declaration.id, Some(Id::from_u128(1)));
+        assert_eq!(d.declaration.span.end, source.len());
+        assert!(d.declaration.span.start <= literal.start);
+        assert!(literal.end <= d.declaration.span.end);
+    }
+    for source in ["oa_actor a \"Actor\"", "oa_actor a \"Actor\" id"] {
+        let result = outline(source, limits()).unwrap();
+        let d = &result.declarations[0];
+        assert_eq!(d.declaration.span.end, source.len());
+        assert_eq!(d.declaration.id, None);
+        assert_eq!(d.id_literal_span, None);
+    }
+}
+
+#[test]
+fn missing_bad_and_historical_ids_never_allocate_authored_identity() {
+    let source = "oa_actor missing \"No ID\" {}\noa_actor bad \"Bad ID\" id \"not-a-uuid\" {}\noa_actor historical \"00000000-0000-0000-0000-000000000001\" { history uuid \"00000000-0000-0000-0000-000000000001\"; }";
+    let first = outline(source, limits()).unwrap();
+    let second = outline(source, limits()).unwrap();
+    assert_eq!(first, second);
+    assert!(
+        first
+            .declarations
+            .iter()
+            .all(|d| d.declaration.id.is_none())
+    );
+    assert_eq!(declaration(&first, "missing").id_literal_span, None);
+    assert_eq!(declaration(&first, "historical").id_literal_span, None);
+    assert_eq!(
+        text(source, declaration(&first, "bad").id_literal_span.unwrap()),
+        "\"not-a-uuid\""
+    );
+    // Balanced tokens are not a successful syntax/semantic validation claim.
+    assert!(!first.has_lexical_errors);
+    assert!(!first.has_unmatched_braces);
+}
+
+#[test]
+fn invalid_full_scan_keeps_closed_children_and_reports_lexical_body_facts() {
+    let source = "oa_entity outer \"Outer\" {\n oa_actor ready \"Ready\" { description \"} stays text\"; }\n oa_actor pending \"Pending\" { description \"unfinished 🌊";
+    let result = outline(source, limits()).unwrap();
+    assert_eq!(result.source, source);
+    assert_eq!(result.tokens.last().unwrap().span.end, source.len());
+    assert!(result.has_lexical_errors);
+    assert!(result.has_unmatched_braces);
+    let ready = declaration(&result, "ready");
+    assert_eq!(
+        text(source, ready.declaration.span),
+        "oa_actor ready \"Ready\" { description \"} stays text\"; }"
+    );
+    assert_eq!(
+        declaration(&result, "outer").declaration.span.end,
+        source.len()
+    );
+    assert_eq!(
+        declaration(&result, "pending").declaration.span.end,
+        source.len()
+    );
+    let unmatched_close = outline("}\n// brace in comment {\n", limits()).unwrap();
+    assert!(unmatched_close.has_unmatched_braces);
+    assert!(!unmatched_close.has_lexical_errors);
+}
+
+#[test]
+fn missing_body_syntax_is_unchecked_even_when_known_error_flags_are_clear() {
+    let source = "oa_actor a \"A\" id \"00000000-0000-0000-0000-000000000001\"";
+    let result = outline(source, limits()).unwrap();
+    assert_eq!(result.declarations.len(), 1);
+    assert!(!result.has_lexical_errors);
+    assert!(!result.has_unmatched_braces);
+    // There is deliberately no `valid` flag: the known-complete fact is scanning
+    // these bytes, not the missing body becoming legal or the draft being applied.
+    assert_eq!(result.source, source);
+}
+
+#[test]
+fn keyword_alias_and_collisions_keep_every_source_ordered_header() {
+    let source = "project root_model \"Model\" {\n oa_actor oa_activity \"First\" id \"00000000-0000-0000-0000-000000000001\" {}\n oa_actor oa_activity \"Second\" id \"00000000-0000-0000-0000-000000000001\" {}\n diagram view_one \"View\" {}\n node placement { diagram @view_one; }\n}";
+    let result = outline(source, limits()).unwrap();
+    assert_eq!(result.declarations.len(), 5);
+    let duplicates: Vec<_> = result
+        .declarations
+        .iter()
+        .filter(|d| d.declaration.alias == "oa_activity")
+        .collect();
+    assert_eq!(duplicates.len(), 2);
+    assert!(duplicates[0].alias_span.start < duplicates[1].alias_span.start);
+    assert_eq!(duplicates[0].declaration.id, duplicates[1].declaration.id);
+    assert!(
+        result
+            .tokens
+            .iter()
+            .any(|t| t.span == duplicates[0].alias_span && t.class == TokenClass::Keyword)
+    );
+    assert_eq!(
+        text(source, declaration(&result, "placement").kind_span),
+        "node"
+    );
+    assert_eq!(declaration(&result, "placement").declaration.id, None);
+}
+
+#[test]
+fn bounds_refuse_before_returning_a_partial_outline() {
+    let source = "oa_actor a \"A\" {}\noa_actor b \"B\" {}";
+    let admitted = outline(source, limits()).unwrap();
+    let exact = OutlineLimits {
+        max_source_bytes: source.len(),
+        max_tokens: admitted.tokens.len(),
+        max_declarations: 2,
+    };
+    assert_eq!(outline(source, exact).unwrap(), admitted);
+    for resource in [
+        OutlineResource::SourceBytes,
+        OutlineResource::Tokens,
+        OutlineResource::Declarations,
+    ] {
+        let mut lower = exact;
+        match resource {
+            OutlineResource::SourceBytes => lower.max_source_bytes -= 1,
+            OutlineResource::Tokens => lower.max_tokens -= 1,
+            OutlineResource::Declarations => lower.max_declarations -= 1,
+        }
+        let error = outline(source, lower).unwrap_err();
+        assert_eq!(error.resource, resource);
+        assert!(error.observed_at_least > error.limit);
+        assert!(source.is_char_boundary(error.offset));
+        if resource == OutlineResource::Declarations {
+            assert_eq!(error.offset, source.find("oa_actor b").unwrap());
+        }
+    }
+    let empty = outline(
+        "",
+        OutlineLimits {
+            max_source_bytes: 0,
+            max_tokens: 0,
+            max_declarations: 0,
+        },
+    )
+    .unwrap();
+    assert!(empty.tokens.is_empty() && empty.declarations.is_empty());
+    let unicode = "// 🌊\r\noa_actor a \"A\" {}";
+    let error = outline(
+        unicode,
+        OutlineLimits {
+            max_source_bytes: 4,
+            ..limits()
+        },
+    )
+    .unwrap_err();
+    assert_eq!(error.resource, OutlineResource::SourceBytes);
+    assert_eq!(error.offset, 0);
+    let error = outline(
+        unicode,
+        OutlineLimits {
+            max_tokens: 1,
+            ..limits()
+        },
+    )
+    .unwrap_err();
+    assert_eq!(error.resource, OutlineResource::Tokens);
+    assert_eq!(error.offset, unicode.find('\n').unwrap());
+}
+
+#[test]
+fn outline_ranges_follow_current_bytes_without_identity_stabilization() {
+    let old = "oa_actor a \"A\" {}\nsource @a;";
+    let current = format!("// 航海 🚒\r\n{old}");
+    let old_outline = outline(old, limits()).unwrap();
+    let current_outline = outline(&current, limits()).unwrap();
+    let shift = current.len() - old.len();
+    let old_role = &old_outline.declarations[0];
+    let current_role = &current_outline.declarations[0];
+    assert_eq!(
+        current_role.alias_span.start,
+        old_role.alias_span.start + shift
+    );
+    assert_eq!(
+        current_role.kind_span.start,
+        old_role.kind_span.start + shift
+    );
+    assert_eq!(
+        current_role.declaration.span.end,
+        old_role.declaration.span.end + shift
+    );
+    assert_eq!(current_outline.source, current);
+    assert_eq!(old_outline.source, old);
+    assert_eq!(current_role.declaration.id, None);
+    assert!(!current_outline.source.contains(" id "));
+    // Workspace revision/stale-handle rejection belongs to the query/adapter,
+    // not a claim that an old owned span can be applied to any other string.
+}
+
+#[test]
+fn deeply_nested_bounds_use_the_same_iterative_walk_and_declaration_budget() {
+    let mut source = String::new();
+    for index in 0..600 {
+        source.push_str(&format!("oa_activity work_{index} \"Work\" {{\n"));
+    }
+    source.push_str(&"}\n".repeat(600));
+    let result = outline(&source, limits()).unwrap();
+    assert_eq!(result.declarations.len(), 600);
+    assert!(!result.has_unmatched_braces);
+    assert_eq!(
+        result.declarations[0].declaration.span.end,
+        source.len() - 1
+    );
+    let error = outline(
+        &source,
+        OutlineLimits {
+            max_declarations: 599,
+            ..limits()
+        },
+    )
+    .unwrap_err();
+    assert_eq!(error.resource, OutlineResource::Declarations);
+    assert_eq!(error.observed_at_least, 600);
+    assert_eq!(error.offset, source.find("oa_activity work_599").unwrap());
+}
+
+#[test]
+fn noncanonical_uuid_spellings_have_no_outline_or_analysis_identity() {
+    for raw in [
+        "00000000000000000000000000000001",
+        "{00000000-0000-0000-0000-000000000001}",
+        "urn:uuid:00000000-0000-0000-0000-000000000001",
+    ] {
+        assert!(
+            Id::parse_str(raw).is_ok(),
+            "The UUID crate alone is too permissive"
+        );
+        assert!(!has_uuid_header_shape(raw));
+        let literal = format!("\"{raw}\"");
+        let modern = format!("arcadia 7; project model \"Model\" id {literal} {{}}");
+        let before = modern.clone();
+        let result = outline(&modern, limits()).unwrap();
+        let d = declaration(&result, "model");
+        assert_eq!(d.declaration.id, None);
+        assert_eq!(text(&modern, d.id_literal_span.unwrap()), literal);
+        assert_eq!(modern, before);
+        let errors = parse(&modern).unwrap_err();
+        assert!(
+            errors
+                .iter()
+                .any(|error| error.message.contains("8-4-4-4-12")
+                    && error.span.start == modern.find(&literal).unwrap())
+        );
+        // Intentional compatibility correction: old analyze yielded Some(Id(1))
+        // here despite lint rejecting the header. It now shares outline's None.
+        let analysis = analyze(&modern);
+        assert_eq!(
+            analysis
+                .declarations
+                .iter()
+                .find(|d| d.alias == "model")
+                .unwrap()
+                .id,
+            None
+        );
+        assert!(
+            analysis
+                .diagnostics
+                .iter()
+                .any(|error| error.message.contains("8-4-4-4-12"))
+        );
+        let legacy_source = format!("arcadia 1; project \"Legacy\" id {literal} {{}}");
+        let legacy_errors = legacy::parse(&legacy_source).unwrap_err();
+        assert!(
+            legacy_errors
+                .iter()
+                .any(|error| error.message.contains("8-4-4-4-12"))
+        );
+    }
+}
+
+#[test]
+fn uppercase_and_json_escaped_header_ids_survive_both_parsers_and_outline() {
+    let expected = Id::from_u128(0xabcdef);
+    let canonical = expected.to_string();
+    let uppercase = canonical.to_uppercase();
+    assert_ne!(uppercase, canonical);
+    for raw in [uppercase.clone(), format!("\\u0030{}", &uppercase[1..])] {
+        let literal = format!("\"{raw}\"");
+        let decoded: String = serde_json::from_str(&literal).unwrap();
+        assert!(has_uuid_header_shape(&decoded));
+        let modern = format!("arcadia 7; project model \"Model\" id {literal} {{}}");
+        let result = outline(&modern, limits()).unwrap();
+        let d = declaration(&result, "model");
+        assert_eq!(d.declaration.id, Some(expected));
+        assert_eq!(text(&modern, d.id_literal_span.unwrap()), literal);
+        assert_eq!(result.source.as_bytes(), modern.as_bytes());
+        assert_eq!(parse(&modern).unwrap().id, expected);
+        let analysis = analyze(&modern);
+        assert_eq!(analysis.declarations[0].id, Some(expected));
+        assert!(
+            !analysis
+                .diagnostics
+                .iter()
+                .any(|error| error.severity == crate::validation::Severity::Error)
+        );
+        let legacy_source = format!("arcadia 1; project \"Legacy\" id {literal} {{}}");
+        assert_eq!(legacy::parse(&legacy_source).unwrap().id, expected);
+    }
+}
+
+#[test]
+fn header_shape_still_requires_valid_hexadecimal_uuid_data() {
+    let raw = "00000000-0000-0000-0000-00000000000Z";
+    assert!(has_uuid_header_shape(raw));
+    assert!(Id::parse_str(raw).is_err());
+    let literal = format!("\"{raw}\"");
+    let source = format!("arcadia 7; project model \"Model\" id {literal} {{}}");
+    let result = outline(&source, limits()).unwrap();
+    let d = declaration(&result, "model");
+    assert_eq!(d.declaration.id, None);
+    assert_eq!(text(&source, d.id_literal_span.unwrap()), literal);
+    assert!(
+        parse(&source)
+            .unwrap_err()
+            .iter()
+            .any(|error| error.message == "Invalid UUID identity.")
+    );
+    assert_eq!(analyze(&source).declarations[0].id, None);
+}

crates/oa-desktop/src/app.rs

@@ -2,12 +2,15 @@ pub(crate) mod architecture_authoring;
 #[cfg(test)]
 mod architecture_authoring_tests;
 mod checkpoints;
+mod diagram_reveal;
 #[cfg(test)]
 mod diagram_selection_tests;
+mod diagram_usages;
 mod hosted;
 mod reference_authoring;
 #[cfg(test)]
 mod review_navigation_tests;
+mod source_symbols;
 #[cfg(test)]
 mod transition_context_tests;
 #[cfg(test)]
@@ -427,9 +430,18 @@ pub enum Message {
     Linted(u64, Result<Vec<SourceDiagnostic>, String>),
     SourceDiagnostic(usize),
     SourceRelated(SourceLocation),
-    SourceViewport,
+    SourceViewport(Option<Id>),
+    SourceSymbols(
+        crate::source_navigation::SymbolContext,
+        crate::source_navigation::SymbolEvent,
+    ),
+    SourceSymbolsReady(crate::source_navigation::Completion),
+    DiagramUsage(crate::diagram_usage::Event),
+    DiagramUsagesReady(crate::diagram_usage::Completion),
+    DiagramRevealViewport(crate::diagram_usage::Context, u64, iced::Size),
     SourceForSelection,
     SourceNavigation(crate::source_navigation::Event),
+    SourceFindClose(crate::source_navigation::SymbolContext, Id),
     Save(bool),
     SavePath(Option<PathBuf>),
     Saved(Result<Option<FileSnapshot>, SaveFailure>),
@@ -507,6 +519,16 @@ pub struct App {
     pub source_jump: Option<text_editor::Cursor>,
     source_select_line: bool,
     pub source_navigation: crate::source_navigation::State,
+    source_find_instance: Id,
+    pub source_symbols: crate::source_navigation::SymbolState,
+    pub(crate) diagram_usages: Option<crate::diagram_usage::Panel>,
+    source_diagram_job: Option<Id>,
+    diagram_lookup_in_flight: Option<Id>,
+    pending_diagram_reveal: Option<(
+        crate::diagram_usage::Context,
+        crate::diagram_usage::Usage,
+        u64,
+    )>,
     pub model_issues: Vec<validation::Issue>,
     pub migration: Option<persistence::MigrationReport>,
     source_version: u64,
@@ -615,6 +637,12 @@ impl App {
             source_jump: None,
             source_select_line: false,
             source_navigation: crate::source_navigation::State::default(),
+            source_find_instance: Id::new_v4(),
+            source_symbols: crate::source_navigation::SymbolState::default(),
+            diagram_usages: None,
+            source_diagram_job: None,
+            diagram_lookup_in_flight: None,
+            pending_diagram_reveal: None,
             model_issues,
             migration: None,
             source_version: 0,
@@ -668,6 +696,7 @@ impl App {
         self.lint_requested = None;
     }
     fn show_source_file(&mut self, restore_cursor: bool) {
+        self.source_symbols.reveal = None;
         self.source_tree.reveal(&self.source_workspace.active);
         self.source_select_line = false;
         let source = self.source_workspace.text().to_owned();
@@ -682,6 +711,9 @@ impl App {
                     .map(|b| b.cursor)
             })
             .flatten();
+        if let Some(cursor) = self.source_jump {
+            self.queue_source_reveal(cursor, false);
+        }
     }
     fn selected_architecture_placement(&self) -> Option<Id> {
         self.active_diagram
@@ -935,6 +967,8 @@ impl App {
         let canvas_size = self.canvas_size;
         let source_version = self.source_version + 1;
         let lint_running = self.lint_running;
+        let navigation_in_flight = self.source_symbols.in_flight;
+        let diagram_lookup_in_flight = self.diagram_lookup_in_flight;
         let guide = std::mem::take(&mut self.guide);
         let mut hosted = std::mem::take(&mut self.hosted);
         hosted.leave_document();
@@ -946,6 +980,8 @@ impl App {
         self.canvas_size = canvas_size;
         self.source_version = source_version;
         self.lint_running = lint_running;
+        self.source_symbols.in_flight = navigation_in_flight;
+        self.diagram_lookup_in_flight = diagram_lookup_in_flight;
         self.guide = guide;
         self.path = path;
         self.status = "Project ready".into();
@@ -1046,22 +1082,70 @@ impl App {
             crate::model_menu::popup(self),
         )
         .into();
-        crate::behavior::scenario::focus::root(
-            behavior::canvas_workspace::focus_root(
-                crate::hosted::view::overlay(self, self.reference_overlay(base)),
-                behavior::canvas_workspace::Scope::input_owner(self),
+        crate::source_navigation::interaction::observe(
+            crate::behavior::scenario::focus::root(
+                behavior::canvas_workspace::focus_root(
+                    crate::hosted::view::overlay(
+                        self,
+                        self.reference_overlay(crate::diagram_usage::view::overlay(self, base)),
+                    ),
+                    behavior::canvas_workspace::Scope::input_owner(self),
+                ),
+                self.scenario_focus_owner(),
             ),
-            self.scenario_focus_owner(),
+            self.source_symbols.raw_interaction.clone(),
         )
     }
     pub fn subscription(&self) -> Subscription<Message> {
         Subscription::batch([
+            self.diagram_usages
+                .as_ref()
+                .map_or_else(Subscription::none, |panel| {
+                    iced::event::listen_with(|event, status, _| {
+                        let iced::Event::Keyboard(keyboard::Event::KeyPressed {
+                            key,
+                            modifiers,
+                            ..
+                        }) = event
+                        else {
+                            return None;
+                        };
+                        if !modifiers.is_empty() {
+                            return None;
+                        }
+                        match key {
+                            keyboard::Key::Named(keyboard::key::Named::ArrowUp) => Some(-1i8),
+                            keyboard::Key::Named(keyboard::key::Named::ArrowDown) => Some(1i8),
+                            keyboard::Key::Named(keyboard::key::Named::Enter)
+                                if status == iced::event::Status::Ignored =>
+                            {
+                                Some(0i8)
+                            }
+                            _ => None,
+                        }
+                    })
+                    .with(panel.token)
+                    .map(|(token, step)| {
+                        Message::DiagramUsage(if step == 0 {
+                            crate::diagram_usage::Event::Activate(token)
+                        } else {
+                            crate::diagram_usage::Event::Move(token, step)
+                        })
+                    })
+                }),
             iced::time::every(std::time::Duration::from_secs(10)).map(|_| Message::CheckpointTick),
             window::close_requests().map(|id| Message::Request(Pending::Close(id))),
             window::resize_events().map(|(_, size)| Message::WindowResized(size)),
             architecture_authoring::subscription(self),
+            // Use one captured-Escape bridge: a focused Find input consumes
+            // Escape, while modal priority remains in the ordinary handler.
             behavior::creation::subscription(
-                self.behavior.creation.has_pending() || self.behavior.source_active(),
+                self.behavior.creation.has_pending()
+                    || self.diagram_usages.is_some()
+                    || self.behavior.source_active()
+                    || (self.page == Page::Text
+                        && (self.source_symbols.open || self.source_navigation.open)
+                        && self.architecture.is_none()),
             )
             .map(|()| Message::Escape),
             iced::event::listen_with(|event, status, _| {
@@ -1108,6 +1192,17 @@ impl App {
         ])
     }
     pub fn update(&mut self, message: Message) -> Task<Message> {
+        let usage_viewport = self.diagram_reveal_viewport(&message);
+        let window_resized = matches!(&message, Message::WindowResized(_));
+        // Reject stale measurements before legacy viewport handlers can change
+        // dimensions or invalidate the exact pending destination epoch.
+        if self.pending_diagram_reveal.is_some()
+            && Self::is_diagram_viewport(&message)
+            && usage_viewport.is_none()
+        {
+            return Task::none();
+        }
+        self.reconcile_pending_diagram_reveal(&message);
         if let Message::BehaviorControl(intent) = message {
             return self.behavior_control(intent);
         }
@@ -1118,6 +1213,12 @@ impl App {
         );
         let before = self.camera_boundary();
         let task = self.update_inner(message);
+        if window_resized && let Some((_, _, epoch)) = &mut self.pending_diagram_reveal {
+            *epoch = self.canvas_epoch;
+        }
+        if let Some(surface) = usage_viewport {
+            self.finish_diagram_reveal(surface);
+        }
         if !camera && self.camera_boundary() != before {
             self.camera_epoch = self.camera_epoch.wrapping_add(1);
             self.camera_boundary_epoch = self.canvas_epoch;
@@ -1207,6 +1308,75 @@ impl App {
         )
     }
     fn update_inner(&mut self, message: Message) -> Task<Message> {
+        let message = match message {
+            Message::SourceFindClose(context, instance) => {
+                if context != self.source_symbol_context()
+                    || instance != self.source_find_instance
+                    || !self.source_navigation.open
+                    || !self.source_navigation_available()
+                {
+                    return Task::none();
+                }
+                // Only the checked envelope may enter the legacy Close handler.
+                Message::SourceNavigation(crate::source_navigation::Event::Close)
+            }
+            Message::SourceNavigation(crate::source_navigation::Event::Close) => {
+                return Task::none();
+            }
+            message => message,
+        };
+        if let Message::SourceSymbols(context, _) = &message
+            && (context.session != self.source_workspace.session()
+                || context.path != self.source_workspace.active)
+        {
+            return Task::none();
+        }
+        // Internal results and geometry do not constitute a new user intent.
+        // Process query completion even behind a modal to release its worker slot;
+        // its handler independently refuses navigation outside the live editor.
+        if let Message::SourceSymbolsReady(completion) = message {
+            return self.source_symbols_ready(completion);
+        }
+        if let Message::DiagramUsagesReady(completion) = message {
+            return self.diagram_usages_ready(completion);
+        }
+        if !matches!(
+            &message,
+            Message::CheckpointTick
+                | Message::CheckpointWritten(..)
+                | Message::Lint(_)
+                | Message::Linted(..)
+                | Message::SourceViewport(_)
+                | Message::WindowResized(_)
+                | Message::CanvasResized(_)
+                | Message::DiagramRevealViewport(..)
+        ) {
+            self.source_interaction();
+        }
+        if let Message::DiagramUsage(event) = message {
+            return self.diagram_usage_event(event);
+        }
+        if let Some(panel) = &self.diagram_usages {
+            if matches!(&message, Message::Request(Pending::Close(_))) {
+                self.diagram_usages = None;
+                return self.update(message);
+            }
+            if matches!(&message, Message::Escape) {
+                return self.diagram_usage_event(crate::diagram_usage::Event::Close(panel.token));
+            }
+            if !matches!(
+                &message,
+                Message::CheckpointTick
+                    | Message::CheckpointWritten(..)
+                    | Message::Lint(_)
+                    | Message::Linted(..)
+                    | Message::WindowResized(_)
+                    | Message::CanvasResized(_)
+                    | Message::SourceViewport(_)
+            ) {
+                return Task::none();
+            }
+        }
         if let Some(task) = self.reference_message(&message) {
             return task;
         }
@@ -1274,7 +1444,7 @@ impl App {
                     | Message::CanvasResized(_)
                     | Message::Lint(_)
                     | Message::Linted(_, _)
-                    | Message::SourceViewport
+                    | Message::SourceViewport(_)
                     | Message::Request(Pending::Close(_))
             )
         {
@@ -1320,7 +1490,7 @@ impl App {
                     | Message::Exported(_)
                     | Message::WindowResized(_)
                     | Message::CanvasResized(_)
-                    | Message::SourceViewport
+                    | Message::SourceViewport(_)
             )
         {
             return Task::none();
@@ -1358,7 +1528,7 @@ impl App {
                 | Message::CheckpointLoaded(..)
                 | Message::WindowResized(_)
                 | Message::CanvasResized(_)
-                | Message::SourceViewport
+                | Message::SourceViewport(_)
                 | Message::Lint(_)
                 | Message::Linted(_, _)
                 | Message::Saved(_)
@@ -1969,6 +2139,8 @@ impl App {
                 return self.update(Message::Add(child));
             }
             Message::Escape => {
+                let restore_source_focus = self.source_navigation_available()
+                    && (self.source_navigation.open || self.source_symbols.open);
                 if self.behavior.source_back() {
                     self.status =
                         "Returned to the unchanged parent form; no source was created.".into();
@@ -1985,6 +2157,12 @@ impl App {
                     self.status = "Drawing cancelled · Select / move is active".into();
                 }
                 self.source_navigation.open = false;
+                self.source_symbols.open = false;
+                self.source_symbols.results = None;
+                self.source_symbols.notice = None;
+                if restore_source_focus {
+                    self.restore_source_editor_focus();
+                }
                 self.canvas_epoch = self.canvas_epoch.wrapping_add(1);
                 self.selected_bend = None;
             }
@@ -3036,6 +3214,9 @@ impl App {
                                 if self.path.is_none()
                                     || self.path.as_ref() == Some(&receipt.target)
                                 {
+                                    if self.path.as_ref() != Some(&receipt.target) {
+                                        self.source_workspace.reset_navigation_session();
+                                    }
                                     self.path = Some(receipt.target);
                                     self.document.bind_repair_baseline(disk.reachable_bundle());
                                     self.disk_project = Some(disk);
@@ -3104,13 +3285,28 @@ impl App {
                 }
             }
             Message::SourceRelated(location) => self.jump_to_source(location),
-            Message::SourceViewport => {
-                if let Some(cursor) = self.source_jump.take() {
-                    self.source_editor.move_to(cursor);
-                    if self.source_select_line && cursor.selection.is_none() {
-                        self.source_editor.perform(text_editor::Action::SelectLine);
-                    }
-                    return iced::widget::operation::focus("source-editor");
+            Message::SourceViewport(ticket) => return self.source_viewport(ticket),
+            Message::SourceFindClose(..) => return Task::none(), // update checks and unwraps it
+            Message::SourceSymbols(_, event) => return self.source_symbol_event(event),
+            Message::SourceSymbolsReady(completion) => {
+                return self.source_symbols_ready(completion);
+            }
+            Message::DiagramUsage(event) => return self.diagram_usage_event(event),
+            Message::DiagramUsagesReady(completion) => {
+                return self.diagram_usages_ready(completion);
+            }
+            Message::DiagramRevealViewport(context, epoch, size) => {
+                if self
+                    .pending_diagram_reveal
+                    .as_ref()
+                    .is_some_and(|(c, _, e)| *c == context && *e == epoch)
+                    && self
+                        .diagram_reveal_viewport(&Message::DiagramRevealViewport(
+                            context, epoch, size,
+                        ))
+                        .is_some()
+                {
+                    return self.handle(Message::CanvasResized(size));
                 }
             }
             Message::ApplySource => {
@@ -3157,6 +3353,7 @@ impl App {
                             return Task::none();
                         }
                         self.page = Page::Text;
+                        self.source_find_instance = Id::new_v4();
                         self.source_navigation.open = true;
                         self.source_navigation.refresh(&self.source_editor.text());
                         return iced::widget::operation::focus(if go_to_line {
@@ -3165,13 +3362,22 @@ impl App {
                             "source-find"
                         });
                     }
-                    Event::Close => self.source_navigation.open = false,
+                    Event::Close => {
+                        let was_open = self.source_navigation.open;
+                        self.source_navigation.open = false;
+                        if was_open {
+                            self.restore_source_editor_focus();
+                        }
+                    }
                     Event::Query(query) => {
                         self.source_navigation.query = query;
                         self.source_navigation.refresh(&self.source_editor.text());
                     }
                     Event::Next(backwards) if self.page == Page::Text => {
                         self.source_jump = self.source_navigation.next(backwards);
+                        if let Some(cursor) = self.source_jump {
+                            self.queue_source_reveal(cursor, false);
+                        }
                         if self.source_jump.is_none() {
                             self.status = "No matching source text.".into();
                         }
@@ -3182,8 +3388,7 @@ impl App {
                         .destination(self.source_editor.line_count())
                     {
                         Ok(cursor) => {
-                            self.source_jump = Some(cursor);
-                            self.source_select_line = true;
+                            self.queue_source_reveal(cursor, true);
                         }
                         Err(error) => self.status = error,
                     },
@@ -3266,6 +3471,9 @@ impl App {
                                 }
                                 self.sync_source();
                             }
+                            if self.path.as_ref() != Some(&receipt.path) {
+                                self.source_workspace.reset_navigation_session();
+                            }
                             self.disk_project = Some(disk);
                             self.path = Some(receipt.path);
                             self.hosted.session = None;
@@ -3866,7 +4074,7 @@ impl App {
                 self.path = Some(path);
                 self.document.bind_repair_baseline(disk.reachable_bundle());
                 self.source_workspace = Workspace::new(&disk.bundle, false);
-                self.source_workspace.reachable = disk.reachable.clone();
+                self.source_workspace.set_reachable(disk.reachable.clone());
                 self.show_source_file(false);
                 self.source_diagnostics = error.diagnostics().to_vec();
                 self.source_version += 1;
@@ -3918,11 +4126,13 @@ impl App {
         let column = prefix
             .rfind('\n')
             .map_or(offset, |start| offset - start - 1);
-        self.source_jump = Some(text_editor::Cursor {
-            position: text_editor::Position { line, column },
-            selection: None,
-        });
-        self.source_select_line = true;
+        self.queue_source_reveal(
+            text_editor::Cursor {
+                position: text_editor::Position { line, column },
+                selection: None,
+            },
+            true,
+        );
     }
 
     fn create_source_file(&mut self) -> Result<(), String> {

crates/oa-desktop/src/app/diagram_reveal.rs

@@ -0,0 +1,112 @@
+//! Complete a navigation camera after the destination reports its real viewport.
+use super::*;
+use crate::diagram_usage::{Context, Surface};
+#[cfg(test)]
+mod tests;
+
+impl App {
+    pub(super) fn is_diagram_viewport(message: &Message) -> bool {
+        matches!(
+            message,
+            Message::CanvasResized(_)
+                | Message::DiagramRevealViewport(..)
+                | Message::TopologyCanvas(behavior::topology::CanvasEvent::Viewport(..))
+                | Message::ScenarioCanvas(behavior::scenario::CanvasEvent::Viewport(..))
+                | Message::StateDiagram(behavior::state_edit::Event::Viewport(..))
+        )
+    }
+    pub(crate) fn architecture_reveal_stamp(&self, diagram: Id) -> Option<(Context, u64)> {
+        self.pending_diagram_reveal
+            .as_ref()
+            .filter(|(_, u, _)| u.surface == Surface::Saved(diagram))
+            .map(|(context, _, epoch)| (*context, *epoch))
+    }
+
+    pub(super) fn diagram_reveal_viewport(&self, message: &Message) -> Option<Surface> {
+        let (context, usage, epoch) = self.pending_diagram_reveal.as_ref()?;
+        if context.document != self.canvas_document
+            || context.revision != self.document.revision()
+            || *epoch != self.canvas_epoch
+        {
+            return None;
+        }
+        let (surface, size, valid) = match message {
+            Message::DiagramRevealViewport(c, e, size) => (
+                usage.surface,
+                *size,
+                c == context
+                    && e == epoch
+                    && self.page == Page::Diagram
+                    && Some(usage.surface.id()) == self.active_diagram,
+            ),
+            Message::TopologyCanvas(behavior::topology::CanvasEvent::Viewport(c, size)) => (
+                Surface::Process(c.owner),
+                *size,
+                c.document == context.document
+                    && c.revision == context.revision
+                    && c.epoch == *epoch,
+            ),
+            Message::ScenarioCanvas(behavior::scenario::CanvasEvent::Viewport(c, size)) => (
+                Surface::Scenario(c.scenario),
+                *size,
+                c.document == context.document
+                    && c.revision == context.revision
+                    && c.epoch == *epoch,
+            ),
+            Message::StateDiagram(behavior::state_edit::Event::Viewport(c, size)) => (
+                Surface::Saved(c.diagram),
+                *size,
+                c.document == context.document
+                    && c.revision == context.revision
+                    && c.epoch == *epoch,
+            ),
+            _ => return None,
+        };
+        (valid
+            && surface == usage.surface
+            && size.width.is_finite()
+            && size.height.is_finite()
+            && size.width > 0.
+            && size.height > 0.)
+            .then_some(surface)
+    }
+
+    pub(super) fn reconcile_pending_diagram_reveal(&mut self, message: &Message) {
+        if !matches!(
+            message,
+            Message::CheckpointTick
+                | Message::CheckpointWritten(..)
+                | Message::Lint(_)
+                | Message::Linted(..)
+                | Message::SourceViewport(_)
+                | Message::WindowResized(_)
+                | Message::CanvasResized(_)
+                | Message::DiagramRevealViewport(..)
+                | Message::DiagramUsagesReady(_)
+                | Message::SourceSymbolsReady(_)
+                | Message::TopologyCanvas(behavior::topology::CanvasEvent::Viewport(..))
+                | Message::ScenarioCanvas(behavior::scenario::CanvasEvent::Viewport(..))
+                | Message::StateDiagram(behavior::state_edit::Event::Viewport(..))
+        ) {
+            self.pending_diagram_reveal = None;
+        }
+    }
+
+    pub(super) fn finish_diagram_reveal(&mut self, surface: Surface) {
+        let Some((context, usage, _)) = self.pending_diagram_reveal.take() else {
+            return;
+        };
+        if context.document == self.canvas_document
+            && context.revision == self.document.revision()
+            && usage.surface == surface
+            && !self.draft_dirty()
+            && !self.source_dirty()
+            && !self.behavior.has_pending()
+        {
+            // The normal viewport handler has now stored the measured size.
+            // Target identity was validated for this revision before navigation.
+            self.reveal_diagram_usage(&usage);
+        }
+        self.pending_diagram_reveal = None;
+    }
+}

crates/oa-desktop/src/app/diagram_reveal/tests.rs

@@ -0,0 +1,403 @@
+//! Independent first-layout navigation oracles, through the real App boundary.
+use super::*;
+use crate::diagram_usage::{self as usage, Target, Usage};
+use iced::{Size, Vector};
+use std::collections::BTreeMap;
+
+#[derive(Clone, Copy, Debug)]
+enum Canvas {
+    Architecture,
+    Process,
+    Scenario,
+    State,
+}
+const CANVASES: [Canvas; 4] = [
+    Canvas::Architecture,
+    Canvas::Process,
+    Canvas::Scenario,
+    Canvas::State,
+];
+const WIDE: Size = Size::new(1200., 700.);
+const ACTUAL: Size = Size::new(500., 300.);
+
+fn send(app: &mut App, message: Message) {
+    let _ = app.update(message);
+}
+
+fn fixture(canvas: Canvas) -> (App, Usage) {
+    let mut p = Project::empty();
+    let work = p
+        .add_element(Kind::Activity, Layer::Oa, "Respond", None)
+        .unwrap();
+    let (surface, subject) = match canvas {
+        Canvas::Architecture => {
+            let diagram = p.ensure_diagram(Layer::Oa);
+            p.place(
+                diagram,
+                work,
+                Position {
+                    x: 12_000.,
+                    y: 9_000.,
+                },
+            );
+            (Surface::Saved(diagram), work)
+        }
+        Canvas::Process | Canvas::Scenario => {
+            let kind = if matches!(canvas, Canvas::Process) {
+                Kind::Process
+            } else {
+                Kind::Scenario
+            };
+            let owner = p.add_element(kind, Layer::Oa, "Response", None).unwrap();
+            let occurrence = p
+                .add_element(Kind::Occurrence, Layer::Oa, "Respond here", Some(owner))
+                .unwrap();
+            *p.elements
+                .get_mut(&occurrence)
+                .unwrap()
+                .shared_mut()
+                .unwrap() = SharedBody::Occurrence {
+                body: OccurrenceBody::Action {
+                    action: Some(work),
+                    lifeline: None,
+                },
+                precondition: String::new(),
+                postcondition: String::new(),
+            };
+            let steps = p.elements.get_mut(&owner).unwrap().steps_mut().unwrap();
+            if !steps.contains(&occurrence) {
+                steps.push(occurrence);
+            }
+            (
+                if matches!(canvas, Canvas::Process) {
+                    Surface::Process(owner)
+                } else {
+                    Surface::Scenario(owner)
+                },
+                occurrence,
+            )
+        }
+        Canvas::State => {
+            let machine = p
+                .add_element(Kind::StateMachine, Layer::Oa, "Modes", None)
+                .unwrap();
+            let region = p
+                .add_element(Kind::Region, Layer::Oa, "Main", Some(machine))
+                .unwrap();
+            let state = p
+                .add_element(Kind::State, Layer::Oa, "Ready", Some(region))
+                .unwrap();
+            let diagram = Id::new_v4();
+            p.diagrams.insert(
+                diagram,
+                Diagram {
+                    id: diagram,
+                    alias: "ready_view".into(),
+                    name: "Ready view".into(),
+                    description: String::new(),
+                    layer: Layer::Oa,
+                    projection: ProjectionKind::StateMachine { machine },
+                    nodes: BTreeMap::new(),
+                    routes: vec![],
+                    view_options: Default::default(),
+                },
+            );
+            p.place(
+                diagram,
+                state,
+                Position {
+                    x: 8_000.,
+                    y: 11_000.,
+                },
+            );
+            (Surface::Saved(diagram), state)
+        }
+    };
+    let mut app = App::with_project(p);
+    let found = usage::collect(
+        app.project(),
+        subject,
+        &app.behavior.topology,
+        &app.behavior.scenario,
+    )
+    .into_iter()
+    .find(|u| u.surface == surface && u.target != Target::Whole)
+    .unwrap();
+    app.canvas_size = Some(WIDE);
+    app.behavior.diagram.viewport = Some(WIDE);
+    if let Surface::Process(owner) = surface {
+        app.behavior.topology.enter(app.canvas_document, owner);
+        app.behavior.topology.viewport(WIDE);
+    }
+    if let Surface::Scenario(owner) = surface {
+        app.behavior.scenario.enter(app.canvas_document, owner);
+        app.behavior.scenario.viewport(WIDE);
+    }
+    app.page = Page::Text;
+    (app, found)
+}
+
+fn measurement(
+    canvas: Canvas,
+    context: Context,
+    epoch: u64,
+    surface: Surface,
+    size: Size,
+) -> Message {
+    match canvas {
+        Canvas::Architecture => Message::DiagramRevealViewport(context, epoch, size),
+        Canvas::Process => Message::TopologyCanvas(behavior::topology::CanvasEvent::Viewport(
+            behavior::topology::Context {
+                document: context.document,
+                owner: surface.id(),
+                revision: context.revision,
+                epoch,
+            },
+            size,
+        )),
+        Canvas::Scenario => Message::ScenarioCanvas(behavior::scenario::CanvasEvent::Viewport(
+            behavior::scenario::Context {
+                document: context.document,
+                scenario: surface.id(),
+                revision: context.revision,
+                epoch,
+            },
+            size,
+        )),
+        Canvas::State => Message::StateDiagram(behavior::state_edit::Event::Viewport(
+            behavior::state_edit::Context {
+                document: context.document,
+                diagram: surface.id(),
+                revision: context.revision,
+                epoch,
+            },
+            size,
+        )),
+    }
+}
+
+fn stamp(app: &App) -> (Context, u64) {
+    let (context, _, epoch) = app
+        .pending_diagram_reveal
+        .as_ref()
+        .expect("reveal awaits measured destination");
+    (*context, *epoch)
+}
+
+fn assert_centered(app: &App, canvas: Canvas, target: &Usage) {
+    // All independently authored fixture targets fit ACTUAL at the readable cap.
+    // This oracle does not call the production camera/reveal implementation.
+    let zoom = 1.25;
+    let pan = Vector::new(
+        250. - target.bounds.center_x() * zoom,
+        150. - target.bounds.center_y() * zoom,
+    );
+    match canvas {
+        Canvas::Architecture => {
+            assert_eq!(app.canvas_size, Some(ACTUAL));
+            assert_eq!(app.zoom, zoom);
+            assert_eq!(app.pan, pan);
+            assert!(!app.fit_to_view);
+        }
+        Canvas::State => {
+            assert_eq!(app.behavior.diagram.viewport, Some(ACTUAL));
+            assert_eq!(app.behavior.diagram.zoom, zoom);
+            assert_eq!(app.behavior.diagram.pan, pan);
+            assert!(!app.behavior.diagram.fit);
+        }
+        Canvas::Process => {
+            let mut expected = behavior::topology::State::default();
+            expected.enter(app.canvas_document, target.surface.id());
+            expected.viewport(ACTUAL);
+            expected.zoom(Some(zoom));
+            expected.camera(behavior::canvas_workspace::Event::Pan(pan));
+            assert!(app.behavior.topology.camera_boundary() == expected.camera_boundary());
+        }
+        Canvas::Scenario => {
+            let mut expected = behavior::scenario::State::default();
+            expected.enter(app.canvas_document, target.surface.id());
+            expected.choose_tool(target.surface.id(), behavior::scenario::CanvasTool::Select);
+            expected.viewport(ACTUAL);
+            expected.zoom(Some(zoom));
+            expected.camera(behavior::canvas_workspace::Event::Pan(pan));
+            assert!(app.behavior.scenario.camera_boundary() == expected.camera_boundary());
+        }
+    }
+}
+
+#[test]
+fn all_reveal_surfaces_recenter_once_after_the_real_viewport_and_preserve_authored_state() {
+    for canvas in CANVASES {
+        let (mut app, target) = fixture(canvas);
+        let accepted = app.document.snapshot();
+        let drafts = app.source_workspace.bundle();
+        let revision = app.document.revision();
+        let history = (
+            app.document.can_undo(),
+            app.document.can_redo(),
+            app.document.dirty(),
+        );
+        assert!(app.reveal_diagram_usage(&target));
+        let (context, epoch) = stamp(&app);
+        send(
+            &mut app,
+            measurement(canvas, context, epoch, target.surface, ACTUAL),
+        );
+        assert!(app.pending_diagram_reveal.is_none());
+        assert_centered(&app, canvas, &target);
+        assert!(Arc::ptr_eq(&accepted, &app.document.snapshot()));
+        assert_eq!(app.source_workspace.bundle(), drafts);
+        assert_eq!(app.document.revision(), revision);
+        assert_eq!(
+            (
+                app.document.can_undo(),
+                app.document.can_redo(),
+                app.document.dirty()
+            ),
+            history
+        );
+        // The exact delivered callback is a replay after the one-shot is consumed.
+        let camera = app.camera_boundary();
+        send(
+            &mut app,
+            measurement(canvas, context, epoch, target.surface, ACTUAL),
+        );
+        assert!(app.pending_diagram_reveal.is_none());
+        assert!(app.camera_boundary() == camera);
+        assert_centered(&app, canvas, &target);
+    }
+}
+
+#[test]
+fn malformed_or_wrong_stamp_measurements_cannot_poison_a_pending_reveal() {
+    for canvas in CANVASES {
+        for invalid in 0..6 {
+            let (mut app, target) = fixture(canvas);
+            assert!(app.reveal_diagram_usage(&target));
+            let (context, epoch) = stamp(&app);
+            let camera = app.camera_boundary();
+            let mut stale = context;
+            let mut wrong_epoch = epoch;
+            let mut size = Size::new(111., 122.);
+            match invalid {
+                0 => stale.document = Id::new_v4(),
+                1 => stale.revision = stale.revision.wrapping_add(1),
+                2 => wrong_epoch = wrong_epoch.wrapping_add(1),
+                3 => size.width = f32::NAN,
+                4 => size.height = f32::INFINITY,
+                _ => size.width = 0.,
+            }
+            send(
+                &mut app,
+                measurement(canvas, stale, wrong_epoch, target.surface, size),
+            );
+            assert!(
+                app.pending_diagram_reveal.is_some(),
+                "{canvas:?} invalid case {invalid}"
+            );
+            assert_eq!(stamp(&app), (context, epoch));
+            assert_eq!(app.canvas_epoch, epoch);
+            assert!(
+                app.camera_boundary() == camera,
+                "{canvas:?} invalid case {invalid}"
+            );
+            send(
+                &mut app,
+                measurement(canvas, context, epoch, target.surface, ACTUAL),
+            );
+            assert!(app.pending_diagram_reveal.is_none());
+            assert_centered(&app, canvas, &target);
+        }
+    }
+}
+
+#[test]
+fn actual_window_resize_before_first_measurement_retains_focus_for_the_new_context() {
+    for canvas in CANVASES {
+        let (mut app, target) = fixture(canvas);
+        let accepted = app.document.snapshot();
+        assert!(app.reveal_diagram_usage(&target));
+        let (context, old_epoch) = stamp(&app);
+        send(&mut app, Message::WindowResized(Size::new(1100., 700.)));
+        let (current, epoch) = stamp(&app);
+        assert_eq!(current, context);
+        assert_eq!(epoch, app.canvas_epoch);
+        if matches!(canvas, Canvas::Process | Canvas::Scenario) {
+            assert_ne!(epoch, old_epoch);
+            let camera = app.camera_boundary();
+            send(
+                &mut app,
+                measurement(canvas, context, old_epoch, target.surface, ACTUAL),
+            );
+            assert_eq!(stamp(&app), (current, epoch));
+            assert!(app.camera_boundary() == camera);
+        }
+        send(
+            &mut app,
+            measurement(canvas, current, epoch, target.surface, ACTUAL),
+        );
+        assert!(app.pending_diagram_reveal.is_none());
+        assert_centered(&app, canvas, &target);
+        assert!(Arc::ptr_eq(&accepted, &app.document.snapshot()));
+    }
+}
+
+#[test]
+fn user_camera_edit_and_navigation_cancel_deferred_focus_without_late_snapping() {
+    for canvas in CANVASES {
+        for action in 0..3 {
+            let (mut app, target) = fixture(canvas);
+            let accepted = app.document.snapshot();
+            assert!(app.reveal_diagram_usage(&target));
+            let (context, epoch) = stamp(&app);
+            let event = match action {
+                0 => match canvas {
+                    Canvas::Architecture => Message::Pan(Vector::new(31., -17.)),
+                    Canvas::State => Message::StateDiagram(behavior::state_edit::Event::Pan(
+                        app.state_context().unwrap(),
+                        Vector::new(31., -17.),
+                    )),
+                    Canvas::Process => {
+                        Message::TopologyCanvas(behavior::topology::CanvasEvent::Camera(
+                            app.topology_context().unwrap(),
+                            app.camera_epoch,
+                            behavior::canvas_workspace::Event::Pan(Vector::new(31., -17.)),
+                        ))
+                    }
+                    Canvas::Scenario => {
+                        Message::ScenarioCanvas(behavior::scenario::CanvasEvent::Camera(
+                            app.scenario_context().unwrap(),
+                            app.camera_epoch,
+                            behavior::canvas_workspace::Event::Pan(Vector::new(31., -17.)),
+                        ))
+                    }
+                },
+                1 => Message::Field("/name".into(), "Pending title edit".into()),
+                _ => Message::Page(Page::Catalog),
+            };
+            send(&mut app, event);
+            assert!(
+                app.pending_diagram_reveal.is_none(),
+                "{canvas:?} action {action}"
+            );
+            let camera = app.camera_boundary();
+            let page = app.page;
+            // A stale layout callback at the already retained size cannot
+            // restore the old navigation camera after deliberate user input.
+            send(
+                &mut app,
+                measurement(canvas, context, epoch, target.surface, WIDE),
+            );
+            assert!(app.pending_diagram_reveal.is_none());
+            assert!(
+                app.camera_boundary() == camera,
+                "{canvas:?} action {action}"
+            );
+            assert_eq!(app.page, page);
+            assert!(Arc::ptr_eq(&accepted, &app.document.snapshot()));
+            if action == 1 {
+                assert!(app.draft_dirty());
+            }
+        }
+    }
+}

crates/oa-desktop/src/app/diagram_usages.rs

@@ -0,0 +1,407 @@
+//! Navigation-only adapter: validates destinations before changing presentation.
+use super::*;
+use crate::diagram_usage::{self as usage, Context, Event, Panel, Surface, Target, Usage};
+#[cfg(test)]
+mod tests;
+
+impl App {
+    pub(crate) fn diagram_usage_message(&self, subject: Id) -> Message {
+        Message::DiagramUsage(Event::Open(Context {
+            document: self.canvas_document,
+            revision: self.document.revision(),
+            subject,
+        }))
+    }
+
+    fn usage_navigation_available(&self) -> bool {
+        !self.busy
+            && self.pending.is_none()
+            && self.file_prompt.is_none()
+            && !self.delete_pending
+            && self.workflow.is_none()
+            && !self.hosted.visible
+            && self.architecture.is_none()
+            && !self.reference_input_active()
+            && !self.behavior.has_pending()
+            && !self.draft_dirty()
+            && !self.source_dirty()
+    }
+
+    /// Admit at most one expensive lookup, including one accepted Project clone.
+    /// A replacement panel waits for the previous worker's exact completion.
+    fn start_diagram_lookup(&mut self) -> Task<Message> {
+        let Some(panel) = self.diagram_usages.as_ref() else {
+            return Task::none();
+        };
+        if !panel.loading || self.diagram_lookup_in_flight.is_some() {
+            return Task::none();
+        }
+        let (token, context) = (panel.token, panel.context);
+        if context.document != self.canvas_document
+            || context.revision != self.document.revision()
+            || !self.usage_navigation_available()
+        {
+            let panel = self.diagram_usages.as_mut().unwrap();
+            panel.loading = false;
+            panel.notice = Some(
+                "The model or pending edits changed. Reopen diagram navigation when ready.".into(),
+            );
+            return Task::none();
+        }
+        let project = self.project().clone();
+        let presentation = self.behavior.topology.usage_snapshot();
+        self.diagram_lookup_in_flight = Some(token);
+        Task::perform(
+            async move {
+                let result = tokio::task::spawn_blocking(move || {
+                    let process = presentation.into_query_state();
+                    let scenario = behavior::scenario::State::default();
+                    usage::collect(&project, context.subject, &process, &scenario)
+                })
+                .await
+                .map_err(|error| format!("Diagram lookup failed: {error}. Close and try again."));
+                usage::Completion {
+                    token,
+                    context,
+                    result,
+                }
+            },
+            Message::DiagramUsagesReady,
+        )
+    }
+
+    fn refresh_diagram_lookup(&mut self, notice: &str) -> Task<Message> {
+        let Some(panel) = self.diagram_usages.as_mut() else {
+            return Task::none();
+        };
+        panel.token = Id::new_v4();
+        panel.context.revision = self.document.revision();
+        panel.usages.clear();
+        panel.loading = true;
+        panel.page = 0;
+        panel.cursor = 0;
+        panel.destination = None;
+        panel.notice = Some(notice.into());
+        self.start_diagram_lookup()
+    }
+
+    /// Must run before modal/input dispatch. A closed or replaced panel still
+    /// owns its worker slot until this exact completion arrives.
+    pub(super) fn diagram_usages_ready(&mut self, completion: usage::Completion) -> Task<Message> {
+        if self.diagram_lookup_in_flight != Some(completion.token) {
+            return Task::none();
+        }
+        self.diagram_lookup_in_flight = None;
+        let Some(panel) = self.diagram_usages.as_ref() else {
+            return Task::none();
+        };
+        if panel.context.document != self.canvas_document {
+            self.diagram_usages = None;
+            return Task::none();
+        }
+        if panel.context.revision != self.document.revision() {
+            return self
+                .refresh_diagram_lookup("The model changed. Review the refreshed destinations.");
+        }
+        if panel.token != completion.token {
+            // A newer Open/refresh waited without cloning or spawning a second job.
+            return self.start_diagram_lookup();
+        }
+        let panel = self.diagram_usages.as_mut().unwrap();
+        if panel.context != completion.context || !panel.loading {
+            panel.loading = false;
+            panel.notice = Some(
+                "This lookup no longer matches the requested model. Close and try again.".into(),
+            );
+            return Task::none();
+        }
+        panel.loading = false;
+        match completion.result {
+            Ok(usages) => panel.usages = usages,
+            Err(error) => panel.notice = Some(error),
+        }
+        Task::none()
+    }
+
+    /// Selection validates one destination only; opening the chooser does the
+    /// whole-project scan on its worker, never on the GUI thread.
+    fn current_surface_usages(&self, subject: Id, surface: Surface) -> Vec<Usage> {
+        match surface {
+            Surface::Saved(diagram) => {
+                usage::saved_usages_for(self.project(), subject, Some(diagram))
+            }
+            Surface::Process(owner) => {
+                self.behavior
+                    .topology
+                    .diagram_usages(self.project(), owner, subject)
+            }
+            Surface::Scenario(owner) => {
+                self.behavior
+                    .scenario
+                    .diagram_usages(self.project(), owner, subject)
+            }
+        }
+    }
+
+    pub(super) fn diagram_usage_event(&mut self, event: Event) -> Task<Message> {
+        if let Event::Open(context) = event {
+            if context.document != self.canvas_document
+                || context.revision != self.document.revision()
+                || !self.project().contains(context.subject)
+            {
+                return Task::none();
+            }
+            if !self.usage_navigation_available() {
+                self.status = "Apply or revert pending edits before opening diagram navigation. Your inputs are retained.".into();
+                return Task::none();
+            }
+            let mut panel = Panel::new(context, Vec::new());
+            panel.loading = true;
+            let filter_id = format!("diagram-usage-filter-{}", panel.token);
+            self.diagram_usages = Some(panel);
+            self.model_menu = None;
+            self.canvas_epoch = self.canvas_epoch.wrapping_add(1);
+            return Task::batch([
+                self.start_diagram_lookup(),
+                iced::widget::operation::focus(filter_id),
+            ]);
+        }
+        let token = match &event {
+            Event::Open(_) => unreachable!(),
+            Event::Close(t)
+            | Event::Search(t, _)
+            | Event::Page(t, _)
+            | Event::Move(t, _)
+            | Event::Activate(t)
+            | Event::Destination(t, _)
+            | Event::Choose(t, _) => *t,
+        };
+        let Some(panel) = &self.diagram_usages else {
+            return Task::none();
+        };
+        if panel.token != token {
+            return Task::none();
+        }
+        if matches!(event, Event::Close(_)) {
+            self.diagram_usages = None;
+            if self.page == Page::Text {
+                self.restore_source_editor_focus();
+            }
+            return Task::none();
+        }
+        if panel.context.document != self.canvas_document {
+            self.diagram_usages = None;
+            return Task::none();
+        }
+        if panel.context.revision != self.document.revision() {
+            return self
+                .refresh_diagram_lookup("The model changed. Review the refreshed destinations.");
+        }
+        if panel.loading {
+            // Search and Close remain useful while loading; queued activation
+            // must not perform a synchronous fallback or choose an old row.
+            if let Event::Search(_, query) = event {
+                self.diagram_usages.as_mut().unwrap().search = query;
+            }
+            return Task::none();
+        }
+        match event {
+            Event::Move(_, direction) => {
+                let panel = self.diagram_usages.as_ref().unwrap();
+                let count = panel.choices(self.project()).len();
+                let panel = self.diagram_usages.as_mut().unwrap();
+                if count > 0 {
+                    panel.cursor = if direction < 0 {
+                        (panel.cursor + count - 1) % count
+                    } else {
+                        (panel.cursor + 1) % count
+                    };
+                    panel.page = panel.cursor / 6;
+                }
+            }
+            Event::Activate(_) => {
+                let panel = self.diagram_usages.as_ref().unwrap();
+                if let Some(event) = panel.choices(self.project()).get(panel.cursor).cloned() {
+                    return self.diagram_usage_event(event);
+                }
+            }
+            Event::Search(_, query) => {
+                let panel = self.diagram_usages.as_mut().unwrap();
+                panel.search = query;
+                panel.page = 0;
+                panel.cursor = 0;
+            }
+            Event::Page(_, page) => {
+                let panel = self.diagram_usages.as_mut().unwrap();
+                panel.page = page;
+                panel.cursor = page.saturating_mul(6);
+            }
+            Event::Destination(_, surface) => {
+                let panel = self.diagram_usages.as_mut().unwrap();
+                if surface.is_none() || panel.usages.iter().any(|u| Some(u.surface) == surface) {
+                    panel.destination = surface;
+                    panel.page = 0;
+                    panel.cursor = 0;
+                }
+            }
+            Event::Choose(_, requested) => {
+                if !self.usage_navigation_available() {
+                    return Task::none();
+                }
+                let subject = self.diagram_usages.as_ref().unwrap().context.subject;
+                let fresh = self
+                    .current_surface_usages(subject, requested.surface)
+                    .into_iter()
+                    .find(|u| u.subject == requested.subject && u.target == requested.target);
+                let Some(fresh) = fresh else {
+                    return self.refresh_diagram_lookup(
+                        "This representation changed. Review the refreshed destinations.",
+                    );
+                };
+                if self.reveal_diagram_usage(&fresh) {
+                    self.diagram_usages = None;
+                    self.status = format!(
+                        "{} · {} in {}",
+                        self.project().named(subject),
+                        fresh.role,
+                        self.project().named(fresh.surface.id())
+                    );
+                    return Task::batch(["model-explorer", "model-browser", "inspector"].map(
+                        |id| {
+                            iced::widget::operation::snap_to(
+                                id,
+                                iced::widget::scrollable::RelativeOffset::START,
+                            )
+                        },
+                    ));
+                }
+            }
+            Event::Open(_) | Event::Close(_) => unreachable!(),
+        }
+        Task::none()
+    }
+
+    pub(super) fn reveal_diagram_usage(&mut self, usage: &Usage) -> bool {
+        if !self.usage_navigation_available() {
+            return false;
+        }
+        let previous_layer = self.layer;
+        let p = self.document.project();
+        let (selected, placement) = match &usage.target {
+            Target::Whole => (usage.surface.id(), None),
+            Target::Placement(id) => {
+                let Some(node) = p
+                    .diagrams
+                    .get(&usage.surface.id())
+                    .and_then(|d| d.nodes.get(id))
+                else {
+                    return false;
+                };
+                (node.element, Some(*id))
+            }
+            Target::Port { port, placement } => (*port, Some(*placement)),
+            Target::StateRow {
+                placement,
+                relation,
+            } => (*relation, Some(*placement)),
+            Target::Edge(id) | Target::ProcessLink(id) | Target::ScenarioObject(id) => (*id, None),
+            Target::ProcessOccurrence(endpoint) => (
+                endpoint
+                    .references
+                    .first()
+                    .copied()
+                    .unwrap_or(endpoint.occurrence),
+                None,
+            ),
+        };
+        match usage.surface {
+            Surface::Saved(id) => {
+                let Some(diagram) = p.diagrams.get(&id) else {
+                    return false;
+                };
+                self.layer = diagram.layer;
+                self.active_diagram = Some(id);
+                if let Some(machine) = diagram.projection.state_machine() {
+                    let viewport = self.behavior.diagram.viewport.unwrap_or(iced::Size::new(
+                        (self.window_size.width - 610.).max(280.),
+                        (self.window_size.height - 320.).max(240.),
+                    ));
+                    let (zoom, pan) = usage::camera_for(&usage.target, usage.bounds, viewport);
+                    self.behavior.diagram = behavior::state_view::State {
+                        diagram: Some(id),
+                        placement,
+                        viewport: Some(viewport),
+                        zoom,
+                        pan,
+                        fit: false,
+                        ..Default::default()
+                    };
+                    self.behavior.active_owner = Some(machine);
+                    self.page = Page::Behavior;
+                } else {
+                    let viewport = self.canvas_size.unwrap_or(iced::Size::new(
+                        (self.window_size.width - 550.).max(280.),
+                        (self.window_size.height - 284.).max(240.),
+                    ));
+                    (self.zoom, self.pan) =
+                        usage::camera_for(&usage.target, usage.bounds, viewport);
+                    self.fit_to_view = false;
+                    self.page = Page::Diagram;
+                }
+            }
+            Surface::Process(owner) => {
+                if !self.behavior.topology.reveal_usage(
+                    p,
+                    self.canvas_document,
+                    owner,
+                    &usage.target,
+                ) {
+                    return false;
+                }
+                self.layer = p.elements[&owner].layer();
+                self.behavior.active_owner = Some(owner);
+                self.page = Page::Behavior;
+            }
+            Surface::Scenario(owner) => {
+                if !self.behavior.scenario.reveal_usage(
+                    p,
+                    self.canvas_document,
+                    owner,
+                    &usage.target,
+                ) {
+                    return false;
+                }
+                self.layer = p.elements[&owner].layer();
+                self.behavior.active_owner = Some(owner);
+                self.page = Page::Behavior;
+            }
+        }
+        self.selected = selected;
+        self.selected_node = placement;
+        self.model_menu = None;
+        self.canvas_epoch = self.canvas_epoch.wrapping_add(1);
+        self.selected_bend = None;
+        self.connection = None;
+        self.last_workspace_page = self.page;
+        if previous_layer != self.layer {
+            self.data_state = Default::default();
+            self.explorer_index = crate::explorer::Index::new(self.project(), self.layer);
+            self.explorer_focus = None;
+            self.explorer_group = None;
+            self.explorer_page = 0;
+        }
+        self.normalize_creation();
+        self.reveal_explorer_selection();
+        self.refresh_draft();
+        self.pending_diagram_reveal = Some((
+            Context {
+                document: self.canvas_document,
+                revision: self.document.revision(),
+                subject: usage.subject,
+            },
+            usage.clone(),
+            self.canvas_epoch,
+        ));
+        true
+    }
+}

crates/oa-desktop/src/app/hosted.rs

@@ -213,6 +213,14 @@ impl App {
             self.pending = None;
             return Task::none();
         }
+        if self.path.is_some()
+            || self.hosted.session.as_ref().is_none_or(|session| {
+                session.resource_id != remote.resource_id
+                    || session.connection.base() != request.connection.base()
+            })
+        {
+            self.source_workspace.reset_navigation_session();
+        }
         self.hosted.session = Some(Session {
             connection: request.connection.clone(),
             resource_id: remote.resource_id,
@@ -345,6 +353,14 @@ impl App {
                         match self.document.apply_compiled((*remote.compiled).clone()) {
                             Ok(_) => {
                                 self.document.mark_saved(remote.compiled.clone());
+                                if self.path.is_some()
+                                    || self.hosted.session.as_ref().is_none_or(|session| {
+                                        session.resource_id != remote.resource_id
+                                            || session.connection.base() != connection.base()
+                                    })
+                                {
+                                    self.source_workspace.reset_navigation_session();
+                                }
                                 self.hosted.session = Some(Session {
                                     connection,
                                     resource_id: remote.resource_id,

crates/oa-desktop/src/app/source_symbols.rs

@@ -0,0 +1,507 @@
+//! Current draft navigation, isolated from model application and disk discovery.
+use super::*;
+use crate::source_navigation::{self as nav, query};
+use std::sync::atomic::Ordering;
+
+fn admission_notice(error: query::AdmissionError) -> String {
+    use nav::symbols::{BuildError, InputProblem, Resource};
+    let (limit, resource) = match error {
+        query::AdmissionError::Index(BuildError::Limit { limit, resource, .. }) => (limit, resource),
+        query::AdmissionError::Outline { error, .. } => (error.limit, match error.resource {
+            language::OutlineResource::SourceBytes => Resource::SourceBytes,
+            language::OutlineResource::Tokens => Resource::Tokens,
+            language::OutlineResource::Declarations => Resource::Records,
+        }),
+        query::AdmissionError::Index(BuildError::Input { problem, .. }) => return match problem {
+            InputProblem::NonCanonicalPath | InputProblem::DuplicateOrCaseCollidingPath =>
+                "Navigation needs distinct relative source paths. Check file names and include paths.".into(),
+            _ => "Navigation could not verify the current source locations. Correct source errors and try again.".into(),
+        },
+    };
+    let unit = match resource {
+        Resource::Files => "loaded files",
+        Resource::SourceBytes => "source bytes",
+        Resource::PathBytes => "bytes in file paths",
+        Resource::Tokens => "source tokens",
+        Resource::Records => "declarations and references",
+    };
+    format!(
+        "Navigation reached its limit of {limit} {unit}. Reduce the loaded source size and try again."
+    )
+}
+
+impl App {
+    pub fn source_symbol_context(&self) -> nav::SymbolContext {
+        nav::SymbolContext {
+            session: self.source_workspace.session(),
+            path: self.source_workspace.active.clone(),
+        }
+    }
+
+    pub fn source_symbol_message(&self, event: nav::SymbolEvent) -> Message {
+        Message::SourceSymbols(self.source_symbol_context(), event)
+    }
+
+    pub fn source_find_close_message(&self) -> Message {
+        Message::SourceFindClose(self.source_symbol_context(), self.source_find_instance)
+    }
+    pub fn source_key(&self) -> query::SnapshotKey {
+        query::SnapshotKey {
+            workspace: self.source_workspace.session(),
+            revision: self.source_workspace.revision(),
+        }
+    }
+
+    fn with_source_input<T>(&self, use_input: impl FnOnce(query::Input<'_>) -> T) -> T {
+        let files: Vec<_> = self
+            .source_workspace
+            .files
+            .iter()
+            .map(|(path, buffer)| query::DraftFile {
+                path,
+                text: &buffer.text,
+            })
+            .collect();
+        let accepted = self.document.bundle();
+        let validated: Vec<_> = accepted
+            .files
+            .iter()
+            .map(|(path, text)| query::DraftFile { path, text })
+            .collect();
+        use_input(query::Input {
+            key: self.source_key(),
+            entry: &self.source_workspace.entry,
+            files: &files,
+            applied: self.source_workspace.applied,
+            validation: self
+                .source_workspace
+                .applied
+                .then_some(query::ValidatedSources {
+                    entry: &accepted.entry,
+                    files: &validated,
+                }),
+        })
+    }
+
+    fn source_snapshot_matches(&self, snapshot: &query::Snapshot) -> bool {
+        snapshot.key() == self.source_key()
+            && self.with_source_input(|input| snapshot.matches(input))
+    }
+
+    pub fn source_navigation_available(&self) -> bool {
+        self.page == Page::Text
+            && !self.busy
+            && self.pending.is_none()
+            && self.file_prompt.is_none()
+            && !self.delete_pending
+            && self.workflow.is_none()
+            && !self.hosted.visible
+            && self.model_menu.is_none()
+            && self.diagram_usages.is_none()
+            && !self.reference_input_active()
+            && self.architecture.is_none()
+            && !self.behavior.has_pending()
+    }
+
+    /// Mounted widget IDs change when another interaction supersedes a reveal.
+    /// A queued focus operation therefore cannot find a subsequently reused editor.
+    pub fn source_editor_id(&self) -> iced::widget::Id {
+        iced::widget::Id::from(format!(
+            "source-editor-{}-{}-{}",
+            self.source_workspace.session(),
+            self.source_workspace.active,
+            self.source_symbols.interaction
+        ))
+    }
+
+    pub fn source_reveal_ticket(&self) -> Option<Id> {
+        self.source_symbols
+            .reveal
+            .as_ref()
+            .map(|reveal| reveal.ticket)
+    }
+
+    pub(super) fn source_interaction(&mut self) {
+        self.source_symbols.interaction = Id::new_v4();
+        self.source_symbols.request = None;
+        self.source_symbols.reveal = None;
+        self.source_jump = None;
+    }
+
+    pub(super) fn queue_source_reveal(&mut self, cursor: text_editor::Cursor, select_line: bool) {
+        self.source_jump = Some(cursor);
+        self.source_select_line = select_line;
+        self.source_symbols.reveal = Some(nav::Reveal {
+            ticket: Id::new_v4(),
+            interaction: self.source_symbols.interaction,
+            raw_interaction: self.source_symbols.raw_interaction.load(Ordering::SeqCst),
+            snapshot: self.source_key(),
+            path: self.source_workspace.active.clone(),
+        });
+    }
+
+    pub(super) fn restore_source_editor_focus(&mut self) {
+        let cursor = self.source_editor.cursor();
+        if self.source_navigation_available()
+            && nav::exact_cursor(self.source_workspace.text(), cursor)
+        {
+            self.queue_source_reveal(cursor, false);
+        }
+    }
+
+    pub(super) fn source_viewport(&mut self, ticket: Option<Id>) -> Task<Message> {
+        let Some(reveal) = &self.source_symbols.reveal else {
+            return Task::none();
+        };
+        if Some(reveal.ticket) != ticket
+            || reveal.interaction != self.source_symbols.interaction
+            || !nav::interaction::is_current(
+                &self.source_symbols.raw_interaction,
+                reveal.raw_interaction,
+            )
+            || reveal.snapshot != self.source_key()
+            || reveal.path != self.source_workspace.active
+            || !self.source_navigation_available()
+        {
+            return Task::none();
+        }
+        let raw_interaction = reveal.raw_interaction;
+        self.source_symbols.reveal = None;
+        if let Some(cursor) = self.source_jump.take() {
+            if !nav::exact_cursor(self.source_workspace.text(), cursor) {
+                return Task::none();
+            }
+            self.source_editor.move_to(cursor);
+            if self.source_select_line && cursor.selection.is_none() {
+                self.source_editor.perform(text_editor::Action::SelectLine);
+            }
+            return nav::interaction::guarded_focus(
+                self.source_editor_id(),
+                self.source_symbols.raw_interaction.clone(),
+                raw_interaction,
+            );
+        }
+        Task::none()
+    }
+
+    pub(super) fn source_symbol_event(&mut self, event: nav::SymbolEvent) -> Task<Message> {
+        if !self.source_navigation_available() {
+            return Task::none();
+        }
+        match event {
+            nav::SymbolEvent::DiagramUsages => {
+                if self.source_dirty() || !self.source_workspace.applied {
+                    self.source_symbols.open = true;
+                    self.source_symbols.notice = Some("Apply source before finding diagram representations. Your current text is retained.".into());
+                    return Task::none();
+                }
+                let task = self.start_source_query(query::Action::Definition);
+                self.source_diagram_job = self
+                    .source_symbols
+                    .request
+                    .as_ref()
+                    .map(|request| request.job);
+                return task;
+            }
+            nav::SymbolEvent::Close => {
+                self.source_symbols.open = false;
+                self.source_symbols.results = None;
+                self.source_symbols.notice = None;
+            }
+            nav::SymbolEvent::Back => {
+                self.source_symbol_back();
+                // A successful Back needs no empty results panel. Retain an
+                // already open panel, or reveal an actionable return notice.
+                self.source_symbols.open |= self.source_symbols.notice.is_some();
+            }
+            nav::SymbolEvent::Choose {
+                stamp,
+                reference,
+                index,
+            } => {
+                let Some(results) = self.source_symbols.results.clone() else {
+                    return Task::none();
+                };
+                if results.stamp != stamp
+                    || stamp.snapshot != self.source_key()
+                    || self
+                        .source_symbols
+                        .cache
+                        .as_ref()
+                        .is_none_or(|cache| !self.source_snapshot_matches(cache))
+                {
+                    self.source_symbols.notice =
+                        Some("Source changed. Run navigation again for current locations.".into());
+                    return Task::none();
+                }
+                let destination = if reference {
+                    results
+                        .references
+                        .get(index)
+                        .map(|row| (&row.path, row.position, row.end_position))
+                } else {
+                    results
+                        .definitions
+                        .get(index)
+                        .map(|row| (&row.path, row.position, row.end_position))
+                };
+                if let Some((path, start, end)) = destination {
+                    self.source_symbol_jump(path, start, end);
+                }
+            }
+            nav::SymbolEvent::Query(action) => return self.start_source_query(action),
+        }
+        Task::none()
+    }
+
+    fn start_source_query(&mut self, action: query::Action) -> Task<Message> {
+        self.source_symbols.open = true;
+        if !nav::interaction::is_current(
+            &self.source_symbols.raw_interaction,
+            self.source_symbols.raw_interaction.load(Ordering::SeqCst),
+        ) {
+            self.source_symbols.notice = Some("Reopen this workspace to reset navigation.".into());
+            return Task::none();
+        }
+        if self.source_symbols.in_flight.is_some() {
+            self.source_symbols.notice = Some("Navigation is finishing. Try again shortly.".into());
+            return Task::none();
+        }
+        let cursor = self.source_editor.cursor();
+        let Some(offset) = nav::cursor_offset(self.source_workspace.text(), cursor) else {
+            self.source_symbols.notice =
+                Some("Place the cursor on an alias or its @ reference.".into());
+            return Task::none();
+        };
+        self.source_symbols.serial = match self.source_symbols.serial.checked_add(1) {
+            Some(serial) => serial,
+            None => {
+                self.source_workspace.reset_navigation_session();
+                self.source_symbols.back.clear();
+                self.source_symbols.cache = None;
+                0
+            }
+        };
+        let request = nav::Request {
+            job: Id::new_v4(),
+            interaction: self.source_symbols.interaction,
+            raw_interaction: self.source_symbols.raw_interaction.load(Ordering::SeqCst),
+            stamp: query::QueryStamp {
+                snapshot: self.source_key(),
+                serial: self.source_symbols.serial,
+            },
+            path: self.source_workspace.active.clone(),
+            offset,
+            cursor,
+            action,
+        };
+        let cache = self
+            .source_symbols
+            .cache
+            .as_ref()
+            .filter(|cache| self.source_snapshot_matches(cache))
+            .cloned();
+        let input = if cache.is_none() {
+            match self
+                .with_source_input(|input| query::admit_owned(input, query::Limits::default()))
+            {
+                Ok(input) => Some(input),
+                Err(error) => {
+                    self.source_symbols.notice = Some(admission_notice(error));
+                    return Task::none();
+                }
+            }
+        } else {
+            None
+        };
+        self.source_symbols.in_flight = Some(request.job);
+        self.source_symbols.request = Some(request.clone());
+        self.source_symbols.results = None;
+        self.source_symbols.notice = None;
+        Task::perform(
+            async move {
+                let worker_request = request.clone();
+                let result = tokio::task::spawn_blocking(move || {
+                    let snapshot = match cache {
+                        Some(cache) => cache,
+                        None => Arc::new(
+                            input
+                                .expect("admitted input for uncached request")
+                                .capture()
+                                .map_err(admission_notice)?,
+                        ),
+                    };
+                    let results = snapshot
+                        .query(query::Query {
+                            stamp: worker_request.stamp,
+                            path: &worker_request.path,
+                            byte_offset: worker_request.offset,
+                            action: worker_request.action,
+                        })
+                        .map_err(|error| match error {
+                            query::QueryError::ResultEnvelopeLimit => "These result details exceed the display limit. Try literal Find for this alias.".to_owned(),
+                            _ => "Navigation could not verify this location. Place the cursor on an alias and try again.".to_owned(),
+                        })?;
+                    Ok((snapshot, Arc::new(results)))
+                })
+                .await
+                .unwrap_or_else(|error| Err(format!("Navigation task failed: {error}")));
+                nav::Completion { request, result }
+            },
+            Message::SourceSymbolsReady,
+        )
+    }
+
+    pub(super) fn source_symbols_ready(&mut self, completion: nav::Completion) -> Task<Message> {
+        let request = completion.request;
+        if self.source_symbols.in_flight != Some(request.job) {
+            return Task::none();
+        }
+        self.source_symbols.in_flight = None;
+        let diagram_query = self.source_diagram_job == Some(request.job);
+        if diagram_query {
+            self.source_diagram_job = None;
+        }
+        let wanted = self
+            .source_symbols
+            .request
+            .take()
+            .is_some_and(|current| current.job == request.job)
+            && request.interaction == self.source_symbols.interaction
+            && request.stamp.snapshot == self.source_key()
+            && nav::interaction::is_current(
+                &self.source_symbols.raw_interaction,
+                request.raw_interaction,
+            )
+            && request.path == self.source_workspace.active
+            && request.cursor == self.source_editor.cursor()
+            && self.source_navigation_available();
+        if !wanted {
+            return Task::none();
+        }
+        match completion.result {
+            Ok((snapshot, results)) if self.source_snapshot_matches(&snapshot) => {
+                self.source_symbols.cache = Some(snapshot);
+                self.source_symbols.results = Some(results.clone());
+                if diagram_query {
+                    if results.disposition == query::Disposition::Direct
+                        && results.scope.validated
+                        && results.omitted_definitions == 0
+                        && let [row] = results.definitions.as_slice()
+                        && let query::Identity::Unique(identity) = row.declaration.identity
+                        && row.membership == query::Membership::Included
+                        && row.evidence == query::Evidence::Validated
+                        && self.project().contains(identity.id())
+                        && crate::diagram_usage::alias(self.project(), identity.id())
+                            == row.declaration.alias
+                    {
+                        self.source_symbols.open = false;
+                        return self.diagram_usage_event(crate::diagram_usage::Event::Open(
+                            crate::diagram_usage::Context {
+                                document: self.canvas_document,
+                                revision: self.document.revision(),
+                                subject: identity.id(),
+                            },
+                        ));
+                    }
+                    self.source_symbols.notice = Some("Place the caret on a uniquely resolved alias in applied source to find diagram representations.".into());
+                    return Task::none();
+                }
+                if results.disposition == query::Disposition::Direct
+                    && let Some(row) = results.definitions.first()
+                {
+                    self.source_symbol_jump(&row.path, row.position, row.end_position);
+                }
+            }
+            Ok(_) => {
+                self.source_symbols.notice = Some("Source changed. Run navigation again.".into())
+            }
+            Err(error) => self.source_symbols.notice = Some(error),
+        }
+        Task::none()
+    }
+
+    fn source_symbol_jump(&mut self, path: &str, start: query::Position, end: query::Position) {
+        let cursor = text_editor::Cursor {
+            position: text_editor::Position {
+                line: start.line,
+                column: start.byte_column,
+            },
+            selection: Some(text_editor::Position {
+                line: end.line,
+                column: end.byte_column,
+            }),
+        };
+        if self
+            .source_workspace
+            .files
+            .get(path)
+            .is_none_or(|buffer| !nav::exact_cursor(&buffer.text, cursor))
+        {
+            self.source_symbols.notice =
+                Some("That source location is no longer available. Run navigation again.".into());
+            return;
+        }
+        if let Some(buffer) = self
+            .source_workspace
+            .files
+            .get(&self.source_workspace.active)
+        {
+            let origin = nav::HistoryEntry {
+                session: self.source_workspace.session(),
+                path: self.source_workspace.active.clone(),
+                generation: buffer.generation(),
+                cursor: self.source_editor.cursor(),
+            };
+            self.source_symbols
+                .back
+                .retain(|entry| entry.session == origin.session);
+            if self.source_symbols.back.len() == 64 {
+                self.source_symbols.back.remove(0);
+            }
+            self.source_symbols.back.push(origin);
+        }
+        self.source_workspace
+            .switch(path, self.source_editor.cursor());
+        self.show_source_file(false);
+        self.queue_source_reveal(cursor, false);
+    }
+
+    fn source_symbol_back(&mut self) {
+        while let Some(origin) = self.source_symbols.back.pop() {
+            if origin.session != self.source_workspace.session() {
+                continue;
+            }
+            let Some(buffer) = self.source_workspace.files.get(&origin.path) else {
+                self.source_symbols.notice = Some("The previous file is no longer loaded.".into());
+                return;
+            };
+            let unchanged = origin.generation == buffer.generation();
+            let cursor = if unchanged {
+                origin.cursor
+            } else if origin.path == self.source_workspace.active {
+                self.source_editor.cursor()
+            } else {
+                buffer.cursor
+            };
+            if !nav::exact_cursor(&buffer.text, cursor) {
+                self.source_symbols.notice = Some(
+                    "The previous location changed. Open the file to choose a current position."
+                        .into(),
+                );
+                return;
+            }
+            self.source_workspace
+                .switch(&origin.path, self.source_editor.cursor());
+            self.show_source_file(false);
+            self.queue_source_reveal(cursor, false);
+            self.source_symbols.notice =
+                (!unchanged).then(|| "This draft changed; its current cursor was restored.".into());
+            return;
+        }
+        self.source_symbols.notice = Some("No previous source location in this workspace.".into());
+    }
+}
+
+#[cfg(test)]
+mod tests;

crates/oa-desktop/src/behavior.rs

@@ -1156,6 +1156,17 @@ struct Line {
     label_at: Point,
     dashed: bool,
 }
+impl Line {
+    fn label_bounds(&self) -> Rectangle {
+        Rectangle::new(
+            self.label_at,
+            Size::new(
+                (self.label.chars().count() as f32 * 6.8 + 8.).min(225.),
+                25.,
+            ),
+        )
+    }
+}
 struct Scene {
     boxes: Vec<BoxItem>,
     lines: Vec<Line>,
@@ -1831,17 +1842,7 @@ impl Scene {
             .or_else(|| {
                 self.lines
                     .iter()
-                    .find(|line| {
-                        !line.label.is_empty()
-                            && Rectangle::new(
-                                line.label_at,
-                                Size::new(
-                                    (line.label.chars().count() as f32 * 6.8 + 8.).min(225.),
-                                    25.,
-                                ),
-                            )
-                            .contains(point)
-                    })
+                    .find(|line| !line.label.is_empty() && line.label_bounds().contains(point))
                     .map(|line| line.id)
             })
             .or_else(|| self.near_sequence_item(point))

crates/oa-desktop/src/behavior/canvas_workspace.rs

@@ -17,6 +17,7 @@ pub fn keyboard_enabled(app: &crate::app::App) -> bool {
         && !app.delete_pending
         && app.pending.is_none()
         && app.model_menu.is_none()
+        && app.diagram_usages.is_none()
         && !app.reference_input_active()
 }
 

crates/oa-desktop/src/behavior/scenario.rs

@@ -5,6 +5,7 @@ use super::*;
 use iced::widget::{Column, column, text_input};
 use std::{cell::RefCell, collections::BTreeSet};
 pub(crate) mod focus;
+mod usage;
 mod workspace;
 pub(crate) use workspace::NAME_INPUT;
 pub use workspace::{Shelf, view};

crates/oa-desktop/src/behavior/scenario/usage.rs

@@ -0,0 +1,207 @@
+//! Navigation is derived from the same opaque-reference scene that is painted.
+use super::*;
+use crate::diagram_usage::{Surface, Target, Usage};
+
+/// The renderer collapses whitespace before shortening. Require at least one
+/// actual character of this field, rather than an ellipsis at its start.
+fn label_field_visible(full: &str, prefix: &str, value: &str) -> bool {
+    if value.trim().is_empty() {
+        return false;
+    }
+    let normalized = full.split_whitespace().collect::<Vec<_>>().join(" ");
+    let normalized_prefix = prefix.split_whitespace().collect::<Vec<_>>().join(" ");
+    let start = normalized_prefix.len()
+        + usize::from(prefix.ends_with(char::is_whitespace) && !normalized_prefix.is_empty());
+    let painted = crate::views::short(full, 32);
+    let retained = normalized
+        .chars()
+        .zip(painted.chars())
+        .take_while(|(a, b)| a == b)
+        .map(|(c, _)| c.len_utf8())
+        .sum::<usize>();
+    start < retained
+}
+
+fn usages(p: &Project, owner: Id, subject: Id, scene: &Scene) -> Vec<Usage> {
+    let mut result = Vec::new();
+    let mut add = |id, bounds, role: &str| {
+        // Activation bars share the occurrence identity with a labelled message;
+        // they must not inflate its target count.
+        if !result
+            .iter()
+            .any(|u: &Usage| u.target == Target::ScenarioObject(id))
+        {
+            result.push(Usage {
+                subject,
+                surface: Surface::Scenario(owner),
+                target: Target::ScenarioObject(id),
+                role: role.into(),
+                bounds,
+            });
+        }
+    };
+    for item in scene.boxes.iter().filter(|item| !item.title.is_empty()) {
+        let Some(element) = p.elements.get(&item.id) else {
+            continue;
+        };
+        if subject == item.id {
+            // A fragment's selectable header is useful even when its frame is
+            // much larger than the viewport.
+            let mut bounds = item.rect;
+            if item.marker == Some(Kind::Occurrence) {
+                bounds.height = bounds.height.min(38.);
+            }
+            add(item.id, bounds, "scenario object");
+        }
+        let represented = match element.shared() {
+            Some(SharedBody::Lifeline { represented }) => represented.map(|id| (id, "lifeline")),
+            Some(SharedBody::Occurrence { body, .. }) => match body {
+                OccurrenceBody::Action { action, .. } => action.map(|id| (id, "action occurrence")),
+                OccurrenceBody::State { state, .. } => state.map(|id| (id, "state observation")),
+                OccurrenceBody::SequenceReference { sequence } => {
+                    sequence.map(|id| (id, "process reference"))
+                }
+                OccurrenceBody::ScenarioUse { scenario, .. } => {
+                    scenario.map(|id| (id, "scenario reference"))
+                }
+                // An incomplete message fallback box only paints the occurrence
+                // name and a repair hint, not its exchange or operation.
+                _ => None,
+            },
+            _ => None,
+        };
+        if let Some((id, role)) = represented.filter(|(id, _)| *id == subject) {
+            let _ = id;
+            add(item.id, item.rect, role);
+        }
+    }
+    for line in scene.lines.iter().filter(|line| !line.label.is_empty()) {
+        let Some(element) = p.elements.get(&line.id) else {
+            continue;
+        };
+        let Some(SharedBody::Occurrence {
+            body: OccurrenceBody::Exchange { exchange, .. },
+            ..
+        }) = element.shared()
+        else {
+            continue;
+        };
+        let bounds = line.label_bounds();
+        if subject == line.id || *exchange == Some(subject) {
+            add(line.id, bounds, "message occurrence");
+        }
+        // Replies derive their operation from the exact call, matching the
+        // operation label formatter rather than scanning raw reference fields.
+        if let Ok(operations::OperationResolution::Selected(operation)) =
+            operations::resolve(p, line.id)
+            && let Some(label) = crate::data_values::operation_label(p, element)
+            && let Some(prefix) = line.label.strip_suffix(&label)
+        {
+            let allocation = &p.relations[&operation.allocation];
+            let operation_prefix = if matches!(
+                element.shared(),
+                Some(SharedBody::Occurrence {
+                    body: OccurrenceBody::Exchange {
+                        message_kind: MessageKind::Reply,
+                        ..
+                    },
+                    ..
+                })
+            ) {
+                "Reply operation from Call: "
+            } else {
+                "Operation: "
+            };
+            let fields = [
+                (allocation.source(), format!("{prefix}{operation_prefix}")),
+                (
+                    allocation.target(),
+                    format!(
+                        "{prefix}{operation_prefix}{} / ",
+                        p.named(allocation.source())
+                    ),
+                ),
+                (
+                    allocation.id,
+                    format!(
+                        "{prefix}{operation_prefix}{} / {} · ",
+                        p.named(allocation.source()),
+                        p.named(allocation.target())
+                    ),
+                ),
+            ];
+            for (id, prefix) in fields {
+                if id == subject && label_field_visible(&line.label, &prefix, p.named(id)) {
+                    add(line.id, bounds, "operation label");
+                }
+            }
+        }
+    }
+    if subject == owner {
+        result.insert(
+            0,
+            Usage {
+                subject,
+                surface: Surface::Scenario(owner),
+                target: Target::Whole,
+                role: "scenario".into(),
+                bounds: Rectangle::new(Point::ORIGIN, scene.size),
+            },
+        );
+    }
+    result
+}
+
+impl State {
+    pub(crate) fn diagram_usages(&self, p: &Project, owner: Id, subject: Id) -> Vec<Usage> {
+        if !p
+            .elements
+            .get(&owner)
+            .is_some_and(|e| e.kind() == Kind::Scenario)
+        {
+            return vec![];
+        }
+        usages(p, owner, subject, &Scene::sequence(p, owner, subject))
+    }
+
+    pub(crate) fn reveal_usage(
+        &mut self,
+        p: &Project,
+        document: Id,
+        owner: Id,
+        target: &Target,
+    ) -> bool {
+        if self.draft.is_some()
+            || !p
+                .elements
+                .get(&owner)
+                .is_some_and(|e| e.kind() == Kind::Scenario)
+        {
+            return false;
+        }
+        let id = match target {
+            Target::Whole => owner,
+            Target::ScenarioObject(id) => *id,
+            _ => return false,
+        };
+        let Some(usage) = self
+            .diagram_usages(p, owner, id)
+            .into_iter()
+            .find(|u| &u.target == target)
+        else {
+            return false;
+        };
+        // Preserve an existing mounted viewport across enter's owner reset.
+        let viewport = self.presentation.viewport.unwrap_or(Size::new(500., 300.));
+        self.enter(document, owner);
+        self.presentation.viewport = Some(viewport);
+        self.canvas_tool = Some((owner, CanvasTool::Select));
+        let (zoom, pan) = crate::diagram_usage::camera_for(target, usage.bounds, viewport);
+        self.presentation.zoom(Some(zoom));
+        self.presentation.pan = pan;
+        true
+    }
+}
+
+#[cfg(test)]
+mod tests;

crates/oa-desktop/src/behavior/scenario/usage/tests.rs

@@ -0,0 +1,276 @@
+use super::*;
+
+fn add_occurrence(p: &mut Project, owner: Id, name: &str, body: OccurrenceBody) -> Id {
+    let layer = p.elements[&owner].layer();
+    let id = p
+        .add_element(Kind::Occurrence, layer, name, Some(owner))
+        .unwrap();
+    *p.elements.get_mut(&id).unwrap().shared_mut().unwrap() = SharedBody::Occurrence {
+        body,
+        precondition: String::new(),
+        postcondition: String::new(),
+    };
+    if let Some(steps) = p.elements.get_mut(&owner).unwrap().steps_mut() {
+        if !steps.contains(&id) {
+            steps.push(id);
+        }
+    }
+    id
+}
+
+fn targets(state: &State, p: &Project, owner: Id, subject: Id) -> BTreeSet<Id> {
+    state
+        .diagram_usages(p, owner, subject)
+        .into_iter()
+        .filter_map(|u| match u.target {
+            Target::ScenarioObject(id) => Some(id),
+            _ => None,
+        })
+        .collect()
+}
+
+#[test]
+fn scenario_usage_counts_nested_occurrences_and_lifelines_but_keeps_reuse_opaque() {
+    for (layer, work_kind, participant_kind) in [
+        (Layer::Oa, Kind::Activity, Kind::Entity),
+        (Layer::Sa, Kind::Function, Kind::SystemActor),
+    ] {
+        let mut p = Project::empty();
+        let owner = p
+            .add_element(Kind::Scenario, layer, "Caller", None)
+            .unwrap();
+        let other = p
+            .add_element(Kind::Scenario, layer, "Definition", None)
+            .unwrap();
+        let work = p.add_element(work_kind, layer, "Respond", None).unwrap();
+        let unused = p.add_element(work_kind, layer, "Respond", None).unwrap();
+        let participant = p
+            .add_element(participant_kind, layer, "Operator", None)
+            .unwrap();
+        let lanes = ["First role", "Second role"].map(|name| {
+            let id = p
+                .add_element(Kind::Lifeline, layer, name, Some(owner))
+                .unwrap();
+            *p.elements.get_mut(&id).unwrap().shared_mut().unwrap() = SharedBody::Lifeline {
+                represented: Some(participant),
+            };
+            id
+        });
+        let first = add_occurrence(
+            &mut p,
+            owner,
+            "First action",
+            OccurrenceBody::Action {
+                action: Some(work),
+                lifeline: Some(lanes[0]),
+            },
+        );
+        let fragment = add_occurrence(
+            &mut p,
+            owner,
+            "Decision",
+            OccurrenceBody::Fragment {
+                operator: FragmentOperator::Alternative,
+                branches: vec![],
+            },
+        );
+        let branch = add_occurrence(
+            &mut p,
+            fragment,
+            "When ready",
+            OccurrenceBody::Branch {
+                guard: "ready".into(),
+                occurrences: vec![],
+            },
+        );
+        if let Some(SharedBody::Occurrence {
+            body: OccurrenceBody::Fragment { branches, .. },
+            ..
+        }) = p.elements.get_mut(&fragment).unwrap().shared_mut()
+        {
+            branches.push(branch);
+        }
+        let nested = add_occurrence(
+            &mut p,
+            branch,
+            "Again",
+            OccurrenceBody::Action {
+                action: Some(work),
+                lifeline: Some(lanes[1]),
+            },
+        );
+        let inside = add_occurrence(
+            &mut p,
+            other,
+            "Hidden inside definition",
+            OccurrenceBody::Action {
+                action: Some(unused),
+                lifeline: None,
+            },
+        );
+        let use_a = add_occurrence(
+            &mut p,
+            owner,
+            "Use A",
+            OccurrenceBody::ScenarioUse {
+                scenario: Some(other),
+                bindings: vec![],
+            },
+        );
+        let use_b = add_occurrence(
+            &mut p,
+            owner,
+            "Use B",
+            OccurrenceBody::ScenarioUse {
+                scenario: Some(other),
+                bindings: vec![],
+            },
+        );
+        let before = p.clone();
+        let state = State::default();
+        assert_eq!(
+            targets(&state, &p, owner, work),
+            BTreeSet::from([first, nested])
+        );
+        assert_eq!(
+            targets(&state, &p, owner, participant),
+            BTreeSet::from(lanes)
+        );
+        assert_eq!(
+            targets(&state, &p, owner, other),
+            BTreeSet::from([use_a, use_b])
+        );
+        assert!(targets(&state, &p, owner, unused).is_empty());
+        assert!(targets(&state, &p, owner, inside).is_empty());
+        assert_eq!(targets(&state, &p, owner, branch), BTreeSet::from([branch]));
+        assert_eq!(
+            state.diagram_usages(&p, owner, owner)[0].target,
+            Target::Whole
+        );
+        assert_eq!(p, before);
+    }
+}
+
+#[test]
+fn scenario_usage_keeps_repeated_messages_and_reveal_is_read_only_and_revalidated() {
+    let f = super::super::direct_tests::fixture();
+    let mut p = f.project;
+    let mut state = State::default();
+    assert_eq!(
+        targets(&state, &p, f.owner, f.exchange),
+        BTreeSet::from([f.call, f.reply])
+    );
+    let before = p.clone();
+    let target = Target::ScenarioObject(f.reply);
+    state.viewport(Size::new(900., 500.));
+    assert!(state.reveal_usage(&p, Id::new_v4(), f.owner, &target));
+    let usage = state
+        .diagram_usages(&p, f.owner, f.reply)
+        .into_iter()
+        .find(|u| u.target == target)
+        .unwrap();
+    let zoom = state
+        .presentation
+        .scale(Scene::sequence(&p, f.owner, f.reply).size);
+    let centered = Point::new(
+        usage.bounds.center_x() * zoom,
+        usage.bounds.center_y() * zoom,
+    ) + state.presentation.pan;
+    assert!((centered.x - 450.).abs() < 0.01 && (centered.y - 250.).abs() < 0.01);
+    assert!(zoom >= 0.5);
+    assert_eq!(p, before);
+    // Keeping an orphan semantic occurrence does not keep its painted target.
+    p.elements
+        .get_mut(&f.owner)
+        .unwrap()
+        .steps_mut()
+        .unwrap()
+        .retain(|id| *id != f.reply);
+    let camera = state.camera_boundary();
+    assert!(!state.reveal_usage(&p, Id::new_v4(), f.owner, &target));
+    assert!(camera == state.camera_boundary());
+    assert!(!state.reveal_usage(&p, Id::new_v4(), f.owner, &Target::Edge(f.exchange)));
+    // A message whose endpoints are incomplete paints only its repair box.
+    if let Some(SharedBody::Occurrence {
+        body: OccurrenceBody::Exchange { receiver, .. },
+        ..
+    }) = p.elements.get_mut(&f.call).unwrap().shared_mut()
+    {
+        *receiver = None;
+    }
+    assert!(targets(&state, &p, f.owner, f.exchange).is_empty());
+    assert_eq!(
+        targets(&state, &p, f.owner, f.call),
+        BTreeSet::from([f.call])
+    );
+}
+
+#[test]
+fn scenario_operation_label_membership_excludes_ellipsis_only_and_normalizes_whitespace() {
+    assert!(label_field_visible(
+        "1. call · X · Operation: I / O",
+        "1. call · X · Operation: ",
+        "I"
+    ));
+    assert!(!label_field_visible(
+        "1234567890123456789012345678901Ixyz",
+        "1234567890123456789012345678901",
+        "Ixyz"
+    ));
+    assert!(!label_field_visible(
+        "A very long occurrence label · Operation: I",
+        "A very long occurrence label · Operation: ",
+        "I"
+    ));
+    assert!(label_field_visible(
+        "call\n\t· Operation: 界",
+        "call\n\t· Operation: ",
+        "界"
+    ));
+    assert!(!label_field_visible("Operation: ", "Operation: ", ""));
+}
+
+#[test]
+fn scenario_usage_only_reports_the_resolved_operation_fields_actually_in_the_label() {
+    let mut p = persistence::decode(include_bytes!(concat!(
+        env!("CARGO_MANIFEST_DIR"),
+        "/../../harness/fixtures/interface-operation-probe/output/boundary-only.json"
+    )))
+    .unwrap();
+    let id = |n| Id::parse_str(&format!("52060906-0000-4000-8000-{n:012x}")).unwrap();
+    let (owner, call, exchange, allocation) = (id(40), id(43), id(34), id(30));
+    let (interface, item) = (
+        p.relations[&allocation].source(),
+        p.relations[&allocation].target(),
+    );
+    for (id, name) in [(call, "x"), (interface, "I"), (item, "O")] {
+        p.elements.get_mut(&id).unwrap().name = name.into();
+    }
+    p.relations.get_mut(&exchange).unwrap().name = "x".into();
+    p.relations.get_mut(&allocation).unwrap().name = "A".into();
+    if let Some(SharedBody::Occurrence {
+        body: OccurrenceBody::Exchange { operation, .. },
+        ..
+    }) = p.elements.get_mut(&call).unwrap().shared_mut()
+    {
+        *operation = Some(OperationUse {
+            allocation: Some(allocation),
+        });
+    }
+    assert!(matches!(
+        operations::resolve(&p, call),
+        Ok(operations::OperationResolution::Selected(_))
+    ));
+    let state = State::default();
+    let before = p.clone();
+    assert_eq!(
+        targets(&state, &p, owner, interface),
+        BTreeSet::from([call])
+    );
+    assert_eq!(targets(&state, &p, owner, item), BTreeSet::from([call]));
+    assert!(targets(&state, &p, owner, allocation).is_empty());
+    assert_eq!(p, before);
+    p.elements.get_mut(&call).unwrap().name = "This occurrence has a deliberately long name".into();
+    assert!(targets(&state, &p, owner, interface).is_empty());
+    assert!(targets(&state, &p, owner, item).is_empty());
+}

crates/oa-desktop/src/behavior/state_canvas.rs

@@ -415,6 +415,171 @@ fn state_action_label(project: &Project, relation: &Relation) -> String {
     format!("{phase} / {}", project.named(target))
 }
 
+/// Match a typed label field by its structural offset, never by a display-name
+/// substring (names may duplicate or also occur in free-form guards).
+fn retained_label_field(full: &str, painted: &str, start: usize) -> bool {
+    start
+        < full
+            .chars()
+            .zip(painted.chars())
+            .take_while(|(a, b)| a == b)
+            .map(|(c, _)| c.len_utf8())
+            .sum::<usize>()
+}
+
+fn transition_label_role(
+    project: &Project,
+    relation: &Relation,
+    subject: Id,
+    width: f32,
+) -> Option<&'static str> {
+    let full = routing::state_transition_summary(project, relation);
+    transition_label_role_in_text(project, relation, subject, &short(&full, width, 10.))
+}
+
+fn transition_label_role_in_text(
+    project: &Project,
+    relation: &Relation,
+    subject: Id,
+    painted: &str,
+) -> Option<&'static str> {
+    let RelationBody::StateTransition {
+        transition_kind,
+        triggers,
+        effects,
+        effect,
+        ..
+    } = &relation.body
+    else {
+        return None;
+    };
+    if project.named(subject).trim().is_empty() {
+        return None;
+    }
+    let full = routing::state_transition_summary(project, relation);
+    let mut offset = format!("{transition_kind:?} · ").len();
+    for id in triggers {
+        if *id == subject && retained_label_field(&full, painted, offset) {
+            return Some("transition trigger");
+        }
+        offset += project.named(*id).len() + " OR ".len();
+    }
+    if !effects.is_empty() {
+        // The canonical routing summary appends typed effects before optional
+        // authored effect prose. Derive its offset from that exact suffix.
+        let mut suffix = format!(
+            " / {}",
+            effects
+                .iter()
+                .map(|id| project.named(*id))
+                .collect::<Vec<_>>()
+                .join(", ")
+        );
+        if !effect.is_empty() {
+            suffix.push_str(&format!(" / {effect}"));
+        }
+        if let Some(prefix) = full.strip_suffix(&suffix) {
+            offset = prefix.len() + " / ".len();
+            for id in effects {
+                if *id == subject && retained_label_field(&full, painted, offset) {
+                    return Some("transition effect");
+                }
+                offset += project.named(*id).len() + ", ".len();
+            }
+        }
+    }
+    None
+}
+
+/// Actual state compartments and painted transition-reference labels. Generic
+/// projected node/edge identities are handled by the shared saved-view query.
+pub(crate) fn diagram_usages(
+    project: &Project,
+    diagram: &Diagram,
+    view: &ProjectedView,
+    subject: Id,
+) -> Vec<crate::diagram_usage::Usage> {
+    use crate::diagram_usage::{Surface, Target, Usage};
+    if diagram.projection.state_machine().is_none() {
+        return vec![];
+    }
+    let mut result = Vec::new();
+    for node in &view.nodes {
+        for (relation, bounds) in state_action_rows(project, node) {
+            let label = state_action_label(project, relation);
+            let painted = short(&label, bounds.width - 12., 11.);
+            let role = if relation.id == subject {
+                Some("state action")
+            } else if relation.target() == subject
+                && retained_label_field(
+                    &label,
+                    &painted,
+                    label.len() - project.named(subject).len(),
+                )
+            {
+                Some("state action work")
+            } else {
+                None
+            };
+            if let Some(role) = role {
+                result.push(Usage {
+                    subject,
+                    surface: Surface::Saved(diagram.id),
+                    target: Target::StateRow {
+                        placement: node.id,
+                        relation: relation.id,
+                    },
+                    role: role.into(),
+                    bounds,
+                });
+            }
+        }
+        for (relation, bounds) in internal_rows(project, node) {
+            let role = if relation.id == subject {
+                Some("internal transition")
+            } else {
+                transition_label_role(project, relation, subject, bounds.width - 12.)
+            };
+            if let Some(role) = role {
+                result.push(Usage {
+                    subject,
+                    surface: Surface::Saved(diagram.id),
+                    target: Target::StateRow {
+                        placement: node.id,
+                        relation: relation.id,
+                    },
+                    role: role.into(),
+                    bounds,
+                });
+            }
+        }
+    }
+    for edge in routing::route_diagram(project, diagram, view)
+        .edges
+        .values()
+    {
+        let Some(relation) = project.relations.get(&edge.id) else {
+            continue;
+        };
+        if edge.id == subject || edge.label.text.is_empty() {
+            continue;
+        }
+        // Routing already shortens external summaries before the canvas applies
+        // its width limit. Compare against precisely that doubly shortened text.
+        let painted = short(&edge.label.text, edge.label.bounds.size.width - 10., 10.);
+        if let Some(role) = transition_label_role_in_text(project, relation, subject, &painted) {
+            result.push(Usage {
+                subject,
+                surface: Surface::Saved(diagram.id),
+                target: Target::Edge(edge.id),
+                role: role.into(),
+                bounds: crate::diagram_usage::edge_focus_bounds(edge),
+            });
+        }
+    }
+    result
+}
+
 impl StateCanvas<'_> {
     fn scale(&self) -> f32 {
         if self.zoom.is_finite() {
@@ -1575,6 +1740,189 @@ mod tests {
         }
     }
 
+    #[test]
+    fn diagram_usage_state_rows_and_label_references_follow_actual_projection() {
+        use crate::diagram_usage::Target;
+        let mut f = fixture();
+        let work = f
+            .project
+            .add_element(Kind::Function, Layer::Sa, "Act", None)
+            .unwrap();
+        let event = f
+            .project
+            .add_element(Kind::Event, Layer::Sa, "E", None)
+            .unwrap();
+        let unused = f
+            .project
+            .add_element(Kind::Event, Layer::Sa, "E", None)
+            .unwrap();
+        let action = f
+            .project
+            .relate(RelationKind::StateAction, "Entry", f.a, work);
+        let internal = f
+            .project
+            .relate(RelationKind::StateTransition, "Internal", f.a, f.a);
+        let external = f
+            .project
+            .relate(RelationKind::StateTransition, "External", f.a, f.b);
+        for (id, kind) in [
+            (internal, TransitionKind::Internal),
+            (external, TransitionKind::External),
+        ] {
+            if let RelationBody::StateTransition {
+                transition_kind,
+                triggers,
+                effects,
+                ..
+            } = &mut f.project.relations.get_mut(&id).unwrap().body
+            {
+                *transition_kind = kind;
+                *triggers = vec![event];
+                *effects = vec![work];
+            }
+        }
+        let before = f.project.clone();
+        let diagram = &f.project.diagrams[&f.diagram];
+        let view = projection::project_diagram(&f.project, diagram);
+        let placement = view.nodes.iter().find(|n| n.element == f.a).unwrap().id;
+        let action_target = Target::StateRow {
+            placement,
+            relation: action,
+        };
+        let internal_target = Target::StateRow {
+            placement,
+            relation: internal,
+        };
+        assert_eq!(
+            diagram_usages(&f.project, diagram, &view, action)[0].target,
+            action_target
+        );
+        assert_eq!(
+            diagram_usages(&f.project, diagram, &view, internal)[0].target,
+            internal_target
+        );
+        let events = diagram_usages(&f.project, diagram, &view, event);
+        assert_eq!(events.len(), 2);
+        assert!(events.iter().any(|u| u.target == internal_target));
+        assert!(events.iter().any(|u| u.target == Target::Edge(external)));
+        assert!(diagram_usages(&f.project, diagram, &view, unused).is_empty());
+        // External edge identity belongs to the shared saved-view adapter.
+        assert!(diagram_usages(&f.project, diagram, &view, external).is_empty());
+        let work_usages = diagram_usages(&f.project, diagram, &view, work);
+        assert!(work_usages.iter().any(|u| u.target == action_target));
+        assert!(work_usages.iter().any(|u| u.target == internal_target));
+        let row = work_usages
+            .iter()
+            .find(|u| u.target == action_target)
+            .unwrap();
+        let canvas = canvas(&f, Tool::Select, 1.);
+        let scene = canvas.scene(&State::default()).unwrap();
+        assert_eq!(
+            canvas.hit(&scene, row.bounds.center()),
+            Some(Hit::StateAction(action))
+        );
+        assert_eq!(f.project, before);
+        f.project
+            .diagrams
+            .get_mut(&f.diagram)
+            .unwrap()
+            .nodes
+            .get_mut(&placement)
+            .unwrap()
+            .collapsed = true;
+        let diagram = &f.project.diagrams[&f.diagram];
+        let folded = projection::project_diagram(&f.project, diagram);
+        assert!(diagram_usages(&f.project, diagram, &folded, action).is_empty());
+        assert!(diagram_usages(&f.project, diagram, &folded, internal).is_empty());
+    }
+
+    #[test]
+    fn diagram_usage_transition_labels_do_not_match_prose_or_fields_beyond_cutoff() {
+        let mut f = fixture();
+        let early = f
+            .project
+            .add_element(Kind::Event, Layer::Sa, "A", None)
+            .unwrap();
+        let late = f
+            .project
+            .add_element(Kind::Event, Layer::Sa, "B", None)
+            .unwrap();
+        let relation = f
+            .project
+            .relate(RelationKind::StateTransition, "Transition", f.a, f.b);
+        if let RelationBody::StateTransition {
+            triggers, guard, ..
+        } = &mut f.project.relations.get_mut(&relation).unwrap().body
+        {
+            *triggers = vec![early, late];
+            *guard = "B".into();
+        }
+        let relation = &f.project.relations[&relation];
+        assert_eq!(
+            transition_label_role(&f.project, relation, early, 84.),
+            Some("transition trigger")
+        );
+        assert_eq!(transition_label_role(&f.project, relation, late, 84.), None);
+        assert_eq!(
+            transition_label_role(&f.project, relation, late, 800.),
+            Some("transition trigger")
+        );
+        assert!(!retained_label_field("1234A678", "1234…", 4));
+    }
+
+    #[test]
+    fn diagram_usage_external_labels_obey_routing_cutoff_while_internal_rows_retain_full_summary() {
+        use crate::diagram_usage::Target;
+        let mut f = fixture();
+        let first = f
+            .project
+            .add_element(Kind::Event, Layer::Sa, &"A".repeat(35), None)
+            .unwrap();
+        let second = f
+            .project
+            .add_element(Kind::Event, Layer::Sa, "Second", None)
+            .unwrap();
+        let external = f
+            .project
+            .relate(RelationKind::StateTransition, "External", f.a, f.b);
+        let internal = f
+            .project
+            .relate(RelationKind::StateTransition, "Internal", f.a, f.a);
+        for (id, kind) in [
+            (external, TransitionKind::External),
+            (internal, TransitionKind::Internal),
+        ] {
+            if let RelationBody::StateTransition {
+                transition_kind,
+                triggers,
+                ..
+            } = &mut f.project.relations.get_mut(&id).unwrap().body
+            {
+                *transition_kind = kind;
+                *triggers = vec![first, second];
+            }
+        }
+        let diagram = &f.project.diagrams[&f.diagram];
+        let view = projection::project_diagram(&f.project, diagram);
+        let routed = routing::route_diagram(&f.project, diagram, &view);
+        let edge = &routed.edges[&external];
+        let painted = short(&edge.label.text, edge.label.bounds.size.width - 10., 10.);
+        // Independent painted-text oracle: 11 prefix characters + 35 As, then
+        // only the space before OR survives the routing limit.
+        assert_eq!(edge.label.text, format!("External · {} …", "A".repeat(35)));
+        assert!(!painted.contains("Second"));
+        let usages = diagram_usages(&f.project, diagram, &view, second);
+        assert!(!usages.iter().any(|u| u.target == Target::Edge(external)));
+        assert!(usages.iter().any(
+            |u| matches!(u.target, Target::StateRow { relation, .. } if relation == internal)
+        ));
+        assert!(
+            diagram_usages(&f.project, diagram, &view, first)
+                .iter()
+                .any(|u| u.target == Target::Edge(external))
+        );
+    }
+
     fn canvas(f: &Fixture, tool: Tool, zoom: f32) -> StateCanvas<'_> {
         StateCanvas {
             project: &f.project,

crates/oa-desktop/src/behavior/topology.rs

@@ -5,6 +5,7 @@ use iced::widget::{Column, text_input};
 use std::collections::BTreeSet;
 pub(crate) mod contextual;
 mod direct;
+mod usages;
 mod view;
 use direct::Input;
 pub(crate) use direct::{
@@ -986,6 +987,7 @@ struct Graph<'a> {
     ordered: bool,
     size: Size,
     selected: Id,
+    selected_preview: Option<OccurrenceEndpoint>,
     scale: f32,
 }
 impl<'a> Graph<'a> {
@@ -1319,6 +1321,7 @@ impl<'a> Graph<'a> {
             ordered: !order.is_empty(),
             size,
             selected,
+            selected_preview: None,
             scale: 1.,
         }
     }
@@ -1577,10 +1580,25 @@ impl canvas::Program<Message> for Graph<'_> {
                             }
                             for (id, name) in &n.preview {
                                 let r = mini[id];
-                                f.fill_rectangle(r.position(), r.size(), Color::WHITE);
+                                let selected = self.selected_preview.as_ref() == Some(id);
+                                f.fill_rectangle(
+                                    r.position(),
+                                    r.size(),
+                                    if selected {
+                                        Color::from_rgb8(224, 247, 242)
+                                    } else {
+                                        Color::WHITE
+                                    },
+                                );
                                 f.stroke(
                                     &Path::rectangle(r.position(), r.size()),
-                                    Stroke::default().with_color(style::LINE),
+                                    Stroke::default()
+                                        .with_color(if selected {
+                                            style::TEAL
+                                        } else {
+                                            style::LINE
+                                        })
+                                        .with_width(if selected { 2.5 } else { 1. }),
                                 );
                                 draw_text(
                                     &mut f,

crates/oa-desktop/src/behavior/topology/usages.rs

@@ -0,0 +1,244 @@
+//! Read-only usages of the actual process graph, including bounded reuse tiles.
+use super::*;
+use crate::diagram_usage::{Surface, Target, Usage};
+
+/// The only presentation inputs needed by a background usage query. Drafts,
+/// focus, camera, history and widget state never cross the worker boundary.
+#[derive(Clone)]
+pub(crate) struct UsageSnapshot {
+    identity: Option<(Id, Id)>,
+    expanded: BTreeSet<Id>,
+    contextual_expanded: BTreeSet<OccurrenceEndpoint>,
+}
+
+impl UsageSnapshot {
+    pub(crate) fn into_query_state(self) -> State {
+        State {
+            identity: self.identity,
+            expanded: self.expanded,
+            contextual_expanded: self.contextual_expanded,
+            ..State::default()
+        }
+    }
+}
+
+impl State {
+    pub(crate) fn usage_snapshot(&self) -> UsageSnapshot {
+        UsageSnapshot {
+            identity: self.identity,
+            expanded: self.expanded.clone(),
+            contextual_expanded: self.contextual_expanded.clone(),
+        }
+    }
+}
+
+fn owner_exists(p: &Project, owner: Id) -> bool {
+    p.elements
+        .get(&owner)
+        .is_some_and(|e| matches!(e.kind(), Kind::Process | Kind::FunctionalChain))
+}
+
+fn occurrence_role(p: &Project, occurrence: Id, subject: Id) -> Option<&'static str> {
+    let e = p.elements.get(&occurrence)?;
+    if occurrence == subject {
+        return Some("contribution");
+    }
+    match e.shared()? {
+        SharedBody::Occurrence {
+            body: OccurrenceBody::Action {
+                action: Some(id), ..
+            },
+            ..
+        } if *id == subject => Some("action occurrence"),
+        SharedBody::Occurrence {
+            body: OccurrenceBody::Exchange {
+                exchange: Some(id), ..
+            },
+            ..
+        } if *id == subject => Some("exchange occurrence"),
+        SharedBody::Occurrence {
+            body: OccurrenceBody::SequenceReference { sequence: Some(id) },
+            ..
+        } if *id == subject => Some("reused process / chain"),
+        _ => None,
+    }
+}
+
+impl Graph<'_> {
+    fn usage_bounds(&self, target: &Target) -> Option<Rectangle> {
+        match target {
+            Target::Whole => Some(Rectangle::new(Point::ORIGIN, self.size)),
+            Target::ProcessOccurrence(endpoint) => {
+                let root = endpoint
+                    .references
+                    .first()
+                    .copied()
+                    .unwrap_or(endpoint.occurrence);
+                let node = self.nodes.iter().find(|node| node.id == root)?;
+                if endpoint.references.is_empty() {
+                    Some(node.rect)
+                } else {
+                    // endpoint_rect intentionally has a proxy fallback for other callers;
+                    // a usage promises an actual tile and must never take that fallback.
+                    node.preview
+                        .iter()
+                        .any(|(shown, _)| shown == endpoint)
+                        .then(|| node.endpoint_rect(endpoint))
+                }
+            }
+            Target::ProcessLink(id) => {
+                let edge = self.edges.iter().find(|edge| edge.id == *id)?;
+                if !edge.guard.is_empty() {
+                    Some(edge.label)
+                } else {
+                    let segment = edge
+                        .points
+                        .windows(2)
+                        .nth(edge.points.len().saturating_sub(1) / 2)?;
+                    let center = Point::new(
+                        (segment[0].x + segment[1].x) / 2.,
+                        (segment[0].y + segment[1].y) / 2.,
+                    );
+                    Some(Rectangle::new(
+                        center - iced::Vector::new(16., 16.),
+                        Size::new(32., 32.),
+                    ))
+                }
+            }
+            _ => None,
+        }
+    }
+}
+
+impl State {
+    /// Inactive owners use the same default preview policy as entering their canvas.
+    fn usage_graph<'a>(&self, p: &'a Project, owner: Id) -> Graph<'a> {
+        if self.identity.is_some_and(|(_, current)| current == owner) {
+            Graph::expanded_qualified(p, owner, owner, &self.expanded, &self.contextual_expanded)
+        } else {
+            Graph::new(p, owner, owner)
+        }
+    }
+
+    pub(crate) fn diagram_usages(&self, p: &Project, owner: Id, subject: Id) -> Vec<Usage> {
+        if !owner_exists(p, owner)
+            || !(p.elements.contains_key(&subject) || p.relations.contains_key(&subject))
+        {
+            return vec![];
+        }
+        let graph = self.usage_graph(p, owner);
+        let mut usages = vec![];
+        let mut add = |target: Target, role: &str| {
+            if let Some(bounds) = graph.usage_bounds(&target) {
+                usages.push(Usage {
+                    subject,
+                    surface: Surface::Process(owner),
+                    target,
+                    role: role.into(),
+                    bounds,
+                });
+            }
+        };
+        if subject == owner {
+            add(Target::Whole, "process / chain canvas");
+        }
+        for node in &graph.nodes {
+            if let Some(role) = occurrence_role(p, node.id, subject) {
+                add(
+                    Target::ProcessOccurrence(OccurrenceEndpoint {
+                        references: vec![],
+                        occurrence: node.id,
+                    }),
+                    role,
+                );
+            }
+            for (endpoint, _) in &node.preview {
+                if let Some(role) = occurrence_role(p, endpoint.occurrence, subject) {
+                    add(
+                        Target::ProcessOccurrence(endpoint.clone()),
+                        &format!("reused {role}"),
+                    );
+                }
+            }
+        }
+        for edge in &graph.edges {
+            let role = if edge.id == subject {
+                Some("process link")
+            } else {
+                match p.relations.get(&edge.id).map(|r| &r.body) {
+                    Some(RelationBody::ContextualLink {
+                        purpose: ContextualLinkPurpose::Exchange { exchange },
+                        ..
+                    }) if *exchange == subject => Some("assembly exchange"),
+                    Some(RelationBody::ContextualLink {
+                        purpose: ContextualLinkPurpose::CommonWork { work },
+                        ..
+                    }) if *work == subject => Some("common work"),
+                    _ => None,
+                }
+            };
+            if let Some(role) = role {
+                add(Target::ProcessLink(edge.id), role);
+            }
+        }
+        usages
+    }
+
+    /// Returns success, not whether the camera changed. App must separately guard
+    /// its other drafts and revalidate the queried subject's current usage.
+    pub(crate) fn reveal_usage(
+        &mut self,
+        p: &Project,
+        document: Id,
+        owner: Id,
+        target: &Target,
+    ) -> bool {
+        if !owner_exists(p, owner) || self.draft.is_some() {
+            return false;
+        }
+        let same = self.identity == Some((document, owner));
+        let graph = if same {
+            self.usage_graph(p, owner)
+        } else {
+            Graph::new(p, owner, owner)
+        };
+        let Some(bounds) = graph.usage_bounds(target) else {
+            return false;
+        };
+        let address = if let Target::ProcessOccurrence(endpoint) = target {
+            let Ok(resolved) =
+                oa_core::topology_context::TopologyIndex::new(p).resolve(owner, endpoint)
+            else {
+                return false;
+            };
+            (!endpoint.references.is_empty()).then_some(resolved.address)
+        } else {
+            None
+        };
+        let viewport = self.viewport.unwrap_or(Size::new(500., 300.));
+        self.enter(document, owner);
+        if !same {
+            self.contextual_expanded.clear();
+        }
+        self.selected_context = address;
+        self.tool = CanvasTool::Select;
+        self.viewport = Some(viewport);
+        let fit = ((viewport.width - 48.).max(1.) / bounds.width.max(1.))
+            .min((viewport.height - 48.).max(1.) / bounds.height.max(1.));
+        let scale = if matches!(target, Target::Whole) {
+            fit.clamp(0.0001, 1.)
+        } else {
+            fit.clamp(0.6, 1.25)
+        };
+        self.zoom = Some(scale);
+        self.fit = false;
+        self.pan = iced::Vector::new(
+            viewport.width / 2. - bounds.center_x() * scale,
+            viewport.height / 2. - bounds.center_y() * scale,
+        );
+        true
+    }
+}
+
+#[cfg(test)]
+mod tests;

crates/oa-desktop/src/behavior/topology/usages/tests.rs

@@ -0,0 +1,276 @@
+use super::*;
+
+fn add(p: &mut Project, owner: Id, name: &str, body: OccurrenceBody) -> Id {
+    let e = occurrence(p, owner, name, body);
+    let id = e.id;
+    *p = execute_batch(p, &[Command::CreateElement(e)]).unwrap();
+    id
+}
+
+fn reused_fixture() -> (Project, Id, Id, Id, [Id; 2], Vec<Id>) {
+    let f = super::super::direct_tests::fixture(Layer::Oa);
+    let mut p = f.p;
+    let sequence = p
+        .make_element(Kind::Process, Layer::Oa, "Reviewed checks", None)
+        .unwrap();
+    let sequence_id = sequence.id;
+    p = execute_batch(&p, &[Command::CreateElement(sequence)]).unwrap();
+    let mut leaves = vec![];
+    for name in [
+        "Check one",
+        "Check two",
+        "Check three",
+        "Check four",
+        "Check five",
+    ] {
+        leaves.push(add(
+            &mut p,
+            sequence_id,
+            name,
+            OccurrenceBody::Action {
+                action: Some(f.work[0]),
+                lifeline: None,
+            },
+        ));
+    }
+    let first = add(
+        &mut p,
+        f.owner,
+        "First invocation",
+        OccurrenceBody::SequenceReference {
+            sequence: Some(sequence_id),
+        },
+    );
+    let second = add(
+        &mut p,
+        f.owner,
+        "Second invocation",
+        OccurrenceBody::SequenceReference {
+            sequence: Some(sequence_id),
+        },
+    );
+    (p, f.owner, sequence_id, f.work[0], [first, second], leaves)
+}
+
+#[test]
+fn process_usages_exclude_endpoint_coincidence_and_keep_actual_occurrences_and_links() {
+    for layer in [Layer::Oa, Layer::Sa] {
+        let f = super::super::direct_tests::fixture(layer);
+        let mut p = f.p;
+        let state = State::default();
+        // Both exchange endpoints have Action contributions, but there is no
+        // Exchange occurrence and no exchange arrow in this process.
+        assert!(state.diagram_usages(&p, f.owner, f.exchange).is_empty());
+        let direct = state.diagram_usages(&p, f.owner, f.work[0]);
+        assert_eq!(direct.len(), 1);
+        assert_eq!(
+            direct[0].target,
+            Target::ProcessOccurrence(OccurrenceEndpoint {
+                references: vec![],
+                occurrence: f.nodes[0]
+            })
+        );
+        let link = state.diagram_usages(&p, f.owner, f.link);
+        assert_eq!(link.len(), 1);
+        assert_eq!(link[0].target, Target::ProcessLink(f.link));
+        let first = add(
+            &mut p,
+            f.owner,
+            "First exchange",
+            OccurrenceBody::Exchange {
+                exchange: Some(f.exchange),
+                sender: None,
+                receiver: None,
+                message_kind: MessageKind::Asynchronous,
+                reply_to: None,
+                values: vec![],
+                operation: None,
+            },
+        );
+        let second = add(
+            &mut p,
+            f.owner,
+            "Second exchange",
+            OccurrenceBody::Exchange {
+                exchange: Some(f.exchange),
+                sender: None,
+                receiver: None,
+                message_kind: MessageKind::Asynchronous,
+                reply_to: None,
+                values: vec![],
+                operation: None,
+            },
+        );
+        let usages = state.diagram_usages(&p, f.owner, f.exchange);
+        assert_eq!(usages.len(), 2);
+        assert_eq!(
+            usages
+                .iter()
+                .map(|usage| usage.target.clone())
+                .collect::<Vec<_>>(),
+            vec![
+                Target::ProcessOccurrence(OccurrenceEndpoint {
+                    references: vec![],
+                    occurrence: first
+                }),
+                Target::ProcessOccurrence(OccurrenceEndpoint {
+                    references: vec![],
+                    occurrence: second
+                }),
+            ]
+        );
+    }
+}
+
+#[test]
+fn process_usages_keep_caller_paths_and_exclude_unshown_fifth_preview() {
+    let (p, owner, sequence, work, calls, leaves) = reused_fixture();
+    let before = p.clone();
+    let mut state = State::default();
+    let leaf = state.diagram_usages(&p, owner, leaves[0]);
+    assert_eq!(leaf.len(), 2);
+    for (usage, call) in leaf.iter().zip(calls) {
+        assert_eq!(
+            usage.target,
+            Target::ProcessOccurrence(OccurrenceEndpoint {
+                references: vec![call],
+                occurrence: leaves[0]
+            })
+        );
+    }
+    assert_ne!(leaf[0].bounds, leaf[1].bounds);
+    assert!(state.diagram_usages(&p, owner, leaves[4]).is_empty());
+    assert_eq!(state.diagram_usages(&p, owner, sequence).len(), 2);
+    // One local action and four tiles in each of two caller boxes.
+    assert_eq!(state.diagram_usages(&p, owner, work).len(), 9);
+    state.enter(Id::new_v4(), owner);
+    assert!(state.expand(&p, owner, calls[0]));
+    let fifth = state.diagram_usages(&p, owner, leaves[4]);
+    assert_eq!(fifth.len(), 1);
+    assert_eq!(
+        fifth[0].target,
+        Target::ProcessOccurrence(OccurrenceEndpoint {
+            references: vec![calls[0]],
+            occurrence: leaves[4]
+        })
+    );
+    // Another active owner must not leak its expansion to this queried canvas.
+    state.enter(Id::new_v4(), sequence);
+    assert!(state.diagram_usages(&p, owner, leaves[4]).is_empty());
+    assert_eq!(p, before);
+}
+
+#[test]
+fn process_usage_reveal_validates_before_state_changes_and_centers_the_exact_tile() {
+    let (p, owner, _, _, calls, leaves) = reused_fixture();
+    let before = p.clone();
+    let document = Id::new_v4();
+    let mut state = State::default();
+    state.enter(document, owner);
+    state.viewport(Size::new(880., 460.));
+    state.pan = iced::Vector::new(-3000., -900.);
+    let hidden = Target::ProcessOccurrence(OccurrenceEndpoint {
+        references: vec![calls[0]],
+        occurrence: leaves[4],
+    });
+    let prior = (
+        state.identity,
+        state.pan,
+        state.zoom,
+        state.fit,
+        state.selected_context.clone(),
+    );
+    assert!(!state.reveal_usage(&p, document, owner, &hidden));
+    assert_eq!(
+        (
+            state.identity,
+            state.pan,
+            state.zoom,
+            state.fit,
+            state.selected_context.clone()
+        ),
+        prior
+    );
+    assert!(!state.reveal_usage(&p, document, Id::new_v4(), &Target::Whole));
+    assert_eq!(
+        (
+            state.identity,
+            state.pan,
+            state.zoom,
+            state.fit,
+            state.selected_context.clone()
+        ),
+        prior
+    );
+    let endpoint = OccurrenceEndpoint {
+        references: vec![calls[1]],
+        occurrence: leaves[0],
+    };
+    let target = Target::ProcessOccurrence(endpoint.clone());
+    assert!(state.reveal_usage(&p, document, owner, &target));
+    assert_eq!(state.selected_context.as_ref().unwrap().endpoint, endpoint);
+    let bounds = state
+        .diagram_usages(&p, owner, leaves[0])
+        .into_iter()
+        .find(|usage| usage.target == target)
+        .unwrap()
+        .bounds;
+    let scale = state.zoom.unwrap();
+    assert!(scale >= 0.6);
+    assert!((bounds.center_x() * scale + state.pan.x - 440.).abs() < 0.01);
+    assert!((bounds.center_y() * scale + state.pan.y - 230.).abs() < 0.01);
+    assert!(state.reveal_usage(&p, document, owner, &Target::Whole));
+    assert!(state.selected_context.is_none());
+    state
+        .update(&p, Event::Start(owner, Tool::Work, None))
+        .unwrap();
+    let draft = state.recovery_snapshot().unwrap();
+    let camera = (state.pan, state.zoom, state.fit);
+    assert!(!state.reveal_usage(&p, document, owner, &target));
+    assert_eq!(state.recovery_snapshot().unwrap(), draft);
+    assert_eq!((state.pan, state.zoom, state.fit), camera);
+    assert_eq!(p, before);
+}
+
+#[test]
+fn process_contextual_purpose_is_a_visible_reference_but_preview_arrows_are_not_links() {
+    let (mut p, owner, sequence, work, calls, leaves) = reused_fixture();
+    let source = OccurrenceEndpoint {
+        references: vec![calls[0]],
+        occurrence: leaves[0],
+    };
+    let target = OccurrenceEndpoint {
+        references: vec![calls[1]],
+        occurrence: leaves[0],
+    };
+    let relation = Relation {
+        id: Id::new_v4(),
+        alias: "same_check".into(),
+        name: "One common check".into(),
+        description: String::new(),
+        body: RelationBody::ContextualLink {
+            owner,
+            source,
+            target,
+            purpose: ContextualLinkPurpose::CommonWork { work },
+        },
+    };
+    let contextual = relation.id;
+    p = execute_batch(&p, &[Command::CreateRelation(relation)]).unwrap();
+    let Command::CreateRelation(relation) = link(&p, leaves[0], leaves[1], "next") else {
+        unreachable!()
+    };
+    let local_link = relation.id;
+    p = execute_batch(&p, &[Command::CreateRelation(relation)]).unwrap();
+    let state = State::default();
+    assert!(
+        state
+            .diagram_usages(&p, owner, work)
+            .iter()
+            .any(|usage| usage.target == Target::ProcessLink(contextual)
+                && usage.role == "common work")
+    );
+    assert_eq!(state.diagram_usages(&p, owner, contextual).len(), 1);
+    assert!(state.diagram_usages(&p, owner, local_link).is_empty());
+    assert_eq!(state.diagram_usages(&p, sequence, local_link).len(), 1);
+}

crates/oa-desktop/src/behavior/topology/view.rs

@@ -183,6 +183,18 @@ pub(super) fn view<'a>(app: &'a App, owner: Id, out: Column<'a, Message>) -> Ele
         &state.expanded,
         &state.contextual_expanded,
     );
+    graph.selected_preview = state
+        .qualified_selection(p, owner)
+        .filter(|address| {
+            address
+                .endpoint
+                .references
+                .first()
+                .copied()
+                .unwrap_or(address.endpoint.occurrence)
+                == app.selected
+        })
+        .map(|address| address.endpoint.clone());
     graph.scale = state.scale(graph.size, (app.window_size.width - 600.).max(200.));
     graph.camera_pan = state.pan;
     graph.pending_insertion = state

crates/oa-desktop/src/diagram_usage.rs

@@ -0,0 +1,394 @@
+//! Read-only identities for objects actually represented by a diagram renderer.
+use iced::Rectangle;
+use oa_core::{Id, OccurrenceEndpoint, Project, projection, routing, view_options::ViewIndex};
+pub(crate) mod view;
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub(crate) struct Context {
+    pub document: Id,
+    pub revision: u64,
+    pub subject: Id,
+}
+
+#[derive(Debug, Clone)]
+pub(crate) enum Event {
+    Open(Context),
+    Close(Id),
+    Search(Id, String),
+    Page(Id, usize),
+    Destination(Id, Option<Surface>),
+    Choose(Id, Usage),
+    Move(Id, i8),
+    Activate(Id),
+}
+
+/// One completed immutable accepted-model lookup. The token owns one worker slot.
+#[derive(Debug, Clone)]
+pub(crate) struct Completion {
+    pub token: Id,
+    pub context: Context,
+    pub result: Result<Vec<Usage>, String>,
+}
+
+pub(crate) struct Panel {
+    pub token: Id,
+    pub context: Context,
+    pub usages: Vec<Usage>,
+    pub loading: bool,
+    pub search: String,
+    pub page: usize,
+    pub cursor: usize,
+    pub destination: Option<Surface>,
+    pub notice: Option<String>,
+}
+
+impl Panel {
+    pub fn new(context: Context, usages: Vec<Usage>) -> Self {
+        Self {
+            token: Id::new_v4(),
+            context,
+            usages,
+            loading: false,
+            search: String::new(),
+            page: 0,
+            cursor: 0,
+            destination: None,
+            notice: None,
+        }
+    }
+
+    pub fn matches<'a>(&'a self, p: &Project) -> Vec<&'a Usage> {
+        let query = self.search.to_lowercase();
+        if query.is_empty() {
+            return self.usages.iter().collect();
+        }
+        self.usages
+            .iter()
+            .filter(|usage| {
+                let surface = usage.surface;
+                let searchable = format!(
+                    "{} {} {} {} {}",
+                    surface.category(p),
+                    p.named(surface.id()),
+                    alias(p, surface.id()),
+                    target_name(p, usage),
+                    usage.role
+                );
+                searchable.to_lowercase().contains(&query)
+            })
+            .collect()
+    }
+
+    pub fn choices(&self, p: &Project) -> Vec<Event> {
+        if self.loading {
+            return Vec::new();
+        }
+        let matches = self.matches(p);
+        if let Some(surface) = self.destination {
+            matches
+                .into_iter()
+                .filter(|u| u.surface == surface)
+                .map(|u| Event::Choose(self.token, u.clone()))
+                .collect()
+        } else {
+            let mut seen = std::collections::BTreeSet::new();
+            matches
+                .into_iter()
+                .filter(|u| seen.insert(u.surface))
+                .map(|u| Event::Destination(self.token, Some(u.surface)))
+                .collect()
+        }
+    }
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
+pub(crate) enum Surface {
+    Saved(Id),
+    Process(Id),
+    Scenario(Id),
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub(crate) enum Target {
+    Whole,
+    Placement(Id),
+    Port { port: Id, placement: Id },
+    Edge(Id),
+    StateRow { placement: Id, relation: Id },
+    ProcessOccurrence(OccurrenceEndpoint),
+    ProcessLink(Id),
+    ScenarioObject(Id),
+}
+
+#[derive(Debug, Clone, PartialEq)]
+pub(crate) struct Usage {
+    pub subject: Id,
+    pub surface: Surface,
+    pub target: Target,
+    /// Concise, truthful explanation, e.g. "action occurrence" or "entry action".
+    pub role: String,
+    /// Actual current renderer coordinates. Recompute before activation.
+    pub bounds: Rectangle,
+}
+
+impl Surface {
+    pub fn id(self) -> Id {
+        match self {
+            Self::Saved(id) | Self::Process(id) | Self::Scenario(id) => id,
+        }
+    }
+
+    pub fn category(self, p: &Project) -> &'static str {
+        match self {
+            Self::Saved(id)
+                if p.diagrams
+                    .get(&id)
+                    .is_some_and(|d| d.projection.state_machine().is_some()) =>
+            {
+                "State views"
+            }
+            Self::Saved(_) => "Architecture",
+            Self::Process(_) => "Processes and chains",
+            Self::Scenario(_) => "Scenarios",
+        }
+    }
+}
+
+pub(crate) fn collect(
+    p: &Project,
+    subject: Id,
+    process: &crate::behavior::topology::State,
+    scenario: &crate::behavior::scenario::State,
+) -> Vec<Usage> {
+    let mut usages = saved_usages(p, subject);
+    for element in p.elements.values() {
+        match element.kind() {
+            oa_core::Kind::Process | oa_core::Kind::FunctionalChain => {
+                usages.extend(process.diagram_usages(p, element.id, subject));
+            }
+            oa_core::Kind::Scenario => {
+                usages.extend(scenario.diagram_usages(p, element.id, subject));
+            }
+            _ => {}
+        }
+    }
+    usages.sort_by_cached_key(|u| {
+        (
+            u.surface.category(p),
+            p.named(u.surface.id()).to_lowercase(),
+            u.surface,
+            target_name(p, u).to_lowercase(),
+        )
+    });
+    usages
+        .dedup_by(|a, b| a.subject == b.subject && a.surface == b.surface && a.target == b.target);
+    usages
+}
+
+pub(crate) fn alias(p: &Project, id: Id) -> &str {
+    p.elements
+        .get(&id)
+        .map(|e| e.alias.as_str())
+        .or_else(|| p.relations.get(&id).map(|r| r.alias.as_str()))
+        .or_else(|| p.diagrams.get(&id).map(|d| d.alias.as_str()))
+        .or_else(|| p.traces.get(&id).map(|t| t.alias.as_str()))
+        .or_else(|| {
+            p.diagrams
+                .values()
+                .find_map(|d| d.nodes.get(&id).map(|n| n.alias.as_str()))
+        })
+        .unwrap_or("")
+}
+
+pub(crate) fn target_name(p: &Project, usage: &Usage) -> String {
+    let id = match &usage.target {
+        Target::Whole => usage.surface.id(),
+        Target::Placement(id) => p
+            .diagrams
+            .get(&usage.surface.id())
+            .and_then(|d| d.nodes.get(id))
+            .map_or(*id, |n| n.element),
+        Target::Port { port, .. } => *port,
+        Target::Edge(id)
+        | Target::StateRow { relation: id, .. }
+        | Target::ProcessLink(id)
+        | Target::ScenarioObject(id) => *id,
+        Target::ProcessOccurrence(endpoint) => {
+            return endpoint
+                .references
+                .iter()
+                .copied()
+                .chain([endpoint.occurrence])
+                .map(|id| format!("{} (@{})", p.named(id), alias(p, id)))
+                .collect::<Vec<_>>()
+                .join(" / ");
+        }
+    };
+    format!("{} (@{})", p.named(id), alias(p, id))
+}
+
+/// Saved view membership is the renderer's final projection, including folds,
+/// projection-kind exclusions and explicit view filters. Stored route metadata
+/// and merely having both relation endpoints placed do not imply visibility.
+pub(crate) fn saved_usages(p: &Project, subject: Id) -> Vec<Usage> {
+    saved_usages_for(p, subject, None)
+}
+
+/// Revalidate only the requested saved surface before activation. The optional
+/// filter is applied before projection and routing, never after a whole lookup.
+pub(crate) fn saved_usages_for(p: &Project, subject: Id, only_diagram: Option<Id>) -> Vec<Usage> {
+    if only_diagram.is_some_and(|id| !p.diagrams.contains_key(&id)) {
+        return Vec::new();
+    }
+    let index = ViewIndex::new(p);
+    let mut usages = Vec::new();
+    for diagram in p
+        .diagrams
+        .values()
+        .filter(|diagram| only_diagram.is_none_or(|id| diagram.id == id))
+    {
+        let view = projection::project_diagram_with_index(p, diagram, &index);
+        let surface = Surface::Saved(diagram.id);
+        if subject == diagram.id || diagram.projection.state_machine() == Some(subject) {
+            usages.push(Usage {
+                subject,
+                surface,
+                target: Target::Whole,
+                role: if subject == diagram.id {
+                    "diagram"
+                } else {
+                    "state machine view"
+                }
+                .into(),
+                bounds: routed_bounds(routing::route_diagram(p, diagram, &view).bounds),
+            });
+        }
+        for node in &view.nodes {
+            if subject == node.element || subject == node.id {
+                usages.push(Usage {
+                    subject,
+                    surface,
+                    target: Target::Placement(node.id),
+                    role: "node".into(),
+                    bounds: Rectangle {
+                        x: node.position.x,
+                        y: node.position.y,
+                        // Reveal the labelled header, not the empty interior of
+                        // a large expanded container at the minimum zoom.
+                        width: node.size.width.min(420.),
+                        height: node.size.height.min(64.),
+                    },
+                });
+            }
+        }
+        for port in &view.ports {
+            if subject == port.element {
+                usages.push(Usage {
+                    subject,
+                    surface,
+                    target: Target::Port {
+                        port: port.element,
+                        placement: port.owner,
+                    },
+                    role: "port".into(),
+                    bounds: Rectangle {
+                        x: port.position.x - 12.,
+                        y: port.position.y - 12.,
+                        width: 24.,
+                        height: 24.,
+                    },
+                });
+            }
+        }
+        if view.edges.iter().any(|edge| edge.id == subject)
+            && let Some(edge) = routing::route_diagram(p, diagram, &view)
+                .edges
+                .get(&subject)
+        {
+            usages.push(Usage {
+                subject,
+                surface,
+                target: Target::Edge(subject),
+                role: "relationship".into(),
+                bounds: edge_focus_bounds(edge),
+            });
+        }
+        if diagram.projection.state_machine().is_some() {
+            usages.extend(crate::behavior::state_canvas::diagram_usages(
+                p, diagram, &view, subject,
+            ));
+        }
+    }
+    usages
+}
+
+pub(crate) fn routed_bounds(bounds: routing::RoutingBounds) -> Rectangle {
+    Rectangle {
+        x: bounds.position.x,
+        y: bounds.position.y,
+        width: bounds.size.width,
+        height: bounds.size.height,
+    }
+}
+
+/// Focus a named edge at its label. For an unlabelled line, focus its middle
+/// segment instead of shrinking a long connector to fit the whole diagram.
+pub(crate) fn edge_focus_bounds(edge: &routing::RoutedEdge) -> Rectangle {
+    if !edge.label.text.is_empty() {
+        return routed_bounds(edge.label.bounds);
+    }
+    let point = edge
+        .points
+        .get(edge.points.len() / 2)
+        .copied()
+        .unwrap_or(edge.label.center);
+    Rectangle {
+        x: point.x - 40.,
+        y: point.y - 24.,
+        width: 80.,
+        height: 48.,
+    }
+}
+
+/// Whole-canvas navigation fits its entire extent; an individual target keeps
+/// the readable minimum zoom of `camera` rather than shrinking unrelated space.
+pub(crate) fn camera_for(
+    target: &Target,
+    bounds: Rectangle,
+    viewport: iced::Size,
+) -> (f32, iced::Vector) {
+    if !matches!(target, Target::Whole) {
+        return camera(bounds, viewport);
+    }
+    let available = iced::Size::new(
+        (viewport.width - 64.).max(1.),
+        (viewport.height - 64.).max(1.),
+    );
+    let zoom = (available.width / bounds.width.max(1.))
+        .min(available.height / bounds.height.max(1.))
+        .clamp(0.0001, 1.25);
+    let pan = iced::Vector::new(
+        viewport.width / 2. - bounds.center_x() * zoom,
+        viewport.height / 2. - bounds.center_y() * zoom,
+    );
+    (zoom, pan)
+}
+
+/// Return a readable, centered camera without modifying authored geometry.
+pub(crate) fn camera(bounds: Rectangle, viewport: iced::Size) -> (f32, iced::Vector) {
+    let available = iced::Size::new(
+        (viewport.width - 64.).max(1.),
+        (viewport.height - 64.).max(1.),
+    );
+    let zoom = (available.width / bounds.width.max(1.))
+        .min(available.height / bounds.height.max(1.))
+        .clamp(0.5, 1.25);
+    let pan = iced::Vector::new(
+        viewport.width / 2. - bounds.center_x() * zoom,
+        viewport.height / 2. - bounds.center_y() * zoom,
+    );
+    (zoom, pan)
+}
+
+#[cfg(test)]
+mod tests;

crates/oa-desktop/src/diagram_usage/tests.rs

@@ -0,0 +1,171 @@
+use super::*;
+use oa_core::{Kind, Layer, Position, RelationKind};
+
+#[test]
+fn saved_membership_respects_filters_and_does_not_change_project() {
+    let mut p = Project::empty();
+    let first = p.add(Kind::Activity, "Same name", 20., 20.);
+    let second = p.add(Kind::Activity, "Same name", 340., 20.);
+    let relation = p.relate(RelationKind::Interaction, "Handoff", first, second);
+    let shown = p.ensure_diagram(Layer::Oa);
+    let mut hidden = p.diagrams[&shown].clone();
+    hidden.id = Id::new_v4();
+    hidden.alias = "filtered_copy".into();
+    hidden.nodes = hidden
+        .nodes
+        .into_values()
+        .map(|mut node| {
+            node.id = Id::new_v4();
+            node.alias = format!("filtered_{}", node.alias);
+            (node.id, node)
+        })
+        .collect();
+    hidden.view_options.hidden_edges.push(relation);
+    let hidden_id = hidden.id;
+    p.diagrams.insert(hidden_id, hidden);
+    let before = p.clone();
+
+    let hits = saved_usages(&p, relation);
+    assert_eq!(hits.len(), 1);
+    assert_eq!(hits[0].surface, Surface::Saved(shown));
+    assert_eq!(hits[0].target, Target::Edge(relation));
+    let hits = saved_usages(&p, first);
+    assert_eq!(hits.len(), 2);
+    assert!(hits.iter().all(|hit| match hit.target {
+        Target::Placement(node) => p.diagrams[&hit.surface.id()].nodes[&node].element == first,
+        _ => false,
+    }));
+    assert_eq!(p, before);
+}
+
+#[test]
+fn folded_child_is_not_a_visible_node_and_placement_identity_stays_exact() {
+    let mut p = Project::empty();
+    let parent = p.add(Kind::Activity, "Container", 20., 20.);
+    let child = p
+        .add_element(Kind::Activity, Layer::Oa, "Nested", Some(parent))
+        .unwrap();
+    let diagram = p.ensure_diagram(Layer::Oa);
+    let child_node = p.place(diagram, child, Position { x: 50., y: 100. });
+    let parent_node = p.diagrams[&diagram]
+        .nodes
+        .values()
+        .find(|n| n.element == parent)
+        .unwrap()
+        .id;
+    let hits = saved_usages(&p, child_node);
+    assert_eq!(hits.len(), 1);
+    assert_eq!(hits[0].target, Target::Placement(child_node));
+    p.diagrams
+        .get_mut(&diagram)
+        .unwrap()
+        .nodes
+        .get_mut(&parent_node)
+        .unwrap()
+        .collapsed = true;
+    let before = p.clone();
+    assert!(saved_usages(&p, child).is_empty());
+    assert!(saved_usages(&p, child_node).is_empty());
+    assert_eq!(saved_usages(&p, parent).len(), 1);
+    assert_eq!(p, before);
+}
+
+#[test]
+fn ports_are_found_at_the_visible_owner_and_unplaced_elements_do_not_match_names() {
+    let mut p = Project::empty();
+    let owner = p.add(Kind::Function, "Compute", 20., 20.);
+    let port = p
+        .add_element(Kind::Port, Layer::Sa, "Input", Some(owner))
+        .unwrap();
+    let unrelated = p
+        .add_element(Kind::Function, Layer::Sa, "Compute", None)
+        .unwrap();
+    let hits = saved_usages(&p, port);
+    assert_eq!(hits.len(), 1);
+    assert!(matches!(hits[0].target, Target::Port { port: found, .. } if found == port));
+    assert!(saved_usages(&p, unrelated).is_empty());
+    assert!(saved_usages(&p, Id::new_v4()).is_empty());
+}
+
+#[test]
+fn reveal_camera_centers_target_without_whole_view_shrink() {
+    let bounds = Rectangle {
+        x: 100_000.,
+        y: -50_000.,
+        width: 224.,
+        height: 94.,
+    };
+    let viewport = iced::Size::new(700., 500.);
+    let (zoom, pan) = camera(bounds, viewport);
+    assert_eq!(zoom, 1.25);
+    assert!((bounds.center_x() * zoom + pan.x - 350.).abs() < 0.01);
+    assert!((bounds.center_y() * zoom + pan.y - 250.).abs() < 0.01);
+}
+
+#[test]
+fn oversized_container_reveal_targets_its_labelled_header() {
+    let mut p = Project::empty();
+    let container = p.add(Kind::Activity, "Large enclosing activity", 40., 70.);
+    let diagram = p.ensure_diagram(Layer::Oa);
+    let node = p
+        .diagrams
+        .get_mut(&diagram)
+        .unwrap()
+        .nodes
+        .values_mut()
+        .next()
+        .unwrap();
+    node.size = oa_core::Size {
+        width: 4000.,
+        height: 4000.,
+    };
+    let before = p.clone();
+    let hits = saved_usages(&p, container);
+    assert_eq!(hits.len(), 1);
+    assert_eq!(hits[0].bounds.x, 40.);
+    assert_eq!(hits[0].bounds.y, 70.);
+    assert!(hits[0].bounds.width <= 420.);
+    assert!(hits[0].bounds.height <= 64.);
+    let (zoom, pan) = camera(hits[0].bounds, iced::Size::new(500., 300.));
+    assert!((hits[0].bounds.center_x() * zoom + pan.x - 250.).abs() < 0.01);
+    assert!(70. * zoom + pan.y >= 0.);
+    assert_eq!(p, before);
+}
+
+#[test]
+fn state_machine_owner_finds_its_view_without_a_machine_placement() {
+    let mut p = Project::empty();
+    let machine = p
+        .add_element(Kind::StateMachine, Layer::Sa, "Monitor", None)
+        .unwrap();
+    let unrelated = p
+        .add_element(Kind::StateMachine, Layer::Sa, "Other", None)
+        .unwrap();
+    let diagram = p.ensure_diagram(Layer::Sa);
+    p.diagrams.get_mut(&diagram).unwrap().projection =
+        oa_core::ProjectionKind::StateMachine { machine };
+    let before = p.clone();
+    let hits = saved_usages(&p, machine);
+    assert_eq!(hits.len(), 1);
+    assert_eq!(hits[0].surface, Surface::Saved(diagram));
+    assert_eq!(hits[0].target, Target::Whole);
+    assert_eq!(hits[0].role, "state machine view");
+    assert!(saved_usages(&p, unrelated).is_empty());
+    assert_eq!(p, before);
+}
+
+#[test]
+fn whole_diagram_camera_fits_large_bounds_instead_of_individual_object_scale() {
+    let bounds = Rectangle {
+        x: 2000.,
+        y: -4000.,
+        width: 100_000.,
+        height: 80_000.,
+    };
+    let (zoom, pan) = camera_for(&Target::Whole, bounds, iced::Size::new(500., 300.));
+    assert!(zoom < 0.01);
+    assert!(bounds.x * zoom + pan.x >= 0.);
+    assert!(bounds.y * zoom + pan.y >= 0.);
+    assert!((bounds.x + bounds.width) * zoom + pan.x <= 500.);
+    assert!((bounds.y + bounds.height) * zoom + pan.y <= 300.);
+}

crates/oa-desktop/src/diagram_usage/view.rs

@@ -0,0 +1,220 @@
+use super::*;
+use crate::{
+    app::{App, Message},
+    style,
+    views::{action, short},
+};
+use iced::{
+    Element, Fill,
+    widget::{self, column, container, row, text, text_input, tooltip},
+};
+use std::collections::BTreeSet;
+
+const PAGE_SIZE: usize = 6;
+
+pub(crate) fn overlay<'a>(app: &'a App, base: Element<'a, Message>) -> Element<'a, Message> {
+    let Some(panel) = &app.diagram_usages else {
+        return base;
+    };
+    let p = app.project();
+    let token = panel.token;
+    let message = |event| Message::DiagramUsage(event);
+    let matched = panel.matches(p);
+    let mut surfaces = Vec::new();
+    let mut seen = BTreeSet::new();
+    for usage in &matched {
+        if seen.insert(usage.surface) {
+            surfaces.push(usage.surface);
+        }
+    }
+    let targets: Vec<_> = matched
+        .iter()
+        .copied()
+        .filter(|usage| Some(usage.surface) == panel.destination)
+        .collect();
+    let count = if panel.destination.is_some() {
+        targets.len()
+    } else {
+        surfaces.len()
+    };
+    let last = count.saturating_sub(1) / PAGE_SIZE;
+    let page = panel.page.min(last);
+    let total_surfaces = panel
+        .usages
+        .iter()
+        .map(|u| u.surface)
+        .collect::<BTreeSet<_>>()
+        .len();
+    let mut content = column![
+        row![
+            text("Show in diagrams").size(22).width(Fill),
+            action("Close", message(Event::Close(token)))
+        ]
+        .spacing(12),
+        tooltip(
+            text(format!(
+                "{}  ·  @{}",
+                short(p.named(panel.context.subject), 48),
+                short(alias(p, panel.context.subject), 48)
+            ))
+            .size(14),
+            container(
+                widget::scrollable(
+                    text(format!(
+                        "{}\n@{}",
+                        p.named(panel.context.subject),
+                        alias(p, panel.context.subject)
+                    ))
+                    .size(13)
+                )
+                .height(220)
+            )
+            .padding(10)
+            .width(620)
+            .style(style::card),
+            tooltip::Position::Bottom
+        ),
+        text(if panel.loading {
+            "Searching rendered objects…".into()
+        } else {
+            format!(
+                "{} diagram destinations · {} representations",
+                total_surfaces,
+                panel.usages.len()
+            )
+        })
+        .size(12)
+        .color(style::MUTED),
+        text_input("Filter diagram, occurrence, or alias", &panel.search)
+            .id(format!("diagram-usage-filter-{}", panel.token))
+            .padding(9)
+            .on_input(move |value| Message::DiagramUsage(Event::Search(token, value)))
+            .on_submit(message(Event::Activate(token))),
+    ]
+    .spacing(10);
+    if let Some(notice) = &panel.notice {
+        content = content.push(text(notice).size(13));
+    }
+    if let Some(surface) = panel.destination {
+        content = content.push(
+            row![
+                action("All diagrams", message(Event::Destination(token, None))),
+                text(short(p.named(surface.id()), 55)).size(15),
+            ]
+            .spacing(10),
+        );
+        for (index, usage) in targets
+            .into_iter()
+            .enumerate()
+            .skip(page * PAGE_SIZE)
+            .take(PAGE_SIZE)
+        {
+            let name = target_name(p, usage);
+            content = content.push(tooltip(
+                action(
+                    &format!("{} · {}", usage.role, short(&name, 70)),
+                    message(Event::Choose(token, usage.clone())),
+                )
+                .width(Fill)
+                .style(if panel.cursor == index {
+                    style::selected
+                } else {
+                    style::nav
+                }),
+                container(text(name).size(13))
+                    .padding(10)
+                    .max_width(680)
+                    .style(style::card),
+                tooltip::Position::Top,
+            ));
+        }
+    } else {
+        for (index, surface) in surfaces
+            .into_iter()
+            .enumerate()
+            .skip(page * PAGE_SIZE)
+            .take(PAGE_SIZE)
+        {
+            let targets = matched.iter().filter(|u| u.surface == surface).count();
+            let name = format!(
+                "{} · {} (@{}) · {} representations",
+                surface.category(p),
+                p.named(surface.id()),
+                alias(p, surface.id()),
+                targets
+            );
+            let layer = p
+                .diagrams
+                .get(&surface.id())
+                .map(|d| d.layer)
+                .or_else(|| p.layer_of(surface.id()))
+                .map(|l| l.to_string())
+                .unwrap_or_default();
+            content = content.push(tooltip(
+                action(
+                    &format!(
+                        "{} · {} · {} · {}",
+                        surface.category(p),
+                        layer,
+                        short(p.named(surface.id()), 34),
+                        targets
+                    ),
+                    message(Event::Destination(token, Some(surface))),
+                )
+                .width(Fill)
+                .style(if panel.cursor == index {
+                    style::selected
+                } else {
+                    style::nav
+                }),
+                container(text(name).size(13))
+                    .padding(10)
+                    .max_width(680)
+                    .style(style::card),
+                tooltip::Position::Top,
+            ));
+        }
+    }
+    if panel.loading {
+        content = content.push(text("Finding diagram representations…").size(13));
+    } else if count == 0 {
+        content = content.push(text(if panel.usages.is_empty() {
+            "No currently rendered representation found. Folded or filtered objects and unexpanded reuse contents are excluded."
+        } else { "No results match this filter." }).size(13));
+    }
+    let mut paging = row![
+        text(format!(
+            "Page {} of {} · {} matches",
+            page + 1,
+            last + 1,
+            count
+        ))
+        .size(12)
+        .width(Fill)
+    ]
+    .spacing(8);
+    if page > 0 {
+        paging = paging.push(action("Previous", message(Event::Page(token, page - 1))));
+    }
+    if page < last {
+        paging = paging.push(action("Next", message(Event::Page(token, page + 1))));
+    }
+    content = content.push(paging).push(text("↑ ↓ choose · Enter opens · Escape closes. Source and saved view settings are preserved.").size(12).color(style::MUTED));
+    widget::stack![
+        base,
+        widget::opaque(
+            container(
+                container(content)
+                    .padding(22)
+                    .width((app.window_size.width - 80.).clamp(620., 820.))
+                    .style(style::card)
+            )
+            .center(Fill)
+            .style(|_| container::Style {
+                background: Some(iced::Color::from_rgba(0.08, 0.12, 0.18, 0.38).into()),
+                ..Default::default()
+            })
+        )
+    ]
+    .into()
+}

crates/oa-desktop/src/guide.rs

@@ -805,7 +805,7 @@ fn article(topic: Topic) -> Article {
             const {
                 Article {
                     summary: "The text editor and graphical forms edit the same model. Source projects preserve file organization and comments for human review, automation and version control.",
-                    keywords: "text textual source language syntax highlighting lint parser git aliases uuid identity rename diff merge restructuredtext spec canonical parity",
+                    keywords: "text textual source language syntax highlighting lint parser git aliases uuid identity rename diff merge restructuredtext spec canonical parity definition references lexical navigation F12 back",
                     sections: &[
                         walkthrough(
                             "Edit and review source",
@@ -818,6 +818,14 @@ fn article(topic: Topic) -> Article {
                                 "Save all writes the entry and its included UTF-8 files. Review the Git diff before committing, including relationships, traces and diagram changes that belong to the same engineering edit.",
                             ],
                         ),
+                        explain(
+                            "Follow definitions and lexical references",
+                            "Place the caret on a declaration alias or an @reference. Choose Definition (F12) to locate its declaration, or References (Shift+F12) to list lexical uses. Choose a row when a definition is ambiguous, draft or detached. Lexical uses exclude comments and strings; they do not establish typed relationships or resolve an ambiguous alias to one declaration. Back (Alt+Left) returns to the previous source location; if that draft changed, it restores the current cursor instead of an obsolete selection. These shortcuts work while the source editor has focus; the Text toolbar also offers the actions.",
+                        ),
+                        explain(
+                            "Read the navigation scope",
+                            "Queries inspect bounded snapshots of currently loaded drafts, without applying them or loading missing included files. The panel identifies partial scope, draft evidence, detached or unverified files, and alias or ID collisions. Counts show total, displayed and omitted rows. A missing result in partial scope does not establish that the whole project has no match. If sources change, stale rows are disabled; run Definition or References again. Row locations use one-based lines and UTF-8 byte columns. Navigation preserves your source drafts and the accepted model.",
+                        ),
                         explain(
                             "Names, aliases and IDs serve different purposes",
                             "The displayed name is engineering prose. A stable @alias is the readable source reference and need not change when the name changes. UUID identity distinguishes the persistent record. Preserve IDs when revising the same engineering object; changing identity is a deliberate operation that affects references.",

crates/oa-desktop/src/main.rs

@@ -7,6 +7,7 @@ mod context_menu;
 mod data_values;
 mod data_view;
 mod diagram;
+mod diagram_usage;
 mod document;
 mod explorer;
 mod explorer_view;

crates/oa-desktop/src/model_menu.rs

@@ -281,6 +281,11 @@ pub fn popup(app: &App) -> Option<Menu<Message>> {
         }
         entries.push(item("Properties", Message::EditProperties(id), true));
         entries.push(item("Open source", Message::SourceForSelection, true));
+        entries.push(item(
+            "Show in diagrams…",
+            app.diagram_usage_message(id),
+            true,
+        ));
         entries.push(item(
             "Connections & references",
             Message::InspectorTab(crate::navigation::InspectorTab::Connections),

crates/oa-desktop/src/navigation.rs

@@ -126,28 +126,8 @@ fn groups(p: &Project, selected: Id) -> Vec<Group> {
     ]
 }
 
-pub fn diagrams_containing(p: &Project, selected: Id) -> Vec<Id> {
-    let endpoints = p.relations.get(&selected).map(|r| [r.source(), r.target()]);
-    p.diagrams
-        .values()
-        .filter(|d| {
-            let placed = |id| {
-                let e = p.elements.get(&id);
-                let owner = e
-                    .filter(|e| e.kind() == Kind::Port)
-                    .and_then(|e| e.parent)
-                    .unwrap_or(id);
-                let kind = p.elements.get(&owner).map(|e| e.kind());
-                kind.is_none_or(|kind| d.projection.includes(kind))
-                    && d.nodes.values().any(|n| n.element == owner || n.id == id)
-            };
-            placed(selected) || endpoints.is_some_and(|ends| ends.into_iter().all(placed))
-        })
-        .map(|d| d.id)
-        .collect()
-}
-
-pub fn view(p: &Project, selected: Id) -> Element<'_, Message> {
+pub fn view(app: &crate::app::App, selected: Id) -> Element<'_, Message> {
+    let p = app.project();
     let mut content = column![
         text(short(p.named(selected), 50)).size(18),
         text("Follow ownership, usage and engineering relationships.")
@@ -203,25 +183,8 @@ pub fn view(p: &Project, selected: Id) -> Element<'_, Message> {
             content = content.push(container(entry).padding(8).style(style::subtle));
         }
     }
-    let diagrams = diagrams_containing(p, selected);
-    if !diagrams.is_empty() {
-        content = content.push(label("SHOWN IN DIAGRAMS"));
-        for id in diagrams {
-            content = content.push(
-                action(
-                    &short(p.named(id), 42),
-                    Message::RevealInDiagram(id, selected),
-                )
-                .width(Fill),
-            );
-        }
-    } else if p.elements.contains_key(&selected) {
-        content = content.push(
-            text("This element has no diagram placement yet.")
-                .size(12)
-                .color(style::MUTED),
-        );
-    }
+    content =
+        content.push(action("Show in diagrams…", app.diagram_usage_message(selected)).width(Fill));
     if count == 0 {
         content = content.push(text("No semantic connections yet. Use Actions or right-click an element to add relationships.").size(12).color(style::MUTED));
     }

crates/oa-desktop/src/source_navigation.rs

@@ -1,4 +1,9 @@
 //! Literal source search and line navigation, independent of accepted model state.
+mod controller;
+pub mod interaction;
+pub mod query;
+pub mod symbols;
+pub use controller::*;
 use iced::widget::text_editor::{Cursor, Position};
 
 #[derive(Debug, Clone)]

crates/oa-desktop/src/source_navigation/controller.rs

@@ -0,0 +1,126 @@
+//! Ephemeral editor navigation; no model commands or filesystem operations.
+use super::query;
+use iced::widget::text_editor::{Cursor, Position};
+use oa_core::Id;
+use std::sync::Arc;
+use std::sync::atomic::AtomicU64;
+
+#[derive(Debug, Clone)]
+pub enum SymbolEvent {
+    DiagramUsages,
+    Query(query::Action),
+    Back,
+    Close,
+    Choose {
+        stamp: query::QueryStamp,
+        reference: bool,
+        index: usize,
+    },
+}
+
+/// Identity of the mounted source view that emitted an action. Message queues
+/// may outlive that view; request-time stamping alone cannot detect replay.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct SymbolContext {
+    pub session: Id,
+    pub path: String,
+}
+
+#[derive(Debug, Clone)]
+pub struct HistoryEntry {
+    pub session: Id,
+    pub path: String,
+    pub generation: u64,
+    pub cursor: Cursor,
+}
+
+#[derive(Debug, Clone)]
+pub struct Request {
+    pub job: Id,
+    pub interaction: Id,
+    pub raw_interaction: u64,
+    pub stamp: query::QueryStamp,
+    pub path: String,
+    pub offset: usize,
+    pub cursor: Cursor,
+    pub action: query::Action,
+}
+
+#[derive(Debug, Clone)]
+pub struct Completion {
+    pub request: Request,
+    pub result: Result<(Arc<query::Snapshot>, Arc<query::Results>), String>,
+}
+
+pub struct Reveal {
+    pub ticket: Id,
+    pub interaction: Id,
+    pub raw_interaction: u64,
+    pub snapshot: query::SnapshotKey,
+    pub path: String,
+}
+
+pub struct SymbolState {
+    pub open: bool,
+    pub interaction: Id,
+    pub raw_interaction: Arc<AtomicU64>,
+    pub serial: u64,
+    pub in_flight: Option<Id>,
+    pub request: Option<Request>,
+    pub cache: Option<Arc<query::Snapshot>>,
+    pub results: Option<Arc<query::Results>>,
+    pub notice: Option<String>,
+    pub back: Vec<HistoryEntry>,
+    pub reveal: Option<Reveal>,
+}
+
+impl Default for SymbolState {
+    fn default() -> Self {
+        Self {
+            open: false,
+            interaction: Id::new_v4(),
+            raw_interaction: Arc::new(AtomicU64::new(0)),
+            serial: 0,
+            in_flight: None,
+            request: None,
+            cache: None,
+            results: None,
+            notice: None,
+            back: Vec::new(),
+            reveal: None,
+        }
+    }
+}
+
+/// Iced uses zero-based UTF-8 byte columns. Reject stale or split-codepoint
+/// coordinates; do not normalize CRLF or silently clamp query destinations.
+pub fn byte_offset(text: &str, position: Position) -> Option<usize> {
+    let start = if position.line == 0 {
+        0
+    } else {
+        text.match_indices('\n').nth(position.line - 1)?.0 + 1
+    };
+    let end = text[start..]
+        .find('\n')
+        .map_or(text.len(), |end| start + end);
+    let offset = start.checked_add(position.column)?;
+    (offset <= end && text.is_char_boundary(offset)).then_some(offset)
+}
+
+pub fn cursor_offset(text: &str, cursor: Cursor) -> Option<usize> {
+    let position = cursor.selection.map_or(cursor.position, |selection| {
+        if (selection.line, selection.column) < (cursor.position.line, cursor.position.column) {
+            selection
+        } else {
+            cursor.position
+        }
+    });
+    byte_offset(text, position)
+}
+
+pub fn exact_cursor(text: &str, cursor: Cursor) -> bool {
+    byte_offset(text, cursor.position).is_some()
+        && cursor
+            .selection
+            .is_none_or(|position| byte_offset(text, position).is_some())
+}

crates/oa-desktop/src/source_navigation/interaction.rs

@@ -0,0 +1,284 @@
+//! Raw input invalidation and focus checks at widget-operation execution time.
+use iced::advanced::{Clipboard, Layout, Shell, Widget, layout, overlay, renderer, widget};
+use iced::{Element, Event, Length, Rectangle, Size, Task, Vector, keyboard, mouse, touch};
+use std::sync::{
+    Arc,
+    atomic::{AtomicU64, Ordering},
+};
+
+/// Exhaustion fails closed: a saturated clock can never authorize navigation.
+/// Replace the clock with a new workspace/controller, rather than wrapping it.
+pub fn is_current(clock: &AtomicU64, expected: u64) -> bool {
+    expected != u64::MAX && clock.load(Ordering::Acquire) == expected
+}
+
+fn invalidate(clock: &AtomicU64, event: &Event) {
+    if matches!(
+        event,
+        Event::Keyboard(keyboard::Event::KeyPressed { .. })
+            | Event::Mouse(mouse::Event::ButtonPressed(_) | mouse::Event::WheelScrolled { .. })
+            | Event::Touch(touch::Event::FingerPressed { .. })
+            | Event::Window(iced::window::Event::Unfocused)
+    ) {
+        let _ = clock.fetch_update(Ordering::AcqRel, Ordering::Acquire, |value| {
+            Some(value.saturating_add(1))
+        });
+    }
+}
+
+/// Transparent, including overlays: invalidate before the child can capture input.
+pub fn observe<'a, Message: 'a, Theme: 'a, Renderer: renderer::Renderer + 'a>(
+    content: Element<'a, Message, Theme, Renderer>,
+    clock: Arc<AtomicU64>,
+) -> Element<'a, Message, Theme, Renderer> {
+    Element::new(Observed { content, clock })
+}
+
+struct Observed<'a, Message, Theme, Renderer> {
+    content: Element<'a, Message, Theme, Renderer>,
+    clock: Arc<AtomicU64>,
+}
+
+impl<Message, Theme, Renderer: renderer::Renderer> Widget<Message, Theme, Renderer>
+    for Observed<'_, Message, Theme, Renderer>
+{
+    fn size(&self) -> Size<Length> {
+        self.content.as_widget().size()
+    }
+    fn size_hint(&self) -> Size<Length> {
+        self.content.as_widget().size_hint()
+    }
+    fn tag(&self) -> widget::tree::Tag {
+        self.content.as_widget().tag()
+    }
+    fn state(&self) -> widget::tree::State {
+        self.content.as_widget().state()
+    }
+    fn children(&self) -> Vec<widget::Tree> {
+        self.content.as_widget().children()
+    }
+    fn diff(&self, tree: &mut widget::Tree) {
+        self.content.as_widget().diff(tree);
+    }
+    fn layout(
+        &mut self,
+        tree: &mut widget::Tree,
+        renderer: &Renderer,
+        limits: &layout::Limits,
+    ) -> layout::Node {
+        self.content.as_widget_mut().layout(tree, renderer, limits)
+    }
+    fn draw(
+        &self,
+        tree: &widget::Tree,
+        renderer: &mut Renderer,
+        theme: &Theme,
+        style: &renderer::Style,
+        layout: Layout<'_>,
+        cursor: mouse::Cursor,
+        viewport: &Rectangle,
+    ) {
+        self.content
+            .as_widget()
+            .draw(tree, renderer, theme, style, layout, cursor, viewport);
+    }
+    fn operate(
+        &mut self,
+        tree: &mut widget::Tree,
+        layout: Layout<'_>,
+        renderer: &Renderer,
+        operation: &mut dyn widget::Operation,
+    ) {
+        self.content
+            .as_widget_mut()
+            .operate(tree, layout, renderer, operation);
+    }
+    fn update(
+        &mut self,
+        tree: &mut widget::Tree,
+        event: &Event,
+        layout: Layout<'_>,
+        cursor: mouse::Cursor,
+        renderer: &Renderer,
+        clipboard: &mut dyn Clipboard,
+        shell: &mut Shell<'_, Message>,
+        viewport: &Rectangle,
+    ) {
+        invalidate(&self.clock, event);
+        self.content.as_widget_mut().update(
+            tree, event, layout, cursor, renderer, clipboard, shell, viewport,
+        );
+    }
+    fn mouse_interaction(
+        &self,
+        tree: &widget::Tree,
+        layout: Layout<'_>,
+        cursor: mouse::Cursor,
+        viewport: &Rectangle,
+        renderer: &Renderer,
+    ) -> mouse::Interaction {
+        self.content
+            .as_widget()
+            .mouse_interaction(tree, layout, cursor, viewport, renderer)
+    }
+    fn overlay<'a>(
+        &'a mut self,
+        tree: &'a mut widget::Tree,
+        layout: Layout<'a>,
+        renderer: &Renderer,
+        viewport: &Rectangle,
+        translation: Vector,
+    ) -> Option<overlay::Element<'a, Message, Theme, Renderer>> {
+        let clock = self.clock.clone();
+        self.content
+            .as_widget_mut()
+            .overlay(tree, layout, renderer, viewport, translation)
+            .map(|content| overlay::Element::new(Box::new(ObservedOverlay { content, clock })))
+    }
+}
+
+struct ObservedOverlay<'a, Message, Theme, Renderer> {
+    content: overlay::Element<'a, Message, Theme, Renderer>,
+    clock: Arc<AtomicU64>,
+}
+impl<Message, Theme, Renderer: renderer::Renderer> overlay::Overlay<Message, Theme, Renderer>
+    for ObservedOverlay<'_, Message, Theme, Renderer>
+{
+    fn layout(&mut self, renderer: &Renderer, bounds: Size) -> layout::Node {
+        self.content.as_overlay_mut().layout(renderer, bounds)
+    }
+    fn draw(
+        &self,
+        renderer: &mut Renderer,
+        theme: &Theme,
+        style: &renderer::Style,
+        layout: Layout<'_>,
+        cursor: mouse::Cursor,
+    ) {
+        self.content
+            .as_overlay()
+            .draw(renderer, theme, style, layout, cursor);
+    }
+    fn operate(
+        &mut self,
+        layout: Layout<'_>,
+        renderer: &Renderer,
+        operation: &mut dyn widget::Operation,
+    ) {
+        self.content
+            .as_overlay_mut()
+            .operate(layout, renderer, operation);
+    }
+    fn update(
+        &mut self,
+        event: &Event,
+        layout: Layout<'_>,
+        cursor: mouse::Cursor,
+        renderer: &Renderer,
+        clipboard: &mut dyn Clipboard,
+        shell: &mut Shell<'_, Message>,
+    ) {
+        invalidate(&self.clock, event);
+        self.content
+            .as_overlay_mut()
+            .update(event, layout, cursor, renderer, clipboard, shell);
+    }
+    fn mouse_interaction(
+        &self,
+        layout: Layout<'_>,
+        cursor: mouse::Cursor,
+        renderer: &Renderer,
+    ) -> mouse::Interaction {
+        self.content
+            .as_overlay()
+            .mouse_interaction(layout, cursor, renderer)
+    }
+    fn overlay<'a>(
+        &'a mut self,
+        layout: Layout<'a>,
+        renderer: &Renderer,
+    ) -> Option<overlay::Element<'a, Message, Theme, Renderer>> {
+        let clock = self.clock.clone();
+        self.content
+            .as_overlay_mut()
+            .overlay(layout, renderer)
+            .map(|content| overlay::Element::new(Box::new(ObservedOverlay { content, clock })))
+    }
+    fn index(&self) -> f32 {
+        self.content.as_overlay().index()
+    }
+}
+
+/// Inspect all focus owners, then focus only the mounted target. Iced executes
+/// Operation::Chain synchronously, without an intervening input event. Both
+/// traversals recheck the raw clock; no result message authorizes later focus.
+pub fn guarded_focus<Message: Send + 'static>(
+    target: widget::Id,
+    clock: Arc<AtomicU64>,
+    expected: u64,
+) -> Task<Message> {
+    widget::operate(GuardedFocus::new(target, clock, expected))
+}
+
+struct GuardedFocus {
+    target: widget::Id,
+    clock: Arc<AtomicU64>,
+    expected: u64,
+    target_count: usize,
+    foreign_focus: bool,
+    apply: bool,
+}
+impl GuardedFocus {
+    fn new(target: widget::Id, clock: Arc<AtomicU64>, expected: u64) -> Self {
+        Self {
+            target,
+            clock,
+            expected,
+            target_count: 0,
+            foreign_focus: false,
+            apply: false,
+        }
+    }
+}
+impl<Message: 'static> widget::Operation<Message> for GuardedFocus {
+    fn traverse(&mut self, visit: &mut dyn FnMut(&mut dyn widget::Operation<Message>)) {
+        if is_current(&self.clock, self.expected) {
+            visit(self);
+        }
+    }
+    fn focusable(
+        &mut self,
+        id: Option<&widget::Id>,
+        _: Rectangle,
+        state: &mut dyn widget::operation::Focusable,
+    ) {
+        if !is_current(&self.clock, self.expected) {
+            return;
+        }
+        if id == Some(&self.target) {
+            self.target_count += 1;
+            if self.apply {
+                state.focus();
+            }
+        } else if state.is_focused() {
+            self.foreign_focus = true;
+        }
+    }
+    fn finish(&self) -> widget::operation::Outcome<Message> {
+        if !self.apply
+            && self.target_count == 1
+            && !self.foreign_focus
+            && is_current(&self.clock, self.expected)
+        {
+            widget::operation::Outcome::Chain(Box::new(Self {
+                apply: true,
+                ..Self::new(self.target.clone(), self.clock.clone(), self.expected)
+            }))
+        } else {
+            widget::operation::Outcome::None
+        }
+    }
+}
+
+#[cfg(all(test, debug_assertions))]
+mod tests;

crates/oa-desktop/src/source_navigation/interaction/tests.rs

@@ -0,0 +1,190 @@
+use super::*;
+use iced::advanced::widget::operation::{Focusable, Outcome};
+use iced::widget::{column, text_input};
+use iced::{Point, Theme};
+
+#[derive(Default)]
+struct FocusMap(Vec<(Option<widget::Id>, Rectangle, bool)>);
+impl widget::Operation for FocusMap {
+    fn traverse(&mut self, visit: &mut dyn FnMut(&mut dyn widget::Operation)) {
+        visit(self);
+    }
+    fn focusable(&mut self, id: Option<&widget::Id>, bounds: Rectangle, state: &mut dyn Focusable) {
+        self.0.push((id.cloned(), bounds, state.is_focused()));
+    }
+}
+
+struct Mounted {
+    element: Element<'static, (), Theme, ()>,
+    tree: widget::Tree,
+    node: layout::Node,
+}
+impl Mounted {
+    fn new(clock: Arc<AtomicU64>) -> Self {
+        let content = column![
+            text_input("Editor", "source")
+                .id("editor")
+                .on_input(|_| ())
+                .padding(12),
+            text_input("Find", "")
+                .id("find")
+                .on_input(|_| ())
+                .padding(12),
+        ]
+        .spacing(10)
+        .into();
+        let mut element = observe(content, clock);
+        let mut tree = widget::Tree::new(element.as_widget());
+        let node = element.as_widget_mut().layout(
+            &mut tree,
+            &(),
+            &layout::Limits::new(Size::ZERO, Size::new(400., 200.)),
+        );
+        Self {
+            element,
+            tree,
+            node,
+        }
+    }
+    fn pass(&mut self, operation: &mut dyn widget::Operation) {
+        self.element.as_widget_mut().operate(
+            &mut self.tree,
+            Layout::new(&self.node),
+            &(),
+            operation,
+        );
+    }
+    fn run(&mut self, operation: impl widget::Operation + 'static) {
+        let mut next: Box<dyn widget::Operation> = Box::new(operation);
+        loop {
+            self.pass(next.as_mut());
+            match next.finish() {
+                Outcome::Chain(chained) => next = chained,
+                Outcome::None => break,
+                Outcome::Some(()) => panic!("focus must not publish an application message"),
+            }
+        }
+    }
+    fn focus(&mut self) -> FocusMap {
+        let mut focus = FocusMap::default();
+        self.pass(&mut focus);
+        focus
+    }
+    fn click(&mut self, id: &str) {
+        let bounds = self
+            .focus()
+            .0
+            .into_iter()
+            .find(|(found, _, _)| found.as_ref() == Some(&widget::Id::from(id.to_owned())))
+            .unwrap()
+            .1;
+        let mut messages = Vec::new();
+        let mut shell = Shell::new(&mut messages);
+        self.element.as_widget_mut().update(
+            &mut self.tree,
+            &Event::Mouse(mouse::Event::ButtonPressed(mouse::Button::Left)),
+            Layout::new(&self.node),
+            mouse::Cursor::Available(bounds.center()),
+            &(),
+            &mut iced::advanced::clipboard::Null,
+            &mut shell,
+            &Rectangle::with_size(Size::new(400., 200.)),
+        );
+        assert!(shell.is_event_captured());
+        assert!(
+            messages.is_empty(),
+            "focus-only click must not rely on App messages"
+        );
+    }
+    fn focused(&mut self, id: &str) -> bool {
+        self.focus()
+            .0
+            .into_iter()
+            .find(|(found, _, _)| found.as_ref() == Some(&widget::Id::from(id.to_owned())))
+            .unwrap()
+            .2
+    }
+}
+
+#[test]
+fn captured_find_click_invalidates_without_app_message_and_preserves_focus() {
+    let clock = Arc::new(AtomicU64::new(0));
+    let mut ui = Mounted::new(clock.clone());
+    ui.run(GuardedFocus::new("editor".into(), clock.clone(), 0));
+    assert!(ui.focused("editor"));
+    ui.click("find");
+    assert!(!is_current(&clock, 0));
+    assert!(ui.focused("find"));
+    ui.run(GuardedFocus::new("editor".into(), clock.clone(), 0));
+    assert!(ui.focused("find"));
+    // Even a matching clock cannot authorize stealing another widget's focus.
+    ui.run(GuardedFocus::new(
+        "editor".into(),
+        clock.clone(),
+        clock.load(Ordering::Acquire),
+    ));
+    assert!(ui.focused("find"));
+    assert!(!ui.focused("editor"));
+}
+
+#[test]
+fn focus_rechecks_clock_between_inspection_and_application_and_missing_target_is_inert() {
+    let clock = Arc::new(AtomicU64::new(0));
+    let mut ui = Mounted::new(clock.clone());
+    let mut operation = GuardedFocus::new("editor".into(), clock.clone(), 0);
+    ui.pass(&mut operation);
+    let Outcome::Chain(mut apply) = <GuardedFocus as widget::Operation<()>>::finish(&operation)
+    else {
+        panic!("mounted, unopposed target must be eligible");
+    };
+    clock.store(1, Ordering::Release);
+    ui.pass(apply.as_mut());
+    assert!(!ui.focused("editor"));
+    ui.run(GuardedFocus::new("editor".into(), clock.clone(), 1));
+    assert!(ui.focused("editor"));
+    ui.run(GuardedFocus::new("removed-editor".into(), clock, 1));
+    assert!(ui.focused("editor"));
+}
+
+#[test]
+fn raw_navigation_inputs_advance_but_passive_geometry_does_not_and_exhaustion_refuses() {
+    let clock = AtomicU64::new(0);
+    let events = [
+        Event::Keyboard(keyboard::Event::KeyPressed {
+            key: keyboard::Key::Named(keyboard::key::Named::ArrowLeft),
+            modified_key: keyboard::Key::Named(keyboard::key::Named::ArrowLeft),
+            physical_key: keyboard::key::Physical::Code(keyboard::key::Code::ArrowLeft),
+            location: keyboard::Location::Standard,
+            modifiers: keyboard::Modifiers::empty(),
+            text: None,
+            repeat: false,
+        }),
+        Event::Mouse(mouse::Event::ButtonPressed(mouse::Button::Left)),
+        Event::Mouse(mouse::Event::WheelScrolled {
+            delta: mouse::ScrollDelta::Lines { x: 0., y: 1. },
+        }),
+        Event::Touch(touch::Event::FingerPressed {
+            id: touch::Finger(1),
+            position: Point::ORIGIN,
+        }),
+        Event::Window(iced::window::Event::Unfocused),
+    ];
+    for (index, event) in events.iter().enumerate() {
+        invalidate(&clock, event);
+        assert_eq!(clock.load(Ordering::Acquire), index as u64 + 1);
+    }
+    invalidate(
+        &clock,
+        &Event::Mouse(mouse::Event::CursorMoved {
+            position: Point::ORIGIN,
+        }),
+    );
+    invalidate(&clock, &Event::Window(iced::window::Event::Focused));
+    assert!(is_current(&clock, 5));
+    clock.store(u64::MAX - 1, Ordering::Release);
+    invalidate(&clock, &events[0]);
+    assert!(!is_current(&clock, u64::MAX));
+    invalidate(&clock, &events[0]);
+    assert_eq!(clock.load(Ordering::Acquire), u64::MAX);
+    assert!(!is_current(&clock, 0));
+}

crates/oa-desktop/src/source_navigation/query_tests.rs

@@ -0,0 +1,989 @@
+use super::*;
+
+const PROJECT: &str = "00000000-0000-0000-0000-000000000001";
+const PUMP: &str = "00000000-0000-0000-0000-000000000002";
+const LINK: &str = "00000000-0000-0000-0000-000000000003";
+
+#[derive(Clone)]
+struct Fixture {
+    entry: String,
+    files: Vec<(String, String)>,
+}
+
+impl Fixture {
+    fn standard() -> Self {
+        Self {
+            entry: "project.arcadia".into(),
+            files: vec![
+                (
+                    "project.arcadia".into(),
+                    format!(
+                        "arcadia 7;\r\nproject model \"Harbour\" id \"{PROJECT}\" {{\r\n include \"模块/活動.arcadia\";\r\n include \"links.arcadia\";\r\n}}\r\n"
+                    ),
+                ),
+                (
+                    "模块/活動.arcadia".into(),
+                    format!(
+                        "// 原文 remains exact\r\noa_activity pump \"泵 🚀\" id \"{PUMP}\" {{}}\r\n"
+                    ),
+                ),
+                (
+                    "links.arcadia".into(),
+                    format!(
+                        "// 航海\r\ninteraction connection \"流れ\" id \"{LINK}\" {{\r\n source @ // separator @pump\r\n   pump;\r\n description \"船 @pump\"; target @pump;\r\n}}\r\n"
+                    ),
+                ),
+            ],
+        }
+    }
+
+    fn borrowed(&self) -> Vec<DraftFile<'_>> {
+        self.files
+            .iter()
+            .map(|(path, text)| DraftFile { path, text })
+            .collect()
+    }
+
+    fn text(&self, path: &str) -> &str {
+        &self
+            .files
+            .iter()
+            .find(|(candidate, _)| candidate == path)
+            .unwrap()
+            .1
+    }
+
+    fn text_mut(&mut self, path: &str) -> &mut String {
+        &mut self
+            .files
+            .iter_mut()
+            .find(|(candidate, _)| candidate == path)
+            .unwrap()
+            .1
+    }
+
+    fn snapshot(&self, validated: Option<&Self>, applied: bool, limits: Limits) -> Snapshot {
+        let current = self.borrowed();
+        let old = validated.map(Self::borrowed);
+        capture(
+            Input {
+                key: key(1),
+                entry: &self.entry,
+                files: &current,
+                applied,
+                validation: old.as_ref().map(|files| ValidatedSources {
+                    entry: &validated.unwrap().entry,
+                    files,
+                }),
+            },
+            limits,
+        )
+        .unwrap()
+    }
+}
+
+fn key(revision: u64) -> SnapshotKey {
+    SnapshotKey {
+        workspace: Id::from_u128(100),
+        revision,
+    }
+}
+
+fn query(snapshot: &Snapshot, path: &str, byte_offset: usize, action: Action) -> Results {
+    snapshot
+        .query(Query {
+            stamp: QueryStamp {
+                snapshot: snapshot.key(),
+                serial: 37,
+            },
+            path,
+            byte_offset,
+            action,
+        })
+        .unwrap()
+}
+
+fn reference_offset(fixture: &Fixture) -> usize {
+    fixture.text("links.arcadia").find("source @").unwrap() + "source ".len()
+}
+
+#[test]
+fn exact_multifile_unicode_crlf_definition_and_repeated_lexical_references() {
+    let fixture = Fixture::standard();
+    let original = fixture.files.clone();
+    let snapshot = fixture.snapshot(Some(&fixture), true, Limits::default());
+    assert!(snapshot.scope().closure_complete && snapshot.scope().validated);
+    assert_eq!(
+        (
+            snapshot.scope().included_files,
+            snapshot.scope().detached_files
+        ),
+        (3, 0)
+    );
+    let result = query(
+        &snapshot,
+        "links.arcadia",
+        reference_offset(&fixture),
+        Action::Definition,
+    );
+    assert_eq!(result.disposition, Disposition::Direct);
+    assert_eq!(
+        (result.total_definitions, result.omitted_definitions),
+        (1, 0)
+    );
+    let definition = &result.definitions[0];
+    assert_eq!(definition.path, "模块/活動.arcadia");
+    assert_eq!(definition.declaration.kind, "oa_activity");
+    assert_eq!(definition.declaration.name.as_deref(), Some("泵 🚀"));
+    assert_eq!(
+        definition.declaration.authored_id,
+        Some(Id::parse_str(PUMP).unwrap())
+    );
+    assert_eq!(
+        definition.position,
+        Position {
+            line: 1,
+            byte_column: "oa_activity ".len()
+        }
+    );
+    assert_eq!(
+        &fixture.text(&definition.path)[definition.span.start..definition.span.end],
+        "pump"
+    );
+    let uses = query(
+        &snapshot,
+        &definition.path,
+        definition.span.start,
+        Action::References,
+    );
+    assert_eq!(uses.disposition, Disposition::LexicalReferences);
+    assert_eq!((uses.total_references, uses.omitted_references), (2, 0));
+    assert_eq!(
+        uses.references[0].position,
+        Position {
+            line: 3,
+            byte_column: 3
+        }
+    );
+    let target_prefix = " description \"船 @pump\"; target @";
+    assert_ne!(target_prefix.len(), target_prefix.chars().count());
+    assert_eq!(
+        uses.references[1].position,
+        Position {
+            line: 4,
+            byte_column: target_prefix.len()
+        }
+    );
+    for row in &uses.references {
+        let text = fixture.text(&row.path);
+        assert_eq!(&text[row.span.start..row.span.end], "pump");
+        assert_eq!(&text[row.marker.start..row.marker.end], "@");
+        let context = row.context.as_ref().unwrap();
+        assert_eq!(context.alias, "connection");
+        assert_eq!(context.kind, "interaction");
+        assert_eq!(context.name.as_deref(), Some("流れ"));
+        assert_eq!(row.evidence, Evidence::Validated);
+    }
+    assert_eq!(
+        uses.stamp,
+        QueryStamp {
+            snapshot: key(1),
+            serial: 37
+        }
+    );
+    assert_eq!(
+        fixture.files, original,
+        "no stabilization, newline rewrite or accepted adoption"
+    );
+    for (index, (path, text)) in original.iter().enumerate() {
+        let owned = snapshot.file(index).unwrap();
+        assert_eq!((owned.path, owned.text), (path.as_str(), text.as_str()));
+    }
+}
+
+#[test]
+fn comments_strings_and_comment_gap_are_not_navigation_hits() {
+    let fixture = Fixture::standard();
+    let snapshot = fixture.snapshot(None, true, Limits::default());
+    let text = fixture.text("links.arcadia");
+    for offset in [
+        text.find("separator @pump").unwrap() + "separator ".len(),
+        text.find("船 @pump").unwrap() + "船 ".len(),
+        text.find("@ //").unwrap() + 1,
+    ] {
+        let result = query(&snapshot, "links.arcadia", offset, Action::Definition);
+        assert_eq!(result.disposition, Disposition::NoSymbol);
+        assert_eq!(result.total_definitions, 0);
+    }
+    assert_eq!(
+        query(
+            &snapshot,
+            "links.arcadia",
+            text.find("   pump;").unwrap() + 3,
+            Action::Definition
+        )
+        .total_definitions,
+        1
+    );
+    let inside_utf8 = text.find('船').unwrap() + 1;
+    assert_eq!(
+        snapshot.query(Query {
+            stamp: QueryStamp {
+                snapshot: key(1),
+                serial: 1
+            },
+            path: "links.arcadia",
+            byte_offset: inside_utf8,
+            action: Action::Definition
+        }),
+        Err(QueryError::Query(symbols::QueryError::InvalidBytePosition))
+    );
+}
+
+#[test]
+fn dirty_but_parseable_text_has_current_names_and_no_validated_fallback() {
+    let original = Fixture::standard();
+    let mut dirty = original.clone();
+    *dirty.text_mut("模块/活動.arcadia") = dirty
+        .text("模块/活動.arcadia")
+        .replace("泵 🚀", "Edited 泵\\nwith detail");
+    let snapshot = dirty.snapshot(Some(&original), true, Limits::default());
+    assert!(snapshot.scope().closure_complete);
+    assert!(!snapshot.scope().validated);
+    let result = query(
+        &snapshot,
+        "links.arcadia",
+        reference_offset(&dirty),
+        Action::Definition,
+    );
+    assert_eq!(result.disposition, Disposition::Choices);
+    assert_eq!(
+        result.definitions[0].declaration.name.as_deref(),
+        Some("Edited 泵\nwith detail")
+    );
+    assert_eq!(result.definitions[0].evidence, Evidence::Draft);
+    assert_eq!(
+        snapshot.file(1).unwrap().text,
+        dirty.text("模块/活動.arcadia")
+    );
+    assert_ne!(
+        snapshot.file(1).unwrap().text,
+        original.text("模块/活動.arcadia")
+    );
+}
+
+#[test]
+fn invalid_include_syntax_never_borrows_the_old_reachable_file_set() {
+    let original = Fixture::standard();
+    let mut invalid = original.clone();
+    *invalid.text_mut("project.arcadia") = invalid
+        .text("project.arcadia")
+        .replace("include \"links.arcadia\";", "include \"links.arcadia\"");
+    let snapshot = invalid.snapshot(Some(&original), true, Limits::default());
+    assert!(snapshot.scope().partial());
+    assert!(!snapshot.scope().validated);
+    assert!(
+        snapshot
+            .scope()
+            .issues
+            .iter()
+            .any(|issue| issue.kind == ScopeIssueKind::InvalidIncludes)
+    );
+    let result = query(
+        &snapshot,
+        "links.arcadia",
+        reference_offset(&invalid),
+        Action::Definition,
+    );
+    assert_eq!(result.total_definitions, 1);
+    assert_eq!(result.disposition, Disposition::Choices);
+    assert_eq!(result.definitions[0].membership, Membership::Unverified);
+}
+
+#[test]
+fn missing_include_partial_scope_does_not_resurrect_witness_text() {
+    let original = Fixture::standard();
+    let mut missing = original.clone();
+    missing
+        .files
+        .retain(|(path, _)| path != "模块/活動.arcadia");
+    let snapshot = missing.snapshot(Some(&original), true, Limits::default());
+    assert!(snapshot.scope().partial());
+    assert!(
+        snapshot
+            .scope()
+            .issues
+            .iter()
+            .any(|issue| issue.kind == ScopeIssueKind::MissingInclude)
+    );
+    let result = query(
+        &snapshot,
+        "links.arcadia",
+        reference_offset(&missing),
+        Action::Definition,
+    );
+    assert_eq!(result.disposition, Disposition::NoDefinition);
+    assert!(result.definitions.is_empty());
+    assert!(
+        result.scope.partial(),
+        "zero means no loaded definition, not no project definition"
+    );
+    assert!(snapshot.file(2).is_none());
+}
+
+#[test]
+fn detached_alias_and_identity_collisions_never_auto_select() {
+    let accepted = Fixture::standard();
+    for (alias, id) in [
+        ("pump", "00000000-0000-0000-0000-000000000099"),
+        ("other", PUMP),
+    ] {
+        let mut loaded = accepted.clone();
+        loaded.files.push((
+            "detached.arcadia".into(),
+            format!("oa_activity {alias} \"Detached\" id \"{id}\" {{}}"),
+        ));
+        let snapshot = loaded.snapshot(Some(&accepted), true, Limits::default());
+        assert!(snapshot.scope().validated);
+        assert_eq!(snapshot.scope().detached_files, 1);
+        let result = query(
+            &snapshot,
+            "links.arcadia",
+            reference_offset(&loaded),
+            Action::Definition,
+        );
+        assert_eq!(result.disposition, Disposition::Choices);
+        if alias == "pump" {
+            assert_eq!(result.total_definitions, 2);
+            assert!(result.definitions.iter().any(
+                |row| row.membership == Membership::Detached && row.evidence == Evidence::Draft
+            ));
+        } else {
+            assert_eq!(result.total_definitions, 1);
+            assert_eq!(
+                result.definitions[0].declaration.identity,
+                Identity::Collision { count: 2 }
+            );
+        }
+    }
+}
+
+#[test]
+fn sole_detached_candidate_and_unapplied_equal_bytes_require_choice() {
+    let accepted = Fixture::standard();
+    let mut detached = accepted.clone();
+    *detached.text_mut("project.arcadia") = detached
+        .text("project.arcadia")
+        .replace(" include \"模块/活動.arcadia\";\r\n", "");
+    let snapshot = detached.snapshot(None, true, Limits::default());
+    let result = query(
+        &snapshot,
+        "links.arcadia",
+        reference_offset(&detached),
+        Action::Definition,
+    );
+    assert_eq!(result.disposition, Disposition::Choices);
+    assert_eq!(result.definitions[0].membership, Membership::Detached);
+    let unapplied = accepted.snapshot(Some(&accepted), false, Limits::default());
+    assert!(unapplied.scope().closure_complete && unapplied.scope().partial());
+    assert!(!unapplied.scope().validated);
+    assert_eq!(
+        query(
+            &unapplied,
+            "links.arcadia",
+            reference_offset(&accepted),
+            Action::Definition
+        )
+        .disposition,
+        Disposition::Choices
+    );
+}
+
+#[test]
+fn include_cycle_depth_and_aggregate_edges_are_explicit_partial_outcomes() {
+    let mut fixture = Fixture::standard();
+    fixture
+        .text_mut("模块/活動.arcadia")
+        .push_str("include \"../project.arcadia\";\r\n");
+    let cycle = fixture.snapshot(None, true, Limits::default());
+    assert!(
+        cycle
+            .scope()
+            .issues
+            .iter()
+            .any(|issue| issue.kind == ScopeIssueKind::IncludeCycle)
+    );
+    let fixture = Fixture::standard();
+    for (depth, edges, expected) in [
+        (0, 1024, ScopeIssueKind::IncludeDepth),
+        (32, 1, ScopeIssueKind::IncludeBudget),
+    ] {
+        let snapshot = fixture.snapshot(
+            None,
+            true,
+            Limits {
+                include_depth: depth,
+                include_edges: edges,
+                ..Limits::default()
+            },
+        );
+        assert!(snapshot.scope().partial());
+        assert!(
+            snapshot
+                .scope()
+                .issues
+                .iter()
+                .any(|issue| issue.kind == expected)
+        );
+        assert_eq!(
+            query(
+                &snapshot,
+                "links.arcadia",
+                reference_offset(&fixture),
+                Action::Definition
+            )
+            .disposition,
+            Disposition::Choices
+        );
+    }
+}
+
+#[test]
+fn exact_snapshot_readback_rejects_same_key_byte_membership_and_evidence_changes() {
+    let fixture = Fixture::standard();
+    let files = fixture.borrowed();
+    let validation = Some(ValidatedSources {
+        entry: &fixture.entry,
+        files: &files,
+    });
+    let input = Input {
+        key: key(1),
+        entry: &fixture.entry,
+        files: &files,
+        applied: true,
+        validation,
+    };
+    let snapshot = capture(input, Limits::default()).unwrap();
+    assert!(snapshot.matches(input));
+    assert!(!snapshot.matches(Input {
+        key: key(2),
+        ..input
+    }));
+    assert!(!snapshot.matches(Input {
+        validation: None,
+        ..input
+    }));
+    assert!(!snapshot.matches(Input {
+        applied: false,
+        ..input
+    }));
+    let mut reversed = files.clone();
+    reversed.reverse();
+    assert!(snapshot.matches(Input {
+        files: &reversed,
+        ..input
+    }));
+    let mut changed = fixture.clone();
+    changed.text_mut("links.arcadia").push(' ');
+    let altered = changed.borrowed();
+    assert!(!snapshot.matches(Input {
+        files: &altered,
+        ..input
+    }));
+    let missing = &files[..files.len() - 1];
+    assert!(!snapshot.matches(Input {
+        files: missing,
+        ..input
+    }));
+    let duplicated = [files[0], files[0], files[2]];
+    assert!(!snapshot.matches(Input {
+        files: &duplicated,
+        ..input
+    }));
+    assert_eq!(
+        snapshot.query(Query {
+            stamp: QueryStamp {
+                snapshot: key(2),
+                serial: 37
+            },
+            path: "links.arcadia",
+            byte_offset: 0,
+            action: Action::Definition
+        }),
+        Err(QueryError::Query(symbols::QueryError::StaleSnapshot))
+    );
+}
+
+#[test]
+fn omitted_rows_are_counted_before_result_allocation_and_never_confer_uniqueness() {
+    let fixture = Fixture::standard();
+    let snapshot = fixture.snapshot(
+        Some(&fixture),
+        true,
+        Limits {
+            result_rows: 2,
+            ..Limits::default()
+        },
+    );
+    let result = query(
+        &snapshot,
+        "links.arcadia",
+        reference_offset(&fixture),
+        Action::References,
+    );
+    assert_eq!((result.total_definitions, result.total_references), (1, 2));
+    assert_eq!(
+        (
+            result.definitions.len(),
+            result.references.len(),
+            result.omitted_references
+        ),
+        (1, 1, 1)
+    );
+    let zero = fixture.snapshot(
+        Some(&fixture),
+        true,
+        Limits {
+            result_rows: 0,
+            ..Limits::default()
+        },
+    );
+    let result = query(
+        &zero,
+        "links.arcadia",
+        reference_offset(&fixture),
+        Action::Definition,
+    );
+    assert_eq!(
+        (
+            result.definitions.len(),
+            result.total_definitions,
+            result.omitted_definitions
+        ),
+        (0, 1, 1)
+    );
+    assert_eq!(result.disposition, Disposition::Choices);
+    let envelope = fixture.snapshot(
+        Some(&fixture),
+        true,
+        Limits {
+            result_bytes: 0,
+            ..Limits::default()
+        },
+    );
+    assert_eq!(
+        envelope.query(Query {
+            stamp: QueryStamp {
+                snapshot: key(1),
+                serial: 1
+            },
+            path: "links.arcadia",
+            byte_offset: reference_offset(&fixture),
+            action: Action::Definition
+        }),
+        Err(QueryError::ResultEnvelopeLimit)
+    );
+}
+
+#[test]
+fn large_display_name_cannot_escape_the_owned_row_string_budget() {
+    let mut fixture = Fixture::standard();
+    *fixture.text_mut("模块/活動.arcadia") = fixture
+        .text("模块/活動.arcadia")
+        .replace("泵 🚀", &"長".repeat(8192));
+    let original = fixture.files.clone();
+    let snapshot = fixture.snapshot(
+        None,
+        true,
+        Limits {
+            result_bytes: 64,
+            ..Limits::default()
+        },
+    );
+    let result = query(
+        &snapshot,
+        "links.arcadia",
+        reference_offset(&fixture),
+        Action::Definition,
+    );
+    assert_eq!(
+        (result.total_definitions, result.omitted_definitions),
+        (1, 1)
+    );
+    assert!(result.definitions.is_empty());
+    assert_eq!(result.disposition, Disposition::Choices);
+    assert_eq!(fixture.files, original);
+}
+
+#[test]
+fn validation_witness_must_match_entry_and_complete_included_file_set() {
+    let fixture = Fixture::standard();
+    for mutation in 0..3 {
+        let mut witness = fixture.clone();
+        match mutation {
+            0 => witness.entry = "other.arcadia".into(),
+            1 => {
+                witness.files.pop();
+            }
+            _ => witness.files.push(("unused.arcadia".into(), String::new())),
+        }
+        let snapshot = fixture.snapshot(Some(&witness), true, Limits::default());
+        assert!(snapshot.scope().closure_complete);
+        assert!(!snapshot.scope().validated);
+        assert_eq!(
+            query(
+                &snapshot,
+                "links.arcadia",
+                reference_offset(&fixture),
+                Action::Definition
+            )
+            .disposition,
+            Disposition::Choices
+        );
+    }
+}
+
+#[test]
+fn raw_aggregate_limits_refuse_before_outline_or_copied_snapshot() {
+    // Token budget zero and malformed paths/text would fail later. Raw byte/path
+    // limits must win, including a large second file; no partial Snapshot exists.
+    let large = "not a model \0".repeat(16_384);
+    let files = [
+        DraftFile {
+            path: "../bad.arcadia",
+            text: "?",
+        },
+        DraftFile {
+            path: "large.arcadia",
+            text: &large,
+        },
+    ];
+    let input = Input {
+        key: key(1),
+        entry: "project.arcadia",
+        files: &files,
+        applied: true,
+        validation: None,
+    };
+    for (resource, files_limit, bytes_limit, paths_limit) in [
+        (symbols::Resource::Files, 1, usize::MAX, usize::MAX),
+        (symbols::Resource::SourceBytes, 8, 1, usize::MAX),
+        (symbols::Resource::PathBytes, 8, usize::MAX, 1),
+    ] {
+        let limits = Limits {
+            index: symbols::Limits {
+                files: files_limit,
+                source_bytes: bytes_limit,
+                path_bytes: paths_limit,
+                tokens: 0,
+                records: 0,
+            },
+            ..Limits::default()
+        };
+        assert!(
+            matches!(capture(input, limits), Err(AdmissionError::Index(symbols::BuildError::Limit { resource: actual, .. })) if actual == resource)
+        );
+    }
+    assert_eq!(files[1].text, large);
+}
+
+#[test]
+fn token_declaration_and_live_reference_limits_are_aggregate_not_per_file() {
+    let files = [
+        DraftFile {
+            path: "a.arcadia",
+            text: "oa_activity a \"A\" {}",
+        },
+        DraftFile {
+            path: "b.arcadia",
+            text: "oa_activity b \"B\" {}",
+        },
+    ];
+    let input = Input {
+        key: key(1),
+        entry: "a.arcadia",
+        files: &files,
+        applied: false,
+        validation: None,
+    };
+    let limits = Limits {
+        index: symbols::Limits {
+            tokens: 10,
+            ..Limits::default().index
+        },
+        ..Limits::default()
+    };
+    assert!(matches!(
+        capture(input, limits),
+        Err(AdmissionError::Outline {
+            file: 1,
+            error: language::OutlineLimit {
+                resource: language::OutlineResource::Tokens,
+                ..
+            }
+        })
+    ));
+    let limits = Limits {
+        index: symbols::Limits {
+            records: 1,
+            ..Limits::default().index
+        },
+        ..Limits::default()
+    };
+    assert!(matches!(
+        capture(input, limits),
+        Err(AdmissionError::Outline {
+            file: 1,
+            error: language::OutlineLimit {
+                resource: language::OutlineResource::Declarations,
+                ..
+            }
+        })
+    ));
+    let use_files = [
+        files[0],
+        DraftFile {
+            path: "uses.arcadia",
+            text: "source @a; target @a; // @a ignored\n",
+        },
+    ];
+    let limits = Limits {
+        index: symbols::Limits {
+            records: 2,
+            ..Limits::default().index
+        },
+        ..Limits::default()
+    };
+    assert!(matches!(
+        capture(
+            Input {
+                files: &use_files,
+                ..input
+            },
+            limits
+        ),
+        Err(AdmissionError::Index(symbols::BuildError::Limit {
+            resource: symbols::Resource::Records,
+            observed_at_least: 3,
+            ..
+        }))
+    ));
+}
+
+#[test]
+fn missing_and_noncanonical_authored_ids_remain_draft_spans_without_generated_anchors() {
+    let fixture = Fixture::standard();
+    for replacement in [
+        String::new(),
+        " id \"00000000000000000000000000000002\"".into(),
+    ] {
+        let mut draft = fixture.clone();
+        let original_id = format!(" id \"{PUMP}\"");
+        *draft.text_mut("模块/活動.arcadia") = draft
+            .text("模块/活動.arcadia")
+            .replace(&original_id, &replacement);
+        draft
+            .text_mut("模块/活動.arcadia")
+            .push_str(&format!("// Historical UUID {PUMP} and @pump\r\n"));
+        let before = draft.files.clone();
+        let snapshot = draft.snapshot(None, false, Limits::default());
+        let result = query(
+            &snapshot,
+            "links.arcadia",
+            reference_offset(&draft),
+            Action::Definition,
+        );
+        assert_eq!(result.definitions[0].declaration.authored_id, None);
+        assert_eq!(
+            result.definitions[0].declaration.identity,
+            Identity::Missing
+        );
+        assert_eq!(result.disposition, Disposition::Choices);
+        assert_eq!(draft.files, before);
+        assert_eq!(
+            snapshot.file(1).unwrap().text,
+            draft.text("模块/活動.arcadia")
+        );
+    }
+}
+
+#[test]
+fn keyword_alias_and_loaded_path_case_collisions_use_reviewed_index_rules() {
+    let mut fixture = Fixture::standard();
+    for (_, text) in &mut fixture.files {
+        *text = text.replace("pump", "source");
+    }
+    let snapshot = fixture.snapshot(None, true, Limits::default());
+    let result = query(
+        &snapshot,
+        "links.arcadia",
+        reference_offset(&fixture),
+        Action::Definition,
+    );
+    assert_eq!(result.alias.as_deref(), Some("source"));
+    assert_eq!(result.total_definitions, 1);
+    fixture.files.push(("LINKS.arcadia".into(), String::new()));
+    let files = fixture.borrowed();
+    assert!(matches!(
+        capture(
+            Input {
+                key: key(1),
+                entry: &fixture.entry,
+                files: &files,
+                applied: true,
+                validation: None
+            },
+            Limits::default()
+        ),
+        Err(AdmissionError::Index(symbols::BuildError::Input {
+            problem: symbols::InputProblem::DuplicateOrCaseCollidingPath,
+            ..
+        }))
+    ));
+}
+
+#[test]
+fn owned_request_moves_exact_text_into_worker_snapshot_and_matches_sync_results() {
+    let fixture = Fixture::standard();
+    let files = fixture.borrowed();
+    let input = Input {
+        key: key(1),
+        entry: &fixture.entry,
+        files: &files,
+        applied: true,
+        validation: Some(ValidatedSources {
+            entry: &fixture.entry,
+            files: &files,
+        }),
+    };
+    let owned = admit_owned(input, Limits::default()).unwrap();
+    let allocations: Vec<_> = owned.files.iter().map(|file| file.text.as_ptr()).collect();
+    let snapshot = owned.capture().unwrap();
+    for (file, allocation) in allocations.iter().enumerate() {
+        assert_eq!(
+            snapshot.file(file).unwrap().text.as_ptr(),
+            *allocation,
+            "worker moves the one current-text copy"
+        );
+    }
+    assert!(snapshot.matches(input));
+    let synchronous = capture(input, Limits::default()).unwrap();
+    assert_eq!(
+        query(
+            &snapshot,
+            "links.arcadia",
+            reference_offset(&fixture),
+            Action::References
+        ),
+        query(
+            &synchronous,
+            "links.arcadia",
+            reference_offset(&fixture),
+            Action::References
+        )
+    );
+    let mut edited = fixture.clone();
+    edited
+        .text_mut("links.arcadia")
+        .push_str("// edited after request\r\n");
+    let changed = edited.borrowed();
+    assert!(!snapshot.matches(Input {
+        files: &changed,
+        ..input
+    }));
+    assert!(!snapshot.matches(Input {
+        validation: None,
+        ..input
+    }));
+}
+
+#[test]
+fn owned_request_checks_raw_limits_immediately_and_extracts_only_on_worker() {
+    let fixture = Fixture::standard();
+    let files = fixture.borrowed();
+    let input = Input {
+        key: key(1),
+        entry: &fixture.entry,
+        files: &files,
+        applied: true,
+        validation: None,
+    };
+    let no_tokens = Limits {
+        index: symbols::Limits {
+            tokens: 0,
+            ..Limits::default().index
+        },
+        ..Limits::default()
+    };
+    let owned = admit_owned(input, no_tokens).expect("request admission does not lex or parse");
+    assert!(matches!(
+        owned.capture(),
+        Err(AdmissionError::Outline {
+            file: 0,
+            error: language::OutlineLimit {
+                resource: language::OutlineResource::Tokens,
+                ..
+            }
+        })
+    ));
+    let no_bytes = Limits {
+        index: symbols::Limits {
+            source_bytes: 1,
+            ..Limits::default().index
+        },
+        ..Limits::default()
+    };
+    assert!(matches!(
+        admit_owned(input, no_bytes),
+        Err(AdmissionError::Index(symbols::BuildError::Limit {
+            resource: symbols::Resource::SourceBytes,
+            ..
+        }))
+    ));
+    assert_eq!(files[1].text, fixture.text("模块/活動.arcadia"));
+}
+
+#[test]
+fn owned_validation_proof_preserves_full_witness_count_and_partial_scope() {
+    let accepted = Fixture::standard();
+    for missing_include in [false, true] {
+        let mut current = accepted.clone();
+        current
+            .files
+            .retain(|(path, _)| path != "模块/活動.arcadia");
+        if !missing_include {
+            *current.text_mut("project.arcadia") = current
+                .text("project.arcadia")
+                .replace(" include \"模块/活動.arcadia\";\r\n", "");
+        }
+        let files = current.borrowed();
+        let old = accepted.borrowed();
+        let input = Input {
+            key: key(1),
+            entry: &current.entry,
+            files: &files,
+            applied: true,
+            validation: Some(ValidatedSources {
+                entry: &accepted.entry,
+                files: &old,
+            }),
+        };
+        let snapshot = admit_owned(input, Limits::default())
+            .unwrap()
+            .capture()
+            .unwrap();
+        assert_eq!(snapshot.scope().closure_complete, !missing_include);
+        assert!(
+            !snapshot.scope().validated,
+            "the old witness is not silently reduced to matching loaded files"
+        );
+        let result = query(
+            &snapshot,
+            "links.arcadia",
+            reference_offset(&current),
+            Action::Definition,
+        );
+        assert_eq!(result.disposition, Disposition::NoDefinition);
+        assert!(snapshot.matches(input));
+    }
+}

crates/oa-desktop/src/source_workspace.rs

@@ -1,7 +1,7 @@
 //! Per-file drafts and navigation. Accepted model/source history lives in Document.
 use iced::widget::text_editor::Cursor;
 use oa_core::{
-    language,
+    Id, language,
     source_project::{self, CompiledSourceProject, ProjectLimits, SourceBundle, SourceDiagnostic},
 };
 use std::collections::{BTreeMap, BTreeSet};
@@ -86,6 +86,7 @@ pub struct Buffer {
     pub cursor: Cursor,
     past: Vec<String>,
     future: Vec<String>,
+    generation: u64,
 }
 
 impl Buffer {
@@ -99,14 +100,20 @@ impl Buffer {
             },
             past: Vec::new(),
             future: Vec::new(),
+            generation: 0,
         }
     }
     pub fn dirty(&self) -> bool {
         self.text != self.baseline
     }
+    pub fn generation(&self) -> u64 {
+        self.generation
+    }
 }
 
 pub struct Workspace {
+    session: Id,
+    revision: u64,
     pub entry: String,
     pub active: String,
     pub files: BTreeMap<String, Buffer>,
@@ -117,6 +124,35 @@ pub struct Workspace {
 }
 
 impl Workspace {
+    /// Ephemeral editor identity, never a model identity or recovery payload.
+    pub fn session(&self) -> Id {
+        self.session
+    }
+    pub fn revision(&self) -> u64 {
+        self.revision
+    }
+    fn advance(&mut self) -> u64 {
+        if let Some(revision) = self.revision.checked_add(1) {
+            self.revision = revision;
+        } else {
+            self.reset_navigation_session();
+        }
+        self.revision
+    }
+    /// A changed filesystem root must not reuse queued navigation from Save As.
+    pub fn reset_navigation_session(&mut self) {
+        self.session = Id::new_v4();
+        self.revision = 0;
+        for buffer in self.files.values_mut() {
+            buffer.generation = 0;
+        }
+    }
+    pub fn set_reachable(&mut self, reachable: BTreeSet<String>) {
+        if self.reachable != reachable {
+            self.advance();
+            self.reachable = reachable;
+        }
+    }
     pub fn recovery_snapshot(&self) -> RecoveryWorkspace {
         RecoveryWorkspace {
             entry: self.entry.clone(),
@@ -136,6 +172,8 @@ impl Workspace {
     pub fn from_recovery(saved: RecoveryWorkspace) -> Result<Self, String> {
         saved.validate()?;
         Ok(Self {
+            session: Id::new_v4(),
+            revision: 0,
             entry: saved.entry,
             active: saved.active,
             files: saved
@@ -154,6 +192,8 @@ impl Workspace {
     }
     pub fn new(bundle: &SourceBundle, applied: bool) -> Self {
         Self {
+            session: Id::new_v4(),
+            revision: 0,
             entry: bundle.entry.clone(),
             active: bundle.entry.clone(),
             files: bundle
@@ -191,11 +231,20 @@ impl Workspace {
         }
     }
     pub fn edit(&mut self, text: String, cursor: Cursor) {
+        let changed = self.files.get(&self.active).is_none_or(|b| b.text != text);
+        let generation = if changed {
+            self.advance()
+        } else {
+            self.revision
+        };
         let buffer = self
             .files
             .entry(self.active.clone())
             .or_insert_with(|| Buffer::new(String::new()));
         buffer.cursor = cursor;
+        if changed {
+            buffer.generation = generation;
+        }
         if text != buffer.text {
             buffer.past.push(std::mem::replace(&mut buffer.text, text));
             if buffer.past.len() > 100 {
@@ -268,6 +317,8 @@ impl Workspace {
         } else {
             buffer.future.push(previous);
         }
+        let generation = self.advance();
+        self.files.get_mut(&self.active).unwrap().generation = generation;
         self.trim_history(DRAFT_HISTORY_BYTES);
         true
     }
@@ -281,6 +332,7 @@ impl Workspace {
         }
     }
     pub fn accept(&mut self, bundle: &SourceBundle) {
+        let generation = self.advance();
         if self.entry != bundle.entry
             && !bundle.files.contains_key(&self.entry)
             && self.files.get(&self.entry).is_some_and(|b| !b.dirty())
@@ -291,7 +343,13 @@ impl Workspace {
         self.reachable = bundle.files.keys().cloned().collect();
         for (path, text) in &bundle.files {
             let cursor = self.files.get(path).map(|b| b.cursor);
+            let previous_generation = self
+                .files
+                .get(path)
+                .filter(|b| b.text == *text)
+                .map(|b| b.generation);
             let mut buffer = Buffer::new(text.clone());
+            buffer.generation = previous_generation.unwrap_or(generation);
             if let Some(cursor) = cursor {
                 buffer.cursor = cursor;
             }
@@ -303,10 +361,22 @@ impl Workspace {
         self.applied = true;
     }
     pub fn discovered(&mut self, bundle: &SourceBundle, reachable: BTreeSet<String>) {
+        let changed = self.reachable != reachable
+            || bundle
+                .files
+                .keys()
+                .any(|path| !self.files.contains_key(path));
+        let generation = if changed {
+            self.advance()
+        } else {
+            self.revision
+        };
         for (path, text) in &bundle.files {
-            self.files
-                .entry(path.clone())
-                .or_insert_with(|| Buffer::new(text.clone()));
+            self.files.entry(path.clone()).or_insert_with(|| {
+                let mut buffer = Buffer::new(text.clone());
+                buffer.generation = generation;
+                buffer
+            });
         }
         self.reachable = reachable;
     }
@@ -314,6 +384,7 @@ impl Workspace {
         if self.reachable.contains(path) || self.files.get(path).is_none_or(Buffer::dirty) {
             return false;
         }
+        self.advance();
         self.files.remove(path);
         if self.active == path {
             self.active = self.entry.clone();
@@ -376,6 +447,148 @@ pub fn lint(bundle: &SourceBundle) -> Vec<SourceDiagnostic> {
 mod tests {
     use super::*;
     use oa_core::Project;
+
+    #[test]
+    fn fresh_session_cannot_reuse_a_retained_buffer_generation() {
+        let bundle = SourceBundle {
+            entry: "main.arcadia".into(),
+            files: BTreeMap::from([
+                ("main.arcadia".into(), "first".into()),
+                ("other.arcadia".into(), "other".into()),
+            ]),
+        };
+        let mut workspace = Workspace::new(&bundle, true);
+        let cursor = workspace.files["main.arcadia"].cursor;
+        workspace.edit("second".into(), cursor);
+        workspace.reset_navigation_session();
+        let before = workspace.files["main.arcadia"].generation();
+        workspace.edit("third".into(), cursor);
+        assert_ne!(workspace.files["main.arcadia"].generation(), before);
+        workspace.switch("other.arcadia", cursor);
+        workspace.revision = u64::MAX;
+        workspace.edit("changed other".into(), cursor);
+        let after_wrap = workspace.files["main.arcadia"].generation();
+        workspace.switch("main.arcadia", cursor);
+        workspace.edit("fourth".into(), cursor);
+        assert_ne!(workspace.files["main.arcadia"].generation(), after_wrap);
+        assert!(workspace.undo(false));
+        assert_eq!(workspace.text(), "third");
+    }
+
+    #[test]
+    fn navigation_versions_distinguish_reopened_recovered_and_changed_drafts() {
+        let bundle = SourceBundle {
+            entry: "project.arcadia".into(),
+            files: BTreeMap::from([
+                ("project.arcadia".into(), "entry\r\n".into()),
+                ("part.arcadia".into(), "雨 draft\r\n".into()),
+            ]),
+        };
+        let mut workspace = Workspace::new(&bundle, true);
+        let reopened = Workspace::new(&bundle, true);
+        let recovered = Workspace::from_recovery(workspace.recovery_snapshot()).unwrap();
+        assert_ne!(workspace.session(), reopened.session());
+        assert_ne!(workspace.session(), recovered.session());
+        assert_eq!(workspace.bundle(), recovered.bundle());
+        let saved = serde_json::to_value(workspace.recovery_snapshot()).unwrap();
+        assert!(saved.get("session").is_none() && saved.get("revision").is_none());
+
+        let cursor = Cursor {
+            position: iced::widget::text_editor::Position { line: 0, column: 3 },
+            selection: None,
+        };
+        let revision = workspace.revision();
+        workspace.edit(workspace.text().into(), cursor);
+        assert_eq!(
+            workspace.revision(),
+            revision,
+            "selection is not a text change"
+        );
+        workspace.switch("part.arcadia", cursor);
+        assert_eq!(
+            workspace.revision(),
+            revision,
+            "switching retains the snapshot"
+        );
+        let untouched = workspace.files["project.arcadia"].generation();
+        workspace.edit("雨 unfinished !\r\n".into(), cursor);
+        let edited = workspace.files["part.arcadia"].generation();
+        assert!(workspace.revision() > revision);
+        assert_eq!(workspace.files["project.arcadia"].generation(), untouched);
+        assert!(workspace.undo(false));
+        assert_eq!(workspace.bundle(), bundle);
+        assert!(workspace.files["part.arcadia"].generation() > edited);
+        assert!(workspace.undo(true));
+        assert_eq!(workspace.text(), "雨 unfinished !\r\n");
+        let previous_session = workspace.session();
+        let previous_text = workspace.bundle();
+        workspace.reset_navigation_session();
+        assert_ne!(workspace.session(), previous_session);
+        assert_eq!(workspace.bundle(), previous_text);
+        assert!(
+            workspace.undo(false),
+            "session reset preserves text history"
+        );
+    }
+
+    #[test]
+    fn navigation_scope_changes_invalidate_without_changing_unchanged_positions() {
+        let bundle = SourceBundle {
+            entry: "project.arcadia".into(),
+            files: BTreeMap::from([
+                ("project.arcadia".into(), "entry".into()),
+                ("part.arcadia".into(), "part".into()),
+            ]),
+        };
+        let mut workspace = Workspace::new(&bundle, true);
+        let entry_generation = workspace.files[&bundle.entry].generation();
+        let initial_revision = workspace.revision();
+        workspace.set_reachable(BTreeSet::from([bundle.entry.clone()]));
+        assert!(workspace.revision() > initial_revision);
+        let membership_revision = workspace.revision();
+        workspace.set_reachable(workspace.reachable.clone());
+        assert_eq!(workspace.revision(), membership_revision);
+        assert!(workspace.discard_detached("part.arcadia"));
+        assert!(workspace.revision() > membership_revision);
+        let closed_revision = workspace.revision();
+        workspace.discovered(&bundle, BTreeSet::from([bundle.entry.clone()]));
+        assert!(workspace.revision() > closed_revision);
+        assert_eq!(
+            workspace.files[&bundle.entry].generation(),
+            entry_generation
+        );
+        assert!(workspace.files["part.arcadia"].generation() > closed_revision);
+        let discovered_revision = workspace.revision();
+        workspace.discovered(&bundle, workspace.reachable.clone());
+        assert_eq!(workspace.revision(), discovered_revision);
+        workspace.accept(&bundle);
+        assert!(
+            workspace.revision() > discovered_revision,
+            "validation evidence changed"
+        );
+        assert_eq!(
+            workspace.files[&bundle.entry].generation(),
+            entry_generation
+        );
+        assert_eq!(workspace.bundle(), bundle);
+    }
+
+    #[test]
+    fn navigation_revision_wrap_cannot_reuse_an_old_workspace_key() {
+        let bundle = SourceBundle {
+            entry: "project.arcadia".into(),
+            files: BTreeMap::from([("project.arcadia".into(), "original".into())]),
+        };
+        let mut workspace = Workspace::new(&bundle, true);
+        workspace.revision = u64::MAX;
+        let before = workspace.session();
+        let cursor = workspace.files[&bundle.entry].cursor;
+        workspace.edit("changed".into(), cursor);
+        assert_ne!(workspace.session(), before);
+        assert_eq!(workspace.revision(), 0);
+        assert!(workspace.undo(false));
+        assert_eq!(workspace.bundle(), bundle);
+    }
     #[test]
     fn draft_history_budget_covers_inactive_files_without_discarding_drafts() {
         let bundle = SourceBundle {

crates/oa-desktop/src/tests.rs

@@ -377,7 +377,8 @@ fn source_navigation_waits_for_editor_layout_and_cancels_on_edit() {
     send(&mut app, Message::SourceForSelection);
     assert_eq!(app.page, Page::Text);
     assert!(app.source_jump.is_some());
-    send(&mut app, Message::SourceViewport);
+    let ticket = app.source_reveal_ticket();
+    send(&mut app, Message::SourceViewport(ticket));
     assert!(app.source_jump.is_none());
     send(&mut app, Message::SourceForSelection);
     assert!(app.source_jump.is_some());
@@ -409,7 +410,8 @@ fn source_find_navigates_an_invalid_draft_without_applying_or_losing_it() {
         cursor.selection,
         Some(text_editor::Position { line: 0, column: 9 })
     );
-    send(&mut app, Message::SourceViewport);
+    let ticket = app.source_reveal_ticket();
+    send(&mut app, Message::SourceViewport(ticket));
     assert_eq!(app.source_editor.cursor(), cursor);
     send(
         &mut app,
@@ -1269,7 +1271,9 @@ fn revealing_an_implicit_function_port_unfolds_its_visible_architecture_owner()
         .get_mut(&ancestor)
         .unwrap()
         .collapsed = true;
-    assert!(crate::navigation::diagrams_containing(&p, port).contains(&diagram));
+    // The usage query reports rendered objects; this port's owner is folded.
+    // The legacy authoring reveal below explicitly expands its saved ancestor.
+    assert!(crate::diagram_usage::saved_usages(&p, port).is_empty());
     let mut app = App::with_project(p);
     send(&mut app, Message::RevealInDiagram(diagram, port));
     assert_eq!(app.selected, port);

crates/oa-desktop/src/views.rs

@@ -1,3 +1,4 @@
+mod source_symbols;
 pub(crate) mod traceability;
 use crate::{
     app::{App, Choice, FileOperation, Message, Page, Pending},
@@ -469,10 +470,17 @@ fn diagram(app: &App) -> View<'_, Message> {
         if let Some(editor) = crate::app::architecture_authoring::inline_editor(app) {
             scene = scene.push(editor);
         }
+        let reveal = app.architecture_reveal_stamp(id);
         row![
             widget::sensor(scene)
-                .on_show(Message::CanvasResized)
-                .on_resize(Message::CanvasResized),
+                .on_show(move |size| reveal
+                    .map_or(Message::CanvasResized(size), |(context, epoch)| {
+                        Message::DiagramRevealViewport(context, epoch, size)
+                    }))
+                .on_resize(move |size| reveal
+                    .map_or(Message::CanvasResized(size), |(context, epoch)| {
+                        Message::DiagramRevealViewport(context, epoch, size)
+                    })),
             crate::app::architecture_authoring::palette(app)
         ]
         .height(Fill)
@@ -588,7 +596,7 @@ fn inspector(app: &App) -> View<'_, Message> {
         return container(
             column![
                 tabs,
-                scrollable(crate::navigation::view(p, app.selected)).height(Fill)
+                scrollable(crate::navigation::view(app, app.selected)).height(Fill)
             ]
             .spacing(14),
         )
@@ -1022,7 +1030,7 @@ fn source(app: &App) -> View<'_, Message> {
                 ),
                 action("Next", Message::SourceNavigation(SourceEvent::Next(false))),
                 label(app.source_navigation.label()),
-                action("Close", Message::SourceNavigation(SourceEvent::Close)),
+                action("Close", app.source_find_close_message()),
             ]
             .spacing(6)
             .align_y(iced::Center),
@@ -1116,8 +1124,12 @@ fn source(app: &App) -> View<'_, Message> {
         }
     }
     let editor = widget::text_editor(&app.source_editor)
-        .id("source-editor")
+        .id(app.source_editor_id())
         .on_action(Message::SourceEdit)
+        .key_binding({
+            let context = app.source_symbol_context();
+            move |press| source_binding(press, &context)
+        })
         .font(Font::MONOSPACE)
         .size(14)
         .padding(16)
@@ -1126,8 +1138,7 @@ fn source(app: &App) -> View<'_, Message> {
             app.source_snapshot.clone(),
             crate::highlight::format,
         );
-    column![
-        container(
+    let header = container(
             column![
                 row![
                     container(heading(
@@ -1170,17 +1181,501 @@ fn source(app: &App) -> View<'_, Message> {
                     "Undo text affects this file's draft. Model Undo restores accepted files together (100 changes / about 32 MiB)."
                 }),
                 navigation,
+                row![
+                    action("Definition · F12", app.source_symbol_message(crate::source_navigation::SymbolEvent::Query(crate::source_navigation::query::Action::Definition))),
+                    action("References · Shift F12", app.source_symbol_message(crate::source_navigation::SymbolEvent::Query(crate::source_navigation::query::Action::References))),
+                    action("Show in diagrams…", app.source_symbol_message(crate::source_navigation::SymbolEvent::DiagramUsages)),
+                    button(text("Back · Alt ←").size(12)).padding([8, 10]).style(style::nav)
+                        .on_press_maybe((app.source_symbols.back.iter().any(|entry| entry.session == app.source_workspace.session())).then(|| app.source_symbol_message(crate::source_navigation::SymbolEvent::Back))),
+                ].spacing(7),
                 scrollable(diagnostics)
                     .height((visible_diagnostics as f32 * 32.).min(132.))
             ]
             .spacing(12)
         )
-        .padding(18),
-        widget::sensor(editor).key((app.source_workspace.active.clone(),app.source_jump))
-            .on_show(|_| Message::SourceViewport).on_resize(|_| Message::SourceViewport)
+        .padding(18);
+    let editor = widget::sensor(editor)
+        .key((
+            app.source_workspace.active.clone(),
+            app.source_reveal_ticket(),
+        ))
+        .on_show({
+            let ticket = app.source_reveal_ticket();
+            move |_| Message::SourceViewport(ticket)
+        })
+        .on_resize({
+            let ticket = app.source_reveal_ticket();
+            move |_| Message::SourceViewport(ticket)
+        });
+    let workspace: View<'_, Message> = if app.source_symbols.open {
+        row![
+            container(editor).width(Fill).height(Fill),
+            container(scrollable(source_symbols::panel(app)))
+                .width(300)
+                .height(Fill),
+        ]
+        .height(Fill)
+        .into()
+    } else {
+        container(editor).width(Fill).height(Fill).into()
+    };
+    source_layout(header.into(), workspace, app.window_size.height)
+}
+
+fn source_layout<'a, Renderer: iced::advanced::text::Renderer + 'a>(
+    header: View<'a, Message, iced::Theme, Renderer>,
+    workspace: View<'a, Message, iced::Theme, Renderer>,
+    window_height: f32,
+) -> View<'a, Message, iced::Theme, Renderer> {
+    // Lint clears and repopulates diagnostics asynchronously. Reserve the same
+    // outer slot so a pointer aimed at the editor cannot land in the header.
+    column![
+        container(scrollable(header).id("source-header")).height((window_height * 0.42).max(180.)),
+        workspace,
     ]
+    .height(Fill)
     .into()
 }
+fn source_binding(
+    press: widget::text_editor::KeyPress,
+    context: &crate::source_navigation::SymbolContext,
+) -> Option<widget::text_editor::Binding<Message>> {
+    use crate::source_navigation::{SymbolEvent, query::Action};
+    use iced::keyboard::{Key, key::Named};
+    use widget::text_editor::{Binding, Status};
+    // Windows owns Alt+Space for its window menu. Iced's default binding would
+    // otherwise insert a supplied space payload, even after that menu closes.
+    // Keep Ctrl+Alt (AltGr), shifted input, and ordinary Space unchanged.
+    #[cfg(target_os = "windows")]
+    if matches!(press.status, Status::Focused { .. })
+        && press.modifiers == iced::keyboard::Modifiers::ALT
+        && matches!(
+            press.key.as_ref(),
+            Key::Named(Named::Space) | Key::Character(" ")
+        )
+    {
+        return None;
+    }
+    if matches!(press.status, Status::Focused { .. })
+        && !press.modifiers.control()
+        && !press.modifiers.logo()
+    {
+        let event = match &press.key {
+            Key::Named(Named::F12) if !press.modifiers.alt() => {
+                Some(SymbolEvent::Query(if press.modifiers.shift() {
+                    Action::References
+                } else {
+                    Action::Definition
+                }))
+            }
+            Key::Named(Named::ArrowLeft) if press.modifiers.alt() && !press.modifiers.shift() => {
+                Some(SymbolEvent::Back)
+            }
+            _ => None,
+        };
+        if let Some(event) = event {
+            return Some(Binding::Custom(Message::SourceSymbols(
+                context.clone(),
+                event,
+            )));
+        }
+    }
+    Binding::from_key_press(press)
+}
+
+#[cfg(all(test, debug_assertions))]
+mod source_tests {
+    use super::*;
+    use iced::advanced::{
+        Layout, Shell, graphics, layout, renderer, text as shaped, widget as core_widget,
+    };
+    use iced::widget::column;
+    use iced::{Background, Color, Pixels, Point, Rectangle, Size, Transformation, Vector};
+
+    // Measure real Iced paragraphs/editor text without constructing a window or GPU.
+    struct FontLayout;
+    impl renderer::Renderer for FontLayout {
+        fn start_layer(&mut self, _: Rectangle) {}
+        fn end_layer(&mut self) {}
+        fn start_transformation(&mut self, _: Transformation) {}
+        fn end_transformation(&mut self) {}
+        fn reset(&mut self, _: Rectangle) {}
+        fn fill_quad(&mut self, _: renderer::Quad, _: impl Into<Background>) {}
+        fn allocate_image(
+            &mut self,
+            handle: &iced::advanced::image::Handle,
+            callback: impl FnOnce(
+                Result<iced::advanced::image::Allocation, iced::advanced::image::Error>,
+            ) + Send
+            + 'static,
+        ) {
+            renderer::Renderer::allocate_image(&mut (), handle, callback);
+        }
+    }
+    impl shaped::Renderer for FontLayout {
+        type Font = Font;
+        type Paragraph = graphics::text::Paragraph;
+        type Editor = graphics::text::Editor;
+        const ICON_FONT: Font = Font::DEFAULT;
+        const CHECKMARK_ICON: char = '0';
+        const ARROW_DOWN_ICON: char = '0';
+        const SCROLL_UP_ICON: char = '0';
+        const SCROLL_DOWN_ICON: char = '0';
+        const SCROLL_LEFT_ICON: char = '0';
+        const SCROLL_RIGHT_ICON: char = '0';
+        const ICED_LOGO: char = '0';
+        fn default_font(&self) -> Font {
+            Font::DEFAULT
+        }
+        fn default_size(&self) -> Pixels {
+            Pixels(16.)
+        }
+        fn fill_paragraph(&mut self, _: &Self::Paragraph, _: Point, _: Color, _: Rectangle) {}
+        fn fill_editor(&mut self, _: &Self::Editor, _: Point, _: Color, _: Rectangle) {}
+        fn fill_text(&mut self, _: shaped::Text, _: Point, _: Color, _: Rectangle) {}
+    }
+
+    #[derive(Default)]
+    struct Geometry {
+        header: Option<(Rectangle, Rectangle, Vector)>,
+        editor: Option<Rectangle>,
+    }
+    impl core_widget::Operation for Geometry {
+        fn traverse(&mut self, visit: &mut dyn FnMut(&mut dyn core_widget::Operation)) {
+            visit(self);
+        }
+        fn container(&mut self, id: Option<&core_widget::Id>, bounds: Rectangle) {
+            if id == Some(&core_widget::Id::new("test-source-editor")) {
+                self.editor = Some(bounds);
+            }
+        }
+        fn scrollable(
+            &mut self,
+            id: Option<&core_widget::Id>,
+            bounds: Rectangle,
+            content: Rectangle,
+            offset: Vector,
+            _: &mut dyn core_widget::operation::Scrollable,
+        ) {
+            if id == Some(&core_widget::Id::new("source-header")) {
+                self.header = Some((bounds, content, offset));
+            }
+        }
+    }
+
+    fn mounted_source<'a>(
+        content: &'a widget::text_editor::Content<FontLayout>,
+        diagnostics: usize,
+        find: bool,
+        window_height: f32,
+    ) -> View<'a, Message, iced::Theme, FontLayout> {
+        let mut notices = column![].spacing(5);
+        for index in 0..diagnostics {
+            notices = notices.push(button(text(format!(
+                "救援/assess.arcadia:{}:5 · Warning: verify this participant's engineering allocation", index + 1,
+            )).size(12)).padding([4, 6]).width(Fill));
+        }
+        let find: View<'_, Message, iced::Theme, FontLayout> = if find {
+            column![
+                text_input("Find literal text", "assess").on_input(|s| Message::SourceNavigation(
+                    crate::source_navigation::Event::Query(s)
+                )),
+                text_input("Line", "1").on_input(|s| Message::SourceNavigation(
+                    crate::source_navigation::Event::Line(s)
+                )),
+            ]
+            .spacing(8)
+            .into()
+        } else {
+            Space::new().into()
+        };
+        let header = container(
+            column![
+                text("Textual model").size(24),
+                text("Edit the current file. Apply text validates the complete included model.")
+                    .size(11),
+                row![
+                    button(text("Apply text")),
+                    button(text("Undo text")),
+                    button(text("Model Undo"))
+                ]
+                .spacing(8),
+                text("救援/assess.arcadia · All files applied to the accepted model").size(11),
+                text("Undo text affects this draft. Model Undo restores accepted files together.")
+                    .size(11),
+                find,
+                row![
+                    button(text("Definition · F12")),
+                    button(text("References · Shift F12")),
+                    button(text("Back"))
+                ]
+                .spacing(7),
+                scrollable(notices).height((diagnostics as f32 * 32.).min(132.)),
+            ]
+            .spacing(12),
+        )
+        .padding(18);
+        let editor = container(
+            widget::text_editor(content)
+                .on_action(Message::SourceEdit)
+                .font(Font::MONOSPACE)
+                .size(14)
+                .padding(16)
+                .height(Fill),
+        )
+        .id("test-source-editor")
+        .height(Fill)
+        .width(Fill);
+        source_layout(header.into(), editor.into(), window_height)
+    }
+
+    #[test]
+    fn source_header_keeps_editor_bounds_stable_through_lint_and_find_rebuilds() {
+        for (host, window_height) in [
+            (Size::new(720., 540.), 700.),
+            (Size::new(1180., 890.), 1080.),
+        ] {
+            let content = widget::text_editor::Content::<FontLayout>::with_text(
+                "// is excluded\r\n// 雨\r\n",
+            );
+            let mut tree = core_widget::Tree::empty();
+            let mut baseline = None;
+            for (diagnostics, find) in [
+                (0, false),
+                (6, false),
+                (0, false),
+                (6, true),
+                (1, true),
+                (0, false),
+            ] {
+                let mut ui = mounted_source(&content, diagnostics, find, window_height);
+                tree.diff(ui.as_widget());
+                let node = ui.as_widget_mut().layout(
+                    &mut tree,
+                    &FontLayout,
+                    &layout::Limits::new(Size::ZERO, host),
+                );
+                let mut geometry = Geometry::default();
+                ui.as_widget_mut().operate(
+                    &mut tree,
+                    Layout::new(&node),
+                    &FontLayout,
+                    &mut geometry,
+                );
+                let editor = geometry.editor.unwrap();
+                let (header, _, _) = geometry.header.unwrap();
+                let slot = node.children()[0].bounds();
+                assert_eq!(slot.height, (window_height * 0.42).max(180.));
+                assert!(
+                    header.height <= slot.height,
+                    "short content may shrink inside the fixed slot"
+                );
+                assert!(
+                    editor.height >= 240.,
+                    "remaining editor must stay usable: {editor:?}"
+                );
+                assert_eq!(editor.y, slot.y + slot.height);
+                if let Some(expected) = baseline {
+                    assert_eq!(editor, expected, "diagnostics={diagnostics}, find={find}");
+                } else {
+                    baseline = Some(editor);
+                }
+            }
+        }
+    }
+
+    #[test]
+    fn source_header_remains_scrollable_and_preserves_offset_across_diagnostic_refresh() {
+        let content = widget::text_editor::Content::<FontLayout>::with_text("// 雨\r\n");
+        let host = Size::new(720., 540.);
+        let mut tree = core_widget::Tree::empty();
+        let mut saved = None;
+        for diagnostics in [6, 7] {
+            let mut ui = mounted_source(&content, diagnostics, true, 700.);
+            tree.diff(ui.as_widget());
+            let node = ui.as_widget_mut().layout(
+                &mut tree,
+                &FontLayout,
+                &layout::Limits::new(Size::ZERO, host),
+            );
+            let mut geometry = Geometry::default();
+            ui.as_widget_mut()
+                .operate(&mut tree, Layout::new(&node), &FontLayout, &mut geometry);
+            let (bounds, contents, _) = geometry.header.unwrap();
+            assert!(
+                contents.height > bounds.height,
+                "fixture must actually overflow"
+            );
+            if saved.is_none() {
+                let mut messages = Vec::new();
+                let mut shell = Shell::new(&mut messages);
+                ui.as_widget_mut().update(
+                    &mut tree,
+                    &iced::Event::Mouse(iced::mouse::Event::WheelScrolled {
+                        delta: iced::mouse::ScrollDelta::Pixels { x: 0., y: -45. },
+                    }),
+                    Layout::new(&node),
+                    iced::mouse::Cursor::Available(Point::new(bounds.x + 8., bounds.y + 8.)),
+                    &FontLayout,
+                    &mut iced::advanced::clipboard::Null,
+                    &mut shell,
+                    &Rectangle::with_size(host),
+                );
+                assert!(shell.is_event_captured());
+            }
+            let mut geometry = Geometry::default();
+            ui.as_widget_mut()
+                .operate(&mut tree, Layout::new(&node), &FontLayout, &mut geometry);
+            let offset = geometry.header.unwrap().2;
+            assert!(offset.y > 0., "the actual mounted Scrollable must move");
+            if let Some(before) = saved {
+                assert_eq!(offset, before);
+            } else {
+                saved = Some(offset);
+            }
+        }
+    }
+
+    #[cfg(target_os = "windows")]
+    #[test]
+    fn source_editor_windows_menu_payload_is_inert_but_space_and_altgr_still_edit() {
+        use core_widget::operation::Focusable;
+        use iced::keyboard::{
+            self, Key, Modifiers,
+            key::{Code, Named, Physical},
+        };
+        use widget::text_editor::{Binding, Content, KeyPress, State, Status};
+        let baseline = "// is excluded\r\n// 雨\r\n";
+        let context = crate::source_navigation::SymbolContext {
+            session: Id::new_v4(),
+            path: "救援/assess.arcadia".into(),
+        };
+        for (key, physical_key, modifiers, payload, inserted) in [
+            (
+                Key::Named(Named::Space),
+                Physical::Code(Code::Space),
+                Modifiers::ALT,
+                " ",
+                false,
+            ),
+            (
+                Key::Character(" ".into()),
+                Physical::Code(Code::Space),
+                Modifiers::ALT,
+                " ",
+                false,
+            ),
+            (
+                Key::Named(Named::Space),
+                Physical::Code(Code::Space),
+                Modifiers::empty(),
+                " ",
+                true,
+            ),
+            (
+                Key::Named(Named::Space),
+                Physical::Code(Code::Space),
+                Modifiers::CTRL | Modifiers::ALT,
+                " ",
+                true,
+            ),
+            (
+                Key::Character("e".into()),
+                Physical::Code(Code::KeyE),
+                Modifiers::CTRL | Modifiers::ALT,
+                "€",
+                true,
+            ),
+            (
+                Key::Named(Named::Space),
+                Physical::Code(Code::Space),
+                Modifiers::ALT | Modifiers::SHIFT,
+                " ",
+                true,
+            ),
+        ] {
+            let mut content = Content::<FontLayout>::with_text(baseline);
+            content.move_to(widget::text_editor::Cursor {
+                position: widget::text_editor::Position { line: 0, column: 5 },
+                selection: None,
+            });
+            let press = KeyPress {
+                key: key.clone(),
+                modified_key: key.clone(),
+                physical_key,
+                modifiers,
+                text: Some(payload.into()),
+                status: Status::Focused { is_hovered: false },
+            };
+            assert!(
+                matches!(
+                    Binding::<Message>::from_key_press(press),
+                    Some(Binding::Insert(_))
+                ),
+                "the supplied event must expose the default insertion path"
+            );
+            let mut messages = Vec::new();
+            {
+                let mut editor: View<'_, Message, iced::Theme, FontLayout> =
+                    widget::text_editor(&content)
+                        .on_action(Message::SourceEdit)
+                        .font(Font::MONOSPACE)
+                        .size(14)
+                        .padding(16)
+                        .height(Fill)
+                        .key_binding(|press| source_binding(press, &context))
+                        .into();
+                let mut tree = core_widget::Tree::new(editor.as_widget());
+                let size = Size::new(600., 240.);
+                let node = editor.as_widget_mut().layout(
+                    &mut tree,
+                    &FontLayout,
+                    &layout::Limits::new(Size::ZERO, size),
+                );
+                tree.state
+                    .downcast_mut::<State<shaped::highlighter::PlainText>>()
+                    .focus();
+                let event = iced::Event::Keyboard(keyboard::Event::KeyPressed {
+                    key: key.clone(),
+                    modified_key: key,
+                    physical_key,
+                    location: keyboard::Location::Standard,
+                    modifiers,
+                    text: Some(payload.into()),
+                    repeat: false,
+                });
+                let mut shell = Shell::new(&mut messages);
+                editor.as_widget_mut().update(
+                    &mut tree,
+                    &event,
+                    Layout::new(&node),
+                    iced::mouse::Cursor::Unavailable,
+                    &FontLayout,
+                    &mut iced::advanced::clipboard::Null,
+                    &mut shell,
+                    &Rectangle::with_size(size),
+                );
+            }
+            assert_eq!(
+                messages.len(),
+                usize::from(inserted),
+                "modifiers={modifiers:?}"
+            );
+            for message in messages {
+                let Message::SourceEdit(action) = message else {
+                    panic!("unexpected navigation action");
+                };
+                content.perform(action);
+            }
+            let expected = if inserted {
+                format!("// is{payload} excluded\r\n// 雨\r\n")
+            } else {
+                baseline.into()
+            };
+            assert_eq!(content.text(), expected);
+        }
+    }
+}
 fn checks(app: &App) -> View<'_, Message> {
     let issues = &app.model_issues;
     let mut out = column![heading(

crates/oa-desktop/src/views/source_symbols.rs

@@ -0,0 +1,260 @@
+use crate::{
+    app::{App, Message},
+    source_navigation::{
+        SymbolEvent,
+        query::{self, Declaration, Disposition, Evidence, Identity, Membership, Position},
+    },
+    style,
+};
+use iced::{
+    Element, Fill,
+    widget::{Space, button, column, container, row, scrollable, text, tooltip},
+};
+
+pub(super) fn panel(app: &App) -> Element<'_, Message> {
+    let state = &app.source_symbols;
+    if !state.open
+        || (state.results.is_none() && state.in_flight.is_none() && state.notice.is_none())
+    {
+        return column![].into();
+    }
+    let title = state.results.as_ref().map_or_else(
+        || "Source symbols".to_owned(),
+        |results| {
+            let action = match results.action {
+                query::Action::Definition => "Definitions",
+                query::Action::References => "References",
+            };
+            results.alias.as_ref().map_or_else(
+                || action.to_owned(),
+                |alias| format!("{action} · @{}", preview(alias, 40)),
+            )
+        },
+    );
+    let mut content = column![
+        row![
+            text(title).size(13),
+            Space::new().width(Fill),
+            button(text("Close").size(11))
+                .padding([3, 8])
+                .style(style::nav)
+                .on_press(app.source_symbol_message(SymbolEvent::Close)),
+        ]
+        .align_y(iced::Center)
+    ]
+    .spacing(5);
+
+    if let Some(notice) = &state.notice {
+        content = content.push(super::label(preview(notice, 240)));
+    }
+    if state.in_flight.is_some() {
+        content = content.push(super::label("Finding source symbols…"));
+    } else if let Some(results) = &state.results {
+        let stale = results.stamp.snapshot != app.source_key();
+        if stale {
+            content = content.push(super::label(
+                "Stale results — source changed. Run Definition or References again.",
+            ));
+        }
+        let scope = &results.scope;
+        content = content.push(super::label(format!(
+            "{} · {} · {} included / {} detached / {} unverified files · {} scope issues",
+            if scope.partial() {
+                "Partial scope"
+            } else {
+                "Complete include scope"
+            },
+            if !scope.applied {
+                "Unapplied drafts"
+            } else if scope.validated {
+                "Validated sources"
+            } else {
+                "Draft sources"
+            },
+            scope.included_files,
+            scope.detached_files,
+            scope.unverified_files,
+            scope.issues.len(),
+        )));
+        let explanation = match results.disposition {
+            Disposition::NoSymbol => "Place the caret on a declaration alias or an @reference.",
+            Disposition::NoDefinition => "No matching declaration in the loaded sources.",
+            Disposition::Choices => {
+                "Choose a declaration; draft and detached candidates need an explicit choice."
+            }
+            Disposition::Direct => "Definition in the current sources.",
+            Disposition::LexicalReferences => {
+                "Lexical uses of this alias; these do not establish a semantic target."
+            }
+        };
+        content = content.push(super::label(explanation));
+        if results.total_definitions > 1 {
+            content = content.push(super::label(format!(
+                "Alias collision: {} declarations. Uses are not attributed to a single declaration.",
+                results.total_definitions,
+            )));
+        }
+        let enabled = !stale && !app.busy;
+        let mut rows = column![super::label(counts(
+            "Declarations",
+            results.definitions.len(),
+            results.total_definitions,
+            results.omitted_definitions,
+        ))]
+        .spacing(4);
+        for (index, definition) in results.definitions.iter().enumerate() {
+            rows = rows.push(location_row(
+                declaration_title(&definition.declaration),
+                &definition.path,
+                definition.position,
+                provenance(
+                    definition.membership,
+                    definition.evidence,
+                    definition.declaration.identity,
+                    false,
+                ),
+                enabled.then(|| {
+                    app.source_symbol_message(SymbolEvent::Choose {
+                        stamp: results.stamp,
+                        reference: false,
+                        index,
+                    })
+                }),
+            ));
+        }
+        rows = rows.push(super::label(counts(
+            "Lexical uses",
+            results.references.len(),
+            results.total_references,
+            results.omitted_references,
+        )));
+        for (index, reference) in results.references.iter().enumerate() {
+            let title = reference.context.as_ref().map_or_else(
+                || format!("@{} · lexical use", preview(&reference.alias, 48)),
+                |context| {
+                    format!(
+                        "@{} · inside {}",
+                        preview(&reference.alias, 48),
+                        declaration_title(context)
+                    )
+                },
+            );
+            rows = rows.push(location_row(
+                title,
+                &reference.path,
+                reference.position,
+                provenance(
+                    reference.membership,
+                    reference.evidence,
+                    reference
+                        .context
+                        .as_ref()
+                        .map_or(Identity::Missing, |context| context.identity),
+                    true,
+                ),
+                enabled.then(|| {
+                    app.source_symbol_message(SymbolEvent::Choose {
+                        stamp: results.stamp,
+                        reference: true,
+                        index,
+                    })
+                }),
+            ));
+        }
+        let row_count = results.definitions.len() + results.references.len();
+        content =
+            content.push(scrollable(rows).height((44.0 + row_count as f32 * 48.0).min(180.0)));
+    }
+    container(content)
+        .padding(8)
+        .width(Fill)
+        .style(style::subtle)
+        .into()
+}
+
+fn counts(label: &str, shown: usize, total: usize, omitted: usize) -> String {
+    format!("{label}: {total} total · {shown} shown · {omitted} omitted")
+}
+
+fn declaration_title(declaration: &Declaration) -> String {
+    let name = declaration
+        .name
+        .as_ref()
+        .map_or_else(String::new, |name| format!(" \"{}\"", preview(name, 48)));
+    format!(
+        "{}{} · @{}",
+        preview(&declaration.kind, 24),
+        name,
+        preview(&declaration.alias, 48)
+    )
+}
+
+fn provenance(
+    membership: Membership,
+    evidence: Evidence,
+    identity: Identity,
+    context: bool,
+) -> String {
+    let membership = match membership {
+        Membership::Included => "Included",
+        Membership::Detached => "Detached",
+        Membership::Unverified => "Unverified",
+    };
+    let evidence = match evidence {
+        Evidence::Validated => "Validated",
+        Evidence::Draft => "Draft",
+    };
+    let collision = match identity {
+        Identity::Collision { count } => format!(
+            " · {}ID collision ({count})",
+            if context { "Context " } else { "" },
+        ),
+        Identity::Missing | Identity::Unique(_) => String::new(),
+    };
+    format!("{membership} · {evidence}{collision}")
+}
+
+fn location_row(
+    title: String,
+    path: &str,
+    position: Position,
+    status: String,
+    event: Option<Message>,
+) -> Element<'static, Message> {
+    let line = position.line.saturating_add(1);
+    let column = position.byte_column.saturating_add(1);
+    let location = format!("{}:{line}:{column}", preview(path, 72));
+    tooltip(
+        button(
+            column![
+                text(title).size(12),
+                super::label(format!("{location} · {status}"))
+            ]
+            .spacing(2),
+        )
+        .padding([4, 6])
+        .width(Fill)
+        .style(style::nav)
+        .on_press_maybe(event),
+        text(format!(
+            "{path}:{line}:{column} (1-based line and UTF-8 byte column)"
+        ))
+        .size(11),
+        tooltip::Position::Top,
+    )
+    .into()
+}
+
+/// Keep headings compact without copying the remainder of a long admitted value.
+fn preview(value: &str, limit: usize) -> String {
+    let mut chars = value.chars();
+    let mut result: String = chars
+        .by_ref()
+        .take(limit)
+        .map(|ch| if ch.is_whitespace() { ' ' } else { ch })
+        .collect();
+    if chars.next().is_some() {
+        result.push('…');
+    }
+    result
+}

docs/diagram-navigation.rst

@@ -0,0 +1,106 @@
+Diagram representation navigation
+=================================
+
+This contract derives from user issues `14: Text symbol usages
+<http://217.177.34.108:3000/sorokin.oleg.edu/ARCADIA-Studio/issues/14>`_
+and `17: tree-to-diagram navigation
+<http://217.177.34.108:3000/sorokin.oleg.edu/ARCADIA-Studio/issues/17>`_.
+Implementation and acceptance status belong to those issues. The source language
+and identity rules remain in ``language.rst``.
+
+Identity and membership
+-----------------------
+
+A result identifies the queried subject, a diagram destination, and a specific
+graphical representation. A destination is a saved diagram UUID, a process or
+functional-chain UUID, or a scenario UUID. Saved state diagrams retain their own
+diagram UUID; membership in the same state machine does not make their contents
+interchangeable.
+
+Representation identities are node placement, port plus owner placement, edge,
+state row plus owner placement, process occurrence plus qualified reference path,
+process link, or scenario lifeline/occurrence. Opening an owner itself is a
+separate whole-diagram target. Names and aliases describe these identities; they
+are never replacement identities. Repeated occurrences remain independently
+selectable even when they represent the same activity or exchange.
+
+The current renderer determines membership:
+
+* Saved node, port, and edge results come from the final projection, including
+  folds, projection-kind rules, and view filters. A stored route or two placed
+  endpoints does not establish a visible edge.
+* Process results use the displayed contribution graph. A contextual preview
+  retains its full caller path and is included only while its actual tile is
+  present. An inactive process uses the same initial preview policy as entering
+  its canvas. Preview adjacency has no invented relation UUID.
+* Scenario results use the actual scene, preserving lifeline and message
+  occurrence identities, nested fragment operands, and repeated messages.
+  A scenario-reference box represents its called scenario. It does not also
+  represent the called scenario's messages or lifelines.
+* State action and internal-transition rows retain their relation identity.
+  Visible named references, such as a state action's work or a transition's
+  trigger, can target the row or edge whose label displays that reference.
+  Label-only membership must account for the renderer's shortening policy.
+
+An arbitrary semantic reference is insufficient. A description mentioning a
+name, an exchange item hidden by the selected label mode, or an unexpanded callee
+does not automatically add a diagram result. The result count describes
+currently rendered representations, not all semantic dependencies. Folded,
+filtered, and unexpanded representations are explicitly excluded by this version;
+an empty result must disclose this scope and must not claim that an object is
+unused everywhere. Semantic dependencies remain available through Connections.
+
+Two additional representation forms remain gaps in this branch: allocation
+relations expressed through nesting, and persisted sequence links drawn inside
+qualified caller previews. These must either receive precise grouping/qualified
+edge targets or remain explicitly disclosed limitations; a passing direct-edge
+test does not establish their coverage.
+
+Interaction and lifecycle
+-------------------------
+
+``Show in diagrams`` opens one searchable destination list from the Text caret,
+an object's context/Actions menu, or Connections. It identifies the subject by
+name and alias, groups targets by destination, reports counts, and presents a
+bounded page. A destination then exposes its individual representations. Search
+matches destination names, aliases, categories, representation names, and roles.
+Long descriptions remain available without replacing stable identities.
+
+The Text entry point uses the exact current caret and the source-symbol service's
+immutable snapshot. It requires a unique, validated, included declaration whose
+authored identity and alias still match the accepted model. It never substitutes
+the previously selected tree object. Unapplied source is retained with an explicit
+instruction to apply it before diagram lookup. Comment, prose, ambiguous, missing,
+detached, and stale symbols cannot trigger a diagram jump.
+
+Every open request captures the document instance, accepted revision, and subject.
+Every chooser action captures that chooser's unique token. Before opening a
+representation, re-resolve the full subject-to-target relationship and renderer
+geometry. If the model or presentation changed, refresh the list and require a
+fresh choice. Matching names, reused aliases, or surviving endpoints cannot make
+a stale target current. An asynchronous source response must also match its job,
+source session/revision, raw interaction, active file, and caret.
+
+Lookup and reveal do not execute model commands, Apply, Revert, or Save. They do
+not expand persisted folds, change filters, rewrite source, or alter undo/redo.
+Pending edits that would be displaced prevent the jump and remain intact.
+Successful reveal updates only the navigation owner/page, precise selection,
+tool lifetime, and camera. The camera centers the target at a readable scale;
+fitting a huge whole diagram is not sufficient evidence of locating one object.
+Escape closes the chooser and restores Text focus/caret when invoked there.
+
+Verification obligations
+------------------------
+
+Independent fixtures must cover actual versus filtered edges, folded children,
+ports, same-name distinct identities, repeated work/message/lifeline occurrences,
+qualified reuse paths, opaque scenario references, state rows and label references.
+For each activation, compare the complete accepted Project, SourceBundle, raw
+buffers, revision, dirty flags, and undo/redo reachability before and after.
+Exercise stale document/revision/token/subject relationships and retained drafts.
+
+Native acceptance additionally checks keyboard and pointer selection, exact
+visible target highlight, camera behavior after the destination's first layout,
+empty and multi-result states, readable long Unicode names, minimum-window layout,
+return to editing, and representative large-model latency. Unit tests and a
+successful build do not by themselves establish these interaction outcomes.

docs/language.html

@@ -2642,6 +2642,23 @@ trace links, occurrence identity, comments and file ownership. Each open file
 retains its own unapplied draft across file navigation. Located lint diagnostics
 refer to the raw draft bytes rather than an identity-stabilized intermediate.
 Property editing MUST NOT silently discard a pending source draft.</p>
+<p>In Textual model, place the caret on a declaration alias or an <span class="docutils literal">&#64;reference</span>
+and choose <strong>Definition</strong> (<span class="docutils literal">F12</span>) or <strong>References</strong> (<span class="docutils literal">Shift+F12</span>).
+<strong>Back</strong> (<span class="docutils literal">Alt+Left</span>) returns to the previous source location in this
+workspace. These shortcuts act while the source editor has focus; the Text
+toolbar also exposes the actions. If the previous draft changed, Back restores
+its current cursor rather than reusing an obsolete selection.</p>
+<p>Symbol navigation reads bounded snapshots of the currently loaded source
+drafts. It does not apply drafts or load missing included files. The results
+identify partial scope, draft evidence, detached or unverified files, alias
+ambiguity and authored-ID collisions. Draft, detached and ambiguous definition
+candidates require an explicit row choice. References are lexical uses of an
+alias, not a list of resolved typed relationships; comments and strings are
+excluded. Declaration and use counts include any rows omitted by the result
+limits. If sources change, stale rows cannot navigate: run the query again.
+Navigation MUST preserve the accepted model and every source draft, and select
+locations in the original UTF-8 bytes. Displayed locations use one-based lines
+and UTF-8 byte columns.</p>
 <p>Changing a graphical UUID must atomically update map keys and every reference.
 Alias changes preserve UUID identity. Deletion must account for owned elements,
 incident relationships, ordered occurrences, and diagram placements without

docs/language.rst

@@ -2064,6 +2064,25 @@ retains its own unapplied draft across file navigation. Located lint diagnostics
 refer to the raw draft bytes rather than an identity-stabilized intermediate.
 Property editing MUST NOT silently discard a pending source draft.
 
+In Textual model, place the caret on a declaration alias or an ``@reference``
+and choose **Definition** (``F12``) or **References** (``Shift+F12``).
+**Back** (``Alt+Left``) returns to the previous source location in this
+workspace. These shortcuts act while the source editor has focus; the Text
+toolbar also exposes the actions. If the previous draft changed, Back restores
+its current cursor rather than reusing an obsolete selection.
+
+Symbol navigation reads bounded snapshots of the currently loaded source
+drafts. It does not apply drafts or load missing included files. The results
+identify partial scope, draft evidence, detached or unverified files, alias
+ambiguity and authored-ID collisions. Draft, detached and ambiguous definition
+candidates require an explicit row choice. References are lexical uses of an
+alias, not a list of resolved typed relationships; comments and strings are
+excluded. Declaration and use counts include any rows omitted by the result
+limits. If sources change, stale rows cannot navigate: run the query again.
+Navigation MUST preserve the accepted model and every source draft, and select
+locations in the original UTF-8 bytes. Displayed locations use one-based lines
+and UTF-8 byte columns.
+
 Changing a graphical UUID must atomically update map keys and every reference.
 Alias changes preserve UUID identity. Deletion must account for owned elements,
 incident relationships, ordered occurrences, and diagram placements without

harness/DECISIONS.md

@@ -346,3 +346,37 @@ regressions; it does not broaden admission or add a new rule. Compilation and
 native acceptance of the renderer are still pending at this decision. Revisit the
 visual encoding if actual minimum-size engineering workflows make marker identity,
 uncertain continuation or the distinction between guide and existence unclear.
+
+## Diagram representation navigation — 2026-09-12
+
+Codex-ytr83r /root. User issues [14](http://217.177.34.108:3000/sorokin.oleg.edu/ARCADIA-Studio/issues/14)
+and [17](http://217.177.34.108:3000/sorokin.oleg.edu/ARCADIA-Studio/issues/17)
+share one typed query and destination chooser; the [contract](../docs/diagram-navigation.rst)
+defines identity, visible membership, source freshness and nonmutation. A result
+retains its representation identity separately from its queried semantic subject.
+Use the actual saved projection, process Graph, scenario Scene and state row
+geometry. Repeated occurrences and qualified reuse paths remain distinct.
+
+Reject endpoint-only membership and generic semantic-reference enumeration:
+they admit suppressed edges and opaque callee contents while missing behavioral
+occurrences and state rows. Reject a destination submenu containing every use or
+always-visible per-line lenses: both add noise and scale poorly for the user's
+editing workflow. An explicitly invoked, searchable chooser groups destinations
+and exposes their occurrences on demand. Independent design work identified
+minimum-window, repeated-name, source-caret, stale-result and full-history oracles
+before implementation; passing those evaluators remains necessary for acceptance.
+
+Ordinary navigation must not reuse the legacy reveal action's implicit Apply and
+persisted fold expansion. Resolve the exact target before changing presentation;
+center that target at readable scale. This first implementation lists currently
+rendered representations and explicitly discloses folded/filtered/unexpanded
+exclusions. It does not claim complete authored-membership discovery. Revisit
+transient hidden-object reveal after measured user workflows; adding a result
+must never imply an invisible object was actually shown or silently edit a view.
+
+The Text entry point builds on delivered source navigation from33c6d83, including
+eeeaa12 native corrections, while preserving the later canvas/chooser/repair
+integration. It requires verified applied-source identity and never substitutes
+model selection for the caret. Dirty-source semantic lookup remains a disclosed
+limitation. Implementation is branch-specific at this decision; Windows build,
+combined tests and native acceptance are not established by this record.

harness/experiments/behavior-navigation-review-20260912/README.md

@@ -0,0 +1,13 @@
+# In-progress navigation source and behavior editing reviews
+
+This commit makes the reviewed source and reports available to sessions on other machines. Local `.local` paths in prior issue comments were inaccessible handoffs; use these versioned files and their relative source links.
+
+The source was copied from the 561-input frozen Windows test snapshot on branch `codex/diagram-usages-ytr83r-20260912`, based on `7aa007b0777aa182a99f46e90eeb9b2558f3ad2a`. Every copied input was SHA-256 verified against the pre-gate capture. This is unaccepted work in progress: the desktop test binary is still compiling at publication preparation, no final tests/lint/native pass is claimed, and known navigation selection/coverage corrections remain. The reports are proposals and independent source reviews, not acceptance results. Linux/WSL remains deferred.
+
+- [Nested activation review for issue21](issue21-activation-analysis-20260912.md): peer956 retains implementation ownership.
+- [Free behavior canvas proposal](free-behavior-canvas-design-20260912.md).
+- [Independent canvas design critique](free-behavior-canvas-critique-20260912.md).
+- [Remaining navigation coverage and selection review](diagram-navigation-remaining-coverage-20260912.md).
+- [Frozen source input manifest](frozen-inputs.json).
+
+The experiment, reviews, source paths, and runtime evidence from this machine must be published before they are used as cross-machine handoffs. In-thread delegated agents share the local workspace; independently running Gitea peers do not. Live ownership, plans, and results remain in Gitea issues.

harness/experiments/behavior-navigation-review-20260912/diagram-navigation-remaining-coverage-20260912.md

@@ -0,0 +1,93 @@
+# Remaining diagram navigation coverage: verified correction seams
+
+Read-only review, 2026-09-12. Scope: #14/#17 in `.local/diagram-usages-ytr83r-20260912`; current frozen, uncommitted working sources, not a release acceptance claim. No production changes, compilation, tests, UI interaction, or Gitea writes were performed by this review. Root owns integration and verification. Paths below are relative to that worktree.
+
+## Decision
+
+Both gaps are actual representations omitted by the current query. Preserve the current render/projection rules, and add explicit target identities plus presentation highlighting. A caller-preview arrow is not identified by the underlying relation ID alone. An allocation grouping's selected semantic object must remain the Allocation relation, independently of the work placement used for focus/highlight.
+
+Issue requirements: [#14](http://217.177.34.108:3000/sorokin.oleg.edu/ARCADIA-Studio/issues/14) requests textual-symbol diagram references and jumps to the corresponding element; [#17](http://217.177.34.108:3000/sorokin.oleg.edu/ARCADIA-Studio/issues/17) requests equivalent tree navigation. Peer boundaries were read directly in [#3 comment 616](http://217.177.34.108:3000/sorokin.oleg.edu/ARCADIA-Studio/issues/3#issuecomment-616) and [comment 627](http://217.177.34.108:3000/sorokin.oleg.edu/ARCADIA-Studio/issues/3#issuecomment-627). Peer confirms the direct-relation/visible-ancestor predicate below, requires separate semantic versus placement identity for Delete, and requires retiring gesture/context lifetimes even for equal-valued navigation. Peer test evidence is not evidence for this worktree.
+
+## A. SequenceLink arrows in caller previews
+
+### Verified representation
+
+- `crates/oa-desktop/src/behavior/topology.rs:904`: `sequence_links` returns actual SequenceLink relations whose two contributions belong to the requested process/chain.
+- `topology.rs:914` (`GraphNode`), especially `:922`: `preview_links` stores only `(OccurrenceEndpoint, OccurrenceEndpoint)`. The relation ID is lost, unlike `GraphEdge.id` at `:942`.
+- `topology.rs:1094` and `:1128`: each SequenceReference obtains the same bounded qualified preview tiles used by painting, then includes the reused definition's links only when both exact endpoints with `references = [caller_reference_id]` occur in the visible preview set. The normal bound is four tiles; expanded references allow 512. It does not add arrows for every deeper nested definition merely because nested tiles have been expanded.
+- `crates/oa-desktop/src/behavior/topology/contextual.rs:253`: preview traversal resolves qualified endpoints through `TopologyIndex`; it preserves each caller path and applies the visibility limit.
+- `topology.rs:1568`: the painter draws every retained preview link from the source tile's right center to the target tile's left center. Tile rectangles are then painted opaquely at `:1581`. Therefore the arrow's visible portion can be smaller than its raw line segment. These are real painted arrows, distinct from `Graph.ordered_paths`, whose explicit contract says they are projected adjacency without persisted relation IDs.
+- `topology.rs:926`: `endpoint_rect` has a whole-reference proxy fallback. A usages query must continue rejecting that fallback, as existing `usages.rs:81` does for qualified tiles.
+- `crates/oa-desktop/src/behavior/topology/usages.rs:89` and `:123`: current relation lookup considers `graph.edges`; it never scans `node.preview_links`. Thus a real caller arrow is absent even when the same relation has a normal link usage on its definition surface.
+- `crates/oa-desktop/src/behavior/topology/direct.rs:540`: edge hit testing is also restricted to `Graph.edges`. `:105` and `:111` implement occurrence context, not qualified relation selection. `topology/view.rs:179` copies that occurrence context into `graph.selected_preview`; `topology.rs:1583` highlights tiles with it. Reusing that context to mean an edge would conflate authoring semantics.
+- `crates/oa-core/src/validation.rs:2437` forbids SequenceLink self endpoints; `:2453` requires contributions directly owned by the same process/chain. Navigation should nevertheless reject missing/degenerate geometry, rather than using an enclosing box fallback.
+
+### Minimal correction
+
+1. Replace the preview endpoint pair with a small record retaining actual relation ID and the same two qualified endpoints. Populate it from the existing filtered relation loop. Do not add traversal, widen preview limits, or change which arrows are painted.
+2. Add a target such as `ProcessPreviewLink { relation, source: OccurrenceEndpoint, target: OccurrenceEndpoint }`. The enclosing `Surface::Process(owner)` plus these fields distinguishes repeated caller instances, parallel relations, and retargeting. The existing unqualified `ProcessLink(Id)` remains appropriate for normal graph edges.
+3. Share the record's exact arrow geometry between painting and usages. A midpoint of the raw segment may fall under an opaque tile; use a visible segment/gap for focus. A small helper can subtract the preview tile rectangles from the straight segment and choose a remaining segment. Require some visible nondegenerate geometry; never manufacture a row from endpoint membership alone when no arrow is emitted. This helper may be tested without changing routing or the visual layout.
+4. Query the actual retained records, with `subject == record.relation`. The chooser label must include the caller path, and its role should distinguish a preview sequence link. Do not emit links for ordered-path adjacency, arbitrary nested source links, or referenced work merely because it is an endpoint.
+5. Add dedicated transient preview-link presentation selection, then paint exactly that record with a selected stroke. Keep `App.selected = relation`, and clear occurrence selection for this target. Do not put an edge into `selected_context`, which is validated as an occurrence and feeds contribution operations. New canvas authoring/hit-test behavior is not necessary for the navigation fix.
+6. Revalidation uses the existing one-surface query and exact target equality. Both endpoints must still resolve and the same record must still be emitted under the current expansion snapshot. Reopening after a changed accepted revision may refresh; the stale Choose event must not jump. Existing asynchronous snapshot behavior remains sufficient: no draft, camera, or selection state needs to cross the worker boundary.
+
+### Independent expectations
+
+- A definition's link rendered in two caller invocations yields two distinct caller targets plus its normal definition target. Choosing either keeps semantic selection equal to the relation ID while highlighting and centering the correct qualified arrow.
+- A link touching the fifth hidden tile has no default caller row. Expanding only the first invocation adds that invocation's arrow, not its sibling's. Collapsing or retargeting invalidates the old target.
+- Deeper expanded tiles alone do not cause usages for deeper links that the existing painter never emits. Ordered adjacency without an actual SequenceLink remains absent.
+- Parallel relations retain distinct relation identities even if current preview geometry overlaps. Reverse/cross-row links focus a visible line segment, not an opaque tile interior.
+- Update `topology/usages/tests.rs`'s current `process_contextual_purpose_is_a_visible_reference_but_preview_arrows_are_not_links` expectation specifically for retained preview records; preserve its exclusion of other unrepresented links.
+- Exercise actual App update with open/completion/choose, old token/revision/document, reference retargeting, modal/draft protection, repeat choice, and preserved Project/SourceBundle/revision/dirty/history. Assert exact qualified selection and bounds, not merely that the destination page opened.
+
+## B. Allocation relations represented by grouping
+
+### Verified representation
+
+- `crates/oa-core/src/projection.rs:81`, `parents`: Allocation projection computes actual placement parents using the effective allocation summary and nearest placed coherent work ancestors, with performer fallback. This is visual containment, separate from semantic ownership.
+- `projection.rs:274` projects compatible placed nodes. Around `:300`, a collapsed ancestor or cycle prevents a descendant from entering visible `view.nodes`. Around `:331`, the resulting node records `visual_parent`; `:350` encloses containers with projected header geometry.
+- `projection.rs:393`: Allocation relations are intentionally suppressed as arrows in Allocation projection. Looking only at projected edges cannot find their grouping representation.
+- `projection.rs:331` and `crates/oa-core/src/validation.rs:2812`: allocation summary is explicitly aggregate display information, never an inherited Allocation relation. A summary node without a direct incoming Allocation is marked for dashed presentation. This does not authorize generating a relation usage.
+- `crates/oa-desktop/src/diagram.rs:1015` derives visible containers from `visual_parent`; `:1021` paints containers before edges/children. `:1129` repaints container headers above traversing relationships. `:1452` paints nodes; selection is based on `element.id == selected`. Summary styling is separate, including `node_header` at `:1509`.
+- `crates/oa-desktop/src/app.rs:718` (`selected_architecture_placement`) derives a placement from `App.selected`; `refresh_draft` immediately recomputes `selected_node` from it. `app/diagram_usages.rs:380` currently writes `selected_node`, but calls `refresh_draft` at `:395`. Setting relation semantic selection plus `selected_node = work_placement` alone therefore does not preserve focus, and the current renderer would not highlight that work. The same architecture seam applies to ports: `Target::Port` sets semantic selection to the port and owner placement separately, then draft refresh cannot find a node whose element is the port and clears `selected_node`. Root identified the existing `port_navigation_selects_port_and_exact_visible_owner_without_editing_geometry` expectation as affected while the frozen gate runs; this review did not execute it. State rows initially set `behavior.diagram.placement` (`app/diagram_usages.rs:330`), but the rest of `refresh_draft` (`app.rs:734`) recomputes that field using the same selected-node/element comparison when `state_context` resolves. Thus relation selection can clear that exact placement too. The renderer can still paint a row from selected relation identity; placement reset alone does not prove a visible row-highlight failure. Preserve and verify both semantic selection and the intended exact presentation identity.
+
+### Confirmed predicate and minimal correction
+
+For an actual direct `RelationKind::Allocation` r, in a saved Allocation projection only:
+
+1. Obtain actual visible projected nodes whose element IDs are r.source (performer) and r.target (work).
+2. Walk the target work placement's `visual_parent` chain through visible projected placements with a visited set.
+3. Emit a grouping usage only if that chain contains the source performer placement. Retain the actual relation ID and the exact work and performer placement IDs.
+
+This is precisely the peer-approved comment 616/627 predicate. It is not inferred from `allocation_summary`, two visible endpoints, a decomposition parent, or arbitrary semantic containment. Do not change core allocation validation, `parents`, drag/reparent commands, persistence, or peer Delete behavior.
+
+Use an explicit target such as `AllocationGrouping { relation, work_placement, performer_placement }`, with role `allocation grouping` and the projected work's bounded labelled-header rectangle. Reuse the existing bounded node-header camera policy. This target makes the distinction reviewable; neither `Placement(work)` nor an unrelated `StateRow` target expresses it correctly.
+
+Keep selected semantic identity equal to the queried relation. Add a separately validated presentation focus/highlight for the exact work placement, surviving `refresh_draft`; pass it to the architecture renderer independently of the semantic selection. Prefer a typed focus carrying document, revision, diagram, relation, placement, and navigation epoch, so normal selection/document changes cannot reuse stale focus. An alternative is deriving highlight from selected relation and projected grouping each paint; that avoids stored focus but needs proof it preserves exact placement when multiple representations exist. Do not silently change selection to work to reuse the current stroke logic. Use the same separation for architecture ports, while preserving state-view placement semantics. Do not blindly restore `selected_node` after refresh: coordinate its edit/Delete meaning first. Independent App tests should assert the exact validated visual marker (port owner, grouping work, or state row) and unchanged semantic target, rather than requiring an overloaded global edit-selection field.
+
+Coordinate this presentation focus with the peer's Delete capture: removal continues to capture the selected relation as semantic target; focus placement is separate context, never a replacement semantic target. Explicit later user selection of work can of course change the target. Preserve `app/diagram_usages.rs:382`'s unconditional canvas epoch increment, menu closure, bend/connection reset, and every pending-draft guard, including navigation returning to equal values. Extend deferred reveal to validate the same grouping target; its temporary pending tuple is consumed after layout and should not double as persistent highlight state.
+
+### Independent expectations
+
+- A visible direct allocation with the performer's placement on the actual work ancestor chain produces one grouping row and focuses that exact work header, even when the performer is not its immediate visual parent.
+- Hidden/folded work, hidden performer, wrong projection, endpoints that are merely both visible, a mismatching visual-parent chain, and aggregate-only summary produce no direct Allocation usage.
+- A direct child allocation underneath a summary container remains discoverable if its target is visible and its performer occurs in the chain. No extra relation is invented for the summary container.
+- Choosing preserves the complete model/source/history and leaves `App.selected == relation`; highlighting work does not make a subsequent Delete capture target work. Test this against peer's integrated removal contract, not by assuming current adapter state alone proves it.
+- Fold/delete/retarget/diagram replacement invalidates an old grouping target. Repeat navigation retires old canvas/context tickets even when destination/selection values compare equal. Both initial and deferred camera reveal reject stale document/revision/epoch.
+
+## Integration boundary and source identity
+
+Suggested bounded production seams: `diagram_usage.rs` target/query/label; `behavior/topology.rs` preview record/geometry/paint; topology `usages.rs` query/reveal and `view.rs` selection wiring; minimal topology presentation-state field; App adapter and architecture canvas presentation-focus wiring. Root coordinates shared App/view changes and peer Delete compatibility. No model/schema/dependency or allocation-authoring changes are required.
+
+Verified SHA-256 snapshots (raw file bytes):
+
+| File | SHA-256 |
+| --- | --- |
+| `behavior/topology.rs` | `dff564d2dca68af02874878cabdabdcb7f717bff67b221d376ccb6734a2e16ae` |
+| `behavior/topology/usages.rs` | `d1ff2f16695d560bd2676825eb6c11d82b0c259cc84d6804dc2dbd1a8dadc42c` |
+| `diagram_usage.rs` | `11ed6c844148eba6a122c675168561e9e9dc4e88399ae4fc0facfb82d79bdd89` |
+| `app/diagram_usages.rs` | `2374a9323bf422c8cb1af7832aa2c3ce3294a894f1fc710ba165c557b26d8c8b` |
+| `oa-core/src/projection.rs` | `69ed12bace2cc5024e151752a174ab14034ac2d05eb741fcf13e9a27521c059b` |
+| `oa-core/src/validation.rs` | `7c1b4ae5e4ebba13e99af9158ccde138dfc5e9a7afb580e76fba72d0b64ba74e` |
+
+Line references describe these inspected working files. Root's in-progress checks cover the frozen implementation before these proposed corrections, not the proposal. Root should implement after the freeze, run focused query/App tests plus required project checks, and inspect actual repeated-call arrow and allocation-grouping navigation with semantic selection/Delete capture before accepting coverage.

harness/experiments/behavior-navigation-review-20260912/free-behavior-canvas-critique-20260912.md

@@ -0,0 +1,104 @@
+# Independent critique: freely editable behavior canvases
+
+2026-09-12. Reviewer `/root/diagram_usage_workflows`, delegated by Codex-ytr83r. Read-only review of current issues #2/#20/#22, the proposal in [free-behavior-canvas-design-20260912.md](free-behavior-canvas-design-20260912.md), and primary code in `.local/diagram-usages-ytr83r-20260912`, branch `codex/diagram-usages-ytr83r-20260912`, base `7aa007b0777aa182a99f46e90eeb9b2558f3ad2a` plus root's uncommitted navigation changes. No production edit, build, GUI operation, or Gitea mutation. This is design evidence, not native acceptance. Root owns synthesis; peers retain #16 resize and #21 activation rendering ownership.
+
+## Actionable conclusions
+
+1. **Conditionally adopt the existing Diagram identity/lifecycle, not the entire proposed implementation shape at once.** Owner-bound Process and Scenario projections fit saved views and avoid a second navigation/source/API aggregate. Use a single tagged behavior-layout payload, or an equally strict validated representation, rather than unrelated optional process/scenario blocks. Preserve the existing architecture/state storage contract. Do not make moving every desktop geometry algorithm into core a prerequisite for the first useful slice.
+2. **Resolve the projection/gesture contract with a bounded numeric experiment before committing to the scenario schema.** Absolute desired anchors are a credible candidate; stored and resolved geometry legitimately differ already in architecture/state. What remains undefined is conflict resolution, the inverse from a requested drag/resize to authored changes, and what a text-only user sees after reorder. The table below makes this uncertainty falsifiable. This is a policy prerequisite, not a categorical rejection of desired coordinates or permission to postpone the feature indefinitely.
+3. **Include legacy ordered process paths in the route contract.** Requiring an explicit SequenceLink before bending an already drawn legacy arrow fails the user's bend request for those existing models. Add a typed derived-path address and a defined lifecycle. Never manufacture semantic links as an elbow-drag side effect.
+4. **Retain relation identity in qualified previews before saving their routes.** Current preview links retain only endpoint pairs. Parallel links would collide if those pairs became the persistence key. A qualified route must identify both the full caller path and the relation. The same leaf reached through different paths must remain independently editable.
+5. **Do not implement first-edit capture as a screenshot-to-model copy.** It must seed valid authored inputs whose projected result equals the preview, preserve omitted/invisible records, and allocate view/placement identities once. Peer #16 already supplies a concrete counterexample to copying rendered dimensions back as authored dimensions. Complete capture also needs a size/performance bound and a stable policy for missing or collapsed appearances.
+6. **Specify reference transformations and source comment keys before UI fan-out.** Owner deletion/change, reidentify, caller-target changes, source reorder, legacy-to-explicit conversion, and hidden routes are not incidental cleanup. They determine whether manual work survives normal editing. Two views of one owner must be part of the first identity tests.
+
+## Requirements and verified evidence
+
+The current user clarification in [#2 comment608](http://217.177.34.108:3000/sorokin.oleg.edu/ARCADIA-Studio/issues/2#issuecomment-608) rejects the camera-repair milestone as satisfying free behavior editing. [#20](http://217.177.34.108:3000/sorokin.oleg.edu/ARCADIA-Studio/issues/20) requires spreading lifelines to make call names readable, moving arrows, resizing, and replacing strange controls. [#22 comment606](http://217.177.34.108:3000/sorokin.oleg.edu/ARCADIA-Studio/issues/22#issuecomment-606) specifically adds process connection bends. Earlier sequence-constraint discussion does not erase these requirements. Cosmetic manipulation should preserve semantics; graphical/text/API parity follows the user-owned project specification. Always-present canvas and ordinary Properties are the agreed direction, not permission for canvas keyboard actions behind a focused text field.
+
+Verified local constraints:
+
+- [model.rs:1431](../../../crates/oa-core/src/model.rs#L1431): ProjectionKind is Copy and currently has only a StateMachine owner variant. Diagram contains common metadata, view options, ID-keyed NodePlacements and relation/trace EdgeRoutes. Keeping owner IDs in ProjectionKind while storing layout separately avoids a needless Copy-breaking change.
+- [validation.rs:645](../../../crates/oa-core/src/validation.rs#L645): routes must refer to existing relations/traces, are unique per edge, have bounded finite waypoints and normalized label fractions. [validation.rs:774](../../../crates/oa-core/src/validation.rs#L774) enforces one placement per semantic element per diagram. Repeated qualified appearances therefore cannot simply be extra ordinary nodes referencing the same leaf.
+- [topology.rs:914](../../../crates/oa-desktop/src/behavior/topology.rs#L914): GraphNode previews carry OccurrenceEndpoints; preview_links are only endpoint pairs. OrderedPath explicitly has source/target/points and no relation ID. [topology.rs:1128](../../../crates/oa-desktop/src/behavior/topology.rs#L1128) drops each preview relation's ID while constructing those pairs.
+- [topology.rs:1000](../../../crates/oa-desktop/src/behavior/topology.rs#L1000): Graph rebuilds a TopologyIndex, derives rank from explicit links plus ordered adjacency, then constructs geometry. The rank traversal filters the adjacency list for each queued node. This is a concrete existing repeated-scan risk; adding stored layouts should not multiply this by every saved view on every pointer move.
+- [behavior.rs:1393](../../../crates/oa-desktop/src/behavior.rs#L1393): scenario rows follow steps/branches and recursively accumulate geometry. Fragment and branch boxes have different anchor conventions. A message y, frame rectangle and branch extent need a deliberate canonical relationship.
+- The separate [#21 read-only activation analysis](issue21-activation-analysis-20260912.md) verifies self-message receive geometry below its row anchor and existing lifetime/branch attachment concerns. This foundation must expose send/receive anchors to the activation owner; it must not implement a competing activation engine.
+
+## Storage alternatives against the actual criteria
+
+| Candidate | Manual freedom and identity | Source/API/lifecycle cost | Main falsifier | Recommendation |
+| --- | --- | --- | --- | --- |
+| Shared Diagram plus independent optional process_layout/scenario_layout | Expressive; keeps saved-view identity | Small additive syntax, but many invalid combinations and duplicated authority | Scenario projection with process layout or generic unrelated nodes passes unnoticed; two records claim one direct appearance | Avoid this public contract unless strict cross-field validation is explicit and exhaustive |
+| Shared Diagram plus tagged BehaviorLayout, projection retains owner ID | Expressive; common metadata/navigation/history retained; domain records typed | Moderate schema/parser/walker work; owner/tag compatibility still needs validation | Tag/owner mismatch, same address in generic and qualified records, incompatible fields retained after projection change | Preferred bounded shape; constructor/accessor invariants plus parser/API validation |
+| Behavior layout stored inside a payload-carrying projection enum | Stronger type coupling possible | Changes Copy assumptions and a widely matched enum; can make common projection queries expensive | Large ripple before first persisted move; geometry cloning during inexpensive kind checks | Viable only if implementation evidence makes it simpler; not needed merely for type purity |
+| Separate top-level BehaviorView collection | Clean discriminated domain structure | Duplicates naming, identities, references, source ownership, REST inventory, selection, recovery, where-used and view deletion | A process view cannot participate in ordinary diagram navigation/export/history without a second branch everywhere | Keep as fallback if common Diagram validation becomes unmanageable, not first choice |
+| Session-only map or spacing sliders | Quick visible result | Cannot provide durable source/REST/reopen parity | Save/reopen loses edits; an individual bend or position remains impossible | Rejected as production feature; candidate preview remains transient |
+
+Minimal recommended boundary: common Diagram ID/metadata; Process/Scenario owner tags; ordinary direct-process nodes and explicit relation routes; typed extra addresses only where the existing representation cannot express identity. A tagged Process payload can hold qualified placements and derived adjacency routes. A tagged Scenario payload can hold lifeline/event/frame/message geometry. Empty ordinary nodes/routes should be required where they have no defined scenario meaning. Do not relax the global one-element-per-diagram invariant just to fit qualified appearances.
+
+Define whether an empty qualified path is illegal or canonicalizes to the ordinary direct occurrence. Allowing both forms creates two geometry authorities. Prefer rejecting the empty path in the qualified-only collection. Presentation records keyed by semantic addresses need not invent global UUIDs, but any new placement UUIDs must join identity/reidentify/alias/serialization walkers consistently. Neither indexes nor displayed labels are persistent addresses.
+
+## Numeric experiment for constrained scenario geometry
+
+These are deliberately simplified independent examples, not production metric claims. Let origin=0, minimum gap=10, A and B each have height20, order=[A,B], displayed tops A=100/B=200. Compare (D) absolute desired tops plus the illustrative monotone projection `resolved[i] = max(desired[i], previous_bottom + 10)` and (G) nonnegative gap-before stored on each occurrence, initially gap(A)=100/gap(B)=80. Neither example algorithm is adopted by this report.
+
+| Operation | D with no inverse adjustment | G with no inverse adjustment | What the experiment must decide/prove |
+| --- | --- | --- | --- |
+| Move A to50 | A50/B200 | A50/B150 | Ordinary move should be able to preserve B at200; G needs gap(B)=130. Test a planner that changes only necessary dependent records. |
+| Move A to250, preserve order | A250/B280; B's desired200 remains displaced | A250/B350 | Both preserve semantics, but select different whitespace policies. Preview must show B's actual final position. A feasible requested layout A250/B280 must be expressible in both (G gap(B)=10). |
+| Move B upward to110 | B resolves130; stored110 differs | Requested negative/too-small gap needs defined clamp or rejection | Report a concrete constraint and preview actual B130; never commit one pixel result and reopen another. Explicitly distinguish desired values from resolved inspector values. |
+| Increase A height20→80 | A100/B200 remains feasible | A100/B260 | Resize must be able to preserve B at200 when feasible (G gap(B)=20). Inactive dimensions and unaffected coordinates should not drift accidentally. |
+| Increase A height20→120 | A100/B230 | A100/B300 | Minimum-gap conflict now exists. Show which rows move and why; preserve authored inactive axes. A source/API resize must produce the same projection as the GUI candidate. |
+| Source reorder to[B,A] | B200/A230, A desired100 displaced | B80/A200 if each gap travels with its occurrence | Both are deterministic yet materially different. Specify whether whitespace belongs to an occurrence, a predecessor pair, or a sequence boundary. No passive rewrite or semantics-from-y. |
+| Delete A | B200 | B80 | This is a lifecycle choice, not a numerical accident. Preserve surviving absolute position or deliberately remove preceding whitespace; GUI/source/API must agree. |
+
+The test harness should enumerate small feasible integer layouts and check every requested feasible result has an authored representation and a stable projector result. Test repeat projection idempotence, no hidden model/source mutation, and planner preview = committed projection = source round trip = JSON/REST round trip. Measure changed records as well as output positions; equality from calling the same solver twice is insufficient. Independently assert the expected selected coordinate, semantic order and unchanged unaffected positions.
+
+Additional discriminating probes:
+
+- Nested fragment F spans y80..400, operand starts120, A160 and B260. Resize only F's bottom to300, then to220. Define header, padding, operand and child containment constraints. The first feasible result must preserve authored children. The second must report/preview specific container growth, constrained bound or chosen child movement; silently clipping children or reparenting them is invalid. Repeat moving F with and without an explicitly named group-move action, specifying absolute versus translated child coordinates.
+- Self-call send at200/receive at224, reply later at320: move the call to250 and change its loop height independently. Send, receive, activation start and reply attachment must consume the same anchor outputs. A single `message.y` is sufficient only if the receive-offset convention is explicitly part of projection/route geometry. Interior waypoints must not accidentally change the semantic receiver or activation interval.
+- A delayed-created lifeline must attach its header to its creation receive anchor after message movement; deletion must end the lane at the deletion receive anchor. Moving a header horizontally never changes sender/receiver. Hidden branch paths must retain stored values without entering a contradictory visible ordering.
+- Repeated messages with one exchange and distinct occurrence IDs get independent y/bends/label offsets. An opaque ScenarioUse does not create layout for callee events merely because bindings refer to them.
+- Text reorder with conflicting desired anchors must return a deterministic inspectable layout diagnostic containing the affected occurrence addresses and reason. Decide whether the UI displays desired and resolved values, offers an explicit Normalize Layout transaction, or exposes the conflict otherwise. Valid semantics must not be silently rewritten to match pixels.
+
+Recommendation: implement both tiny pure candidate projectors/inverse planners outside production architecture and run these probes. Start with absolute anchors as the likely better fit for exact coordinates and preserving unaffected positions, but select it only after the nested/lifetime probes and inverse-resize counterexample pass. Gap-before remains a meaningful comparison, not an automatic-only caricature: a planner can translate requested absolute positions into gaps. Record measured complexity and source diff size. Bound this experiment to the policy uncertainty rather than broad renderer extraction.
+
+## Reference lifecycle and source contract that cannot remain implicit
+
+| Case | Required independent oracle |
+| --- | --- |
+| Two saved views of one owner | Change only view V1's layout; V2 and semantics remain byte-for-byte equal. All context stamps, camera caches, navigation and recovery include diagram ID. |
+| Reuse same callee twice; nested reuse twice | Route/resize `[caller1,nested1]/leaf` only; caller2 and the callee definition remain unchanged. Parallel callee relations retain separate routes despite equal endpoints. |
+| Delete/reidentify caller or occurrence | Reidentify transforms every address component and source comment key; delete removes or explicitly invalidates dependent records in the same validated transaction. Never retarget by name. Undo restores exact keys and geometry. |
+| Change a caller's referenced process | Reject incompatible old paths or remove them through an explicit reported transformation. Reuse of a UUID elsewhere must not silently activate an unrelated stale record. |
+| Legacy order A,B,C → A,C,B | Derived route(A,B) stops applying; route(A,C) is a different key. Define whether obsolete records are removed, retained dormant, or diagnosed. If retained, state whether reintroducing adjacency restores them. The decision must be bounded and tested. |
+| Convert legacy paths to explicit links | Define an atomic presentation route migration by exact endpoint correspondence, with ambiguity handling for parallel links. No automatic semantic conversion during bend edits. |
+| Filter/collapse temporarily hides a route/node | Preserve authored records. Partial current visibility must never become a destructive replacement snapshot. Reopen/reexpand restores the same geometry. |
+| Change diagram owner/projection/layer | Reject incompatible retained fields, or require an explicit complete conversion in one transaction. No silent geometry loss or unrelated node acceptance. |
+| Invalid source/API payload | Reject duplicate typed keys, owner/tag mismatch, scenario event of another owner, empty/invalid qualified path, wrong route subject kind, NaN/infinity/out-of-bounds geometry, and over-budget path/point collections with precise field diagnostics. |
+
+The current version7 strict parsing/serde and validation gates require a coordinated schema version decision, not unversioned optional-field accretion. Old sources should open clean without synthesized diagrams or formatted rewrites. An older reader must reject unsupported new constructs rather than discard manual geometry. Source format/parse, JSON, REST conditional transactions, reference walkers, copy/transition, multi-file ownership and comments all need compatible changes.
+
+Nested comments must be matched by the full typed key: a scenario occurrence, qualified endpoint, qualified relation, or derived ordered-path pair plus its domain. Array index and terminal occurrence alone are insufficient after reorder/reidentify. Same-named aliases in included files must resolve by IDs. Explicit reset of one geometry record must not discard sibling comments or materialize invisible records.
+
+## First edit, scalability, and proportionate implementation
+
+First accepted gesture should create the view and required authored records in one normal transaction. Pointer-down/preview may reserve deterministic candidate IDs, but render, selection and cancel create no source changes. Undo removes the first view creation; redo restores the same IDs and geometry. If a first resize begins from derived geometry, preserve the authored-versus-resolved contract established by #16 instead of serializing every projected width/height.
+
+Complete direct-surface capture protects untouched objects against later seed-layout movement, but has costs: an O(model-size) first edit, larger source diffs, new identity allocation and potential dependence on transient filters. Sparse capture is smaller but leaves untouched nodes dependent on changing ranks/row generation. A bounded compromise is a stable initial placement plan plus explicit overrides, provided that this does not introduce two unexplained coordinate authorities. The first slice should compare total records and diff size on a realistic long model before selecting capture policy. Do not claim that “currently rendered” means a stable semantic set until filter/expansion/default-view rules are fixed.
+
+Keep stored geometry projection pure and reuse geometry primitives. It is not necessary to relocate the entire Scene/Graph renderer before proving persistence. An adapter can resolve typed authored records into current Scene/Graph positions, attachment anchors and routed paths; both preview and committed render must consume that result. Any behavior constraint or inverse planner needed by REST should be UI-free. Do not duplicate a second projector for source/API or retain competing automatic geometry paths that overwrite saved positions late in rendering.
+
+The existing process rank scan can approach V×E work; repeated TopologyIndex rebuilding and qualification resolution add cost. Cache immutable owner/topology indexes per model revision, rebuild affected geometry once per candidate, and bound visible expansion separately from stored-record validation. Validate stored keys without enumerating every possible recursive appearance. Limit total records, aggregate path length/depth and points as well as points per route. A saved view must not force eager expansion of the Cartesian product of nested uses. Stress tests should record first-edit latency, per-pointer candidate work, lookup/reopen work and source size on the same fixture, with an explicit target budget agreed for the actual hardware rather than invented acceptance milliseconds.
+
+## Minimum independent acceptance before broad adoption
+
+1. One owner-bound process view moves a direct occurrence off its rank column, resizes it, bends both an explicit link and an existing legacy path, and moves a label. Links, steps and represented work do not change. Preview/commit/reopen are numerically equal and one Undo restores source/model.
+2. Two-lifeline scenario independently spaces headers and positions/routes two occurrences of the same exchange, preserving sender/receiver, message kind, reply_to, steps and lifetimes. Long labels become inspectable through ordinary controls. The numeric source-reorder/resize policy probes above pass.
+3. First edit, cancel, zero movement, stale revision, document/view switch, dirty-source navigation, focus loss and modal entry have explicit nonmutation or atomic commit outcomes. Actual App input paths must be exercised later, not only pure command constructors.
+4. Two saved views and two qualified appearances retain independent geometry, full target identity and source comments across save/reopen, REST, reidentify, collapse, delete and Undo. An exact usage jump reaches the saved appearance without changing geometry.
+5. Nested fragments, operands, self messages and delayed creation/deletion use explicit attachment outputs. Peer #21 activation rendering is reviewed against those outputs; this task neither overwrites its fix nor claims its native acceptance.
+6. Actual native workflows at the minimum supported window demonstrate immediate canvas manipulation, visible resize/bend handles, Properties focus, discoverable semantic Reorder, and stable viewport origin. A screenshot or small fixture alone does not establish all process/scenario kinds or large-model usability.
+
+Adopt the common saved-view direction and a bounded end-to-end slice now; settle the numeric projection/inverse and address-lifecycle rules before multiplying UI controls and schema cases. Revisit the common Diagram choice only if the typed payload/validation slice demonstrates more duplication than a separate aggregate, not because domain-specific geometry exists.

harness/experiments/behavior-navigation-review-20260912/free-behavior-canvas-design-20260912.md

@@ -0,0 +1,185 @@
+# Freely editable process and scenario canvases — design investigation
+
+2026-09-12. Read-only investigation by delegated reviewer `/root/diagram_membership_map` for Codex-ytr83r. Source inspected in `C:/Users/User/Documents/Git/ARCADIA-Studio/.local/diagram-usages-ytr83r-20260912`, branch `codex/diagram-usages-ytr83r-20260912`, base `7aa007b0777aa182a99f46e90eeb9b2558f3ad2a` plus root's uncommitted navigation/prerequisite integration. This is a proposal, not an implemented feature or an acceptance result. No source modifications, build, GUI operation, or Gitea claim was performed. Root owns compilation and native inspection; peer Codex-956atf owns #16 resize foundation and #3/#15 work.
+
+## Required outcome and evidence boundary
+
+The user's [#2 clarification608](http://217.177.34.108:3000/sorokin.oleg.edu/ARCADIA-Studio/issues/2#issuecomment-608) explicitly rejects the camera/repair preview as satisfying free behavior editing. Process and scenario diagrams must support ordinary direct manipulation comparable to architecture/state diagrams. The earlier comment250 about sequence constraints does not authorize retaining rigid automatic-only layouts after that clarification.
+
+Concrete requirements are [#20](http://217.177.34.108:3000/sorokin.oleg.edu/ARCADIA-Studio/issues/20): spread lifelines to expose labels, move arrows, resize objects, replace strange draggable rectangles with understandable controls; [#22](http://217.177.34.108:3000/sorokin.oleg.edu/ARCADIA-Studio/issues/22), including comment606: process movement, resizing, and connection bends; [#24](http://217.177.34.108:3000/sorokin.oleg.edu/ARCADIA-Studio/issues/24): replace the Details-menu interaction; [#25](http://217.177.34.108:3000/sorokin.oleg.edu/ARCADIA-Studio/issues/25): canvas available without an activation button. The user-owned specification also requires graphical/text parity, an unambiguous reST specification, REST automation, readable source, and maintainable architecture. Cosmetic movement is not authorization to change behavioral ordering.
+
+The [peer resize foundation at full commit f7d84faf30cdb5e3695c2dc16ee0a5f2eac91e71](http://217.177.34.108:3000/sorokin.oleg.edu/ARCADIA-Studio/src/commit/f7d84faf30cdb5e3695c2dc16ee0a5f2eac91e71/harness/diagram-resize-foundation-20260912.md) was read, including its executed falsifiers and unresolved questions. Its verified contract is eight handles, fixed opposite edges, unchanged authored child placements/semantic ownership, one Undo transaction, preservation of inactive authored fields, and exact projected preview/reopen equality. It rejects copying every visible dimension back into storage: stored224×160 projects224×232, copying224×232 can project232×232, while preserving authored height permits214×232. It also rejects a universal preferred minimum on an inactive axis. Those are resize-planner requirements, not reasons to omit handles. Process/scenario persistence is explicitly a separate dependency. No new resize-gesture implementation is claimed here.
+
+Existing [native Capella benchmark](../../../harness/release-capella-scenario-benchmark-20260910.md#L1) demonstrates point creation, a drag-created LOOP/operand, and distinct occurrence/definition identities at1010×760. It does not establish resize, message movement, routing, or nested activation behavior. Root's current native capture attempts timed out, so no new native evidence is claimed.
+
+## Current implementation: the missing persistence boundary
+
+| Surface | Actual geometry and interaction | Consequence |
+| --- | --- | --- |
+| Persisted architecture/state | [`Diagram`, `NodePlacement`, `EdgeRoute`][model] provide stable view/placement identities, absolute coordinates, authored size, routes and labels. `ProjectionKind` has StateMachine but no Process/Scenario owner variant. | Existing source/history/API mechanisms are reusable. Adding process/scenario enum labels alone cannot make their desktop renderers consume saved geometry. |
+| Process | [`Graph::expanded_qualified`][graph] derives columns from SequenceLinks/legacy order and places every contribution at `x=24+rank*420`, initial size270×104. Reuse cards get automatic preview height; expansion chooses4 or up to512 tiles. [`State`][topology-state] stores ephemeral camera/expansion/draft state, no persisted layout. | Every render reconstructs positions and routes. No user-authored movement survives because no such geometry exists in the model. Source owner `steps` determines included occurrences, not coordinates. |
+| Process input | [`direct::Graph::input`][process-input] selects from node bodies. A separate [`handle`][process-handle] starts `Press::Reorder`; release publishes Reorder, not Move. The planner rejects cross-column reorder because links define columns. Reconnect handles alter semantic links; there is no bendpoint drag. | The strange rectangle is a semantic reorder affordance, not a misplaced implementation of free movement. Renaming it or making it larger cannot satisfy #22. |
+| Qualified process reuse | [`contextual::preview`][context-preview] and `GraphNode.preview` retain caller paths plus occurrence IDs. Direct ContextualLinks retain relation IDs; preview links currently reduce callee links to endpoint pairs. | Two appearances of one callee occurrence must have independent layout. Saving by represented work ID or callee occurrence ID alone will alias them. Preview routes need the complete caller path plus callee relation ID before they can be authored. |
+| Scenario | [`Scene::sequence`][scene] gathers direct lifelines, places them at automatic x positions (160+i*240), creates fixed204×70 headers, and [`occurrences`][scene-occurrences] walks semantic sequences/operands to build fixed row spacing, boxes, arrows and frames. Lines are keyed by exchange **occurrence** ID. [`Presentation`][presentation] stores only identity, viewport, focus/shelf and camera. | Lifeline spacing, event y, box/frame dimensions and route bends are not model data. Reopening cannot restore manual layout. Repeated messages using one exchange still require separate presentation. |
+| Scenario input | [`Scene::reorder_handle`][scenario-handle] creates a22×24 rectangle at x6 beside the selected row. [`scenario::reorder`][scenario-reorder] changes `SetSteps` within the current owner/operand only. | The existing drag is an ordered-list edit. It does not represent free line movement, independent whitespace, or shape sizing. |
+| Scenario lifetime/activation | [`scenario_lifecycle`][lifecycle] derives birth/death/call semantics, with rendering consuming occurrence rows/sequence bounds. ScenarioUse is currently an opaque card; bindings do not produce inlined callee rows. | Geometry must consume semantic lifetimes and ordering; it must not derive new semantic call/death relations from drawn coordinates. Nested activation #21 remains a separate semantic/rendering dependency. |
+| Shared shell | [`controls`][controls] has Details and Canvas buttons; `keyboard_enabled` and `Scope::input_owner` gate draft/modal contexts. [`host`][host] overlays a300px editor over the viewport. | Replace the activation/Details UX, but preserve actual keyboard ownership and stale-context protections. Always-active pointer editing is compatible with text inputs owning their keyboard. |
+
+The authoritative existing presentation specification is [language.rst section5][language-diagrams]. Ordinary `node` coordinates are absolute diagram coordinates and do not alter containment/allocation. `routes.edge` currently accepts a Relation or Trace, never a scenario exchange occurrence. Route list order/comments are retained by identity; endpoints and automatic elbows are deliberately not saved. [`Command`][commands] already has Create/EditDiagram, Create/EditNode, MoveNode, Set/RemoveEdgeRoute, SetSteps, Batch and Layout. [`Document::execute`][document] prepares a complete candidate, updates source with the identity map, and commits the accepted model/source pair together. [Server routes][server] expose conditional project transactions; adding layout must use this pathway, not a second desktop-only store.
+
+## Alternatives and proposed choice
+
+Criteria: satisfy manual placement/resizing/bends; preserve behavioral semantics during cosmetic edits; exact source/API/Undo/reopen parity; retain existing authored architecture/state geometry; use stable identities for repeats; keep the interaction understandable; avoid a broad rewrite before a useful end-to-end workflow exists.
+
+| Candidate | Advantages | Material failure or cost | Decision |
+| --- | --- | --- | --- |
+| More camera controls, auto-layout spacing sliders, wider fixed cards | Small desktop diff; preserves current generator | Still cannot place individual objects/routes; explicit user rejection already falsifies sufficiency | Reject as the feature; optional layout assistance only |
+| Desktop/session position overrides | Fast visual prototype | Loses source/REST/save parity; undo splits between model and view; stale/reused identities become ambiguous | Reject production storage; transient drag preview is its only role |
+| Put all behavior in an unconstrained generic graph, with free x/y treated as semantic order | Broad shape reuse | Cosmetic drags can change execution; sequence endpoints, lifecycle, operands and nested calls require special treatment anyway | Reject semantics-by-coordinate; reuse primitives only |
+| New independent BehaviorDiagram top-level aggregate | Clean domain separation and typed layouts | Duplicates view naming/identity/source ownership/artifacts/navigation/server inventory; more migration and integration than needed | Viable if Diagram becomes unmaintainable, but not smallest coherent first choice |
+| Extend existing Diagram with owner-bound Process/Scenario projections and typed domain layout | Reuses stable saved-view lifecycle and source transactions; direct process nodes/routes fit existing records; scenario-specific anchors stay explicit | Requires real core/source/API work, and pure geometry extraction from desktop | **Proposed choice**, with the type partition below |
+
+Reuse direct process `NodePlacement` and existing relation `EdgeRoute` records. Do not distort scenario arrows into fake semantic relations just to use EdgeRoute. Do not force every scenario representation into a generic rectangle with meaningless fields. Add typed scenario presentation keyed by occurrence/lifeline identity and typed qualified-process presentation keyed by full call path. These records remain inside the same Diagram, with the same history/source owner. This is a deliberate domain distinction, not separate persistence technology.
+
+## Proposed persistence contract
+
+This section is an implementation candidate requiring specification review, not a declaration of existing syntax. The current schema/source version is7. Reserve a new version during integration; examples below use8 provisionally. Coordinate the version with other schema owners before editing it.
+
+1. Add `ProjectionKind::Process { process: Id }` accepting a Process or FunctionalChain owner, and `Scenario { scenario: Id }` accepting a Scenario, each in the diagram's layer. A diagram has one explicit owner. Multiple saved views of that owner are legal and independent. Owner identity and diagram identity are distinct.
+2. Process direct occurrence boxes use ordinary `Diagram.nodes`: one placement per included occurrence in a view, positioned independently of its represented work/exchange. Explicit SequenceLink and ContextualLink geometry uses ordinary `Diagram.routes`. Moving any process node changes only its placement; it does not edit links, parent, steps, represented element, or allocation. Automatic rank is only a seed/explicit Arrange result.
+3. A typed optional process presentation block holds `context_nodes` and `context_routes`. A contextual node key is `OccurrenceEndpoint { references: Vec<Id>, occurrence: Id }`. A contextual route key is `{ references: Vec<Id>, edge: Id }`, where the edge belongs to the resolved called process. Direct ContextualLink edges still use their own relation ID in normal routes. Each key is unique per view. Retain full IDs in the scene, including preview links; never use labels, tile indices or abbreviated paths as keys.
+4. A typed optional scenario presentation block has separate records for lifeline headers (`lifeline`, `x`, `width`, `height`), message anchors (`occurrence`, desired `y`), boxes/frames (`occurrence`, desired rectangle), operand presentation extents, and message routes (`occurrence`, pinned waypoints, optional EdgeLabel). Types reject inapplicable fields. Lifeline x is presentation order: the present metamodel does not contain Sirius's explicit semantic instance-role ordering, so do not invent one. Normalized route-label fractions/offsets and finite coordinate/size limits reuse existing primitives.
+5. Scenario box/frame time anchors have one canonical derivation from their rectangle (specified per kind, e.g. top event/header anchor); no competing stored `y` values for one occurrence. Birth/death ends and execution intervals remain derived semantic attachments. Header x/size is authored; creation timing determines its vertical attachment. A box attached to a lifeline may have a presentation x offset/leader while retaining the same lifeline reference. A cosmetic horizontal move must never rebind its participant.
+6. Persisted process child coordinates are absolute, matching normal nodes. Moving a reused group translates its visible descendant presentation records in one batch if group movement is selected; resizing a containing frame preserves child authored coordinates, consistent with #16. Scenario frame resizing changes frame geometry and available space; it does not silently add/remove covered events, change operands or move semantic ownership.
+7. Valid, feasible authored geometry is used exactly. Missing records use deterministic initial geometry. Passive rendering/navigation never creates records, marks dirty, saves, or resets authored geometry. Existing records survive collapse, temporary invisibility, filters and owner renames. Delete/reidentify/reparent/view-owner changes must explicitly clean or transform dependent references in the core transaction; stale path records cannot silently bind to a new same-named object.
+8. New records count against parse/model limits; route points retain a bounded per-route limit. Resolve caller paths with existing cycle/depth defenses and a bounded visible expansion budget. An explicit partial expansion is not permission to discard invisible authored records. Large stored layouts should not be rebuilt in App.update per pointer move.
+
+Example candidate source, following existing constructor/record conventions:
+
+```text
+arcadia 8;
+// Existing semantic declarations omitted for brevity.
+diagram response_view "Response workflow" {
+    layer Oa;
+    projection { Process { process @oa_response; }; };
+    routes [{ edge @oa_confirm_path;
+              waypoints [{ x 580; y 110; }, { x 580; y 360; }];
+              label { fraction 0.5; offset { x 0; y -16; }; }; }];
+    process_layout {
+        context_nodes [{ endpoint { references [@oa_assess_step];
+                                    occurrence @oa_assessment_action; };
+                         position { x 95; y 185; };
+                         size { width 210; height 85; }; }];
+    };
+}
+node confirm_view {
+    diagram @response_view; element @oa_confirm_step;
+    position { x 710; y 350; }; size { width 320; height 125; };
+}
+diagram conversation_view "Conversation" {
+    layer Oa;
+    projection { Scenario { scenario @oa_conversation; }; };
+    scenario_layout {
+        lifelines [{ lifeline @oa_caller; x 180; width 240; height 90; },
+                   { lifeline @oa_responder; x 660; width 280; height 90; }];
+        messages [{ occurrence @oa_call; y 210; },
+                  { occurrence @oa_reply; y 390; }];
+        message_routes [{ occurrence @oa_call;
+                          waypoints [{ x 430; y 240; }];
+                          label { fraction 0.55; offset { x 0; y -20; }; }; }];
+    };
+}
+```
+
+`oa_call` and `oa_reply` intentionally have independent anchor/route records although the release fixture uses the same underlying `oa_contact` exchange for both. `oa_confirm_path` is the fixture's explicit link from `oa_merge` to `oa_confirm_step`. Exact grammar, diagnostics and canonical formatting must be specified and round-tripped before UI depends on this candidate.
+
+API candidate: existing CreateDiagram/CreateNode/MoveNode/EditNode/SetEdgeRoute remain ordinary direct-process operations. Add typed upsert/remove operations for contextual nodes/routes and scenario lifelines/items/message routes, or one `EditBehaviorLayout { diagram, patch }` with a strictly tagged list of those operations. Prefer bounded per-record patches for scripting and safe comment retention; retain full EditDiagram replacement for existing generic clients. Do not make full-diagram replacement the only geometry API. A scenario message move changes its anchor and any explicitly previewed affected neighbor anchors in one `Batch`; an explicit reorder adds `SetSteps` to that same batch. REST uses the existing conditional transaction route and concurrency rules. Source writeback updates only the owning diagram declaration/file and matches nested comments by full typed key.
+
+## Scenario drag policy: compare before deciding
+
+The user requested movable arrows, not implicit behavioral mutation. In the current model, ordered occurrences and operand membership carry sequence meaning independently of their visual y. There are two materially different policies:
+
+| Policy | Benefit | Risk | Assessment |
+| --- | --- | --- | --- |
+| Ordinary drag crossing another event commits `SetSteps` | Closest to Sirius event reorder; quick behavioral edits | An engineer making room for a long label can change execution; a few pixels of overshoot is consequential; source diff mixes geometry with semantics | Do not make this the default without direct user-workflow evidence |
+| Ordinary drag edits presentation; explicit Reorder changes steps | Cosmetic operations preserve semantics; source diff/Undo intent is clear | Need an understandable constraint/ripple preview and an accessible reorder command | **Recommended default** |
+
+Within the second policy, a hard tiny-gap clamp would remain frustrating and could repeat the rigid-canvas failure. Prefer a local spacing planner: drag within available space moves the chosen anchor; dragging farther proposes moving the affected following/preceding event block while retaining semantic order. Show every moved row in the preview. The user can insert/remove vertical space directly, spread lifelines freely, move labels/bends independently, and resize boxes/frames. A selected arrow itself is the handle for movement; no left-margin rectangle is required. A pointer cursor/status can say “Move message” or “Reorder message” according to the active action. Do not silently fall back from a blocked layout move to semantic reorder.
+
+Provide named Reorder in the common context menu/Properties actions and keyboard accessibility. An optional modifier may invoke the same action after it is discoverable; the modifier is not the sole route. Reorder shows a before/after insertion marker in the actual operand and previews lifecycle/activation changes. Cross-operand movement remains a separately named semantic action until its valid rules are implemented. Complete reorder in one atomic semantic+layout transaction, not a SetSteps commit followed by a best-effort geometry save.
+
+Two storage choices for constrained y require an early evaluator:
+
+- Absolute desired anchors are easy to understand in text and support precise coordinates. When source editing changes steps without adjusting layout, the pure projector must resolve only actual order/containment conflicts, retain authored values and report displaced anchors; it must not allow a contradictory rendered sequence or rewrite source during render. GUI reorder should persist its previewed resolved anchors, so reopen matches exactly.
+- Nonnegative gap-before records naturally survive order edits and make blank-space insertion simple. They are less direct for exact coordinates; box-height changes move downstream events by construction, and frame/nested-call constraints still need a solver. They also risk recreating an automatic-only layout if exposed as the only UI freedom.
+
+Recommend absolute desired anchors plus a deterministic, explicitly tested local conflict resolver, subject to falsification on source reorder/nesting fixtures before commitment. A conflicting source layout is a presentation diagnostic, not grounds to reject a semantically valid model or silently mutate its order. The renderer must distinguish stored geometry from resolved geometry. No broad layout run occurs on selection, property inspection, camera changes, label edits that still fit, or switching views. If the resolver cannot meet hard semantic anchors, it produces a clear bounded conflict result; it does not claim that an unsearched resize/move is impossible.
+
+Connection bends are presentation-only. Process edges attach to their existing source/target occurrences; route handles move/add/remove pinned points and labels use existing fraction+offset behavior. Scenario message ends remain attached to the existing sender/receiver and event anchor; interior bendpoints/label offsets do not encode send/receive order. Self-message loops must be resizable/routable while preserving their occurrence identity. Reconnection is a different visible handle/action and uses semantic validation. Derived legacy process adjacency lacks a stable relation ID: either give its presentation a typed `{source_occurrence,target_occurrence}` key with lifecycle rules, or require an explicit link before authoring its route. Never create a hidden SequenceLink as a side effect of dragging an elbow. This is a concrete remaining route-coverage decision for legacy fixtures.
+
+## Interaction and architecture boundaries
+
+Extract pure process/scenario geometry projection into oa-core (or an existing UI-free shared crate if the core layering demands it). Inputs are project, explicit view identity/presentation, and bounded expansion state. Outputs have stable typed representation targets, actual hit bounds, attachment anchors, routed polylines, constraints and diagnostics. Fonts/text measurements need a deterministic shared interface or conservative documented metrics; do not put Iced types into persisted data. Keep initial layout and explicit Arrange as planners separate from projection. The same candidate projector must drive drag preview, committed render, navigation bounds, export and geometry tests.
+
+Reuse architecture route math/label projection and peer resize planning rather than copying its algorithms into both behavior renderers. The existing [`routing::route_diagram`][routing] is coupled to projected diagrams, so first reuse primitives or adapt typed scene edges; do not pretend it already accepts sequence events. Process graph topology/rank logic remains valuable for initial/selected Arrange. Scenario lifetime/call semantics remain a separate input to geometry.
+
+Interaction state is transient: `Gesture { document, diagram, owner, revision, epoch, target, original, candidate }`. Pointer-down resolves one exact rendered target, pointer moves only update a candidate, and release revalidates the complete scope before one normal transaction. Escape, focus loss, document/view switch, modal entry, source changes and stale revisions cancel without history. Zero movement retains exact authored data. Camera changes must either transform the captured gesture consistently or cancel it; they cannot replay a saved release against a new view. Peer resize hit arbitration must order visible resize/route handles ahead of overlapping invisible port slop.
+
+Canvas is always present and pointer-active whenever its document is editable. Remove the user-facing Canvas activation button and mode-dependent hiding of editing essentials. F6 may remain ordinary focus traversal; text inputs still own text/navigation keys, and dialogs/drafts retain their existing guards. “Always active” must not make Delete/arrow keys operate behind a focused Properties text field. Keep the stamped control/input protection already introduced in the camera prerequisite.
+
+Use one conventional selection and Properties workflow: click a box/arrow selects it, selected objects display familiar handles, double-click/name action edits its name, context menu offers relevant semantic actions, and the common Properties panel follows selection automatically. Replace the Details shelf with this panel; avoid a second selection editor or tiny reorder controls. Tools remain available in a compact palette. At the minimum supported window, the panel must be collapsible/resizable or use a stable shared inspector region; selection must not shift the canvas coordinate origin mid-gesture. The existing300px opaque overlay is evidence of current behavior, not proof that it is an acceptable final layout. Root needs native evaluation for hit size, palette contrast, long names and keyboard flow.
+
+Saved-view identity must propagate to `Scope`, process/scenario State identity, camera cache, recovery target and diagram-usage navigation. Current process/scenario usages identify owner-based surfaces; multiple views require the saved Diagram ID as well. Qualified occurrences retain their full paths. Navigation selects/reveals the actual saved appearance without creating a view, resetting geometry or applying drafts. Camera can remain session-local; authored expansion/collapse affecting the saved view must have an explicit persistence policy rather than being conflated with camera focus.
+
+## Migration, source edits and lifecycle
+
+- Old version7 source/JSON loads without manufacturing views or geometry. New optional blocks default absent. Frozen old-version readers must reject new fields/owner constructors rather than silently accept and drop them. Update schema gates, serde/parser defaults, formatter, strict reST, API schemas/OpenAPI, source limits and transition/copy/reference walkers together.
+- With no saved behavior view, show the current deterministic initial presentation and allow immediate gestures. The first accepted geometry edit creates the saved view and required initial presentation in the same Undo transaction. This is an internal lifecycle, not a new Canvas-enable prompt. View creation must allocate IDs once before preview/source preparation; no render-time random IDs. Merely opening a scenario remains clean.
+- Decide whether initial capture is complete or sparse before implementation. Complete capture of the currently rendered direct surface gives stronger protection against unrelated future edits moving objects; sparse overrides create smaller source but leave untouched objects dependent on changing automatic ranks. Recommend complete direct-surface capture on the first layout edit, with unseen qualified expansions initialized lazily. Preserve omitted/invisible semantic objects as omissions; do not turn opening a view into a semantic model synthesis.
+- Changing semantic names preserves positions/routes and grows/clips only according to an explicit content-size policy. Show long names through wrapping, handles and Properties; automatic size growth cannot silently overwrite stored dimensions. New objects get a local collision-aware initial position and do not trigger Arrange All.
+- Deleting a view removes only presentation; deleting an occurrence removes its direct/qualified layout and route keys; deleting a caller invalidates paths through it; reidentification transforms every reference while preserving geometry/comments. Changing an owner or reparenting must reject or explicitly repair incompatible presentation in the same transaction. Coordinate these dependency walkers with peer Delete ownership before touching them.
+- Source reorder and semantic relation edits must preserve all nonconflicting authored geometry. Layout diagnostics/derived conflict resolution must be deterministic and available outside the GUI. Text-only users can fully author the same representation and reset individual routes/placements without opening a window.
+- Saving/reopening, REST import/export, copy/transition and undo/redo must preserve distinct repeated occurrences, qualified paths, pinned route points and source comments. A route whose edge is temporarily hidden remains stored, matching existing architecture semantics.
+
+## Milestones and acceptance that can falsify this proposal
+
+1. **Contract/core slice first.** Choose schema ownership and event-anchor policy; implement one owner-bound process view with ordinary nodes/routes and one two-lifeline scenario view with separately keyed call/reply anchors/routes. Prove parse/format/model equality, JSON/source migration, REST conditional transaction and one-Undo source parity before expanding gestures. Independent tests must use expected coordinates/semantic invariants, not merely call the same planner twice.
+2. **Shared geometry/resize integration.** Extract scene projection and connect the #16 candidate planner. Exercise eight handles, active/inactive axes, port/state counterexamples where shared code applies, collapsed reuse and nested frame bounds. Demand projected preview=commit=reopen, cancellation=no change, child authored coordinates unchanged on resize. Failed bounded search is not proof of a minimum.
+3. **Direct manipulation and Properties.** On the actual minimum window and realistic large model, enter a process/scenario and immediately drag the object itself, resize from each handle, edit a bend/label, select and change a property. No activation button, Details detour, unexplained rectangle or moving viewport origin. Test text focus, Tab/F6/Escape, touchpad/mouse camera, modal entry mid-drag and dirty-source refusal/recovery.
+4. **Behavior-specific depth.** Process cycles/parallel links, repeated callee appearances and expanded nested callers; scenario same-exchange call/reply, self-message, long lifeline labels, create/delete, ALT/PAR/LOOP operands, ScenarioUse and nested activation #21. Verify routing/labels and bounds after every move. Finish all visible object kinds rather than calling the simple fixture feature-complete.
+5. **Preservation/regression/package.** Source comments across included files, two views per owner, hidden routes, reidentify/delete, conditional REST stale revisions, save/reopen, undo/redo, source reorder conflict diagnostics, navigation to the exact saved appearance, and long-model responsiveness. Root must run native workflow review and fresh independent critique, then integrate/publish a versioned milestone with honest remaining issues.
+
+Concrete user-workflow checks:
+
+- In `scenario_oa_conversation.arcadia`, widen/spread caller/responder until the full call label is readable, move call/reply to separately chosen y positions, edit only the call route, save and reopen. Underlying exchange IDs, `reply_to`, sender/receiver, steps and lifetime semantics are byte-for-byte unchanged after cosmetic operations. The two appearances retain different geometry.
+- Drag the call down across the reply's initial screen row. Default movement preserves semantic order and shows any spacing/ripple adjustment. Invoke Reorder explicitly and verify a valid/invalid preview according to call/reply semantics; there is no automatic `SetSteps` hidden in ordinary drag.
+- In `process_oa_response.arcadia`, put the confirmation box below/left of its previous rank column, resize it, bend its explicit incoming edge around another object and move its label. Links/steps/represented work do not change. Reopening does not return the box to a rank column.
+- Place two references to the assessment procedure, expand each, position/resize one visible inner occurrence and route an inner link where present. Only that caller path changes; opening the callee definition and the other caller is unaffected. Collapse/reexpand retains it.
+- Resize a fragment around existing operands, then resize a reuse card: child authored coordinates and semantic membership stay unchanged. Use a separately named semantic action to change membership. New nested activation support must use the same geometry contract rather than regenerate all rows.
+- Edit names/steps in source with comments and included files; undo restores both source and geometry. A source reorder that conflicts with authored y produces a deterministic, inspectable presentation result without rejecting a valid model, silently saving, or editing semantics from pixels.
+
+## Remaining decisions and limits
+
+The proposed absolute-anchor conflict resolver, local ripple behavior, legacy derived-path route identity, saved expansion policy, and exact Properties layout need early independent evaluators/native evidence. They are explicit design questions, not authorization to defer basic persistence or free manipulation. Capella's behavior is a comparison, not the required product specification.
+
+Official primary references support the distinction: [Sirius sequence user documentation](https://eclipse.dev/sirius/doc/user/sequences/Sequence%20Diagrams.html) describes movable lifelines, stored header height, manual blank-space insertion and order-preserving layout. Its [sequence specifier documentation](https://eclipse.dev/sirius/doc/specifier/sequences/Sequence%20Diagrams.html) explicitly delegates event/instance reordering to semantic tools when graphical movement changes order. [General Sirius diagram documentation](https://eclipse.dev/sirius/doc/user/diagrams/Diagrams.html) supplies ordinary shape movement/resizing, route bendpoint and label interactions. These are useful interaction precedents; they do not prove native Capella's current configuration or justify copying its menu density. [Capella's official feature overview](https://mbse-capella.org/features.html) distinguishes functional, exchange and interface scenarios; the same presentation architecture should apply across the application's supported scenario viewpoints rather than fixing only one.
+
+[model]: ../../../crates/oa-core/src/model.rs#L1431
+[topology-state]: ../../../crates/oa-desktop/src/behavior/topology.rs#L79
+[graph]: ../../../crates/oa-desktop/src/behavior/topology.rs#L1000
+[process-input]: ../../../crates/oa-desktop/src/behavior/topology/direct.rs#L662
+[process-handle]: ../../../crates/oa-desktop/src/behavior/topology/direct.rs#L562
+[context-preview]: ../../../crates/oa-desktop/src/behavior/topology/contextual.rs#L253
+[scene]: ../../../crates/oa-desktop/src/behavior.rs#L1228
+[scene-occurrences]: ../../../crates/oa-desktop/src/behavior.rs#L1393
+[presentation]: ../../../crates/oa-desktop/src/behavior/scenario/workspace.rs#L14
+[scenario-handle]: ../../../crates/oa-desktop/src/behavior.rs#L1819
+[scenario-reorder]: ../../../crates/oa-desktop/src/behavior/scenario.rs#L1071
+[lifecycle]: ../../../crates/oa-desktop/src/behavior/scenario_lifecycle.rs#L70
+[controls]: ../../../crates/oa-desktop/src/behavior/canvas_workspace.rs#L13
+[host]: ../../../crates/oa-desktop/src/behavior/canvas_workspace.rs#L214
+[language-diagrams]: ../../../docs/language.rst#L1056
+[commands]: ../../../crates/oa-core/src/session.rs#L11
+[document]: ../../../crates/oa-desktop/src/document.rs#L315
+[server]: ../../../crates/oa-server/src/routes.rs#L1017
+[routing]: ../../../crates/oa-core/src/routing.rs#L429

harness/experiments/behavior-navigation-review-20260912/issue21-activation-analysis-20260912.md

@@ -0,0 +1,97 @@
+# Issue 21 — independent activation rendering analysis
+
+2026-09-12, `/root/diagram_usage_workflows`, for root synthesis and peer Codex-956atf's implementation ownership. Read current issues/comments #20 and #21, including peer claim637 and root claim641. Root subsequently yielded implementation to peer956 and assigned this independent read-only evaluation. No production writes, compiler, model experiment, or native application interaction were performed. Active inspected worktree: `C:/Users/User/Documents/Git/ARCADIA-Studio/.local/diagram-usages-ytr83r-20260912`, base7aa007b plus root's diagram-usage working changes. Source line references identify the inspected files and may shift after integration.
+
+## User requirement and scope
+
+[Issue21](http://217.177.34.108:3000/sorokin.oleg.edu/ARCADIA-Studio/issues/21) gives the exact stored order Call1 L1→L2, Call2 L1→L2, Reply2 L2→L1, Reply1 L2→L1 and reports invisible inner call blocks. Comment622 asks to examine Capella because the user likes its treatment. The attached image at root `.local/gitea-issue21-25269f9e.png` shows two calls arriving at the left lifeline and one visible pale strip with no separate nested activation apparent. This supports the reported visual symptom but does not reveal the complete model, both correlations, build version, or screenshot provenance beyond the issue attachment.
+
+[Issue20](http://217.177.34.108:3000/sorokin.oleg.edu/ARCADIA-Studio/issues/20) requires less rigid scenario diagrams: ordinary direct controls for spacing lifelines, moving arrows, resizing elements and avoiding clipped names, comparable in ease to architecture editing. The #21 correction should not hardwire a new geometry scheme that makes that later work more difficult. This analysis does not propose taking #20 implementation scope.
+
+## Findings: verified source facts
+
+### 1. Overlapping activations have identical horizontal geometry and UUID-dependent paint/hit precedence
+
+`behavior.rs:1339–1363` gathers Calls by `scene.rows.keys()` from a BTreeMap keyed by occurrence ID, then invokes `activation_sequence` for each Call. This is UUID order, not call occurrence order or outer-before-inner order.
+
+`activation_sequence` follows the particular Call's `reply_to` correlation and correctly can produce two different vertical spans for the reported simple case. However, every `activation_segment` (`:1657–1678`) receives exactly the receiver lane x and emits the same `x−4` origin and width8. Reply caps (`:1739–1751`) likewise use fixed `x−7`,width14. There is no nesting depth, horizontal interval assignment or activation-specific anchor.
+
+For y1<y2<y3<y4, both Call1's span [y1,y4] and Call2's span [y2,y3] occupy [x−4,x+4]. `Scene::draw` (`:2169` onward) paints filled boxes in their stored order before messages. If the outer Call sorts later, its opaque fill/stroke covers the whole inner interval. If the inner sorts later, some short cross-lines can survive, but there is still no distinct offset nested block. This is sufficient source evidence for the reported symptom; it does not depend on a guessed GPU bug.
+
+`Scene::hit` (`:1848–1858`) searches empty-title boxes in reverse order after message/header checks. Thus the same overlap makes a click select whichever Call's bar was appended last, regardless of intended nested identity. A paint-only color tweak would leave interaction ambiguity.
+
+### 2. Messages are attached to lane center, not to a distinct activation boundary
+
+Occurrence geometry (`:1505–1531`) derives call/reply polyline endpoints from lane x positions. Birth/death rendering later adjusts lifecycle messages, but ordinary call/reply endpoints remain at the lane center. Offsetting activation rectangles alone would leave the arrowhead or reply origin disconnected from the corresponding block, or passing through the wrong block.
+
+Therefore the correction needs a shared call-activation geometry association for draw, message endpoints and hit testing, retaining the original occurrence/correlation IDs. The semantics do not require a new persistent activation model record merely to render that association.
+
+### 3. Recursive/self-call activation starts at the send row, 24 units above its receive endpoint
+
+The self-message polyline ends at `(x, y+24)` (`:1513–1520`); its occurrence row is recorded at y. `activation_sequence` starts its receiver activation at `self.rows[call].y` (`:1710`) rather than that receive anchor. Thus a self-Call bar currently begins before its drawn receive endpoint. For ordinary horizontal calls both anchors have the same y, which hides this defect.
+
+For self-replies, termination should follow the replying activation's send anchor; the subsequent receive anchor belongs to the resumed caller. A correction that uses the same row as both events would perpetuate the recursive case and conflict with movable arrows in #20. No native reproduction was performed here; the 24-unit mismatch is directly derivable from the code.
+
+### 4. Existing fragment and lifetime behavior is meaningful and must be preserved
+
+`activation_sequence` splits an inherited activation across Fragment operands, identifies a Reply by its exact correlation, stops branch-local segments at matching Reply/Delete, and leaves a visible unresolved cue for open continuations. ALT resumes when a path can remain open; PAR, OPT and LOOP have distinct continuation rules (`:1755–1787`). These are not interchangeable flattened vertical intervals.
+
+`scenario_lifecycle/render.rs:154–174` clips activation spans to the receiver's Alive intervals in the same scope. An uncreated/dead/unresolved lifetime must not gain a visually asserted active span through the correction. Create/Delete markers paint after ordinary bars/messages, with their original occurrence identity.
+
+Existing tests (`behavior.rs:direct_alt_execution_stops_each_operand_at_its_reply_and_marks_open_operand` and `direct_execution_span_ends_at_its_correlated_reply_and_marks_an_open_call`) check span ends, operand splits and unresolved cues for one Call. They do not test two overlapping same-receiver activations, UUID permutation, endpoint attachment or distinguishable hit regions. They therefore do not disprove the reported defect.
+
+## Semantic boundary: what nesting must and must not imply
+
+`docs/language.rst:678–701` requires Reply to reference a preceding Call on a guaranteed common path, reverse its actual lifelines, and avoid duplicate replies that may follow on one shared execution path. It does not impose a LIFO stack between replies to different Calls. Rendering should not silently change that contract.
+
+The issue's y1<y2<y3<y4 correlations form strictly nested intervals, so an offset inner block is well justified. A crossing case Call1,Call2,Reply1,Reply2 must still preserve both admitted correlations. Treat it as two overlapping active intervals with separate visible tracks, not as a proof that Call2 is semantically invoked by Call1 or a reason to rewrite which Reply completes which Call. Calls from two different senders can overlap on one receiver without their senders being part of one execution stack.
+
+Likewise, different ALT operands are exclusive paths; screen stacking does not make their Calls nested. PAR operands are not a fabricated total execution order. Track assignment should be scoped by branch-path compatibility and inherited open activations, not by raw rectangle containment across the entire flattened canvas.
+
+## Primary comparison evidence, with limits
+
+The official [Sirius sequence-editor specification](https://help.eclipse.org/latest/topic/org.eclipse.sirius.doc/doc/specifier/sequences/Sequence%20Diagrams.html) describes executions with start and finish events, recursive execution containment, and mappings that connect those events to graphical elements. It also separates graphical ordering from semantic ordering and requires them to remain coherent. This supports an explicit event/activation geometry mapping and nested border-node treatment rather than painting multiple indistinguishable rectangles on a lifeline. It does not independently establish how the user's installed Capella version renders this particular model.
+
+Official [Capella features](https://mbse-capella.org/features.html) distinguishes functional, exchange and interface scenarios by their lifeline/message meanings. The same geometric nested-activation correction should therefore be assessed against supported Studio scenario viewpoints rather than assuming every Call is a software operation.
+
+The official [Sirius historical release notes](https://help.eclipse.org/latest/topic/org.eclipse.sirius.doc/doc/Release_Notes_Previous.html) describe direct execution resizing within operands with enclosing containers growing as needed, and sequence-diagram control of geometry to preserve semantic ordering. That is relevant to #20 compatibility: editable geometry can remain constrained by event/ownership semantics. It is not evidence of current native Capella affordances. Peer owner retains the requested comparable native exploration; this report does not duplicate it.
+
+## Independently derived acceptance expectations
+
+Fixture identity/correlation maps should be handwritten separately from the renderer's output. Use exact Call/Reply IDs, lane IDs, scope paths and stored order. Tests must check observable visible geometry and selection, not only count BoxItems or confirm no panic.
+
+| Case | Independent expected behavior |
+| --- | --- |
+| Exact user case, L1 left of L2 | With order C1,C2,R2,R1 and correlations R2→C2,R1→C1, show outer receiver activation from C1 receive to R1 send; inner activation from C2 receive to R2 send. Inner block has a visible offset boundary, and each Call/Reply endpoint attaches to its own block. A point in each exposed strip selects the corresponding Call. |
+| Mirrored user case | Exchange the physical left/right lane positions while retaining the same message/correlation identities. The two spans remain visibly distinct and correctly attached. An implementation must not assume sender is left of receiver. |
+| UUID permutation | Reidentify or construct IDs so C1 sorts before C2, then so C1 sorts after C2, while preserving each model's equivalent order/correlations. Geometric layout and which block appears on top must be equivalent modulo identities. Neither paint nor hit precedence may switch arbitrarily with ID order. |
+| Three nested Calls to same receiver | C1,C2,C3,R3,R2,R1 produces three visible, separately selectable intervals, with each inner receive/send attachment at its own depth. Ending C3 does not end C2/C1. |
+| Nonoverlapping repeat | C1,R1,C2,R2 reuses the base track when no interval overlaps. Do not accumulate horizontal indentation permanently by chronological Call count. |
+| Crossing overlap | C1,C2,R1,R2 retains each explicit correlation and shows both active intervals without hiding one. Do not change semantic order or fabricate LIFO rejection. If the core rejects a particular fixture for an independent channel/viewpoint reason, repair that fixture rather than interpreting the unrelated rejection as a stack rule. |
+| Opposite-direction reentrancy | C1 L1→L2, C2 L2→L1, C3 L1→L2, then R3,R2,R1. On L2, C3 overlaps C1 and needs a distinguishable nested/overlap track; C2 belongs to L1. Per-lane identity and reply association remain exact. |
+| Recursive self-call | C1 L→L, C2 L→L, R2 L→L, R1 L→L. Every activation begins at its Call's actual receive endpoint (currently y+24 for the elbow), not its send row; each terminates at its correlated Reply's send endpoint. Elbows clear all live activation tracks and their arrowheads land on the correct boundaries. |
+| ALT with inherited outer Call | Outer C1 precedes ALT. Operand A contains C2,R2,R1; operand B contains its own C3,R3 and leaves C1 open. Distinct inner tracks coexist with branch-local C1 segments. No C1 segment joins across operand headers; no activation depth leaks from A into B. Only B/possible continuation remains unresolved. |
+| PAR and optional/repeated fragments | Test independent Calls in separate PAR operands and an inherited outer Call under OPT/LOOP. Preserve current valid/invalid correlation rules and uncertainty cues. Different screen operand rows do not manufacture nesting or serialize concurrent paths. An optional/repeated Reply cannot assert guaranteed completion. |
+| Delayed creation/deletion | Create L2, then C1,C2,R2,R1,Delete L2: no activation before birth/after death; both nested intervals remain visible while alive. Separate warning-admitted unresolved-lifetime case retains neutral gaps. If Delete occurs while a Call remains open and is admitted, it clips the visible activation at death and preserves unresolved-call indication, never a false Reply cap. |
+| Unreplied inner/outer | C1,C2 with missing R2 and/or R1 retains separate identifiable incomplete indications where current semantics permit. Do not use a guessed end to merge or hide the two calls. |
+| Viewpoint/layer and typography | Exercise at least ordinary OA exchange scenario and SA boundary/interface Call with actual operation identity. Same geometry invariant, no alias/name correlation guessing. Repeat with long and Unicode labels, 100%,125%,pan and minimum supported window; label backgrounds, markers and selection do not erase the exposed block boundary. |
+| Passive and edited layout | Query/render/select/pan/zoom preserves complete Project, accepted source envelope, source buffers and undo/redo history. In the future #20 layout representation, move lane coordinates or message geometry while retaining correlation/order; the same event-based activation association follows the chosen anchors and survives save/reopen without adding semantic edges or silently reordering steps. |
+
+Geometric oracle for the minimal issue: let receive/send anchors be (xC1,y1),(xC2,y2),(xR2,y3),(xR1,y4) with y1<y2<y3<y4. Verify C1 spans [y1,y4], C2 spans [y2,y3], the bars are not identical in x range, both expose a drawable and selectable boundary during overlap, and R2 remains associated with C2. No required absolute pixel width/offset is imposed here; the implementation must demonstrate legibility at the actual tested scale. A screenshot alone is insufficient to prove identity selection; a hit geometry assertion alone is insufficient to establish visible contrast.
+
+## Bounded correction candidates and tradeoffs
+
+| Candidate | Benefits | Falsification / limitation | Assessment |
+| --- | --- | --- | --- |
+| Sort existing boxes and recolor selected inner bar | Smallest local edit | Same x range remains; one bar occludes another, hit ambiguity persists, recursive anchor still wrong | Insufficient. Useful only as part of a geometric correction. |
+| Add derived ActivationSegment metadata, then assign deterministic receiver-local visible tracks and shared message anchors | Reuses existing correlation/branch/lifetime traversal; can separate segment derivation from display geometry and keep source untouched; supports exposed hits and endpoints | Must carry scope/path and start/end event identity, handle crossing intervals and inherited branches, and prove opposite direction/self-call; naive global y nesting would be wrong | Leading bounded correction. Preserve current scope-aware clipping and add one authoritative geometry product consumed by paint/hit/routing. |
+| Replace current activation traversal with a full execution-tree/stack semantic model | May support richer execution semantics later | More than user requested; a stack can reject permitted crossing Calls; new persistent execution identities complicate textual/API parity and #20 layout | Defer unless actual requirements establish new semantic executions. Rendering nested activations does not itself authorize a metamodel change. |
+| Persistent manual activation rectangles | Can be visually adjusted | Duplicates derivable lifetime/correlation data, invites stale ends after Reply edits, and shifts the original defect to users | Reject as correction; #20 can persist presentation offsets/anchors without making manual rectangles semantic authority. |
+
+Suggested bounded implementation shape: retain existing activation_sequence's branch/correlation traversal, but emit typed records `(call, receiver, scope/path, start/end event anchors, termination state)` before reducing to rectangles. Derive track assignment from comparable active intervals, with stable stored-event order as the primary ordering. Resolve lane positions and message send/receive anchors in a layout pass, then use the same rectangles/anchors for paint, hit targets and navigation bounds. Lifeline birth/death clipping remains explicit. This is an architectural candidate, not reviewed implementation or a mandatory API.
+
+For #20 compatibility, treat `lane_x`, event rows and actual message anchor positions as inputs to geometry rather than deriving activations from hardcoded row offsets forever. Persistent layout fields (when specified by #20) remain presentation data and must not replace `reply_to` or sequence/branch ownership. Do not compute semantic nesting from whichever y coordinates the user dragged on screen.
+
+## Verification status and handoff
+
+The fixed-width overlap, UUID-driven precedence, lane-center attachment and self-call 24-unit start mismatch are verified source facts. The user's image is consistent with them. No runtime reproduction, prototype, correction, automated test pass, native Capella comparison or release acceptance is claimed. Peer956 owns implementation; root should consolidate this evidence with the peer's reproduction and compare its final geometry/hit changes against the independent matrix before integration. Existing single-call/ALT/lifecycle evidence can be reused for unchanged invariants, but same-lane nesting, recursive anchors and UUID independence need new checks.