arkaos 4.32.0 → 4.34.0

package/departments/dev/skills/diagram/vendor/schemas/README.md

@@ -0,0 +1,93 @@
+# Archify JSON IR Schemas
+
+Each typed renderer consumes a JSON intermediate representation (IR) validated
+against one of the schemas in this folder before any layout work happens.
+
+## Files
+
+| Schema | Governs | Structural arrays |
+|--------|---------|-------------------|
+| `workflow.schema.json` | `diagram_type: "workflow"` | `lanes`, `phases`, `groups`, `mainPath`, `nodes`, `edges` |
+| `sequence.schema.json` | `diagram_type: "sequence"` | `participants`, `segments`, `messages`, `activations` |
+| `dataflow.schema.json` | `diagram_type: "dataflow"` | `stages`, `nodes`, `flows` |
+| `lifecycle.schema.json` | `diagram_type: "lifecycle"` | `lanes`, `states`, `transitions` |
+| `architecture.schema.json` | `diagram_type: "architecture"` | `components`, `boundaries`, `connections` |
+| `common.schema.json` | shared `$defs` only (no top-level document) | — |
+
+Every diagram schema requires `schema_version`, `diagram_type`, `meta` (with
+`title`), and its structural arrays — except `segments`, `activations`, and
+`cards`, which are optional — and sets `additionalProperties: false` at every
+level, so unknown fields are rejected rather than silently ignored.
+
+Every `meta` object also accepts `animation: "trace"` for opt-in SVG/CSS motion
+in generated HTML. Omit it, or set `"none"`, for the default static output.
+`visual_preset` accepts `classic` (the stable default), `signal-flow` (luminous
+motion-forward presentation), or `blueprint` (high-contrast engineering review).
+Presets change only viewer styling; they do not alter semantic IDs or geometry.
+It may also include up to five guided `views`. Each view has a unique `id`, a
+reader-facing `label`, a non-empty `focus` list of existing semantic node IDs,
+and an optional short `note`.
+
+Every relationship collection (`connections`, `edges`, `messages`, `flows`, and
+`transitions`) accepts an optional author-controlled `id` using the shared ID
+pattern. The renderer keeps its source-order runtime key separately, while the
+authored ID enables a stable `#relation=<id>` viewer link that survives array
+reordering. ID-less documents remain valid and their relationship pins stay
+local to the current page.
+
+## schema_version policy
+
+`schema_version` is `"const": 1`. The constant pins the IR contract: a file
+that validates today keeps validating and rendering on every 2.x release.
+Additive viewer, accessibility, and presentation improvements may enhance the
+generated HTML, but they must not reinterpret authored IR or turn a previously
+valid profile-less v1 file into a new hard layout failure. A breaking change to
+any IR shape bumps the constant to `2`; renderers will then reject version-1
+files with a clear schema error instead of misrendering them. Additive,
+backwards-compatible fields do not bump the version.
+
+## Shared definitions (common.schema.json)
+
+The five diagram schemas reference `common.schema.json#/$defs/...`:
+
+- `id` — element identifiers, pattern `^[a-zA-Z][a-zA-Z0-9_-]*$`
+- `point` — an `[x, y]` pair of numbers (used by `via` and `labelAt`)
+- `componentType` — `frontend`, `backend`, `database`, `cloud`, `security`,
+  `messagebus`, `external`
+- `variant` — `default`, `emphasis`, `security`, `dashed` (sequence messages
+  extend this list locally with `return`)
+- `guidedViews` — the bounded, read-only reader paths accepted by `meta.views`
+- `cards` — the summary-card blocks rendered below the SVG
+
+Lifecycle state `type` is mode-specific (`start`/`active`/`waiting`/...) and
+stays in `lifecycle.schema.json`.
+
+## Runtime validation
+
+At development time, `scripts/generate-validators.mjs` compiles all five
+schemas with ajv's draft 2020-12 standalone generator using `strict: true` and
+`allErrors: true`. The generated `renderers/shared/generated-validators.mjs`
+is committed and shipped with the skill, so runtime validation has no npm or
+network dependency. `renderers/shared/validator.mjs` applies the matching
+standalone validator before the renderer's own layout checks.
+The shared loader then checks cross-collection facts that JSON Schema cannot
+express cleanly here: duplicate view IDs, duplicate focus IDs, focus IDs that do
+not exist in the diagram's semantic collection, and duplicate authored
+relationship IDs within the mode's relationship collection.
+
+`npm test` runs the generator in check mode and fails when the committed
+validators drift from their schemas.
+
+## Error format
+
+Schema violations exit non-zero. Each ajv error is reported on its own line as
+the instance path — annotated with the nearest enclosing element's `id` or
+`label` — followed by the message and parameters:
+
+```text
+workflow schema validation failed:
+  /nodes/3 (id/label: "router") must NOT have additional properties {"additionalProperty":"colour"}
+```
+
+Schemas catch shape errors (types, enums, ranges, unknown fields); geometry
+problems such as overlaps and label collisions are the renderers' job.

package/departments/dev/skills/diagram/vendor/schemas/architecture.schema.json

