@memoarchitect/tools 0.6.7 → 0.7.2

package/packages/tools/lib/server/dev-server.js

@@ -5,14 +5,46 @@
 //   - WebSocket endpoint for pushing model updates to browser
 // ─────────────────────────────────────────────────────────────────────────────
 import { createServer as createHttpServer } from 'node:http';
-import { createHash } from 'node:crypto';
+import { createHash, randomUUID } from 'node:crypto';
 import { isAbsolute, relative, resolve } from 'node:path';
 import { existsSync, readFileSync, realpathSync, writeFileSync, mkdirSync, createReadStream, statSync } from 'node:fs';
 import { extname } from 'node:path';
 import { findMemoManifests, validateRelationshipMutation, validateRelationshipDeletion } from '@memoarchitect/tools';
+import { indexFromIdentityTable } from '../model/ir-identity.js';
+import { recompileProject, writeElement } from '../operations/authoring.js';
 import { isWritableRelationshipFile, removeRelationship, resolveRelationshipPlacement, writeRelationship, } from './relationship-writer.js';
+import { removeElement } from './element-writer.js';
+import { assertSingleDomainMutation, MixedMutationDomainError } from './mutation-domain.js';
+import { classifyConflict } from './conflict-policy.js';
+import { checkRulePolicy, insertRulePolicy, renderRulePolicy } from './rule-policy-writer.js';
 import { loadViewLayouts, saveViewLayout } from './view-layout-store.js';
 import { loadDhfDocs, saveDhfDoc, deleteDhfDoc, loadDhfSettings, saveDhfSettings, listRepoTemplates, readRepoTemplate, saveRepoTemplate, } from './dhf-doc-store.js';
