archgraph-argo 0.12.5 → 0.13.0

package/argo/scripts/ea-qea-sync-lib.js

@@ -113,6 +113,84 @@ function sha1(text) {
   return crypto.createHash('sha1').update(String(text)).digest('hex');
 }
 
+// ---------------------------------------------------------------------------
+// Element child mirror (attributes -> t_attribute, testcases -> t_objecttests)
+// Mirrors the legacy object-model import (import-from-kg.js applyElementAttributes /
+// applyTestcases) so canonical attributes and acceptance tests are visible in EA
+// under the element's Attributes / Testing tabs. Canonical-owned fields only:
+// run status/results on tests are left untouched on update (EA-side state).
+// ---------------------------------------------------------------------------
+const MAX_ATTRIBUTE_DEFAULT_LENGTH = 250;
+const TEST_CLASS_ACCEPTANCE = 4; // mirrors import-from-kg mapTestTypeToEaClass('Acceptance Test')
+
+function attrRowGuid(elementAlias, name, occurrence) {
+  return deterministicGuid('attr:' + elementAlias + ':' + name + '#' + occurrence);
+}
+function attributeDefaultValue(attr) {
+  const value = attr.value === undefined || attr.value === null ? '' : String(attr.value);
+  return value.length > MAX_ATTRIBUTE_DEFAULT_LENGTH ? '' : value;
+}
+function attributeNoteText(attr) {
+  const parts = [];
+  const value = attr.value === undefined || attr.value === null ? '' : String(attr.value);
+  if (value.length > MAX_ATTRIBUTE_DEFAULT_LENGTH) { parts.push(value); }
+  if (attr.description !== undefined && attr.description !== null && String(attr.description) !== '') { parts.push(String(attr.description)); }
+  if (attr.content !== undefined && attr.content !== null && String(attr.content) !== '') { parts.push(String(attr.content)); }
+  return parts.join('\r\n\r\n');
+}
+function isPersistedAttribute(attr) {
+  return !!(attr && typeof attr === 'object' && typeof attr.name === 'string' && attr.name.trim() !== '' && attr.op !== 'remove');
+}
+function mirrorElementChildren(db, objectId, element, stats) {
+  const alias = String(element.id);
+  const attrs = (Array.isArray(element.attributes) ? element.attributes : []).filter(isPersistedAttribute);
+  if (attrs.length > 0) {
+    const existing = db.prepare('SELECT ID, Name, "Default", Notes, ea_guid, Pos FROM t_attribute WHERE Object_ID=?').all(objectId);
+    const available = existing.map((r) => ({ ...r }));
+    let maxPos = 0;
+    for (const r of existing) { const p = Number(r.Pos); if (!Number.isNaN(p) && p > maxPos) { maxPos = p; } }
+    const occurrence = {};
+    for (const a of attrs) {
+      occurrence[a.name] = (occurrence[a.name] || 0) + 1;
+      const guid = attrRowGuid(alias, a.name, occurrence[a.name]);
+      const notes = attributeNoteText(a);
+      const def = attributeDefaultValue(a);
+      const idx = available.findIndex((r) => String(r.ea_guid || '') === guid);
+      if (idx >= 0) {
+        db.prepare('UPDATE t_attribute SET Name=?, Type=?, "Default"=?, Notes=? WHERE ID=?')
+          .run(a.name, 'String', def, notes, Number(available[idx].ID));
+        available.splice(idx, 1);
+        stats.attributesUpdated++;
+      } else {
+        maxPos += 16;
+        db.prepare('INSERT INTO t_attribute (Object_ID, Name, Scope, Type, "Default", Notes, Pos, ea_guid) VALUES (?,?,?,?,?,?,?,?)')
+          .run(objectId, a.name, 'Public', 'String', def, notes, maxPos, guid);
+        stats.attributesAdded++;
+      }
+    }
+  }
+  const tests = Array.isArray(element.testcases) ? element.testcases : [];
+  for (const tc of tests) {
+    if (!tc || typeof tc.name !== 'string' || tc.name.trim() === '') { continue; }
+    const name = tc.name.trim();
+    const type = (tc.type !== undefined && tc.type !== null && String(tc.type) !== '') ? String(tc.type) : 'Acceptance Test';
+    const notes = tc.description === undefined || tc.description === null ? '' : String(tc.description);
+    const input = tc.Input === undefined || tc.Input === null ? '' : String(tc.Input);
+    const criteria = tc.acceptanceCriteria === undefined || tc.acceptanceCriteria === null ? '' : String(tc.acceptanceCriteria);
+    const existing = db.prepare('SELECT Test FROM t_objecttests WHERE Object_ID=? AND Test=? AND TestClass=?')
+      .get(objectId, name, TEST_CLASS_ACCEPTANCE);
+    if (existing) {
+      db.prepare('UPDATE t_objecttests SET TestType=?, Notes=?, InputData=?, AcceptanceCriteria=? WHERE Object_ID=? AND Test=? AND TestClass=?')
+        .run(type, notes, input, criteria, objectId, name, TEST_CLASS_ACCEPTANCE);
+      stats.testsUpdated++;
+    } else {
+      db.prepare('INSERT INTO t_objecttests (Object_ID, Test, TestClass, TestType, Notes, InputData, AcceptanceCriteria, Status, Results) VALUES (?,?,?,?,?,?,?,?,?)')
+        .run(objectId, name, TEST_CLASS_ACCEPTANCE, type, notes, input, criteria, 'Proposed', '');
+      stats.testsAdded++;
+    }
+  }
+}
+
 // ---------------------------------------------------------------------------
 // sqlite helpers
 // ---------------------------------------------------------------------------
