@memoarchitect/tools 0.6.6 → 0.7.2

package/packages/tools/lib/server/mutation-domain.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mutation-domain.d.ts","sourceRoot":"","sources":["../../src/server/mutation-domain.ts"],"names":[],"mappings":"AAsBA,iDAAiD;AACjD,MAAM,MAAM,cAAc,GAAG,UAAU,GAAG,QAAQ,GAAG,SAAS,CAAC;AAE/D,yDAAyD;AACzD,eAAO,MAAM,kBAAkB,EAAE,SAAS,MAAM,EAE/C,CAAC;AA0BF,wBAAgB,cAAc,CAAC,WAAW,EAAE,MAAM,GAAG,cAAc,CAElE;AAED,yEAAyE;AACzE,qBAAa,wBAAyB,SAAQ,KAAK;IACnC,QAAQ,CAAC,WAAW,EAAE,MAAM;IAAE,QAAQ,CAAC,eAAe,EAAE,SAAS,MAAM,EAAE;gBAAhE,WAAW,EAAE,MAAM,EAAW,eAAe,EAAE,SAAS,MAAM,EAAE;CAQxF;AAED;;;;;;;;GAQG;AACH,wBAAgB,0BAA0B,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,IAAI,CAStF"}

package/packages/tools/lib/server/mutation-domain.js

@@ -0,0 +1,87 @@
+// ─── One action, one domain ─────────────────────────────────────────────────
+//
+// A MEMO project keeps two kinds of state, and they are not the same kind of
+// fact:
+//
+//   semantic — what the model says. Lives in `.sysml`, reviewed, diffed,
+//              versioned, and read by every tool that reads SysML.
+//   layout   — where a symbol sits on a canvas. Lives in a `.viewlayout`
+//              sidecar, and says nothing about the model.
+//
+// The rule this module enforces is that **no single action writes both**.
+// Moving a symbol must produce no `.sysml` diff, and editing a declaration must
+// leave the sidecar alone. The reason is reviewability: once a drag can change
+// source, a semantic diff can no longer be read as a semantic change, and once
+// a semantic edit can move symbols, a layout diff stops being noise you can
+// safely ignore.
+//
+// Keeping it as a check rather than a convention means a new handler cannot
+// quietly reintroduce the mixture: an unclassified mutation is a failure, not a
+// default.
+// ─────────────────────────────────────────────────────────────────────────────
+/** Payload keys that only ever describe presentation. */
+export const LAYOUT_ONLY_FIELDS = [
+    'layout', 'position', 'nodes', 'edges', 'canvas', 'annotations',
+];
+/**
+ * The domain a server message writes.
+ *
+ * Deliberately explicit rather than pattern-matched on the message name: a
+ * message whose domain nobody decided is the one that ends up writing both.
+ */
+const MUTATION_DOMAINS = {
+    'element:create': 'semantic',
+    'element:update': 'semantic',
+    'element:delete': 'semantic',
+    'element:remap-kinds': 'semantic',
+    'relationship:create': 'semantic',
+    'relationship:delete': 'semantic',
+    'diagram:source:save': 'semantic',
+    'methodology:source:save': 'semantic',
+    'csv:import': 'semantic',
+    'diagram:layout:update': 'layout',
+    // User diagrams are a sidecar too — a saved view is presentation state, and
+    // creating one has never written SysML.
+    'diagram:create': 'layout',
+    'diagram:update': 'layout',
+    'diagram:delete': 'layout',
+};
+export function mutationDomain(messageType) {
+    return MUTATION_DOMAINS[messageType] ?? 'neither';
+}
+/** A mutation carrying data from a domain it is not allowed to write. */
+export class MixedMutationDomainError extends Error {
+    messageType;
+    offendingFields;
+    constructor(messageType, offendingFields) {
+        super(`"${messageType}" is a ${mutationDomain(messageType)} mutation but carries layout data `
+            + `(${offendingFields.join(', ')}). Layout changes go to the view sidecar and semantic `
+            + 'changes go to SysML source; one action never writes both.');
+        this.messageType = messageType;
+        this.offendingFields = offendingFields;
+        this.name = 'MixedMutationDomainError';
+    }
+}
+/**
+ * Refuse a semantic mutation that also carries layout data.
+ *
+ * The check runs on the payload rather than trusting the caller, because the
+ * mixture arrives from a client: a properties panel that happened to spread a
+ * node object into its save request would otherwise write a canvas position
+ * into `.sysml` as an ordinary attribute, and nothing downstream would tell it
+ * apart from a modelled one.
+ */
+export function assertSingleDomainMutation(messageType, payload) {
+    if (mutationDomain(messageType) !== 'semantic')
+        return;
+    if (!payload || typeof payload !== 'object')
+        return;
+    const record = payload;
+    const offending = LAYOUT_ONLY_FIELDS.filter(field => record[field] !== undefined);
+    // Attributes are modelled data and are written to source by definition, so
+    // a modelled attribute *named* `position` is legitimate; only top-level
+    // payload fields are presentation.
+    if (offending.length > 0)
+        throw new MixedMutationDomainError(messageType, offending);
+}
+//# sourceMappingURL=mutation-domain.js.map

