Skip to content

Turn any idea, plan, or codebase into a beautiful interactive diagram. An agent skill for Claude Code, Codex, and more.

fix(workflow): separate shared routes and preserve constrained geometry

sunsunsunc8942ed70ec0
diff --git a/archify.zip b/archify.zip
index cb18e206..c8478842 100644
Binary files a/archify.zip and b/archify.zip differ
diff --git a/archify/examples/workflow-agent-tool-call-rendered.html b/archify/examples/workflow-agent-tool-call-rendered.html
index bd6f7ea4..66d6a50b 100644
--- a/archify/examples/workflow-agent-tool-call-rendered.html
+++ b/archify/examples/workflow-agent-tool-call-rendered.html
@@ -5240,7 +5240,7 @@ OTHER DEALINGS IN THE FONT SOFTWARE.
<!-- Main Diagram -->
<div class="diagram-container" data-detail-level="read"
data-preset-badge-editorial-plate="ARCHIFY / PLATE 04">
- <svg viewBox="0 0 1096 684" role="img" lang="en" aria-labelledby="archify-diagram-title archify-diagram-description" data-animation="trace" data-preset="signal-flow" data-quality-profile="showcase">
+ <svg viewBox="0 0 1096 684" data-layout-contract="readable-v2" role="img" lang="en" aria-labelledby="archify-diagram-title archify-diagram-description" data-animation="trace" data-preset="signal-flow" data-quality-profile="showcase">
<title id="archify-diagram-title">Agent Tool Call Workflow</title>
<desc id="archify-diagram-description">A workflow diagram generated by Archify.</desc>
<!-- Definitions -->
@@ -5301,17 +5301,17 @@ OTHER DEALINGS IN THE FONT SOFTWARE.
<text x="770" y="482" class="t-messagebus" font-size="7" font-weight="600">Tool work</text>
<!-- Edge paths -->
- <path data-edge-from="router" data-edge-to="approval" data-edge-label="needs approval?" data-edge-key="0" data-edge-id="approval-check" data-composition-points="651.2,279;651.2,302;569.2,302;569.2,387;585.2,387" d="M 651.2 279 L 651.2 302 L 569.2 302 L 569.2 387 L 585.2 387" class="a-security" data-animate="edge" style="--step:3" stroke-width="1.4" marker-end="url(#arrowhead-security)"/>
- <path data-edge-from="approval" data-edge-to="blocked" data-edge-label="denied" data-edge-key="1" data-edge-id="approval-denied" data-composition-points="651.2,421;651.2,442;830,442;830,413" d="M 651.2 421 L 651.2 442 L 830 442 L 830 413" class="a-security" data-animate="edge" style="--step:9" stroke-width="1.4" marker-end="url(#arrowhead-security)"/>
- <path data-edge-from="approval" data-edge-to="tool" data-edge-key="2" data-edge-id="approved-tool" data-composition-points="651.2,421;651.2,521;764,521" d="M 651.2 421 L 651.2 521 L 764 521" class="a-emphasis" data-animate="edge" style="--step:4" stroke-width="1.8" marker-end="url(#arrowhead-emphasis)"/>
- <path data-edge-from="external" data-edge-to="final" data-edge-key="3" data-edge-id="external-reply" data-composition-points="1056,521;1080,521;1080,120;1056,120" d="M 1056 521 L 1080 521 L 1080 120 L 1056 120" class="a-emphasis" data-animate="edge" style="--step:6" stroke-width="1.2" marker-end="url(#arrowhead-emphasis)"/>
- <path data-edge-from="chat" data-edge-to="planner" data-edge-label="plan" data-edge-key="4" data-edge-id="plan-request" data-composition-points="274,146;274,253;425.2,253" d="M 274 146 L 274 253 L 425.2 253" class="a-emphasis" data-animate="edge" style="--step:1" stroke-width="1.8" marker-end="url(#arrowhead-emphasis)"/>
- <path data-edge-from="planner" data-edge-to="router" data-edge-key="5" data-edge-id="planner-route" data-composition-points="557.2,253;585.2,253" d="M 557.2 253 L 585.2 253" class="a-default" data-animate="edge" style="--step:2" stroke-width="1.4" marker-end="url(#arrowhead)"/>
- <path data-edge-from="external" data-edge-to="trace" data-edge-label="record result" data-edge-key="6" data-edge-id="record-result" data-composition-points="990,547;990,579;491.2,579;491.2,547" d="M 990 547 L 990 579 L 491.2 579 L 491.2 547" class="a-dashed" data-animate="edge" style="--step:12" stroke-width="1.4" marker-end="url(#arrowhead-dashed)"/>
- <path data-edge-from="user" data-edge-to="chat" data-edge-key="7" data-edge-id="request-chat" data-composition-points="180,120;208,120" d="M 180 120 L 208 120" class="a-default" data-animate="edge" style="--step:0" stroke-width="1.4" marker-end="url(#arrowhead)"/>
- <path data-edge-from="blocked" data-edge-to="retry" data-edge-key="8" data-edge-id="retry-request" data-composition-points="896,387;924,387" d="M 896 387 L 924 387" class="a-dashed" data-animate="edge" style="--step:12" stroke-width="1.4" marker-end="url(#arrowhead-dashed)"/>
- <path data-edge-from="tool" data-edge-to="external" data-edge-key="9" data-edge-id="tool-external-call" data-composition-points="896,521;924,521" d="M 896 521 L 924 521" class="a-default" data-animate="edge" style="--step:5" stroke-width="1.4" marker-end="url(#arrowhead)"/>
- <path data-edge-from="store" data-edge-to="trace" data-edge-label="trace + memory" data-edge-key="10" data-edge-id="write-trace-memory" data-composition-points="340,521;425.2,521" d="M 340 521 L 425.2 521" class="a-dashed" data-animate="edge" style="--step:12" stroke-width="1.4" marker-end="url(#arrowhead-dashed)"/>
+ <path data-edge-from="router" data-edge-to="approval" data-edge-label="needs approval?" data-edge-key="0" data-edge-id="approval-check" data-composition-routing="workflow-v2-auto" data-edge-role="" data-composition-points="651.2,279;651.2,302;569.2,302;569.2,387;585.2,387" d="M 651.2 279 L 651.2 302 L 569.2 302 L 569.2 387 L 585.2 387" class="a-security" data-animate="edge" style="--step:3" stroke-width="1.4" marker-end="url(#arrowhead-security)"/>
+ <path data-edge-from="approval" data-edge-to="blocked" data-edge-label="denied" data-edge-key="1" data-edge-id="approval-denied" data-composition-routing="workflow-v2-auto" data-edge-role="error" data-composition-points="651.2,421;651.2,442;830,442;830,413" d="M 651.2 421 L 651.2 442 L 830 442 L 830 413" class="a-security" data-animate="edge" style="--step:9" stroke-width="1.4" marker-end="url(#arrowhead-security)"/>
+ <path data-edge-from="approval" data-edge-to="tool" data-edge-key="2" data-edge-id="approved-tool" data-composition-routing="workflow-v2-auto" data-edge-role="" data-composition-points="639.2,421;639.2,521;764,521" d="M 639.2 421 L 639.2 521 L 764 521" class="a-emphasis" data-animate="edge" style="--step:4" stroke-width="1.8" marker-end="url(#arrowhead-emphasis)"/>
+ <path data-edge-from="external" data-edge-to="final" data-edge-key="3" data-edge-id="external-reply" data-edge-role="return" data-composition-points="1056,521;1080,521;1080,120;1056,120" d="M 1056 521 L 1080 521 L 1080 120 L 1056 120" class="a-emphasis" data-animate="edge" style="--step:6" stroke-width="1.2" marker-end="url(#arrowhead-emphasis)"/>
+ <path data-edge-from="chat" data-edge-to="planner" data-edge-label="plan" data-edge-key="4" data-edge-id="plan-request" data-composition-routing="workflow-v2-auto" data-edge-role="" data-composition-points="274,146;274,253;425.2,253" d="M 274 146 L 274 253 L 425.2 253" class="a-emphasis" data-animate="edge" style="--step:1" stroke-width="1.8" marker-end="url(#arrowhead-emphasis)"/>
+ <path data-edge-from="planner" data-edge-to="router" data-edge-key="5" data-edge-id="planner-route" data-composition-routing="workflow-v2-auto" data-edge-role="" data-composition-points="557.2,253;585.2,253" d="M 557.2 253 L 585.2 253" class="a-default" data-animate="edge" style="--step:2" stroke-width="1.4" marker-end="url(#arrowhead)"/>
+ <path data-edge-from="external" data-edge-to="trace" data-edge-label="record result" data-edge-key="6" data-edge-id="record-result" data-edge-role="" data-composition-points="990,547;990,579;491.2,579;491.2,547" d="M 990 547 L 990 579 L 491.2 579 L 491.2 547" class="a-dashed" data-animate="edge" style="--step:12" stroke-width="1.4" marker-end="url(#arrowhead-dashed)"/>
+ <path data-edge-from="user" data-edge-to="chat" data-edge-key="7" data-edge-id="request-chat" data-composition-routing="workflow-v2-auto" data-edge-role="" data-composition-points="180,120;208,120" d="M 180 120 L 208 120" class="a-default" data-animate="edge" style="--step:0" stroke-width="1.4" marker-end="url(#arrowhead)"/>
+ <path data-edge-from="blocked" data-edge-to="retry" data-edge-key="8" data-edge-id="retry-request" data-composition-routing="workflow-v2-auto" data-edge-role="branch" data-composition-points="896,387;924,387" d="M 896 387 L 924 387" class="a-dashed" data-animate="edge" style="--step:12" stroke-width="1.4" marker-end="url(#arrowhead-dashed)"/>
+ <path data-edge-from="tool" data-edge-to="external" data-edge-key="9" data-edge-id="tool-external-call" data-composition-routing="workflow-v2-auto" data-edge-role="" data-composition-points="896,521;924,521" d="M 896 521 L 924 521" class="a-default" data-animate="edge" style="--step:5" stroke-width="1.4" marker-end="url(#arrowhead)"/>
+ <path data-edge-from="store" data-edge-to="trace" data-edge-label="trace + memory" data-edge-key="10" data-edge-id="write-trace-memory" data-composition-routing="workflow-v2-auto" data-edge-role="" data-composition-points="340,521;425.2,521" d="M 340 521 L 425.2 521" class="a-dashed" data-animate="edge" style="--step:12" stroke-width="1.4" marker-end="url(#arrowhead-dashed)"/>
<!-- Nodes -->
<g id="node-user" data-node-id="user" data-node-label="User" tabindex="0" role="button" aria-label="Focus User, asks for work, User Interface › Intake" aria-pressed="false" data-node-kind="external" data-node-sublabel="asks for work" data-node-context="User Interface › Intake">
diff --git a/archify/renderers/shared/geometry.mjs b/archify/renderers/shared/geometry.mjs
index db75dd20..eaaed2b3 100644
--- a/archify/renderers/shared/geometry.mjs
+++ b/archify/renderers/shared/geometry.mjs
@@ -576,10 +576,9 @@ function pointLiesOnSegment(point, start, end) {
&& point[1] <= Math.max(start[1], end[1]) + epsilon;
}
-// Reject only a proper interior X between relationships that share no semantic
-// endpoint. Endpoint touches, branch/merge ports, and collinear shared
-// corridors are intentionally outside this contract because geometry alone
-// cannot tell whether those are authored junctions.
+// Authored shared endpoints retain their junction interpretation by default.
+// Renderers can opt their automatic routes into proper interior X checks;
+// endpoint touches and collinear trunks still are not proper crossings.
export function cleanCrossingProblems({
relations,
endpointIds,
@@ -589,6 +588,7 @@ export function cleanCrossingProblems({
profile = 'standard',
profileIsAuthoritative = false,
mergeForwardCollinearWaypoints = false,
+ includeSharedEndpoints = () => false,
crossingResolved = () => false,
routeHint = 'adjust route/via or channel coordinates so the relationships use separate corridors'
}) {
@@ -613,7 +613,8 @@ export function cleanCrossingProblems({
const left = routed[leftIndex];
for (let rightIndex = leftIndex + 1; rightIndex < routed.length; rightIndex += 1) {
const right = routed[rightIndex];
- if ([left.relation.from, left.relation.to].some((id) => id === right.relation.from || id === right.relation.to)) continue;
+ if ([left.relation.from, left.relation.to].some((id) => id === right.relation.from || id === right.relation.to)
+ && !includeSharedEndpoints(left.relation, right.relation)) continue;
let hit = null;
for (const leftSegment of left.analysisSegments) {
@@ -668,12 +669,16 @@ export function cleanCrossingProblems({
// as one authored branch or merge even when neither relationship crosses a
// node or forms a proper X. Keep authored shared endpoints exempt by default;
// automatic architecture routes opt in because they promise separate ports.
+// Workflow v2 opts into shared-endpoint checks with a bounded terminal-trunk
+// exception. Other callers keep their existing authored-junction contract.
// Tiny overlaps below the route rhythm
// floor are ignored to avoid turning sub-pixel rounding into a quality debt.
export function collectAmbiguousCorridors({
routedRelations,
minOverlapPx = 8,
includeSharedEndpoints = () => false,
+ includeSharedEndpointCounterflow = () => false,
+ allowShortWorkflowTrunks = false,
}) {
const routed = asArray(routedRelations).map((entry, fallbackIndex) => {
const relation = entry?.relation;
@@ -692,8 +697,9 @@ export function collectAmbiguousCorridors({
const left = routed[leftIndex];
for (let rightIndex = leftIndex + 1; rightIndex < routed.length; rightIndex += 1) {
const right = routed[rightIndex];
- if ([left.relation.from, left.relation.to].some((id) => id === right.relation.from || id === right.relation.to)
- && !includeSharedEndpoints(left.relation, right.relation)) continue;
+ const sharedEndpoint = [left.relation.from, left.relation.to].some((id) => id === right.relation.from || id === right.relation.to);
+ const counterflowOnly = sharedEndpoint && !includeSharedEndpoints(left.relation, right.relation);
+ if (counterflowOnly && !includeSharedEndpointCounterflow(left.relation, right.relation)) continue;
let longest = null;
for (let leftSegment = 0; leftSegment < left.points.length - 1; leftSegment += 1) {
@@ -705,6 +711,12 @@ export function collectAmbiguousCorridors({
right.points[rightSegment + 1],
);
if (!overlap || overlap.length + 0.0001 < minOverlapPx) continue;
+ if (allowShortWorkflowTrunks && shortWorkflowTrunk(left, right, leftSegment, rightSegment, overlap.length)) continue;
+ if (counterflowOnly) {
+ const leftDelta = left.points[leftSegment + 1].map((value, axis) => value - left.points[leftSegment][axis]);
+ const rightDelta = right.points[rightSegment + 1].map((value, axis) => value - right.points[rightSegment][axis]);
+ if (leftDelta[0] * rightDelta[0] + leftDelta[1] * rightDelta[1] >= 0) continue;
+ }
if (!longest || overlap.length > longest.overlapLength + 0.0001) {
longest = {
left,
@@ -724,9 +736,26 @@ export function collectAmbiguousCorridors({
return hits;
}
+function shortWorkflowTrunk(left, right, leftSegment, rightSegment, length) {
+ if (length > 24 + 0.0001) return false;
+ const a = left.relation, b = right.relation;
+ const variant = (edge) => edge.variant || 'default';
+ const width = (edge) => edge.width || (variant(edge) === 'emphasis' ? 1.8 : 1.4);
+ if (variant(a) !== variant(b) || width(a) !== width(b) || (a.role || '') !== (b.role || '')) return false;
+ const same = (p, q) => Math.abs(p[0] - q[0]) < 0.0001 && Math.abs(p[1] - q[1]) < 0.0001;
+ const source = a.from === b.from && leftSegment === 0 && rightSegment === 0
+ && same(left.points[0], right.points[0]);
+ const target = a.to === b.to && leftSegment === left.points.length - 2 && rightSegment === right.points.length - 2
+ && same(left.points.at(-1), right.points.at(-1));
+ if (!source && !target) return false;
+ const p = left.points[leftSegment], q = left.points[leftSegment + 1];
+ const r = right.points[rightSegment], s = right.points[rightSegment + 1];
+ return (q[0] - p[0]) * (s[0] - r[0]) + (q[1] - p[1]) * (s[1] - r[1]) > 0;
+}
+
// Bundled arrow markers are 7 stroke-widths across the direction of travel.
// Callers select the automatic routes they own; explicit junctions are preserved.
-export function collectArrowheadCollisions({ routedRelations }) {
+export function collectArrowheadCollisions({ routedRelations, allowShortWorkflowTrunks = false }) {
const incoming = new Map();
const hits = [];
for (const entry of asArray(routedRelations)) {
@@ -745,6 +774,12 @@ export function collectArrowheadCollisions({ routedRelations }) {
if (Math.abs(tip[1 - axis] - sibling.tip[1 - axis]) > 0.0001) continue;
const distance = Math.abs(tip[axis] - sibling.tip[axis]);
const minimum = halfWidth + sibling.halfWidth;
+ if (allowShortWorkflowTrunks) {
+ const left = { ...sibling, points: normalizeRoutePoints(sibling.points) };
+ const right = { ...entry, points };
+ const overlap = collinearAxisOverlap(left.points.at(-2), left.points.at(-1), points.at(-2), tip);
+ if (overlap && shortWorkflowTrunk(left, right, left.points.length - 2, points.length - 2, overlap.length)) continue;
+ }
if (distance < minimum - 0.0001) hits.push({ left: sibling, right: current, distance, minimum });
}
siblings.push(current);
@@ -764,11 +799,15 @@ export function cleanAmbiguousCorridorProblems({
routeHint = 'adjust route/via or channel coordinates so the relationships use separate corridors',
minOverlapPx = 8,
includeSharedEndpoints = () => false,
+ includeSharedEndpointCounterflow = () => false,
+ allowShortWorkflowTrunks = false,
+ onDiagnostic = recordDiagnostic,
}) {
- if (qualityProfileForGate(profile, profileIsAuthoritative) !== 'showcase') return [];
+ const severity = qualityProfileForGate(profile, profileIsAuthoritative) === 'showcase' ? 'error' : 'warning';
+ if (severity === 'warning' && !allowShortWorkflowTrunks) return [];
const routedRelations = collectEligibleRoutedRelations({ relations, endpointIds, pathFor });
- return collectAmbiguousCorridors({ routedRelations, minOverlapPx, includeSharedEndpoints }).map((hit) => {
+ return collectAmbiguousCorridors({ routedRelations, minOverlapPx, includeSharedEndpoints, includeSharedEndpointCounterflow, allowShortWorkflowTrunks }).map((hit) => {
const describe = ({ relation, relationIndex }) => {
const id = relation.id ? ` id "${relation.id}"` : '';
return `${relationCollection}[${relationIndex}]${id} "${relation.from}" -> "${relation.to}"`;
@@ -777,10 +816,10 @@ export function cleanAmbiguousCorridorProblems({
const from = hit.overlapStart.map((value) => Math.round(value * 10) / 10).join(', ');
const to = hit.overlapEnd.map((value) => Math.round(value * 10) / 10).join(', ');
const hint = rePlanHint([hit.left.relation, hit.right.relation], routeHint);
- const message = `[composition/ambiguous-corridor] showcase ${diagramType} ${describe(hit.left)} shares a ${length}px corridor with ${describe(hit.right)} at [${from}] -> [${to}] (segments ${hit.leftSegment} and ${hit.rightSegment}; minimum ${minOverlapPx}px) — ${hint}.`;
- recordDiagnostic({
+ const message = `[composition/ambiguous-corridor] ${severity === 'error' ? 'showcase' : 'standard'} ${diagramType} ${describe(hit.left)} shares a ${length}px corridor with ${describe(hit.right)} at [${from}] -> [${to}] (segments ${hit.leftSegment} and ${hit.rightSegment}; minimum ${minOverlapPx}px) — ${hint}.`;
+ onDiagnostic({
code: 'composition/ambiguous-corridor',
- severity: 'error',
+ severity,
message,
subject: relationshipSubject(diagramType, relationCollection, hit.left.relationIndex, hit.left.relation),
evidence: {
@@ -794,8 +833,8 @@ export function cleanAmbiguousCorridorProblems({
},
supportedFixes: [hint],
});
- return message;
- });
+ return severity === 'error' ? message : null;
+ }).filter(Boolean);
}
// Relationship paths may cross a structural frame, but they must not borrow a
diff --git a/archify/renderers/workflow/README.md b/archify/renderers/workflow/README.md
index ae022631..a1c56056 100644
--- a/archify/renderers/workflow/README.md
+++ b/archify/renderers/workflow/README.md
@@ -264,7 +264,26 @@ Set `meta.quality_profile` to `showcase` for polished delivery. Unrelated proper
X crossings then fail with `composition/proper-crossing`; default `standard`
keeps them as artifact-receipt warnings. Collinear lane corridors are outside
the proper-X rule, but a separate gate warns in `standard` and fails in
-`showcase` when unrelated edges overlap for at least 8px. Shared semantic
-endpoints, point touches, and shorter overlaps remain valid. Showcase also
+`showcase` when unrelated edges overlap for at least 8px. V1 keeps its authored
+shared-endpoint contract. V2 also checks shared endpoints, including explicitly
+controlled routes: long or mixed-style trunks, counterflow, proper interior X
+crossings and overlapping independent arrowheads are not exempt. Pins are
+preserved, not silently repaired; unresolved v2 corridor/arrowhead collisions
+warn in `standard` and fail in `showcase`.
+
+V2 permits a same-direction shared terminal stub of at most 24 SVG units only
+when both relationships share the actual source or target port, effective
+variant, stroke width and role. A nonterminal overlap is never such a stub;
+forward-collinear waypoints do not split a long trunk into permitted pieces.
+Compatible short merges may share their terminal arrowhead. Automatic routes
+consider separate ports, reserve absolute routes at contested nodes, and prefer
+clear paths over shorter ambiguous ones. Crowded automatic corridors can use a
+bounded local adjustment without moving nodes or changing explicit coordinates.
+
+The SVG carries `data-layout-contract="readable-v2"` and each edge's role so
+artifact checks apply the same classification to actual visible path geometry,
+not stale composition-point metadata. These internal output attributes do not
+add authoring schema fields. Other diagram types retain their existing rules.
+Showcase also
rejects any route segment below 8px and any interior turn segment below 16px;
ordinary 8–15px endpoint stubs remain valid for fixed lane gaps.
diff --git a/archify/renderers/workflow/workflow-compiler.mjs b/archify/renderers/workflow/workflow-compiler.mjs
index 252a4c7a..33623da7 100644
--- a/archify/renderers/workflow/workflow-compiler.mjs
+++ b/archify/renderers/workflow/workflow-compiler.mjs
@@ -44,6 +44,7 @@ import {
cleanLabelRouteClearanceProblems,
cleanLabelCanvasContainmentProblems,
collectAmbiguousCorridors,
+ collectArrowheadCollisions,
collectLabelRouteClearance,
collectBorderRuns,
forwardCollinearAnalysisSegments,
@@ -69,9 +70,9 @@ import {
const LEGACY_COLUMN_CENTERS = Object.freeze([88, 220, 300, 430, 500, 625]);
const READABLE_CANDIDATE_COST_PRIORITY = Object.freeze([
- 'automaticForwardReversePx',
'properCrossingCount',
'sharedCorridorPx',
+ 'automaticForwardReversePx',
'labelRouteClearanceDeficit',
'interiorPreferred28Deficit',
'bendCount',
@@ -1969,6 +1970,15 @@ function routeContainsChannelPin(points, field, value) {
function validateReadablePinnedGeometry() {
if (workflow.schema_version !== 2) return;
+ // Reserve absolute geometry at contested nodes before automatic routing,
+ // independently of IDs. Unrelated routes retain their diagnostic ordering.
+ for (const edge of workflow.edges) {
+ if (!hasAbsoluteRoutePins(edge) || !nodes.has(edge.from) || !nodes.has(edge.to)) continue;
+ if (!workflow.edges.some(other => !hasAbsoluteRoutePins(other)
+ && [edge.from, edge.to].some(id => id === other.from || id === other.to))) continue;
+ validateReadableRouteControls(edge);
+ pathFor(edge);
+ }
for (const edge of workflow.edges) {
if (!nodes.has(edge.from) || !nodes.has(edge.to)) continue;
validateReadableRouteControls(edge);
@@ -2443,6 +2453,7 @@ function validateWorkflow() {
profile: workflow.meta?.quality_profile,
profileIsAuthoritative: true,
mergeForwardCollinearWaypoints: workflow.schema_version === 2,
+ includeSharedEndpoints: () => workflow.schema_version === 2,
routeHint: 'adjust route/via, bias, or channel coordinates so the edges use separate lane corridors'
}));
problems.push(...cleanAmbiguousCorridorProblems({
@@ -2453,8 +2464,29 @@ function validateWorkflow() {
relationCollection: 'edges',
profile: workflow.meta?.quality_profile,
profileIsAuthoritative: true,
+ includeSharedEndpoints: () => workflow.schema_version === 2,
+ allowShortWorkflowTrunks: workflow.schema_version === 2,
+ onDiagnostic: (diagnostic) => workflowDiagnostics.push(diagnostic),
routeHint: 'adjust route/via, bias, or channel coordinates so unrelated edges do not visually merge'
}));
+ if (workflow.schema_version === 2) {
+ const routedRelations = workflow.edges.map((relation, relationIndex) => ({
+ relation: { ...relation, width: relation.width || (relation.variant === 'emphasis' ? 1.8 : 1.4) },
+ relationIndex, points: pathFor(relation).points,
+ }));
+ for (const hit of collectArrowheadCollisions({ routedRelations, allowShortWorkflowTrunks: true })) {
+ const severity = resolvedQualityProfile === 'showcase' ? 'error' : 'warning';
+ const name = entry => entry.relation.id || `${entry.relation.from}->${entry.relation.to}`;
+ const message = `[composition/arrowhead-collision] workflow arrows "${name(hit.left)}" and "${name(hit.right)}" overlap at their destination (clearance ${hit.distance}px; minimum ${hit.minimum}px).`;
+ workflowDiagnostics.push({
+ code: 'composition/arrowhead-collision', severity, message,
+ subject: { diagramType: 'workflow', edge: name(hit.left), from: hit.left.relation.from, to: hit.left.relation.to },
+ evidence: { otherEdge: name(hit.right), distancePx: hit.distance, minimumPx: hit.minimum },
+ supportedFixes: ['use separate destination sides or ports with clearance for both arrow markers'],
+ });
+ if (severity === 'error') problems.push(message);
+ }
+ }
problems.push(...cleanBorderRunProblems({
relations: workflow.edges,
endpointIds: new Set(nodes.keys()),
@@ -2550,6 +2582,7 @@ function validateWorkflow() {
if (problems.length) {
throwDiagnosticProblems('Workflow layout validation failed', problems, {
subject: { diagramType: 'workflow' },
+ diagnostics: workflowDiagnostics,
});
}
}
@@ -2883,6 +2916,7 @@ function oneBendCrossLaneVia(edge, start, end, fromSide, toSide) {
const pathCache = new Map();
const readableSideCache = new Map();
+const workflowDiagnostics = [];
function legacyAutomaticOneBendSides(edge, from, to) {
const automaticRoute = !edge.via && (!edge.route || edge.route === 'auto');
@@ -3193,19 +3227,6 @@ function corridorViaX(start, end, fromSide, toSide, x) {
return [startStub, [x, startStub[1]], [x, endStub[1]], endStub];
}
-function axisOverlapLength(a, b, c, d) {
- const horizontal = Math.abs(a[1] - b[1]) <= 0.0001
- && Math.abs(c[1] - d[1]) <= 0.0001
- && Math.abs(a[1] - c[1]) <= 0.0001;
- const vertical = Math.abs(a[0] - b[0]) <= 0.0001
- && Math.abs(c[0] - d[0]) <= 0.0001
- && Math.abs(a[0] - c[0]) <= 0.0001;
- if (!horizontal && !vertical) return 0;
- const axis = horizontal ? 0 : 1;
- return Math.max(0, Math.min(Math.max(a[axis], b[axis]), Math.max(c[axis], d[axis]))
- - Math.max(Math.min(a[axis], b[axis]), Math.min(c[axis], d[axis])));
-}
-
function properAxisCrossing(a, b, c, d) {
const firstHorizontal = Math.abs(a[1] - b[1]) <= 0.0001;
const secondHorizontal = Math.abs(c[1] - d[1]) <= 0.0001;
@@ -3220,19 +3241,31 @@ function properAxisCrossing(a, b, c, d) {
&& y < Math.max(vertical[0][1], vertical[1][1]) - 0.0001;
}
+function independentAutomaticRoute(edge) {
+ return workflow.schema_version === 2
+ && !edge.via && edge.channelX === undefined && edge.channelY === undefined
+ && !edge.labelAt
+ && (!edge.route || edge.route === 'auto')
+ && (!edge.fromSide || edge.fromSide === 'auto')
+ && (!edge.toSide || edge.toSide === 'auto');
+}
+
function routeInteractionMetrics(edge, points) {
let properCrossingCount = 0;
let sharedCorridorPx = 0;
for (const [otherEdge, routed] of pathCache) {
- if ([edge.from, edge.to].some((id) => id === otherEdge.from || id === otherEdge.to)) continue;
+ const sharedEndpoint = [edge.from, edge.to].some((id) => id === otherEdge.from || id === otherEdge.to);
+ if (sharedEndpoint && workflow.schema_version !== 2) continue;
+ sharedCorridorPx += collectAmbiguousCorridors({
+ routedRelations: [{ relation: edge, points }, { relation: otherEdge, points: routed.points }],
+ includeSharedEndpoints: () => workflow.schema_version === 2,
+ allowShortWorkflowTrunks: workflow.schema_version === 2,
+ }).reduce((total, hit) => total + hit.overlapLength, 0);
for (let left = 0; left < points.length - 1; left += 1) {
for (let right = 0; right < routed.points.length - 1; right += 1) {
if (properAxisCrossing(points[left], points[left + 1], routed.points[right], routed.points[right + 1])) {
properCrossingCount += 1;
}
- sharedCorridorPx += axisOverlapLength(
- points[left], points[left + 1], routed.points[right], routed.points[right + 1],
- );
}
}
}
@@ -3750,6 +3783,39 @@ const automaticPorts = automaticPortSpread(workflow.edges, nodes, {
sideFor: (edge, endpoint) => edgeSides(edge)[endpoint === 'source' ? 'fromSide' : 'toSide'],
});
+function automaticPortCandidates(edge, node, side, preferred, counterpart) {
+ if (!independentAutomaticRoute(edge)) return [preferred];
+ const verticalSide = side === 'left' || side === 'right';
+ const axis = verticalSide ? 1 : 0;
+ const center = anchor(node, side);
+ const occupied = [];
+ for (const [other, routed] of pathCache) {
+ for (const endpoint of ['from', 'to']) {
+ if (other[endpoint] !== node.id) continue;
+ const point = endpoint === 'from' ? routed.points[0] : routed.points.at(-1);
+ const ownWidth = edge.width || (edge.variant === 'emphasis' ? 1.8 : 1.4);
+ const otherWidth = other.width || (other.variant === 'emphasis' ? 1.8 : 1.4);
+ if (Math.abs(point[1 - axis] - center[1 - axis]) < 0.0001) {
+ occupied.push({ coordinate: point[axis], clearance: Math.max(12, 3.5 * (ownWidth + otherWidth)) });
+ }
+ }
+ }
+ const clear = (point) => occupied.every(({ coordinate, clearance }) => Math.abs(coordinate - point[axis]) >= clearance - 0.0001);
+ if (clear(preferred)) return [preferred];
+ const candidates = [];
+ const extent = verticalSide ? node.height : node.width;
+ const direction = (verticalSide ? counterpart.cy : counterpart.cx) >= center[axis] ? 1 : -1;
+ for (let offset = 0; offset <= extent / 2 - 16; offset += 12) {
+ for (const sign of [direction, -direction]) {
+ const point = [...center];
+ point[axis] += sign * offset;
+ if (clear(point) && !candidates.some((candidate) => candidate[axis] === point[axis])) candidates.push(point);
+ }
+ if (candidates.length >= 2) return candidates.slice(0, 2);
+ }
+ return candidates.length ? candidates : [preferred];
+}
+
function readableAutomaticRoute(edge, from, to, primarySides, primaryPorts) {
const authoredFrom = edge.fromSide && edge.fromSide !== 'auto' ? edge.fromSide : null;
const authoredTo = edge.toSide && edge.toSide !== 'auto' ? edge.toSide : null;
@@ -3767,6 +3833,22 @@ function readableAutomaticRoute(edge, from, to, primarySides, primaryPorts) {
const plans = [];
const feedback = [];
let firstFailure = null;
+ // Spreading ports for provisional sides can offset an otherwise clear
+ // facing pair. Keep the aligned route in the same feasibility/cost contest.
+ const alignedStart = automaticPortCandidates(edge, from, naturalFromSide, anchor(from, naturalFromSide), to)[0];
+ const alignedEnd = automaticPortCandidates(edge, to, naturalToSide, anchor(to, naturalToSide), from)[0];
+ const alignedPoints = [alignedStart, alignedEnd];
+ if (to.col > from.col && !['return', 'error'].includes(edge.role)
+ && !edge.fromSide && !edge.toSide && !edge.labelAt
+ && readableCandidateIsFeasible(edge, alignedPoints, from, to, naturalFromSide, naturalToSide)) {
+ plans.push({
+ family: 'aligned-facing',
+ points: alignedPoints,
+ fromSide: naturalFromSide,
+ toSide: naturalToSide,
+ cost: readableCandidateCost(edge, alignedPoints, -1, naturalFromSide, naturalToSide),
+ });
+ }
for (const candidateSides of sidePairs) {
if (authoredFrom && candidateSides.fromSide !== authoredFrom) continue;
if (authoredTo && candidateSides.toSide !== authoredTo) continue;
@@ -3775,12 +3857,16 @@ function readableAutomaticRoute(edge, from, to, primarySides, primaryPorts) {
const pairOrdinal = seen.size;
seen.add(key);
const primary = pairOrdinal === 0;
- const start = primaryPorts?.from && primary
+ const preferredStart = primaryPorts?.from && primary
? primaryPorts.from
: anchor(from, candidateSides.fromSide);
- const end = primaryPorts?.to && primary
+ const preferredEnd = primaryPorts?.to && primary
? primaryPorts.to
: anchor(to, candidateSides.toSide);
+ const starts = automaticPortCandidates(edge, from, candidateSides.fromSide, preferredStart, to);
+ const ends = automaticPortCandidates(edge, to, candidateSides.toSide, preferredEnd, from);
+ const [start] = starts;
+ const [end] = ends;
const planned = readableAutomaticCandidateSet(
edge,
from,
@@ -3799,6 +3885,35 @@ function readableAutomaticRoute(edge, from, to, primarySides, primaryPorts) {
...candidate,
...candidateSides,
})));
+ let portOrdinal = 0;
+ for (const alternativeStart of starts) {
+ for (const alternativeEnd of ends) {
+ if (alternativeStart === start && alternativeEnd === end) continue;
+ portOrdinal += 1;
+ const alternative = readableAutomaticCandidateSet(edge, from, to, alternativeStart, alternativeEnd,
+ candidateSides.fromSide, candidateSides.toSide, {
+ ordinalOffset: pairOrdinal * 9 + portOrdinal * 144,
+ naturalFromSide,
+ naturalToSide,
+ });
+ plans.push(...alternative.candidates.map((candidate) => ({ ...candidate, ...candidateSides })));
+ if (!alternative.candidates.length) {
+ try {
+ const via = withDiagnosticRecordingSuppressed(() => readableAutomaticVia(
+ edge, from, to, alternativeStart, alternativeEnd, candidateSides.fromSide, candidateSides.toSide,
+ ));
+ const points = normalizeRoutePoints([alternativeStart, ...via, alternativeEnd]);
+ plans.push({
+ points, ...candidateSides,
+ cost: readableCandidateCost(edge, points, pairOrdinal * 9 + portOrdinal * 144 + 6, naturalFromSide, naturalToSide),
+ });
+ } catch (error) {
+ if (error instanceof WorkflowLayoutFeedback) feedback.push({ error, pairOrdinal });
+ else if (!firstFailure) firstFailure = error;
+ }
+ }
+ }
+ }
if (planned.candidates.length) continue;
try {
const expandedVia = withDiagnosticRecordingSuppressed(() => readableAutomaticVia(
@@ -3839,6 +3954,34 @@ function readableAutomaticRoute(edge, from, to, primarySides, primaryPorts) {
plans.sort((left, right) => compareCost(left.cost, right.cost));
if (plans.length) {
+ const repairSeeds = plans[0].cost.sharedCorridorPx > 0
+ ? plans.filter((plan, index) => plans.findIndex(other => (
+ other.fromSide === plan.fromSide && other.toSide === plan.toSide
+ && String(other.points[0]) === String(plan.points[0])
+ && String(other.points.at(-1)) === String(plan.points.at(-1))
+ )) === index).slice(0, 8) : [];
+ // A crowded fan-out can exhaust the fixed corridor coordinates even with
+ // distinct ports. Repair only interior segments of this automatic route;
+ // One pass over at most eight seeds and four offsets bounds the search.
+ for (const selected of repairSeeds) {
+ if (selected.cost.sharedCorridorPx === 0) continue;
+ const alternatives = [];
+ for (let segment = 1; segment < selected.points.length - 2; segment += 1) {
+ const a = selected.points[segment], b = selected.points[segment + 1];
+ const axis = a[0] === b[0] ? 0 : 1;
+ for (const offset of [-16, 16, -32, 32]) {
+ const points = selected.points.map(point => [...point]);
+ points[segment][axis] += offset;
+ points[segment + 1][axis] += offset;
+ if (!readableCandidateIsFeasible(edge, points, from, to, selected.fromSide, selected.toSide)) continue;
+ const cost = readableCandidateCost(edge, points, selected.cost.stableCandidateOrdinal, naturalFromSide, naturalToSide);
+ if (compareCost(cost, selected.cost) < 0) alternatives.push({ ...selected, points, cost });
+ }
+ }
+ alternatives.sort((a, b) => compareCost(a.cost, b.cost));
+ if (alternatives.length) plans.push(alternatives[0]);
+ }
+ plans.sort((a, b) => compareCost(a.cost, b.cost));
const selected = plans[0];
return {
points: selected.points,
@@ -4304,7 +4447,9 @@ function renderEdgePath(edge, index) {
const [cls, marker] = arrowClassMap[edge.variant || 'default'] || arrowClassMap.default;
const routed = pathFor(edge);
const strokeWidth = edge.width || (edge.variant === 'emphasis' ? 1.8 : 1.4);
- return ` <path ${focusEdgeAttrs(edge.from, edge.to, edge.label, index, edge.id)} data-composition-points="${routePointsValue(routed.points)}" d="${routed.d}" class="${cls}"${animateAttr(workflow.meta, 'edge', edgeSteps.get(edge))} stroke-width="${strokeWidth}" marker-end="url(#${marker})"/>`;
+ const routing = independentAutomaticRoute(edge) ? ' data-composition-routing="workflow-v2-auto"' : '';
+ const role = workflow.schema_version === 2 ? ` data-edge-role="${esc(edge.role || '')}"` : '';
+ return ` <path ${focusEdgeAttrs(edge.from, edge.to, edge.label, index, edge.id)}${routing}${role} data-composition-points="${routePointsValue(routed.points)}" d="${routed.d}" class="${cls}"${animateAttr(workflow.meta, 'edge', edgeSteps.get(edge))} stroke-width="${strokeWidth}" marker-end="url(#${marker})"/>`;
}
function renderEdgeLabel(edge, index) {
@@ -4340,7 +4485,8 @@ function renderSvg() {
&& asArray(layout.laneHeights).some((height) => height > 104)
? ' data-reader-fit="intrinsic-height"'
: '';
- return ` <svg viewBox="0 0 ${viewBox[0]} ${viewBox[1]}"${readerFit} ${svgRootAttrs(workflow.meta, resolvedQualityProfile)}>
+ const contract = workflow.schema_version === 2 ? ' data-layout-contract="readable-v2"' : '';
+ return ` <svg viewBox="0 0 ${viewBox[0]} ${viewBox[1]}"${readerFit}${contract} ${svgRootAttrs(workflow.meta, resolvedQualityProfile)}>
${svgAccessibleText(workflow.meta, 'workflow')}
${renderDefinitions()}
@@ -4402,7 +4548,7 @@ ${renderLegend()}
const [x, y] = workflowEdgeLabelPoint(edge, pathFor(edge).points);
return [{ edge: edge.id ?? null, label: edge.label, x, y, width: workflowLabelWidth(edge.label), height: 14 }];
}),
- diagnostics: [],
+ diagnostics: workflowDiagnostics,
};
return { ok: true, svg, receipt };
} catch (error) {
diff --git a/archify/scripts/check-render-output.mjs b/archify/scripts/check-render-output.mjs
index 42a381bd..ffd317e2 100644
--- a/archify/scripts/check-render-output.mjs
+++ b/archify/scripts/check-render-output.mjs
@@ -109,6 +109,7 @@ if (svgMatches.length === 1) {
const svgRoot = svg.match(/<svg\b[^>]*>/i)?.[0] || '';
const svgAttrs = parseAttrs(svgRoot);
const qualityProfile = svgAttrs['data-quality-profile'] || 'standard';
+ const workflowV2 = svgAttrs['data-layout-contract'] === 'readable-v2';
const qualityGatesEnforced = svgAttrs['data-quality-gates'] !== 'advisory';
const nonFiniteAttrs = collectNonFiniteAttrs(svg);
addCheck('finite_svg', nonFiniteAttrs.length === 0, nonFiniteAttrs);
@@ -124,14 +125,14 @@ if (svgMatches.length === 1) {
diagramType: svgAttrs['data-diagram-type'] || null,
hasGuidedViews: /class="guided-views/.test(html),
});
- const arrows = collectArrows(beforeLegend);
+ const arrows = collectArrows(beforeLegend, workflowV2);
const diagonal = arrows.flatMap((arrow) => diagonalStraightSegments(arrow).map((segment) => ({ arrow, ...segment })));
addCheck(
'orthogonal_arrows',
diagonal.length === 0,
diagonal.map(({ arrow, segmentIndex }) => `${arrow.kind} ${arrow.index} segment ${segmentIndex + 1}: expected an orthogonal segment or an explicitly authored direct straight route; ${arrow.raw}`),
);
- const measuredRelationshipCrossings = collectRelationshipCrossings(arrows);
+ const measuredRelationshipCrossings = collectRelationshipCrossings(arrows, workflowV2);
const resolvedCrossovers = measuredRelationshipCrossings.filter((hit) => (
hit.left.crossoverHalo && hit.right.crossoverHalo
));
@@ -157,10 +158,13 @@ if (svgMatches.length === 1) {
const routeRhythmIssues = collectRouteRhythmIssues({ routedRelations: routedRelationships });
const ambiguousCorridors = collectAmbiguousCorridors({
routedRelations: routedRelationships,
- includeSharedEndpoints: (left, right) => left.independentPorts && right.independentPorts,
+ includeSharedEndpoints: (left, right) => workflowV2 || (left.independentPorts && right.independentPorts),
+ allowShortWorkflowTrunks: workflowV2,
+ includeSharedEndpointCounterflow: (left, right) => left.automaticWorkflowRoute && right.automaticWorkflowRoute,
});
const arrowheadCollisions = collectArrowheadCollisions({
- routedRelations: routedRelationships.filter((entry) => entry.relation.independentPorts),
+ routedRelations: routedRelationships.filter((entry) => workflowV2 || entry.relation.independentPorts),
+ allowShortWorkflowTrunks: workflowV2,
});
const relationshipLabels = collectRelationshipLabelMasks(beforeLegend, arrows);
const leadingSpace = collectArchitectureLeadingSpace({
@@ -420,7 +424,7 @@ console.log(JSON.stringify({ ok, file: htmlPath, artifact, checks, composition }
// Let pending stdout writes drain: large receipts are asynchronous when piped.
process.exitCode = ok ? 0 : 1;
-function collectArrows(fragment) {
+function collectArrows(fragment, useActualPoints = false) {
const arrows = [];
let index = 0;
let previousTag = null;
@@ -472,10 +476,15 @@ function collectArrows(fragment) {
&& (tag[1].toLowerCase() === 'line' || /^\s*M\s+[-+\d.eE]+\s+[-+\d.eE]+\s+L\s+[-+\d.eE]+\s+[-+\d.eE]+\s*$/.test(attrs.d || '')),
crossoverHalo: verifiedCrossoverHalo,
independentPorts: verifiedCrossoverHalo && attrs['data-composition-independent'] === 'true',
+ // This opt-in only tightens shared-endpoint checks. It does not certify
+ // a crossover halo or exempt any existing artifact-quality rule.
+ automaticWorkflowRoute: attrs['data-composition-routing'] === 'workflow-v2-auto',
width: routeStrokeWidth,
+ variant: raw.match(/\ba-(default|emphasis|security|dashed)\b/)?.[1] || 'default',
+ role: attrs['data-edge-role'],
segments,
borderSegments,
- routePoints: parseRoutePoints(attrs['data-composition-points']) || (
+ routePoints: (!useActualPoints && parseRoutePoints(attrs['data-composition-points'])) || (
borderSegments.length ? [borderSegments[0].start, ...borderSegments.map((segment) => segment.end)] : []
),
from: attrs['data-edge-from'] || attrs['data-composition-edge-from'],
@@ -556,7 +565,7 @@ function parseRoutePoints(value) {
return points.length >= 2 && points.every(isPoint) ? points : null;
}
-function collectRelationshipCrossings(arrows) {
+function collectRelationshipCrossings(arrows, includeSharedEndpoints = false) {
const relationships = arrows.filter((arrow) => arrow.from && arrow.to && arrow.segments.length);
const crossings = [];
for (let leftIndex = 0; leftIndex < relationships.length; leftIndex += 1) {
@@ -564,9 +573,11 @@ function collectRelationshipCrossings(arrows) {
for (let rightIndex = leftIndex + 1; rightIndex < relationships.length; rightIndex += 1) {
const right = relationships[rightIndex];
// A shared semantic endpoint does not make an interior X a junction
- // when both generated paths promise independent automatic ports.
+ // when both paths opt into automatic workflow or independent-port checks.
if ([left.from, left.to].some((id) => id === right.from || id === right.to)
- && (!left.independentPorts || !right.independentPorts)) continue;
+ && !includeSharedEndpoints
+ && !(left.independentPorts && right.independentPorts)
+ && !(left.automaticWorkflowRoute && right.automaticWorkflowRoute)) continue;
let point = null;
for (const leftSegment of left.segments) {
for (const rightSegment of right.segments) {
diff --git a/archify/test/fixtures/workflow-routing-clarity.workflow.json b/archify/test/fixtures/workflow-routing-clarity.workflow.json
new file mode 100644
index 00000000..fb611899
--- /dev/null
+++ b/archify/test/fixtures/workflow-routing-clarity.workflow.json
@@ -0,0 +1,45 @@
+{
+ "schema_version": 2,
+ "diagram_type": "workflow",
+ "meta": {
+ "title": "Agent Turn Workflow",
+ "locale": "zh-CN",
+ "output": "workflow-routing-clarity.html",
+ "quality_profile": "showcase"
+ },
+ "lanes": [
+ { "id": "host", "label": "Runtime Host" },
+ { "id": "runtime", "label": "Session + AgentRun" },
+ { "id": "evidence", "label": "Events + Projections" }
+ ],
+ "phases": [
+ { "id": "admit", "label": "准入与路由", "fromCol": 0, "toCol": 1 },
+ { "id": "execute", "label": "Turn 执行", "fromCol": 2, "toCol": 4, "variant": "emphasis" },
+ { "id": "project", "label": "持久化与投影", "fromCol": 5, "toCol": 5, "variant": "dashed" }
+ ],
+ "mainPath": ["request", "admit", "start", "turn", "commit", "project"],
+ "nodes": [
+ { "id": "request", "lane": "host", "col": 0, "type": "frontend", "label": "Submit Task", "sublabel": "Desktop / TUI / CLI" },
+ { "id": "admit", "lane": "host", "col": 1, "type": "security", "label": "Host Admission", "sublabel": "client + capability" },
+ { "id": "start", "lane": "runtime", "col": 2, "type": "backend", "label": "Start Session", "sublabel": "SessionManager" },
+ { "id": "turn", "lane": "runtime", "col": 3, "type": "backend", "label": "Run Turn", "sublabel": "model + tool loop" },
+ { "id": "tool", "lane": "runtime", "col": 4, "type": "security", "label": "Tool Boundary", "sublabel": "permission / sandbox" },
+ { "id": "commit", "lane": "evidence", "col": 4, "type": "database", "label": "Append Event", "sublabel": "RuntimeEvent" },
+ { "id": "project", "lane": "evidence", "col": 5, "type": "frontend", "label": "Project State", "sublabel": "UI + recovery" },
+ { "id": "graph", "lane": "host", "col": 3, "type": "messagebus", "label": "Agent Graph", "sublabel": "dependent child work" },
+ { "id": "resume", "lane": "runtime", "col": 5, "type": "security", "label": "Resume Check", "sublabel": "safe replay or blocked" }
+ ],
+ "edges": [
+ { "from": "request", "to": "admit", "label": "client request", "role": "main" },
+ { "from": "admit", "to": "start", "label": "authorized session", "role": "main" },
+ { "from": "start", "to": "turn", "label": "startTurn", "role": "main" },
+ { "from": "turn", "to": "tool", "label": "dispatch tool", "variant": "security", "role": "main" },
+ { "from": "tool", "to": "turn", "label": "tool result", "variant": "dashed", "role": "return" },
+ { "from": "turn", "to": "commit", "label": "append event", "variant": "dashed", "role": "main" },
+ { "from": "commit", "to": "project", "label": "projection", "variant": "dashed", "role": "main" },
+ { "from": "start", "to": "graph", "label": "schedule graph", "variant": "emphasis", "role": "async" },
+ { "from": "graph", "to": "turn", "label": "activation", "variant": "dashed", "role": "return" },
+ { "from": "turn", "to": "resume", "label": "crash / handoff", "variant": "security", "role": "branch" },
+ { "from": "resume", "to": "commit", "label": "replay evidence", "variant": "dashed", "role": "return" }
+ ]
+}
diff --git a/archify/test/fixtures/workflow-shared-trunks.workflow.json b/archify/test/fixtures/workflow-shared-trunks.workflow.json
new file mode 100644
index 00000000..415dd606
--- /dev/null
+++ b/archify/test/fixtures/workflow-shared-trunks.workflow.json
@@ -0,0 +1,38 @@
+{
+ "schema_version": 2,
+ "diagram_type": "workflow",
+ "meta": { "title": "分支与回流", "locale": "zh-CN", "output": "workflow.html" },
+ "lanes": [
+ { "id": "parent", "label": "会话入口与用户反馈" },
+ { "id": "ordinary", "label": "普通工具路径" },
+ { "id": "execution", "label": "主会话调度与独立委派" },
+ { "id": "orchestration", "label": "多阶段编排路径" },
+ { "id": "process", "label": "后台进程路径" }
+ ],
+ "nodes": [
+ { "id": "submit", "lane": "parent", "col": 0, "type": "frontend", "label": "提交任务", "width": 156 },
+ { "id": "capabilities", "lane": "parent", "col": 1, "type": "security", "label": "加载能力", "width": 172 },
+ { "id": "decide", "lane": "execution", "col": 2, "type": "backend", "label": "执行决策", "width": 156 },
+ { "id": "native", "lane": "ordinary", "col": 3, "type": "backend", "label": "普通工具", "width": 172 },
+ { "id": "child", "lane": "execution", "col": 3, "type": "backend", "label": "独立执行", "width": 172 },
+ { "id": "workflow", "lane": "orchestration", "col": 3, "type": "messagebus", "label": "任务编排", "width": 172 },
+ { "id": "background", "lane": "process", "col": 3, "type": "external", "label": "后台进程", "width": 172 },
+ { "id": "collect", "lane": "execution", "col": 4, "type": "messagebus", "label": "接收结果", "width": 156 },
+ { "id": "reply", "lane": "parent", "col": 5, "type": "frontend", "label": "回复结果", "width": 172 }
+ ],
+ "edges": [
+ { "id": "prepare", "from": "submit", "to": "capabilities", "label": "回合启动前", "role": "main", "variant": "emphasis" },
+ { "id": "model-turn", "from": "capabilities", "to": "decide", "label": "可用工具面", "role": "main", "variant": "emphasis" },
+ { "id": "ordinary-work", "from": "decide", "to": "native", "label": "普通工作", "role": "main", "variant": "emphasis" },
+ { "id": "delegate-work", "from": "decide", "to": "child", "label": "独立执行", "role": "branch" },
+ { "id": "orchestrate-work", "from": "decide", "to": "workflow", "label": "编排执行", "role": "branch" },
+ { "id": "launch-process", "from": "decide", "to": "background", "label": "后台执行", "role": "branch" },
+ { "id": "native-result", "from": "native", "to": "collect", "label": "工具结果", "role": "main", "variant": "emphasis" },
+ { "id": "child-result", "from": "child", "to": "collect", "label": "完成后跟进", "role": "async", "variant": "dashed" },
+ { "id": "workflow-result", "from": "workflow", "to": "collect", "label": "等待返回/稍后投递", "role": "async", "variant": "dashed" },
+ { "id": "process-result", "from": "background", "to": "collect", "label": "状态/完成通知", "role": "async", "variant": "dashed" },
+ { "id": "continue-work", "from": "collect", "to": "decide", "label": "仍需后续工作", "role": "return", "variant": "dashed", "channelY": 180 },
+ { "id": "finish", "from": "collect", "to": "reply", "label": "综合结果", "role": "main", "variant": "emphasis" },
+ { "id": "direct-answer", "from": "decide", "to": "reply", "label": "无需工具时直接回答", "role": "branch" }
+ ]
+}
diff --git a/archify/test/geometry.test.mjs b/archify/test/geometry.test.mjs
index 7d224019..53c229ee 100644
--- a/archify/test/geometry.test.mjs
+++ b/archify/test/geometry.test.mjs
@@ -449,6 +449,25 @@ test('cleanCrossingProblems exempts shared endpoints', () => {
assert.deepEqual(problems, []);
});
+test('cleanCrossingProblems selectively checks automatic shared-endpoint interior crossings', () => {
+ const relations = [{ from: 'a', to: 'hub', automatic: true }, { from: 'b', to: 'hub', automatic: true }];
+ const paths = [
+ [[20, 20], [80, 20], [80, 80], [140, 80]],
+ [[20, 100], [120, 100], [120, 40], [140, 40]],
+ ];
+ const options = {
+ relations,
+ endpointIds: new Set(['a', 'b', 'hub']),
+ pathFor: (relation) => ({ points: paths[relations.indexOf(relation)] }),
+ diagramType: 'workflow', relationCollection: 'edges', profile: 'showcase',
+ includeSharedEndpoints: (left, right) => left.automatic && right.automatic,
+ };
+ assert.equal(cleanCrossingProblems(options).length, 1);
+ assert.deepEqual(cleanCrossingProblems({ ...options, profile: 'standard' }), []);
+ relations[1].automatic = false;
+ assert.deepEqual(cleanCrossingProblems(options), [], 'one authored route preserves the legacy exemption');
+});
+
test('cleanCrossingProblems exempts endpoint touches and collinear corridors', () => {
const relations = [
{ from: 'a', to: 'b' },
@@ -516,6 +535,36 @@ test('ambiguous corridor gate exempts shared endpoints, point touches, and overl
assert.deepEqual(collectAmbiguousCorridors({ routedRelations }), []);
});
+test('shared-endpoint counterflow opt-in detects reverse trunks while preserving same-direction branches', () => {
+ const first = { from: 'a', to: 'hub', automatic: true };
+ const second = { from: 'hub', to: 'b', automatic: true };
+ const paths = [ [[60, 20], [60, 100]], [[60, 100], [60, 49], [140, 49]] ];
+ const options = {
+ routedRelations: [first, second].map((relation, index) => ({ relation, points: paths[index] })),
+ includeSharedEndpointCounterflow: (left, right) => left.automatic && right.automatic,
+ };
+ const hits = collectAmbiguousCorridors(options);
+ assert.equal(hits.length, 1);
+ assert.equal(hits[0].overlapLength, 51);
+ assert.deepEqual(hits[0].overlapStart, [60, 49]);
+ assert.deepEqual(hits[0].overlapEnd, [60, 100]);
+ assert.equal(cleanAmbiguousCorridorProblems({
+ relations: [first, second], endpointIds: new Set(['a', 'hub', 'b']),
+ pathFor: (relation) => ({ points: paths[relation === first ? 0 : 1] }),
+ diagramType: 'workflow', relationCollection: 'edges', profile: 'showcase',
+ includeSharedEndpointCounterflow: options.includeSharedEndpointCounterflow,
+ }).length, 1, 'compiler wrapper forwards the selective policy');
+ second.automatic = false;
+ assert.deepEqual(collectAmbiguousCorridors(options), [], 'mixed automatic and authored routes retain compatibility');
+ second.automatic = true;
+ options.routedRelations[1].points = [[60, 49], [60, 100], [140, 100]];
+ assert.deepEqual(collectAmbiguousCorridors(options), [], 'same-direction trunks are permitted');
+ assert.equal(collectAmbiguousCorridors({ ...options, includeSharedEndpoints: () => true }).length, 1,
+ 'existing independent-port policy remains stricter');
+ options.routedRelations[1].points = [[60, 100], [60, 93], [140, 93]];
+ assert.deepEqual(collectAmbiguousCorridors(options), [], 'less than 8px remains below the overlap floor');
+});
+
test('ambiguous corridor gate keeps standard renderable', () => {
const relations = [{ from: 'a', to: 'b' }, { from: 'c', to: 'd' }];
const routes = [[[0, 20], [100, 20]], [[40, 20], [140, 20]]];
diff --git a/archify/test/render-output-checks.test.mjs b/archify/test/render-output-checks.test.mjs
index be8e4977..b40c3ddb 100644
--- a/archify/test/render-output-checks.test.mjs
+++ b/archify/test/render-output-checks.test.mjs
@@ -624,6 +624,67 @@ function automaticArrow(id, from, to, points, width = 1.5) {
<path data-edge-id="${id}" data-edge-from="${from}" data-edge-to="${to}" data-composition-points="${points.map((point) => point.join(',')).join(';')}" data-composition-crossover="halo" data-composition-independent="true" d="${d}" class="a-default" stroke-width="${width}" marker-end="url(#arrowhead)"/>`;
}
+function automaticWorkflowArrow(id, from, to, points) {
+ const d = points.map(([x, y], index) => `${index ? 'L' : 'M'} ${x} ${y}`).join(' ');
+ return `<path data-edge-id="${id}" data-edge-from="${from}" data-edge-to="${to}" data-composition-routing="workflow-v2-auto" data-composition-points="${points.map((point) => point.join(',')).join(';')}" d="${d}" class="a-default" marker-end="url(#arrowhead)"/>`;
+}
+
+test('render output check: automatic workflow counterflow warns in standard and fails showcase without a halo', () => {
+ const markup = automaticWorkflowArrow('admission', 'a', 'hub', [[60, 20], [60, 100]])
+ + automaticWorkflowArrow('dispatch', 'hub', 'b', [[60, 100], [60, 49], [140, 49]]);
+ for (const profile of ['standard', 'showcase']) {
+ const { code, result } = checkHtml(`workflow-counterflow-${profile}`, markup, profile);
+ assert.equal(code, profile === 'showcase' ? 1 : 0);
+ const issue = result.composition.issues.find((entry) => entry.code === 'composition/ambiguous-corridor');
+ assert.equal(issue?.severity, profile === 'showcase' ? 'error' : 'warning');
+ assert.equal(issue?.overlapLength, 51);
+ assert.deepEqual([issue?.relationship.id, issue?.otherRelationship.id], ['admission', 'dispatch']);
+ assert.deepEqual(result.composition.summary, profile === 'showcase'
+ ? { errors: 1, warnings: 0 } : { errors: 0, warnings: 1 });
+ }
+ for (const preserved of [
+ markup.replaceAll(' data-composition-routing="workflow-v2-auto"', ''),
+ markup.replace(' data-composition-routing="workflow-v2-auto"', ''),
+ markup.replaceAll('workflow-v2-auto', 'workflow-v1'),
+ ]) {
+ const { code, result } = checkHtml('workflow-authored-counterflow', preserved, 'showcase');
+ assert.equal(code, 0, JSON.stringify(result));
+ assert.equal(result.composition.metrics.ambiguousCorridors, 0);
+ }
+ const sharedTrunk = automaticWorkflowArrow('first', 'hub', 'a', [[60, 20], [60, 100]])
+ + automaticWorkflowArrow('second', 'hub', 'b', [[60, 20], [60, 70], [140, 70]]);
+ const sameDirection = checkHtml('workflow-shared-trunk', sharedTrunk, 'showcase');
+ assert.equal(sameDirection.code, 0, JSON.stringify(sameDirection.result));
+ assert.equal(sameDirection.result.composition.metrics.ambiguousCorridors, 0);
+});
+
+test('render output check: automatic workflow shared-endpoint X is checked independently of halo claims', () => {
+ const markup = automaticWorkflowArrow('first', 'a', 'hub', [[20, 20], [80, 20], [80, 80], [140, 80]])
+ + automaticWorkflowArrow('second', 'b', 'hub', [[20, 100], [120, 100], [120, 40], [140, 40]]);
+ for (const profile of ['standard', 'showcase']) {
+ const { code, result } = checkHtml(`workflow-shared-crossing-${profile}`, markup, profile);
+ assert.equal(code, profile === 'showcase' ? 1 : 0);
+ assert.equal(result.composition.metrics.properCrossings, 1);
+ assert.equal(result.composition.metrics.resolvedCrossovers, 0);
+ const issue = result.composition.issues.find((entry) => entry.code === 'composition/proper-crossing');
+ assert.equal(issue?.severity, profile === 'showcase' ? 'error' : 'warning');
+ assert.deepEqual(issue?.point, [120, 80]);
+ }
+ const mixed = checkHtml('workflow-mixed-shared-crossing', markup.replace(' data-composition-routing="workflow-v2-auto"', ''), 'showcase');
+ assert.equal(mixed.code, 0, JSON.stringify(mixed.result));
+ const falseHalo = markup.replaceAll('data-composition-routing=', 'data-composition-crossover="halo" data-composition-independent="true" data-composition-routing=');
+ const forged = checkHtml('workflow-false-halo', falseHalo, 'showcase');
+ assert.equal(forged.code, 1, 'routing provenance cannot certify an absent crossover halo');
+ assert.equal(forged.result.composition.metrics.properCrossings, 1);
+ assert.equal(forged.result.composition.metrics.resolvedCrossovers, 0);
+
+ const unrelated = markup.replace('data-edge-to="hub"', 'data-edge-to="other"');
+ const marked = checkHtml('workflow-marked-unrelated-crossing', unrelated, 'showcase');
+ const unmarked = checkHtml('workflow-unmarked-unrelated-crossing', unrelated.replaceAll(' data-composition-routing="workflow-v2-auto"', ''), 'showcase');
+ assert.equal(marked.code, 1);
+ assert.equal(unmarked.code, 1, 'an automatic marker only tightens existing crossing acceptance');
+});
+
test('render output check: independent shared-endpoint crossings still recommend visual review', () => {
const markup = automaticArrow('first', 'a', 'hub', [[20, 20], [80, 20], [80, 80], [140, 80]])
+ automaticArrow('second', 'b', 'hub', [[20, 100], [120, 100], [120, 40], [140, 40]]);
diff --git a/archify/test/workflow-compiler-hard-contract.test.mjs b/archify/test/workflow-compiler-hard-contract.test.mjs
index 1344d229..71fc7ed5 100644
--- a/archify/test/workflow-compiler-hard-contract.test.mjs
+++ b/archify/test/workflow-compiler-hard-contract.test.mjs
@@ -1469,7 +1469,13 @@ test('readable-v2 reports conflicts between two absolute label pins without dele
{ edge: 'one', field: 'labelAt' },
{ edge: 'two', field: 'labelAt' },
]);
- assertSupportedFixesNameChangedEdge(diagnostic, ['one', 'two']);
+ if (qualityProfile === 'standard') {
+ assertSupportedFixesNameChangedEdge(diagnostic, ['one', 'two']);
+ } else {
+ // Moving either label alone still leaves two fully coincident fixed
+ // routes. The stricter v2 contract must not advertise that as a repair.
+ assert.deepEqual(diagnostic.supportedFixes, []);
+ }
assert.doesNotMatch(diagnostic.supportedFixes.join('\n'), /remove (?:one |the )?label(?!At)/i);
}
});
diff --git a/archify/test/workflow-compiler.test.mjs b/archify/test/workflow-compiler.test.mjs
index 3f0a4ee6..a881714a 100644
--- a/archify/test/workflow-compiler.test.mjs
+++ b/archify/test/workflow-compiler.test.mjs
@@ -347,14 +347,17 @@ test('fixed-v1 compiler preserves the exact 700x400 compatibility geometry', ()
);
});
-test('readable-v2 preserves the checked-in workflow example when no vertical stack is authored', () => {
+test('readable-v2 separates approval branches in the checked-in workflow example', () => {
const workflow = readJson(path.join(__dirname, '..', 'examples', 'agent-tool-call.workflow.json'));
const result = compileSuccessfully(workflow);
assert.equal(result.receipt.contract, 'readable-v2');
assert.equal(
- sha256(result.svg),
- '868547656078117182c273fa15532cd7d30707030866cc5f70aba72685b95814',
+ // The only visible delta is approved-tool's source moving 12px left:
+ // approval-denied and approved-tool previously shared a mixed-style trunk.
+ // Node geometry, labels, all other paths and v1 baselines are unchanged.
+ sha256(result.svg.replace(/ data-(?:composition-routing|edge-role|layout-contract)="[^"]*"/g, '')),
+ '7a4effe6000ef4d5c8e2e933186ff225f6398d76216d916600e51f8e05a7e139',
);
});
diff --git a/archify/test/workflow-routing-clarity.test.mjs b/archify/test/workflow-routing-clarity.test.mjs
new file mode 100644
index 00000000..28a9611f
--- /dev/null
+++ b/archify/test/workflow-routing-clarity.test.mjs
@@ -0,0 +1,231 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { compileWorkflow } from '../renderers/workflow/workflow-compiler.mjs';
+
+function workflowFixture() {
+ return JSON.parse(fs.readFileSync(
+ new URL('./fixtures/workflow-routing-clarity.workflow.json', import.meta.url),
+ 'utf8',
+ ));
+}
+
+function edgeTag(svg, from, to) {
+ const tag = (svg.match(/<path\b[^>]*>/g) || []).find((candidate) => (
+ candidate.includes(`data-edge-from="${from}"`) && candidate.includes(`data-edge-to="${to}"`)
+ ));
+ assert.ok(tag, `expected rendered ${from}->${to}`);
+ return tag;
+}
+
+test('readable-v2 keeps clear adjacent routes straight without moving nodes or enlarging the canvas', () => {
+ const result = compileWorkflow({ workflow: workflowFixture(), qualityProfile: 'showcase' });
+ assert.equal(result.ok, true, JSON.stringify(result.diagnostics, null, 2));
+
+ // The reproduction already has sufficient room; routing must preserve its layout.
+ assert.deepEqual(result.receipt.viewBox, [949, 528]);
+ assert.deepEqual(result.receipt.nodes.map(({ id, x, y, width, height }) => (
+ [id, x, y, width, height]
+ )), [
+ ['request', 48, 93, 92, 52],
+ ['admit', 225.2, 93, 92, 52],
+ ['graph', 498.4, 93, 92, 52],
+ ['start', 345.2, 217, 92, 52],
+ ['turn', 498.4, 217, 92, 52],
+ ['tool', 670.8, 217, 92, 52],
+ ['resume', 828.8, 217, 92, 52],
+ ['commit', 670.8, 341, 92, 52],
+ ['project', 828.8, 341, 92, 52],
+ ]);
+
+ const adjacentRoutes = [['turn', 'tool'], ['commit', 'project']].map(([from, to]) => {
+ const edge = result.receipt.edges.find((candidate) => candidate.from === from && candidate.to === to);
+ assert.ok(edge, `expected the authored ${from}->${to} relationship`);
+ return { from, to, pointCount: edge.points.length };
+ });
+ assert.deepEqual(adjacentRoutes, [
+ { from: 'turn', to: 'tool', pointCount: 2 },
+ { from: 'commit', to: 'project', pointCount: 2 },
+ ], 'clear adjacent forward relationships should not take channel detours');
+});
+
+test('readable-v2 separates opposing routes that meet at a shared node', () => {
+ const result = compileWorkflow({ workflow: workflowFixture(), qualityProfile: 'showcase' });
+ assert.equal(result.ok, true, JSON.stringify(result.diagnostics, null, 2));
+
+ const edges = result.receipt.edges;
+ const opposingCorridors = [];
+ for (let firstIndex = 0; firstIndex < edges.length; firstIndex += 1) {
+ const first = edges[firstIndex];
+ for (const second of edges.slice(firstIndex + 1)) {
+ if (![first.from, first.to].some((id) => id === second.from || id === second.to)) continue;
+ for (let firstSegment = 0; firstSegment < first.points.length - 1; firstSegment += 1) {
+ const [a, b] = first.points.slice(firstSegment, firstSegment + 2);
+ for (let secondSegment = 0; secondSegment < second.points.length - 1; secondSegment += 1) {
+ const [c, d] = second.points.slice(secondSegment, secondSegment + 2);
+ for (const axis of [0, 1]) {
+ const fixedAxis = 1 - axis;
+ if (a[fixedAxis] !== b[fixedAxis] || c[fixedAxis] !== d[fixedAxis]
+ || a[fixedAxis] !== c[fixedAxis]) continue;
+ if ((b[axis] - a[axis]) * (d[axis] - c[axis]) >= 0) continue;
+ const overlapPx = Math.min(Math.max(a[axis], b[axis]), Math.max(c[axis], d[axis]))
+ - Math.max(Math.min(a[axis], b[axis]), Math.min(c[axis], d[axis]));
+ if (overlapPx >= 8) {
+ opposingCorridors.push({
+ first: `${first.from}->${first.to}`,
+ second: `${second.from}->${second.to}`,
+ overlapPx,
+ });
+ }
+ }
+ }
+ }
+ }
+ }
+
+ assert.deepEqual(opposingCorridors, [], 'incoming and outgoing arrows must remain distinguishable at shared nodes');
+});
+
+test('readable-v2 routing remains deterministic and preserves every authored relationship', () => {
+ const workflow = workflowFixture();
+ const before = JSON.stringify(workflow);
+ const first = compileWorkflow({ workflow, qualityProfile: 'showcase' });
+ assert.equal(first.ok, true, JSON.stringify(first.diagnostics, null, 2));
+ assert.equal(JSON.stringify(workflow), before, 'compilation must not mutate its input');
+ assert.equal(first.receipt.nodes.length, 9);
+ assert.deepEqual(
+ first.receipt.edges.map(({ from, to }) => `${from}->${to}`).sort(),
+ workflow.edges.map(({ from, to }) => `${from}->${to}`).sort(),
+ );
+
+ const reordered = workflowFixture();
+ reordered.nodes.reverse();
+ reordered.edges.reverse();
+ for (const document of [workflow, reordered]) {
+ const repeated = compileWorkflow({ workflow: document, qualityProfile: 'showcase' });
+ assert.equal(repeated.ok, true, JSON.stringify(repeated.diagnostics, null, 2));
+ assert.deepEqual(repeated.receipt, first.receipt);
+ assert.equal(repeated.svg, first.svg);
+ }
+});
+
+test('readable-v2 preserves authored sides, routes, channels, vias, and label positions', () => {
+ const cases = [
+ { fromSide: 'right', toSide: 'left' },
+ { route: 'straight' },
+ { route: 'bottom-channel' },
+ { channelY: 425 },
+ { via: [[716.8, 425], [836.8, 425]], fromSide: 'bottom', toSide: 'bottom' },
+ { labelAt: [776.8, 415] },
+ ];
+ for (const authored of cases) {
+ const workflow = workflowFixture();
+ Object.assign(workflow.edges.find(({ from, to }) => from === 'commit' && to === 'project'), authored);
+ const result = compileWorkflow({ workflow, qualityProfile: 'showcase' });
+ assert.equal(result.ok, true, JSON.stringify({ authored, diagnostics: result.diagnostics }, null, 2));
+ const edge = result.receipt.edges.find(({ from, to }) => from === 'commit' && to === 'project');
+ const source = result.receipt.nodes.find(({ id }) => id === 'commit');
+ const target = result.receipt.nodes.find(({ id }) => id === 'project');
+ assert.doesNotMatch(edgeTag(result.svg, 'commit', 'project'), /data-composition-routing=/);
+ assert.match(edgeTag(result.svg, 'request', 'admit'), /data-composition-routing="workflow-v2-auto"/);
+ if (authored.fromSide === 'right') assert.equal(edge.points[0][0], source.x + source.width);
+ if (authored.toSide === 'left') assert.equal(edge.points.at(-1)[0], target.x);
+ if (authored.fromSide === 'bottom') assert.equal(edge.points[0][1], source.y + source.height);
+ if (authored.toSide === 'bottom') assert.equal(edge.points.at(-1)[1], target.y + target.height);
+ if (authored.route === 'straight') assert.equal(edge.points.length, 2);
+ if (authored.route === 'bottom-channel') {
+ assert.ok(edge.points.slice(1, -1).every(([, y]) => y > Math.max(source.y + source.height, target.y + target.height)));
+ }
+ if (authored.channelY !== undefined) {
+ assert.ok(edge.points.some((point, index) => index > 0 && point[1] === authored.channelY
+ && edge.points[index - 1][1] === authored.channelY));
+ }
+ if (authored.via) assert.deepEqual(edge.points.slice(1, -1), authored.via);
+ if (authored.labelAt) {
+ const label = result.receipt.labels.find(({ label: text }) => text === 'projection');
+ assert.deepEqual([label.x, label.y], authored.labelAt);
+ }
+ }
+});
+
+test('fixed-v1 stays outside the automatic workflow routing contract', () => {
+ const workflow = JSON.parse(fs.readFileSync(
+ new URL('./fixtures/v1-baseline/agent-tool-call.workflow.json', import.meta.url),
+ 'utf8',
+ ));
+ const result = compileWorkflow({ workflow, qualityProfile: 'standard' });
+ assert.equal(result.ok, true, JSON.stringify(result.diagnostics, null, 2));
+ assert.equal(result.receipt.contract, 'fixed-v1');
+ assert.deepEqual(result.receipt.viewBox, [720, 900]);
+ assert.equal(result.receipt.edges.length, workflow.edges.length);
+ assert.doesNotMatch(result.svg, /data-composition-routing="workflow-v2-auto"/);
+});
+
+test('readable-v2 keeps emphasis and wide-arrow fan-in marker bounds disjoint', () => {
+ for (const width of [undefined, 6]) {
+ const workflow = {
+ schema_version: 2,
+ diagram_type: 'workflow',
+ meta: { title: 'Shared destination', output: 'shared-destination.html', legend: { mode: 'hidden' } },
+ lanes: ['a', 'b', 'c'].map((id) => ({ id, label: id.toUpperCase() })),
+ nodes: ['a', 'b', 'c'].map((id) => ({
+ id, lane: id, col: id === 'c' ? 2 : 0, type: 'backend', label: id.toUpperCase(),
+ })),
+ edges: ['a', 'b'].map((from) => ({
+ from, to: 'c', variant: 'emphasis', ...(width === undefined ? {} : { width }),
+ })),
+ };
+ const result = compileWorkflow({ workflow, qualityProfile: 'showcase' });
+ assert.equal(result.ok, true, JSON.stringify(result.diagnostics, null, 2));
+ const destination = result.receipt.nodes.find(({ id }) => id === 'c');
+ const topRoute = result.receipt.edges.find(({ from }) => from === 'a').points;
+ const leftRoute = result.receipt.edges.find(({ from }) => from === 'b').points;
+ const topTip = topRoute.at(-1);
+ const leftTip = leftRoute.at(-1);
+ assert.deepEqual(topTip, [destination.x + destination.width / 2, destination.y]);
+ assert.equal(topRoute.at(-2)[0], topTip[0]);
+ assert.ok(topRoute.at(-2)[1] < topTip[1], 'the top arrow arrives downward');
+ // The bundled 10x7 marker has refX=9: these perpendicular marker bounds
+ // remain disjoint even with a 6px stroke, without relying on router helpers.
+ const strokeWidth = width ?? 1.8;
+ if (leftTip[1] === destination.y) {
+ assert.equal(leftRoute.at(-2)[0], leftTip[0]);
+ assert.ok(leftRoute.at(-2)[1] < leftTip[1]);
+ assert.ok(Math.abs(topTip[0] - leftTip[0]) >= 7 * strokeWidth,
+ 'parallel arrivals must have non-overlapping marker bounds');
+ } else {
+ assert.deepEqual(leftTip, [destination.x, destination.y + destination.height / 2]);
+ assert.equal(leftRoute.at(-2)[1], leftTip[1]);
+ assert.ok(leftRoute.at(-2)[0] < leftTip[0]);
+ assert.ok(topTip[0] - 3.5 * strokeWidth > leftTip[0] + strokeWidth,
+ 'the top marker must remain to the right of the left marker');
+ }
+ }
+});
+
+test('public validate and rendered HTML agree on automatic workflow routing', (t) => {
+ const cli = fileURLToPath(new URL('../bin/archify.mjs', import.meta.url));
+ const input = fileURLToPath(new URL('./fixtures/workflow-routing-clarity.workflow.json', import.meta.url));
+ const validation = spawnSync(process.execPath, [cli, 'validate', 'workflow', input, '--quality', 'showcase', '--json'], { encoding: 'utf8' });
+ assert.equal(validation.status, 0, validation.stderr || validation.stdout);
+ const receipt = JSON.parse(validation.stdout);
+ assert.equal(receipt.ok, true);
+ assert.ok(receipt.checks.length > 0);
+ assert.ok(receipt.checks.every(({ ok }) => ok));
+
+ const directory = fs.mkdtempSync(path.join(os.tmpdir(), 'archify-routing-clarity-'));
+ t.after(() => fs.rmSync(directory, { recursive: true, force: true }));
+ const output = path.join(directory, 'workflow.html');
+ const rendered = spawnSync(process.execPath, [cli, 'render', 'workflow', input, output, '--quality', 'showcase'], { encoding: 'utf8' });
+ assert.equal(rendered.status, 0, rendered.stderr || rendered.stdout);
+ const html = fs.readFileSync(output, 'utf8');
+ assert.equal((html.match(/data-composition-routing="workflow-v2-auto"/g) || []).length, 11);
+ const checked = spawnSync(process.execPath, [cli, 'check', output, '--json'], { encoding: 'utf8' });
+ assert.equal(checked.status, 0, checked.stderr || checked.stdout);
+ assert.equal(JSON.parse(checked.stdout).ok, true);
+});
diff --git a/archify/test/workflow-shared-trunks.test.mjs b/archify/test/workflow-shared-trunks.test.mjs
new file mode 100644
index 00000000..2c421e72
--- /dev/null
+++ b/archify/test/workflow-shared-trunks.test.mjs
@@ -0,0 +1,158 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { compileWorkflow } from '../renderers/workflow/workflow-compiler.mjs';
+
+const checker = fileURLToPath(new URL('../scripts/check-render-output.mjs', import.meta.url));
+
+test('workflow v2 separates long trunks without changing authored return geometry', () => {
+ const workflow = JSON.parse(fs.readFileSync(new URL('./fixtures/workflow-shared-trunks.workflow.json', import.meta.url)));
+ const result = compileWorkflow({ workflow, qualityProfile: 'showcase' });
+ assert.equal(result.ok, true, JSON.stringify(result.diagnostics));
+ const edge = id => result.receipt.edges.find(e => e.id === id).points;
+ const returnPoints = edge('continue-work');
+ assert.ok(returnPoints.some((p,i) => i && p[1] === 180 && returnPoints[i-1][1] === 180));
+ assert.notDeepEqual(edge('model-turn').at(-1), returnPoints.at(-1), 'incoming main and return arrows need separate ports');
+ assert.notDeepEqual(edge('finish')[0], returnPoints[0], 'outgoing main and return paths need separate ports');
+ assert.notDeepEqual(edge('direct-answer')[0], edge('ordinary-work')[0], 'independent branch paths need separate ports');
+});
+
+test('automatic routing respects a fixed return even when its ID sorts last', () => {
+ const workflow = JSON.parse(fs.readFileSync(new URL('./fixtures/workflow-shared-trunks.workflow.json', import.meta.url)));
+ workflow.edges.find(e=>e.id==='continue-work').id='zz-return';
+ const result=compileWorkflow({workflow,qualityProfile:'showcase'});
+ assert.equal(result.ok,true,JSON.stringify(result.diagnostics));
+});
+
+function checkSvg(t, body, profile = 'showcase', contract = 'readable-v2') {
+ const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'archify-shared-trunks-'));
+ t.after(() => fs.rmSync(dir, { recursive: true, force: true }));
+ const file = path.join(dir, 'diagram.html');
+ fs.writeFileSync(file, `<html><body><svg viewBox="0 0 400 240" data-diagram-type="workflow" data-layout-contract="${contract}" data-quality-profile="${profile}">${body}</svg></body></html>`);
+ const result = spawnSync(process.execPath, [checker, file], { encoding: 'utf8' });
+ return { code: result.status, receipt: JSON.parse(result.stdout) };
+}
+
+test('workflow v2 artifact reports a long mixed-style shared endpoint even for explicit paths', (t) => {
+ const body = `
+ <path data-edge-id="return" data-edge-from="result" data-edge-to="decision" data-edge-role="return" d="M 200 180 L 200 40 L 40 40 L 40 180" class="a-dashed" stroke-width="1.4" marker-end="url(#arrowhead-dashed)"/>
+ <path data-edge-id="finish" data-edge-from="result" data-edge-to="reply" data-edge-role="main" d="M 200 180 L 200 80 L 300 80" class="a-emphasis" stroke-width="1.8" marker-end="url(#arrowhead-emphasis)"/>`;
+ const result = checkSvg(t, body);
+ assert.equal(result.code, 1, 'showcase must not accept the 100px overlap');
+ const issue = result.receipt.composition.issues.find(x => x.code === 'composition/ambiguous-corridor');
+ assert.equal(issue?.overlapLength, 100);
+ assert.equal(issue?.severity, 'error');
+});
+
+test('workflow v2 allows only compatible short terminal merges, including the 24px boundary', (t) => {
+ for (const length of [16, 23, 24, 24.00005, 24.001, 25]) {
+ for (const variant of ['dashed', 'emphasis']) {
+ const result = checkSvg(t, `
+ <path data-edge-from="a" data-edge-to="result" data-edge-role="async" d="M 40 100 L 200 100" class="a-dashed" stroke-width="1.4" marker-end="url(#arrowhead-dashed)"/>
+ <path data-edge-from="b" data-edge-to="result" data-edge-role="async" d="M ${200-length} 180 L ${200-length} 100 L 200 100" class="a-${variant}" stroke-width="1.4" marker-end="url(#arrowhead-${variant})"/>`);
+ const collisions = result.receipt.composition.issues.filter(x => x.code === 'composition/ambiguous-corridor');
+ assert.equal(collisions.length, length <= 24.0001 && variant === 'dashed' ? 0 : 1, `${length}/${variant}`);
+ }
+ }
+});
+
+test('workflow v2 rejects mismatched roles, widths, nonterminal and opposing short shared segments', (t) => {
+ const base='<path data-edge-from="a" data-edge-to="result" data-edge-role="async" d="M 40 100 L 200 100" class="a-dashed" stroke-width="1.4" marker-end="url(#arrowhead-dashed)"/>';
+ for (const [name,from,to,role,width,route] of [
+ ['role','b','result','return',1.4,'M 184 180 L 184 100 L 200 100'],
+ ['width','b','result','async',2,'M 184 180 L 184 100 L 200 100'],
+ ['interior','b','result','async',1.4,'M 100 180 L 100 100 L 116 100 L 116 40 L 200 40'],
+ ['opposing','result','a','async',1.4,'M 200 100 L 184 100 L 184 180'],
+ ]) {
+ const checked=checkSvg(t,base+`<path data-edge-from="${from}" data-edge-to="${to}" data-edge-role="${role}" d="${route}" class="a-dashed" stroke-width="${width}" marker-end="url(#arrowhead-dashed)"/>`);
+ assert.equal(checked.receipt.composition.metrics.ambiguousCorridors,1,name);
+ }
+});
+
+test('workflow v2 warns in standard while v1 keeps its authored shared-endpoint contract', (t) => {
+ const body='<path data-edge-from="a" data-edge-to="b" d="M 40 100 L 200 100" class="a-default" marker-end="url(#arrowhead)"/><path data-edge-from="a" data-edge-to="c" d="M 40 100 L 200 100 L 200 180" class="a-default" marker-end="url(#arrowhead)"/>';
+ const standard=checkSvg(t,body,'standard');
+ assert.equal(standard.code,0);
+ assert.equal(standard.receipt.composition.issues.find(x=>x.code==='composition/ambiguous-corridor')?.severity,'warning');
+ const legacy=checkSvg(t,body,'showcase','fixed-v1');
+ assert.equal(legacy.code,0);
+ assert.equal(legacy.receipt.composition.metrics.ambiguousCorridors,0);
+});
+
+test('shared-trunk routing is deterministic under repeated and reordered input', () => {
+ const workflow=JSON.parse(fs.readFileSync(new URL('./fixtures/workflow-shared-trunks.workflow.json',import.meta.url)));
+ const before=JSON.stringify(workflow);
+ const first=compileWorkflow({workflow,qualityProfile:'showcase'});
+ assert.equal(first.ok,true);
+ const second=compileWorkflow({workflow,qualityProfile:'showcase'});
+ assert.equal(JSON.stringify(workflow),before);
+ assert.deepEqual(second,first);
+ workflow.edges.reverse();workflow.nodes.reverse();
+ assert.deepEqual(compileWorkflow({workflow,qualityProfile:'showcase'}),first);
+});
+
+test('workflow v2 detects arrow collisions even without coincident centerlines', (t) => {
+ const result = checkSvg(t, `
+ <path data-edge-from="a" data-edge-to="result" d="M 40 80 L 200 80" class="a-emphasis" stroke-width="6" marker-end="url(#arrowhead-emphasis)"/>
+ <path data-edge-from="b" data-edge-to="result" d="M 40 100 L 200 100" class="a-emphasis" stroke-width="6" marker-end="url(#arrowhead-emphasis)"/>`);
+ assert.equal(result.code, 1);
+ assert.equal(result.receipt.composition.metrics.arrowheadCollisions, 1);
+});
+
+test('workflow compiler diagnoses fixed shared trunks without overriding the authored paths', () => {
+ const workflow = {
+ schema_version: 2, diagram_type: 'workflow', meta: { title: 'Pinned fork', output: 'fork.html' },
+ lanes: [{ id: 'top', label: 'Top' }, { id: 'bottom', label: 'Bottom' }],
+ nodes: [
+ { id: 'a', lane: 'top', col: 0, type: 'backend', label: 'A' },
+ { id: 'b', lane: 'bottom', col: 1, type: 'backend', label: 'B' },
+ { id: 'c', lane: 'bottom', col: 2, type: 'backend', label: 'C' },
+ ],
+ edges: ['b','c'].map(to=>({id:to,from:'a',to,fromSide:'bottom',toSide:'top',channelY:180,variant:to==='b'?'dashed':'emphasis'})),
+ };
+ const standard = compileWorkflow({workflow,qualityProfile:'standard'});
+ assert.equal(standard.ok,true,JSON.stringify(standard));
+ assert.equal(standard.receipt.diagnostics.find(d=>d.code==='composition/ambiguous-corridor')?.severity,'warning');
+ const showcase = compileWorkflow({workflow,qualityProfile:'showcase'});
+ assert.equal(showcase.ok,false);
+ const issue=showcase.diagnostics.find(d=>d.code==='composition/ambiguous-corridor');
+ assert.equal(issue?.severity,'error');
+ assert.ok(issue.evidence.overlapLengthPx>24);
+ assert.ok(issue.supportedFixes.length);
+});
+
+test('workflow v2 checker measures actual strokes, not stale composition point metadata', (t) => {
+ const result=checkSvg(t, `
+ <path data-edge-from="a" data-edge-to="b" data-composition-points="40,40;180,40" d="M 40 100 L 180 100" class="a-default" marker-end="url(#arrowhead)"/>
+ <path data-edge-from="a" data-edge-to="c" data-composition-points="40,60;180,60" d="M 40 100 L 180 100 L 180 180" class="a-default" marker-end="url(#arrowhead)"/>`);
+ assert.equal(result.receipt.composition.metrics.ambiguousCorridors,1);
+});
+
+test('workflow v2 does not exempt proper crossings between explicit paths sharing a node', (t) => {
+ const result=checkSvg(t,`
+ <path data-edge-from="a" data-edge-to="b" d="M 40 100 L 150 100 L 150 20 L 220 20" class="a-default" marker-end="url(#arrowhead)"/>
+ <path data-edge-from="a" data-edge-to="c" d="M 40 100 L 40 60 L 220 60 L 220 180" class="a-default" marker-end="url(#arrowhead)"/>`);
+ assert.equal(result.receipt.composition.metrics.properCrossings,1);
+});
+
+test('compiler and artifact checks both report independent shared arrowheads', (t) => {
+ const workflow = {
+ schema_version:2, diagram_type:'workflow', meta:{title:'Pinned arrivals',output:'arrivals.html'},
+ lanes:[{id:'top',label:'Top'},{id:'bottom',label:'Bottom'}],
+ nodes:[
+ {id:'a',lane:'top',col:0,type:'backend',label:'A'},
+ {id:'b',lane:'top',col:1,type:'backend',label:'B'},
+ {id:'c',lane:'bottom',col:2,type:'backend',label:'C'},
+ ],
+ edges:['a','b'].map(from=>({id:from,from,to:'c',fromSide:'bottom',toSide:'top',channelY:180,variant:from==='a'?'emphasis':'dashed'})),
+ };
+ const result=compileWorkflow({workflow,qualityProfile:'standard'});
+ assert.equal(result.ok,true,JSON.stringify(result));
+ assert.equal(result.receipt.diagnostics.filter(d=>d.code==='composition/arrowhead-collision').length,1);
+ const checked=checkSvg(t,result.svg.replace(/^[\s\S]*?<svg[^>]*>/,'').replace(/<\/svg>\s*$/,''),'standard');
+ assert.equal(checked.receipt.composition.metrics.arrowheadCollisions,1);
+});
diff --git a/docs/assets/archify-live-proof.gif b/docs/assets/archify-live-proof.gif
index 3b3e0300..3233aa7b 100644
Binary files a/docs/assets/archify-live-proof.gif and b/docs/assets/archify-live-proof.gif differ
diff --git a/docs/assets/archify-live-proof.json b/docs/assets/archify-live-proof.json
index 5196bc91..7a191f87 100644
--- a/docs/assets/archify-live-proof.json
+++ b/docs/assets/archify-live-proof.json
@@ -7,13 +7,13 @@
"fps": 10,
"frameCount": 54,
"durationSeconds": 5.4,
- "bytes": 1656984,
- "sha256": "514b77f5097499f743855cf211046eb9f5291f9b6fdde05cc9a2ab8372b165c8",
+ "bytes": 1638856,
+ "sha256": "d728e609160aa9551306d89e1c0887fccc979784bb5022c6a53398285d3155b4",
"scenes": [
{
"id": "signal-flow",
"artifact": "docs/gallery/artifacts/agent-tool-call.workflow.html",
- "artifactSha256": "c7c09a3d5224721a7b0e45800ba02bfcec51fe38a7b388aa162a9273d7e50286",
+ "artifactSha256": "8be7063620cf3d1adb65e6d5710b0950bd86cd1798376a88fc6ab74844712314",
"view": "happy-path",
"eyebrow": "WORKFLOW · SIGNAL FLOW",
"title": "Agent Tool Call",
diff --git a/docs/assets/workflow-routing-clarity/maka-after.png b/docs/assets/workflow-routing-clarity/maka-after.png
new file mode 100644
index 00000000..9e00b4dd
Binary files /dev/null and b/docs/assets/workflow-routing-clarity/maka-after.png differ
diff --git a/docs/assets/workflow-routing-clarity/maka-before.png b/docs/assets/workflow-routing-clarity/maka-before.png
new file mode 100644
index 00000000..b31f9ed2
Binary files /dev/null and b/docs/assets/workflow-routing-clarity/maka-before.png differ
diff --git a/docs/assets/workflow-routing-clarity/openpi-after.png b/docs/assets/workflow-routing-clarity/openpi-after.png
new file mode 100644
index 00000000..48cef8d3
Binary files /dev/null and b/docs/assets/workflow-routing-clarity/openpi-after.png differ
diff --git a/docs/assets/workflow-routing-clarity/openpi-before.png b/docs/assets/workflow-routing-clarity/openpi-before.png
new file mode 100644
index 00000000..9877bd86
Binary files /dev/null and b/docs/assets/workflow-routing-clarity/openpi-before.png differ
diff --git a/docs/gallery.html b/docs/gallery.html
index 48ba65e9..1b62e981 100644
--- a/docs/gallery.html
+++ b/docs/gallery.html
@@ -298,7 +298,7 @@
<div class="receipt-cell"><span class="receipt-label">Artifact</span><span class="receipt-value ok">9/9 pass</span></div>
<div class="receipt-cell"><span class="receipt-label">Composition</span><span class="receipt-value ok" title="0 crossings · 0 border runs · 0 micro segments · 0 cramped turns">SHOWCASE · PASS</span></div>
<div class="receipt-cell"><span class="receipt-label">Graph</span><span class="receipt-value">12N · 11E</span></div>
- <div class="receipt-cell"><span class="receipt-label">SHA-256</span><span class="receipt-value" title="c7c09a3d5224721a7b0e45800ba02bfcec51fe38a7b388aa162a9273d7e50286">c7c09a3d5224</span></div>
+ <div class="receipt-cell"><span class="receipt-label">SHA-256</span><span class="receipt-value" title="8be7063620cf3d1adb65e6d5710b0950bd86cd1798376a88fc6ab74844712314">8be7063620cf</span></div>
</div>
<div class="card-actions">
<a class="card-link primary" href="gallery/artifacts/agent-tool-call.workflow.html?present=1&amp;play=1#view=happy-path" target="_blank" rel="noopener" data-en="Play named chapter ↗" data-zh="播放命名章节 ↗">Play named chapter ↗</a>
@@ -675,8 +675,8 @@ receipt 99 checks / 11 artifacts / deterministic hashes</pre>
"engineeringProfile": null,
"nodeCount": 12,
"edgeCount": 11,
- "artifactBytes": 845486,
- "artifactSha256": "c7c09a3d5224721a7b0e45800ba02bfcec51fe38a7b388aa162a9273d7e50286",
+ "artifactBytes": 846132,
+ "artifactSha256": "8be7063620cf3d1adb65e6d5710b0950bd86cd1798376a88fc6ab74844712314",
"sourceBytes": 5687,
"sourceSha256": "4d3f6c23de2ca7d306e05d0041a9506833bb5a164a2bddc2d1984cf4da3ee90c",
"checks": [
diff --git a/docs/gallery/artifacts/agent-tool-call.workflow.html b/docs/gallery/artifacts/agent-tool-call.workflow.html
index bd6f7ea4..66d6a50b 100644
--- a/docs/gallery/artifacts/agent-tool-call.workflow.html
+++ b/docs/gallery/artifacts/agent-tool-call.workflow.html
@@ -5240,7 +5240,7 @@ OTHER DEALINGS IN THE FONT SOFTWARE.
<!-- Main Diagram -->
<div class="diagram-container" data-detail-level="read"
data-preset-badge-editorial-plate="ARCHIFY / PLATE 04">
- <svg viewBox="0 0 1096 684" role="img" lang="en" aria-labelledby="archify-diagram-title archify-diagram-description" data-animation="trace" data-preset="signal-flow" data-quality-profile="showcase">
+ <svg viewBox="0 0 1096 684" data-layout-contract="readable-v2" role="img" lang="en" aria-labelledby="archify-diagram-title archify-diagram-description" data-animation="trace" data-preset="signal-flow" data-quality-profile="showcase">
<title id="archify-diagram-title">Agent Tool Call Workflow</title>
<desc id="archify-diagram-description">A workflow diagram generated by Archify.</desc>
<!-- Definitions -->
@@ -5301,17 +5301,17 @@ OTHER DEALINGS IN THE FONT SOFTWARE.
<text x="770" y="482" class="t-messagebus" font-size="7" font-weight="600">Tool work</text>
<!-- Edge paths -->
- <path data-edge-from="router" data-edge-to="approval" data-edge-label="needs approval?" data-edge-key="0" data-edge-id="approval-check" data-composition-points="651.2,279;651.2,302;569.2,302;569.2,387;585.2,387" d="M 651.2 279 L 651.2 302 L 569.2 302 L 569.2 387 L 585.2 387" class="a-security" data-animate="edge" style="--step:3" stroke-width="1.4" marker-end="url(#arrowhead-security)"/>
- <path data-edge-from="approval" data-edge-to="blocked" data-edge-label="denied" data-edge-key="1" data-edge-id="approval-denied" data-composition-points="651.2,421;651.2,442;830,442;830,413" d="M 651.2 421 L 651.2 442 L 830 442 L 830 413" class="a-security" data-animate="edge" style="--step:9" stroke-width="1.4" marker-end="url(#arrowhead-security)"/>
- <path data-edge-from="approval" data-edge-to="tool" data-edge-key="2" data-edge-id="approved-tool" data-composition-points="651.2,421;651.2,521;764,521" d="M 651.2 421 L 651.2 521 L 764 521" class="a-emphasis" data-animate="edge" style="--step:4" stroke-width="1.8" marker-end="url(#arrowhead-emphasis)"/>
- <path data-edge-from="external" data-edge-to="final" data-edge-key="3" data-edge-id="external-reply" data-composition-points="1056,521;1080,521;1080,120;1056,120" d="M 1056 521 L 1080 521 L 1080 120 L 1056 120" class="a-emphasis" data-animate="edge" style="--step:6" stroke-width="1.2" marker-end="url(#arrowhead-emphasis)"/>
- <path data-edge-from="chat" data-edge-to="planner" data-edge-label="plan" data-edge-key="4" data-edge-id="plan-request" data-composition-points="274,146;274,253;425.2,253" d="M 274 146 L 274 253 L 425.2 253" class="a-emphasis" data-animate="edge" style="--step:1" stroke-width="1.8" marker-end="url(#arrowhead-emphasis)"/>
- <path data-edge-from="planner" data-edge-to="router" data-edge-key="5" data-edge-id="planner-route" data-composition-points="557.2,253;585.2,253" d="M 557.2 253 L 585.2 253" class="a-default" data-animate="edge" style="--step:2" stroke-width="1.4" marker-end="url(#arrowhead)"/>
- <path data-edge-from="external" data-edge-to="trace" data-edge-label="record result" data-edge-key="6" data-edge-id="record-result" data-composition-points="990,547;990,579;491.2,579;491.2,547" d="M 990 547 L 990 579 L 491.2 579 L 491.2 547" class="a-dashed" data-animate="edge" style="--step:12" stroke-width="1.4" marker-end="url(#arrowhead-dashed)"/>
- <path data-edge-from="user" data-edge-to="chat" data-edge-key="7" data-edge-id="request-chat" data-composition-points="180,120;208,120" d="M 180 120 L 208 120" class="a-default" data-animate="edge" style="--step:0" stroke-width="1.4" marker-end="url(#arrowhead)"/>
- <path data-edge-from="blocked" data-edge-to="retry" data-edge-key="8" data-edge-id="retry-request" data-composition-points="896,387;924,387" d="M 896 387 L 924 387" class="a-dashed" data-animate="edge" style="--step:12" stroke-width="1.4" marker-end="url(#arrowhead-dashed)"/>
- <path data-edge-from="tool" data-edge-to="external" data-edge-key="9" data-edge-id="tool-external-call" data-composition-points="896,521;924,521" d="M 896 521 L 924 521" class="a-default" data-animate="edge" style="--step:5" stroke-width="1.4" marker-end="url(#arrowhead)"/>
- <path data-edge-from="store" data-edge-to="trace" data-edge-label="trace + memory" data-edge-key="10" data-edge-id="write-trace-memory" data-composition-points="340,521;425.2,521" d="M 340 521 L 425.2 521" class="a-dashed" data-animate="edge" style="--step:12" stroke-width="1.4" marker-end="url(#arrowhead-dashed)"/>
+ <path data-edge-from="router" data-edge-to="approval" data-edge-label="needs approval?" data-edge-key="0" data-edge-id="approval-check" data-composition-routing="workflow-v2-auto" data-edge-role="" data-composition-points="651.2,279;651.2,302;569.2,302;569.2,387;585.2,387" d="M 651.2 279 L 651.2 302 L 569.2 302 L 569.2 387 L 585.2 387" class="a-security" data-animate="edge" style="--step:3" stroke-width="1.4" marker-end="url(#arrowhead-security)"/>
+ <path data-edge-from="approval" data-edge-to="blocked" data-edge-label="denied" data-edge-key="1" data-edge-id="approval-denied" data-composition-routing="workflow-v2-auto" data-edge-role="error" data-composition-points="651.2,421;651.2,442;830,442;830,413" d="M 651.2 421 L 651.2 442 L 830 442 L 830 413" class="a-security" data-animate="edge" style="--step:9" stroke-width="1.4" marker-end="url(#arrowhead-security)"/>
+ <path data-edge-from="approval" data-edge-to="tool" data-edge-key="2" data-edge-id="approved-tool" data-composition-routing="workflow-v2-auto" data-edge-role="" data-composition-points="639.2,421;639.2,521;764,521" d="M 639.2 421 L 639.2 521 L 764 521" class="a-emphasis" data-animate="edge" style="--step:4" stroke-width="1.8" marker-end="url(#arrowhead-emphasis)"/>
+ <path data-edge-from="external" data-edge-to="final" data-edge-key="3" data-edge-id="external-reply" data-edge-role="return" data-composition-points="1056,521;1080,521;1080,120;1056,120" d="M 1056 521 L 1080 521 L 1080 120 L 1056 120" class="a-emphasis" data-animate="edge" style="--step:6" stroke-width="1.2" marker-end="url(#arrowhead-emphasis)"/>
+ <path data-edge-from="chat" data-edge-to="planner" data-edge-label="plan" data-edge-key="4" data-edge-id="plan-request" data-composition-routing="workflow-v2-auto" data-edge-role="" data-composition-points="274,146;274,253;425.2,253" d="M 274 146 L 274 253 L 425.2 253" class="a-emphasis" data-animate="edge" style="--step:1" stroke-width="1.8" marker-end="url(#arrowhead-emphasis)"/>
+ <path data-edge-from="planner" data-edge-to="router" data-edge-key="5" data-edge-id="planner-route" data-composition-routing="workflow-v2-auto" data-edge-role="" data-composition-points="557.2,253;585.2,253" d="M 557.2 253 L 585.2 253" class="a-default" data-animate="edge" style="--step:2" stroke-width="1.4" marker-end="url(#arrowhead)"/>
+ <path data-edge-from="external" data-edge-to="trace" data-edge-label="record result" data-edge-key="6" data-edge-id="record-result" data-edge-role="" data-composition-points="990,547;990,579;491.2,579;491.2,547" d="M 990 547 L 990 579 L 491.2 579 L 491.2 547" class="a-dashed" data-animate="edge" style="--step:12" stroke-width="1.4" marker-end="url(#arrowhead-dashed)"/>
+ <path data-edge-from="user" data-edge-to="chat" data-edge-key="7" data-edge-id="request-chat" data-composition-routing="workflow-v2-auto" data-edge-role="" data-composition-points="180,120;208,120" d="M 180 120 L 208 120" class="a-default" data-animate="edge" style="--step:0" stroke-width="1.4" marker-end="url(#arrowhead)"/>
+ <path data-edge-from="blocked" data-edge-to="retry" data-edge-key="8" data-edge-id="retry-request" data-composition-routing="workflow-v2-auto" data-edge-role="branch" data-composition-points="896,387;924,387" d="M 896 387 L 924 387" class="a-dashed" data-animate="edge" style="--step:12" stroke-width="1.4" marker-end="url(#arrowhead-dashed)"/>
+ <path data-edge-from="tool" data-edge-to="external" data-edge-key="9" data-edge-id="tool-external-call" data-composition-routing="workflow-v2-auto" data-edge-role="" data-composition-points="896,521;924,521" d="M 896 521 L 924 521" class="a-default" data-animate="edge" style="--step:5" stroke-width="1.4" marker-end="url(#arrowhead)"/>
+ <path data-edge-from="store" data-edge-to="trace" data-edge-label="trace + memory" data-edge-key="10" data-edge-id="write-trace-memory" data-composition-routing="workflow-v2-auto" data-edge-role="" data-composition-points="340,521;425.2,521" d="M 340 521 L 425.2 521" class="a-dashed" data-animate="edge" style="--step:12" stroke-width="1.4" marker-end="url(#arrowhead-dashed)"/>
<!-- Nodes -->
<g id="node-user" data-node-id="user" data-node-label="User" tabindex="0" role="button" aria-label="Focus User, asks for work, User Interface › Intake" aria-pressed="false" data-node-kind="external" data-node-sublabel="asks for work" data-node-context="User Interface › Intake">
diff --git a/docs/gallery/manifest.json b/docs/gallery/manifest.json
index 604449c3..925e90da 100644
--- a/docs/gallery/manifest.json
+++ b/docs/gallery/manifest.json
@@ -27,8 +27,8 @@
"engineeringProfile": null,
"nodeCount": 12,
"edgeCount": 11,
- "artifactBytes": 845486,
- "artifactSha256": "c7c09a3d5224721a7b0e45800ba02bfcec51fe38a7b388aa162a9273d7e50286",
+ "artifactBytes": 846132,
+ "artifactSha256": "8be7063620cf3d1adb65e6d5710b0950bd86cd1798376a88fc6ab74844712314",
"sourceBytes": 5687,
"sourceSha256": "4d3f6c23de2ca7d306e05d0041a9506833bb5a164a2bddc2d1984cf4da3ee90c",
"checks": [
diff --git a/docs/specs/workflow-routing-clarity-validation.md b/docs/specs/workflow-routing-clarity-validation.md
new file mode 100644
index 00000000..ae1e01fb
--- /dev/null
+++ b/docs/specs/workflow-routing-clarity-validation.md
@@ -0,0 +1,92 @@
+# Workflow routing clarity: scope and validation
+
+## Scope
+
+Workflow v2 routes sharing a node must remain distinguishable: long shared
+corridors, mixed-style/counterflow overlaps and colliding arrowheads are not
+exempt merely because edges share an endpoint. Compatible terminal stubs of at
+most 24 SVG units remain allowed. Fixed route coordinates remain authoritative;
+automatic routes use separate ports and bounded local repair (one pass, at most
+eight seed plans, offsets of ±16/±32).
+
+Compiler and final-HTML checking share the classifier; readable v2 HTML is
+checked from its actual path geometry rather than stale composition metadata.
+Standard reports warnings, showcase reports failures. Workflow v1 and the
+default geometry policy used by other diagram types remain unchanged. No new
+schema fields, dependencies, layout engine or version changes are introduced.
+
+## User-provided end-to-end comparisons
+
+| Project | Before | After |
+| --- | --- | --- |
+| Maka | ![Maka before](../assets/workflow-routing-clarity/maka-before.png) | ![Maka after](../assets/workflow-routing-clarity/maka-after.png) |
+| OpenPI | ![OpenPI before](../assets/workflow-routing-clarity/openpi-before.png) | ![OpenPI after](../assets/workflow-routing-clarity/openpi-after.png) |
+
+These original screenshots are qualitative end-to-end examples, **not a
+controlled same-input routing benchmark**. Labels, authored layout and topology
+also changed. In particular, OpenPI before shows workflow-runtime internals,
+whereas after shows the broader task-orchestration overview. The entire visual
+difference must not be attributed to routing alone. Private project source and
+local delivery artifacts are not included in this PR.
+
+## Fixed-input acceptance evidence
+
+The prior implementation acceptance used base commit `1c1e47ad` plus the
+first-round changes as its second-round baseline. Same-input OpenPI comparison:
+9 nodes and 13 edges retained; node geometry, 1210×776 canvas and authored
+channelY=180 unchanged. Three long overlaps of 113/113/98 SVG units became zero;
+proper crossings, ambiguous corridors, arrowhead collisions and label-clearance
+issues were zero. Maximum bends decreased from 3 to 2; maximum stretch stayed
+1.64. Public, sanitized regressions are checked in as
+`archify/test/workflow-routing-clarity.test.mjs` and
+`archify/test/workflow-shared-trunks.test.mjs`, with their matching fixtures.
+
+Prior focused checks: 279 passed. Prior complete `env -u ARCHIFY_CHROME npm test`
+from `archify/`: 2360 total, 2277 passed, 0 failed, 83 skipped (201.195 seconds).
+Skipped tests are not browser passes. This evidence predates integration of
+`upstream/dev` at `9a76b742`; final integration results are recorded in the PR.
+
+Prior browser collection was run manually by the user: six frozen before/after
+HTML files, light/dark themes at 1440×900 and 2048×1320, 24 screenshots inspected
+by the agent. Browser receipts and independent perceptual review are distinct;
+native visual-review fields were not rewritten as human approval. These are
+reused results, not a new browser run for this PR or the newly authored Maka
+screenshot above. Workflow runtime source SHA-256 at that acceptance:
+
+| Source | SHA-256 |
+| --- | --- |
+| `archify/renderers/shared/geometry.mjs` | `dafdd8d3233a6e7a5ef3588a6f21a2651799af95f412afada201d6b68cdee68f` |
+| `archify/renderers/workflow/workflow-compiler.mjs` | `4f494c35e5b9fbffd33a47e50adee14e0738c54f4900bc76bcacc8e8340ec266` |
+| `archify/scripts/check-render-output.mjs` | `82ea7d9a826cbf2cf3c629a84b29d87b32a70a7fb439e87c2852e75164b13f15` |
+
+Performance: Node 22.23.1, three warm-ups and ten measured runs per fixed input.
+Median milliseconds (second-round baseline → candidate): OpenPI 31.890→38.163;
+Maka 23.009→28.197; alternate Maka 22.295→28.440; fan-out 29.427→37.989;
+bundled example 20.477→22.762; crowded fixture 9.585→13.691. Each met the agreed
+ceiling of max(baseline × 1.25, baseline + 10 ms). Local raw project receipts
+are intentionally not published; checked-in regressions are reproducible.
+
+## Ablation and remaining boundary
+
+- Removed extra port expansion for labelAt/explicit-side constrained edges;
+ 279 related checks passed while the original compatibility guard remained.
+- Removed the second local-repair pass; 95 routing/constraint checks and the
+ final 279 focused checks passed with one pass.
+- Removed the duplicate unused `axisOverlapLength` helper.
+- Restored the eight-seed bound after a two-seed bound failed crowded fan-out.
+- Restored ±32 offsets after ±16 alone failed the same crowded regression.
+
+The 120-character-label synthetic stress fixture fails final showcase HTML
+desktop readability on both baseline and candidate (projected font 5.66/5.54,
+minimum 6). Candidate canvas width grows 1315→1343 to separate routes, within
+the fixture's 1400 bound. It is compiler/performance evidence, not an accepted
+diagram delivery. No quality gate was lowered to hide this limitation.
+
+## Generated outputs
+
+The bundled/root workflow example, Gallery HTML/artifact/manifest, README GIF
+and its proof receipt were regenerated during implementation. The README GIF
+was actually re-recorded by the user, not merely rehashed. The distributable
+`archify.zip` must be rebuilt with Node 22 from the combined tracked sources
+after integrating dev's independent lifecycle fixes. Remote CI remains a
+separate requirement; local success does not imply CI or maintainer approval.
diff --git a/examples/workflow-agent-tool-call-rendered.html b/examples/workflow-agent-tool-call-rendered.html
index bd6f7ea4..66d6a50b 100644
--- a/examples/workflow-agent-tool-call-rendered.html
+++ b/examples/workflow-agent-tool-call-rendered.html
@@ -5240,7 +5240,7 @@ OTHER DEALINGS IN THE FONT SOFTWARE.
<!-- Main Diagram -->
<div class="diagram-container" data-detail-level="read"
data-preset-badge-editorial-plate="ARCHIFY / PLATE 04">
- <svg viewBox="0 0 1096 684" role="img" lang="en" aria-labelledby="archify-diagram-title archify-diagram-description" data-animation="trace" data-preset="signal-flow" data-quality-profile="showcase">
+ <svg viewBox="0 0 1096 684" data-layout-contract="readable-v2" role="img" lang="en" aria-labelledby="archify-diagram-title archify-diagram-description" data-animation="trace" data-preset="signal-flow" data-quality-profile="showcase">
<title id="archify-diagram-title">Agent Tool Call Workflow</title>
<desc id="archify-diagram-description">A workflow diagram generated by Archify.</desc>
<!-- Definitions -->
@@ -5301,17 +5301,17 @@ OTHER DEALINGS IN THE FONT SOFTWARE.
<text x="770" y="482" class="t-messagebus" font-size="7" font-weight="600">Tool work</text>
<!-- Edge paths -->
- <path data-edge-from="router" data-edge-to="approval" data-edge-label="needs approval?" data-edge-key="0" data-edge-id="approval-check" data-composition-points="651.2,279;651.2,302;569.2,302;569.2,387;585.2,387" d="M 651.2 279 L 651.2 302 L 569.2 302 L 569.2 387 L 585.2 387" class="a-security" data-animate="edge" style="--step:3" stroke-width="1.4" marker-end="url(#arrowhead-security)"/>
- <path data-edge-from="approval" data-edge-to="blocked" data-edge-label="denied" data-edge-key="1" data-edge-id="approval-denied" data-composition-points="651.2,421;651.2,442;830,442;830,413" d="M 651.2 421 L 651.2 442 L 830 442 L 830 413" class="a-security" data-animate="edge" style="--step:9" stroke-width="1.4" marker-end="url(#arrowhead-security)"/>
- <path data-edge-from="approval" data-edge-to="tool" data-edge-key="2" data-edge-id="approved-tool" data-composition-points="651.2,421;651.2,521;764,521" d="M 651.2 421 L 651.2 521 L 764 521" class="a-emphasis" data-animate="edge" style="--step:4" stroke-width="1.8" marker-end="url(#arrowhead-emphasis)"/>
- <path data-edge-from="external" data-edge-to="final" data-edge-key="3" data-edge-id="external-reply" data-composition-points="1056,521;1080,521;1080,120;1056,120" d="M 1056 521 L 1080 521 L 1080 120 L 1056 120" class="a-emphasis" data-animate="edge" style="--step:6" stroke-width="1.2" marker-end="url(#arrowhead-emphasis)"/>
- <path data-edge-from="chat" data-edge-to="planner" data-edge-label="plan" data-edge-key="4" data-edge-id="plan-request" data-composition-points="274,146;274,253;425.2,253" d="M 274 146 L 274 253 L 425.2 253" class="a-emphasis" data-animate="edge" style="--step:1" stroke-width="1.8" marker-end="url(#arrowhead-emphasis)"/>
- <path data-edge-from="planner" data-edge-to="router" data-edge-key="5" data-edge-id="planner-route" data-composition-points="557.2,253;585.2,253" d="M 557.2 253 L 585.2 253" class="a-default" data-animate="edge" style="--step:2" stroke-width="1.4" marker-end="url(#arrowhead)"/>
- <path data-edge-from="external" data-edge-to="trace" data-edge-label="record result" data-edge-key="6" data-edge-id="record-result" data-composition-points="990,547;990,579;491.2,579;491.2,547" d="M 990 547 L 990 579 L 491.2 579 L 491.2 547" class="a-dashed" data-animate="edge" style="--step:12" stroke-width="1.4" marker-end="url(#arrowhead-dashed)"/>
- <path data-edge-from="user" data-edge-to="chat" data-edge-key="7" data-edge-id="request-chat" data-composition-points="180,120;208,120" d="M 180 120 L 208 120" class="a-default" data-animate="edge" style="--step:0" stroke-width="1.4" marker-end="url(#arrowhead)"/>
- <path data-edge-from="blocked" data-edge-to="retry" data-edge-key="8" data-edge-id="retry-request" data-composition-points="896,387;924,387" d="M 896 387 L 924 387" class="a-dashed" data-animate="edge" style="--step:12" stroke-width="1.4" marker-end="url(#arrowhead-dashed)"/>
- <path data-edge-from="tool" data-edge-to="external" data-edge-key="9" data-edge-id="tool-external-call" data-composition-points="896,521;924,521" d="M 896 521 L 924 521" class="a-default" data-animate="edge" style="--step:5" stroke-width="1.4" marker-end="url(#arrowhead)"/>
- <path data-edge-from="store" data-edge-to="trace" data-edge-label="trace + memory" data-edge-key="10" data-edge-id="write-trace-memory" data-composition-points="340,521;425.2,521" d="M 340 521 L 425.2 521" class="a-dashed" data-animate="edge" style="--step:12" stroke-width="1.4" marker-end="url(#arrowhead-dashed)"/>
+ <path data-edge-from="router" data-edge-to="approval" data-edge-label="needs approval?" data-edge-key="0" data-edge-id="approval-check" data-composition-routing="workflow-v2-auto" data-edge-role="" data-composition-points="651.2,279;651.2,302;569.2,302;569.2,387;585.2,387" d="M 651.2 279 L 651.2 302 L 569.2 302 L 569.2 387 L 585.2 387" class="a-security" data-animate="edge" style="--step:3" stroke-width="1.4" marker-end="url(#arrowhead-security)"/>
+ <path data-edge-from="approval" data-edge-to="blocked" data-edge-label="denied" data-edge-key="1" data-edge-id="approval-denied" data-composition-routing="workflow-v2-auto" data-edge-role="error" data-composition-points="651.2,421;651.2,442;830,442;830,413" d="M 651.2 421 L 651.2 442 L 830 442 L 830 413" class="a-security" data-animate="edge" style="--step:9" stroke-width="1.4" marker-end="url(#arrowhead-security)"/>
+ <path data-edge-from="approval" data-edge-to="tool" data-edge-key="2" data-edge-id="approved-tool" data-composition-routing="workflow-v2-auto" data-edge-role="" data-composition-points="639.2,421;639.2,521;764,521" d="M 639.2 421 L 639.2 521 L 764 521" class="a-emphasis" data-animate="edge" style="--step:4" stroke-width="1.8" marker-end="url(#arrowhead-emphasis)"/>
+ <path data-edge-from="external" data-edge-to="final" data-edge-key="3" data-edge-id="external-reply" data-edge-role="return" data-composition-points="1056,521;1080,521;1080,120;1056,120" d="M 1056 521 L 1080 521 L 1080 120 L 1056 120" class="a-emphasis" data-animate="edge" style="--step:6" stroke-width="1.2" marker-end="url(#arrowhead-emphasis)"/>
+ <path data-edge-from="chat" data-edge-to="planner" data-edge-label="plan" data-edge-key="4" data-edge-id="plan-request" data-composition-routing="workflow-v2-auto" data-edge-role="" data-composition-points="274,146;274,253;425.2,253" d="M 274 146 L 274 253 L 425.2 253" class="a-emphasis" data-animate="edge" style="--step:1" stroke-width="1.8" marker-end="url(#arrowhead-emphasis)"/>
+ <path data-edge-from="planner" data-edge-to="router" data-edge-key="5" data-edge-id="planner-route" data-composition-routing="workflow-v2-auto" data-edge-role="" data-composition-points="557.2,253;585.2,253" d="M 557.2 253 L 585.2 253" class="a-default" data-animate="edge" style="--step:2" stroke-width="1.4" marker-end="url(#arrowhead)"/>
+ <path data-edge-from="external" data-edge-to="trace" data-edge-label="record result" data-edge-key="6" data-edge-id="record-result" data-edge-role="" data-composition-points="990,547;990,579;491.2,579;491.2,547" d="M 990 547 L 990 579 L 491.2 579 L 491.2 547" class="a-dashed" data-animate="edge" style="--step:12" stroke-width="1.4" marker-end="url(#arrowhead-dashed)"/>
+ <path data-edge-from="user" data-edge-to="chat" data-edge-key="7" data-edge-id="request-chat" data-composition-routing="workflow-v2-auto" data-edge-role="" data-composition-points="180,120;208,120" d="M 180 120 L 208 120" class="a-default" data-animate="edge" style="--step:0" stroke-width="1.4" marker-end="url(#arrowhead)"/>
+ <path data-edge-from="blocked" data-edge-to="retry" data-edge-key="8" data-edge-id="retry-request" data-composition-routing="workflow-v2-auto" data-edge-role="branch" data-composition-points="896,387;924,387" d="M 896 387 L 924 387" class="a-dashed" data-animate="edge" style="--step:12" stroke-width="1.4" marker-end="url(#arrowhead-dashed)"/>
+ <path data-edge-from="tool" data-edge-to="external" data-edge-key="9" data-edge-id="tool-external-call" data-composition-routing="workflow-v2-auto" data-edge-role="" data-composition-points="896,521;924,521" d="M 896 521 L 924 521" class="a-default" data-animate="edge" style="--step:5" stroke-width="1.4" marker-end="url(#arrowhead)"/>
+ <path data-edge-from="store" data-edge-to="trace" data-edge-label="trace + memory" data-edge-key="10" data-edge-id="write-trace-memory" data-composition-routing="workflow-v2-auto" data-edge-role="" data-composition-points="340,521;425.2,521" d="M 340 521 L 425.2 521" class="a-dashed" data-animate="edge" style="--step:12" stroke-width="1.4" marker-end="url(#arrowhead-dashed)"/>
<!-- Nodes -->
<g id="node-user" data-node-id="user" data-node-label="User" tabindex="0" role="button" aria-label="Focus User, asks for work, User Interface › Intake" aria-pressed="false" data-node-kind="external" data-node-sublabel="asks for work" data-node-context="User Interface › Intake">