dsh-knowhub 0.9.0 → 0.10.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (195) hide show
  1. package/README.md +11 -2
  2. package/cordis.patch.yml +10 -0
  3. package/lib/host/model.js +1 -1
  4. package/lib/host/pipeline/incremental.js +3 -3
  5. package/lib/host/pipeline/initialize.js +144 -27
  6. package/lib/host/pipeline/model-output.js +2 -2
  7. package/package.json +3 -2
  8. package/skills/archify/LICENSE +202 -0
  9. package/skills/archify/LICENSE-MIT +22 -0
  10. package/skills/archify/NOTICE +26 -0
  11. package/skills/archify/SKILL.md +137 -0
  12. package/skills/archify/THIRD_PARTY_NOTICES.md +78 -0
  13. package/skills/archify/assets/JetBrainsMono-OFL.txt +93 -0
  14. package/skills/archify/assets/template.html +14768 -0
  15. package/skills/archify/bin/archify.mjs +7289 -0
  16. package/skills/archify/bin/delivery-update.mjs +92 -0
  17. package/skills/archify/bin/finalize.mjs +1055 -0
  18. package/skills/archify/bin/open-artifact.mjs +146 -0
  19. package/skills/archify/bin/preview.mjs +970 -0
  20. package/skills/archify/bin/recover-output.mjs +41 -0
  21. package/skills/archify/bin/visual-check.mjs +2780 -0
  22. package/skills/archify/brand-marks/README.md +31 -0
  23. package/skills/archify/brand-marks/catalog.json +131 -0
  24. package/skills/archify/delta/architecture-delta.mjs +1318 -0
  25. package/skills/archify/examples/agent-run.lifecycle.json +55 -0
  26. package/skills/archify/examples/agent-tool-call.workflow.json +74 -0
  27. package/skills/archify/examples/archify-dev-activity.timeline.json +176 -0
  28. package/skills/archify/examples/archify-repository.tree.json +197 -0
  29. package/skills/archify/examples/async-job-roundtrip.sequence.json +56 -0
  30. package/skills/archify/examples/brand-aware-delivery.architecture.json +34 -0
  31. package/skills/archify/examples/cache-miss-request.sequence.json +77 -0
  32. package/skills/archify/examples/checkout-platform.base.architecture.json +32 -0
  33. package/skills/archify/examples/checkout-platform.head.architecture.json +32 -0
  34. package/skills/archify/examples/checkout-request.waterfall.json +20 -0
  35. package/skills/archify/examples/delivery.explainer.json +155 -0
  36. package/skills/archify/examples/deployment-release.lifecycle.json +72 -0
  37. package/skills/archify/examples/event-stream.dataflow.json +52 -0
  38. package/skills/archify/examples/example-rebuild.waterfall.json +212 -0
  39. package/skills/archify/examples/holiday-planning.workflow.json +143 -0
  40. package/skills/archify/examples/incident-response.workflow.json +59 -0
  41. package/skills/archify/examples/locales/de.json +463 -0
  42. package/skills/archify/examples/locales/fr.json +463 -0
  43. package/skills/archify/examples/locales/fr.partial.json +22 -0
  44. package/skills/archify/examples/locales/it.json +463 -0
  45. package/skills/archify/examples/locales/ja.json +463 -0
  46. package/skills/archify/examples/locales/pt.json +463 -0
  47. package/skills/archify/examples/locales/ru.json +463 -0
  48. package/skills/archify/examples/orders.erd.json +337 -0
  49. package/skills/archify/examples/payment-incident.timeline.json +24 -0
  50. package/skills/archify/examples/payment-platform.tree.json +22 -0
  51. package/skills/archify/examples/payment-processors.class.json +177 -0
  52. package/skills/archify/examples/payments.class.json +85 -0
  53. package/skills/archify/examples/product-analytics.dataflow.json +71 -0
  54. package/skills/archify/examples/production-deployment.architecture.json +51 -0
  55. package/skills/archify/examples/release-delivery.workflow.json +57 -0
  56. package/skills/archify/examples/subscription-billing.erd.json +548 -0
  57. package/skills/archify/examples/web-app.architecture.json +41 -0
  58. package/skills/archify/explainer/browser-check.mjs +208 -0
  59. package/skills/archify/explainer/charts.mjs +70 -0
  60. package/skills/archify/explainer/check.mjs +167 -0
  61. package/skills/archify/explainer/diagrams.mjs +517 -0
  62. package/skills/archify/explainer/diff.mjs +124 -0
  63. package/skills/archify/explainer/inline.mjs +155 -0
  64. package/skills/archify/explainer/layout.mjs +35 -0
  65. package/skills/archify/explainer/page-bundle.mjs +16 -0
  66. package/skills/archify/explainer/parse.mjs +300 -0
  67. package/skills/archify/explainer/patch.mjs +117 -0
  68. package/skills/archify/explainer/prepare.mjs +131 -0
  69. package/skills/archify/explainer/reader.css +472 -0
  70. package/skills/archify/explainer/reader.js +666 -0
  71. package/skills/archify/explainer/render.mjs +224 -0
  72. package/skills/archify/explainer/revision.mjs +20 -0
  73. package/skills/archify/explainer/sources.mjs +318 -0
  74. package/skills/archify/explainer/validate.mjs +138 -0
  75. package/skills/archify/explainer/vendor/pele/LICENSE +40 -0
  76. package/skills/archify/explainer/vendor/pele/README.md +5 -0
  77. package/skills/archify/explainer/vendor/pele/chunks/3DKXF73K.js +4 -0
  78. package/skills/archify/explainer/vendor/pele/chunks/42UTT654.js +3 -0
  79. package/skills/archify/explainer/vendor/pele/chunks/DKTLEL5E.js +1 -0
  80. package/skills/archify/explainer/vendor/pele/chunks/EEIX5ZYH.js +2 -0
  81. package/skills/archify/explainer/vendor/pele/chunks/EJ5KOXYD.js +25 -0
  82. package/skills/archify/explainer/vendor/pele/chunks/GUJTEFZK.js +1 -0
  83. package/skills/archify/explainer/vendor/pele/chunks/IZOKQ2GT.js +4 -0
  84. package/skills/archify/explainer/vendor/pele/chunks/L4LY553T.js +3 -0
  85. package/skills/archify/explainer/vendor/pele/chunks/MSKIJHB2.js +2 -0
  86. package/skills/archify/explainer/vendor/pele/chunks/RVARI57O.js +1 -0
  87. package/skills/archify/explainer/vendor/pele/chunks/UKSIWDDN.js +2 -0
  88. package/skills/archify/explainer/vendor/pele/chunks/UPTXNAXN.js +2 -0
  89. package/skills/archify/explainer/vendor/pele/chunks/XTDUIGUI.js +9 -0
  90. package/skills/archify/explainer/vendor/pele/chunks/YAYTP6L5.js +9 -0
  91. package/skills/archify/explainer/vendor/pele/core.js +1 -0
  92. package/skills/archify/explainer/vendor/pele/diagrams/pie.js +1 -0
  93. package/skills/archify/explainer/vendor/pele/diagrams/quadrantChart.js +1 -0
  94. package/skills/archify/explainer/vendor/pele/diagrams/radar.js +1 -0
  95. package/skills/archify/explainer/vendor/pele/diagrams/sankey.js +1 -0
  96. package/skills/archify/explainer/vendor/pele/diagrams/venn.js +1 -0
  97. package/skills/archify/explainer/vendor/pele/diagrams/xychart.js +1 -0
  98. package/skills/archify/explainer/writing.mjs +139 -0
  99. package/skills/archify/locales/README.md +40 -0
  100. package/skills/archify/locales/ar.json +488 -0
  101. package/skills/archify/locales/en.json +488 -0
  102. package/skills/archify/locales/es.json +488 -0
  103. package/skills/archify/locales/ko.json +488 -0
  104. package/skills/archify/locales/manifest.json +10 -0
  105. package/skills/archify/locales/zh-CN.json +488 -0
  106. package/skills/archify/locales/zh-TW.json +488 -0
  107. package/skills/archify/migrations/workflow-v2.mjs +280 -0
  108. package/skills/archify/package.json +17 -0
  109. package/skills/archify/recipes/scenarios.mjs +455 -0
  110. package/skills/archify/references/architecture-layout-repair.md +18 -0
  111. package/skills/archify/references/authoring-contract.md +645 -0
  112. package/skills/archify/references/authoring-defaults.md +57 -0
  113. package/skills/archify/references/brand-marks.md +119 -0
  114. package/skills/archify/references/delivery-contract.md +665 -0
  115. package/skills/archify/references/explainer-authoring.md +274 -0
  116. package/skills/archify/references/repository-authoring.md +126 -0
  117. package/skills/archify/references/update-awareness.md +13 -0
  118. package/skills/archify/references/viewer-runtime.md +52 -0
  119. package/skills/archify/renderers/architecture/grid.mjs +62 -0
  120. package/skills/archify/renderers/architecture/labels.mjs +2 -0
  121. package/skills/archify/renderers/architecture/render-architecture.mjs +1204 -0
  122. package/skills/archify/renderers/architecture/routing.mjs +1469 -0
  123. package/skills/archify/renderers/class/README.md +130 -0
  124. package/skills/archify/renderers/class/render-class.mjs +1095 -0
  125. package/skills/archify/renderers/dataflow/README.md +176 -0
  126. package/skills/archify/renderers/dataflow/dataflow-compiler.mjs +1605 -0
  127. package/skills/archify/renderers/dataflow/joint-label-routing.mjs +165 -0
  128. package/skills/archify/renderers/dataflow/label-capacity.mjs +81 -0
  129. package/skills/archify/renderers/dataflow/render-dataflow.mjs +23 -0
  130. package/skills/archify/renderers/erd/README.md +246 -0
  131. package/skills/archify/renderers/erd/grid.mjs +150 -0
  132. package/skills/archify/renderers/erd/render-erd.mjs +1588 -0
  133. package/skills/archify/renderers/explainer/render-explainer.mjs +42 -0
  134. package/skills/archify/renderers/lifecycle/README.md +104 -0
  135. package/skills/archify/renderers/lifecycle/render-lifecycle.mjs +1134 -0
  136. package/skills/archify/renderers/sequence/README.md +146 -0
  137. package/skills/archify/renderers/sequence/render-sequence.mjs +1105 -0
  138. package/skills/archify/renderers/shared/atomic-output.mjs +1982 -0
  139. package/skills/archify/renderers/shared/automatic-labels.mjs +290 -0
  140. package/skills/archify/renderers/shared/brand-marks.mjs +706 -0
  141. package/skills/archify/renderers/shared/cli.mjs +430 -0
  142. package/skills/archify/renderers/shared/desktop-readability.mjs +132 -0
  143. package/skills/archify/renderers/shared/diagnostics.mjs +0 -0
  144. package/skills/archify/renderers/shared/engineering-profiles.mjs +157 -0
  145. package/skills/archify/renderers/shared/generated-brand-marks.mjs +2003 -0
  146. package/skills/archify/renderers/shared/generated-validators.mjs +279 -0
  147. package/skills/archify/renderers/shared/geometry.mjs +2073 -0
  148. package/skills/archify/renderers/shared/i18n.mjs +328 -0
  149. package/skills/archify/renderers/shared/layout-report.mjs +57 -0
  150. package/skills/archify/renderers/shared/legend.mjs +227 -0
  151. package/skills/archify/renderers/shared/node-card-style.mjs +32 -0
  152. package/skills/archify/renderers/shared/output-path.mjs +440 -0
  153. package/skills/archify/renderers/shared/owned-temp-directory.mjs +82 -0
  154. package/skills/archify/renderers/shared/path-semantics.mjs +1017 -0
  155. package/skills/archify/renderers/shared/portable-path.mjs +408 -0
  156. package/skills/archify/renderers/shared/repository-evidence.mjs +394 -0
  157. package/skills/archify/renderers/shared/repository-location.mjs +71 -0
  158. package/skills/archify/renderers/shared/route-quality.mjs +670 -0
  159. package/skills/archify/renderers/shared/sidecar-path.mjs +38 -0
  160. package/skills/archify/renderers/shared/software-notices.mjs +6 -0
  161. package/skills/archify/renderers/shared/spatial-grid.mjs +66 -0
  162. package/skills/archify/renderers/shared/svg-path-analysis.mjs +135 -0
  163. package/skills/archify/renderers/shared/text-fit.mjs +105 -0
  164. package/skills/archify/renderers/shared/utils.mjs +260 -0
  165. package/skills/archify/renderers/shared/validator.mjs +83 -0
  166. package/skills/archify/renderers/timeline/README.md +76 -0
  167. package/skills/archify/renderers/timeline/render-timeline.mjs +576 -0
  168. package/skills/archify/renderers/tree/README.md +96 -0
  169. package/skills/archify/renderers/tree/render-tree.mjs +573 -0
  170. package/skills/archify/renderers/waterfall/README.md +73 -0
  171. package/skills/archify/renderers/waterfall/render-waterfall.mjs +413 -0
  172. package/skills/archify/renderers/workflow/README.md +337 -0
  173. package/skills/archify/renderers/workflow/render-workflow.mjs +47 -0
  174. package/skills/archify/renderers/workflow/workflow-compiler.mjs +5920 -0
  175. package/skills/archify/renderers/workflow/workflow-migration-geometry.mjs +161 -0
  176. package/skills/archify/renderers/workflow/workflow-placement-repair.mjs +94 -0
  177. package/skills/archify/schemas/README.md +258 -0
  178. package/skills/archify/schemas/architecture.schema.json +152 -0
  179. package/skills/archify/schemas/class.schema.json +345 -0
  180. package/skills/archify/schemas/common.schema.json +181 -0
  181. package/skills/archify/schemas/dataflow.schema.json +254 -0
  182. package/skills/archify/schemas/erd.schema.json +381 -0
  183. package/skills/archify/schemas/explainer.schema.json +927 -0
  184. package/skills/archify/schemas/lifecycle.schema.json +179 -0
  185. package/skills/archify/schemas/sequence.schema.json +234 -0
  186. package/skills/archify/schemas/timeline.schema.json +160 -0
  187. package/skills/archify/schemas/tree.schema.json +141 -0
  188. package/skills/archify/schemas/waterfall.schema.json +147 -0
  189. package/skills/archify/schemas/workflow.schema.json +439 -0
  190. package/skills/archify/scripts/check-render-output.mjs +1469 -0
  191. package/skills/archify/scripts/check-update.mjs +1717 -0
  192. package/skills/archify/scripts/delivery-update-child.mjs +26 -0
  193. package/skills/archify/scripts/render-examples.mjs +36 -0
  194. package/skills/archify/scripts/update-contract.mjs +187 -0
  195. package/skills/archify/skill-release.json +10 -0