+const MODEL_MUTATION_MESSAGES = new Set([
+    'element:update', 'element:create', 'element:delete', 'element:remap-kinds',
+    'relationship:create', 'relationship:delete',
+    'diagram:create', 'diagram:update', 'diagram:delete', 'diagram:layout:update', 'diagram:source:save',
+    'methodology:source:save', 'csv:import', 'screen-capture:upload',
+    'ontology:install', 'ontology:remove', 'ontology:save-selection',
+    'dhf:doc:save', 'dhf:doc:delete', 'dhf:settings:save', 'dhf:template:save',
+    'llm:chat:apply', 'llm:settings:save',
+]);
+/** Exported so the lockout boundary is mechanically testable. */
+export function isModelMutationMessage(type) {
+    return MODEL_MUTATION_MESSAGES.has(type);
+}
+/**
+ * Project/model state is reconciled over the MEMO WebSocket. Vite must never
+ * turn these writes into a browser reload, even when a local ontology package
+ * is symlinked beneath Vite's dependency graph.
+ */
+export function isModelOwnedWatchPath(path) {
+    const normalized = path.replaceAll('\\', '/');
+    return normalized.endsWith('.sysml')
+        || normalized.endsWith('/memo.config.yaml')
+        || normalized.endsWith('/memo.package.yaml')
+        || normalized.includes('/.memo/')
+        || normalized.includes('/model/assets/');
+}
 // ─── User-diagram persistence helpers ──────────────────────────────────────
 function userDiagramsPath(projectRoot) {
     return resolve(projectRoot, '.memo', 'user-diagrams.json');
@@ -41,6 +73,9 @@ const STATIC_MIME = {
     '.json': 'application/json',
     '.svg': 'image/svg+xml',
     '.png': 'image/png',
+    '.jpg': 'image/jpeg',
+    '.jpeg': 'image/jpeg',
+    '.webp': 'image/webp',
     '.ico': 'image/x-icon',
     '.woff2': 'font/woff2',
     '.woff': 'font/woff',
@@ -53,9 +88,79 @@ function streamFile(res, fullPath, status = 200) {
     res.writeHead(status, { 'Content-Type': mime, 'Content-Length': size });
     createReadStream(fullPath).pipe(res);
 }
+/** Resolve only project-owned screen captures under model/assets. */
+export function resolveProjectAssetRequest(projectRoot, requestUrl) {
+    let pathname;
+    try {
+        pathname = decodeURIComponent(requestUrl.split('?')[0]);
+    }
+    catch {
+        return undefined;
+    }
+    if (!pathname.startsWith('/model/assets/'))
+        return undefined;
+    const assetRoot = resolve(projectRoot, 'model', 'assets');
+    const requested = resolve(projectRoot, pathname.replace(/^\//, ''));
+    const fromAssetRoot = relative(assetRoot, requested);
+    if (!fromAssetRoot || fromAssetRoot === '..' || fromAssetRoot.startsWith('../') || fromAssetRoot.startsWith('..\\')) {
+        return undefined;
+    }
+    return requested;
+}
 export async function createDevServer(options) {
     const { port, webPackagePath, initialMessages, transformClientHtml } = options;
     const host = '127.0.0.1';
+    // State publications are ordered independently of model semantics. The
+    // three state payloads from a rebuild share one revision so the browser
+    // cannot combine a model from one build with validation from another.
+    const workspaceSessionId = randomUUID();
+    const writeTransactions = new Map();
+    let workspaceRevision = 1;
+    let mutationLockout;
+    /** Set while the project source does not compile; cleared by the next clean rebuild. */
+    let sourceIncoherence;
+    function stampWorkspace(messages, baseRevision, snapshot = false, changedSourceIds = []) {
+        const model = messages.find(message => message.type === 'model:update');
+        const sourceGraphHash = createHash('sha256')
+            .update(JSON.stringify(model?.payload.sourceGraph ?? {})).digest('hex').slice(0, 16);
+        const reusableRegistryHash = String(model?.payload?.ontologyHash ?? 'none');
+        const projectRegistryHash = createHash('sha256')
+            .update(JSON.stringify(model?.payload.registries ?? {})).digest('hex').slice(0, 16);
+        const previous = initialMessages.find(message => message.type === 'model:update');
+        const modelDelta = !snapshot && model && previous
+            ? {
+                upsertElements: Object.fromEntries(Object.entries(model.payload.elements).filter(([id, element]) => JSON.stringify(previous.payload.elements[id]) !== JSON.stringify(element))),
+                removeElementIds: Object.keys(previous.payload.elements).filter(id => !(id in model.payload.elements)),
+                patch: Object.fromEntries(Object.entries(model.payload).filter(([key]) => key !== 'elements')),
+            }
+            : undefined;
+        return messages.map(message => {
+            if (message.type !== 'model:update' &&
+                message.type !== 'validation:update' &&
+                message.type !== 'completeness:update')
+                return message;
+            return {
+                ...message,
+                revision: {
+                    workspaceSessionId, revision: workspaceRevision, baseRevision, snapshot,
+                    sourceGraphHash, reusableRegistryHash, projectRegistryHash,
+                    changedSourceIds: [...changedSourceIds].sort(),
+                    modelDelta,
+                },
+            };
+        });
+    }
+    const initialSnapshot = stampWorkspace(initialMessages, null, true);
+    initialMessages.length = 0;
+    initialMessages.push(...initialSnapshot);
+    function recordWriteTransaction(sourceFile, text) {
+        const id = randomUUID();
+        writeTransactions.set(sourceFile.replaceAll('\\', '/'), {
+            id, hash: createHash('sha256').update(text).digest('hex').slice(0, 16),
+            createdAt: Date.now(), unmatchedWrites: 0,
+        });
+        return id;
+    }
     // A source client can use Vite middleware. A packaged client can provide a
     // prebuilt dist/ directory. Tools does not resolve or depend on that client.
     const hasWebSource = existsSync(resolve(webPackagePath, 'index.html'));
@@ -107,6 +212,20 @@ export async function createDevServer(options) {
         streamFile(res, fullPath);
         return true;
     }
+    /** Serve captures referenced by project-relative ScreenCapture.imageUri. */
+    function serveProjectAsset(req, res) {
+        const requestUrl = req.url ?? '/';
+        if (!requestUrl.split('?')[0].startsWith('/model/assets/'))
+            return false;
+        const requested = resolveProjectAssetRequest(options.projectRoot, requestUrl);
+        if (!requested || !existsSync(requested) || !statSync(requested).isFile()) {
+            res.writeHead(404);
+            res.end('Capture not found');
+            return true;
+        }
+        streamFile(res, requested);
+        return true;
+    }
     /** Serve the caller-provided prebuilt client as an SPA. */
     function serveWebDist(req, res) {
         if (!hasWebDist)
@@ -140,13 +259,19 @@ export async function createDevServer(options) {
         // Create Vite dev server in middleware mode
         viteServer = await vite.createServer({
             root: webPackagePath,
-            server: { middlewareMode: true, host },
+            server: {
+                middlewareMode: true,
+                host,
+                watch: { ignored: isModelOwnedWatchPath },
+            },
             appType: 'spa',
             plugins: transformClientHtml
                 ? [{ name: 'memo-client-html', transformIndexHtml: transformClientHtml }]
                 : [],
         });
         server = createHttpServer((req, res) => {
+            if (serveProjectAsset(req, res))
+                return;
             if (serveHelp(req, res))
                 return;
             viteServer.middlewares(req, res);
@@ -155,6 +280,8 @@ export async function createDevServer(options) {
     else if (hasWebDist) {
         // Packaged install: serve the prebuilt web app statically
         server = createHttpServer((req, res) => {
+            if (serveProjectAsset(req, res))
+                return;
             if (serveHelp(req, res))
                 return;
             serveWebDist(req, res);
@@ -163,6 +290,8 @@ export async function createDevServer(options) {
     else {
         // Fallback: serve a basic page that connects via WebSocket
         server = createHttpServer((req, res) => {
+            if (serveProjectAsset(req, res))
+                return;
             res.writeHead(200, { 'Content-Type': 'text/html' });
             res.end(`
                 <!DOCTYPE html>
@@ -188,6 +317,20 @@ export async function createDevServer(options) {
     const { WebSocketServer } = await import('ws');
     const wss = new WebSocketServer({ server });
     const clients = new Set();
+    // User-created views are project state, not session state. Merge them into
+    // the initial model payload so a UI screen created from the workbench is
+    // still present after the dev server restarts.
+    const initialModelIndex = initialMessages.findIndex(message => message.type === 'model:update');
+    if (initialModelIndex >= 0) {
+        const initialModel = initialMessages[initialModelIndex];
+        const authored = initialModel.payload.diagrams ?? [];
+        const authoredIds = new Set(authored.map(diagram => diagram.id));
+        const userDiagrams = loadUserDiagrams(options.projectRoot).filter(diagram => !authoredIds.has(diagram.id));
+        initialMessages[initialModelIndex] = {
+            type: 'model:update',
+            payload: { ...initialModel.payload, diagrams: [...authored, ...userDiagrams] },
+        };
+    }
     const currentDiagrams = () => {
         const model = initialMessages.find(m => m.type === 'model:update');
         return model?.payload.diagrams ?? [];
@@ -215,23 +358,156 @@ export async function createDevServer(options) {
                 client.send(JSON.stringify(updatedMsg));
         }
     }
+    function broadcastEditConflict(payload) {
+        const message = { type: 'app:edit-conflict', payload };
+        for (const client of clients) {
+            if (client.readyState === 1)
+                client.send(JSON.stringify(message));
+        }
+    }
+    /**
+     * Provenance origin of a file being written.
+     *
+     * The caller has already established the path is inside the project root,
+     * so the only distinction left that changes the conflict route is whether
+     * it is reusable source the project happens to vendor — a methodology or
+     * extension package living in the workspace. Those are frozen for the
+     * session exactly as an installed package is, so a change to one escalates.
+     */
+    function originOf(sourcePath) {
+        const methodology = initialMessages.find(m => m.type === 'methodology:update');
+        const methodologyFiles = new Set((methodology?.payload?.folders ?? [])
+            .flatMap((folder) => (folder.sourceFiles ?? [])
+            .map((file) => resolve(options.projectRoot, file))));
+        if (methodologyFiles.has(sourcePath))
+            return 'methodology';
+        return 'project';
+    }
+    function checkMutationPrecondition(precondition, rejectedCommandId, rejectedDraft) {
+        if (!precondition)
+            return 'The mutation has no source precondition; reload before saving.';
+        const projectPath = realpathSync(resolve(options.projectRoot));
+        const sourcePath = resolve(projectPath, precondition.sourceFile);
+        if (!sourcePath.startsWith(`${projectPath}/`))
+            return 'Mutation source is outside the project.';
+        const currentHash = existsSync(sourcePath) ? fileRevision(readFileSync(sourcePath, 'utf8')) : '';
+        // Section 13.5's two routes. The decision is in `conflict-policy.ts`
+        // so it can be tested without driving a live server; this applies it.
+        const decision = classifyConflict({
+            commandSessionId: precondition.workspaceSessionId,
+            currentSessionId: workspaceSessionId,
+            expectedSourceHash: precondition.expectedSourceHash,
+            currentSourceHash: currentHash,
+            origin: originOf(sourcePath),
+            // Source incoherence is deliberately NOT folded in here. It is held
+            // earlier, on the message handler, so no mutation reaches this
+            // classifier while the project does not parse. Routing it through
+            // here instead would classify a stale hash as
+            // `dependency-closure-uncomputable` and demand a relaunch — which
+            // is the one outcome a source typo must never produce.
+            dependencyClosureComputable: !mutationLockout,
+        });
+        if (decision.outcome === 'accept')
+            return undefined;
+        if (decision.outcome === 'lockout') {
+            const lockout = {
+                type: 'app:restart-required',
+                reason: decision.escalation === 'reusable-source-changed'
+                    ? 'ontology-source-changed' : 'dependency-closure-uncomputable',
+                changedFile: precondition.sourceFile,
+                instruction: decision.reason,
+            };
+            mutationLockout = lockout;
+            for (const client of clients) {
+                if (client.readyState === 1)
+                    client.send(JSON.stringify(lockout));
+            }
+            return decision.reason;
+        }
+        broadcastEditConflict({
+            sourceFile: precondition.sourceFile,
+            targetElementIds: precondition.targetElementIds,
+            baseRevision: precondition.baseRevision,
+            currentRevision: workspaceRevision,
+            expectedSourceHash: precondition.expectedSourceHash,
+            currentSourceHash: currentHash,
+            rejectedCommandId,
+            rejectedDraft,
+        });
+        return `${precondition.sourceFile} changed on disk; no write was made.`;
+    }
     /** Latest model DTO — broadcast() replaces initialMessages on every rebuild. */
     const currentModel = () => initialMessages.find(m => m.type === 'model:update')?.payload;
+    /**
+     * Identities minted by the most recent authoring recompile.
+     *
+     * A write-back recompiles through the lowering provider and therefore knows
+     * the addresses its own edit produced before the file watcher has caught
+     * up. Holding them here is what lets a user make two edits in a row without
+     * the second one being addressed to a revision that no longer exists.
+     * Cleared by `broadcast`, because a published model supersedes it.
+     */
+    let writeBackIndex;
+    /** The index every write resolves its identities against. */
+    const irIndex = () => writeBackIndex ?? indexFromIdentityTable(currentModel()?.irIdentities);
+    /**
+     * Recompile after a semantic write, through the *selected* lowering
+     * provider (§6.2).
+     *
+     * Not a refresh optimisation: the watcher rebuild that follows is what
+     * publishes the new model. This exists so the identities handed back with
+     * the write are the ones the write created, rather than whatever the client
+     * happened to be holding. It costs a project lowering per authored change,
+     * which is the price of an address that is never a revision behind.
+     */
+    /** What every authoring operation is given: the project, its settings, and the index. */
+    async function authoringContext() {
+        const { loadAndResolveConfig } = await import('./config-resolver.js');
+        const { findConfigFile } = await import('@memoarchitect/tools');
+        const configPath = findConfigFile(options.projectRoot);
+        return {
+            projectDir: options.projectRoot,
+            config: configPath ? loadAndResolveConfig(configPath) : undefined,
+            irIndex: irIndex(),
+        };
+    }
+    async function recompileAfterWrite() {
+        try {
+            writeBackIndex = (await recompileProject(await authoringContext())).index;
+        }
+        catch (e) {
+            // A recompile that fails leaves the previous index in place: the
+            // write itself already succeeded, and refusing to answer would be
+            // reporting a failure that did not happen. The next watcher rebuild
+            // republishes the identities either way.
+            console.warn(`[Authoring] Recompile after write failed: ${e instanceof Error ? e.message : String(e)}`);
+        }
+    }
     /**
      * Build the query context the LLM engines read from, against whatever the
      * server currently holds. Every LLM handler needs the same four pieces, so
      * they share this rather than each re-deriving them.
      */
     async function llmQueryContext() {
-        const { createQueryContext, findConfigFile } = await import('@memoarchitect/tools');
+        const { createQueryContext, findConfigFile, loadOntologyRegistries, ontologyViewFrom, EMPTY_ONTOLOGY_VIEW } = await import('@memoarchitect/tools');
         const { loadAndResolveConfig } = await import('./config-resolver.js');
         const modelMsg = initialMessages.find(m => m.type === 'model:update');
         const validMsg = initialMessages.find(m => m.type === 'validation:update');
         const compMsg = initialMessages.find(m => m.type === 'completeness:update');
         const configPath = findConfigFile(options.projectRoot);
-        const config = configPath ? await loadAndResolveConfig(configPath) : {};
+        const config = configPath ? loadAndResolveConfig(configPath) : { projectName: 'untitled' };
+        // Kinds and relationships come from the resolved SysML, not from the
+        // settings file the config path points at.
+        let ontology = EMPTY_ONTOLOGY_VIEW;
+        try {
+            const loaded = await loadOntologyRegistries(options.projectRoot);
+            ontology = ontologyViewFrom(loaded.registries.kindRegistry, loaded.registries.relationshipRegistry);
+        }
+        catch {
+            // A project whose ontology does not resolve still has a model to query.
+        }
         const ctx = createQueryContext(modelMsg?.payload ?? {}, validMsg?.payload ?? { violations: [] }, compMsg?.payload ?? { overall: 0, layers: [] }, config);
-        return { ctx, config };
+        return { ctx, config, ontology };
     }
     /** Settings status for the client — provider/model/origin, never the key. */
     async function llmSettings() {
@@ -250,9 +526,9 @@ export async function createDevServer(options) {
         const { saveElementToFile } = await import('./persistor.js');
         switch (change.kind) {
             case 'create-element': {
-                const { config } = await llmQueryContext();
-                const kindDef = config.kinds?.[change.elementKind];
-                const result = saveElementToFile(options.projectRoot, {
+                const { ontology } = await llmQueryContext();
+                const kindDef = ontology.kinds[change.elementKind];
+                const result = await saveElementToFile(options.projectRoot, {
                     id: change.elementId,
                     name: change.name,
                     kind: change.elementKind,
@@ -263,20 +539,22 @@ export async function createDevServer(options) {
                 });
                 if (!result.success)
                     throw new Error(result.error ?? 'Failed to write the element.');
+                await recompileAfterWrite();
                 return;
             }
             case 'update-element': {
                 const existing = currentModel()?.elements?.[change.elementId];
                 if (!existing)
                     throw new Error(`Element "${change.elementId}" no longer exists.`);
-                const result = saveElementToFile(options.projectRoot, {
+                const result = await saveElementToFile(options.projectRoot, {
                     ...existing,
                     ...(change.changes.name !== undefined ? { name: change.changes.name } : {}),
                     ...(change.changes.doc !== undefined ? { doc: change.changes.doc } : {}),
                     attributes: { ...existing.attributes, ...(change.changes.attributes ?? {}) },
-                });
+                }, irIndex());
                 if (!result.success)
                     throw new Error(result.error ?? 'Failed to write the element.');
+                await recompileAfterWrite();
                 return;
             }
             case 'create-relationship': {
@@ -328,6 +606,7 @@ export async function createDevServer(options) {
             ontologyRoots: options.ontologyRoots,
             designatedFiles: options.relationshipFiles,
             canonicalFile: options.canonicalRelationshipFile,
+            irIndex: irIndex(),
         };
     }
     /**
@@ -344,6 +623,9 @@ export async function createDevServer(options) {
             type: 'relationship:create:result',
             payload: { requestId, success: false, error, diagnostics },
         });
+        const conflict = checkMutationPrecondition(payload.precondition, requestId, payload);
+        if (conflict)
+            return reject(conflict);
         const model = currentModel();
         if (!model)
             return reject('The model is not loaded yet.');
@@ -377,8 +659,12 @@ export async function createDevServer(options) {
             console.error(`[Relationship] Write failed: ${result.error}`);
             return reject(result.error ?? 'The relationship could not be written.', validation.diagnostics);
         }
-        console.log(`[Persisted] relationship ${result.relationshipId} (${validation.normalizedType}) ` +
-            `to ${result.sourceFile} [${result.placementReason}]`);
+        console.log(`[Persisted] relationship ${result.relationshipId ?? `(${result.notation})`} ` +
+            `(${validation.normalizedType}) to ${result.sourceFile} [${result.placementReason}]`);
+        if (result.sourceFile) {
+            recordWriteTransaction(result.sourceFile, readFileSync(resolve(options.projectRoot, result.sourceFile), 'utf8'));
+        }
+        await recompileAfterWrite();
         // The file watcher rebuilds and broadcasts the canonical model; this
         // response only confirms the write and carries the IDs the client needs
         // to replace its pending row.
@@ -388,6 +674,8 @@ export async function createDevServer(options) {
                 requestId,
                 success: true,
                 relationshipId: result.relationshipId,
+                notation: result.notation,
+                declaration: result.declaration,
                 type: validation.normalizedType,
                 sourceId: payload.sourceId,
                 targetId: payload.targetId,
@@ -404,6 +692,9 @@ export async function createDevServer(options) {
             type: 'relationship:delete:result',
             payload: { requestId, success: false, relationshipId, error, diagnostics },
         });
+        const conflict = checkMutationPrecondition(payload.precondition, requestId, payload);
+        if (conflict)
+            return reject(conflict);
         const model = currentModel();
         if (!model)
             return reject('The model is not loaded yet.');
@@ -420,6 +711,10 @@ export async function createDevServer(options) {
             return reject(result.error ?? 'The relationship could not be removed.');
         }
         console.log(`[Persisted] removed relationship ${relationshipId} from ${result.sourceFile}`);
+        if (result.sourceFile) {
+            recordWriteTransaction(result.sourceFile, readFileSync(resolve(options.projectRoot, result.sourceFile), 'utf8'));
+        }
+        await recompileAfterWrite();
         return {
             type: 'relationship:delete:result',
             payload: {
@@ -431,6 +726,57 @@ export async function createDevServer(options) {
             },
         };
     }
+    async function handleElementDelete(payload) {
+        const requestId = payload?.requestId ?? '';
+        const elementId = payload?.elementId ?? '';
+        const reject = (error) => ({
+            type: 'element:delete:result',
+            payload: { requestId, elementId, success: false, error },
+        });
+        const conflict = checkMutationPrecondition(payload.precondition, requestId, payload);
+        if (conflict)
+            return reject(conflict);
+        const model = currentModel();
+        if (!model)
+            return reject('The model is not loaded yet.');
+        const element = model.elements[elementId];
+        if (!element)
+            return reject(`Element "${elementId}" was not found.`);
+        if (element.provenance && !element.provenance.declaration.writable) {
+            return reject(`Element "${elementId}" is read-only ${element.provenance.declaration.origin} content.`);
+        }
+        const result = await removeElement(element, model, options.projectRoot);
+        if (result.success) {
+            for (const sourceFile of result.sourceFiles ?? []) {
+                const path = resolve(options.projectRoot, sourceFile);
+                if (existsSync(path))
+                    recordWriteTransaction(sourceFile, readFileSync(path, 'utf8'));
+            }
+            // User-authored diagrams are sidecars rather than semantic
+            // relationships, but they must not retain a stale element ID.
+            const diagrams = loadUserDiagrams(options.projectRoot);
+            let changed = false;
+            const cleaned = diagrams.map(diagram => {
+                if (!diagram.elementIds?.includes(elementId))
+                    return diagram;
+                changed = true;
+                return { ...diagram, elementIds: diagram.elementIds.filter(id => id !== elementId) };
+            });
+            if (changed)
+                saveUserDiagrams(options.projectRoot, cleaned);
+        }
+        return {
+            type: 'element:delete:result',
+            payload: {
+                requestId,
+                elementId,
+                success: result.success,
+                sourceFiles: result.sourceFiles,
+                removedRelationshipIds: result.removedRelationshipIds,
+                error: result.error,
+            },
+        };
+    }
     /** Convert a DhfBlock (from document IR) to a markdown string */
     function blockToMarkdown(block) {
         switch (block.type) {
@@ -505,10 +851,17 @@ export async function createDevServer(options) {
     }
     wss.on('connection', (ws) => {
         clients.add(ws);
+        options.onClientCountChanged?.(clients.size);
         // Send initial state to new connections
         for (const msg of initialMessages) {
             ws.send(JSON.stringify(msg));
         }
+        if (mutationLockout)
+            ws.send(JSON.stringify(mutationLockout));
+        // A client that connects while the source is broken must learn that the
+        // model it just received is the last good one, not the current file.
+        if (sourceIncoherence)
+            ws.send(JSON.stringify(sourceIncoherence));
         // Send all sidecar layouts on connect
         const layouts = loadViewLayouts(options.projectRoot, currentDiagrams());
         if (Object.keys(layouts).length > 0) {
@@ -542,25 +895,194 @@ export async function createDevServer(options) {
                 console.error('[LLM] settings load failed:', e);
             }
         })();
-        ws.on('close', () => clients.delete(ws));
+        ws.on('close', () => {
+            clients.delete(ws);
+            options.onClientCountChanged?.(clients.size);
+        });
         ws.on('message', async (data) => {
             try {
                 const msg = JSON.parse(data.toString());
+                if (mutationLockout && isModelMutationMessage(msg.type)) {
+                    // A section 13.5 escalation is a hard server boundary;
+                    // stale and hand-authored clients cannot write through it.
+                    ws.send(JSON.stringify(mutationLockout));
+                    return;
+                }
+                if (sourceIncoherence && isModelMutationMessage(msg.type)) {
+                    // Held, not locked out: the write cannot be placed while the
+                    // closure is unknown, but the hold lifts by itself as soon
+                    // as the source parses again.
+                    ws.send(JSON.stringify(sourceIncoherence));
+                    return;
+                }
+                // One action writes one store (§6.2). A semantic mutation
+                // carrying canvas geometry is refused here rather than at the
+                // writer, so no handler has to remember the rule.
+                try {
+                    assertSingleDomainMutation(msg.type, msg.payload);
+                }
+                catch (e) {
+                    if (!(e instanceof MixedMutationDomainError))
+                        throw e;
+                    console.warn(`[Mutation] ${e.message}`);
+                    ws.send(JSON.stringify({
+                        type: 'app:error',
+                        payload: { requestId: msg.payload?.requestId, error: e.message },
+                    }));
+                    return;
+                }
                 if (msg.type === 'request:refresh') {
-                    // Re-send current state
-                    for (const m of initialMessages) {
+                    // A missed publication always falls back to one coherent
+                    // snapshot, never a partial replay of old deltas.
+                    for (const m of stampWorkspace(initialMessages, null, true)) {
                         ws.send(JSON.stringify(m));
                     }
                 }
                 else if (msg.type === 'element:update' || msg.type === 'element:create') {
-                    // 1. Persist to FS
-                    const { saveElementToFile } = await import('./persistor.js');
                     const { projectRoot } = options;
-                    const result = saveElementToFile(projectRoot, msg.payload);
+                    const { requestId = '', id = '' } = msg.payload ?? {};
+                    const reply = (payload) => ws.send(JSON.stringify({
+                        type: 'element:mutation:result',
+                        payload: { requestId, elementId: id, ...payload },
+                    }));
+                    const existing = currentModel()?.elements[msg.payload?.id];
+                    if (existing?.provenance && !existing.provenance.declaration.writable) {
+                        reply({ success: false, rejectedDraft: msg.payload,
+                            error: `Element "${existing.id}" is read-only ${existing.provenance.declaration.origin} content.` });
+                        return;
+                    }
+                    const precondition = msg.payload?.precondition;
+                    if (!precondition) {
+                        reply({ success: false, conflict: true, rejectedDraft: msg.payload,
+                            error: 'The edit has no source precondition; reload it before saving.' });
+                        return;
+                    }
+                    if (precondition) {
+                        if (precondition.workspaceSessionId !== workspaceSessionId) {
+                            reply({ success: false, conflict: true, rejectedDraft: msg.payload,
+                                error: 'The workspace runtime changed; no write was made.' });
+                            return;
+                        }
+                        const sourcePath = resolve(projectRoot, precondition.sourceFile);
+                        const projectPath = realpathSync(resolve(projectRoot));
+                        // A precondition that does not name a project file is
+                        // untrustworthy: do not silently turn it into a write.
+                        if (!sourcePath.startsWith(`${projectPath}/`) ||
+                            (msg.type === 'element:update' && !existsSync(sourcePath))) {
+                            reply({ success: false, conflict: true, rejectedDraft: msg.payload,
+                                error: 'Mutation source is not a current project file.' });
+                            return;
+                        }
+                        const currentHash = existsSync(sourcePath)
+                            ? fileRevision(readFileSync(sourcePath, 'utf8')) : '';
+                        if (precondition.expectedSourceHash !== currentHash) {
+                            broadcastEditConflict({
+                                sourceFile: precondition.sourceFile,
+                                targetElementIds: precondition.targetElementIds,
+                                baseRevision: precondition.baseRevision,
+                                currentRevision: workspaceRevision,
+                                expectedSourceHash: precondition.expectedSourceHash,
+                                currentSourceHash: currentHash,
+                                rejectedCommandId: requestId,
+                                rejectedDraft: msg.payload,
+                            });
+                            reply({ success: false, conflict: true, rejectedDraft: msg.payload,
+                                sourceFile: precondition.sourceFile,
+                                expectedSourceHash: precondition.expectedSourceHash,
+                                currentSourceHash: currentHash,
+                                error: `${precondition.sourceFile} changed on disk; no write was made.`,
+                            });
+                            return;
+                        }
+                    }
+                    // One operation: write the source, then recompile through
+                    // the selected lowering provider so the identity the client
+                    // edits next is the one this write produced. The file
+                    // watcher still publishes the model.
+                    const result = await writeElement(await authoringContext(), msg.payload);
+                    let transactionId;
                     if (result.success) {
-                        // The file watcher will catch this change and broadcast to all clients
+                        transactionId = recordWriteTransaction(result.filePath, readFileSync(resolve(projectRoot, result.filePath), 'utf8'));
+                        if (result.revision)
+                            writeBackIndex = result.revision.index;
                         console.log(`[Persisted] ${msg.type} to ${result.filePath}`);
                     }
+                    if (result.stale) {
+                        // The file may be byte-identical and the edit still
+                        // wrong, so this is announced as its own kind of
+                        // conflict rather than as "the file changed".
+                        broadcastEditConflict({
+                            reason: 'stale-identity',
+                            detail: result.error,
+                            sourceFile: result.filePath,
+                            targetElementIds: [id],
+                            baseRevision: precondition.baseRevision,
+                            currentRevision: workspaceRevision,
+                            expectedSourceHash: precondition.expectedSourceHash,
+                            currentSourceHash: precondition.expectedSourceHash,
+                            rejectedCommandId: requestId,
+                            rejectedDraft: msg.payload,
+                        });
+                    }
+                    reply({
+                        success: result.success,
+                        sourceFile: result.filePath,
+                        transactionId,
+                        error: result.error,
+                        // A stale address is a conflict, not a malformed request:
+                        // the client's answer to both is to reload and retry.
+                        ...(result.stale ? { conflict: true, stale: true, rejectedDraft: msg.payload } : {}),
+                        ...(result.warnings ? { warnings: result.warnings } : {}),
+                        ...(result.success ? { irIdentity: irIndex().byMemoElement[id] } : {}),
+                    });
+                }
+                else if (msg.type === 'screen-capture:upload') {
+                    const { requestId, viewName, fileName, base64, mediaType } = msg.payload ?? {};
+                    const reply = (payload) => ws.send(JSON.stringify({
+                        type: 'screen-capture:upload:result',
+                        payload: { requestId, ...payload },
+                    }));
+                    try {
+                        if (!requestId || typeof base64 !== 'string')
+                            throw new Error('The image payload is missing.');
+                        const extensions = {
+                            'image/png': '.png',
+                            'image/jpeg': '.jpg',
+                            'image/webp': '.webp',
+                        };
+                        const extension = extensions[mediaType];
+                        if (!extension)
+                            throw new Error('Only PNG, JPEG, and WebP captures are supported.');
+                        const bytes = Buffer.from(base64, 'base64');
+                        if (!bytes.length)
+                            throw new Error('The selected image is empty.');
+                        if (bytes.length > 25 * 1024 * 1024)
+                            throw new Error('Screen captures must be 25 MB or smaller.');
+                        const safeView = String(viewName || 'ui-screen')
+                            .normalize('NFKD').replace(/[^a-zA-Z0-9_-]+/g, '-').replace(/^-+|-+$/g, '')
+                            || 'ui-screen';
+                        const rawStem = String(fileName || 'capture').replace(/\.[^.]+$/, '');
+                        const safeStem = rawStem
+                            .normalize('NFKD').replace(/[^a-zA-Z0-9_-]+/g, '-').replace(/^-+|-+$/g, '')
+                            || 'capture';
+                        const assetDir = resolve(options.projectRoot, 'model', 'assets', safeView);
+                        const assetPath = resolve(assetDir, `${safeStem}${extension}`);
+                        const modelRoot = resolve(options.projectRoot, 'model');
+                        if (relative(modelRoot, assetPath).startsWith('..'))
+                            throw new Error('Invalid capture path.');
+                        mkdirSync(assetDir, { recursive: true });
+                        writeFileSync(assetPath, bytes);
+                        const imageUri = relative(options.projectRoot, assetPath).replaceAll('\\', '/');
+                        reply({
+                            success: true,
+                            imageUri,
+                            imageHash: createHash('sha256').update(bytes).digest('hex'),
+                        });
+                        console.log(`[Screen Capture] Saved ${imageUri}`);
+                    }
+                    catch (e) {
+                        reply({ success: false, error: e?.message ?? String(e) });
+                    }
                 }
                 else if (msg.type === 'diagram:create') {
                     const { projectRoot } = options;
@@ -610,6 +1132,9 @@ export async function createDevServer(options) {
                 else if (msg.type === 'relationship:delete') {
                     ws.send(JSON.stringify(await handleRelationshipDelete(msg.payload)));
                 }
+                else if (msg.type === 'element:delete') {
+                    ws.send(JSON.stringify(await handleElementDelete(msg.payload)));
+                }
                 else if (msg.type === 'element:remap-kinds') {
                     // Remap orphaned kind references: for each element whose kind is in the
                     // mappings, persist the element with the new kind. The file watcher will
@@ -624,11 +1149,13 @@ export async function createDevServer(options) {
                         for (const element of Object.values(elements)) {
                             const newKind = mappings[element.kind];
                             if (newKind) {
-                                const result = saveElementToFile(projectRoot, { ...element, kind: newKind });
+                                const result = await saveElementToFile(projectRoot, { ...element, kind: newKind }, irIndex());
                                 if (result.success)
                                     remappedCount++;
                             }
                         }
+                        if (remappedCount > 0)
+                            await recompileAfterWrite();
                         console.log(`[Remap] Remapped ${remappedCount} elements across ${Object.keys(mappings).length} kind(s)`);
                         ws.send(JSON.stringify({ type: 'remap:result', payload: { success: true, count: remappedCount } }));
                     }
@@ -678,6 +1205,97 @@ export async function createDevServer(options) {
                         payload: { diagramId: msg.payload.diagramId, elementIds, errors: [] },
                     }));
                 }
+                else if (msg.type === 'methodology:source:request' || msg.type === 'methodology:source:save') {
+                    const { requestId, sourceFile } = msg.payload ?? {};
+                    const operation = msg.type === 'methodology:source:save' ? 'save' : 'load';
+                    const reply = (payload) => ws.send(JSON.stringify({
+                        type: 'methodology:source:result',
+                        payload: { requestId, sourceFile, operation, ...payload },
+                    }));
+                    try {
+                        const methodology = initialMessages.find(message => message.type === 'methodology:update');
+                        const allowed = new Set((methodology?.payload?.folders ?? []).flatMap((folder) => (folder.sourceFiles ?? []).map((file) => resolve(options.projectRoot, file))));
+                        const path = resolve(options.projectRoot, String(sourceFile ?? ''));
+                        if (!allowed.has(path) || !path.endsWith('.sysml')) {
+                            throw new Error('The requested file is not in the resolved methodology source set.');
+                        }
+                        const onDisk = readFileSync(path, 'utf8');
+                        const revision = fileRevision(onDisk);
+                        if (operation === 'load') {
+                            reply({ success: true, text: onDisk, revision });
+                            return;
+                        }
+                        const { text, baseRevision } = msg.payload;
+                        if (typeof text !== 'string' || typeof baseRevision !== 'string') {
+                            throw new Error('Text and source revision are required.');
+                        }
+                        if (baseRevision !== revision) {
+                            const lockout = {
+                                type: 'app:restart-required',
+                                reason: 'ontology-source-changed',
+                                changedFile: String(sourceFile),
+                                instruction: 'Reusable methodology source changed externally. Model mutations are locked; Relaunch Memo Architect.',
+                            };
+                            mutationLockout = lockout;
+                            for (const client of clients) {
+                                if (client.readyState === 1)
+                                    client.send(JSON.stringify(lockout));
+                            }
+                            reply({ success: false, conflict: true, text: onDisk, revision,
+                                error: `${sourceFile} changed on disk; no write was made.` });
+                            return;
+                        }
+                        writeFileSync(path, text, 'utf8');
+                        const transactionId = recordWriteTransaction(String(sourceFile), text);
+                        reply({ success: true, revision: fileRevision(text), transactionId });
+                    }
+                    catch (error) {
+                        reply({ success: false, error: error instanceof Error ? error.message : String(error) });
+                    }
+                }
+                else if (msg.type === 'rule:policy:write') {
+                    // Tailoring a rule from the browser goes through exactly
+                    // the path a hand edit does: the same allowed-source check,
+                    // the same base-revision precondition, the same transaction
+                    // ID. The editor supplies a decision; the SysML is rendered
+                    // here, so the browser never composes model source.
+                    const { requestId } = msg.payload ?? {};
+                    const reply = (payload) => ws.send(JSON.stringify({
+                        type: 'rule:policy:write:result', payload: { requestId, ...payload },
+                    }));
+                    try {
+                        const request = msg.payload;
+                        const methodology = initialMessages.find(message => message.type === 'methodology:update');
+                        const effectiveRules = initialMessages.find(message => message.type === 'rules:update')?.payload?.rules ?? [];
+                        const refusal = checkRulePolicy(request, effectiveRules);
+                        if (refusal) {
+                            reply({ success: false, code: refusal.code, error: refusal.message });
+                            return;
+                        }
+                        const allowed = new Set((methodology?.payload?.folders ?? []).flatMap((folder) => (folder.sourceFiles ?? []).map((file) => resolve(options.projectRoot, file))));
+                        const path = resolve(options.projectRoot, String(request.sourceFile ?? ''));
+                        if (!allowed.has(path) || !path.endsWith('.sysml')) {
+                            throw new Error('The target file is not in the resolved methodology source set.');
+                        }
+                        const onDisk = readFileSync(path, 'utf8');
+                        const revision = fileRevision(onDisk);
+                        if (request.baseRevision !== revision) {
+                            reply({ success: false, conflict: true, revision,
+                                error: `${request.sourceFile} changed on disk; no write was made.` });
+                            return;
+                        }
+                        const updated = insertRulePolicy(onDisk, renderRulePolicy(request));
+                        if (!updated) {
+                            throw new Error(`${request.sourceFile} declares no MethodologyDefinition to attach the policy to.`);
+                        }
+                        writeFileSync(path, updated, 'utf8');
+                        const transactionId = recordWriteTransaction(String(request.sourceFile), updated);
+                        reply({ success: true, revision: fileRevision(updated), transactionId });
+                    }
+                    catch (error) {
+                        reply({ success: false, error: error instanceof Error ? error.message : String(error) });
+                    }
+                }
                 else if (msg.type === 'diagram:source:request') {
                     const { requestId, diagramId } = msg.payload ?? {};
                     try {
@@ -703,15 +1321,27 @@ export async function createDevServer(options) {
                     try {
                         if (typeof text !== 'string')
                             throw new Error('SysML source text is required.');
+                        if (typeof baseRevision !== 'string')
+                            throw new Error('A source revision is required; reload the file before saving.');
                         const source = diagramSource(String(diagramId ?? ''));
                         // Refuse to overwrite work that arrived after this edit
                         // began. The client gets the current file back so it can
                         // show the conflict instead of losing one of the two.
                         const onDisk = readFileSync(source.path, 'utf8');
                         const currentRevision = fileRevision(onDisk);
-                        if (typeof baseRevision === 'string' && baseRevision !== currentRevision) {
+                        if (baseRevision !== currentRevision) {
                             console.warn(`[Diagram] Refused stale save of ${source.sourceFile} ` +
                                 `(based on ${baseRevision}, disk is ${currentRevision})`);
+                            broadcastEditConflict({
+                                sourceFile: source.sourceFile,
+                                targetElementIds: currentDiagrams().find(d => d.id === diagramId)?.elementIds ?? [],
+                                baseRevision,
+                                currentRevision,
+                                expectedSourceHash: baseRevision,
+                                currentSourceHash: currentRevision,
+                                rejectedCommandId: requestId,
+                                rejectedDraft: { diagramId, text },
+                            });
                             ws.send(JSON.stringify({
                                 type: 'diagram:source:result',
                                 payload: {
@@ -723,11 +1353,13 @@ export async function createDevServer(options) {
                             return;
                         }
                         writeFileSync(source.path, text, 'utf8');
+                        const transactionId = recordWriteTransaction(source.sourceFile, text);
                         ws.send(JSON.stringify({
                             type: 'diagram:source:result',
                             payload: {
                                 requestId, diagramId, operation: 'save', success: true,
                                 sourceFile: source.sourceFile, revision: fileRevision(text),
+                                transactionId,
                                 parseErrors: await sysmlParseErrors(text),
                             },
                         }));
@@ -881,17 +1513,9 @@ export async function createDevServer(options) {
                     const { projectRoot } = options;
                     const { elementsCsv, relationshipsCsv, packageName, targetFile } = msg.payload ?? {};
                     try {
-                        const { parseElementsCsv, parseRelationshipsCsv, generateFile, attachProvenance, findConfigFile, } = await import('@memoarchitect/tools');
-                        const { loadAndResolveConfig } = await import('./config-resolver.js');
-                        const configPath = findConfigFile(projectRoot);
-                        if (!configPath) {
-                            ws.send(JSON.stringify({
-                                type: 'import:result',
-                                payload: { success: false, elementsImported: 0, relationshipsImported: 0, errors: ['No memo config found'], warnings: [] },
-                            }));
-                            return;
-                        }
-                        const config = await loadAndResolveConfig(configPath);
+                        const { parseElementsCsv, parseRelationshipsCsv, generateFile, attachProvenance, loadProjectSettings, } = await import('@memoarchitect/tools');
+                        const config = loadProjectSettings(projectRoot);
+                        const { ontology } = await llmQueryContext();
                         const errors = [];
                         const warnings = [];
                         let elementsImported = 0;
@@ -899,7 +1523,7 @@ export async function createDevServer(options) {
                         let elements = [];
                         let relationships = [];
                         if (elementsCsv) {
-                            const result = parseElementsCsv(elementsCsv, config);
+                            const result = parseElementsCsv(elementsCsv, ontology);
                             errors.push(...result.errors);
                             warnings.push(...result.warnings);
                             // Attach provenance
@@ -915,7 +1539,7 @@ export async function createDevServer(options) {
                             const knownIds = elementsImported > 0
                                 ? new Set(elements.map((e) => e.id))
                                 : undefined;
-                            const result = parseRelationshipsCsv(relationshipsCsv, config, knownIds);
+                            const result = parseRelationshipsCsv(relationshipsCsv, ontology, knownIds);
                             errors.push(...result.errors);
                             warnings.push(...result.warnings);
                             relationships = result.items;
@@ -986,10 +1610,10 @@ export async function createDevServer(options) {
                             ws.send(JSON.stringify({ type: 'llm:chat:result', payload: { requestId, error: 'No LLM provider configured. Add an API key in Settings, set ANTHROPIC_API_KEY or OPENAI_API_KEY, or put one in a project .env file.' } }));
                         }
                         else {
-                            const { ctx, config } = await llmQueryContext();
+                            const { ctx, ontology } = await llmQueryContext();
                             const provider = createProvider(llmConfig);
                             const result = await runChatTurn({
-                                question, history, ctx, provider, config,
+                                question, history, ctx, provider, ontology,
                                 allowEdits: allowEdits === true,
                             });
                             ws.send(JSON.stringify({
@@ -1068,22 +1692,13 @@ export async function createDevServer(options) {
                     }
                 }
                 else if (msg.type === 'llm:generate') {
-                    // Generate SysML v2 from natural language (#54)
+                    // Argument marshalling only: memo-tools owns generation,
+                    // validation, repair, and normalized diagnostics.
                     const { requestId, description } = msg.payload ?? {};
                     try {
-                        const { resolveLLMConfig, createProvider, generateSysml, findConfigFile } = await import('@memoarchitect/tools');
-                        const { loadAndResolveConfig } = await import('./config-resolver.js');
-                        const llmConfig = resolveLLMConfig();
-                        if (!llmConfig) {
-                            ws.send(JSON.stringify({ type: 'llm:generate:result', payload: { requestId, error: 'No LLM provider configured.' } }));
-                        }
-                        else {
-                            const configPath = findConfigFile(options.projectRoot);
-                            const config = configPath ? await loadAndResolveConfig(configPath) : {};
-                            const provider = createProvider(llmConfig);
-                            const result = await generateSysml(description, config, provider);
-                            ws.send(JSON.stringify({ type: 'llm:generate:result', payload: { requestId, sysml: result.sysml, explanation: result.explanation, suggestedFile: result.suggestedFile } }));
-                        }
+                        const { generateValidatedSysml } = await import('../operations/ai-authoring.js');
+                        const result = await generateValidatedSysml({ projectRoot: options.projectRoot, description });
+                        ws.send(JSON.stringify({ type: 'llm:generate:result', payload: { requestId, ...result } }));
                     }
                     catch (e) {
                         console.error('[LLM] generate failed:', e);
@@ -1291,14 +1906,22 @@ Return ONLY a JSON array of strings. Each string is a concise, actionable sugges
     await new Promise((resolve) => {
         server.listen(port, host, () => resolve());
     });
+    const address = server.address();
     return {
-        broadcast(messages) {
+        port: typeof address === 'object' && address ? address.port : port,
+        broadcast(messages, changedSourceIds = []) {
             // Update initial messages for new connections
+            const baseRevision = workspaceRevision;
+            workspaceRevision++;
+            const publication = stampWorkspace(messages, baseRevision, false, changedSourceIds);
+            // A published model carries its own identities; the write-back's
+            // provisional index has been superseded.
+            writeBackIndex = undefined;
             initialMessages.length = 0;
-            initialMessages.push(...messages);
+            initialMessages.push(...publication);
             for (const client of clients) {
                 if (client.readyState === 1) { // WebSocket.OPEN
-                    for (const msg of messages) {
+                    for (const msg of publication) {
                         client.send(JSON.stringify(msg));
                     }
                 }
@@ -1312,6 +1935,51 @@ Return ONLY a JSON array of strings. Each string is a concise, actionable sugges
                 }
             }
         },
+        consumeWriteTransactions(files) {
+            const matched = {};
+            let escalationFile;
+            for (const file of files) {
+                const normalized = file.replaceAll('\\', '/');
+                const transaction = writeTransactions.get(normalized);
+                if (!transaction)
+                    continue;
+                const path = resolve(options.projectRoot, normalized);
+                const currentHash = existsSync(path) ? fileRevision(readFileSync(path, 'utf8')) : '';
+                if (currentHash === transaction.hash) {
+                    matched[normalized] = transaction.id;
+                    writeTransactions.delete(normalized);
+                    continue;
+                }
+                transaction.unmatchedWrites++;
+                if (Date.now() - transaction.createdAt > 5000) {
+                    writeTransactions.delete(normalized);
+                }
+                else if (transaction.unmatchedWrites >= 2) {
+                    escalationFile = normalized;
+                    writeTransactions.delete(normalized);
+                }
+            }
+            return { matched, escalationFile };
+        },
+        lockMutations(message) {
+            mutationLockout = message;
+            for (const client of clients) {
+                if (client.readyState === 1)
+                    client.send(JSON.stringify(message));
+            }
+        },
+        setSourceCoherence(payload) {
+            const message = { type: 'source:coherence', payload };
+            // Recovery is announced once, not on every clean rebuild after it —
+            // a coherent project is the ordinary case and says nothing.
+            if (payload.coherent && !sourceIncoherence)
+                return;
+            sourceIncoherence = payload.coherent ? undefined : message;
+            for (const client of clients) {
+                if (client.readyState === 1)
+                    client.send(JSON.stringify(message));
+            }
+        },
         close() {
             wss.close();
             viteServer?.close();