@memoarchitect/tools 0.6.7 → 0.8.7

package/packages/tools/lib/server/persistor.js

@@ -1,30 +1,67 @@
-import { readFileSync, writeFileSync, existsSync, appendFileSync, mkdirSync } from 'node:fs';
-import { resolve, dirname } from 'node:path';
-import { generateUsage } from '@memoarchitect/tools';
+// ─── Element write-back ──────────────────────────────────────────────────────
+//
+// Persists one element change back to its source `.sysml` file.
+//
+// This module used to find its target with a regular expression over the file
+// text — `<construct> <id> : <kind> { … }` — which made the authored name the
+// address of the declaration. That is wrong in three ways at once: two
+// same-named declarations in different namespaces are one target; a `{}` nested
+// two deep escapes the pattern; and a comment mentioning the name is a match.
+//
+// An update now addresses its target by **IR identity** (§6.2): the caller
+// quotes the identity minted by the last lowering, the identity is resolved
+// against the current source, and the declaration's own CST range is replaced.
+// Everything else in the file — comments, imports, neighbouring declarations —
+// is untouched because only that one range is edited, and the result is
+// reparsed before it reaches disk. An identity the current source does not have
+// raises `StaleIrIdentityError` rather than falling back to a name match, which
+// is the whole point: a stale write fails loudly instead of editing whatever
+// happens to share the name.
+//
+// Creation has no identity yet, by definition. It appends, and the recompile
+// that follows the write mints the identity for the next edit.
+// ─────────────────────────────────────────────────────────────────────────────
+import { existsSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { generateUsage } from '../serializer/sysml-generator.js';
+import { parseText } from '../model/parser-utils.js';
+import { requireIrIdentity, resolveDeclarationByIdentity, StaleIrIdentityError, } from '../model/ir-identity.js';
+import { insertIntoBody, locatePackages } from './package-source.js';
+/** Default home for an element the request does not place. */
+export const DEFAULT_ELEMENT_FILE = 'model/catalog/project.sysml';
 /**
- * Persists an element change back to its source .sysml file.
+ * Why a rename is only a text edit, said once here so every surface says the
+ * same thing.
  *
- * If the element is new (no 'file' property), it records it in 'model/generated.sysml'.
- * Uses a regex-based usage block replacement for existing elements.
+ * Updating references would need name resolution across the workspace — the
+ * linker, which is Track B B5 and does not exist yet. Silently rewriting the
+ * declaration and leaving every reference pointing at the old name would be a
+ * broken model presented as a successful edit, so the write succeeds and says
+ * what it did not do.
  */
-export function saveElementToFile(cwd, element) {
-    const relativePath = element.file || 'model/generated.sysml';
+export const RENAME_IS_TEXT_ONLY = 'Renaming edits this declaration only. MEMO cannot yet update references to it elsewhere in the '
+    + 'project — that needs cross-file name resolution — so any reference to the old name will not resolve '
+    + 'until you update it by hand.';
+/**
+ * Write one element into project source.
+ *
+ * `index` is the identity index of the current revision. Passing it is what
+ * makes an update identity-addressed; without it only creation is possible,
+ * and an update that quotes an identity is refused rather than silently
+ * degraded to a name match.
+ */
+export async function saveElementToFile(cwd, element, index) {
+    const relativePath = element.file || DEFAULT_ELEMENT_FILE;
     const filePath = resolve(cwd, relativePath);
-    // 1. Ensure directory exists
     const dir = dirname(filePath);
-    if (!existsSync(dir)) {
+    if (!existsSync(dir))
         mkdirSync(dir, { recursive: true });
-    }
-    // 2. Initialize file if new
     if (!existsSync(filePath)) {
         const pkgName = relativePath.replace(/[^a-zA-Z0-9]/g, '_').replace(/^_/, '').replace(/\.sysml$/, '');
         writeFileSync(filePath, `package ${pkgName || 'generated'} {\n}\n`, 'utf8');
     }
     const content = readFileSync(filePath, 'utf8');
-    // Transform element to the format generator expects
-    // Note: our current generator expects CsvElement, but we can call generateUsage 
-    // with a duck-typed object.
-    const newUsage = generateUsage({
+    const usage = generateUsage({
         id: element.id,
         name: element.name,
         kind: element.kind,
@@ -33,40 +70,132 @@ export function saveElementToFile(cwd, element) {
         doc: element.doc || '',
         attributes: element.attributes || {},
     });
-    // 3. Find and replace or Append
-    // This regex looks for: <construct> <id> : <kind> { ... }
-    const escapedId = element.id.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-    const usageRegex = new RegExp(`(\\w+)\\s+${escapedId}\\s*:\\s*(\\w+)\\s*\\{([^{}]|\\{[^{}]*\\})*\\}`, 'g');
-    const matches = content.match(usageRegex);
-    let newContent;
-    const log = (msg) => appendFileSync('/tmp/persistor.log', `[${new Date().toISOString()}] ${msg}\n`);
-    log(`Persisting ${element.id} to ${filePath}. File length: ${content.length}`);
-    if (matches) {
-        log(`Found existing definition(s) for ${element.id}. Matching block: ${matches[0].slice(0, 50)}...`);
-        newContent = content.replace(usageRegex, newUsage);
-    }
-    else {
-        log(`No existing definition found for ${element.id}. Current package structure might be missing. Appending at end.`);
-        const lastBrace = content.lastIndexOf('}');
-        if (lastBrace !== -1) {
-            const indentedUsage = newUsage.split('\n').map(l => '    ' + l).join('\n');
-            newContent = content.slice(0, lastBrace) + '\n' + indentedUsage + '\n' + content.slice(lastBrace);
+    let updated;
+    let replaced = false;
+    const warnings = [];
+    // A caller holding the current index does not have to quote an identity for
+    // an element the index already knows: server-side callers (kind remapping,
+    // an approved LLM change) work from the model rather than from a UI
+    // selection, and re-deriving the identity there is the same lookup the
+    // client would have done. A *quoted* identity is never overridden this way
+    // — that is the one that has to be checked for staleness.
+    const identity = element.irIdentity ?? (index ? index.byMemoElement[element.id] : undefined);
+    if (identity) {
+        if (!index) {
+            return {
+                success: false, filePath: relativePath, stale: true,
+                error: 'The write quotes an IR identity but no compiled revision is available to resolve it '
+                    + 'against; no file was written.',
+            };
+        }
+        let located;
+        try {
+            located = await locateDeclaration(content, index, identity, element.renamedFrom ?? element.id);
         }
-        else {
-            newContent = content + '\n' + newUsage + '\n';
+        catch (e) {
+            if (e instanceof StaleIrIdentityError) {
+                return { success: false, filePath: relativePath, stale: true, error: e.message };
+            }
+            return { success: false, filePath: relativePath, error: String(e) };
         }
+        if (located.declaredName && element.id !== located.declaredName) {
+            warnings.push({ code: 'rename-is-text-only', message: RENAME_IS_TEXT_ONLY });
+        }
+        updated = spliceIndented(content, located.start, located.end, usage);
+        replaced = true;
+    }
+    else if (element.package) {
+        const target = (await locatePackages(content)).find(pkg => pkg.qualifiedName === element.package);
+        if (!target) {
+            return {
+                success: false, filePath: relativePath,
+                error: `${relativePath} does not declare package "${element.package}"; nothing was written.`,
+            };
+        }
+        updated = insertIntoBody(content, target, `${usage}\n`);
+    }
+    else {
+        updated = appendToLastPackage(content, usage);
+    }
+    const committed = await commitSource(filePath, relativePath, updated);
+    if (!committed.success)
+        return { success: false, filePath: relativePath, error: committed.error };
+    return { success: true, filePath: relativePath, replaced, ...(warnings.length ? { warnings } : {}) };
+}
+/**
+ * Parse-before-commit, then write atomically.
+ *
+ * Source that does not parse never reaches disk. The editor model (§1.1) says a
+ * *user* may save anything; it does not say a machine-generated splice may
+ * corrupt a file the user did not touch.
+ */
+export async function commitSource(absolutePath, relativePath, updated) {
+    const { errors } = await parseText(updated);
+    if (errors.length > 0) {
+        return {
+            success: false,
+            error: `The updated source did not parse (${errors[0].message}); ${relativePath} was left unchanged.`,
+        };
     }
     try {
-        writeFileSync(filePath, newContent, 'utf8');
-        log(`Successfully wrote ${newContent.length} bytes to ${filePath}`);
-        return { success: true, filePath: relativePath };
+        atomicWrite(absolutePath, updated);
     }
     catch (e) {
-        log(`CRITICAL: Failed to write to ${filePath}: ${e}`);
-        return { success: false, filePath: relativePath, error: String(e) };
+        return { success: false, error: `Could not write ${relativePath}: ${String(e)}` };
+    }
+    return { success: true };
+}
+/** Source range of the declaration an identity names, in this file's text. */
+async function locateDeclaration(source, index, identityId, memoElementId) {
+    const record = requireIrIdentity(index, identityId, memoElementId);
+    const { document, errors } = await parseText(source);
+    if (errors.length > 0) {
+        throw new StaleIrIdentityError(identityId, `its file no longer parses (${errors[0].message})`);
+    }
+    const node = resolveDeclarationByIdentity(document.parseResult.value, record.identity);
+    const cst = node.$cstNode;
+    if (!cst)
+        throw new StaleIrIdentityError(identityId, 'the resolved declaration has no source range');
+    return { start: cst.offset, end: cst.offset + cst.length, declaredName: node.name };
+}
+/** Replace a range, re-indenting the replacement to the line it starts on. */
+function spliceIndented(source, start, end, replacement) {
+    const lineStart = source.lastIndexOf('\n', start - 1) + 1;
+    const lead = source.slice(lineStart, start);
+    const indent = /^[ \t]*$/.test(lead) ? lead : '';
+    const body = replacement.split('\n').map((line, i) => (i === 0 || !line ? line : indent + line)).join('\n');
+    return source.slice(0, start) + body + source.slice(end);
+}
+/** Append a new declaration as the last member of the file's final package. */
+function appendToLastPackage(source, usage) {
+    const lastBrace = source.lastIndexOf('}');
+    if (lastBrace === -1)
+        return `${source}\n${usage}\n`;
+    const braceLineStart = source.lastIndexOf('\n', lastBrace - 1) + 1;
+    const braceIndent = source.slice(braceLineStart, lastBrace);
+    const indent = /^[ \t]*$/.test(braceIndent) ? `${braceIndent}    ` : '    ';
+    const indented = usage.split('\n').map(line => (line ? indent + line : line)).join('\n');
+    const before = source.slice(0, lastBrace);
+    const separator = before.endsWith('\n') ? '' : '\n';
+    return `${before}${separator}${indented}\n${source.slice(lastBrace)}`;
+}
+/** Write via a sibling temp file so a crash cannot leave a half-written model. */
+function atomicWrite(absolutePath, contents) {
+    const tempPath = `${absolutePath}.${process.pid}.tmp`;
+    try {
+        writeFileSync(tempPath, contents, 'utf8');
+        renameSync(tempPath, absolutePath);
+    }
+    catch (e) {
+        if (existsSync(tempPath)) {
+            try {
+                unlinkSync(tempPath);
+            }
+            catch { /* best effort cleanup */ }
+        }
+        throw e;
     }
 }
-// Relationship persistence lives in ./relationship-writer.ts. It replaces the
-// blind append this module used to do: relationships now go through ontology
-// validation, a deterministic ownership policy, and CST-aware source editing.
+// Relationship persistence lives in ./relationship-writer.ts, and the notation
+// it emits in ./sysml-notation.ts.
 //# sourceMappingURL=persistor.js.map

package/packages/tools/lib/server/persistor.js.map

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

package/packages/tools/lib/server/relationship-writer.d.ts

@@ -1,7 +1,9 @@
 import type { MemoModelDTO, MemoRelationship } from '../model/semantic.js';
-import type { RelationshipCreateRequest, RelationshipDefinitionDTO } from '../model/relationship-legality.js';
+import type { RelationshipCreateRequest, RelationshipDefinitionDTO, RelationshipUpdateRequest } from '../model/relationship-legality.js';
+import { type IrIdentityIndex } from '../model/ir-identity.js';
+import { type RelationshipNotation } from './sysml-notation.js';
 /** Default file used when the project has no better home for a relationship. */
-export declare const CANONICAL_RELATIONSHIP_FILE = "model/relationships.sysml";
+export declare const CANONICAL_RELATIONSHIP_FILE = "model/catalog/relationships.sysml";
 /** Directory segments holding view/presentation SysML — never a relationship home. */
 export declare const DEFAULT_PRESENTATION_DIRS: string[];
 /** Filenames a package uses to collect its relationships. */
@@ -28,6 +30,14 @@ export interface RelationshipWriterOptions {
     presentationDirs?: string[];
     /** Filenames treated as a package's relationship collection. */
     relationshipFilePattern?: RegExp;
+    /**
+     * Identity index of the current revision.
+     *
+     * Present whenever a compiled revision exists. Absent only before the first
+     * successful lowering, and a request quoting an identity is then refused
+     * rather than written blind.
+     */
+    irIndex?: IrIdentityIndex;
 }
 /** Why a particular file was chosen, for logging and for the UI to show. */
 export type PlacementReason = 'requested' | 'designated-package-file' | 'common-package-file' | 'source-element-file' | 'canonical-file' | 'canonical-file-created';
@@ -42,12 +52,20 @@ export interface RelationshipWriteResult {
     success: boolean;
     /** Project-relative file actually written. */
     sourceFile?: string;
-    /** Stable ID (the connection usage name) of the created relationship. */
+    /**
+     * Stable ID (the connection usage name) of the created relationship.
+     *
+     * Absent for notations SysML does not name — see `notation`.
+     */
     relationshipId?: string;
+    /** SysML production the relationship was written in. */
+    notation?: RelationshipNotation;
     /** The exact declaration text inserted. */
     declaration?: string;
     placementReason?: PlacementReason;
     error?: string;
+    /** Set when the failure was a stale endpoint identity. */
+    stale?: boolean;
 }
 export interface RelationshipRemoveResult {
     success: boolean;
@@ -56,6 +74,12 @@ export interface RelationshipRemoveResult {
     removedDeclaration?: string;
     error?: string;
 }
+export interface RelationshipUpdateResult {
+    success: boolean;
+    sourceFile?: string;
+    declaration?: string;
+    error?: string;
+}
 /**
  * Whether a project-relative path is a legal home for a model relationship.
  *
@@ -83,8 +107,14 @@ export declare function resolveRelationshipPlacement(request: Pick<RelationshipC
  * authored relationship gets one.
  */
 export declare function generateRelationshipId(type: string, sourceId: string, targetId: string, taken: Iterable<string>): string;
-/** Render the typed connection usage for a relationship. */
-export declare function generateRelationshipDeclaration(id: string, definition: RelationshipDefinitionDTO, sourceId: string, targetId: string, flowItem?: string): string;
+/**
+ * Render a relationship as SysML source.
+ *
+ * The form comes from the language, not from this module — see
+ * `./sysml-notation.ts`. Kept as a named export because the shape "id,
+ * definition, endpoints" is what every caller has.
+ */
+export declare function generateRelationshipDeclaration(id: string, definition: RelationshipDefinitionDTO, sourceId: string, targetId: string, flowItem?: string, guard?: string): string;
 /**
  * Write a relationship into project SysML.
  *
@@ -93,6 +123,12 @@ export declare function generateRelationshipDeclaration(id: string, definition:
  * not parse or does not contain the new connection.
  */
 export declare function writeRelationship(request: RelationshipCreateRequest, definition: RelationshipDefinitionDTO, model: Pick<MemoModelDTO, 'elements' | 'relationships'>, options: RelationshipWriterOptions): Promise<RelationshipWriteResult>;
+/**
+ * Atomically replace one relationship declaration at the exact range supplied
+ * by the current compiled model. This also supports anonymous SysML `flow` and
+ * `succession` usages, which deliberately have no stable declared name.
+ */
+export declare function updateRelationship(request: RelationshipUpdateRequest, relationship: MemoRelationship, definition: RelationshipDefinitionDTO, model: Pick<MemoModelDTO, 'elements'>, options: RelationshipWriterOptions): Promise<RelationshipUpdateResult>;
 /**
  * Remove exactly one connection usage from its owning file.
  *

package/packages/tools/lib/server/relationship-writer.d.ts.map

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

package/packages/tools/lib/server/relationship-writer.js

@@ -7,16 +7,28 @@
 // Editing is CST-aware: the file is parsed, the edit is applied by source
 // offset so comments and unrelated declarations survive untouched, the result
 // is reparsed and validated, and only then does it atomically replace the file.
+//
+// Endpoints are addressed by **IR identity** when the caller quotes one (§6.2).
+// A relationship names two elements, so a request built against a stale
+// revision is a request to connect two things that may no longer be what the
+// client thought they were — it is refused, loudly, rather than written against
+// whatever now answers to those names.
+//
+// The notation is standard SysML, chosen in ./sysml-notation.ts: a succession
+// is written `succession first a if g then b;`, not encoded as a MEMO-flavoured
+// connection usage.
 // ─────────────────────────────────────────────────────────────────────────────
 import { existsSync, mkdirSync, readdirSync, readFileSync, realpathSync, renameSync, unlinkSync, writeFileSync, } from 'node:fs';
 import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
 import { parseText } from '../model/parser-utils.js';
+import { StaleIrIdentityError, } from '../model/ir-identity.js';
+import { notationFor, notationIsNameable, renderRelationship, } from './sysml-notation.js';
 import { isConnectionUsage, isPackageDeclaration, } from '../language/generated/ast.js';
 // Project-layout conventions, not ontology semantics — these describe where a
 // MEMO project keeps its files, so they are overridable per project rather than
 // fixed in the engine.
 /** Default file used when the project has no better home for a relationship. */
-export const CANONICAL_RELATIONSHIP_FILE = 'model/relationships.sysml';
+export const CANONICAL_RELATIONSHIP_FILE = 'model/catalog/relationships.sysml';
 /** Directory segments holding view/presentation SysML — never a relationship home. */
 export const DEFAULT_PRESENTATION_DIRS = ['views'];
 /** Filenames a package uses to collect its relationships. */
@@ -175,15 +187,15 @@ export function generateRelationshipId(type, sourceId, targetId, taken) {
         n++;
     return `${base}_${n}`;
 }
-/** Render the typed connection usage for a relationship. */
-export function generateRelationshipDeclaration(id, definition, sourceId, targetId, flowItem) {
-    const head = `connection ${id} : ${definition.sysmlName} connect ` +
-        `${definition.sourceEnd.name} ::> ${sourceId} to ` +
-        `${definition.targetEnd.name} ::> ${targetId}`;
-    const item = flowItem?.trim();
-    return item
-        ? `${head} {\n        attribute transportedItem = ${JSON.stringify(item)};\n    }`
-        : `${head};`;
+/**
+ * Render a relationship as SysML source.
+ *
+ * The form comes from the language, not from this module — see
+ * `./sysml-notation.ts`. Kept as a named export because the shape "id,
+ * definition, endpoints" is what every caller has.
+ */
+export function generateRelationshipDeclaration(id, definition, sourceId, targetId, flowItem, guard) {
+    return renderRelationship({ id, definition, sourceId, targetId, flowItem, guard });
 }
 // ─── Create ─────────────────────────────────────────────────────────────────
 /**
@@ -194,13 +206,24 @@ export function generateRelationshipDeclaration(id, definition, sourceId, target
  * not parse or does not contain the new connection.
  */
 export async function writeRelationship(request, definition, model, options) {
+    // Endpoint identities first: a request built against a revision that has
+    // moved on must not be written at all, so this precedes every file decision.
+    try {
+        assertFreshEndpoints(request, options.irIndex);
+    }
+    catch (e) {
+        if (e instanceof StaleIrIdentityError)
+            return { success: false, stale: true, error: e.message };
+        throw e;
+    }
     const placement = resolveRelationshipPlacement(request, model, options);
     if (!isWritableRelationshipFile(placement.file, options)) {
         return { success: false, error: `No writable project file can own this relationship (${placement.file})` };
     }
     const absolutePath = resolve(options.projectRoot, placement.file);
+    const notation = notationFor(definition);
     const relationshipId = generateRelationshipId(definition.name, request.sourceId, request.targetId, model.relationships.map(rel => rel.id));
-    const declaration = generateRelationshipDeclaration(relationshipId, definition, request.sourceId, request.targetId, request.flowItem);
+    const declaration = generateRelationshipDeclaration(relationshipId, definition, request.sourceId, request.targetId, request.flowItem, request.guard);
     let updated;
     if (!existsSync(absolutePath)) {
         updated = newRelationshipFile(placement.file, declaration);
@@ -220,7 +243,9 @@ export async function writeRelationship(request, definition, model, options) {
             error: `The updated source did not parse (${errors[0].message}); the file was left unchanged`,
         };
     }
-    const written = findConnectionUsage(document.parseResult.value, relationshipId);
+    const written = notationIsNameable(notation)
+        ? findConnectionUsage(document.parseResult.value, relationshipId) !== undefined
+        : containsDeclaration(document.parseResult.value, updated, declaration);
     if (!written) {
         return {
             success: false,
@@ -236,11 +261,45 @@ export async function writeRelationship(request, definition, model, options) {
     return {
         success: true,
         sourceFile: placement.file,
-        relationshipId,
+        // SysML's succession and flow productions take no declared name, so a
+        // relationship written in one is addressed by position. Reporting an ID
+        // it does not have would only make deletion fail later, further away.
+        ...(notationIsNameable(notation) ? { relationshipId } : {}),
+        notation,
         declaration,
         placementReason: placement.reason,
     };
 }
+/**
+ * Refuse a request whose endpoints were named against an older revision.
+ *
+ * Only quoted identities are checked. A caller that quotes none is asking for
+ * the by-name behaviour it always had, and gets it — the loud failure is for
+ * callers that *did* name a revision and named a stale one, which is the case
+ * where continuing would connect the wrong elements.
+ */
+function assertFreshEndpoints(request, index) {
+    const ends = [
+        ['source', request.sourceIdentity, request.sourceId],
+        ['target', request.targetIdentity, request.targetId],
+    ];
+    for (const [end, identityId, elementId] of ends) {
+        if (!identityId)
+            continue;
+        if (!index) {
+            throw new StaleIrIdentityError(identityId, 'no compiled revision is available to resolve the ' + end + ' endpoint against');
+        }
+        const record = index.byIdentity.get(identityId);
+        if (!record) {
+            throw new StaleIrIdentityError(identityId, `the ${end} endpoint is not in the current model revision`);
+        }
+        const named = record.memoElementId;
+        if (named !== elementId) {
+            throw new StaleIrIdentityError(identityId, `the ${end} endpoint now names ${named ? `"${named}"` : 'a declaration MEMO does not project'}, `
+                + `not "${elementId}"`);
+        }
+    }
+}
 /** Body of a freshly created relationship file. */
 function newRelationshipFile(relativePath, declaration) {
     const packageName = relativePath
@@ -249,6 +308,65 @@ function newRelationshipFile(relativePath, declaration) {
         .replace(/^_+|_+$/g, '') || 'relationships';
     return `package ${packageName} {\n    ${declaration}\n}\n`;
 }
+/** Fully qualify a nested endpoint from the semantic ownership chain. */
+function endpointPath(elementId, model) {
+    const path = [elementId];
+    const visited = new Set(path);
+    let owner = model.elements[elementId]?.owner;
+    while (owner && !visited.has(owner)) {
+        path.unshift(owner);
+        visited.add(owner);
+        owner = model.elements[owner]?.owner;
+    }
+    return path.join('.');
+}
+/**
+ * Atomically replace one relationship declaration at the exact range supplied
+ * by the current compiled model. This also supports anonymous SysML `flow` and
+ * `succession` usages, which deliberately have no stable declared name.
+ */
+export async function updateRelationship(request, relationship, definition, model, options) {
+    try {
+        assertFreshEndpoints(request, options.irIndex);
+    }
+    catch (e) {
+        if (e instanceof StaleIrIdentityError)
+            return { success: false, error: e.message };
+        throw e;
+    }
+    if (!relationship.file || !isWritableRelationshipFile(relationship.file, options)) {
+        return { success: false, error: `${relationship.file || 'The source file'} is not a writable project file` };
+    }
+    const range = relationship.sourceRange;
+    if (!range)
+        return { success: false, error: 'The relationship has no source range in the current model revision' };
+    const absolutePath = resolve(options.projectRoot, relationship.file);
+    if (!existsSync(absolutePath))
+        return { success: false, error: `${relationship.file} no longer exists` };
+    const source = readFileSync(absolutePath, 'utf8');
+    if (range.offset < 0 || range.length <= 0 || range.offset + range.length > source.length) {
+        return { success: false, error: 'The relationship source range is stale' };
+    }
+    const declaration = generateRelationshipDeclaration(relationship.id, definition, endpointPath(request.sourceId, model), endpointPath(request.targetId, model), relationship.flowItem, relationship.attributes?.guard);
+    const updated = source.slice(0, range.offset) + declaration + source.slice(range.offset + range.length);
+    const reparsed = await parseText(updated);
+    if (reparsed.errors.length > 0) {
+        return { success: false, error: `The updated source did not parse (${reparsed.errors[0].message}); the file was left unchanged` };
+    }
+    const notation = notationFor(definition);
+    const present = notationIsNameable(notation)
+        ? findConnectionUsage(reparsed.document.parseResult.value, relationship.id) !== undefined
+        : containsDeclaration(reparsed.document.parseResult.value, updated, declaration);
+    if (!present)
+        return { success: false, error: 'The updated relationship was not present after reparsing; the file was left unchanged' };
+    try {
+        atomicWrite(absolutePath, updated);
+    }
+    catch (e) {
+        return { success: false, error: `Could not write ${relationship.file}: ${String(e)}` };
+    }
+    return { success: true, sourceFile: relationship.file, declaration };
+}
 /**
  * Insert a declaration as the last member of the file's final top-level
  * package, matching the indentation of the members already there. Everything
@@ -363,6 +481,32 @@ export async function removeRelationship(relationship, options) {
     return { success: true, sourceFile: relationship.file, removedDeclaration };
 }
 // ─── Shared helpers ─────────────────────────────────────────────────────────
+/**
+ * Whether a parsed document contains exactly the declaration that was inserted.
+ *
+ * The confirmation for anonymous notations. A named connection can be looked up
+ * by name; a succession cannot, so the check is that some parsed node's own
+ * source range *is* the text that was inserted — which proves both that it
+ * survived the reparse and that the parser read it as one declaration rather
+ * than as a fragment of something larger.
+ */
+function containsDeclaration(model, source, declaration) {
+    const wanted = declaration.trim();
+    const stack = [...(model.members ?? [])];
+    while (stack.length > 0) {
+        const node = stack.pop();
+        if (!node || typeof node !== 'object')
+            continue;
+        const cst = node.$cstNode;
+        if (cst && source.slice(cst.offset, cst.offset + cst.length).trim() === wanted)
+            return true;
+        if (Array.isArray(node.members))
+            stack.push(...node.members);
+        if (Array.isArray(node.body))
+            stack.push(...node.body);
+    }
+    return false;
+}
 /** Depth-first search for a named connection usage anywhere in the document. */
 function findConnectionUsage(model, name) {
     const stack = [...(model.members ?? [])];