@@ -186,6 +264,17 @@ function parseStyleToken(styleEx, key) {
   const m = re.exec(text);
   return m ? m[2] : '';
 }
+function ensureStyleToken(styleEx, keyValue) {
+  // EA rewrites StyleEx with its own tokens and drops unknown ones (e.g. schema_view_id).
+  // Re-inject our anchor while preserving EA's formatting tokens so diagram identity
+  // stays discoverable on the next sync.
+  const text = String(styleEx === null || styleEx === undefined ? '' : styleEx);
+  const key = String(keyValue).split('=')[0];
+  const existing = parseStyleToken(text, key);
+  if (existing !== '') { return text; }
+  const token = String(keyValue).indexOf('=') >= 0 ? String(keyValue) + ';' : String(keyValue) + '=;';
+  return text ? token + text : token;
+}
 
 // ---------------------------------------------------------------------------
 // Core sync
@@ -335,6 +424,10 @@ function syncGraphToQea(graph, qeaPath, opts) {
         }
         tagStats.propsSkip = propsToWrite.length - newProps.length;
       }
+      // canonical attributes -> t_attribute, canonical testcases -> t_objecttests
+      for (const t of toTag) {
+        mirrorElementChildren(db, t.id, t.e, tagStats);
+      }
     }
     stages.elemTags = nowMs();
 
@@ -414,12 +507,20 @@ function syncGraphToQea(graph, qeaPath, opts) {
     stages.relTags = nowMs();
 
     // --- views/diagrams ----------------------------------------------------
+    // Diagram identity is matched by BOTH the schema_view_id StyleEx token AND the
+    // deterministic ea_guid. EA rewrites StyleEx (its own formatting tokens) whenever
+    // it touches an open project and DROPS unknown tokens like schema_view_id — if we
+    // only matched by the token we would re-INSERT the same deterministic ea_guid and
+    // crash on t_diagram's UNIQUE(ea_guid) (projection failure: Neo4j ok, EA stale).
     const existingDiags = db.prepare('SELECT Diagram_ID, Package_ID, Name, StyleEx, ea_guid FROM t_diagram WHERE Package_ID=?').all(syncId);
     const diagByView = new Map();
+    const diagByGuid = new Map();
     for (const d of existingDiags) {
+      if (d.ea_guid) { diagByGuid.set(String(d.ea_guid), d); }
       const v = parseStyleToken(d.StyleEx, 'schema_view_id');
       if (v) { diagByView.set(v, d); }
     }
+    const diagViewRows = new Map(); // view_id -> matched existing row (token OR guid)
     const newDiags = [];
     for (const view of graph.views || []) {
       if (!view || view.view_id === undefined || view.view_id === null) { continue; }
@@ -432,7 +533,7 @@ function syncGraphToQea(graph, qeaPath, opts) {
         }
         return 0;
       })();
