@echelon-foundry/design-system 0.3.0 → 0.4.0-main.222.1

package/docs/workflow/VALIDATION.md

@@ -0,0 +1,91 @@
+# Validating workflows
+
+Validation does not need Forma Studio. CI, Praxis, agents and external
+applications all use the same implementation: `Forma.Workflow.Validation`. It
+is available through the CLI, the .NET library and the browser package.
+
+## Command line
+
+```bash
+dotnet run --project src/workflow/Forma.Workflow.Cli -c Release -- validate forma/workflows/*.forma-workflow.json
+dotnet run --project src/workflow/Forma.Workflow.Cli -c Release -- validate --json forma/workflows/launch.forma-workflow.json
+```
+
+| Exit code | Meaning |
+|---|---|
+| 0 | Every file is valid. That includes valid with preserved extensions, valid with unavailable capabilities, and automatically migrated. |
+| 1 | At least one file is invalid or needs a migration that cannot run automatically. |
+| 2 | Invalid arguments. |
+| 3 | A file could not be read. |
+
+`--json` prints a report for each file:
+
+```json
+[
+  {
+    "file": "forma/workflows/extensions.forma-workflow.json",
+    "report": {
+      "class": "supported-with-preserved-extensions",
+      "valid": true,
+      "workflow": "extensions",
+      "formatVersion": "1.0.0",
+      "capabilities": ["workflow.core"],
+      "extensions": ["com.example.scheduler", "org.example.audit", "gov.nasa.example.range"],
+      "findings": []
+    }
+  }
+]
+```
+
+## .NET
+
+```fsharp
+open Forma.Workflow
+
+let report = Validation.load (System.IO.File.ReadAllText "forma/workflows/launch.forma-workflow.json")
+match report.Class with
+| FullySupported | SupportedWithPreservedExtensions _ -> printfn "ok"
+| UnavailableCapabilities caps -> printfn "needs a newer Forma: %A" caps
+| MigrationRequired(from, target, automatic, reason) -> printfn "%s" reason
+| StructurallyInvalid | SemanticallyInvalid ->
+    for f in report.Findings do printfn "%s %s %s" f.Code f.Pointer f.Message
+```
+
+## Browser
+
+```js
+const report = await document.querySelector("forma-workflow").validate(workflowObject);
+```
+
+## Compatibility classes
+
+| Class | When |
+|---|---|
+| `fully-supported` | Valid, and everything in it is understood. |
+| `supported-with-preserved-extensions` | Valid, and it carries namespaced extensions that Forma preserves but does not interpret. |
+| `migration-required` | It declares another `formatVersion`. `migration.automatic` says whether Forma migrated it. |
+| `structurally-invalid` | Not JSON, has duplicate keys, has the wrong `format`, or violates the published schema. |
+| `semantically-invalid` | Schema-valid, but has broken references, ids, ports, membership, unsafe URLs or failed static accessibility rules. The document still decodes, so an editor can show the findings without deleting anyone's data. |
+| `unavailable-capabilities` | Valid format, but it needs capabilities the target `forma.version` lacks, or capabilities this Forma does not provide. |
+
+## What is checked
+
+Structure is checked against the published schema file itself. A small built-in
+JSON Schema validator enforces it, so there is no hand-maintained copy.
+
+| Area | Finding codes |
+|---|---|
+| JSON | `JSON` (malformed, duplicate keys, more than 64 levels deep, larger than 16 MB) |
+| Format | `FORMAT`, `FORMAT-VERSION`, `FORMAT-MIGRATED` |
+| Schema | `SCHEMA` (with a JSON Pointer) |
+| Identity | `ID-DUPLICATE`, `ID-DUPLICATE-PORT`, `ID-DUPLICATE-REFERENCE`, `ID-DUPLICATE-LEGEND` |
+| References | `REF-DANGLING-EDGE`, `REF-MISSING-PORT`, `REF-INTERACTION-TARGET`, `REF-PALETTE` |
+| Ports | `PORT-DIRECTION`, `PORT-CARDINALITY` |
+| Groups | `GROUP-MISSING-MEMBER`, `GROUP-MISSING-PARENT`, `GROUP-CYCLE`, `GROUP-LANE-CONFLICT` |
+| Extensions | `EXT-RESERVED` (and the schema's namespace and object rules) |
+| Compatibility | `COMPAT-UNAVAILABLE`, `COMPAT-UNKNOWN-CAPABILITY` |
+| Accessibility (static) | `A11Y-TITLE`, `A11Y-NAME`, `A11Y-CONTRAST` (authored text colour against fill below 4.5:1), `A11Y-BRANCH-LABEL`, `A11Y-LEGEND` |
+| Security | `SEC-UNSAFE-URL` (anything other than http, https, mailto or relative; also control characters and leading spaces), `SEC-BIDI-CONTROL` |
+| Semantics (warnings) | `SEM-DECISION-BRANCHES`, `SEM-START-INCOMING`, `SEM-END-OUTGOING`, `LAYOUT-PARTIAL` |
+
+Errors decide the class. Warnings and notes do not.

package/examples/workflows/fixtures.json

@@ -0,0 +1,101 @@
+{
+  "description": "Executable compatibility fixtures for the Forma portable workflow format. Each entry names the file, the compatibility class Forma validation must report, and what it proves. tests/workflow runs every entry.",
+  "formatVersion": "1.0.0",
+  "fixtures": [
+    {
+      "id": "minimal",
+      "class": "fully-supported",
+      "proves": "The smallest valid workflow: one node, no layout."
+    },
+    {
+      "id": "multi-step",
+      "class": "fully-supported",
+      "proves": "A linear multi-step workflow with provenance."
+    },
+    {
+      "id": "branching",
+      "class": "fully-supported",
+      "proves": "A decision with labelled conditional branches and a loop back."
+    },
+    {
+      "id": "groups",
+      "class": "fully-supported",
+      "proves": "Groups and containers with explicit membership and nesting."
+    },
+    {
+      "id": "swimlanes",
+      "class": "fully-supported",
+      "proves": "Swimlanes and a phase that crosses lanes."
+    },
+    {
+      "id": "colored",
+      "class": "fully-supported",
+      "proves": "Literal, token and palette colours unrelated to status, with a legend (FMD-TEST-007)."
+    },
+    {
+      "id": "node-metadata",
+      "class": "fully-supported",
+      "proves": "Arbitrary node and workflow metadata, plus typed domain references."
+    },
+    {
+      "id": "edge-metadata",
+      "class": "fully-supported",
+      "proves": "Edge metadata, semantic edge kinds and edge status."
+    },
+    {
+      "id": "extensions",
+      "class": "supported-with-preserved-extensions",
+      "proves": "Namespaced extension data at workflow, node and edge level survives unchanged."
+    },
+    {
+      "id": "no-layout",
+      "class": "fully-supported",
+      "proves": "A workflow with no coordinates; the deterministic default layout places it."
+    },
+    {
+      "id": "accessible",
+      "class": "fully-supported",
+      "proves": "Accessible names and descriptions, and labelled branches."
+    },
+    {
+      "id": "mobile",
+      "class": "fully-supported",
+      "proves": "A top-to-bottom compact workflow for narrow screens."
+    },
+    {
+      "id": "branded",
+      "class": "fully-supported",
+      "proves": "Token-backed palette slots that a Forma brand restyles."
+    },
+    {
+      "id": "embedded-view",
+      "class": "fully-supported",
+      "proves": "Runtime status projected onto a read-only embedded workflow."
+    },
+    {
+      "id": "embedded-edit",
+      "class": "supported-with-preserved-extensions",
+      "proves": "Ports, interaction intents and host extension data in an editable embedded workflow."
+    },
+    {
+      "id": "static-export",
+      "class": "fully-supported",
+      "proves": "Authored geometry; the reference for static HTML export (exports/static-export.*.html)."
+    },
+    {
+      "id": "interactive-export",
+      "class": "fully-supported",
+      "proves": "Declarative interaction intents; the reference for interactive HTML export (exports/interactive-export.document.html)."
+    },
+    {
+      "id": "runtime-ports",
+      "class": "fully-supported",
+      "proves": "Ports with direction and cardinality, core and namespaced status states."
+    },
+    {
+      "id": "color-mapping",
+      "class": "supported-with-preserved-extensions",
+      "proves": "An explicit producer metadata-to-colour mapping with a legend (FMD-TEST-008)."
+    }
+  ]
+}

package/examples/workflows/forma/workflows/accessible.forma-workflow.json

@@ -0,0 +1,90 @@
+{
+  "$schema": "https://forma.echelonfoundry.com/schemas/workflow/1.0/forma-workflow.schema.json",
+  "format": "forma-workflow",
+  "formatVersion": "1.0.0",
+  "id": "accessible",
+  "title": "Docking approach",
+  "description": "Every branch is labelled so the paths are distinguishable without seeing the diagram.",
+  "language": "en",
+  "direction": "ltr",
+  "forma": {
+    "version": "0.4.0"
+  },
+  "nodes": [
+    {
+      "id": "approach",
+      "kind": "start",
+      "label": "Begin approach",
+      "accessibility": {
+        "description": "The spacecraft starts its final approach at 200 metres."
+      }
+    },
+    {
+      "id": "check",
+      "kind": "decision",
+      "label": "Alignment within limits?",
+      "accessibility": {
+        "name": "Decision: is alignment within limits?"
+      }
+    },
+    {
+      "id": "capture",
+      "kind": "task",
+      "label": "Soft capture"
+    },
+    {
+      "id": "abort",
+      "kind": "task",
+      "label": "Abort and back away"
+    },
+    {
+      "id": "docked",
+      "kind": "end",
+      "label": "Docked"
+    }
+  ],
+  "edges": [
+    {
+      "id": "a1",
+      "source": {
+        "node": "approach"
+      },
+      "target": {
+        "node": "check"
+      }
+    },
+    {
+      "id": "a2",
+      "source": {
+        "node": "check"
+      },
+      "target": {
+        "node": "capture"
+      },
+      "label": "Within limits",
+      "accessibility": {
+        "description": "Normal path."
+      }
+    },
+    {
+      "id": "a3",
+      "source": {
+        "node": "check"
+      },
+      "target": {
+        "node": "abort"
+      },
+      "label": "Out of limits",
+      "line": "dashed"
+    },
+    {
+      "id": "a4",
+      "source": {
+        "node": "capture"
+      },
+      "target": {
+        "node": "docked"
+      }
+    }
+  ]
+}

package/examples/workflows/forma/workflows/branching.forma-workflow.json

@@ -0,0 +1,91 @@
+{
+  "$schema": "https://forma.echelonfoundry.com/schemas/workflow/1.0/forma-workflow.schema.json",
+  "format": "forma-workflow",
+  "formatVersion": "1.0.0",
+  "id": "branching",
+  "title": "Launch readiness poll",
+  "forma": {
+    "version": "0.4.0"
+  },
+  "nodes": [
+    {
+      "id": "poll",
+      "kind": "start",
+      "label": "Begin readiness poll"
+    },
+    {
+      "id": "go",
+      "kind": "decision",
+      "label": "All stations go?"
+    },
+    {
+      "id": "hold",
+      "kind": "task",
+      "label": "Call a hold"
+    },
+    {
+      "id": "resolve",
+      "kind": "task",
+      "label": "Resolve the issue"
+    },
+    {
+      "id": "launch",
+      "kind": "end",
+      "label": "Proceed to launch"
+    }
+  ],
+  "edges": [
+    {
+      "id": "e-poll",
+      "source": {
+        "node": "poll"
+      },
+      "target": {
+        "node": "go"
+      }
+    },
+    {
+      "id": "e-yes",
+      "source": {
+        "node": "go"
+      },
+      "target": {
+        "node": "launch"
+      },
+      "kind": "conditional",
+      "label": "Go"
+    },
+    {
+      "id": "e-no",
+      "source": {
+        "node": "go"
+      },
+      "target": {
+        "node": "hold"
+      },
+      "kind": "conditional",
+      "label": "No go",
+      "line": "dashed"
+    },
+    {
+      "id": "e-fix",
+      "source": {
+        "node": "hold"
+      },
+      "target": {
+        "node": "resolve"
+      }
+    },
+    {
+      "id": "e-repoll",
+      "source": {
+        "node": "resolve"
+      },
+      "target": {
+        "node": "go"
+      },
+      "label": "Repoll",
+      "line": "dotted"
+    }
+  ]
+}

package/examples/workflows/forma/workflows/branded.forma-workflow.json

@@ -0,0 +1,85 @@
+{
+  "$schema": "https://forma.echelonfoundry.com/schemas/workflow/1.0/forma-workflow.schema.json",
+  "format": "forma-workflow",
+  "formatVersion": "1.0.0",
+  "id": "branded",
+  "title": "Partner mission review",
+  "description": "Uses only token-backed palette slots, so a Forma brand restyles it without editing the workflow.",
+  "forma": {
+    "version": "0.4.0"
+  },
+  "palette": {
+    "primary": "token:surface-secondary",
+    "accent": "token:accent-primary"
+  },
+  "nodes": [
+    {
+      "id": "brief",
+      "kind": "task",
+      "label": "Partner briefing",
+      "color": {
+        "fill": "palette:primary",
+        "foreground": "token:text-primary"
+      }
+    },
+    {
+      "id": "review",
+      "kind": "task",
+      "label": "Joint review",
+      "color": {
+        "accent": "palette:accent"
+      }
+    },
+    {
+      "id": "signoff",
+      "kind": "end",
+      "label": "Joint sign-off",
+      "color": {
+        "stroke": "palette:accent"
+      }
+    }
+  ],
+  "edges": [
+    {
+      "id": "b1",
+      "source": {
+        "node": "brief"
+      },
+      "target": {
+        "node": "review"
+      }
+    },
+    {
+      "id": "b2",
+      "source": {
+        "node": "review"
+      },
+      "target": {
+        "node": "signoff"
+      },
+      "color": {
+        "stroke": "palette:accent"
+      }
+    }
+  ],
+  "presentation": {
+    "legend": [
+      {
+        "id": "partner",
+        "label": "Partner-owned step",
+        "description": "brand surface fill",
+        "color": {
+          "fill": "palette:primary"
+        }
+      },
+      {
+        "id": "joint",
+        "label": "Joint step",
+        "description": "brand accent",
+        "color": {
+          "accent": "palette:accent"
+        }
+      }
+    ]
+  }
+}

package/examples/workflows/forma/workflows/color-mapping.forma-workflow.json

@@ -0,0 +1,111 @@
+{
+  "$schema": "https://forma.echelonfoundry.com/schemas/workflow/1.0/forma-workflow.schema.json",
+  "format": "forma-workflow",
+  "formatVersion": "1.0.0",
+  "id": "color-mapping",
+  "title": "Risk-coded review queue",
+  "description": "Colours come from an explicit mapping the producer applied to the metadata field risk. The mapping belongs to the producer; Forma only renders the resolved colours. Risk is also stated in text.",
+  "forma": {
+    "version": "0.4.0"
+  },
+  "nodes": [
+    {
+      "id": "r1",
+      "kind": "task",
+      "label": "Thermal model update",
+      "metadata": {
+        "risk": "high"
+      },
+      "color": {
+        "fill": "#fde2e1",
+        "accent": "#9b1c1c",
+        "foreground": "#1d1d1b"
+      }
+    },
+    {
+      "id": "r2",
+      "kind": "task",
+      "label": "Antenna re-point",
+      "metadata": {
+        "risk": "medium"
+      },
+      "color": {
+        "fill": "#fff1d6",
+        "accent": "#8a5300",
+        "foreground": "#1d1d1b"
+      }
+    },
+    {
+      "id": "r3",
+      "kind": "task",
+      "label": "Battery trend report",
+      "metadata": {
+        "risk": "low"
+      },
+      "color": {
+        "fill": "#e3f4e8",
+        "accent": "#1e6b3a",
+        "foreground": "#1d1d1b"
+      }
+    }
+  ],
+  "edges": [
+    {
+      "id": "q1",
+      "source": {
+        "node": "r1"
+      },
+      "target": {
+        "node": "r2"
+      }
+    },
+    {
+      "id": "q2",
+      "source": {
+        "node": "r2"
+      },
+      "target": {
+        "node": "r3"
+      }
+    }
+  ],
+  "presentation": {
+    "legendTitle": "Key: risk (producer mapping of metadata field risk)",
+    "legend": [
+      {
+        "id": "high",
+        "label": "High risk",
+        "color": {
+          "fill": "#fde2e1",
+          "accent": "#9b1c1c"
+        }
+      },
+      {
+        "id": "medium",
+        "label": "Medium risk",
+        "color": {
+          "fill": "#fff1d6",
+          "accent": "#8a5300"
+        }
+      },
+      {
+        "id": "low",
+        "label": "Low risk",
+        "color": {
+          "fill": "#e3f4e8",
+          "accent": "#1e6b3a"
+        }
+      }
+    ]
+  },
+  "extensions": {
+    "com.example.riskboard": {
+      "mapping": {
+        "field": "risk",
+        "high": "#fde2e1",
+        "medium": "#fff1d6",
+        "low": "#e3f4e8"
+      }
+    }
+  }
+}

package/examples/workflows/forma/workflows/colored.forma-workflow.json

@@ -0,0 +1,131 @@
+{
+  "$schema": "https://forma.echelonfoundry.com/schemas/workflow/1.0/forma-workflow.schema.json",
+  "format": "forma-workflow",
+  "formatVersion": "1.0.0",
+  "id": "colored",
+  "title": "Mission operations by team",
+  "description": "Fill colour shows the owning team. It says nothing about status: each step states its status in text.",
+  "forma": {
+    "version": "0.4.0"
+  },
+  "palette": {
+    "archive": "token:surface-secondary"
+  },
+  "nodes": [
+    {
+      "id": "plan",
+      "kind": "task",
+      "label": "Plan the pass",
+      "color": {
+        "fill": "#e8f0ff",
+        "accent": "#2f5fb3",
+        "foreground": "#1d1d1b"
+      },
+      "status": {
+        "state": "complete"
+      }
+    },
+    {
+      "id": "uplink",
+      "kind": "task",
+      "label": "Uplink commands",
+      "color": {
+        "fill": "#e8f0ff",
+        "accent": "#2f5fb3",
+        "foreground": "#1d1d1b"
+      },
+      "status": {
+        "state": "active"
+      }
+    },
+    {
+      "id": "downlink",
+      "kind": "task",
+      "label": "Receive telemetry",
+      "color": {
+        "fill": "#fff1d6",
+        "accent": "#8a5300",
+        "foreground": "#1d1d1b"
+      },
+      "status": {
+        "state": "pending"
+      }
+    },
+    {
+      "id": "archive",
+      "kind": "end",
+      "label": "Archive the pass",
+      "color": {
+        "fill": "palette:archive",
+        "foreground": "token:text-primary"
+      }
+    }
+  ],
+  "edges": [
+    {
+      "id": "c1",
+      "source": {
+        "node": "plan"
+      },
+      "target": {
+        "node": "uplink"
+      }
+    },
+    {
+      "id": "c2",
+      "source": {
+        "node": "uplink"
+      },
+      "target": {
+        "node": "downlink"
+      },
+      "color": {
+        "stroke": "#2f5fb3"
+      },
+      "width": 3
+    },
+    {
+      "id": "c3",
+      "source": {
+        "node": "downlink"
+      },
+      "target": {
+        "node": "archive"
+      },
+      "color": {
+        "stroke": "token:accent-secondary"
+      }
+    }
+  ],
+  "presentation": {
+    "legendTitle": "Key: fill colour by owning team",
+    "legend": [
+      {
+        "id": "ops",
+        "label": "Flight operations",
+        "description": "blue fill",
+        "color": {
+          "fill": "#e8f0ff",
+          "accent": "#2f5fb3"
+        }
+      },
+      {
+        "id": "ground",
+        "label": "Ground network",
+        "description": "amber fill",
+        "color": {
+          "fill": "#fff1d6",
+          "accent": "#8a5300"
+        }
+      },
+      {
+        "id": "data",
+        "label": "Data systems",
+        "description": "neutral fill",
+        "color": {
+          "fill": "palette:archive"
+        }
+      }
+    ]
+  }
+}