@memoarchitect/tools 0.13.2 → 0.15.0

package/packages/tools/lib/analysis/suspect-links.d.ts

@@ -0,0 +1,45 @@
+import type { MemoElement, MemoRelationship } from '../model/semantic.js';
+export type SuspectReason = 'revision-moved' | 'source-withdrawn';
+export interface SuspectLink {
+    relationshipId: string;
+    relationshipType: string;
+    /** The imported element the link is suspect about. */
+    elementId: string;
+    /** Which end of the link that element is. */
+    end: 'source' | 'target';
+    /** The revision the link was made against. */
+    baseline: string;
+    /** The element's revision now; undefined when the source no longer carries it. */
+    current: string | undefined;
+    reason: SuspectReason;
+}
+/** What a baseline says: the revision a link was made against, and the record it belongs to. */
+export interface Baseline {
+    sourceRevision: string;
+    /** The imported element the revision belongs to; absent, every imported end is compared. */
+    sourceIdentifier?: string;
+}
+/** An imported element as the comparison sees it. */
+export interface ImportedRecord {
+    identifier: string;
+    revision: string | undefined;
+    withdrawn: boolean;
+}
+/** The baseline a link carries, if it carries one. */
+export declare function baselineOf(attributes: Record<string, string> | undefined): Baseline | undefined;
+/** The imported record an element is, if it is one. */
+export declare function importedRecordOf(element: MemoElement | undefined): ImportedRecord | undefined;
+/**
+ * Whether a baseline is suspect against one imported record. The one predicate:
+ * the queue (`computeSuspectLinks`) and an import's preview both ask it, so what
+ * the preview says it will mark is what the queue then shows.
+ */
+export declare function suspectReason(baseline: Baseline, record: ImportedRecord): SuspectReason | undefined;
+/** A model the computation can read: a built one, or the DTO a client holds. */
+export interface SuspectModel {
+    relationships: readonly MemoRelationship[];
+    elements: ReadonlyMap<string, MemoElement> | Readonly<Record<string, MemoElement>>;
+}
+/** Every baselined link whose imported end has moved or been withdrawn. */
+export declare function computeSuspectLinks(model: SuspectModel): SuspectLink[];
+//# sourceMappingURL=suspect-links.d.ts.map

package/packages/tools/lib/analysis/suspect-links.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"suspect-links.d.ts","sourceRoot":"","sources":["../../src/analysis/suspect-links.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAE1E,MAAM,MAAM,aAAa,GAAG,gBAAgB,GAAG,kBAAkB,CAAC;AAElE,MAAM,WAAW,WAAW;IACxB,cAAc,EAAE,MAAM,CAAC;IACvB,gBAAgB,EAAE,MAAM,CAAC;IACzB,sDAAsD;IACtD,SAAS,EAAE,MAAM,CAAC;IAClB,6CAA6C;IAC7C,GAAG,EAAE,QAAQ,GAAG,QAAQ,CAAC;IACzB,8CAA8C;IAC9C,QAAQ,EAAE,MAAM,CAAC;IACjB,kFAAkF;IAClF,OAAO,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5B,MAAM,EAAE,aAAa,CAAC;CACzB;AAKD,gGAAgG;AAChG,MAAM,WAAW,QAAQ;IACrB,cAAc,EAAE,MAAM,CAAC;IACvB,4FAA4F;IAC5F,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED,qDAAqD;AACrD,MAAM,WAAW,cAAc;IAC3B,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7B,SAAS,EAAE,OAAO,CAAC;CACtB;AAED,sDAAsD;AACtD,wBAAgB,UAAU,CAAC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,GAAG,QAAQ,GAAG,SAAS,CAK/F;AAED,uDAAuD;AACvD,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,WAAW,GAAG,SAAS,GAAG,cAAc,GAAG,SAAS,CAI7F;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,QAAQ,EAAE,MAAM,EAAE,cAAc,GAAG,aAAa,GAAG,SAAS,CAInG;AAED,gFAAgF;AAChF,MAAM,WAAW,YAAY;IACzB,aAAa,EAAE,SAAS,gBAAgB,EAAE,CAAC;IAC3C,QAAQ,EAAE,WAAW,CAAC,MAAM,EAAE,WAAW,CAAC,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC,CAAC;CACtF;AAED,2EAA2E;AAC3E,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,YAAY,GAAG,WAAW,EAAE,CAqBtE"}

package/packages/tools/lib/analysis/suspect-links.js