package/packages/tools/lib/server/mutation-domain.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mutation-domain.js","sourceRoot":"","sources":["../../src/server/mutation-domain.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,EAAE;AACF,6EAA6E;AAC7E,QAAQ;AACR,EAAE;AACF,yEAAyE;AACzE,mEAAmE;AACnE,yEAAyE;AACzE,0DAA0D;AAC1D,EAAE;AACF,0EAA0E;AAC1E,gFAAgF;AAChF,+EAA+E;AAC/E,+EAA+E;AAC/E,4EAA4E;AAC5E,iBAAiB;AACjB,EAAE;AACF,4EAA4E;AAC5E,gFAAgF;AAChF,WAAW;AACX,gFAAgF;AAKhF,yDAAyD;AACzD,MAAM,CAAC,MAAM,kBAAkB,GAAsB;IACjD,QAAQ,EAAE,UAAU,EAAE,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,aAAa;CAClE,CAAC;AAEF;;;;;GAKG;AACH,MAAM,gBAAgB,GAAmC;IACrD,gBAAgB,EAAE,UAAU;IAC5B,gBAAgB,EAAE,UAAU;IAC5B,gBAAgB,EAAE,UAAU;IAC5B,qBAAqB,EAAE,UAAU;IACjC,qBAAqB,EAAE,UAAU;IACjC,qBAAqB,EAAE,UAAU;IACjC,qBAAqB,EAAE,UAAU;IACjC,yBAAyB,EAAE,UAAU;IACrC,YAAY,EAAE,UAAU;IACxB,uBAAuB,EAAE,QAAQ;IACjC,4EAA4E;IAC5E,wCAAwC;IACxC,gBAAgB,EAAE,QAAQ;IAC1B,gBAAgB,EAAE,QAAQ;IAC1B,gBAAgB,EAAE,QAAQ;CAC7B,CAAC;AAEF,MAAM,UAAU,cAAc,CAAC,WAAmB;IAC9C,OAAO,gBAAgB,CAAC,WAAW,CAAC,IAAI,SAAS,CAAC;AACtD,CAAC;AAED,yEAAyE;AACzE,MAAM,OAAO,wBAAyB,SAAQ,KAAK;IAC1B;IAA8B;IAAnD,YAAqB,WAAmB,EAAW,eAAkC;QACjF,KAAK,CACD,IAAI,WAAW,UAAU,cAAc,CAAC,WAAW,CAAC,oCAAoC;cACtF,IAAI,eAAe,CAAC,IAAI,CAAC,IAAI,CAAC,wDAAwD;cACtF,2DAA2D,CAChE,CAAC;QALe,gBAAW,GAAX,WAAW,CAAQ;QAAW,oBAAe,GAAf,eAAe,CAAmB;QAMjF,IAAI,CAAC,IAAI,GAAG,0BAA0B,CAAC;IAC3C,CAAC;CACJ;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,0BAA0B,CAAC,WAAmB,EAAE,OAAgB;IAC5E,IAAI,cAAc,CAAC,WAAW,CAAC,KAAK,UAAU;QAAE,OAAO;IACvD,IAAI,CAAC,OAAO,IAAI,OAAO,OAAO,KAAK,QAAQ;QAAE,OAAO;IACpD,MAAM,MAAM,GAAG,OAAkC,CAAC;IAClD,MAAM,SAAS,GAAG,kBAAkB,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,SAAS,CAAC,CAAC;IAClF,2EAA2E;IAC3E,wEAAwE;IACxE,mCAAmC;IACnC,IAAI,SAAS,CAAC,MAAM,GAAG,CAAC;QAAE,MAAM,IAAI,wBAAwB,CAAC,WAAW,EAAE,SAAS,CAAC,CAAC;AACzF,CAAC"}

package/packages/tools/lib/server/persistor.d.ts

