qgraphflow 0.0.6

package/skills/q-flow/scripts/compile-sequence.mjs

@@ -0,0 +1,112 @@
+import { minimumNodeSize } from '../assets/viewer/src/layout-measure.js';
+import { sequenceHeaderHeight } from '../assets/viewer/src/diagrams/sequence.js';
+import { operandId, operandEdges, fragmentDepth, fragmentHeadingLayout } from '../assets/viewer/src/sequence-fragments.js';
+import { createEdgeRoutes } from '../assets/viewer/src/edge-routing.js';
+import { sequenceMessageLabel, sequenceExecutions } from '../assets/viewer/src/sequence-executions.js';
+import { edgeLabelLayout, layoutText } from '../assets/viewer/src/text-layout.js';
+import { LAYOUT_LIMITS, LAYOUT_TARGETS } from '../assets/viewer/src/layout-spacing.js';
+
+export function compileSequence(input, candidate) {
+  const graph = structuredClone(input), groups = graph.groups ?? [], edges = new Map(graph.edges.map(edge => [edge.id, edge]));
+  // Without declared order, participants stand in the order the messages first reach them, initiator leftmost.
+  const firstSeen = new Map();
+  for (const edge of [...graph.edges].sort((a, b) => a.order - b.order)) for (const id of [edge.source, edge.target]) if (!firstSeen.has(id)) firstSeen.set(id, firstSeen.size);
+  const ordered = graph.layout?.participantOrder ?? [...graph.nodes].sort((a, b) => (a.layout?.order ?? 0) - (b.layout?.order ?? 0) || (firstSeen.get(a.id) ?? Infinity) - (firstSeen.get(b.id) ?? Infinity) || (a.id < b.id ? -1 : 1)).map(node => node.id);
+  const nodes = ordered.map(id => graph.nodes.find(node => node.id === id));
+  const spacing = LAYOUT_TARGETS.nodeGap + candidate * 8, gap = LAYOUT_LIMITS.labelGap + candidate * 4;
+  const guardText = (group, operand) => group.kind === 'par' ? operand.label : `${group.kind === 'loop' ? `${group.loop.min}..${group.loop.max} ` : ''}[${operand.guard}]`;
+  const guardLayout = (group, operand) => layoutText(guardText(group, operand), LAYOUT_TARGETS.labelWidth, 14, 20);
+  const bodyLayout = operand => layoutText(operand.body, LAYOUT_TARGETS.labelWidth, 16, 24);
+  let x = 32;
+  for (const node of nodes) {
+    node.size = minimumNodeSize(node, 'sequence', graph.meta.locale); node.position = { x, y: 48 };
+    x += node.size.width + spacing;
+  }
+  // Difference constraints on the message's actual span; moving the suffix keeps
+  // unrelated neighboring gaps unchanged. Longer spans reuse existing space.
+  const constraints = [...graph.edges].sort((a, b) => Math.abs(ordered.indexOf(a.source) - ordered.indexOf(a.target)) - Math.abs(ordered.indexOf(b.source) - ordered.indexOf(b.target)) || a.order - b.order);
+  const selfCounts = new Map();
+  for (const edge of constraints) {
+    const left = Math.min(ordered.indexOf(edge.source), ordered.indexOf(edge.target));
+    let right = Math.max(ordered.indexOf(edge.source), ordered.indexOf(edge.target));
+    const label = edgeLabelLayout(sequenceMessageLabel(graph, edge));
+    let required = label.width + 64;
+    if (left === right) {
+      const ordinal = selfCounts.get(edge.source) ?? 0; selfCounts.set(edge.source, ordinal + 1);
+      right++; required += 48 + ordinal * 24;
+      if (right === nodes.length) continue;
+    }
+    const center = node => node.position.x + node.size.width / 2;
+    const extra = Math.max(0, required - (center(nodes[right]) - center(nodes[left])));
+    for (let i = right; i < nodes.length; i++) nodes[i].position.x += extra;
+  }
+  // Provisional order-preserving times let the shared router measure actual
+  // prefixes, activation offsets, wrapped labels and self calls.
+  for (const edge of graph.edges) edge.route = { messageY: 200 + edge.order * 100 };
+  const routes = createEdgeRoutes(graph), executions = sequenceExecutions(graph);
+  const owned = new Set(groups.flatMap(group => (group.operands ?? []).flatMap(operand => operand.edgeIds)));
+  const range = group => (group.operands ?? []).flatMap((operand, i) => operandEdges(group, operand, i, groups)).map(id => edges.get(id).order);
+  const eventOrder = event => event.edge ? event.edge.order : Math.min(Infinity, ...range(event.group));
+  const sorted = events => events.sort((a, b) => eventOrder(a) - eventOrder(b) || ((a.edge ?? a.group).id < (b.edge ?? b.group).id ? -1 : 1));
+  // Fragments enclose only their messages and children. A bounded local gutter
+  // lets active lifelines continue beside complete, wrapped conditions.
+  const spanPoints = group => (group.operands ?? []).flatMap((operand, i) => operandEdges(group, operand, i, groups)).map(id => routes.get(id)).flatMap(route => [...route.points, { x: route.labelBox.x }, { x: route.labelBox.x + route.labelBox.width }]);
+  // A fragment without messages of its own stays under the span it comments on: the
+  // nearest ancestor's messages, or the whole conversation at top level.
+  const anchorPoints = group => {
+    const seen = new Set();
+    for (let item = group; item && !seen.has(item.id); item = groups.find(other => other.id === item.parentId)) {
+      seen.add(item.id);
+      const points = spanPoints(item);
+      if (points.length) return points;
+    }
+    return [...routes.values()].flatMap(route => route.points);
+  };
+  const tagRoom = 56; // kind tag plus its inset, kept clear of activation bars
+  for (const group of [...groups].sort((a, b) => fragmentDepth(b, groups) - fragmentDepth(a, groups) || a.id.localeCompare(b.id))) {
+    if (!group.operands) throw new Error(`Sequence group ${group.id} needs explicit operands before automatic layout`);
+    const points = anchorPoints(group);
+    const children = groups.filter(child => child.parentId === group.id);
+    const textWidth = Math.max(fragmentHeadingLayout({ ...group, size: undefined }).width + 16, ...group.operands.flatMap(operand => [guardLayout(group, operand).width, bodyLayout(operand).width]));
+    const ys = group.operands.flatMap((operand, i) => operandEdges(group, operand, i, groups)).map(id => edges.get(id).route.messageY);
+    const top = Math.min(...ys), bottom = Math.max(...ys);
+    const bars = executions.filter(bar => !ys.length || (bar.y <= bottom && bar.y + bar.height >= top)).sort((a, b) => a.x - b.x);
+    // Messages leave an activation at its edge; the gutter starts at the bar itself.
+    const anchorLeft = points.length ? Math.min(...points.map(point => point.x)) : nodes[0].position.x;
+    const localLeft = Math.min(anchorLeft, ...bars.filter(bar => bar.x < anchorLeft && bar.x + bar.width >= anchorLeft - 8).map(bar => bar.x)) - textWidth - 40;
+    const frameLeft = Math.min(localLeft, ...children.map(child => child.position.x - 32));
+    let right = Math.max(frameLeft + textWidth + 120, ...points.map(point => point.x + 32), ...children.map(child => child.position.x + child.size.width + 32));
+    for (const bar of bars) if (bar.x < right + 8 && bar.x + bar.width > right - tagRoom - 16) right = Math.max(right, bar.x + bar.width + tagRoom);
+    group.position = { x: frameLeft, y: 0 }; group.size = { width: Math.ceil(right - frameLeft), height: 0 };
+  }
+  function message(edge, cursor) {
+    const label = routes.get(edge.id).labelBox, self = edge.source === edge.target;
+    const y = Math.ceil(cursor + (self ? Math.max(16, label.height / 2 - 15) : label.height + 6));
+    edge.route = { messageY: y };
+    return y + (self ? Math.max(36, 15 + label.height / 2) : 6) + gap;
+  }
+  function eventsAt(events, cursor) {
+    for (const event of sorted(events)) cursor = event.edge ? message(event.edge, cursor) : fragment(event.group, cursor);
+    return cursor;
+  }
+  function fragment(group, top) {
+    group.position.y = top;
+    let cursor = top + Math.max(36, fragmentHeadingLayout(group).height + 20) + gap;
+    for (const [i, operand] of group.operands.entries()) {
+      cursor += guardLayout(group, operand).height + 16;
+      if (operand.body) cursor += bodyLayout(operand).height + 16;
+      const children = groups.filter(child => child.parentId === group.id && child.parentOperandId === operandId(operand, i));
+      cursor = eventsAt([...operand.edgeIds.map(id => ({ edge: edges.get(id) })), ...children.map(group => ({ group }))], cursor);
+      cursor += gap;
+    }
+    group.size.height = cursor - top + 16;
+    return top + group.size.height + gap;
+  }
+  const bottom = eventsAt([...graph.edges.filter(edge => !owned.has(edge.id)).map(edge => ({ edge })), ...groups.filter(group => !group.parentId).map(group => ({ group }))], 48 + Math.max(...nodes.map(sequenceHeaderHeight)) + LAYOUT_LIMITS.labelGap);
+  const messages = [...graph.edges].sort((a, b) => a.order - b.order);
+  for (let i = 1; i < messages.length; i++) if (messages[i].route.messageY <= messages[i - 1].route.messageY) throw new Error(`Sequence fragment ranges interleave at ${messages[i].id}; retain message order and correct operand ownership`);
+  const shift = Math.max(0, 32 - Math.min(...groups.map(group => group.position.x), ...nodes.map(node => node.position.x)));
+  for (const item of [...nodes, ...groups]) item.position.x += shift;
+  for (const node of graph.nodes) node.size.height = bottom + 32 - node.position.y;
+  return graph;
+}