@@ -0,0 +1,337 @@
1
+ # Workflow Renderer
2
+
3
+ Render `diagram_type: "workflow"` JSON files into the standard Archify HTML
4
+ template.
5
+
6
+ ```bash
7
+ node archify/renderers/workflow/render-workflow.mjs input.workflow.json output.html
8
+ ```
9
+
10
+ The renderer validates input against `archify/schemas/workflow.schema.json`
11
+ with the bundled standalone validator. No dependency installation is required.
12
+
13
+ If `output.html` is omitted, the renderer uses the required `meta.output` value
14
+ from the JSON file.
15
+
16
+ After rendering, run the artifact checker:
17
+
18
+ ```bash
19
+ node archify/scripts/check-render-output.mjs output.html
20
+ ```
21
+
22
+ It catches final-SVG issues that are easiest to see in a browser: non-finite
23
+ SVG values, accidental two-point diagonal arrows, and arrows crossing the
24
+ legend.
25
+
26
+ ## Input
27
+
28
+ Workflow JSON files must set:
29
+
30
+ ```json
31
+ {
32
+ "schema_version": 2,
33
+ "diagram_type": "workflow",
34
+ "meta": {
35
+ "title": "Agent Tool Call Workflow",
36
+ "output": "agent-tool-call.html"
37
+ },
38
+ "lanes": [],
39
+ "phases": [],
40
+ "groups": [],
41
+ "mainPath": [],
42
+ "nodes": [],
43
+ "edges": [],
44
+ "cards": []
45
+ }
46
+ ```
47
+
48
+ Use `schema_version: 2` for new workflows. Its readable layout compiler treats
49
+ every `col` as a logical rank in `0..5` and derives geometry from the measured
50
+ document. `schema_version: 1` remains the fixed legacy contract for existing
51
+ sources; valid v1 output is preserved byte-for-byte and never silently
52
+ reinterpreted as v2.
53
+
54
+ Omit `meta.viewBox` for the common v2 case so the compiler can use intrinsic
55
+ measured bounds. In v1, the omitted width remains fixed at 720 and height is
56
+ derived from lane count. A complete worked example lives at
57
+ `archify/examples/agent-tool-call.workflow.json`; its `schema_version` selects
58
+ the applicable contract.
59
+
60
+ The schema lives at:
61
+
62
+ ```text
63
+ archify/schemas/workflow.schema.json
64
+ ```
65
+
66
+ ## Migration and layout receipt
67
+
68
+ Migrate an existing v1 source into a separate v2 file:
69
+
70
+ ```bash
71
+ node archify/bin/archify.mjs migrate workflow old.json new.json --to-schema 2 --json
72
+ ```
73
+
74
+ Running the command again with its schema-v2 output as the new source is an
75
+ idempotent verification pass: the destination bytes and geometry stay unchanged.
76
+
77
+ If a legacy v1 source is blocked solely because `meta.output` is missing or no
78
+ longer portable, supply its replacement for the separate v2 destination:
79
+
80
+ ```bash
81
+ node archify/bin/archify.mjs migrate workflow old.json new.json --to-schema 2 --output reports/workflow.html --json
82
+ ```
83
+
84
+ `--output` must itself be a portable POSIX-relative `.html` path. It updates
85
+ only the verified destination candidate; the source bytes remain unchanged and
86
+ all non-output schema and compiler diagnostics still block migration.
87
+
88
+ The command never overwrites the source by default. It maps absolute
89
+ `via[*][0]`, `labelAt[0]`, and `channelX` values from legacy to solved rank
90
+ space, preserves y coordinates unless a reported vertical constraint needs
91
+ author input, expands an explicit viewBox only for an unambiguous containment
92
+ repair, and writes the destination only after v2 compilation and artifact
93
+ checks pass. Ambiguous explicit pins fail without producing the destination.
94
+
95
+ Migration preserves `semanticChecks` and validates those requirements against the
96
+ complete authored topology. Temporary layout planning may omit routed edges,
97
+ but authors do not need to remove or relax their contracts to use migration.
98
+ The complete migrated document must still satisfy every authored requirement.
99
+
100
+ Inspect the stable author-facing v2 plan with:
101
+
102
+ ```bash
103
+ node archify/bin/archify.mjs validate workflow input.workflow.json --layout-json
104
+ ```
105
+
106
+ The receipt reports the selected contract, measured `viewBox` and
107
+ `requiredViewBox`, solved columns, nodes, edges, labels, and causal diagnostics.
108
+ It deliberately omits solver iterations and candidate scores. A complete plan
109
+ rejected by a late layout, canvas, or text check also includes this geometry with
110
+ `ok: false`; validation still exits non-zero and writes no HTML. Its `viewBox`
111
+ is the attempted frame at rejection, while `requiredViewBox` is the measured
112
+ footprint of that same rejected plan. Labels use their anchor coordinates,
113
+ not the top-left corner of the label mask. Early or incomplete failures retain
114
+ only the contract and causal diagnostics. Failed geometry is repair evidence,
115
+ not acceptance; migration failure reports may also gain measured canvas evidence
116
+ without accepting the rejected plan.
117
+
118
+ ## Legend
119
+
120
+ The default legend derives component kinds from `nodes[].type`. Supported
121
+ `meta.legend.entries` keys, in stable order, are `frontend`, `backend`,
122
+ `security`, `messagebus`, `database`, `cloud`, and `external`. Labels and
123
+ visibility may be overridden through the shared legend contract; only kinds
124
+ backed by rendered nodes receive Semantic Legend controls.
125
+
126
+ ## Layout contracts
127
+
128
+ ### Fixed v1
129
+
130
+ | Constant | Value |
131
+ |----------|-------|
132
+ | viewBox | default `[720, auto]` — auto height = 52 + lanes×104 + (lanes−1)×20 + 124 |
133
+ | Lane frame | x 40, width 640, height 104, gap 20; first lane top at y 52 |
134
+ | Lane title strip | top 30px of each lane; node boxes must stay below it |
135
+ | Column centers (`col` 0–5) | x = 88, 220, 300, 430, 500, 625 |
136
+ | Phase headers | Optional `phases[]` render above the first lane, spanning `fromCol..toCol` |
137
+ | Lane groups | Optional `groups[]` frame parallel work or branch work inside one lane |
138
+ | Exception lanes | Set `lane.variant: "exception"` for retry, denial, fallback, or failure paths |
139
+ | Main path lint | Optional `mainPath[]` checks that happy-path steps have matching edges and do not move backward |
140
+ | Default node | 92×52 (height 68 when `tag` is set) |
141
+ | Node spacing | ≥8px between nodes in the same lane |
142
+ | Edge length | straight segments must span ≥28px |
143
+ | Legend row | y = lane bottom + 44; viewBox height must be ≥ legend y + 18 |
144
+
145
+ Column-center gaps are 132 / 80 / 130 / 70 / 125 px: columns 1↔2 (80px) and
146
+ 3↔4 (70px) cannot both hold default-width 92px nodes in the same lane. Such an
147
+ invalid v1 source receives one causal `workflow/column-capacity` diagnostic and
148
+ a verified migration-to-v2 repair; v1 never falls through to adaptive layout.
149
+
150
+ ### Readable v2
151
+
152
+ | Invariant | Contract |
153
+ |----------|----------|
154
+ | Logical columns | `col` is an integer in `0..5`; pixel centers are measured output |
155
+ | Adjacent-rank baseline | 120px center distance before document-specific constraints |
156
+ | Same-lane node clearance | ≥8px when vertical node intervals overlap |
157
+ | Facing direct edge | clear gap ≥`max(28px, measured label mask width + 8px)` |
158
+ | Automatic route rhythm | direct segment ≥28px; endpoint stub ≥8px; interior turn segment ≥16px |
159
+ | Implicit viewBox | intrinsic content bounds plus contract padding |
160
+ | Explicit viewBox | containment capacity; too-small input reports exact `requiredViewBox` and contributors |
161
+ | Lane measurement | A same-column vertical stack (two or more distinct `yOffset` values) opts an implicit, unpinned workflow into per-lane measurement. Explicit `meta.viewBox`, `via`, `labelAt`, `channelX`, or `channelY`, and workflows without a stack retain shared-height v2 geometry for compatibility. |
162
+
163
+ Unpinned v2 drafts reserve 32px between overlapping same-lane nodes for routes,
164
+ and omitted node widths may grow from 92px to 200px to fit their text. Documents
165
+ with an explicit `meta.viewBox` or absolute `via`, `labelAt`, `channelX`, or
166
+ `channelY` pins retain the existing width defaults and 8px rank-clearance
167
+ constraint, in both compilation and migration planning. Authored widths remain
168
+ authoritative.
169
+
170
+ Automatic showcase canvases check sublabels against the desktop reading floor
171
+ without enlarging text beyond its existing 8px slot. If the canvas cannot keep
172
+ that slot readable, `workflow/sublabel-readability` reports the required font
173
+ and canvas width. Standard quality and explicit canvases retain their previous
174
+ text-fitting behavior and the existing composition/browser quality checks.
175
+
176
+ The compiler applies constraints only to actual related or overlapping
177
+ same-lane nodes, so a wide node in an unrelated lane does not expand every
178
+ rank. Legacy centers are a soft preference after correctness constraints, not
179
+ a geometry promise. Phase and group frames derive from the solved rank bands.
180
+ Automatic routes are normalized once and the same final scene drives
181
+ validation and SVG serialization. Long automatic labels compare direct-gutter
182
+ growth with a legal channel instead of widening every downstream rank. Measured
183
+ multi-row legends participate in intrinsic height and explicit viewBox
184
+ capacity.
185
+
186
+ The Issue #250 shape already has a v2 representation without an authored lane
187
+ size. Keep the three stages in one grouped lane, omit `meta.viewBox`, and center
188
+ their offsets around zero:
189
+
190
+ ```json
191
+ {
192
+ "schema_version": 2,
193
+ "diagram_type": "workflow",
194
+ "meta": { "title": "stack", "output": "stack.html" },
195
+ "lanes": [{ "id": "cage", "label": "one cage" }],
196
+ "groups": [{ "id": "g", "label": "cage", "lane": "cage", "fromCol": 1, "toCol": 3 }],
197
+ "nodes": [
198
+ { "id": "a", "lane": "cage", "col": 2, "type": "security", "label": "stageA", "yOffset": -90 },
199
+ { "id": "b", "lane": "cage", "col": 2, "type": "security", "label": "stageB", "yOffset": 0 },
200
+ { "id": "c", "lane": "cage", "col": 2, "type": "security", "label": "stageC", "yOffset": 90 }
201
+ ],
202
+ "edges": [
203
+ { "from": "a", "to": "b", "fromSide": "bottom", "toSide": "top" },
204
+ { "from": "b", "to": "c", "fromSide": "bottom", "toSide": "top" }
205
+ ]
206
+ }
207
+ ```
208
+
209
+ An implicit readable-v2 vertical stack whose measured lane height exceeds the
210
+ 104px baseline declares `data-reader-fit="width-first"`, as does any implicit
211
+ readable-v2 canvas that would otherwise overflow the 1440×900 desktop page at
212
+ full width. The desktop Viewer uses
213
+ available reading width and normal page scrolling to keep tall stages readable,
214
+ with the existing 1.5× automatic enlargement cap. This changes only displayed
215
+ size: canonical SVG geometry and explicit `meta.viewBox` workflows retain their
216
+ authored contracts. Embed, Present, and print retain their existing fitting modes.
217
+ `visual-check` still checks readability, horizontal containment, and clipping;
218
+ the declaration does not weaken node or route validation.
219
+
220
+ Authored `via`, `labelAt`, `channelX`, and `channelY` are absolute hard pins in
221
+ v2; an infeasible pin returns `workflow/explicit-pin-conflict` rather than being
222
+ silently moved. `fromSide` and `toSide` remain direction constraints. A route
223
+ preset restricts the automatic candidate family but is not itself an absolute
224
+ coordinate pin. When either endpoint side is omitted, the v2 compiler chooses
225
+ a feasible side; an authored side restricts that endpoint to the named port.
226
+ An infeasible preset returns `workflow/route-preset-conflict` with the actual
227
+ rejected `evidence.invariant`. For node clearance it also identifies the node,
228
+ segment, endpoint role, and required clearance. Use that obstacle to revise
229
+ the connected placement or route constraints, then revalidate; minimum segment
230
+ lengths alone do not establish a clear path. Concrete alternatives for
231
+ `workflow/route-preset-conflict` are checked by replanning the complete workflow
232
+ at the active quality profile.
233
+
234
+ ## Design Rules
235
+
236
+ - Use lanes for ownership or runtime boundaries.
237
+ - Use phase headers for high-level story beats such as Intake, Plan, Execute, and Report.
238
+ - Use groups for parallel checks, branch handling, or bounded work within a lane; every group must contain at least one node.
239
+ - For sequential stages stacked inside one container, use one v2 lane and one group, keep the stages in one column, and omit `meta.viewBox`. `yOffset` is relative to the center of the lane's content area, so center a three-stage stack with `-90 / 0 / 90` rather than `0 / 90 / 180`. With compiler-owned routes and canvas, the compiler expands only that lane.
240
+ - Use `lane.variant: "exception"` for human wait, denial, retry, fallback, and failure lanes instead of mixing those paths into the happy path.
241
+ - Set `mainPath` when the diagram has a clear happy path; the renderer validates that consecutive ids have matching edges and move left-to-right.
242
+ - Place nodes with lane IDs and `col` indexes in `0..5`, not raw SVG coordinates.
243
+ - Preserve semantic edge labels. Readable v2 allocates measured label clearance;
244
+ when a label does not fit, repair the reported capacity or route constraint
245
+ instead of deleting meaning.
246
+ - Use labels for decisions, approvals, protocols, async traces, return paths,
247
+ and any other relationship meaning not fully implied by its endpoints.
248
+ - Prefer route presets — `drop` (bend between lanes; `bias` 0–1 picks where),
249
+ `outside-right`, `return-left`, `bottom-channel`, and `up-channel` — before
250
+ using raw `via` points. `straight` and the default `auto` cover the rest.
251
+ - Keep workflow examples compact enough to render well in narrow chat/browser
252
+ previews.
253
+
254
+ ### Optional semantic checks
255
+
256
+ Layout validation cannot infer domain truth from labels or cards. When source
257
+ evidence establishes roots, terminals, mandatory direct relationships, or
258
+ mandatory directed reachability, encode those facts in `semanticChecks`:
259
+
260
+ ```json
261
+ "semanticChecks": {
262
+ "allowedRoots": ["request", "resource_catalog"],
263
+ "allowedTerminals": ["reply", "audit_log"],
264
+ "requiredEdges": [
265
+ { "from": "dispatch", "to": "dispatch_ledger" }
266
+ ],
267
+ "requiredPaths": [
268
+ { "from": "event_ledger", "to": "runtime_host" }
269
+ ]
270
+ }
271
+ ```
272
+
273
+ When `allowedRoots` or `allowedTerminals` is present, it is the complete allow
274
+ list for zero-incoming or zero-outgoing nodes respectively. `requiredEdges`
275
+ requires one exact authored direction; `requiredPaths` permits intermediate
276
+ nodes but follows authored edge direction. These checks run before layout, do
277
+ not alter SVG or receipt bytes, and must not be weakened merely to resolve a
278
+ route or composition diagnostic. Omit fields whose domain facts are unknown.
279
+
280
+ Schema violations exit non-zero with path-prefixed messages annotated with the
281
+ element's id or label. The renderer additionally fails when it can detect
282
+ layout problems, including node overlap, nodes outside their lanes, invalid
283
+ phase/group column ranges, empty groups, broken `mainPath` steps, unknown edge
284
+ targets, labels colliding with nodes or other labels, labels wider than their
285
+ node, legends outside the viewBox, or straight arrows that are too short to
286
+ read cleanly. The shared Clean Flow Gate also rejects edges crossing unrelated
287
+ nodes with 2px clearance; lanes, phases, and groups remain intentional
288
+ pass-through containers. Text width is estimated CJK-aware: fullwidth glyphs
289
+ count as two units.
290
+
291
+ Diagnostics are causal: a rank-capacity failure suppresses derivative short
292
+ edge, endpoint-direction, and label-overlap findings. `supportedFixes[]` can
293
+ contain concrete edits checked by the compiler's fix search or general repair
294
+ guidance from shared composition checks. General guidance is not a verified
295
+ edit. After any edit, rerun the complete `finalize` command. A diagnostic never
296
+ proposes removing a semantic label when label presence does not cause the
297
+ failed invariant.
298
+
299
+ Set `meta.quality_profile` to `showcase` for polished delivery. Unrelated proper
300
+ X crossings then fail with `composition/proper-crossing`; default `standard`
301
+ keeps them as artifact-receipt warnings. Collinear lane corridors are outside
302
+ the proper-X rule, but a separate gate warns in `standard` and fails in
303
+ `showcase` when unrelated edges overlap for at least 8px. V1 keeps its authored
304
+ shared-endpoint contract. V2 also checks shared endpoints, including explicitly
305
+ controlled routes: long or mixed-style trunks, counterflow, proper interior X
306
+ crossings and overlapping independent arrowheads are not exempt. Pins are
307
+ preserved, not silently repaired; unresolved v2 corridor/arrowhead collisions
308
+ warn in `standard` and fail in `showcase`.
309
+
310
+ V2 permits a same-direction shared terminal stub of at most 24 SVG units only
311
+ when both relationships share the actual source or target port, effective
312
+ variant, stroke width and role. A nonterminal overlap is never such a stub;
313
+ forward-collinear waypoints do not split a long trunk into permitted pieces.
314
+ Compatible short merges may share their terminal arrowhead. Automatic routes
315
+ consider separate ports, reserve absolute routes at contested nodes, and prefer
316
+ clear paths over shorter ambiguous ones. Crowded automatic corridors can use a
317
+ bounded local adjustment without moving nodes or changing explicit coordinates.
318
+
319
+ The SVG carries `data-layout-contract="readable-v2"` and each edge's role so
320
+ artifact checks apply the same classification to actual visible path geometry,
321
+ not stale composition-point metadata. These internal output attributes do not
322
+ add authoring schema fields. Other diagram types retain their existing rules.
323
+ V2 proper-crossing diagnostics retain the relationship IDs, intersection point,
324
+ and supported fixes in both compiler/layout-JSON receipts and final HTML checks;
325
+ `standard` reports warnings while `showcase` rejects the crossing. Both analyses
326
+ merge forward-collinear waypoints without rewriting authored paths; real bends
327
+ and reversals remain endpoint touches rather than being merged into an X.
328
+
329
+ The older per-edge `data-composition-routing="workflow-v2-auto"` marker remains
330
+ for compatibility with first-round exported HTML that has no root layout
331
+ contract and with older artifact checkers. Marker-only artifacts retain their
332
+ narrower automatic-pair crossing/counterflow policy; the root `readable-v2`
333
+ contract is authoritative when present and also checks explicit routes. Do not
334
+ remove the marker-only path as dead code without retiring that export format.
335
+ Showcase also
336
+ rejects any route segment below 8px and any interior turn segment below 16px;
337
+ ordinary 8–15px endpoint stubs remain valid for fixed lane gaps.
@@ -0,0 +1,47 @@
1
+ import path from 'node:path';
2
+ import { fileURLToPath } from 'node:url';
3
+ import { loadDiagramWithBrandMarks, writeDiagram } from '../shared/cli.mjs';
4
+ import { recordDiagnostic, throwDiagnosticError, withIsolatedDiagnosticRecording } from '../shared/diagnostics.mjs';
5
+ import { compileWorkflow } from './workflow-compiler.mjs';
6
+
7
+ const __dirname = path.dirname(fileURLToPath(import.meta.url));
8
+ const { diagram: workflow, template, outPath, sourceEvidence } = await loadDiagramWithBrandMarks({
9
+ rendererDir: __dirname,
10
+ diagramType: 'workflow',
11
+ defaultExample: 'agent-tool-call.workflow.json'
12
+ });
13
+
14
+ let compiled;
15
+ try {
16
+ compiled = withIsolatedDiagnosticRecording(() => compileWorkflow({
17
+ workflow,
18
+ qualityProfile: process.env.ARCHIFY_QUALITY_PROFILE || workflow.meta?.quality_profile,
19
+ sourceEvidence,
20
+ }));
21
+ } catch (error) {
22
+ // The scope has restored the caller's recording. Keep a typed escape visible
23
+ // alongside earlier failures without publishing abandoned compile attempts.
24
+ if (Array.isArray(error?.archifyDiagnostics)) {
25
+ for (const diagnostic of error.archifyDiagnostics) recordDiagnostic(diagnostic);
26
+ }
27
+ throw error;
28
+ }
29
+
30
+ const layoutJson = process.argv.includes('--layout-json');
31
+
32
+ if (layoutJson) {
33
+ process.stdout.write(`${JSON.stringify(compiled.receipt, null, 2)}\n`);
34
+ if (!compiled.ok) process.exitCode = 1;
35
+ } else if (!compiled.ok) {
36
+ throwDiagnosticError(compiled.error || 'Workflow compilation failed.', compiled.diagnostics);
37
+ } else {
38
+ writeDiagram({
39
+ outPath,
40
+ template,
41
+ diagramType: 'workflow',
42
+ meta: workflow.meta,
43
+ svg: compiled.svg,
44
+ cards: workflow.cards,
45
+ sourceEvidence,
46
+ });
47
+ }