@@ -1,12 +1,67 @@
-/**
- * Persists an element change back to its source .sysml file.
- *
- * 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.
- */
-export declare function saveElementToFile(cwd: string, element: any): {
+import { type IrIdentityIndex } from '../model/ir-identity.js';
+/** Default home for an element the request does not place. */
+export declare const DEFAULT_ELEMENT_FILE = "model/catalog/project.sysml";
+export interface ElementWriteRequest {
+    id: string;
+    name?: string;
+    kind?: string;
+    construct?: string;
+    layer?: string;
+    doc?: string;
+    attributes?: Record<string, string>;
+    /** Project-relative source file. */
+    file?: string;
+    /**
+     * IR identity of the declaration being edited.
+     *
+     * Required to *update* an existing declaration. Absent means "create":
+     * there is no identity to quote for source that does not exist yet.
+     */
+    irIdentity?: string;
+    /**
+     * The element ID the quoted identity is expected to name, when this write
+     * changes the declaration's own identifier.
+     *
+     * Without it a rename is indistinguishable from a stale address — both are
+     * "the identity names something other than `id`" — and the safe reading of
+     * that ambiguity is to refuse. Saying so explicitly is what makes a rename
+     * a deliberate act rather than an accident the checker has to tolerate.
+     */
+    renamedFrom?: string;
+}
+/** Advisory notes about a write that succeeded. */
+export interface ElementWriteWarning {
+    code: 'rename-is-text-only';
+    message: string;
+}
+export interface ElementWriteResult {
     success: boolean;
     filePath: string;
+    /** True when the declaration was replaced rather than appended. */
+    replaced?: boolean;
+    warnings?: ElementWriteWarning[];
     error?: string;
-};
+    /** Set when the failure was a stale identity, so callers can say so. */
+    stale?: boolean;
+}
+/**
+ * Why a rename is only a text edit, said once here so every surface says the
+ * same thing.
+ *
+ * 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 declare const RENAME_IS_TEXT_ONLY: string;
+/**
+ * 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 declare function saveElementToFile(cwd: string, element: ElementWriteRequest, index?: IrIdentityIndex): Promise<ElementWriteResult>;
 //# sourceMappingURL=persistor.d.ts.map

package/packages/tools/lib/server/persistor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"persistor.d.ts","sourceRoot":"","sources":["../../src/server/persistor.ts"],"names":[],"mappings":"AAIA;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,GAAG;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAmEnH"}
+{"version":3,"file":"persistor.d.ts","sourceRoot":"","sources":["../../src/server/persistor.ts"],"names":[],"mappings":"AA4BA,OAAO,EAIH,KAAK,eAAe,EACvB,MAAM,yBAAyB,CAAC;AAEjC,8DAA8D;AAC9D,eAAO,MAAM,oBAAoB,gCAAgC,CAAC;AAElE,MAAM,WAAW,mBAAmB;IAChC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpC,oCAAoC;IACpC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;;OAKG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;;;;;OAQG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,mDAAmD;AACnD,MAAM,WAAW,mBAAmB;IAChC,IAAI,EAAE,qBAAqB,CAAC;IAC5B,OAAO,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,kBAAkB;IAC/B,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,mEAAmE;IACnE,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,QAAQ,CAAC,EAAE,mBAAmB,EAAE,CAAC;IACjC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,wEAAwE;IACxE,KAAK,CAAC,EAAE,OAAO,CAAC;CACnB;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,mBAAmB,QAGI,CAAC;AAErC;;;;;;;GAOG;AACH,wBAAsB,iBAAiB,CACnC,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,mBAAmB,EAC5B,KAAK,CAAC,EAAE,eAAe,GACxB,OAAO,CAAC,kBAAkB,CAAC,CA8E7B"}

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

@@ -1,30 +1,66 @@
-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';
+/** 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 +69,112 @@ 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.',
+            };
         }
-        else {
-            newContent = content + '\n' + newUsage + '\n';
+        let located;
+        try {
+            located = await locateDeclaration(content, index, identity, element.renamedFrom ?? element.id);
         }
+        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 {
+        updated = appendToLastPackage(content, usage);
+    }
+    // Parse-before-commit: 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.
+    const { errors } = await parseText(updated);
+    if (errors.length > 0) {
+        return {
+            success: false, filePath: relativePath,
+            error: `The updated source did not parse (${errors[0].message}); the file was left unchanged.`,
+        };
     }
     try {
-        writeFileSync(filePath, newContent, 'utf8');
-        log(`Successfully wrote ${newContent.length} bytes to ${filePath}`);
-        return { success: true, filePath: relativePath };
+        atomicWrite(filePath, updated);
     }
     catch (e) {
-        log(`CRITICAL: Failed to write to ${filePath}: ${e}`);
-        return { success: false, filePath: relativePath, error: String(e) };
+        return { success: false, filePath: relativePath, error: `Could not write ${relativePath}: ${String(e)}` };
+    }
+    return { success: true, filePath: relativePath, replaced, ...(warnings.length ? { warnings } : {}) };
+}
+/** 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 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;
@@ -83,8 +101,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): 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.
  *

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":"AA0BA,OAAO,KAAK,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAC3E,OAAO,KAAK,EACR,yBAAyB,EACzB,yBAAyB,EAC5B,MAAM,mCAAmC,CAAC;AAE3C,OAAO,EAEH,KAAK,eAAe,EACvB,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAEH,KAAK,oBAAoB,EAC5B,MAAM,qBAAqB,CAAC;AAY7B,gFAAgF;AAChF,eAAO,MAAM,2BAA2B,sCAAsC,CAAC;AAE/E,sFAAsF;AACtF,eAAO,MAAM,yBAAyB,UAAY,CAAC;AAEnD,6DAA6D;AAC7D,eAAO,MAAM,iCAAiC,QAA4B,CAAC;AAE3E,MAAM,WAAW,yBAAyB;IACtC,iEAAiE;IACjE,WAAW,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACzC,gEAAgE;IAChE,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB;;;OAGG;IACH,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC5B,gEAAgE;IAChE,uBAAuB,CAAC,EAAE,MAAM,CAAC;IACjC;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,eAAe,CAAC;CAC7B;AAED,4EAA4E;AAC5E,MAAM,MAAM,eAAe,GACrB,WAAW,GACX,yBAAyB,GACzB,qBAAqB,GACrB,qBAAqB,GACrB,gBAAgB,GAChB,wBAAwB,CAAC;AAE/B,MAAM,WAAW,qBAAqB;IAClC,mEAAmE;IACnE,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,eAAe,CAAC;IACxB,iEAAiE;IACjE,UAAU,EAAE,OAAO,CAAC;CACvB;AAED,MAAM,WAAW,uBAAuB;IACpC,OAAO,EAAE,OAAO,CAAC;IACjB,8CAA8C;IAC9C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,wDAAwD;IACxD,QAAQ,CAAC,EAAE,oBAAoB,CAAC;IAChC,2CAA2C;IAC3C,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,eAAe,CAAC,EAAE,eAAe,CAAC;IAClC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,0DAA0D;IAC1D,KAAK,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,wBAAwB;IACrC,OAAO,EAAE,OAAO,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,sEAAsE;IACtE,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,KAAK,CAAC,EAAE,MAAM,CAAC;CAClB;AAID;;;;;;GAMG;AACH,wBAAgB,0BAA0B,CACtC,YAAY,EAAE,MAAM,EACpB,OAAO,EAAE,yBAAyB,GACnC,OAAO,CAkCT;AAID;;;;;;;;;;;GAWG;AACH,wBAAgB,4BAA4B,CACxC,OAAO,EAAE,IAAI,CAAC,yBAAyB,EAAE,UAAU,GAAG,UAAU,GAAG,YAAY,CAAC,EAChF,KAAK,EAAE,IAAI,CAAC,YAAY,EAAE,UAAU,CAAC,EACrC,OAAO,EAAE,yBAAyB,GACnC,qBAAqB,CAyCvB;AAgDD;;;;GAIG;AACH,wBAAgB,sBAAsB,CAClC,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,GACxB,MAAM,CAQR;AAED;;;;;;GAMG;AACH,wBAAgB,+BAA+B,CAC3C,EAAE,EAAE,MAAM,EACV,UAAU,EAAE,yBAAyB,EACrC,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,EAChB,QAAQ,CAAC,EAAE,MAAM,EACjB,KAAK,CAAC,EAAE,MAAM,GACf,MAAM,CAER;AAID;;;;;;GAMG;AACH,wBAAsB,iBAAiB,CACnC,OAAO,EAAE,yBAAyB,EAClC,UAAU,EAAE,yBAAyB,EACrC,KAAK,EAAE,IAAI,CAAC,YAAY,EAAE,UAAU,GAAG,eAAe,CAAC,EACvD,OAAO,EAAE,yBAAyB,GACnC,OAAO,CAAC,uBAAuB,CAAC,CAuElC;AAwGD;;;;;;GAMG;AACH,wBAAsB,kBAAkB,CACpC,YAAY,EAAE,IAAI,CAAC,gBAAgB,EAAE,IAAI,GAAG,MAAM,GAAG,OAAO,CAAC,EAC7D,OAAO,EAAE,yBAAyB,GACnC,OAAO,CAAC,wBAAwB,CAAC,CA6DnC"}