@@ -0,0 +1,66 @@
+// ─── Suspect links ────────────────────────────────────────────────────────────
+//
+// A MEMO-authored link to an imported element records the revision of that
+// element it was made against (`@TraceBaseline { sourceRevision }`). The link
+// is suspect when the element has since moved on. Status is derived here from
+// attributes alone and never stored, so there is no flag to go stale; reviewing
+// a link means rewriting its baseline to the element's current revision.
+//
+// Nothing here knows a kind or a relation type: an imported element is one that
+// carries an `externalReference`, a baselined link is one that carries a
+// `sourceRevision`.
+// ─────────────────────────────────────────────────────────────────────────────
+const REVISION = 'externalReference.revision';
+const IDENTIFIER = 'externalReference.identifier';
+/** The baseline a link carries, if it carries one. */
+export function baselineOf(attributes) {
+    const sourceRevision = attributes?.['sourceRevision'];
+    if (sourceRevision === undefined)
+        return undefined;
+    const sourceIdentifier = attributes?.['sourceIdentifier'];
+    return sourceIdentifier === undefined ? { sourceRevision } : { sourceRevision, sourceIdentifier };
+}
+/** The imported record an element is, if it is one. */
+export function importedRecordOf(element) {
+    const identifier = element?.attributes[IDENTIFIER];
+    if (!element || identifier === undefined)
+        return undefined;
+    return { identifier, revision: element.attributes[REVISION], withdrawn: element.attributes['sourceWithdrawn'] === 'true' };
+}
+/**
+ * Whether a baseline is suspect against one imported record. The one predicate:
+ * the queue (`computeSuspectLinks`) and an import's preview both ask it, so what
+ * the preview says it will mark is what the queue then shows.
+ */
+export function suspectReason(baseline, record) {
+    if (baseline.sourceIdentifier !== undefined && baseline.sourceIdentifier !== record.identifier)
+        return undefined;
+    if (record.withdrawn)
+        return 'source-withdrawn';
+    return record.revision !== baseline.sourceRevision ? 'revision-moved' : undefined;
+}
+/** Every baselined link whose imported end has moved or been withdrawn. */
+export function computeSuspectLinks(model) {
+    const elementOf = (id) => model.elements instanceof Map ? model.elements.get(id) : model.elements[id];
+    const suspects = [];
+    for (const relationship of model.relationships) {
+        const baseline = baselineOf(relationship.attributes);
+        if (!baseline)
+            continue;
+        for (const end of ['source', 'target']) {
+            const elementId = end === 'source' ? relationship.sourceId : relationship.targetId;
+            const record = importedRecordOf(elementOf(elementId));
+            if (!record)
+                continue;
+            const reason = suspectReason(baseline, record);
+            if (reason) {
+                suspects.push({
+                    relationshipId: relationship.id, relationshipType: relationship.type, elementId, end,
+                    baseline: baseline.sourceRevision, current: record.revision, reason,
+                });
+            }
+        }
+    }
+    return suspects;
+}
+//# sourceMappingURL=suspect-links.js.map

package/packages/tools/lib/analysis/suspect-links.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"suspect-links.js","sourceRoot":"","sources":["../../src/analysis/suspect-links.ts"],"names":[],"mappings":"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"}

package/packages/tools/lib/analysis-starters.d.ts

@@ -1,3 +1,5 @@
+/** The notebooks' model access, shipped beside the compiled library. */
+export declare const MEMO_MODEL_MODULE: string;
 /** Add model-independent Jupyter samples to a newly initialized project. */
 export declare function scaffoldAnalysisSamples(projectDir: string): void;
 export declare const analysisSampleNames: string[];

package/packages/tools/lib/analysis-starters.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"analysis-starters.d.ts","sourceRoot":"","sources":["../src/analysis-starters.ts"],"names":[],"mappings":"AAibA,4EAA4E;AAC5E,wBAAgB,uBAAuB,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAShE;AAED,eAAO,MAAM,mBAAmB,UAA4C,CAAC"}
+{"version":3,"file":"analysis-starters.d.ts","sourceRoot":"","sources":["../src/analysis-starters.ts"],"names":[],"mappings":"AAibA,wEAAwE;AACxE,eAAO,MAAM,iBAAiB,QAAqE,CAAC;AAEpG,4EAA4E;AAC5E,wBAAgB,uBAAuB,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAWhE;AAED,eAAO,MAAM,mBAAmB,UAA4C,CAAC"}

package/packages/tools/lib/analysis-starters.js

@@ -1,41 +1,44 @@
-import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { copyFileSync, existsSync, mkdirSync, writeFileSync } from 'node:fs';
 import { resolve } from 'node:path';
-const LOAD_MODEL = `from pathlib import Path
+import { fileURLToPath } from 'node:url';
+const LOAD_MODEL = `import sys
+from pathlib import Path
 from collections import Counter, defaultdict