@@ -0,0 +1,125 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/tt-a1i/archify/schemas/architecture.schema.json",
+  "title": "Archify Architecture Diagram",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema_version", "diagram_type", "meta", "components"],
+  "properties": {
+    "schema_version": { "const": 1 },
+    "diagram_type": { "const": "architecture" },
+    "meta": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["title"],
+      "properties": {
+        "title": { "type": "string", "minLength": 1 },
+        "subtitle": { "type": "string" },
+        "output": { "type": "string" },
+        "animation": { "enum": ["trace", "none"] },
+        "visual_preset": { "enum": ["classic", "signal-flow", "blueprint"] },
+        "quality_profile": { "enum": ["standard", "showcase"] },
+        "views": { "$ref": "common.schema.json#/$defs/guidedViews" },
+        "viewBox": {
+          "type": "array",
+          "prefixItems": [
+            { "type": "number", "minimum": 320 },
+            { "type": "number", "minimum": 240 }
+          ],
+          "items": false,
+          "minItems": 2,
+          "maxItems": 2
+        }
+      }
+    },
+    "layout": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["mode"],
+      "properties": {
+        "mode": { "enum": ["grid"] },
+        "origin": { "$ref": "common.schema.json#/$defs/point" },
+        "cols": { "type": "integer", "minimum": 1, "maximum": 12 },
+        "gapX": { "type": "number", "minimum": 0 },
+        "gapY": { "type": "number", "minimum": 0 },
+        "cellW": { "type": "number", "minimum": 40 },
+        "cellH": { "type": "number", "minimum": 24 }
+      }
+    },
+    "components": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["id", "type", "label"],
+        "properties": {
+          "id": { "$ref": "common.schema.json#/$defs/id" },
+          "type": { "$ref": "common.schema.json#/$defs/componentType" },
+          "label": { "type": "string", "minLength": 1 },
+          "sublabel": { "type": "string" },
+          "tag": { "type": "string" },
+          "row": { "type": "integer", "minimum": 0 },
+          "col": { "type": "integer", "minimum": 0 },
+          "pos": { "$ref": "common.schema.json#/$defs/point" },
+          "size": {
+            "type": "array",
+            "prefixItems": [
+              { "type": "number", "exclusiveMinimum": 0 },
+              { "type": "number", "exclusiveMinimum": 0 }
+            ],
+            "items": false,
+            "minItems": 2,
+            "maxItems": 2
+          }
+        }
+      }
+    },
+    "boundaries": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["kind", "label", "wraps"],
+        "properties": {
+          "kind": { "enum": ["region", "security-group"] },
+          "label": { "type": "string", "minLength": 1 },
+          "wraps": {
+            "type": "array",
+            "minItems": 1,
+            "items": { "$ref": "common.schema.json#/$defs/id" }
+          },
+          "pad": { "type": "number", "minimum": 0 }
+        }
+      }
+    },
+    "connections": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["from", "to"],
+        "properties": {
+          "id": { "$ref": "common.schema.json#/$defs/id" },
+          "from": { "$ref": "common.schema.json#/$defs/id" },
+          "to": { "$ref": "common.schema.json#/$defs/id" },
+          "label": { "type": "string" },
+          "variant": { "$ref": "common.schema.json#/$defs/variant" },
+          "fromSide": { "enum": ["left", "right", "top", "bottom"] },
+          "toSide": { "enum": ["left", "right", "top", "bottom"] },
+          "route": { "enum": ["auto", "straight", "orthogonal-h", "orthogonal-v"] },
+          "via": {
+            "type": "array",
+            "items": { "$ref": "common.schema.json#/$defs/point" }
+          },
+          "labelAt": { "$ref": "common.schema.json#/$defs/point" },
+          "labelDx": { "type": "number" },
+          "labelDy": { "type": "number" },
+          "labelSegment": { "type": "integer", "minimum": 0 },
+          "width": { "type": "number", "minimum": 0.5 }
+        }
+      }
+    },
+    "cards": { "$ref": "common.schema.json#/$defs/cards" }
+  }
+}

package/departments/dev/skills/diagram/vendor/schemas/common.schema.json

@@ -0,0 +1,62 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/tt-a1i/archify/schemas/common.schema.json",
+  "title": "Archify Shared Definitions",
+  "$defs": {
+    "id": {
+      "type": "string",
+      "pattern": "^[a-zA-Z][a-zA-Z0-9_-]*$"
+    },
+    "point": {
+      "type": "array",
+      "prefixItems": [
+        { "type": "number" },
+        { "type": "number" }
+      ],
+      "items": false,
+      "minItems": 2,
+      "maxItems": 2
+    },
+    "componentType": {
+      "enum": ["frontend", "backend", "database", "cloud", "security", "messagebus", "external"]
+    },
+    "variant": {
+      "enum": ["default", "emphasis", "security", "dashed"]
+    },
+    "guidedViews": {
+      "type": "array",
+      "maxItems": 5,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["id", "label", "focus"],
+        "properties": {
+          "id": { "$ref": "#/$defs/id" },
+          "label": { "type": "string", "minLength": 1, "maxLength": 48 },
+          "focus": {
+            "type": "array",
+            "minItems": 1,
+            "items": { "$ref": "#/$defs/id" }
+          },
+          "note": { "type": "string", "maxLength": 140 }
+        }
+      }
+    },
+    "cards": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["dot", "title", "items"],
+        "properties": {
+          "dot": { "enum": ["cyan", "emerald", "violet", "amber", "rose", "orange", "slate"] },
+          "title": { "type": "string", "minLength": 1 },
+          "items": {
+            "type": "array",
+            "items": { "type": "string" }
+          }
+        }
+      }
+    }
+  }
+}