package/skills/q-flow/scripts/generate-viewer.mjs

@@ -0,0 +1,126 @@
+#!/usr/bin/env node
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parseArgs } from 'node:util';
+import { diagramTypeOf, graphsOf, printCompositionReview, readAndValidateGraph, verifySourceEvidence, layoutComposition } from './validate-graph.mjs';
+import { compileGraphLayout } from './compile-layout.mjs';
+import { requireDiagramQuality } from '../assets/viewer/src/layout-quality.js';
+import { pageWithGraph } from '../assets/viewer/src/session-graph.js';
+import { SVG_FILE, diagramSvgFiles } from '../assets/viewer/src/export-svg.js';
+
+const scriptDir = path.dirname(fileURLToPath(import.meta.url));
+const shellPath = path.resolve(scriptDir, '../assets/viewer-dist/index.html');
+const PAGE_OUTPUTS = ['index.html', 'graph.json'];
+
+// Every output is staged first; the old ones and the stale ones (removed by this run) move into the staging backup,
+// and any failure puts all of them back.
+export function writeOutputs(outputDir, contents, stale = []) {
+  const names = Object.keys(contents);
+  fs.mkdirSync(outputDir, { recursive: true });
+  const staging = fs.mkdtempSync(path.join(outputDir, '.qgraphflow-')), backedUp = [], installed = [];
+  let keepBackup = false;
+  try {
+    for (const name of names) fs.writeFileSync(path.join(staging, name), contents[name]);
+    for (const name of [...names, ...stale]) if (fs.existsSync(path.join(outputDir, name))) {
+      fs.renameSync(path.join(outputDir, name), path.join(staging, `${name}.backup`)); backedUp.push(name);
+    }
+    for (const name of names) { fs.renameSync(path.join(staging, name), path.join(outputDir, name)); installed.push(name); }
+  } catch (error) {
+    const rollbackErrors = [];
+    for (const name of installed) try { fs.unlinkSync(path.join(outputDir, name)); } catch (failure) { rollbackErrors.push(failure); }
+    for (const name of backedUp) try { fs.renameSync(path.join(staging, `${name}.backup`), path.join(outputDir, name)); } catch (failure) { rollbackErrors.push(failure); }
+    if (rollbackErrors.length) { keepBackup = true; throw new AggregateError([error, ...rollbackErrors], `Output rollback failed; original backups retained in ${staging}`); }
+    throw error;
+  } finally { if (!keepBackup) fs.rmSync(staging, { recursive: true, force: true }); }
+}
+
+// Every view is compiled before anything is judged, so one run names every failing view instead of the first one only.
+// A single failure is rethrown untouched; several are combined, their diagnostics concatenated and candidates keyed by type.
+export async function compileViews(graphs, compile) {
+  const compiled = [], failures = [];
+  for (const graph of graphs) {
+    try { compiled.push(await compile(graph)); } catch (error) { failures.push({ graph, error }); }
+  }
+  if (failures.length === 1) throw failures[0].error;
+  if (failures.length) {
+    const phase = failures.some(({ error }) => error.phases?.semantic?.status === 'failed') ? 'semantic' : 'geometry';
+    throw Object.assign(new Error(failures.map(({ error }) => error.message).join('\n\n')), {
+      phases: { semantic: { status: phase === 'semantic' ? 'failed' : 'passed' }, geometry: { status: phase === 'semantic' ? 'not-checked' : 'failed' }, rendering: { status: 'not-checked' } },
+      diagnostics: failures.flatMap(({ error }) => error.diagnostics ?? []),
+      candidates: Object.fromEntries(failures.filter(({ error }) => error.candidates).map(({ graph, error }) => [diagramTypeOf(graph), error.candidates])),
+      failedViews: failures.map(({ graph }) => diagramTypeOf(graph))
+    });
+  }
+  return compiled;
+}
+
+const USAGE = `Usage: node generate-viewer.mjs <graph.json> <output-directory> [options]
+  --repo-root <dir>     verify every node source (file, line range, symbol) against this working tree
+  --layout auto|preserve  auto (default) computes positions; preserve keeps authored geometry under the same gate
+  --force               replace existing index.html / graph.json / diagram*.svg in the output directory (needs approval)
+  --verbose             print the full receipt (layout candidates, folds, diagnostics) instead of one summary line
+  -h, --help            this text
+Writes index.html, graph.json and one SVG per view (diagram.svg, or diagram-<n>-<type>.svg for a collection).
+Success prints one JSON line; failure prints the failing elements with rule, measurement and remediation.`;
+
+async function main() {
+  const { positionals: positional, values } = parseArgs({ allowPositionals: true, options: { force: { type: 'boolean' }, 'repo-root': { type: 'string' }, layout: { type: 'string', default: 'auto' }, verbose: { type: 'boolean', default: false }, help: { type: 'boolean', short: 'h', default: false } } });
+  const force = values.force;
+  if (values.help) { console.log(USAGE); process.exit(0); }
+  if (positional.length !== 2) {
+    console.error(USAGE);
+    process.exit(2);
+  }
+
+  const [inputPath, outputArg] = positional;
+  const outputDir = path.resolve(outputArg);
+  if (outputDir === path.parse(outputDir).root || outputDir === os.homedir()) throw new Error('Refusing broad output directory');
+  const input = readAndValidateGraph(inputPath, { inputOnly: true });
+  const sourceEvidence = verifySourceEvidence(input, values['repo-root']);
+  const warnings = printCompositionReview(input, { print: false }); // already printed by the input validation step
+  if (!fs.existsSync(shellPath)) throw new Error(`Viewer shell missing: ${shellPath}`);
+
+  const inputAbsolute = path.resolve(inputPath);
+  // Every SVG named by this tool is either rewritten or, when this run no longer produces it, removed: both need --force.
+  const svgs = fs.existsSync(outputDir) ? fs.readdirSync(outputDir).filter(name => SVG_FILE.test(name)).sort() : [];
+  const existing = [...PAGE_OUTPUTS.filter(name => {
+    const outputPath = path.join(outputDir, name);
+    return fs.existsSync(outputPath) && path.resolve(outputPath) !== inputAbsolute;
+  }), ...svgs];
+  if (existing.length && !force) throw new Error(`Refusing to overwrite: ${existing.join(', ')}; rerun with --force after approval`);
+  const shell = fs.readFileSync(shellPath, 'utf8');
+  if (!shell.includes('__CODEGRAPH_FLOW_DATA__')) throw new Error('Viewer shell data marker is missing');
+  const compiled = await compileViews(graphsOf(input), item => compileGraphLayout(item, { layout: values.layout }));
+  const quality = compiled.map(item => requireDiagramQuality(item.graph));
+  const graph = Array.isArray(input.diagrams) ? { ...input, diagrams: compiled.map(item => item.graph) } : compiled[0].graph;
+  const contents = { 'index.html': pageWithGraph(shell, graph), 'graph.json': `${JSON.stringify(graph, null, 2)}\n` };
+  for (const { name, svg } of diagramSvgFiles(graph)) contents[name] = svg;
+  writeOutputs(outputDir, contents, svgs.filter(name => !Object.hasOwn(contents, name)));
+  const files = Object.keys(contents);
+  const graphs = graphsOf(graph);
+  // One line on success: what was made and whether each gate passed. Candidates, folds and diagnostics stay out of the
+  // model's context unless asked for with --verbose; failures still print their diagnostics through the catch below.
+  const status = key => quality.every(item => item[key]?.status === 'passed') ? 'passed' : quality.some(item => item[key]?.status === 'failed') ? 'failed' : quality[0]?.[key]?.status ?? 'not-checked';
+  const summary = {
+    nodes: graphs.reduce((sum, item) => sum + item.nodes.length, 0),
+    edges: graphs.reduce((sum, item) => sum + item.edges.length, 0),
+    groups: graphs.reduce((sum, item) => sum + (item.groups?.length ?? 0), 0),
+    semantic: { status: status('semantic') }, geometry: { status: status('geometry') }, rendering: { status: status('rendering') },
+    ...(warnings.length ? { warnings: warnings.length } : {})
+  };
+  const detail = values.verbose ? { layoutComposition: graphs.map(layoutComposition), layout: compiled.map(item => item.report), quality } : {};
+  console.log(JSON.stringify(graphs.length === 1 && !Object.hasOwn(graph, 'diagrams')
+    ? { generated: true, diagramType: diagramTypeOf(graphs[0]), outputDir, files, ...summary, ...detail, sourceEvidence }
+    : { generated: true, diagramTypes: graphs.map(diagramTypeOf), diagrams: graphs.length, outputDir, files, ...summary, ...detail, sourceEvidence }));
+}
+
+if (process.argv[1] && fs.existsSync(process.argv[1]) && fs.realpathSync(process.argv[1]) === fs.realpathSync(fileURLToPath(import.meta.url))) try {
+  await main();
+} catch (error) {
+  console.error(error.message);
+  if (error.phases || error.candidates) console.error(JSON.stringify({ ...error.phases, ...(error.failedViews ? { failedViews: error.failedViews } : {}), diagnostics: error.diagnostics, candidates: error.candidates }));
+  process.exit(1);
+}

