@memoarchitect/tools 0.13.2 → 0.15.0

package/packages/tools/lib/stage2/build-from-api.js

@@ -0,0 +1,1462 @@
+// ─── Stage 2: the MEMO graph from stage 1's API JSON ─────────────────────────
+//
+// `buildMemoModel` (model/builder.ts) reads MEMO's own Langium syntax trees. This
+// builds the same graph from the OMG API JSON a SysML compiler hands stage 2,
+// through `ApiModel`, so MEMO no longer needs a SysML parser of its own
+// (plans/memo-compiler-stages-opensysml.md, milestone 2, slice 2d).
+//
+// It is being built one family at a time, each held to
+// `scripts/diff-memo-graph.mjs` against the Langium builder's output. This slice
+// is ELEMENTS: which declarations become MEMO elements, their ids, kinds,
+// constructs, layers, attributes, docs, ports and parameters. Relationships
+// (connections, flows, bindings, allocations, successions, satisfy/verify) are
+// the next slice; `composes` edges synthesized from nesting come with them.
+//
+// The rules below are the Langium builder's, restated over the metamodel. Where
+// one is a rule about MEMO (what becomes an element, what a kind is) it is kept;
+// where it was a workaround for the grammar's shape it has no counterpart here,
+// because the metamodel already says what the grammar had to infer.
+// ─────────────────────────────────────────────────────────────────────────────
+import { CONTROL_KIND_METACLASS } from '../model/activity-notation.js';
+import { completeModel } from '../model/complete-model.js';
+import { toModelType } from '../model/naming.js';
+import { LANGUAGE_NATIVE_RELATIONS, REFINEMENT_METADATA, pascalToCamelCase } from '../model/relationship-registry.js';
+import { ElementIndex, qualifiedId } from '../model/element-index.js';
+import { resolveLayerFromPath } from '../model/layer-resolver.js';
+import { textualName } from './sysml-names.js';
+/** The definition metaclasses whose project declarations become elements, and their construct. */
+const DEFINITION_CONSTRUCTS = {
+    PartDefinition: 'part',
+    PortDefinition: 'port',
+    InterfaceDefinition: 'interface',
+    ConnectionDefinition: 'connection',
+    RequirementDefinition: 'requirement',
+    VerificationCaseDefinition: 'verification',
+    StateDefinition: 'state',
+    AttributeDefinition: 'attribute',
+    EnumerationDefinition: 'enumeration',
+    UseCaseDefinition: 'use case',
+};
+/** The usage metaclasses a package member becomes an element as, and its construct. */
+const USAGE_CONSTRUCTS = {
+    PartUsage: 'part',
+    RequirementUsage: 'requirement',
+    ItemUsage: 'item',
+    UseCaseUsage: 'use case',
+    VerificationCaseUsage: 'verification',
+    StateUsage: 'state',
+    PortUsage: 'port',
+    ViewUsage: 'view',
+    ConcernUsage: 'concern',
+};
+/** Standard metadata whose field name differs from the flat key MEMO reads. */
+const METADATA_KEY_ALIASES = {
+    Rationale: { text: 'rationale' },
+};
+const lastSegment = (qualifiedName) => qualifiedName.slice(qualifiedName.lastIndexOf('::') + 2);
+/**
+ * The finished MEMO model from a stage 1 handoff: what `buildMemoModel` returns
+ * from MEMO's own parse, finished by the same `completeModel`.
+ *
+ * `unresolvedReferences` is left empty on purpose: it reports qualified names
+ * that do not resolve, and stage 2 only ever runs on a stage 1 that resolved
+ * everything.
+ */
+export function buildMemoModelFromApi(api, config, registries, 
+/**
+ * The files MEMO's project resolution counts as project source, relative to
+ * the project root. A file the handoff carries as project content can still
+ * be a resolved library root (a project's own `methodology/`), which
+ * `memo validate` leaves out of the model; absent, every project file counts.
+ */
+projectFiles) {
+    const builder = new ElementBuilder(api, registries, projectFiles);
+    builder.run();
+    builder.buildRelationships();
+    return completeModel({
+        elements: builder.elements,
+        relationships: builder.relationships,
+        errors: [],
+        config,
+        registries,
+        packages: builder.packages(),
+        lineOfRelationship: relationship => builder.lineOf(relationship),
+    });
+}
+/** Build MEMO's elements AND relationships from a stage 1 handoff. */
+export function buildFromApi(api, registries) {
+    const builder = new ElementBuilder(api, registries);
+    builder.run();
+    builder.buildRelationships();
+    return { elements: builder.elements, relationships: builder.relationships, diagnostics: builder.diagnostics };
+}
+/**
+ * Build MEMO's elements from a stage 1 handoff. `registries` are the ontology's,
+ * loaded exactly as `buildMemoModel`'s caller loads them.
+ */
+export function buildElementsFromApi(api, registries) {
+    const builder = new ElementBuilder(api, registries);
+    builder.run();
+    return { elements: builder.elements };
+}
+/**
+ * A definition's flat attribute map and doc comment, read exactly as the
+ * builder reads them for model elements: declared attributes, then metadata
+ * applications (`@MemoIdentity { :>> providedId = … }`) over them. The rule
+ * loader reads ontology rules through this, so stage 2 needs no parser.
+ */
+export function apiDefinitionFacts(api, definition) {
+    const builder = new ElementBuilder(api);
+    return { attributes: builder.attributesOf(definition), doc: builder.docOf(definition) };
+}
+class ElementBuilder {
+    api;
+    registries;
+    projectFiles;
+    elements = new ElementIndex();
+    relationships = [];
+    diagnostics = [];
+    counter = 0;
+    /** The line each relationship is declared on, for end-kind findings. */
+    relationshipLines = new Map();
+    /** API element → the MEMO element it became, including anonymous ones (a `terminate`). */
+    idOf = new Map();
+    constructor(api, registries, projectFiles) {
+        this.api = api;
+        this.registries = registries;
+        this.projectFiles = projectFiles;
+    }
+    run() {
+        for (const root of this.projectRootPackages())
+            this.visitPackage(root, '', undefined);
+        this.inheritKindsFromLocalDefinitions();
+    }
+    /** Top-level packages the project declares. */
+    projectRootPackages() {
+        const roots = [];
+        for (const element of this.api.projectElements()) {
+            if (element['@type'] !== 'Namespace')
+                continue; // a document's root namespace
+            if (this.projectFiles && !this.projectFiles.has(this.file(element)) && !this.api.isDependency(element['@id']))
+                continue;
+            for (const member of this.api.ownedMembers(element['@id'])) {
+                if (member['@type'] === 'Package' || member['@type'] === 'LibraryPackage')
+                    roots.push(member);
+            }
+        }
+        return roots;
+    }
+    file(element) {
+        return (this.api.isDependency(element['@id']) ? this.api.dependencyFile(element['@id']) : undefined)
+            ?? this.api.source(element['@id'])?.file ?? '';
+    }
+    visitPackage(pkg, parent, folder) {
+        const name = this.api.name(pkg['@id']) ?? '';
+        const packageName = parent ? `${parent}::${name}` : name;
+        const isLibrary = pkg['@type'] === 'LibraryPackage';
+        // Only nested packages present as folders; the top-level package is the root.
+        const folderLabel = parent ? this.folderLabel(pkg, name) : undefined;
+        void folder;
+        for (const member of this.api.ownedMembers(pkg['@id'])) {
+            const type = member['@type'];
+            if (type === 'Package' || type === 'LibraryPackage') {
+                this.visitPackage(member, packageName, folderLabel);
+                continue;
+            }
+            if (!this.api.name(member['@id']))
+                continue;
+            const definition = DEFINITION_CONSTRUCTS[type];
+            if (definition) {
+                // A library package's definitions are types for other models,
+                // not this model's content; they stay kinds.
+                if (isLibrary)
+                    continue;
+                this.definition(member, definition, packageName);
+                continue;
+            }
+            if (type === 'ActionDefinition' || type === 'CalculationDefinition') {
+                if (!isLibrary)
+                    this.actionDefinition(member, packageName);
+                continue;
+            }
+            if (type === 'ItemDefinition') {
+                if (!isLibrary)
+                    this.itemDefinition(member, packageName);
+                continue;
+            }
+            if (type === 'ActionUsage' || type === 'CalculationUsage') {
+                this.action(member, packageName, undefined);
+                continue;
+            }
+            if (type === 'ViewpointUsage') {
+                this.viewpoint(member, packageName, undefined);
+                continue;
+            }
+            if (type === 'TransitionUsage') {
+                this.transition(member, packageName, undefined);
+                continue;
+            }
+            if (type === 'InterfaceUsage' && this.connectorEnds(member).length >= 2)
+                continue; // an edge: next slice
+            const construct = type === 'InterfaceUsage' ? 'interface' : USAGE_CONSTRUCTS[type];
+            if (construct) {
+                const id = this.usage(member, construct, packageName, undefined);
+                const element = this.elements.get(id);
+                if (element && folderLabel && ['part', 'requirement', 'item', 'verification'].includes(construct)) {
+                    element.attributes['elementPackage'] = folderLabel;
+                }
+            }
+        }
+    }
+    /** A folder's label: an explicit `Matrix folder:` doc line, else the package name tidied. */
+    folderLabel(pkg, name) {
+        const doc = this.doc(pkg);
+        const match = doc?.match(/Matrix folder:\s*(.+)/);
+        return match ? match[1].trim() : name.replace(/^folder_/, '').replace(/_/g, ' ');
+    }
+    // ─── Kinds ──────────────────────────────────────────────────────────────
+    /** Registry first; a qualified name falls back to its last segment, as `resolveKindDef` does. */
+    resolveKind(typeName) {
+        const registry = this.registries?.kindRegistry;
+        if (!typeName || !registry)
+            return { kind: typeName, layer: undefined };
+        const entry = registry.getKind(typeName) ?? registry.getKind(lastSegment(typeName));
+        return entry
+            ? { kind: registry.getKind(typeName) ? typeName : lastSegment(typeName), layer: entry.layer }
+            : { kind: typeName, layer: undefined };
+    }
+    /** The type a usage names, spelled as MEMO stores it: the type's own name. */
+    typeName(element) {
+        const type = this.api.types(element['@id'])[0] ?? this.api.conjugatedOriginal(element['@id']);
+        return type ? this.api.name(type['@id']) : undefined;
+    }
+    superTypeName(element) {
+        const general = this.api.superclassifiers(element['@id'])[0];
+        return general ? this.api.name(general['@id']) : undefined;
+    }
+    // ─── Declarations ───────────────────────────────────────────────────────
+    definition(def, construct, packageName, ownerId) {
+        const shortName = this.api.name(def['@id']);
+        const id = qualifiedId(shortName, packageName, ownerId);
+        const superType = this.superTypeName(def);
+        const resolved = superType ? this.resolveKind(superType) : undefined;
+        const attributes = this.attributes(def);
+        if (def.isVariation === true)
+            attributes.isVariation = 'true';
+        this.define({
+            id, shortName, name: displayNameOf(attributes, shortName),
+            kind: resolved?.kind ?? `${construct.charAt(0).toUpperCase()}${construct.slice(1)}Definition`,
+            construct, layer: resolved?.layer || 'unknown', file: this.file(def), package: packageName || undefined,
+            attributes, doc: this.doc(def), isDefinition: true, owner: ownerId,
+        }, def);
+        if (['part', 'port', 'interface', 'connection'].includes(construct)) {
+            this.ports(def, packageName, id);
+            this.nestedParts(def, packageName, id);
+        }
+    }
+    itemDefinition(def, packageName) {
+        const shortName = this.api.name(def['@id']);
+        const superType = this.superTypeName(def);
+        const resolved = superType ? this.resolveKind(superType) : undefined;
+        const known = resolved?.layer && resolved.layer !== 'unknown';
+        this.define({
+            id: qualifiedId(shortName, packageName, undefined), shortName, name: shortName,
+            kind: known ? resolved.kind : 'ItemDefinition', construct: 'item', isDefinition: true,
+            layer: known ? resolved.layer : resolveLayerFromPath(this.file(def)),
+            file: this.file(def), package: packageName || undefined, attributes: this.attributes(def), doc: this.doc(def),
+        }, def);
+    }
+    actionDefinition(def, packageName) {
+        const shortName = this.api.name(def['@id']);
+        const id = qualifiedId(shortName, packageName, undefined);
+        const behaviorKind = def['@type'] === 'CalculationDefinition' ? 'function' : 'action';
+        const superType = this.superTypeName(def);
+        const resolved = superType ? this.resolveKind(superType) : undefined;
+        const known = resolved?.layer && resolved.layer !== 'unknown';
+        const parameters = this.parameters(def);
+        this.define({
+            id, shortName, name: shortName,
+            kind: known ? resolved.kind : behaviorKind === 'function' ? 'FunctionDefinition' : 'ActionDefinition',
+            construct: 'action', isDefinition: true,
+            layer: known ? resolved.layer : resolveLayerFromPath(this.file(def)),
+            file: this.file(def), package: packageName || undefined,
+            attributes: { ...this.attributes(def), behaviorKind }, doc: this.doc(def),
+            parameters: parameters.length > 0 ? parameters : undefined,
+        }, def);
+        this.behaviorBody(def, packageName, id);
+    }
+    usage(usage, construct, packageName, ownerId) {
+        const shortName = this.api.name(usage['@id']);
+        const id = qualifiedId(shortName, packageName, ownerId);
+        const typeName = this.typeName(usage);
+        const resolved = typeName ? this.resolveKind(typeName) : undefined;
+        const attributes = this.attributes(usage);
+        if (typeName)
+            attributes.usageType = typeName;
+        // Read from the handoff's own flag: SysIDE also sets `isAbstract` on a variation and OpenSysML does not.
+        if (usage.isVariation === true)
+            attributes.isVariation = 'true';
+        if (construct === 'view')
+            Object.assign(attributes, this.exposes(usage));
+        Object.assign(attributes, this.viewMetadata(usage));
+        const element = {
+            id, shortName, name: displayNameOf(attributes, shortName),
+            kind: resolved?.kind ?? 'Unknown', construct, layer: resolved?.layer || 'unknown',
+            file: this.file(usage), package: packageName || undefined, attributes, doc: this.doc(usage), owner: ownerId,
+        };
+        if (construct === 'port') {
+            const directed = this.directedFeatures(usage);
+            const directions = new Set(directed.map(f => f.direction));
+            element.portSpec = {
+                type: typeName,
+                direction: (this.direction(usage) ?? (directions.size === 1 ? directed[0]?.direction : undefined)),
+                isConjugated: this.api.ownedRelationships(usage['@id']).some(r => r['@type'] === 'ConjugatedPortTyping'),
+            };
+            element.parameters = directed;
+        }
+        this.define(element, usage);
+        if (construct === 'port')
+            this.ports(usage, packageName, id);
+        if (construct === 'part' || construct === 'item')
+            this.nestedParts(usage, packageName, id);
+        if (construct === 'part')
+            this.ports(usage, packageName, id);
+        for (const member of this.api.ownedMembers(usage['@id'])) {
+            if (member['@type'] === 'TransitionUsage')
+                this.transition(member, packageName, id);
+            else if (construct === 'state' && member['@type'] === 'StateUsage' && this.api.name(member['@id'])) {
+                this.usage(member, 'state', packageName, id);
+            }
+        }
+        return id;
+    }
+    viewpoint(usage, packageName, ownerId) {
+        const id = this.usage(usage, 'viewpoint', packageName, ownerId);
+        for (const member of this.api.ownedMembers(usage['@id'])) {
+            if (member['@type'] === 'ViewpointUsage' && this.api.name(member['@id']))
+                this.viewpoint(member, packageName, id);
+        }
+    }
+    /** An action usage. `ownerId` is a non-action owner (a part that performs it), which names it and is not its `parentAction`. */
+    action(usage, packageName, parentActionId, ownerId) {
+        const shortName = this.api.name(usage['@id']);
+        if (!shortName)
+            return;
+        const id = qualifiedId(shortName, packageName, parentActionId ?? ownerId);
+        const behaviorKind = usage['@type'] === 'CalculationUsage' ? 'function' : 'action';
+        const typeName = this.typeName(usage);
+        let kind = behaviorKind === 'function' ? 'FunctionUsage' : 'ActionUsage';
+        let layer = resolveLayerFromPath(this.file(usage));
+        if (typeName) {
+            const resolved = this.resolveKind(typeName);
+            if (resolved.layer && resolved.layer !== 'unknown') {
+                kind = resolved.kind;
+                layer = resolved.layer;
+            }
+        }
+        const subsetted = this.api.subsetted(usage['@id'])[0];
+        if (!typeName && subsetted && parentActionId && layer === 'unknown') {
+            layer = this.elements.get(parentActionId)?.layer ?? layer;
+        }
+        const attributes = this.attributes(usage);
+        attributes.behaviorKind = behaviorKind;
+        if (typeName) {
+            attributes.actionType = typeName;
+            attributes.usageType = typeName;
+        }
+        if (subsetted)
+            attributes.subsets = this.api.name(subsetted['@id']) ?? '';
+        this.define({
+            id, shortName, name: displayNameOf(attributes, shortName), kind, construct: 'action', layer,
+            file: this.file(usage), package: packageName || undefined, attributes, doc: this.doc(usage),
+            parentAction: parentActionId, owner: ownerId, parameters: this.parameters(usage),
+        }, usage);
+        this.behaviorBody(usage, packageName, id);
+    }
+    /** Nested steps of an action body: actions and control nodes. */
+    behaviorBody(owner, packageName, parentActionId) {
+        let terminates = 0;
+        for (const member of this.api.ownedMembers(owner['@id'])) {
+            const type = member['@type'];
+            if (type === 'ActionUsage' || type === 'CalculationUsage') {
+                if (this.direction(member))
+                    continue; // a parameter, not a step
+                this.action(member, packageName, parentActionId);
+            }
+            else if (type in CONTROL_METACLASS_KINDS) {
+                const name = this.api.name(member['@id']);
+                if (!name)
+                    continue;
+                const controlKind = CONTROL_METACLASS_KINDS[type];
+                this.define({
+                    id: qualifiedId(name, packageName, parentActionId), shortName: name, name,
+                    kind: CONTROL_KIND_METACLASS[controlKind], construct: 'action',
+                    layer: resolveLayerFromPath(this.file(member)), file: this.file(member),
+                    package: packageName || undefined, attributes: { controlKind }, parentAction: parentActionId,
+                }, member);
+            }
+            else if (['AcceptActionUsage', 'SendActionUsage', 'TerminateActionUsage'].includes(type)) {
+                const fallback = type === 'TerminateActionUsage' ? `terminate${terminates++ === 0 ? '' : terminates}` : undefined;
+                const name = this.api.name(member['@id']) ?? fallback;
+                if (!name)
+                    continue;
+                const id = qualifiedId(name, packageName, parentActionId);
+                // An accept's payload is its parameter: `accept order : Order`.
+                const payload = type === 'AcceptActionUsage'
+                    ? this.api.ownedRelationships(member['@id'])
+                        .filter(r => r['@type'] === 'ParameterMembership')
+                        .flatMap(r => this.api.ownedMembers(member['@id']).filter(m => m['@id'] === r.memberElement?.['@id']))[0]
+                    : undefined;
+                const payloadName = payload ? this.api.name(payload['@id']) : undefined;
+                const payloadType = payload ? this.typeName(payload) : undefined;
+                this.define({
+                    id, shortName: name, name: this.api.name(member['@id']) ?? type,
+                    kind: type === 'TerminateActionUsage' ? 'ActivityFinalNodeUsage' : type,
+                    construct: 'action', layer: resolveLayerFromPath(this.file(member)), file: this.file(member),
+                    package: packageName || undefined,
+                    attributes: { ...(payloadName ? { payloadName } : {}), ...(payloadType ? { payloadType } : {}) },
+                    parentAction: parentActionId,
+                    parameters: payloadName ? [{ name: payloadName, direction: 'out', type: payloadType ?? 'Item' }] : undefined,
+                }, member);
+            }
+        }
+    }
+    transition(transition, packageName, ownerId) {
+        const shortName = this.api.name(transition['@id']);
+        if (!shortName)
+            return; // an anonymous transition is a control statement, not an element
+        // The source is the transition's first member (`FeatureChainMember`,
+        // SysML-textual-bnf.kebnf:1283): a Membership naming the state, or an
+        // owned chain feature for `first a.b`. The target is the end of the
+        // succession it owns (`then …`). Both are written as MEMO stores them,
+        // the path from the state machine down.
+        const attributes = { ...this.attributes(transition) };
+        const path = (feature) => {
+            if (!feature)
+                return undefined;
+            const steps = this.api.chain(feature['@id']);
+            return (steps.length ? steps : [feature]).map(step => this.api.name(step['@id'])).join('.');
+        };
+        const first = this.api.ownedRelationships(transition['@id'])[0];
+        let source;
+        if (first?.['@type'] === 'Membership') {
+            const member = first.memberElement;
+            source = path(member ? this.api.element(member['@id']) : undefined);
+        }
+        else if (first?.['@type'] === 'OwningMembership') {
+            const owned = first.ownedRelatedElement?.[0];
+            source = path(owned ? this.api.element(owned['@id']) : undefined);
+        }
+        const succession = this.api.ownedMembers(transition['@id']).find(m => m['@type'] === 'SuccessionAsUsage');
+        const targetEnd = succession ? this.connectorEnds(succession).at(-1) : undefined;
+        const target = targetEnd
+            ? path(this.api.related(targetEnd['@id'], ['ReferenceSubsetting'], 'referencedFeature')[0])
+            : undefined;
+        if (source)
+            attributes.sourceState = source;
+        if (target)
+            attributes.targetState = target;
+        const typeName = this.typeName(transition);
+        const resolved = typeName ? this.resolveKind(typeName) : undefined;
+        this.define({
+            id: qualifiedId(shortName, packageName, ownerId), shortName, name: attributes.name || shortName,
+            kind: resolved?.kind ?? 'Unknown', construct: 'transition', layer: resolved?.layer || 'unknown',
+            file: this.file(transition), package: packageName || undefined, attributes, doc: this.doc(transition), owner: ownerId,
+        }, transition);
+    }
+    /** Port usages an owner declares, each an element owned by it. */
+    ports(owner, packageName, ownerId) {
+        const owned = [];
+        for (const member of this.api.ownedMembers(owner['@id'])) {
+            if (member['@type'] !== 'PortUsage' || !this.api.name(member['@id']))
+                continue;
+            const id = this.usage(member, 'port', packageName, ownerId);
+            if (this.elements.has(id))
+                owned.push(id);
+        }
+        const element = this.elements.get(ownerId);
+        if (owned.length > 0 && element)
+            element.ownedPorts = owned;
+    }
+    /** Typed nested parts and undirected items: containment, owned by the owner. */
+    nestedParts(owner, packageName, ownerId) {
+        for (const member of this.api.ownedMembers(owner['@id'])) {
+            const type = member['@type'];
+            if (type === 'Package') {
+                this.groupingPackage(member, packageName, ownerId);
+                continue;
+            }
+            const isPart = type === 'PartUsage';
+            const isItem = type === 'ItemUsage' && !this.direction(member);
+            if (!isPart && !isItem)
+                continue;
+            // A connection definition's `end part source : T` is an end, not a part it contains.
+            if (member.isEnd === true)
+                continue;
+            // Only a TYPED nested usage is containment; an untyped one is view metadata.
+            if (!this.api.name(member['@id']) || this.api.types(member['@id']).length === 0)
+                continue;
+            // A typed part that subsets a feature (`part mapEngine : LogicalComponent :> component`)
+            // is still a part usage the owner contains: `PartUsage` takes a `UsageDeclaration`, whose
+            // `FeatureSpecializationPart` allows typing and subsetting together
+            // (SysML-textual-bnf.kebnf:627, :312, :428). Only `viewMetadata` reads a subsetting
+            // part as a binding (`isBinding`), and so does a methodology owner, whose
+            // `part x : RulePolicy :> rulePolicy { … }` is configuration the rule-policy writer
+            // appends to the model's `ModelMethodBinding` (measured on a scratch E0, 2026-10-12).
+            if (this.api.redefined(member['@id']).length > 0)
+                continue;
+            if (this.isBinding(member) && this.elements.get(ownerId)?.layer === 'methodology')
+                continue;
+            this.usage(member, isPart ? 'part' : 'item', packageName, ownerId);
+        }
+    }
+    /** A package inside a usage groups; its members stay contained by the owner. */
+    groupingPackage(pkg, packageName, ownerId) {
+        const name = this.api.name(pkg['@id']);
+        if (!name)
+            return;
+        this.define({
+            id: qualifiedId(name, packageName, ownerId), shortName: name, name, kind: 'ElementPackage',
+            construct: 'package', layer: this.elements.get(ownerId)?.layer ?? 'unknown',
+            file: this.file(pkg), package: packageName, attributes: {}, owner: ownerId,
+        }, pkg);
+        for (const member of this.api.ownedMembers(pkg['@id'])) {
+            const isPart = member['@type'] === 'PartUsage';
+            const isItem = member['@type'] === 'ItemUsage' && !this.direction(member);
+            if ((!isPart && !isItem) || !this.api.name(member['@id']) || this.api.types(member['@id']).length === 0)
+                continue;
+            const childId = this.usage(member, isPart ? 'part' : 'item', packageName, ownerId);
+            const child = this.elements.get(childId);
+            if (child)
+                child.attributes['elementPackage'] = name;
+        }
+    }
+    // ─── Features, values, metadata ─────────────────────────────────────────
+    direction(element) {
+        const direction = element.direction;
+        return typeof direction === 'string' ? direction : undefined;
+    }
+    /** Directed item features: a port's payloads, an action's parameters. */
+    directedFeatures(owner) {
+        return this.api.ownedMembers(owner['@id'])
+            .filter(m => ['ItemUsage', 'ReferenceUsage', 'AttributeUsage', 'PartUsage'].includes(m['@type']) && this.direction(m))
+            .map(m => {
+            const type = this.typeName(m);
+            const subsetted = this.api.subsetted(m['@id'])[0] ?? this.api.referenced(m['@id'])[0];
+            return {
+                name: this.api.name(m['@id']) ?? '',
+                direction: this.direction(m),
+                type: type ?? (subsetted ? this.api.name(subsetted['@id']) : undefined) ?? 'Item',
+            };
+        });
+    }
+    parameters(owner) {
+        return this.directedFeatures(owner);
+    }
+    /**
+     * The flat attribute map: every attribute or reference member with a value
+     * (or a type, or a structured body flattened to dotted keys), then metadata
+     * applications, which win over a directly declared attribute of the same name.
+     */
+    attributes(owner) {
+        const attributes = {};
+        for (const member of this.api.ownedMembers(owner['@id'])) {
+            if (member['@type'] !== 'AttributeUsage' && member['@type'] !== 'ReferenceUsage')
+                continue;
+            if (this.direction(member) || this.isBinding(member))
+                continue;
+            const name = this.api.name(member['@id']);
+            if (!name)
+                continue;
+            const value = this.api.value(member['@id']);
+            if (value) {
+                attributes[name] = this.render(value);
+                continue;
+            }
+            const type = this.typeName(member);
+            if (type && this.api.redefined(member['@id']).length === 0) {
+                attributes[name] = `<${type}>`;
+                continue;
+            }
+            for (const [key, nested] of Object.entries(this.attributes(member)))
+                attributes[`${name}.${key}`] = nested;
+        }
+        Object.assign(attributes, this.metadata(owner));
+        return attributes;
+    }
+    /**
+     * A connector's own attributes over the values its type binds. A feature value on a
+     * definition (`attribute :>> direction = DirectionKind::output;` on an `interface def`)
+     * is inherited by every usage, and the usage may not restate it (SysIDE:
+     * feature-value-overriding), so reading only the usage's own members misses it.
+     */
+    withTypeValues(node) {
+        const inherited = {};
+        const seen = new Set();
+        const visit = (definition) => {
+            if (seen.has(definition['@id']))
+                return;
+            seen.add(definition['@id']);
+            for (const parent of this.api.superclassifiers(definition['@id']))
+                visit(parent);
+            if (this.api.source(definition['@id'])?.role === 'project')
+                Object.assign(inherited, this.attributes(definition));
+        };
+        for (const type of this.api.types(node['@id']))
+            visit(type);
+        return { ...inherited, ...this.attributes(node) };
+    }
+    /** `@Foo { :>> field = value; }` applications, lifted under each field's own name. */
+    metadata(owner) {
+        const attributes = {};
+        for (const member of this.api.ownedMembers(owner['@id'])) {
+            if (member['@type'] !== 'MetadataUsage')
+                continue;
+            const type = this.typeName(member) ?? '';
+            const aliases = METADATA_KEY_ALIASES[type] ?? {};
+            for (const [field, value] of Object.entries(this.attributes(member))) {
+                if (value === '')
+                    continue;
+                attributes[aliases[field] ?? field] = value;
+            }
+        }
+        return attributes;
+    }
+    /**
+     * A part or reference member that SUBSETS a feature is a binding, not
+     * containment: `part x : T :> rulePolicy { … }` records `x = rulePolicy`, and
+     * `ref vp :> viewpointDefinition = v;` adds `v` to `viewpointDefinition`
+     * (comma-joined, since such a feature may be bound more than once).
+     */
+    isBinding(member) {
+        return (member['@type'] === 'PartUsage' || member['@type'] === 'ReferenceUsage')
+            && this.api.subsetted(member['@id']).length > 0 && this.api.redefined(member['@id']).length === 0;
+    }
+    /** View metadata members flattened onto the view: bindings and an untyped `part :>> x { … }` body. */
+    viewMetadata(owner) {
+        const attributes = {};
+        for (const member of this.api.ownedMembers(owner['@id'])) {
+            if (this.isBinding(member)) {
+                const subsetted = this.api.name(this.api.subsetted(member['@id'])[0]['@id']) ?? '';
+                const value = this.api.value(member['@id']);
+                const [key, bound] = value ? [subsetted, this.render(value)] : [this.api.name(member['@id']) ?? '', subsetted];
+                if (!key)
+                    continue;
+                attributes[key] = attributes[key] ? `${attributes[key]},${bound}` : bound;
+                continue;
+            }
+            if (member['@type'] !== 'PartUsage')
+                continue;
+            if (this.api.types(member['@id']).length > 0)
+                continue; // typed: containment
+            const name = this.api.name(member['@id']);
+            if (!name)
+                continue;
+            for (const [key, value] of Object.entries(this.attributes(member)))
+                attributes[`${name}.${key}`] = value;
+        }
+        return attributes;
+    }
+    /** A view's `expose` paths, comma-joined, as `resolveViewElementIds` reads them. */
+    exposes(view) {
+        const paths = [];
+        for (const relationship of this.api.ownedRelationships(view['@id'])) {
+            if (relationship['@type'] !== 'NamespaceExpose' && relationship['@type'] !== 'MembershipExpose')
+                continue;
+            let name;
+            if (relationship['@type'] === 'NamespaceExpose') {
+                const target = relationship.importedNamespace;
+                name = target ? this.api.qualifiedName(target['@id']) : undefined;
+                if (name)
+                    name += relationship.isRecursive ? '::**' : '::*';
+            }
+            else {
+                // A membership expose names a membership; the element is its member.
+                const membership = relationship.importedMembership;
+                const member = membership ? this.api.element(membership['@id'])?.memberElement : undefined;
+                // Written by qualified name: a short name can be ambiguous (two
+                // views may each declare a `clinician`), a qualified name never is.
+                name = member ? this.api.qualifiedName(member['@id']) : undefined;
+                if (name && relationship.isRecursive)
+                    name += '::**';
+            }
+            if (name)
+                paths.push(name);
+        }
+        return paths.length > 0 ? { expose: paths.join(',') } : {};
+    }
+    /** A value as MEMO's flat attribute map spells it. */
+    render(value) {
+        switch (value.kind) {
+            case 'string': return value.value;
+            case 'number': return renderNumber(value.value, value.rational);
+            case 'boolean': return String(value.value);
+            case 'sequence': return value.items.map(item => this.render(item)).filter(s => s.length > 0).join(', ');
+            case 'reference': {
+                // An enumeration literal is `Kind::member`, the one spelling MEMO
+                // accepts; any other reference is the referenced element's name.
+                const target = this.api.resolve(value.qualifiedName);
+                const owner = target ? this.api.owner(target['@id']) : undefined;
+                if (owner?.['@type'] === 'EnumerationDefinition') {
+                    return `${textualName(this.api.name(owner['@id']) ?? '')}::${textualName(lastSegment(value.qualifiedName))}`;
+                }
+                return lastSegment(value.qualifiedName);
+            }
+            case 'chain': return value.steps.map(lastSegment).join('.');
+            default: return '';
+        }
+    }
+    /** The flat attribute map of any element, for readers outside the builder. */
+    attributesOf(owner) { return this.attributes(owner); }
+    /** The doc comment of any element, for readers outside the builder. */
+    docOf(owner) { return this.doc(owner); }
+    doc(owner) {
+        const documentation = this.api.ownedMembers(owner['@id']).find(m => m['@type'] === 'Documentation');
+        const body = documentation?.body;
+        if (typeof body !== 'string' || !body.trim())
+            return undefined;
+        return body.replace(/^\/\*\s*/, '').replace(/\s*\*\/$/, '').replace(/\n\s*\*\s?/g, ' ').replace(/\s*\n\s*/g, ' ').trim();
+    }
+    connectorEnds(connector) {
+        return this.api.ownedMembers(connector['@id']).filter(m => m.isEnd === true
+            || this.api.ownedRelationships(m['@id']).some(r => r['@type'] === 'ReferenceSubsetting'));
+    }
+    define(element, node) {
+        this.elements.define(element, node);
+        this.idOf.set(node['@id'], element.id);
+    }
+    // ─── Relationships ──────────────────────────────────────────────────────
+    //
+    // The Langium builder's order, for the reason it gives: a named flow,
+    // binding or interface is an identity a later connection, allocation or
+    // trace may name, so those land first.
+    buildRelationships() {
+        const project = [...this.api.projectElements()];
+        const scoped = (types, where) => project
+            .filter(e => types.includes(e['@type']))
+            .map(e => ({ node: e, ...this.contextOf(e) }))
+            .filter(c => c.inPackage || c.inStructure || (where === 'package-or-action' && c.parentActionId));
+        for (const c of scoped(['FlowUsage', 'SuccessionFlowUsage'], 'package-or-action'))
+            this.flow(c.node, c.packageName, c.parentActionId);
+        for (const c of scoped(['BindingConnectorAsUsage'], 'package'))
+            this.binding(c.node, c.packageName);
+        for (const c of scoped(['InterfaceUsage'], 'package'))
+            this.interfaceEdge(c.node, c.packageName);
+        for (const c of scoped(['ConnectionUsage'], 'package'))
+            this.connection(c.node, c.packageName);
+        for (const c of scoped(['SuccessionAsUsage'], 'package-or-action'))
+            this.succession(c.node, c.packageName, c.parentActionId);
+        for (const c of scoped(['TransitionUsage'], 'package-or-action')) {
+            if (c.parentActionId && !this.api.declaredName(c.node['@id']))
+                this.guardedSuccession(c.node, c.packageName, c.parentActionId);
+        }
+        for (const c of scoped(['AllocationUsage'], 'package'))
+            this.allocation(c.node, c.packageName);
+        this.nativeTraces(project);
+        this.composition();
+    }
+    /** The enclosing package (qualified) and, when directly in an action body, that action's element id. */
+    contextOf(node) {
+        const owner = this.api.owner(node['@id']);
+        const packageName = this.packageOf(node);
+        const ownerId = owner ? this.api.qualifiedName(owner['@id']) : undefined;
+        const isPackage = owner?.['@type'] === 'Package' || owner?.['@type'] === 'LibraryPackage';
+        const isAction = ownerId !== undefined && this.elements.get(ownerId)?.construct === 'action';
+        // A part definition or usage owns its connectors and allocations; the endpoints
+        // are features it contains, which the element index names by qualified name.
+        const inStructure = owner?.['@type'] === 'PartDefinition' || owner?.['@type'] === 'PartUsage';
+        return { packageName, parentActionId: isAction ? ownerId : undefined, inPackage: isPackage, inStructure };
+    }
+    packageOf(node) {
+        for (let current = this.api.owner(node['@id']); current; current = this.api.owner(current['@id'])) {
+            if (current['@type'] === 'Package' || current['@type'] === 'LibraryPackage')
+                return this.api.qualifiedName(current['@id']) ?? '';
+        }
+        return '';
+    }
+    /** The nearest enclosing element that is a MEMO element: what owns a native usage. */
+    nearestElement(node) {
+        for (let current = this.api.owner(node['@id']); current; current = this.api.owner(current['@id'])) {
+            const id = this.api.qualifiedName(current['@id']);
+            if (id && this.elements.has(id))
+                return id;
+        }
+        return undefined;
+    }
+    /** The steps a feature reference names: a chain's, or the feature itself. */
+    steps(feature) {
+        if (!feature)
+            return [];
+        const chain = this.api.chain(feature['@id']);
+        return chain.length ? chain : [feature];
+    }
+    /**
+     * Resolve a reference to the deepest MEMO element it names, as the Langium
+     * builder's `resolvePath` does: what is left over (an action's parameter, a
+     * port's payload) is the end label. A resolved head is passed as its
+     * qualified name, which `resolvePath` matches exactly; one that is not an
+     * element (an inherited feature) falls back to its name in context.
+     */
+    endpoint(steps, context, options = {}) {
+        if (steps.length === 0)
+            return { end: '' };
+        const names = steps.map(step => this.api.name(step['@id']) ?? '');
+        const head = this.api.qualifiedName(steps[0]['@id']);
+        const reference = head && this.elements.has(head) ? [head, ...names.slice(1)].join('.') : names.join('.');
+        const walked = this.elements.resolvePath(reference, context);
+        if (walked.element)
+            return options.throughTypes ? this.throughTypes(walked) : { id: walked.id, end: walked.end };
+        if (walked.ambiguous)
+            return { end: '' };
+        // A named flow or connection is an identity too.
+        const asRelationship = this.elements.lookupRelationship(head ?? names.join('.'), context)
+            ?? this.elements.lookupRelationship(names.join('.'), context);
+        if (asRelationship)
+            return { id: asRelationship.id, end: '' };
+        // An element the project does not hold (a clause instance in the
+        // ontology) is kept by its name, as the Langium builder keeps it.
+        return { id: names.at(-1) || undefined, end: '' };
+    }
+    /**
+     * Carry a walked path on into the definitions that type it. A nested part is
+     * owned by the definition (`P::Pump::motor`), not by the usage that is typed
+     * by it, so `pump.motor` stops on `pump` until the walk follows the typing.
+     *
+     * Only for relations that name an element (`allocate`, `satisfy`, `verify`):
+     * a connector end on a slot means the slot, and is walked without this.
+     */
+    throughTypes(walked) {
+        let id = walked.id;
+        let rest = walked.end ? walked.end.split('.') : [];
+        while (rest.length > 0) {
+            const usage = this.api.resolve(id);
+            const next = usage && this.api.types(usage['@id'])
+                .map(type => this.api.qualifiedName(type['@id']))
+                .map(type => type && this.elements.get(`${type}::${rest[0]}`))
+                .find(Boolean);
+            if (!next)
+                break;
+            id = next.id;
+            rest = rest.slice(1);
+        }
+        return { id, end: rest.join('.') };
+    }
+    /** The feature a connector end references, as steps. */
+    endSteps(end) {
+        const target = this.api.related(end['@id'], ['ReferenceSubsetting'], 'referencedFeature')[0];
+        return this.steps(target);
+    }
+    sourceRangeOf(node) {
+        const source = this.api.source(node['@id']);
+        return source?.startByte !== undefined && source.endByte !== undefined
+            ? { offset: source.startByte, length: source.endByte - source.startByte } : undefined;
+    }
+    push(relationship, named, node) {
+        const line = this.api.source(node['@id'])?.line;
+        if (line !== undefined)
+            this.relationshipLines.set(relationship, line);
+        this.relationships.push(relationship);
+        if (named)
+            this.elements.defineRelationship(relationship, node);
+    }
+    nextId() { return `rel-${++this.counter}`; }
+    lineOf(relationship) { return this.relationshipLines.get(relationship); }
+    /** The packages the project declares, as `collectPackages` reports them. */
+    packages() {
+        const out = [];
+        for (const element of this.api.projectElements()) {
+            if (element['@type'] !== 'Package' && element['@type'] !== 'LibraryPackage')
+                continue;
+            const qualifiedName = this.api.qualifiedName(element['@id']);
+            if (!qualifiedName)
+                continue;
+            const separator = qualifiedName.lastIndexOf('::');
+            const attributes = this.metadata(element);
+            out.push({
+                qualifiedName,
+                name: separator === -1 ? qualifiedName : qualifiedName.slice(separator + 2),
+                ...(separator === -1 ? {} : { parent: qualifiedName.slice(0, separator) }),
+                file: this.file(element),
+                // `@ImportSource { … }` and any other metadata the package carries.
+                ...(Object.keys(attributes).length > 0 ? { attributes } : {}),
+            });
+        }
+        return out.sort((a, b) => a.qualifiedName.localeCompare(b.qualifiedName));
+    }
+    tagPorts(relationship) {
+        if (this.elements.get(relationship.sourceId)?.construct === 'port')
+            relationship.sourcePortId = relationship.sourceId;
+        if (this.elements.get(relationship.targetId)?.construct === 'port')
+            relationship.targetPortId = relationship.targetId;
+    }
+    flow(node, packageName, parentActionId) {
+        // Ends: a flow end (`from a.b`) references `a` and owns a flow feature
+        // redefining `b`; a message end is an event parameter referencing its part.
+        const endFeatures = this.api.ownedMembers(node['@id']).filter(m => m.isEnd === true
+            || (m['@type'] === 'EventOccurrenceUsage' && this.api.referenced(m['@id']).length > 0));
+        if (endFeatures.length < 2)
+            return;
+        const pathOf = (end) => {
+            const steps = this.endSteps(end);
+            const flowFeature = this.api.ownedMembers(end['@id'])
+                .map(m => this.api.redefined(m['@id'])[0]).find(Boolean);
+            return flowFeature ? [...steps, flowFeature] : steps;
+        };
+        const context = { packageName, ownerId: parentActionId };
+        const source = this.endpoint(pathOf(endFeatures[0]), context);
+        const target = this.endpoint(pathOf(endFeatures[1]), context);
+        if (!source.id || !target.id || !this.elements.hasEntity(source.id) || !this.elements.hasEntity(target.id)) {
+            this.diagnostics.push(`flow '${this.api.name(node['@id']) ?? '(anonymous)'}' has an end naming no element`);
+            return;
+        }
+        const name = this.api.declaredName(node['@id']);
+        const payload = this.api.ownedMembers(node['@id']).find(m => m['@type'] === 'PayloadFeature');
+        const kind = this.typeName(node);
+        const relationship = {
+            id: name ? qualifiedId(name, packageName || undefined, parentActionId) : this.nextId(),
+            ...(name ? { shortName: name } : {}),
+            type: 'flow', sourceId: source.id, sourceEnd: source.end, targetId: target.id, targetEnd: target.end,
+            file: this.file(node), sourceRange: this.sourceRangeOf(node), named: name ? true : undefined,
+            kind, attributes: this.attributes(node),
+            flowItem: payload ? this.typeName(payload) : undefined,
+        };
+        this.push(relationship, Boolean(name), node);
+    }
+    binding(node, packageName) {
+        const ends = this.connectorEnds(node);
+        if (ends.length < 2)
+            return;
+        const context = { packageName };
+        const source = this.endpoint(this.endSteps(ends[0]), context);
+        const target = this.endpoint(this.endSteps(ends[1]), context);
+        if (!source.id || !target.id || !this.elements.has(source.id) || !this.elements.has(target.id)) {
+            this.diagnostics.push(`binding '${this.api.name(node['@id']) ?? '(anonymous)'}' has an end naming no element`);
+            return;
+        }
+        const name = this.api.declaredName(node['@id']);
+        const attributes = this.attributes(node);
+        this.push({
+            id: name ? qualifiedId(name, packageName || undefined, undefined) : this.nextId(),
+            ...(name ? { shortName: name, named: true } : {}),
+            type: 'bind', sourceId: source.id, sourceEnd: source.end, targetId: target.id, targetEnd: target.end,
+            file: this.file(node),
+            ...(name ? { sourceRange: this.sourceRangeOf(node) } : {}),
+            ...(Object.keys(attributes).length ? { attributes } : {}),
+        }, Boolean(name), node);
+    }
+    interfaceEdge(node, packageName) {
+        const ends = this.connectorEnds(node);
+        if (ends.length < 2)
+            return; // an interface with no ends is an element
+        const context = { packageName };
+        const source = this.endpoint(this.endSteps(ends[0]), context);
+        const target = this.endpoint(this.endSteps(ends[1]), context);
+        if (!source.id || !target.id || !this.elements.has(source.id) || !this.elements.has(target.id)) {
+            this.diagnostics.push(`interface '${this.api.name(node['@id'])}' has an end naming no element`);
+            return;
+        }
+        const name = this.api.declaredName(node['@id']) ?? '';
+        const relationship = {
+            id: qualifiedId(name, packageName || undefined, undefined), shortName: name, type: 'interface',
+            sourceId: source.id, sourceEnd: source.end || 'source', targetId: target.id, targetEnd: target.end || 'target',
+            file: this.file(node), sourceRange: this.sourceRangeOf(node), named: true,
+            kind: this.typeName(node), attributes: this.withTypeValues(node),
+        };
+        this.tagPorts(relationship);
+        this.push(relationship, true, node);
+    }
+    connection(node, packageName) {
+        let ends = this.connectorEnds(node);
+        if (ends.length < 2) {
+            // `connection : T { …; connect a to b; }`: by the grammar the `connect`
+            // in a body declares a separate, nested connection, and the outer one
+            // relates nothing (plan, milestone 1 item c). MEMO's own compiler read
+            // the nested ends as the outer's, and the examples rely on it, so this
+            // reads them the same way and says so.
+            const nested = this.api.ownedMembers(node['@id'])
+                .find(m => m['@type'] === 'ConnectionUsage' && this.connectorEnds(m).length >= 2);
+            if (!nested)
+                return;
+            ends = this.connectorEnds(nested);
+            this.diagnostics.push(`${this.file(node)}:${this.api.source(node['@id'])?.line ?? '?'}: `
+                + `a 'connect' inside a connection's body declares a nested connection; it is read as this `
+                + `connection's ends. Move 'connect … to …' into the declaration.`);
+        }
+        const context = { packageName };
+        const sourceSteps = this.endSteps(ends[0]);
+        const targetSteps = this.endSteps(ends[1]);
+        const source = this.endpoint(sourceSteps, context);
+        const target = this.endpoint(targetSteps, context);
+        if (!source.id || !target.id)
+            return;
+        const typeName = this.typeName(node);
+        const name = this.api.declaredName(node['@id']);
+        const attributes = this.attributes(node);
+        const relationship = {
+            id: name ? qualifiedId(name, packageName || undefined, undefined) : this.nextId(),
+            ...(name ? { shortName: name } : {}),
+            type: typeName ? toModelType(typeName) : 'connect',
+            sourceId: source.id, sourceEnd: this.api.declaredName(ends[0]['@id']) ?? 'source',
+            targetId: target.id, targetEnd: this.api.declaredName(ends[1]['@id']) ?? 'target',
+            file: this.file(node), sourceRange: this.sourceRangeOf(node), named: name ? true : undefined,
+            attributes, flowItem: attributes.transportedItem || attributes.flowItem || undefined,
+        };
+        this.tagPorts(relationship);
+        this.push(relationship, Boolean(name), node);
+    }
+    succession(node, packageName, parentActionId) {
+        const ends = this.connectorEnds(node);
+        if (ends.length === 0 && parentActionId) {
+            // `then action b;`: the ends are implied by position — the occurrence
+            // declared before the succession and the one declared after it.
+            const [before, after] = this.neighbours(node);
+            if (before && after)
+                this.relationships.push({ id: this.nextId(), type: 'succession', sourceId: before,
+                    sourceEnd: '', targetId: after, targetEnd: '', file: this.file(node) });
+            return;
+        }
+        if (ends.length < 2)
+            return;
+        const context = { packageName, ownerId: parentActionId, file: this.file(node) };
+        const pseudo = (steps, which) => steps.length === 1 && this.api.qualifiedName(steps[0]['@id']) === `Actions::Action::${which}`;
+        const resolve = (written) => {
+            const steps = this.performedSteps(written);
+            if (pseudo(steps, 'start'))
+                return parentActionId ? `${parentActionId}__start` : '__start';
+            if (pseudo(steps, 'done'))
+                return parentActionId ? `${parentActionId}__done` : '__done';
+            // An end that references a declared element reaches it by identity,
+            // which an anonymous one (`then terminate;`) needs: it has no name.
+            const direct = steps.length === 1 ? this.idOf.get(steps[0]['@id']) : undefined;
+            if (direct && this.elements.has(direct))
+                return direct;
+            const found = this.endpoint(steps, context);
+            return found.id && this.elements.has(found.id) ? found.id : undefined;
+        };
+        // `then b;` with no `first`: a compiler may write the implied ends out
+        // (OpenSysML does, with the source end naming nothing), so an end that
+        // refers to nothing takes the occurrence before or after it by position.
+        const [before, after] = parentActionId ? this.neighbours(node) : [undefined, undefined];
+        const sourceSteps = this.endSteps(ends[0]);
+        const targetSteps = this.endSteps(ends[1]);
+        const sourceId = sourceSteps.length === 0 ? before : resolve(sourceSteps);
+        const targetId = targetSteps.length === 0 ? after : resolve(targetSteps);
+        if (!sourceId || !targetId)
+            return;
+        this.relationships.push({
+            id: this.nextId(), type: 'succession', sourceId, sourceEnd: '', targetId, targetEnd: '', file: this.file(node),
+        });
+    }
+    /**
+     * The steps a succession end reaches. `first actClean then …` written where
+     * the body declares `perform actClean;` names that perform usage, by the
+     * name it takes from the action it performs (SysML name resolution finds
+     * the local member first); the step MEMO records is the performed action,
+     * the feature the perform's reference subsetting references.
+     */
+    performedSteps(steps) {
+        const last = steps.at(-1);
+        if (!last || last['@type'] !== 'PerformActionUsage')
+            return steps;
+        const performed = this.api.related(last['@id'], ['ReferenceSubsetting'], 'referencedFeature')[0];
+        if (!performed)
+            return steps;
+        const chain = this.api.chain(performed['@id']);
+        return chain.length ? chain : [performed];
+    }
+    /** The MEMO elements declared immediately before and after a member of its owner. */
+    neighbours(node) {
+        const owner = this.api.owner(node['@id']);
+        if (!owner)
+            return [undefined, undefined];
+        const members = this.api.ownedMembers(owner['@id']);
+        const at = members.findIndex(m => m['@id'] === node['@id']);
+        const step = (m) => this.idOf.get(m['@id']);
+        const before = members.slice(0, at).reverse().map(step).find(Boolean);
+        const after = members.slice(at + 1).map(step).find(Boolean);
+        return [before, after];
+    }
+    /**
+     * `succession first a if g then b;` is a guarded succession, which SysML
+     * makes a TransitionUsage (SysML-textual-bnf.kebnf, GuardedSuccession). MEMO
+     * records it as a succession whose source end is the guard, `[g]`.
+     */
+    guardedSuccession(node, packageName, parentActionId) {
+        const context = { packageName, ownerId: parentActionId };
+        const first = this.api.ownedRelationships(node['@id'])[0];
+        const sourceFeature = first?.['@type'] === 'Membership'
+            ? this.api.element(first.memberElement?.['@id'] ?? '') : undefined;
+        const succession = this.api.ownedMembers(node['@id']).find(m => m['@type'] === 'SuccessionAsUsage');
+        const targetEnd = succession ? this.connectorEnds(succession).at(-1) : undefined;
+        const source = this.endpoint(this.steps(sourceFeature), context);
+        const target = targetEnd ? this.endpoint(this.endSteps(targetEnd), context) : { id: undefined };
+        if (!source.id || !target.id || !this.elements.has(source.id) || !this.elements.has(target.id))
+            return;
+        const guardMembership = this.api.ownedRelationships(node['@id'])
+            .find(r => r['@type'] === 'TransitionFeatureMembership' && r.kind === 'guard');
+        const guard = guardMembership
+            ? this.expressionText((guardMembership.ownedRelatedElement ?? [])[0]?.['@id'])
+            : undefined;
+        this.relationships.push({ id: this.nextId(), type: 'succession', sourceId: source.id,
+            sourceEnd: guard === undefined ? '' : `[${guard}]`, targetId: target.id, targetEnd: '', file: this.file(node) });
+    }
+    /** An expression as readable text, as MEMO labels a guard: `validUser == true`. */
+    expressionText(id) {
+        const expression = id ? this.api.element(id) : undefined;
+        if (!expression)
+            return undefined;
+        switch (expression['@type']) {
+            case 'LiteralBoolean': return String(expression.value);
+            case 'LiteralInteger':
+            case 'LiteralRational': return String(expression.value);
+            case 'LiteralString': return `"${expression.value}"`;
+            case 'FeatureReferenceExpression':
+            case 'FeatureChainExpression': {
+                const value = this.api.value(expression['@id']) ?? this.valueOfExpression(expression['@id']);
+                return value && value.kind !== 'other' ? this.render(value) : undefined;
+            }
+            case 'OperatorExpression': {
+                const operands = this.api.ownedRelationships(id)
+                    .filter(r => r['@type'] === 'ParameterMembership')
+                    .flatMap(r => (r.ownedRelatedElement ?? []))
+                    .map(operand => {
+                    const bound = this.api.ownedRelationships(operand['@id']).find(r => r['@type'] === 'FeatureValue');
+                    return this.expressionText((bound?.ownedRelatedElement ?? [])[0]?.['@id']);
+                });
+                if (operands.some(o => o === undefined))
+                    return undefined;
+                const operator = String(expression.operator);
+                return operands.length === 1 ? `${operator} ${operands[0]}` : operands.join(` ${operator} `);
+            }
+            default: return undefined;
+        }
+    }
+    /** The value of a bare expression (not a feature's), through a throwaway feature-value reading. */
+    valueOfExpression(id) {
+        return this.api.expression(id);
+    }
+    allocation(node, packageName) {
+        const ends = this.connectorEnds(node);
+        if (ends.length < 2)
+            return;
+        const context = { packageName };
+        const source = this.endpoint(this.endSteps(ends[0]), context, { throughTypes: true });
+        const target = this.endpoint(this.endSteps(ends[1]), context, { throughTypes: true });
+        if (!source.id || !target.id)
+            return;
+        const sourceElement = this.elements.get(source.id);
+        if (sourceElement)
+            sourceElement.allocatedTo = target.id;
+        // A typed allocation keeps which allocation it is (`DeploysTo`,
+        // `BuildsInto`); an unknown or absent type is the base allocation.
+        const typeName = this.typeName(node);
+        const typed = typeName ? pascalToCamelCase(typeName) : undefined;
+        const registry = this.registries?.relationshipRegistry;
+        const type = typed && registry?.has(typed) ? typed : 'allocatedTo';
+        const ends2 = type === 'allocatedTo'
+            ? LANGUAGE_NATIVE_RELATIONS.allocatedTo.ends
+            : registry?.getRelType(type)?.ends ?? [];
+        this.relationships.push({
+            id: this.nextId(), type, sourceId: source.id, sourceEnd: ends2[0]?.name ?? 'source',
+            targetId: target.id, targetEnd: ends2[1]?.name ?? 'target', file: this.file(node),
+        });
+    }
+    native(name, sourceId, targetId, file, attributes = {}, declaration) {
+        const [sourceEnd, targetEnd] = LANGUAGE_NATIVE_RELATIONS[name].ends;
+        this.relationships.push({
+            id: this.nextId(), type: name, sourceId, sourceEnd: sourceEnd.name, targetId, targetEnd: targetEnd.name, file,
+            // Metadata applied to the link (`satisfy r by x { @TraceBaseline { … } }`), as a typed connection carries it.
+            ...(Object.keys(attributes).length > 0 ? { attributes } : {}),
+            // Where the statement is, for a writer that edits it in place. Only a statement that is its own
+            // declaration has one; an owner-rooted `verify` or `perform` is a member of something larger.
+            ...(declaration ? { sourceRange: this.sourceRangeOf(declaration) } : {}),
+        });
+    }
+    /**
+     * The action a `perform` declares in place. `perform action n : T;` has no
+     * reference subsetting (SysML-textual-bnf.kebnf:952-955, the second
+     * alternative of PerformActionUsageDeclaration), so the usage is itself the
+     * action performed: the abstract syntax's `performedAction` is the
+     * `ownedReferenceSubsetting`'s feature if there is one and the usage itself
+     * if not. It is an element of the model owned by the performer, and the
+     * performer performs it. An unnamed one has no identity to hold.
+     */
+    performedHere(node, owner) {
+        // The declared name: `perform action :>> clean;` takes its name from what it
+        // redefines and declares none, so it is not a new element.
+        const name = this.api.declaredName(node['@id']);
+        if (!name || !owner)
+            return undefined;
+        const id = qualifiedId(name, this.packageOf(node), owner);
+        if (!this.elements.has(id)) {
+            const ownerIsAction = this.elements.get(owner)?.construct === 'action';
+            this.action(node, this.packageOf(node), ownerIsAction ? owner : undefined, ownerIsAction ? undefined : owner);
+        }
+        return id;
+    }
+    /** `satisfy`, `verify`, `perform`, subjects, actors, dependencies, variants, constraints. */
+    nativeTraces(project) {
+        const endpointOf = (steps, node) => this.endpoint(steps, { packageName: this.packageOf(node) }, { throughTypes: true }).id;
+        const valueSteps = (value) => {
+            if (!value)
+                return [];
+            if (value.kind === 'reference')
+                return [[this.api.resolve(value.qualifiedName)].filter(Boolean)];
+            if (value.kind === 'chain')
+                return [value.steps.map(q => this.api.resolve(q)).filter(Boolean)];
+            if (value.kind === 'sequence')
+                return value.items.flatMap(valueSteps);
+            return [];
+        };
+        for (const node of project) {
+            const type = node['@type'];
+            const file = this.file(node);
+            if (type === 'SatisfyRequirementUsage') {
+                if (node.isNegated === true)
+                    continue;
+                const requirement = endpointOf(this.steps(this.api.referenced(node['@id'])[0] && this.api.related(node['@id'], ['ReferenceSubsetting'], 'referencedFeature')[0]), node);
+                const subject = this.api.ownedRelationships(node['@id']).find(r => r['@type'] === 'SubjectMembership');
+                const subjectFeature = subject ? this.api.element((subject.ownedRelatedElement ?? [])[0]?.['@id'] ?? '') : undefined;
+                const by = subjectFeature ? valueSteps(this.api.value(subjectFeature['@id']))[0] : undefined;
+                const satisfying = by ? endpointOf(by, node) : undefined;
+                if (requirement && satisfying)
+                    this.native('satisfiedBy', requirement, satisfying, file, this.metadata(node), node);
+            }
+            else if (type === 'RequirementVerificationMembership') {
+                const verified = this.api.ownedMembers(node['@id'])[0] ?? this.api.element((node.ownedRelatedElement ?? [])[0]?.['@id'] ?? '');
+                const requirement = verified ? endpointOf(this.steps(this.api.related(verified['@id'], ['ReferenceSubsetting'], 'referencedFeature')[0]), node) : undefined;
+                const owner = this.nearestElement(node);
+                if (requirement && owner)
+                    this.native('verifiedBy', requirement, owner, file);
+            }
+            else if (type === 'RequirementConstraintMembership') {
+                const constraint = this.api.element((node.ownedRelatedElement ?? [])[0]?.['@id'] ?? '');
+                const referenced = constraint ? this.api.related(constraint['@id'], ['ReferenceSubsetting'], 'referencedFeature')[0] : undefined;
+                const owner = this.nearestElement(node);
+                const target = referenced ? endpointOf(this.steps(referenced), node) : undefined;
+                if (owner && target)
+                    this.native(node.kind === 'assumption' ? 'assumes' : 'requires', owner, target, file);
+            }
+            else if (type === 'PerformActionUsage' || type === 'IncludeUseCaseUsage' || type === 'ExhibitStateUsage') {
+                const referenced = this.api.related(node['@id'], ['ReferenceSubsetting'], 'referencedFeature')[0];
+                const owner = this.nearestElement(node);
+                const target = referenced ? endpointOf(this.steps(referenced), node)
+                    : type === 'PerformActionUsage' ? this.performedHere(node, owner) : undefined;
+                const edge = type === 'PerformActionUsage' ? 'performs' : type === 'IncludeUseCaseUsage' ? 'includesStep' : 'exhibitsMode';
+                if (owner && target)
+                    this.native(edge, owner, target, file);
+            }
+            else if (type === 'FramedConcernMembership') {
+                const concern = this.api.element((node.ownedRelatedElement ?? [])[0]?.['@id'] ?? '');
+                const referenced = concern ? this.api.related(concern['@id'], ['ReferenceSubsetting'], 'referencedFeature')[0] : undefined;
+                const owner = this.nearestElement(node);
+                const target = referenced ? endpointOf(this.steps(referenced), node) : undefined;
+                if (owner && target)
+                    this.native('framesConcern', owner, target, file);
+            }
+            else if (type === 'ActionUsage' && this.api.subsetted(node['@id']).length > 0) {
+                // `action step :> fnX;` is fnX performed here; the step's owner performs it.
+                const owner = this.nearestElement(node);
+                const target = endpointOf(this.steps(this.api.subsetted(node['@id'])[0]), node);
+                if (owner && target)
+                    this.native('performs', owner, target, file);
+            }
+            else if (type === 'SubjectMembership') {
+                const ownerNode = this.api.owner(node['@id']);
+                const ownerId = ownerNode ? this.api.qualifiedName(ownerNode['@id']) : undefined;
+                if (!ownerNode || !ownerId || !this.elements.has(ownerId))
+                    continue; // a satisfy's subject, say
+                const subject = this.api.element((node.ownedRelatedElement ?? [])[0]?.['@id'] ?? '');
+                if (!subject)
+                    continue;
+                const bound = [...valueSteps(this.api.value(subject['@id'])),
+                    ...this.api.subsetted(subject['@id']).map(f => this.steps(f)),
+                    ...this.api.related(subject['@id'], ['ReferenceSubsetting'], 'referencedFeature').map(f => this.steps(f))];
+                // A requirement and a use case are ABOUT their subject; a
+                // verification case's subject is what it verifies. A use case
+                // bound to its subject (`subject :>> supportingSystem = lab;`,
+                // or `= lab.navigation` on an `include`) is the system the case is
+                // carried out with, which `verifiedBy` would claim was verified.
+                const aboutSubject = [
+                    'RequirementUsage', 'RequirementDefinition',
+                    'UseCaseUsage', 'UseCaseDefinition', 'IncludeUseCaseUsage',
+                ].includes(ownerNode['@type']);
+                // A subject declared by TYPE (`subject :>> supportingSystem : NavigationSystem;`)
+                // is about that definition: it is how a system's use case names its system. Only a
+                // definition the project holds counts. A subject bound inside an `include` is not
+                // read: the include is not an element, and its target is owned by the system of
+                // systems, so the edge would pull the system's use case into the lab's workspace.
+                const typed = aboutSubject && ownerNode['@type'] !== 'IncludeUseCaseUsage'
+                    ? this.api.types(subject['@id'])
+                        .filter(type => this.elements.has(this.api.qualifiedName(type['@id']) ?? ''))
+                        .map(type => [type])
+                    : [];
+                for (const steps of [...bound, ...typed]) {
+                    const boundId = endpointOf(steps, node);
+                    if (!boundId)
+                        continue;
+                    if (aboutSubject)
+                        this.native('hasSubject', ownerId, boundId, file);
+                    else
+                        this.native('verifiedBy', boundId, ownerId, file);
+                }
+            }
+            else if (type === 'ActorMembership') {
+                const actor = this.api.element((node.ownedRelatedElement ?? [])[0]?.['@id'] ?? '');
+                const bound = actor ? valueSteps(this.api.value(actor['@id']))[0] : undefined;
+                const owner = this.nearestElement(node);
+                const source = bound ? endpointOf(bound, node) : undefined;
+                if (source && owner)
+                    this.native('participatesIn', source, owner, file);
+            }
+            else if (type === 'Dependency') {
+                const refinement = this.api.ownedRelationships(node['@id'])
+                    .filter(r => r['@type'] === 'Annotation')
+                    .flatMap(r => this.api.ownedMembers(r['@id']).length ? this.api.ownedMembers(r['@id'])
+                    : (r.ownedRelatedElement ?? []).map(x => this.api.element(x['@id'])).filter(Boolean))
+                    .some(metadata => (this.typeName(metadata) ?? '').toLowerCase() === REFINEMENT_METADATA);
+                const ids = (key) => (node[key] ?? [])
+                    .map(r => this.api.element(r['@id'])).filter(Boolean);
+                for (const client of ids('client')) {
+                    const sourceId = endpointOf([client], node);
+                    if (!sourceId)
+                        continue;
+                    for (const supplier of ids('supplier')) {
+                        const targetId = endpointOf([supplier], node);
+                        if (!targetId)
+                            continue;
+                        const applied = this.metadata(node);
+                        // A dependency typed by a metadata def the ontology declares as a relation
+                        // (`#RealizesFeature dependency …`) is that relation, and only that: one
+                        // statement, one edge. Any other dependency stays a plain `dependency`.
+                        const typed = this.typedDependencyOf(node);
+                        if (typed) {
+                            const ends = this.registries?.relationshipRegistry?.getRelType(typed)?.ends ?? [];
+                            this.relationships.push({
+                                id: this.nextId(), type: typed, sourceId, sourceEnd: ends[0]?.name ?? 'client',
+                                targetId, targetEnd: ends[1]?.name ?? 'supplier', file,
+                                ...(Object.keys(applied).length > 0 ? { attributes: applied } : {}),
+                                sourceRange: this.sourceRangeOf(node),
+                            });
+                            continue;
+                        }
+                        this.native('dependency', sourceId, targetId, file, applied, node);
+                        if (refinement)
+                            this.native('realizes', sourceId, targetId, file, applied, node);
+                    }
+                }
+            }
+            else if (type === 'VariantMembership') {
+                const variant = this.api.element((node.ownedRelatedElement ?? [])[0]?.['@id'] ?? '');
+                const referenced = variant ? this.api.related(variant['@id'], ['ReferenceSubsetting'], 'referencedFeature')[0] : undefined;
+                const owner = this.nearestElement(node);
+                // `variant part euOut : T;` declares its variant in place and references nothing.
+                const declaredHere = variant ? this.api.qualifiedName(variant['@id']) : undefined;
+                const target = referenced ? endpointOf(this.steps(referenced), node)
+                    : declaredHere && this.elements.has(declaredHere) ? declaredHere : undefined;
+                if (owner && target)
+                    this.relationships.push({
+                        id: this.nextId(), type: 'variant', sourceId: owner, sourceEnd: 'variationPoint',
+                        targetId: target, targetEnd: 'variant', file,
+                    });
+            }
+        }
+    }
+    /**
+     * The relation a dependency's prefix metadata names, when the ontology declares that metadata def
+     * as one (`memo_core_relationships::MemoTypedDependency`): `#RealizesFeature dependency …` is
+     * `realizesFeature`. Undefined for a plain dependency or any other prefix (`#refinement`,
+     * `#EnforcesClause`).
+     */
+    typedDependencyOf(node) {
+        const registry = this.registries?.relationshipRegistry;
+        if (!registry)
+            return undefined;
+        for (const annotation of this.api.ownedRelationships(node['@id'])) {
+            if (annotation['@type'] !== 'Annotation')
+                continue;
+            const metadata = this.api.ownedMembers(annotation['@id'])[0]
+                ?? (annotation.ownedRelatedElement ?? []).map(x => this.api.element(x['@id'])).find(Boolean);
+            const name = metadata ? this.typeName(metadata) : undefined;
+            const relation = name ? registry.getRelType(pascalToCamelCase(name)) : undefined;
+            if (relation?.sysmlConstruct === 'metadata def')
+                return relation.name;
+        }
+        return undefined;
+    }
+    /** `composes` edges from native nesting: parts, items and states by owner; actions by parent action. */
+    composition() {
+        const containing = new Set(['part', 'item', 'state']);
+        for (const element of this.elements.values()) {
+            if (!containing.has(element.construct) || !element.owner)
+                continue;
+            const parent = this.elements.get(element.owner);
+            if (!parent || !containing.has(parent.construct))
+                continue;
+            this.relationships.push({ id: this.nextId(), type: 'composes', sourceId: element.owner, sourceEnd: 'parent',
+                targetId: element.id, targetEnd: 'child', file: element.file, named: false });
+        }
+        for (const element of this.elements.values()) {
+            if (element.construct !== 'action' || !element.parentAction)
+                continue;
+            const parent = this.elements.get(element.parentAction);
+            if (!parent || parent.construct !== 'action')
+                continue;
+            this.relationships.push({ id: this.nextId(), type: 'composes', sourceId: element.parentAction, sourceEnd: 'parent',
+                targetId: element.id, targetEnd: 'child', file: element.file, named: false });
+        }
+    }
+    // ─── After extraction ───────────────────────────────────────────────────
+    /** A usage typed by a local definition takes the ontology kind that definition resolved to. */
+    inheritKindsFromLocalDefinitions() {
+        const registry = this.registries?.kindRegistry;
+        if (!registry)
+            return;
+        const byName = new Map();
+        for (const [id, element] of this.elements) {
+            if (!byName.has(id))
+                byName.set(id, element);
+            if (element.shortName && !byName.has(element.shortName))
+                byName.set(element.shortName, element);
+            if (element.name && !byName.has(element.name))
+                byName.set(element.name, element);
+        }
+        for (let pass = 0; pass < 16; pass++) {
+            let progressed = false;
+            for (const element of this.elements.values()) {
+                if (!element.kind || registry.getKind(element.kind))
+                    continue;
+                const def = byName.get(lastSegment(element.kind));
+                if (def && def !== element && def.kind && def.kind !== element.kind) {
+                    element.kind = def.kind;
+                    if (def.layer && (!element.layer || element.layer === 'unknown'))
+                        element.layer = def.layer;
+                    progressed = true;
+                }
+            }
+            if (!progressed)
+                break;
+        }
+    }
+}
+/** The metamodel's control nodes, keyed to the `controlKind` MEMO records. */
+const CONTROL_METACLASS_KINDS = {
+    ForkNode: 'fork', JoinNode: 'join', DecisionNode: 'decide', MergeNode: 'merge',
+};
+function displayNameOf(attributes, shortName) {
+    return attributes['label'] || attributes['name'] || attributes['title'] || shortName;
+}
+/**
+ * A number as the source most plausibly wrote it: the JSON holds values, not
+ * spellings, so a real that is whole is written `100.0` (a rational literal
+ * always has a point) and no value is written in exponent form.
+ */
+function renderNumber(value, rational) {
+    if (!Number.isFinite(value))
+        return String(value);
+    if (rational && Number.isInteger(value))
+        return `${value}.0`;
+    const plain = value.toLocaleString('en-US', { useGrouping: false, maximumFractionDigits: 20 });
+    return plain;
+}
+//# sourceMappingURL=build-from-api.js.map