Skip to content

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

fix(sequence): diagnose unsupported self-messages

tt-a1ib18ea2ed0f72
diff --git a/archify.zip b/archify.zip
index dd53e282..33373304 100644
Binary files a/archify.zip and b/archify.zip differ
diff --git a/archify/references/authoring-defaults.md b/archify/references/authoring-defaults.md
index 1a16877f..7ccd576f 100644
--- a/archify/references/authoring-defaults.md
+++ b/archify/references/authoring-defaults.md
@@ -36,6 +36,6 @@ Use one primary authored language from the user's choice or the request/conversa
Omit `meta.visual_preset` for classic, `meta.subtitle` for a title-only header, `meta.legend` for truthful auto, and `meta.engineering_profile` for an ordinary system overview. Explicit styles and a subtitle require a user request. Use legend or deployment ownership under the [legend](authoring-contract.md#legend-contract) or [engineering profile](authoring-contract.md#engineering-profile-default) contracts. Branding is optional and explicit when a node names a real product; [Brand marks](brand-marks.md) gives lookup and capture rules for that branch. Never let a badge replace semantic type, label, or relationship facts. Set required `meta.output` to a portable POSIX-relative `.html` path within the working directory; see [Output path contracts](delivery-contract.md#output-path-contracts) for native path exceptions.
-For new Workflow use schema v2, preserving v1 for a fixed legacy source; use its [layout contracts](../renderers/workflow/README.md#layout-contracts) when lane or group geometry needs detail. For Sequence omit `meta.column_fit` for spread columns on both automatic and authored canvases; preserve an authored `meta.viewBox`. Set `meta.column_fit: "fixed"` explicitly when historical fixed coordinates are required; use `spread` when a wide viewBox leaves unused horizontal space or meaningful labels need width. For Lifecycle use schema v3: list the happy path in `mainPath` and author every transition, including the main path; the renderer places all other states and routes. Give an exit shared by several consecutive phases the same label so it draws once, and keep transition labels short; a recoverable failure needs a real transition back. Read [Mode placement](authoring-contract.md#mode-placement) when a mode-specific placement or viewport problem needs more detail.
+For new Workflow use schema v2, preserving v1 for a fixed legacy source; use its [layout contracts](../renderers/workflow/README.md#layout-contracts) when lane or group geometry needs detail. For Sequence omit `meta.column_fit` for spread columns on both automatic and authored canvases; preserve an authored `meta.viewBox`. Set `meta.column_fit: "fixed"` explicitly when historical fixed coordinates are required; use `spread` when a wide viewBox leaves unused horizontal space or meaningful labels need width. Describe a participant's internal action in a note on its surrounding real cross-participant message, preserving its meaning and order; Sequence self-message loops are not supported. For Lifecycle use schema v3: list the happy path in `mainPath` and author every transition, including the main path; the renderer places all other states and routes. Give an exit shared by several consecutive phases the same label so it draws once, and keep transition labels short; a recoverable failure needs a real transition back. Read [Mode placement](authoring-contract.md#mode-placement) when a mode-specific placement or viewport problem needs more detail.
`finalize` performs the browser gate. Keep the complete drawing comfortably readable on desktop, with zero horizontal overflow. Use meaningful vertical rows and intrinsic-height page scroll when necessary. The 6px projected-text check is a failure floor; at 1440px, aim for ordinary context text around 7.5px or larger. See [Automated browser evidence](delivery-contract.md#automated-browser-evidence) when viewport evidence fails.
diff --git a/archify/renderers/sequence/README.md b/archify/renderers/sequence/README.md
index 188a43e8..dcd98f65 100644
--- a/archify/renderers/sequence/README.md
+++ b/archify/renderers/sequence/README.md
@@ -103,6 +103,14 @@ for the bounded authoring repair and explicit-fixed preservation rules.
## Design Rules
+- Messages currently require distinct `from` and `to` participants. Although
+ schema-v1 accepts matching IDs, this renderer does not draw self-call loops
+ and rejects them with `sequence/self-message-unsupported`, naming the message
+ path and participant. Increasing column distance cannot repair a self-message.
+ Preserve an internal step's wording, ownership, and order in a note on an
+ actual interaction or an explicitly ordered card. Do not invent another
+ participant or change the target merely to pass validation. These authoring
+ choices require semantic review and are not advertised as automatic fixes.
- Put participants across the top, ordered by the story the reader should
follow.
- Time moves downward.
diff --git a/archify/renderers/sequence/render-sequence.mjs b/archify/renderers/sequence/render-sequence.mjs
index 805768cc..5468d7f1 100644
--- a/archify/renderers/sequence/render-sequence.mjs
+++ b/archify/renderers/sequence/render-sequence.mjs
@@ -259,8 +259,35 @@ function validateSequence() {
problems.push(`Message "${message.label}" sits outside the readable timeline — keep y between ${layout.lifelineTop + 18} and ${layout.lifelineBottom - 18}.`);
}
if (participants.has(message.from) && participants.has(message.to)) {
- const distance = Math.abs(participants.get(message.to).cx - participants.get(message.from).cx);
- if (distance < 60) problems.push(`Message "${message.label}" spans ${Math.round(distance)}px (minimum 60px) — give its participants more column distance.`);
+ if (message.from === message.to) {
+ const problem = `Message "${message.label}" is a self-message on participant "${message.from}"; this Sequence renderer supports only messages between distinct participants. Participant spacing cannot repair it. Preserve the internal step's meaning and order in a supported representation such as a note on a real message or a card; do not invent a participant.`;
+ diagnostics.push({
+ code: 'sequence/self-message-unsupported', severity: 'error', message: problem,
+ subject: {
+ diagramType: 'sequence',
+ message: message.label,
+ collection: 'messages',
+ index: messageIndex,
+ path: `/messages/${messageIndex}`,
+ ...(message.id ? { id: message.id } : {}),
+ from: message.from,
+ to: message.to,
+ fromPath: `/messages/${messageIndex}/from`,
+ toPath: `/messages/${messageIndex}/to`,
+ },
+ evidence: {
+ participant: message.from,
+ participantPath: `/participants/${participantOrder.get(message.from)}`,
+ y: message.y,
+ supportedMessageGeometry: 'horizontal-between-distinct-participants',
+ },
+ supportedFixes: [],
+ });
+ problems.push(problem);
+ } else {
+ const distance = Math.abs(participants.get(message.to).cx - participants.get(message.from).cx);
+ if (distance < 60) problems.push(`Message "${message.label}" spans ${Math.round(distance)}px (minimum 60px) — give its participants more column distance.`);
+ }
}
}
diff --git a/test/sequence-self-message.test.mjs b/test/sequence-self-message.test.mjs
new file mode 100644
index 00000000..95cd4d86
--- /dev/null
+++ b/test/sequence-self-message.test.mjs
@@ -0,0 +1,60 @@
+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 { validateSchema } from '../archify/renderers/shared/validator.mjs';
+
+const cli = fileURLToPath(new URL('../archify/bin/archify.mjs', import.meta.url));
+
+for (const quality of ['standard', 'showcase']) {
+ test(`sequence ${quality} names unsupported self-messages without advertising a spacing repair`, t => {
+ const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'archify-sequence-self-'));
+ t.after(() => fs.rmSync(dir, { recursive: true, force: true }));
+ const input = path.join(dir, 'input.json');
+ const doc = {
+ schema_version: 1, diagram_type: 'sequence',
+ meta: { title: 'Internal operation', output: 'self.html', quality_profile: quality },
+ participants: [
+ { id: 'caller', type: 'frontend', label: 'Caller' },
+ { id: 'worker', type: 'backend', label: 'Worker' },
+ ],
+ messages: [
+ { id: 'request', from: 'caller', to: 'worker', y: 200, label: 'Request' },
+ { id: 'internal', from: 'worker', to: 'worker', y: 260, label: 'Apply local policy' },
+ ],
+ };
+ assert.doesNotThrow(() => validateSchema('sequence', doc), 'schema accepts the unsupported renderer capability');
+ fs.writeFileSync(input, JSON.stringify(doc));
+ const result = spawnSync(process.execPath, [cli, 'validate', 'sequence', input, '--quality', quality, '--json'], { encoding: 'utf8' });
+ assert.notEqual(result.status, 0);
+ const receipt = JSON.parse(result.stdout);
+ const diagnostic = receipt.diagnostics.find(({ code }) => code === 'sequence/self-message-unsupported');
+ assert.ok(diagnostic, result.stdout || result.stderr);
+ assert.equal(diagnostic.subject.path, '/messages/1');
+ assert.equal(diagnostic.subject.collection, 'messages');
+ assert.equal(diagnostic.subject.index, 1);
+ assert.equal(diagnostic.subject.id, 'internal');
+ assert.equal(diagnostic.subject.from, 'worker');
+ assert.equal(diagnostic.subject.to, 'worker');
+ assert.equal(diagnostic.subject.fromPath, '/messages/1/from');
+ assert.equal(diagnostic.subject.toPath, '/messages/1/to');
+ assert.equal(diagnostic.evidence.participant, 'worker');
+ assert.equal(diagnostic.evidence.participantPath, '/participants/1');
+ assert.equal(diagnostic.evidence.y, 260);
+ assert.equal(diagnostic.evidence.supportedMessageGeometry, 'horizontal-between-distinct-participants');
+ assert.deepEqual(diagnostic.supportedFixes, []);
+ assert.match(diagnostic.message, /meaning and order/);
+ assert.doesNotMatch(result.stdout, /spans 0px|give its participants more column distance/);
+ assert.deepEqual(JSON.parse(fs.readFileSync(input, 'utf8')), doc, 'rejection preserves authored semantics');
+ assert.equal(fs.existsSync(path.join(dir, 'self.html')), false);
+ const output = path.join(dir, 'rendered.html');
+ const rendered = spawnSync(process.execPath, [cli, 'render', 'sequence', input, output, '--quality', quality], { encoding: 'utf8' });
+ assert.notEqual(rendered.status, 0);
+ assert.match(rendered.stderr, /self-message on participant "worker"/);
+ assert.doesNotMatch(rendered.stderr, /spans 0px|give its participants more column distance/);
+ assert.equal(fs.existsSync(output), false, 'render rejects before producing an artifact');
+ });
+}