package/departments/dev/skills/diagram/vendor/schemas/dataflow.schema.json

@@ -0,0 +1,240 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/tt-a1i/archify/schemas/dataflow.schema.json",
+  "title": "Archify Data Flow Diagram",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema_version",
+    "diagram_type",
+    "meta",
+    "stages",
+    "nodes",
+    "flows"
+  ],
+  "properties": {
+    "schema_version": {
+      "const": 1
+    },
+    "diagram_type": {
+      "const": "dataflow"
+    },
+    "meta": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "title"
+      ],
+      "properties": {
+        "title": {
+          "type": "string",
+          "minLength": 1
+        },
+        "subtitle": {
+          "type": "string"
+        },
+        "output": {
+          "type": "string"
+        },
+        "animation": {
+          "enum": [
+            "trace",
+            "none"
+          ]
+        },
+        "visual_preset": {
+          "enum": [
+            "classic",
+            "signal-flow",
+            "blueprint"
+          ]
+        },
+        "quality_profile": {
+          "enum": [
+            "standard",
+            "showcase"
+          ]
+        },
+        "views": {
+          "$ref": "common.schema.json#/$defs/guidedViews"
+        },
+        "viewBox": {
+          "type": "array",
+          "prefixItems": [
+            {
+              "type": "number",
+              "minimum": 360
+            },
+            {
+              "type": "number",
+              "minimum": 360
+            }
+          ],
+          "items": false,
+          "minItems": 2,
+          "maxItems": 2
+        }
+      }
+    },
+    "stages": {
+      "type": "array",
+      "minItems": 2,
+      "maxItems": 5,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "label"
+        ],
+        "properties": {
+          "label": {
+            "type": "string",
+            "minLength": 1
+          }
+        }
+      }
+    },
+    "nodes": {
+      "type": "array",
+      "minItems": 2,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "id",
+          "type",
+          "label",
+          "stage",
+          "row"
+        ],
+        "properties": {
+          "id": {
+            "$ref": "common.schema.json#/$defs/id"
+          },
+          "type": {
+            "$ref": "common.schema.json#/$defs/componentType"
+          },
+          "label": {
+            "type": "string",
+            "minLength": 1
+          },
+          "sublabel": {
+            "type": "string"
+          },
+          "tag": {
+            "type": "string"
+          },
+          "stage": {
+            "type": "integer",
+            "minimum": 0
+          },
+          "row": {
+            "type": "integer",
+            "minimum": 0
+          },
+          "width": {
+            "type": "number",
+            "minimum": 48
+          },
+          "height": {
+            "type": "number",
+            "minimum": 36
+          },
+          "yOffset": {
+            "type": "number"
+          }
+        }
+      }
+    },
+    "flows": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "from",
+          "to",
+          "label"
+        ],
+        "properties": {
+          "id": {
+            "$ref": "common.schema.json#/$defs/id"
+          },
+          "from": {
+            "$ref": "common.schema.json#/$defs/id"
+          },
+          "to": {
+            "$ref": "common.schema.json#/$defs/id"
+          },
+          "label": {
+            "type": "string",
+            "minLength": 1
+          },
+          "classification": {
+            "type": "string"
+          },
+          "variant": {
+            "$ref": "common.schema.json#/$defs/variant"
+          },
+          "route": {
+            "enum": [
+              "auto",
+              "straight",
+              "vertical-channel",
+              "bottom-channel",
+              "top-channel"
+            ]
+          },
+          "fromSide": {
+            "enum": [
+              "left",
+              "right",
+              "top",
+              "bottom"
+            ]
+          },
+          "toSide": {
+            "enum": [
+              "left",
+              "right",
+              "top",
+              "bottom"
+            ]
+          },
+          "channelX": {
+            "type": "number"
+          },
+          "channelY": {
+            "type": "number"
+          },
+          "labelAt": {
+            "$ref": "common.schema.json#/$defs/point"
+          },
+          "labelDx": {
+            "type": "number"
+          },
+          "labelDy": {
+            "type": "number"
+          },
+          "labelSegment": {
+            "type": "integer",
+            "minimum": 0
+          },
+          "via": {
+            "type": "array",
+            "items": {
+              "$ref": "common.schema.json#/$defs/point"
+            }
+          },
+          "width": {
+            "type": "number",
+            "minimum": 0.5
+          }
+        }
+      }
+    },
+    "cards": {
+      "$ref": "common.schema.json#/$defs/cards"
+    }
+  }
+}