package/skills/q-flow/scripts/validate-graph.mjs

@@ -0,0 +1,278 @@
+#!/usr/bin/env node
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parseArgs } from 'node:util';
+import { auditGraphLayout, graphBounds } from '../assets/viewer/src/edge-routing.js';
+import { canvasBudgetFor, diagramTypeOf } from '../assets/viewer/src/diagrams/registry.js';
+import { ASPECT_BAND, ASPECT_SLACK, ratioExcess } from '../assets/viewer/src/layout-spacing.js';
+import { graphsOf, reviewComposition, validateGraphInput } from '../assets/viewer/src/graph-validation.js';
+import { requireDiagramQuality, qualityFailure } from '../assets/viewer/src/layout-quality.js';
+import { operandScopes } from '../assets/viewer/src/sequence-fragments.js';
+import { callsMissingExecutions } from '../assets/viewer/src/sequence-executions.js';
+export { DIAGRAM_TYPES, diagramTypeOf } from '../assets/viewer/src/diagrams/registry.js';
+export { graphsOf, reviewComposition, validateGraph, validateGraphInput } from '../assets/viewer/src/graph-validation.js';
+
+const USAGE = `Usage: node validate-graph.mjs <graph.json> [options]
+  --input-only          check semantics only (no geometry); use before generating
+  --repo-root <dir>     verify every node source (file, line range, symbol) against this working tree
+  --fix                 repair mechanical errors in place (sequence order numbering, opt/loop/par operand ids,
+                        unambiguous replyTo, the callee activation bar of each answered sync call; with --repo-root,
+                        anchor line re-anchoring to a symbol found once in its file); prints each change; writes back
+                        only when the graph then passes
+  --verbose             print the full receipt (layout composition, diagnostics) instead of one summary line
+  -h, --help            this text
+Success prints one JSON line; failure prints the failing elements with rule, measurement and remediation.
+Composition warnings never fail the run; --input-only prints them in full, later steps only count them in the
+receipt. Fix module.missing, module.inconsistent and flowchart.process-branch; module.single-tone asks whether the
+steps really are one subsystem's work.`;
+
+export function readAndValidateGraph(inputPath, options = {}) {
+  const absolute = path.resolve(inputPath);
+  const graph = JSON.parse(fs.readFileSync(absolute, 'utf8'));
+  const semantic = validateGraphInput(graph, { ...options, inputOnly: true });
+  const errors = semantic.length ? semantic : validateGraphInput(graph, options);
+  if (errors.length) {
+    const phase = semantic.length ? 'semantic' : 'geometry';
+    const diagnostics = errors.flatMap(message => {
+      const index = message.match(/^diagrams\[(\d+)\]\./)?.[1];
+      return qualityFailure(index === undefined ? graph : graph.diagrams[index], phase, message.replace(/^diagrams\[\d+\]\./, '')).diagnostics;
+    });
+    throw qualityFailure(graph, phase, `Invalid graph:\n- ${errors.join('\n- ')}`, diagnostics);
+  }
+  if (!options.inputOnly) for (const item of graphsOf(graph)) {
+    requireDiagramQuality(item);
+    for (const warning of auditGraphLayout(item).warnings) console.warn(`Layout warning: ${warning}`);
+    for (const warning of layoutComposition(item).warnings) console.warn(`Composition warning (${diagramTypeOf(item)}): ${warning}`);
+  }
+  return graph;
+}
+
+// Warnings only. The full lines print once per delivery — during input validation, where the author repairs the
+// graph; generation and output validation see the same facts again and carry only the count in their receipt.
+export function printCompositionReview(graph, { print = true } = {}) {
+  const warnings = reviewComposition(graph);
+  if (print) for (const warning of warnings) console.warn(`Composition warning (${warning.diagramType}) ${warning.ruleId}: ${warning.message} — ${warning.remediation}`);
+  return warnings;
+}
+
+export function layoutComposition(graph) {
+  const { width, height } = graphBounds(graph);
+  const canvasBudget = canvasBudgetFor(diagramTypeOf(graph));
+  const targetRatio = canvasBudget ? canvasBudget.width / canvasBudget.height : null, aspectRatio = width / height;
+  const fit = targetRatio === null ? null : Math.min(aspectRatio / targetRatio, targetRatio / aspectRatio);
+  const singleRow = diagramTypeOf(graph) !== 'sequence' && graph.nodes.length >= 6
+    && Math.max(...graph.nodes.map(node => node.position.y)) < Math.min(...graph.nodes.map(node => node.position.y + node.size.height));
+  const warnings = [];
+  if (singleRow) warnings.push('single-row layout: arrange semantic layers, branches or groups across multiple rows');
+  // The band is informational here: a small graph may legitimately sit outside it, so it never warns.
+  return { diagramType: diagramTypeOf(graph), canvasBudget, aspectRatio: Number(aspectRatio.toFixed(2)), targetRatio: targetRatio === null ? null : Number(targetRatio.toFixed(2)), fit: fit === null ? null : Number(fit.toFixed(2)),
+    aspectBand: targetRatio === null ? null : ASPECT_BAND, bandSlack: targetRatio === null ? null : ASPECT_SLACK, withinBand: targetRatio === null ? null : +ratioExcess(aspectRatio).toFixed(2) <= ASPECT_SLACK, singleRow, warnings };
+}
+
+// Mechanical repairs only: numbering, operand ids, unambiguous reply pairing and the activation bar a paired sync call
+// requires (its anchors follow from the pair). Facts (kinds, evidence, labels, fields, anchors) are never touched and no
+// other element is added; every change is reported so the author can veto it.
+export function applyMechanicalFixes(input) {
+  const changes = [], blocked = [];
+  for (const [index, graph] of graphsOf(input).entries()) {
+    if (graph?.meta?.diagramType !== 'sequence' || !Array.isArray(graph.edges) || !Array.isArray(graph.nodes)) continue;
+    const prefix = Object.hasOwn(input, 'diagrams') ? `diagrams[${index}].` : '';
+    const edges = graph.edges.filter(edge => edge && typeof edge === 'object');
+    // 1. order: renumber in authoring order when any value is missing, invalid or duplicated.
+    const orders = edges.map(edge => edge.order);
+    const valid = value => Number.isInteger(value) && value > 0;
+    if (orders.some(value => !valid(value)) || new Set(orders).size !== orders.length) {
+      edges.forEach((edge, i) => { if (edge.order !== i + 1) { changes.push(`${prefix}edge ${edge.id}.order ${JSON.stringify(edge.order)} → ${i + 1}`); edge.order = i + 1; } });
+    }
+    // 2. operand ids for opt / loop / par.
+    for (const group of graph.groups ?? []) {
+      if (!group || group.kind === 'alt' || !Array.isArray(group.operands)) continue;
+      group.operands.forEach((operand, i) => {
+        if (operand && typeof operand === 'object' && operand.id === undefined) { operand.id = `op${i + 1}`; changes.push(`${prefix}group ${group.id}.operands[${i}].id → op${i + 1}`); }
+      });
+    }
+    // 3. replyTo: exactly one earlier, unanswered, reversed call in the same operand scope.
+    const scopes = operandScopes(graph);
+    const answered = new Set(edges.map(edge => edge.replyTo).filter(Boolean));
+    for (const edge of edges.filter(edge => edge.kind === 'return' && edge.replyTo === undefined)) {
+      const candidates = edges.filter(call => ['sync', 'async'].includes(call.kind) && valid(call.order) && call.order < edge.order && call.source === edge.target && call.target === edge.source && !answered.has(call.id) && (scopes.get(call.id) ?? '') === (scopes.get(edge.id) ?? ''));
+      if (candidates.length === 1) { edge.replyTo = candidates[0].id; answered.add(candidates[0].id); changes.push(`${prefix}edge ${edge.id}.replyTo → ${candidates[0].id}`); }
+      else blocked.push(`${prefix}edge ${edge.id}.replyTo not filled: ${candidates.length ? `${candidates.length} candidates (${candidates.map(call => call.id).join(', ')})` : 'no unanswered reversed call before it'}`);
+    }
+    // 4. executions: an answered sync call gets its callee bar (call receive → reply send), nested in the innermost bar of
+    // that participant around it. Longer calls go first, so a bar added inside them finds its parent.
+    if (edges.length === graph.edges.length && (graph.executions === undefined || Array.isArray(graph.executions) && graph.executions.every(bar => bar && typeof bar === 'object'))) {
+      const bars = graph.executions ?? [], byId = new Map(edges.map(edge => [edge.id, edge]));
+      const point = anchor => { const edge = byId.get(anchor?.edgeId); return edge ? edge.order * 2 + Number(anchor.at === 'receive' && edge.source === edge.target) : NaN; };
+      const missing = callsMissingExecutions(graph).sort((a, b) => (b.reply.order - b.call.order) - (a.reply.order - a.call.order) || a.call.order - b.call.order);
+      for (const { call, reply } of missing) {
+        let id = `x-${call.id}`;
+        for (let n = 2; bars.some(bar => bar.id === id); n++) id = `x-${call.id}-${n}`;
+        const bar = { id, participantId: call.target, start: { edgeId: call.id, at: 'receive' }, end: { edgeId: reply.id, at: 'send' } };
+        const from = point(bar.start), to = point(bar.end);
+        const parent = bars.filter(other => other.participantId === call.target && point(other.start) <= from && to <= point(other.end) && (point(other.start) < from || to < point(other.end)))
+          .sort((a, b) => (point(a.end) - point(a.start)) - (point(b.end) - point(b.start)))[0];
+        if (parent) bar.parentId = parent.id;
+        bars.push(bar);
+        changes.push(`${prefix}execution ${id} on ${call.target} from ${call.id} receive to ${reply.id} send${parent ? ` inside ${parent.id}` : ''}`);
+      }
+      if (bars.length && graph.executions === undefined) graph.executions = bars;
+    }
+  }
+  return { changes, blocked };
+}
+
+// Fix in memory, then judge with every check the run makes without --fix (geometry and the quality gate unless
+// --input-only, source evidence under a repository root), and write back only a graph that passes all of them.
+export function fixGraphFile(inputPath, { repoRoot, ...options } = {}) {
+  const absolute = path.resolve(inputPath);
+  const original = fs.readFileSync(absolute, 'utf8');
+  const graph = JSON.parse(original);
+  const mechanical = applyMechanicalFixes(graph), anchors = repoRoot === undefined ? { changes: [], blocked: [] } : applyAnchorFixes(graph, repoRoot);
+  const changes = [...mechanical.changes, ...anchors.changes], blocked = [...mechanical.blocked, ...anchors.blocked];
+  let errors = validateGraphInput(graph, { ...options, inputOnly: true });
+  if (!errors.length && !options.inputOnly) errors = validateGraphInput(graph, options);
+  if (!errors.length && !options.inputOnly) for (const [index, item] of graphsOf(graph).entries()) {
+    const prefix = Object.hasOwn(graph, 'diagrams') ? `diagrams[${index}].` : '';
+    try { requireDiagramQuality(item); } catch (error) { errors.push(...error.message.split('\n- ').slice(1).map(message => prefix + message)); }
+  }
+  if (!errors.length && repoRoot !== undefined) {
+    try { verifySourceEvidence(graph, repoRoot); } catch (error) { errors = error.message.split('\n- ').slice(1); }
+  }
+  if (errors.length) return { changes, blocked, errors, written: false };
+  const text = `${JSON.stringify(graph, null, 2)}\n`;
+  const written = changes.length > 0 && text !== original;
+  if (written) fs.writeFileSync(absolute, text);
+  return { changes, blocked, errors: [], written };
+}
+
+// Re-anchors a drifted node whose symbol occurs exactly once in its file; the range moves with it and keeps its span.
+// Several matches need a judgement about which one is the definition, so they are only reported.
+export function applyAnchorFixes(input, repoRoot) {
+  const changes = [], blocked = [], { read } = sourceReader(repoRoot);
+  for (const [index, graph] of graphsOf(input).entries()) {
+    const prefix = Object.hasOwn(input, 'diagrams') ? `diagrams[${index}].` : '';
+    for (const node of Array.isArray(graph?.nodes) ? graph.nodes : []) {
+      const source = node?.source;
+      if (typeof source?.symbol !== 'string' || !Number.isInteger(source.lineStart)) continue;
+      let lines;
+      try { lines = read(source.file); } catch { continue; } // reported by the source evidence check
+      const term = symbolTerm(source.symbol), found = term ? symbolLines(lines, term) : [];
+      if (found.some(line => line >= source.lineStart && line <= (source.lineEnd ?? source.lineStart))) continue;
+      if (found.length !== 1) { blocked.push(`${prefix}node ${node.id}.source not re-anchored: "${term ?? source.symbol}" ${foundAt(found)}`); continue; }
+      const lineEnd = source.lineEnd === undefined ? undefined : Math.min(lines.length, found[0] + source.lineEnd - source.lineStart);
+      changes.push(`${prefix}node ${node.id}.source.lineStart ${source.lineStart} → ${found[0]}${lineEnd === undefined ? '' : `, lineEnd ${source.lineEnd} → ${lineEnd}`}`);
+      source.lineStart = found[0];
+      if (lineEnd !== undefined) source.lineEnd = lineEnd;
+    }
+  }
+  return { changes, blocked };
+}
+
+// ponytail: a whole-word text match on the symbol's last segment, not a definition parser. A mention left inside the
+// range (a comment, a call) still passes after the definition moved; add per-language definition rules if that bites.
+const symbolTerm = symbol => symbol.split(/[^\p{L}\p{N}_$]+/u).filter(Boolean).at(-1);
+const symbolLines = (lines, term) => {
+  const word = new RegExp(`(?<![\\p{L}\\p{N}_$])${term.replaceAll('$', '\\$')}(?![\\p{L}\\p{N}_$])`, 'u');
+  return lines.flatMap((line, index) => word.test(line) ? [index + 1] : []);
+};
+const foundAt = lines => lines.length ? `found at line${lines.length > 1 ? 's' : ''} ${lines.slice(0, 5).join(', ')}${lines.length > 5 ? ` and ${lines.length - 5} more` : ''}` : 'not found in the file';
+
+// Reads repository files once each: repository-relative paths only, no escape through symlinks, UTF-8 text only.
+function sourceReader(repoRoot) {
+  if (typeof repoRoot !== 'string' || !repoRoot.trim()) throw new Error('--repo-root must name a directory');
+  const root = fs.realpathSync(repoRoot);
+  if (!fs.statSync(root).isDirectory()) throw new Error('--repo-root must name a directory');
+  const files = new Map();
+  const read = name => {
+    if (path.isAbsolute(name) || path.win32.isAbsolute(name) || /[\\\0]/.test(name) || name.split('/').includes('..')) {
+      throw new Error('path must be repository-relative without parent traversal');
+    }
+    const file = fs.realpathSync(path.resolve(root, name)), relative = path.relative(root, file);
+    if (relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) throw new Error('path resolves outside --repo-root');
+    if (!files.has(file)) {
+      if (!fs.statSync(file).isFile()) throw new Error('path must name a regular file');
+      const bytes = fs.readFileSync(file);
+      if (bytes.includes(0)) throw new Error('source must be a UTF-8 text file');
+      const text = new TextDecoder('utf-8', { fatal: true }).decode(bytes);
+      const lines = text ? text.split(/\r\n|\n|\r/) : [];
+      if (/[\r\n]$/.test(text)) lines.pop();
+      files.set(file, lines);
+    }
+    return files.get(file);
+  };
+  return { read, files };
+}
+
+// Checks the explicitly selected working tree, not the revision named in sourceRef or the meaning of a claim.
+export function verifySourceEvidence(input, repoRoot) {
+  const anchors = graphsOf(input).flatMap((graph, graphIndex) => graph.nodes.flatMap((node, nodeIndex) => node.source
+    ? [{ source: node.source, label: `diagrams[${graphIndex}].nodes[${nodeIndex}].source` }] : []));
+  const summary = { scope: 'working-tree', references: anchors.length, checked: 0, files: 0 };
+  if (repoRoot === undefined) {
+    if (anchors.length) console.warn('Source evidence not verified: pass --repo-root <repository-directory> to check files, line ranges and symbols.');
+    return { ...summary, status: anchors.length ? 'skipped' : 'not-applicable', ...(anchors.length ? { reason: 'repository-root-not-provided' } : {}) };
+  }
+  const { read, files } = sourceReader(repoRoot), errors = [];
+  let symbols = 0;
+  for (const { source, label } of anchors) {
+    try {
+      const lines = read(source.file), end = source.lineEnd ?? source.lineStart;
+      if (end > lines.length) throw new Error(`line ${end} exceeds file length (${lines.length} lines)`);
+      if (typeof source.symbol !== 'string') continue;
+      symbols++;
+      const term = symbolTerm(source.symbol);
+      if (!term) throw new Error(`symbol ${JSON.stringify(source.symbol)} has no name to check`);
+      const found = symbolLines(lines, term);
+      if (!found.some(line => line >= source.lineStart && line <= end)) {
+        throw new Error(`symbol "${term}" is not in line${end === source.lineStart ? ` ${end}` : `s ${source.lineStart}-${end}`}; ${foundAt(found)}; run --fix to re-anchor a unique match`);
+      }
+    } catch (error) { errors.push(`${label} (${source.file}): ${error.code === 'ENOENT' ? 'file does not exist' : error.message}`); }
+  }
+  if (errors.length) throw new Error(`Invalid source evidence:\n- ${errors.join('\n- ')}`);
+  return { ...summary, status: anchors.length ? 'passed' : 'not-applicable', checked: anchors.length, files: files.size, symbols };
+}
+
+if (process.argv[1] && fs.existsSync(process.argv[1]) && fs.realpathSync(process.argv[1]) === fs.realpathSync(fileURLToPath(import.meta.url))) {
+  try {
+    const { positionals, values } = parseArgs({ allowPositionals: true, options: { 'repo-root': { type: 'string' }, 'input-only': { type: 'boolean', default: false }, fix: { type: 'boolean', default: false }, verbose: { type: 'boolean', default: false }, help: { type: 'boolean', short: 'h', default: false } } });
+    if (values.help) { console.log(USAGE); process.exit(0); }
+    if (positionals.length !== 1) throw new Error(USAGE);
+    if (values.fix) {
+      const result = fixGraphFile(positionals[0], { inputOnly: values['input-only'], repoRoot: values['repo-root'] });
+      for (const change of result.changes) console.error(`fixed: ${change}`);
+      for (const item of result.blocked) console.error(`not fixed: ${item}`);
+      if (result.errors.length) throw new Error(`Invalid graph after mechanical fixes (file left unchanged):\n- ${result.errors.join('\n- ')}`);
+      const file = path.resolve(positionals[0]), directory = path.dirname(file);
+      if (result.written) console.error(`wrote ${file} (${result.changes.length} change${result.changes.length === 1 ? '' : 's'})`);
+      // A generated page and its SVGs still embed the old data: regenerate them from the fixed file, keeping the layout.
+      if (result.written && fs.existsSync(path.join(directory, 'index.html'))) {
+        console.error(`regenerate the page and SVGs: node "${path.join(import.meta.dirname, 'generate-viewer.mjs')}" "${file}" "${directory}" --layout preserve --force${values['repo-root'] === undefined ? '' : ` --repo-root "${path.resolve(values['repo-root'])}"`}`);
+      }
+    }
+    const graph = readAndValidateGraph(positionals[0], { inputOnly: values['input-only'] });
+    const sourceEvidence = verifySourceEvidence(graph, values['repo-root']);
+    const warnings = printCompositionReview(graph, { print: values['input-only'] });
+    const graphs = graphsOf(graph);
+    const totals = {
+      nodes: graphs.reduce((sum, item) => sum + item.nodes.length, 0),
+      edges: graphs.reduce((sum, item) => sum + item.edges.length, 0),
+      groups: graphs.reduce((sum, item) => sum + (item.groups?.length ?? 0), 0),
+      semantic: { status: 'passed' },
+      geometry: { status: values['input-only'] ? 'not-checked' : 'passed' },
+      rendering: { status: 'not-checked' },
+      ...(warnings.length ? { warnings: warnings.length } : {}),
+      // Informational diagnostics and composition figures only on request; a passing graph reads as one line.
+      ...(values.verbose ? { diagnostics: values['input-only'] ? [] : graphs.flatMap(item => requireDiagramQuality(item).diagnostics), layoutComposition: values['input-only'] ? null : graphs.map(layoutComposition) } : {})
+    };
+    console.log(JSON.stringify(graphs.length === 1 && !Object.hasOwn(graph, 'diagrams')
+      ? { valid: true, diagramType: diagramTypeOf(graphs[0]), ...totals, sourceEvidence }
+      : { valid: true, diagramTypes: graphs.map(diagramTypeOf), diagrams: graphs.length, ...totals, sourceEvidence }));
+  } catch (error) {
+    console.error(error.message);
+    if (error.phases) console.error(JSON.stringify({ ...error.phases, diagnostics: error.diagnostics }));
+    process.exit(1);
+  }
+}