-import syside
-
-def find_sysml_root(start=Path.cwd()):
-    """Find the nearest model/ or src/ folder containing textual SysML."""
-    for directory in (start, *start.parents):
-        for folder_name in ('model', 'src'):
-            candidate = directory / folder_name
-            if candidate.is_dir() and next(candidate.rglob('*.sysml'), None):
-                return candidate
-    raise FileNotFoundError('No model/ or src/ directory containing .sysml files was found')
-
-SYSML_ROOT = find_sysml_root()
-SYSML_FILES = sorted(SYSML_ROOT.rglob('*.sysml'))
-model, diagnostics = syside.try_load_model([str(path) for path in SYSML_FILES])
-print(f'Loaded {len(SYSML_FILES)} SysML files from {SYSML_ROOT}')`;
+
+# memo_model.py sits in the project's analysis/ folder, above this notebook.
+sys.path.insert(0, str(next(d for d in (Path.cwd(), *Path.cwd().parents) if (d / 'memo_model.py').is_file())))
+import memo_model
+
+# Compiled by the project's selected compiler (toolchain.compiler), as every
+# MEMO command is: change the setting and this notebook follows.
+model = memo_model.load()
+diagnostics = model.diagnostics
+SYSML_FILES = model.documents
+print(f'Loaded {len(SYSML_FILES)} SysML files, compiled by {model.compiler} {model.compiler_version or ""}')`;
 const SAMPLES_README = `# MEMO analysis samples
 
-These notebooks are created by \`memo init\` and are designed to work with any
-MEMO textual SysML v2 project. They locate the nearest \`model/\` or \`src/\`
-directory automatically and query it through the typed Syside API.
+These notebooks are created by \`memo-architect init\` and work with any MEMO textual
+SysML v2 project. Each one reads the model through \`analysis/memo_model.py\`,
+which compiles the project with the compiler its settings select
+(\`toolchain.compiler\`), exactly as \`memo compile\` does. Changing the
+project's compiler changes what every notebook analyses.
 
 ## Prerequisites
 
-Use Python 3.12 or newer with JupyterLab and Syside installed and licensed:
+- Python 3.12 or newer with JupyterLab.
+- The \`memo\` command on \`PATH\`, or \`MEMO_CLI\` set to the command that runs it.
+- What the selected compiler needs, as \`memo compile --probe\` reports. A
+  compiler that builds no SysML v2 model of its own (\`internal\`) cannot serve
+  the notebooks; \`memo_model.load()\` says so.
 
 \`\`\`bash
 python -m venv analysis/.venv
 source analysis/.venv/bin/activate
-python -m pip install jupyterlab syside
+python -m pip install jupyterlab
 cd analysis
 jupyter lab --port 8888
 \`\`\`
 
-Configure the Syside license using its supported keyring or environment setup.
 MEMO Architect's **Analysis → Jupyter Notebooks** menu opens the local server at
 \`http://127.0.0.1:8888\`.
 
@@ -51,9 +54,10 @@ MEMO Architect's **Analysis → Jupyter Notebooks** menu opens the local server
 | \`06-ownership-graph.ipynb\` | SVG network graph of model ownership relationships. |
 | \`07-model-inventory-table.ipynb\` | Filterable inventory parameters, HTML table, and CSV export. |
 
-The notebooks use \`syside.try_load_model()\`, so partial analysis remains
-available while the project contains parser or semantic diagnostics. Review the
-reported diagnostics before treating analysis results as release evidence.
+A model loads only once the compiler accepts it: \`memo_model.load()\` raises
+with the compiler's errors otherwise. Compilers can differ in the elements they
+write for the same text (anonymous features in particular), so counts can
+differ slightly from one compiler to another.
 `;
 const STARTERS = [
     {
@@ -71,9 +75,7 @@ semantic_types = [
 ]
 counts = {}
 for type_name in semantic_types:
-    node_type = getattr(syside, type_name, None)
-    if node_type is not None:
-        counts[type_name] = len(list(model.elements(node_type)))
+    counts[type_name] = len(model.elements(type_name))
 
 largest = max(counts.values(), default=1)
 rows = ''.join(
@@ -84,9 +86,9 @@ display(HTML(f'<h3>Semantic inventory</h3><table><tr><th>Element type</th><th>Co
 
 {
     'SysML files': len(SYSML_FILES),
-    'Errors': len(list(diagnostics.errors)),
-    'Warnings': len(list(diagnostics.warnings)),
-    'Information': len(list(diagnostics.infos)),
+    'Errors': len(diagnostics.errors),
+    'Warnings': len(diagnostics.warnings),
+    'Information': len(diagnostics.infos),
 }`,
         ],
     },
@@ -98,8 +100,8 @@ display(HTML(f'<h3>Semantic inventory</h3><table><tr><th>Element type</th><th>Co
             `from IPython.display import display
 
 semantic_elements = (
-    list(model.elements(syside.Usage, include_subtypes=True))
-    + list(model.elements(syside.Definition, include_subtypes=True))
+    model.elements('Usage', include_subtypes=True)
+    + model.elements('Definition', include_subtypes=True)
 )
 
 def safe_name(element):
@@ -116,21 +118,21 @@ def ownership_depth(element):
 
 containers = []
 for element in semantic_elements:
-    children = [child for child in element.owned_elements if isinstance(child, (syside.Usage, syside.Definition))]
+    children = [child for child in element.owned_elements if child.is_a('Usage', 'Definition')]
     if children:
-        containers.append((len(children), type(element).__name__, safe_name(element)))
+        containers.append((len(children), element.type, safe_name(element)))
 
 print('Top containers by directly owned semantic elements')
 display(sorted(containers, reverse=True)[:25])
 
 print('Deepest ownership paths')
 display(sorted(
-    ((ownership_depth(item), type(item).__name__, safe_name(item)) for item in semantic_elements),
+    ((ownership_depth(item), item.type, safe_name(item)) for item in semantic_elements),
     reverse=True,
 )[:25])
 
 print('Most common semantic types')
-Counter(type(item).__name__ for item in semantic_elements).most_common(30)`,
+Counter(item.type for item in semantic_elements).most_common(30)`,
         ],
     },
     {
@@ -140,8 +142,8 @@ Counter(type(item).__name__ for item in semantic_elements).most_common(30)`,
         codeCells: [
             `from IPython.display import display
 
-usages = list(model.elements(syside.Usage, include_subtypes=True))
-definitions = list(model.elements(syside.Definition, include_subtypes=True))
+usages = model.elements('Usage', include_subtypes=True)
+definitions = model.elements('Definition', include_subtypes=True)
 semantic_elements = usages + definitions
 
 unnamed = [item for item in semantic_elements if not (item.name or item.declared_name)]
@@ -151,15 +153,15 @@ for item in semantic_elements:
     name = str(value) if value else None
     if name:
         by_name[name].append(item)
-duplicates = [(name, len(items), sorted({type(item).__name__ for item in items})) for name, items in by_name.items() if len(items) > 1]
+duplicates = [(name, len(items), sorted({item.type for item in items})) for name, items in by_name.items() if len(items) > 1]
 empty_definitions = [
     item for item in definitions
-    if not any(isinstance(child, (syside.Usage, syside.Definition)) for child in item.owned_elements)
+    if not any(child.is_a('Usage', 'Definition') for child in item.owned_elements)
 ]
 
 display({
-    'parser/semantic errors': len(list(diagnostics.errors)),
-    'warnings': len(list(diagnostics.warnings)),
+    'parser/semantic errors': len(diagnostics.errors),
+    'warnings': len(diagnostics.warnings),
     'unnamed usages or definitions': len(unnamed),
     'repeated qualified names': len(duplicates),
     'definitions with no owned usages/definitions': len(empty_definitions),
@@ -169,9 +171,9 @@ print('Repeated qualified names (first 30)')
 display(sorted(duplicates, key=lambda item: item[1], reverse=True)[:30])
 
 print('Empty definition candidates (first 30)')
-[(type(item).__name__, item.qualified_name or item.name) for item in empty_definitions[:30]]`,
+[(item.type, item.qualified_name or item.name) for item in empty_definitions[:30]]`,
             `print('First diagnostics to investigate')
-for diagnostic in list(diagnostics.errors)[:20] + list(diagnostics.warnings)[:20]:
+for diagnostic in diagnostics.errors[:20] + diagnostics.warnings[:20]:
     print(diagnostic)`,
         ],
     },
@@ -183,8 +185,8 @@ for diagnostic in list(diagnostics.errors)[:20] + list(diagnostics.warnings)[:20
             `QUERY = ''  # Example: 'pump', 'controller', 'safety', or a requirement name
 
 semantic_elements = (
-    list(model.elements(syside.Usage, include_subtypes=True))
-    + list(model.elements(syside.Definition, include_subtypes=True))
+    model.elements('Usage', include_subtypes=True)
+    + model.elements('Definition', include_subtypes=True)
 )
 
 def label(element):
@@ -200,20 +202,20 @@ else:
     matches = [item for item in semantic_elements if QUERY.casefold() in label(item).casefold()]
     print(f'{len(matches)} match(es) for {QUERY!r}')
 
-[(type(item).__name__, label(item)) for item in matches[:100]]`,
+[(item.type, label(item)) for item in matches[:100]]`,
             `def neighborhood(element):
     owner = getattr(element, 'owner', None)
-    children = [child for child in element.owned_elements if isinstance(child, (syside.Usage, syside.Definition))]
+    children = [child for child in element.owned_elements if child.is_a('Usage', 'Definition')]
     related = []
     for relationship in element.owned_relationships:
         for candidate in relationship.related_elements:
             if candidate is not element:
                 related.append(candidate)
     return {
-        'selected': (type(element).__name__, label(element)),
-        'owner': None if owner is None else (type(owner).__name__, label(owner)),
-        'children': [(type(child).__name__, label(child)) for child in children[:50]],
-        'directly related': [(type(item).__name__, label(item)) for item in related[:50]],
+        'selected': (element.type, label(element)),
+        'owner': None if owner is None else (owner.type, label(owner)),
+        'children': [(child.type, label(child)) for child in children[:50]],
+        'directly related': [(item.type, label(item)) for item in related[:50]],
     }
 
 [neighborhood(item) for item in matches[:10]]`,
@@ -234,9 +236,7 @@ type_names = [
 ]
 counts = {}
 for type_name in type_names:
-    node_type = getattr(syside, type_name, None)
-    if node_type is not None:
-        counts[type_name] = len(list(model.elements(node_type)))
+    counts[type_name] = len(model.elements(type_name))
 
 palette = ['#2d8d70', '#3887c7', '#e58a2b', '#8357b6', '#cf5c62', '#4f9d9d']
 largest = max(counts.values(), default=1)
@@ -248,9 +248,9 @@ for index, (name, count) in enumerate(sorted(counts.items(), key=lambda item: it
       <div>{escape(name)}</div><div style="background:#edf2f4;border-radius:6px;overflow:hidden"><div style="width:{width:.1f}%;height:20px;background:{color}"></div></div><strong>{count:,}</strong>
     </div>''')
 
-error_count = len(list(diagnostics.errors))
-warning_count = len(list(diagnostics.warnings))
-info_count = len(list(diagnostics.infos))
+error_count = len(diagnostics.errors)
+warning_count = len(diagnostics.warnings)
+info_count = len(diagnostics.infos)
 total_diagnostics = max(1, error_count + warning_count + info_count)
 diagnostic_gradient = (
     f'#cf5c62 0 {error_count / total_diagnostics * 100:.1f}%, '
@@ -279,8 +279,8 @@ display(HTML(f'''<div style="font-family:system-ui;max-width:900px">
 from IPython.display import SVG, display
 
 semantic_elements = (
-    list(model.elements(syside.Usage, include_subtypes=True))
-    + list(model.elements(syside.Definition, include_subtypes=True))
+    model.elements('Usage', include_subtypes=True)
+    + model.elements('Definition', include_subtypes=True)
 )
 
 def node_name(element):
@@ -290,7 +290,7 @@ def node_name(element):
 # Prefer named elements with semantic children, then fill with other named elements.
 ranked = sorted(
     (item for item in semantic_elements if item.name or item.declared_name),
-    key=lambda item: sum(isinstance(child, (syside.Usage, syside.Definition)) for child in item.owned_elements),
+    key=lambda item: sum(child.is_a('Usage', 'Definition') for child in item.owned_elements),
     reverse=True,
 )
 selected = ranked[:60]
@@ -322,7 +322,7 @@ for item in selected:
     if owner is not None and id(owner) in selected_ids:
         ox, oy = positions[id(owner)]
         edges.append(f'<path d="M {ox + 190} {oy + 20} C {ox + 215} {oy + 20}, {x - 25} {y + 20}, {x} {y + 20}" fill="none" stroke="#91a7b3" stroke-width="1.5"/>')
-    kind = type(item).__name__
+    kind = item.type
     fill = colors.get(kind, '#f4f6f7')
     label = escape(node_name(item)[:27])
     nodes.append(f'<g><rect x="{x}" y="{y}" width="190" height="40" rx="7" fill="{fill}" stroke="#547180"/><text x="{x + 9}" y="{y + 17}" font-size="11" font-weight="700">{label}</text><text x="{x + 9}" y="{y + 32}" font-size="9" fill="#587487">{kind}</text></g>')
@@ -345,8 +345,8 @@ NAME_FILTER = ''   # Case-insensitive name fragment
 ROW_LIMIT = 250
 
 semantic_elements = (
-    list(model.elements(syside.Usage, include_subtypes=True))
-    + list(model.elements(syside.Definition, include_subtypes=True))
+    model.elements('Usage', include_subtypes=True)
+    + model.elements('Definition', include_subtypes=True)
 )
 
 def text(value):
@@ -354,7 +354,7 @@ def text(value):
 
 records = []
 for item in semantic_elements:
-    kind = type(item).__name__
+    kind = item.type
     name = text(item.name or item.declared_name)
     qualified_name = text(item.qualified_name)
     owner = getattr(item, 'owner', None)
@@ -388,7 +388,7 @@ function markdownCell(starter) {
     return {
         cell_type: 'markdown',
         metadata: {},
-        source: [`# ${starter.title}\n\n${starter.description}\n\nThis sample uses only standard SysML v2 concepts and automatically discovers the project's \`model/\` or \`src/\` directory.`],
+        source: [`# ${starter.title}\n\n${starter.description}\n\nThis sample uses only standard SysML v2 concepts and reads the model through \`memo_model.py\`, compiled by the project's selected compiler.`],
     };
 }
 function codeCell(source) {
@@ -408,10 +408,15 @@ function notebook(starter) {
         nbformat_minor: 5,
     };
 }
+/** The notebooks' model access, shipped beside the compiled library. */
+export const MEMO_MODEL_MODULE = fileURLToPath(new URL('../python/memo_model.py', import.meta.url));
 /** Add model-independent Jupyter samples to a newly initialized project. */
 export function scaffoldAnalysisSamples(projectDir) {
     const samplesDir = resolve(projectDir, 'analysis', 'Samples');
     mkdirSync(samplesDir, { recursive: true });
+    const modulePath = resolve(projectDir, 'analysis', 'memo_model.py');
+    if (!existsSync(modulePath))
+        copyFileSync(MEMO_MODEL_MODULE, modulePath);
     const readmePath = resolve(samplesDir, 'README.md');
     if (!existsSync(readmePath))
         writeFileSync(readmePath, SAMPLES_README);

package/packages/tools/lib/analysis-starters.js.map

@@ -1 +1 @@
-{"version":3,"file":"analysis-starters.js","sourceRoot":"","sources":["../src/analysis-starters.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"analysis-starters.js","sourceRoot":"","sources":["../src/analysis-starters.ts"],"names":[],"mappings":"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"}

package/packages/tools/lib/authoring/outline-identity.d.ts

@@ -0,0 +1,34 @@
+import { type OutlineNode, type SourceOutline } from './source-outline.js';
+/** `file#key:metaclass`. */
+export declare function outlineIdentity(file: string, node: Pick<OutlineNode, 'key' | 'metaclass'>): string;
+/** An identity's parts, or undefined for a string that is not one. */
+export declare function parseOutlineIdentity(identity: string): {
+    file: string;
+    key: string;
+    metaclass: string;
+} | undefined;
+/**
+ * Every declaration of the outlines with an identity, by identity. A key that
+ * two declarations of one file share addresses neither, so it is left out
+ * rather than resolving to whichever came first.
+ */
+export declare function outlineIdentities(outlines: Iterable<SourceOutline>): Map<string, {
+    outline: SourceOutline;
+    node: OutlineNode;
+}>;
+/**
+ * The element id → identity table a model update ships: an element is the
+ * declaration whose key is its id, in its file.
+ */
+export declare function outlineIdentityTable(outlines: Iterable<SourceOutline>, elements: Iterable<{
+    id: string;
+    file?: string;
+}>, 
+/** An element's file is absolute from some builders; the outline's is project-relative. */
+projectRoot?: string): Record<string, string>;
+/**
+ * The declaration an identity names in the file's current outline, or a
+ * `StaleIrIdentityError` saying why there is none.
+ */
+export declare function resolveOutlineIdentity(outline: SourceOutline, identity: string): OutlineNode;
+//# sourceMappingURL=outline-identity.d.ts.map

package/packages/tools/lib/authoring/outline-identity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"outline-identity.d.ts","sourceRoot":"","sources":["../../src/authoring/outline-identity.ts"],"names":[],"mappings":"AAaA,OAAO,EAAgB,KAAK,WAAW,EAAE,KAAK,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAGzF,4BAA4B;AAC5B,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,WAAW,EAAE,KAAK,GAAG,WAAW,CAAC,GAAG,MAAM,CAElG;AAED,sEAAsE;AACtE,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,CAKnH;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,QAAQ,CAAC,aAAa,CAAC,GAAG,GAAG,CAAC,MAAM,EAAE;IAAE,OAAO,EAAE,aAAa,CAAC;IAAC,IAAI,EAAE,WAAW,CAAA;CAAE,CAAC,CAY/H;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAChC,QAAQ,EAAE,QAAQ,CAAC,aAAa,CAAC,EACjC,QAAQ,EAAE,QAAQ,CAAC;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AACjD,2FAA2F;AAC3F,WAAW,CAAC,EAAE,MAAM,GACrB,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAgBxB;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,GAAG,WAAW,CAc5F"}

package/packages/tools/lib/authoring/outline-identity.js

@@ -0,0 +1,95 @@
+// ─── Identities from the source outline ──────────────────────────────────────
+//
+// An authoring write names its target by an identity: the file, the
+// declaration's key in it and its metaclass —
+// `model/methodology/project.sysml#Plant::pump:PartUsage`
+// (plans/memo-write-back-from-handoff.md). It is minted from a source outline,
+// so it reads the same whether a stage 1 handoff or MEMO's parse built the
+// outline, and it survives an insertion elsewhere in the file. A rename or a
+// deletion makes it stale, and resolving a stale identity fails loudly rather
+// than editing a neighbour.
+// ─────────────────────────────────────────────────────────────────────────────
+import { isAbsolute, relative } from 'node:path';
+import { outlineNodes } from './source-outline.js';
+import { StaleIrIdentityError } from '../model/ir-identity.js';
+/** `file#key:metaclass`. */
+export function outlineIdentity(file, node) {
+    return `${file.replaceAll('\\', '/')}#${node.key}:${node.metaclass}`;
+}
+/** An identity's parts, or undefined for a string that is not one. */
+export function parseOutlineIdentity(identity) {
+    const hash = identity.indexOf('#');
+    const colon = identity.lastIndexOf(':');
+    if (hash <= 0 || colon <= hash + 1 || identity[colon - 1] === ':')
+        return undefined;
+    return { file: identity.slice(0, hash), key: identity.slice(hash + 1, colon), metaclass: identity.slice(colon + 1) };
+}
+/**
+ * Every declaration of the outlines with an identity, by identity. A key that
+ * two declarations of one file share addresses neither, so it is left out
+ * rather than resolving to whichever came first.
+ */
+export function outlineIdentities(outlines) {
+    const found = new Map();
+    const ambiguous = new Set();
+    for (const outline of outlines) {
+        for (const node of outlineNodes(outline)) {
+            const identity = outlineIdentity(outline.file, node);
+            if (found.has(identity))
+                ambiguous.add(identity);
+            else
+                found.set(identity, { outline, node });
+        }
+    }
+    for (const identity of ambiguous)
+        found.delete(identity);
+    return found;
+}
+/**
+ * The element id → identity table a model update ships: an element is the
+ * declaration whose key is its id, in its file.
+ */
+export function outlineIdentityTable(outlines, elements, 
+/** An element's file is absolute from some builders; the outline's is project-relative. */
+projectRoot) {
+    const byFileKey = new Map();
+    for (const identity of outlineIdentities(outlines).keys()) {
+        const parts = parseOutlineIdentity(identity);
+        const fileKey = `${parts.file}#${parts.key}`;
+        // One file and key with two metaclasses is no address either.
+        byFileKey.set(fileKey, byFileKey.has(fileKey) ? '' : identity);
+    }
+    const table = {};
+    for (const element of elements) {
+        if (!element.file)
+            continue;
+        const file = projectRoot && isAbsolute(element.file) ? relative(projectRoot, element.file) : element.file;
+        const identity = byFileKey.get(`${file.replaceAll('\\', '/')}#${element.id}`);
+        if (identity)
+            table[element.id] = identity;
+    }
+    return table;
+}
+/**
+ * The declaration an identity names in the file's current outline, or a
+ * `StaleIrIdentityError` saying why there is none.
+ */
+export function resolveOutlineIdentity(outline, identity) {
+    const parts = parseOutlineIdentity(identity);
+    if (!parts)
+        throw new StaleIrIdentityError(identity, 'it is not an identity this revision minted');
+    if (parts.file !== outline.file.replaceAll('\\', '/')) {
+        throw new StaleIrIdentityError(identity, `it names ${parts.file}, not ${outline.file}`);
+    }
+    const matches = [...outlineNodes(outline)].filter(node => node.key === parts.key);
+    if (matches.length === 0)
+        throw new StaleIrIdentityError(identity, 'no declaration in the file has that name now');
+    if (matches.length > 1)
+        throw new StaleIrIdentityError(identity, 'more than one declaration in the file has that name');
+    const node = matches[0];
+    if (node.metaclass !== parts.metaclass) {
+        throw new StaleIrIdentityError(identity, `it now names a ${node.metaclass}, not a ${parts.metaclass}`);
+    }
+    return node;
+}
+//# sourceMappingURL=outline-identity.js.map

package/packages/tools/lib/authoring/outline-identity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"outline-identity.js","sourceRoot":"","sources":["../../src/authoring/outline-identity.ts"],"names":[],"mappings":"AAAA,gFAAgF;AAChF,EAAE;AACF,oEAAoE;AACpE,8CAA8C;AAC9C,0DAA0D;AAC1D,+EAA+E;AAC/E,2EAA2E;AAC3E,6EAA6E;AAC7E,8EAA8E;AAC9E,4BAA4B;AAC5B,gFAAgF;AAEhF,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AACjD,OAAO,EAAE,YAAY,EAAwC,MAAM,qBAAqB,CAAC;AACzF,OAAO,EAAE,oBAAoB,EAAE,MAAM,yBAAyB,CAAC;AAE/D,4BAA4B;AAC5B,MAAM,UAAU,eAAe,CAAC,IAAY,EAAE,IAA4C;IACtF,OAAO,GAAG,IAAI,CAAC,UAAU,CAAC,IAAI,EAAE,GAAG,CAAC,IAAI,IAAI,CAAC,GAAG,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;AACzE,CAAC;AAED,sEAAsE;AACtE,MAAM,UAAU,oBAAoB,CAAC,QAAgB;IACjD,MAAM,IAAI,GAAG,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IACnC,MAAM,KAAK,GAAG,QAAQ,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;IACxC,IAAI,IAAI,IAAI,CAAC,IAAI,KAAK,IAAI,IAAI,GAAG,CAAC,IAAI,QAAQ,CAAC,KAAK,GAAG,CAAC,CAAC,KAAK,GAAG;QAAE,OAAO,SAAS,CAAC;IACpF,OAAO,EAAE,IAAI,EAAE,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,EAAE,GAAG,EAAE,QAAQ,CAAC,KAAK,CAAC,IAAI,GAAG,CAAC,EAAE,KAAK,CAAC,EAAE,SAAS,EAAE,QAAQ,CAAC,KAAK,CAAC,KAAK,GAAG,CAAC,CAAC,EAAE,CAAC;AACzH,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,iBAAiB,CAAC,QAAiC;IAC/D,MAAM,KAAK,GAAG,IAAI,GAAG,EAAyD,CAAC;IAC/E,MAAM,SAAS,GAAG,IAAI,GAAG,EAAU,CAAC;IACpC,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;QAC7B,KAAK,MAAM,IAAI,IAAI,YAAY,CAAC,OAAO,CAAC,EAAE,CAAC;YACvC,MAAM,QAAQ,GAAG,eAAe,CAAC,OAAO,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;YACrD,IAAI,KAAK,CAAC,GAAG,CAAC,QAAQ,CAAC;gBAAE,SAAS,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;;gBAC5C,KAAK,CAAC,GAAG,CAAC,QAAQ,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC;QAChD,CAAC;IACL,CAAC;IACD,KAAK,MAAM,QAAQ,IAAI,SAAS;QAAE,KAAK,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;IACzD,OAAO,KAAK,CAAC;AACjB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,oBAAoB,CAChC,QAAiC,EACjC,QAAiD;AACjD,2FAA2F;AAC3F,WAAoB;IAEpB,MAAM,SAAS,GAAG,IAAI,GAAG,EAAkB,CAAC;IAC5C,KAAK,MAAM,QAAQ,IAAI,iBAAiB,CAAC,QAAQ,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC;QACxD,MAAM,KAAK,GAAG,oBAAoB,CAAC,QAAQ,CAAE,CAAC;QAC9C,MAAM,OAAO,GAAG,GAAG,KAAK,CAAC,IAAI,IAAI,KAAK,CAAC,GAAG,EAAE,CAAC;QAC7C,8DAA8D;QAC9D,SAAS,CAAC,GAAG,CAAC,OAAO,EAAE,SAAS,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC;IACnE,CAAC;IACD,MAAM,KAAK,GAA2B,EAAE,CAAC;IACzC,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;QAC7B,IAAI,CAAC,OAAO,CAAC,IAAI;YAAE,SAAS;QAC5B,MAAM,IAAI,GAAG,WAAW,IAAI,UAAU,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC;QAC1G,MAAM,QAAQ,GAAG,SAAS,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,UAAU,CAAC,IAAI,EAAE,GAAG,CAAC,IAAI,OAAO,CAAC,EAAE,EAAE,CAAC,CAAC;QAC9E,IAAI,QAAQ;YAAE,KAAK,CAAC,OAAO,CAAC,EAAE,CAAC,GAAG,QAAQ,CAAC;IAC/C,CAAC;IACD,OAAO,KAAK,CAAC;AACjB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,sBAAsB,CAAC,OAAsB,EAAE,QAAgB;IAC3E,MAAM,KAAK,GAAG,oBAAoB,CAAC,QAAQ,CAAC,CAAC;IAC7C,IAAI,CAAC,KAAK;QAAE,MAAM,IAAI,oBAAoB,CAAC,QAAQ,EAAE,4CAA4C,CAAC,CAAC;IACnG,IAAI,KAAK,CAAC,IAAI,KAAK,OAAO,CAAC,IAAI,CAAC,UAAU,CAAC,IAAI,EAAE,GAAG,CAAC,EAAE,CAAC;QACpD,MAAM,IAAI,oBAAoB,CAAC,QAAQ,EAAE,YAAY,KAAK,CAAC,IAAI,SAAS,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC;IAC5F,CAAC;IACD,MAAM,OAAO,GAAG,CAAC,GAAG,YAAY,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,GAAG,KAAK,KAAK,CAAC,GAAG,CAAC,CAAC;IAClF,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,MAAM,IAAI,oBAAoB,CAAC,QAAQ,EAAE,8CAA8C,CAAC,CAAC;IACnH,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC;QAAE,MAAM,IAAI,oBAAoB,CAAC,QAAQ,EAAE,qDAAqD,CAAC,CAAC;IACxH,MAAM,IAAI,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IACxB,IAAI,IAAI,CAAC,SAAS,KAAK,KAAK,CAAC,SAAS,EAAE,CAAC;QACrC,MAAM,IAAI,oBAAoB,CAAC,QAAQ,EAAE,kBAAkB,IAAI,CAAC,SAAS,WAAW,KAAK,CAAC,SAAS,EAAE,CAAC,CAAC;IAC3G,CAAC;IACD,OAAO,IAAI,CAAC;AAChB,CAAC"}