-      const existing = diagByView.get(viewId);
+      const existing = diagByView.get(viewId) || diagByGuid.get(deterministicGuid('diag:' + viewId)) || null;
       const intended = {
         Name: safeName(view.view_name, viewId),
         Diagram_Type: DIAGRAM_TYPE,
@@ -442,10 +543,15 @@ function syncGraphToQea(graph, qeaPath, opts) {
         StyleEx: styleEx,
       };
       if (existing) {
-        const changed = intended.Name !== (existing.Name || '');
-        if (DEBUG && changed) { console.error('DEBUG diagram chg', viewId, JSON.stringify({n:[intended.Name,(existing.Name||'')], notes:[intended.Notes,(existing.Notes||'')]})); }
+        diagViewRows.set(viewId, existing);
+        // EA may have rewritten StyleEx and dropped the anchor — re-inject it while
+        // preserving EA's own formatting tokens so identity stays discoverable.
+        const anchoredStyleEx = ensureStyleToken(existing.StyleEx, 'schema_view_id=' + viewId);
+        const changed = intended.Name !== (existing.Name || '') || (existing.StyleEx || '') !== anchoredStyleEx;
+        if (DEBUG && changed) { console.error('DEBUG diagram chg', viewId, JSON.stringify({n:[intended.Name,(existing.Name||'')], style: !!parseStyleToken(existing.StyleEx,'schema_view_id')})); }
         if (changed && !o.dryRun) {
-          updateRow(db, 't_diagram', ['Name'], 'Diagram_ID', Number(existing.Diagram_ID), intended);
+          db.prepare('UPDATE t_diagram SET Name=?, StyleEx=? WHERE Diagram_ID=?')
+            .run(intended.Name, anchoredStyleEx, Number(existing.Diagram_ID));
         }
         stats[changed ? 'updated' : 'skipped'].diagrams++;
       } else {
@@ -470,6 +576,12 @@ function syncGraphToQea(graph, qeaPath, opts) {
     } else {
       for (const d of newDiags) { diagAliasToId.set(parseStyleToken(d.StyleEx, 'schema_view_id'), -1); }
     }
+    const diagIdForView = (viewId) => {
+      const row = diagViewRows.get(viewId) || diagByView.get(viewId);
+      if (row) { return Number(row.Diagram_ID !== undefined ? row.Diagram_ID : row); }
+      const planned = diagAliasToId.get(viewId);
+      return planned === undefined ? null : planned;
+    };
     // view meta
     if (!o.dryRun) {
       for (const view of graph.views || []) {
@@ -480,10 +592,8 @@ function syncGraphToQea(graph, qeaPath, opts) {
     for (const view of graph.views || []) {
       if (!view || view.view_id === undefined || view.view_id === null) { continue; }
       const viewId = String(view.view_id);
-      let dId = diagByView.get(viewId);
-      if (!dId) { dId = diagAliasToId.get(viewId); }
-      if (!dId) { continue; }
-      const diagramId = Number(dId.Diagram_ID !== undefined ? dId.Diagram_ID : dId);
+      const diagramId = diagIdForView(viewId);
+      if (diagramId === null) { continue; }
       const placedObjs = new Set();
       const objs = db.prepare('SELECT Object_ID FROM t_diagramobjects WHERE Diagram_ID=?').all(diagramId);
       for (const r of objs) { placedObjs.add(Number(r.Object_ID)); }
@@ -637,9 +747,46 @@ function fullProjection(graph, qeaPath, opts) {
 // ---------------------------------------------------------------------------
 // Export
 // ---------------------------------------------------------------------------
-// ---------------------------------------------------------------------------
-// Export
-// ---------------------------------------------------------------------------
+// Read the EA diagram GEOMETRY for one KG view from a .qea model (read-only).
+// The view maps to the diagram anchored by the deterministic ea_guid (diag:<viewId>)
+// or the schema_view_id StyleEx token written by the sync. Returns:
+//   - element boxes  = t_diagramobjects rects joined to t_object.Alias (schema id)
+//   - connector lines = t_diagramlinks rows joined to the connector's schema_id tag
+// Returns null when the view has no matching EA diagram. Never writes EA geometry.
+function readViewDiagramGeometry(qeaPath, viewId) {
+  const v = String(viewId === null || viewId === undefined ? '' : viewId).trim();
+  if (v === '') { return null; }
+  const db = openQea(qeaPath);
+  try {
+    ensureMetaTable(db);
+    const guid = deterministicGuid('diag:' + v);
+    const diag = db.prepare('SELECT Diagram_ID FROM t_diagram WHERE ea_guid = ? OR StyleEx LIKE ?')
+      .get(guid, '%schema_view_id=' + v + ';%');
+    if (!diag) { return null; }
+    const diagramId = Number(diag.Diagram_ID);
+    const elements = db.prepare(
+      'SELECT o.Alias AS id, d.RectLeft AS left, d.RectTop AS top, d.RectRight AS right, d.RectBottom AS bottom ' +
+      'FROM t_diagramobjects d JOIN t_object o ON o.Object_ID = d.Object_ID ' +
+      'WHERE d.Diagram_ID = ? AND o.Alias IS NOT NULL AND o.Alias <> ? ' +
+      'ORDER BY d.Sequence'
+    ).all(diagramId, '').map((r) => ({
+      id: String(r.id),
+      left: Number(r.left), top: Number(r.top), right: Number(r.right), bottom: Number(r.bottom),
+    }));
+    const relationships = db.prepare(
+      'SELECT t.VALUE AS id, dl.Geometry AS path ' +
+      'FROM t_diagramlinks dl JOIN t_connectortag t ON t.ElementID = dl.ConnectorID AND t.Property = ? ' +
+      'WHERE dl.DiagramID = ? ORDER BY dl.ConnectorID'
+    ).all('schema_id', diagramId).map((r) => ({
+      id: String(r.id),
+      path: String(r.path === null || r.path === undefined ? '' : r.path),
+    }));
+    return { diagramId, elements, relationships };
+  } finally {
+    try { db.close(); } catch { /* ignore */ }
+  }
+}
+
 function exportQeaToGraph(qeaPath) {
   const db = openQea(qeaPath);
   try {
@@ -679,6 +826,7 @@ module.exports = {
   canonicalArchimateType,
   syncGraphToQea,
   exportQeaToGraph,
+  readViewDiagramGeometry,
   snapshotQea,
   readMetaKind,
   fullProjection,

package/argo/scripts/systemarchitecture-mcp-server.js

@@ -219,7 +219,7 @@ const TOOLS = [
   },
   {
     name: 'getArchitectureViewContext',
-    description: 'read-only query that resolves one view by view_id into its complete membership: the view object, every member element (from included_elements), every member relationship (from included_relationships), the parent element, and optionally child sub-views declared by member elements. Resolves ids into full canonical objects instead of returning raw id lists.',
+    description: 'read-only query that resolves one view by view_id into its complete membership: the view object, every member element (from included_elements), every member relationship (from included_relationships), the parent element, and optionally child sub-views declared by member elements. Resolves ids into full canonical objects instead of returning raw id lists. Optional includeEaGeometry (default false) additionally returns the EA diagram geometry of the resolved view.',
     inputSchema: viewContextInputSchema(),
   },
   {
@@ -441,6 +441,7 @@ function viewContextInputSchema() {
       view_id: { type: 'string', description: 'The id of the view to resolve.' },
       includeParentElement: { type: 'boolean', description: 'Default: true. Resolve the parent element referenced by the view.' },
       includeChildViews: { type: 'boolean', description: 'Default: false. Include child views declared by member elements through subdiagram_views.' },
+      includeEaGeometry: { type: 'boolean', description: 'Default: false (opt-in). When true, additionally resolve the diagram GEOMETRY (element boxes + connector line paths) for this view from the workspace EA model (.qea) and return it under a `geometry` field aligned by schema id with the resolved members. By default the EA model is never touched and no `geometry` field is returned; a missing EA model/diagram yields geometry.present=false, never an error.' },
     },
     additionalProperties: false,
   };
@@ -678,6 +679,50 @@ function buildIntentElementContext(context, args = {}) {
   };
 }
 
+// ---------------------------------------------------------------------------
+// Optional EA diagram GEOMETRY (opt-in, default off)
+// ---------------------------------------------------------------------------
+// getArchitectureViewContext is a canonical-graph read; it never touches the EA
+// model unless the caller explicitly sets includeEaGeometry=true. The workspace's
+// EA model (.qea, the SQLite carrier this toolchain can read) may hold human-laid-out
+// diagram geometry for a view — element boxes (t_diagramobjects rects) and connector
+// line paths (t_diagramlinks). When present it is returned under `geometry`, aligned
+// by schema id with the resolved members, so an image-capable LLM can redraw the view
+// faithfully. Absent model/diagram → present:false (never an error).
+const EA_GEOMETRY_MODEL_EXTENSIONS = new Set(['.qea']);
+function findEaGeometryModelPath(workspaceRoot) {
+  try {
+    const entries = fs.readdirSync(workspaceRoot, { withFileTypes: true });
+    const names = entries
+      .filter((entry) => entry.isFile() && EA_GEOMETRY_MODEL_EXTENSIONS.has(path.extname(entry.name).toLowerCase()))
+      .map((entry) => entry.name)
+      .sort();
+    return names.length > 0 ? path.join(workspaceRoot, names[0]) : null;
+  } catch {
+    return null;
+  }
+}
+function readEaViewGeometry(workspaceRoot, viewId) {
+  // Lazily require the .qea projection lib: it depends on node:sqlite (Node >= 22),
+  // so it is only loaded when geometry is actually requested, never for other calls.
+  let modelRel = null;
+  try {
+    const modelPath = findEaGeometryModelPath(workspaceRoot);
+    if (!modelPath) {
+      return { source: null, present: false, elements: [], relationships: [] };
+    }
+    modelRel = normalizeRelativePath(path.relative(workspaceRoot, modelPath)) || null;
+    const eaQeaLib = require('./ea-qea-sync-lib.js');
+    const geo = eaQeaLib.readViewDiagramGeometry(modelPath, viewId);
+    if (!geo) {
+      return { source: modelRel, present: false, elements: [], relationships: [] };
+    }
+    return { source: modelRel, present: true, elements: geo.elements, relationships: geo.relationships };
+  } catch {
+    return { source: modelRel, present: false, elements: [], relationships: [] };
+  }
+}
+
 function buildViewContext(context, args = {}) {
   const viewId = typeof args.view_id === 'string' ? args.view_id.trim() : '';
   if (!viewId) {
@@ -746,7 +791,7 @@ function buildViewContext(context, args = {}) {
     }
   }
 
-  return {
+  const result = {
     status: 'passed',
     graphPath: context.graphPath.relativePath,
     view: clone(view),
@@ -757,6 +802,10 @@ function buildViewContext(context, args = {}) {
     parentElement,
     childViews,
   };
+  if (args.includeEaGeometry === true) {
+    result.geometry = readEaViewGeometry(context.workspaceRoot, viewId);
+  }
+  return result;
 }
 
 function resolveFocusElement(document, args) {
@@ -1616,9 +1665,12 @@ async function buildMutationResult(context, mutations, write) {
   writeGraph(context.graphPath.absolutePath, mutationResult.document);
   result.written = true;
 
-  // WP2791: .qea projection parallel to the Neo4j trigger — non-fatal, best-effort.
+  // WP2791: .qea projection parallel to the Neo4j trigger — non-fatal, best-effort,
+  // but ALWAYS reported on the result (passed / failed / noop+reason) so a missing EA
+  // update is never silent.
   {
-    const qeaTarget = resolveQeaProjectionTarget(context);
+    const resolved = resolveQeaProjectionTarget(context);
+    const qeaTarget = resolved && resolved.target;
     if (qeaTarget) {
       try {
         const projection = await runQeaProjection(qeaTarget);
@@ -1632,6 +1684,15 @@ async function buildMutationResult(context, mutations, write) {
         result.qeaProjection = { status: 'failed', error: String(error && error.message ? error.message : error) };
         result.warnings = addUnique(result.warnings || [], ['ea-qea projection error (non-fatal): ' + String(error && error.message ? error.message : error)]);
       }
+    } else {
+      result.qeaProjection = {
+        status: 'noop',
+        reason: (resolved && resolved.reason) || 'no .qea target',
+        workspaceRoot: context.workspaceRoot,
+      };
+      if (resolved && resolved.hasEaSignals) {
+        result.warnings = addUnique(result.warnings || [], ['ea-qea projection not run: ' + ((resolved && resolved.reason) || 'no .qea target')]);
+      }
     }
   }
 
@@ -1832,59 +1893,79 @@ function summarizeDocument(document) {
   };
 }
 
-// --- WP2791: post-canonical-write .qea projection (parallel to Neo4j sync, non-fatal) ---
-// Target resolution (decision qea-full-wholefile-argo-scripts-no-config): env ARGO_EA_QEA >
-// the single *.qea at the workspace root (0/many -> no-op with an explicit log). NO config file.
-// Projection script runs from argo/scripts (same package as the MCP runtime), so a workspace
-// does not need to ship its own projection script (bundled argo/scripts module).
-function resolveQeaProjectionTarget(context) {
-  try {
-    const workspaceRoot = String(context && context.workspaceRoot ? context.workspaceRoot : '');
-    if (!workspaceRoot || !fs.existsSync(workspaceRoot)) { return null; }
-    const graphAbsolute = context.graphPath && context.graphPath.absolutePath ? context.graphPath.absolutePath : null;
-    if (!graphAbsolute || !fs.existsSync(graphAbsolute)) { return null; }
-    const pick = (p) => (p && fs.existsSync(p) ? path.resolve(p) : null);
-    let qeaPath = pick(process.env.ARGO_EA_QEA);
-    if (qeaPath) { return { qeaPath, graphPath: graphAbsolute, workspaceRoot }; }
-    let qeas = [];
-    try { qeas = fs.readdirSync(workspaceRoot).filter((n) => n.toLowerCase().endsWith('.qea')); } catch { /* ignore */ }
-    if (qeas.length === 1) {
-      return { qeaPath: path.resolve(workspaceRoot, qeas[0]), graphPath: graphAbsolute, workspaceRoot };
-    }
-    console.log('[ea-qea] projection target: none' + (qeas.length > 1 ? ' (' + qeas.length + ' *.qea found; expected exactly one or ARGO_EA_QEA)' : '') + ' in ' + workspaceRoot);
-    return null;
-  } catch (error) {
-    console.log('[ea-qea] projection target resolution failed: ' + String(error && error.message ? error.message : error));
-    return null;
-  }
-}
-
-function runQeaProjection(target) {
-  return new Promise((resolve) => {
-    const script = path.join(__dirname, 'ea-qea-sync.js');
-    if (!fs.existsSync(script)) {
-      resolve({ ok: false, error: 'argo/scripts/ea-qea-sync.js missing', ms: 0 });
-      return;
-    }
-    const snapshotDir = path.join(target.workspaceRoot, '.argo', 'temp', 'qea-backups');
-    const args = [script, '--mode', 'sync', '--graph', target.graphPath, '--qea', target.qeaPath, '--snapshot-dir', snapshotDir];
-    const started = Date.now();
-    let stderr = '';
-    let child;
-    try {
-      child = spawn(process.execPath, args, { cwd: target.workspaceRoot, windowsHide: true });
-    } catch (error) {
-      resolve({ ok: false, error: String(error && error.message ? error.message : error), ms: Date.now() - started });
-      return;
-    }
-    child.stderr.on('data', (d) => { stderr += String(d); });
-    child.on('error', (err) => resolve({ ok: false, error: String(err && err.message ? err.message : err), ms: Date.now() - started, stderr: stderr.slice(0, 600) }));
-    child.on('close', (code) => {
-      resolve({ ok: code === 0, code, ms: Date.now() - started, stderr: stderr.slice(0, 600) });
-    });
-  });
-}
-
+// --- WP2791: post-canonical-write .qea projection (parallel to Neo4j sync, non-fatal) ---
+// Target resolution (decision qea-full-wholefile-argo-scripts-no-config): env ARGO_EA_QEA >
+// the single *.qea at the workspace root (0/many -> no-op with an explicit log). NO config file.
+// Projection script runs from argo/scripts (same package as the MCP runtime), so a workspace
+// does not need to ship its own projection script (bundled argo/scripts module).
+function resolveQeaProjectionTarget(context) {
+  const none = (reason, hasEaSignals) => ({ target: null, reason, hasEaSignals: !!hasEaSignals });
+  try {
+    const workspaceRoot = String(context && context.workspaceRoot ? context.workspaceRoot : '');
+    if (!workspaceRoot || !fs.existsSync(workspaceRoot)) { return none('workspace root unavailable: ' + workspaceRoot, true); }
+    const graphAbsolute = context.graphPath && context.graphPath.absolutePath ? context.graphPath.absolutePath : null;
+    if (!graphAbsolute || !fs.existsSync(graphAbsolute)) { return none('canonical graph not found under ' + workspaceRoot, false); }
+    const pick = (p) => (p && fs.existsSync(p) ? path.resolve(p) : null);
+    const envTarget = process.env.ARGO_EA_QEA;
+    let qeaPath = pick(envTarget);
+    if (qeaPath) { return { target: { qeaPath, graphPath: graphAbsolute, workspaceRoot } }; }
+    let qeas = [];
+    try { qeas = fs.readdirSync(workspaceRoot).filter((n) => n.toLowerCase().endsWith('.qea')).sort(); } catch { /* ignore */ }
+    if (qeas.length === 1) {
+      return { target: { qeaPath: path.resolve(workspaceRoot, qeas[0]), graphPath: graphAbsolute, workspaceRoot } };
+    }
+    let eaFiles = [];
+    try { eaFiles = fs.readdirSync(workspaceRoot).filter((n) => /\.(qea|feap|eap)$/i.test(n)).sort(); } catch { /* ignore */ }
+    if (qeas.length > 1) {
+      const reason = `${qeas.length} *.qea files found at the workspace root (${qeas.join(', ')}); expected exactly one or set ARGO_EA_QEA`;
+      console.log('[ea-qea] projection target: none (' + reason + ') in ' + workspaceRoot);
+      return none(reason, true);
+    }
+    const legacy = eaFiles.filter((n) => /\.(feap|eap)$/i.test(n));
+    if (legacy.length > 0) {
+      const reason = `EA model is a legacy ${legacy.join(', ')} (Firebird/Jet); the direct .qea projection cannot write it — convert to .qea (EA 17.2+) or set ARGO_EA_QEA to a .qea target`;
+      console.log('[ea-qea] projection target: none (' + reason + ') in ' + workspaceRoot);
+      return none(reason, true);
+    }
+    if (envTarget) {
+      const reason = 'ARGO_EA_QEA points to a missing .qea file: ' + envTarget;
+      console.log('[ea-qea] projection target: none (' + reason + ')');
+      return none(reason, true);
+    }
+    console.log('[ea-qea] projection target: none in ' + workspaceRoot);
+    return none('no .qea target found (set ARGO_EA_QEA or place exactly one *.qea at the workspace root)', false);
+  } catch (error) {
+    console.log('[ea-qea] projection target resolution failed: ' + String(error && error.message ? error.message : error));
+    return none('EA .qea target resolution failed: ' + String(error && error.message ? error.message : error), true);
+  }
+}
+
+function runQeaProjection(target) {
+  return new Promise((resolve) => {
+    const script = path.join(__dirname, 'ea-qea-sync.js');
+    if (!fs.existsSync(script)) {
+      resolve({ ok: false, error: 'argo/scripts/ea-qea-sync.js missing', ms: 0 });
+      return;
+    }
+    const snapshotDir = path.join(target.workspaceRoot, '.argo', 'temp', 'qea-backups');
+    const args = [script, '--mode', 'sync', '--graph', target.graphPath, '--qea', target.qeaPath, '--snapshot-dir', snapshotDir];
+    const started = Date.now();
+    let stderr = '';
+    let child;
+    try {
+      child = spawn(process.execPath, args, { cwd: target.workspaceRoot, windowsHide: true });
+    } catch (error) {
+      resolve({ ok: false, error: String(error && error.message ? error.message : error), ms: Date.now() - started });
+      return;
+    }
+    child.stderr.on('data', (d) => { stderr += String(d); });
+    child.on('error', (err) => resolve({ ok: false, error: String(err && err.message ? err.message : err), ms: Date.now() - started, stderr: stderr.slice(0, 600) }));
+    child.on('close', (code) => {
+      resolve({ ok: code === 0, code, ms: Date.now() - started, stderr: stderr.slice(0, 600) });
+    });
+  });
+}
+
 function writeGraph(graphPath, document) {
   const tempPath = `${graphPath}.${process.pid}.${Date.now()}.tmp`;
   fs.writeFileSync(tempPath, `${JSON.stringify(document, null, 2)}\n`, 'utf8');
@@ -2167,6 +2248,26 @@ function compactMutationResponse(payload) {
   if (payload && payload.embeddingLifecycle && payload.embeddingLifecycle.state) {
     compact.embeddingLifecycle = { state: payload.embeddingLifecycle.state };
   }
+  // Successful writes stay compact but downstream projection side effects (EA .qea,
+  // Neo4j) and non-fatal warnings must stay observable — a caller deciding whether
+  // "the EA file reflects this write" relies on qeaProjection.status (passed /
+  // failed / noop + reason), never on silence.
+  if (payload && payload.qeaProjection) {
+    const q = payload.qeaProjection;
+    if (q.status === 'passed') {
+      compact.qeaProjection = { status: 'passed', ms: q.ms };
+    } else if (q.status === 'noop') {
+      compact.qeaProjection = { status: 'noop', reason: q.reason };
+    } else {
+      compact.qeaProjection = { status: q.status, error: q.error || q.reason };
+    }
+  }
+  if (payload && payload.neo4jSync) {
+    compact.neo4jSync = { status: payload.neo4jSync.status };
+  }
+  if (Array.isArray(payload && payload.warnings) && payload.warnings.length > 0) {
+    compact.warnings = payload.warnings;
+  }
   // Failed actual writes must retain business diagnostics (e.g. View15 maximum/observed)
   // so callers can distinguish reject reasons; successful writes stay compact.
   if (payload && payload.status === 'failed') {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "archgraph-argo",
-  "version": "0.12.5",
+  "version": "0.13.0",
   "description": "Deploy the ArchGraph ARGO toolchain, skills, and rules (schema, scripts, argo-init skill, global rule) with one command.",
   "license": "MIT",
   "bin": {