graphenix-format 1.2.1 → 1.4.0

package/README.md

@@ -1,274 +1,322 @@
-## `@graphenix/format`
-
-TypeScript/JavaScript utilities for working with the **Graphenix Format 1.0.0**:
-
-- **JSON Schema** for validation (`schema/graphenix-format-1.0.0.schema.json`)
-- **Runtime validator** built on [`ajv`](https://ajv.js.org)
-- Lightweight **CRUD helpers** for nodes, edges, types and subgraphs
-- First-class **TypeScript types** for graph documents
-
----
-
-### Install
-
-```bash
-npm install @graphenix/format
-# or
-yarn add @graphenix/format
-```
-
----
-
-### Usage
-
-#### Validate a graph document
-
-```ts
-import { validateGraph, type GraphDocument } from "@graphenix/format";
-
-const doc: GraphDocument = {
-  formatVersion: "1.0.0",
-  id: "graph:auth/user-signup",
-  graph: {
-    nodes: [],
-    edges: [],
-    inputs: [],
-    outputs: []
-  }
-};
-
-const result = validateGraph(doc);
-
-if (!result.valid) {
-  console.error(result.errors);
-}
-```
-
-Each error has:
-
-- **`message`**: human readable message
-- **`path`**: JSON Pointer to the failing instance
-- **`keyword`** and **`params`** from `ajv` for tooling.
-
----
-
-#### Quick start: minimal Graphenix document
-
-This is a minimal but complete **Graphenix Format 1.0.0** document that you can load, validate, and then modify:
-
-```ts
-import {
-  validateGraph,
-  type GraphDocument,
-  addNode,
-  addEdge
-} from "@graphenix/format";
-
-const doc: GraphDocument = {
-  formatVersion: "1.0.0",
-  id: "graph:auth/user-signup",
-  name: "User Signup",
-  graph: {
-    nodes: [
-      {
-        id: "node:validate-input",
-        kind: "builtin:validate",
-        inputs: [
-          {
-            id: "in:payload",
-            direction: "input",
-            type: "builtin:object",
-            required: true
-          }
-        ],
-        outputs: [
-          {
-            id: "out:validated",
-            direction: "output",
-            type: "builtin:object"
-          }
-        ],
-        parameters: {
-          schemaType: "type:User"
-        }
-      }
-    ],
-    edges: [],
-    inputs: [
-      {
-        id: "graph-input:request",
-        name: "Request Body",
-        type: "builtin:object",
-        target: {
-          nodeId: "node:validate-input",
-          portId: "in:payload"
-        }
-      }
-    ],
-    outputs: [],
-    metadata: {}
-  },
-  types: [
-    {
-      id: "type:User",
-      kind: "object",
-      fields: [
-        { name: "id", type: "builtin:string", required: true },
-        { name: "email", type: "builtin:string", required: true }
-      ]
-    }
-  ]
-};
-
-// Validate against the Graphenix JSON Schema
-const res = validateGraph(doc);
-if (!res.valid) {
-  throw new Error(JSON.stringify(res.errors, null, 2));
-}
-
-// Programmatically add a new node + edge
-const withCreateNode = addNode(doc, {
-  id: "node:create-user",
-  kind: "task:http-request",
-  inputs: [
-    {
-      id: "in:validated",
-      direction: "input",
-      type: "type:User",
-      required: true
-    }
-  ],
-  outputs: [
-    {
-      id: "out:user",
-      direction: "output",
-      type: "type:User"
-    }
-  ],
-  parameters: {
-    method: "POST",
-    url: "https://example.com/users"
-  }
-});
-
-const finalDoc = addEdge(withCreateNode, {
-  id: "edge:validate-to-create",
-  from: { nodeId: "node:validate-input", portId: "out:validated" },
-  to: { nodeId: "node:create-user", portId: "in:validated" }
-});
-```
-
-This matches the structure described in `GRAPHENIX-FORMAT.md` and can be fed directly to your executor.
-
----
-
-#### CRUD helpers
-
-CRUD helpers operate on an in-memory `GraphDocument` and return a new document by default (immutable), or mutate in-place when `mutate: true` is passed.
-
-```ts
-import {
-  addNode,
-  updateNode,
-  removeNode,
-  addEdge,
-  removeEdge,
-  addType
-} from "@graphenix/format";
-
-import type { GraphDocument } from "@graphenix/format";
-
-let doc: GraphDocument = /* ... */;
-
-// Add a node (immutable)
-doc = addNode(doc, {
-  id: "node:validate-input",
-  kind: "builtin:validate",
-  inputs: [],
-  outputs: []
-});
-
-// Update a node
-doc = updateNode(doc, "node:validate-input", {
-  name: "Validate Input"
-});
-
-// Remove a node (also removes attached edges and graph IO)
-doc = removeNode(doc, "node:validate-input");
-```
-
-All CRUD helpers accept an optional `{ mutate?: boolean }`:
-
-```ts
-addNode(doc, newNode, { mutate: true }); // modifies `doc` in place
-```
-
-Available helpers:
-
-- **Nodes**: `getNode`, `addNode`, `updateNode`, `removeNode`
-- **Edges**: `getEdge`, `addEdge`, `updateEdge`, `removeEdge`
-- **Types**: `getType`, `addType`, `updateType`, `removeType`
-- **Subgraphs**: `getSubgraph`, `addSubgraph`, `updateSubgraph`, `removeSubgraph`
-
----
-
-### Working with subgraphs and types
-
-Subgraphs are just nested `graph` structures that can be referenced via node `kind`:
-
-```ts
-import {
-  type GraphDocument,
-  addSubgraph,
-  addNode
-} from "@graphenix/format";
-
-let doc: GraphDocument = /* existing document */;
-
-// Add a reusable subgraph
-doc = addSubgraph(doc, {
-  id: "graph:user-validation",
-  name: "User Validation",
-  graph: {
-    nodes: [],
-    edges: [],
-    inputs: [],
-    outputs: []
-  }
-});
-
-// Use it as a node in the main graph
-doc = addNode(doc, {
-  id: "node:user-validation",
-  kind: "subgraph:graph:user-validation",
-  inputs: [],
-  outputs: []
-});
-```
-
-For a full description of all fields and constraints, see `GRAPHENIX-FORMAT.md` in this repo.
-
----
-
-### Build & test locally
-
-```bash
-# install dev dependencies
-npm install
-
-# build ESM + CJS
-npm run build
-
-# run a tiny smoke test that validates the minimal example graph
-npm test
-```
-
-The minimal example graph lives in `src/examples/minimal-graph.ts` and mirrors the example from `GRAPHENIX-FORMAT.md`.
-
----
-
-### Notes
-
-- The package is **execution-agnostic**: it only knows about the static Graphenix format.
-- Runtime concerns (scheduling, retries, parallelism, logging, etc.) are intentionally left to your executor/runtime.
-
+## `@graphenix/format`
+
+TypeScript/JavaScript utilities for working with the **Graphenix Format 1.0.0**:
+
+- **JSON Schema** for validation (`schema/graphenix-format-1.0.0.schema.json`)
+- **Runtime validator** built on [`ajv`](https://ajv.js.org)
+- Lightweight **CRUD helpers** for nodes, edges, types and subgraphs
+- First-class **TypeScript types** for graph documents
+
+---
+
+### Install
+
+```bash
+npm install @graphenix/format
+# or
+yarn add @graphenix/format
+```
+
+---
+
+### Usage
+
+#### Validate a graph document
+
+```ts
+import { validateGraph, type GraphDocument } from "@graphenix/format";
+
+const doc: GraphDocument = {
+  formatVersion: "1.0.0",
+  id: "graph:auth/user-signup",
+  graph: {
+    nodes: [],
+    edges: [],
+    inputs: [],
+    outputs: []
+  }
+};
+
+const result = validateGraph(doc);
+
+if (!result.valid) {
+  console.error(result.errors);
+}
+```
+
+Each error has:
+
+- **`message`**: human readable message
+- **`path`**: JSON Pointer to the failing instance
+- **`keyword`** and **`params`** from `ajv` for tooling.
+
+---
+
+#### Quick start: minimal Graphenix document
+
+This is a minimal but complete **Graphenix Format 1.0.0** document that you can load, validate, and then modify:
+
+```ts
+import {
+  validateGraph,
+  type GraphDocument,
+  addNode,
+  addEdge
+} from "@graphenix/format";
+
+const doc: GraphDocument = {
+  formatVersion: "1.0.0",
+  id: "graph:auth/user-signup",
+  name: "User Signup",
+  graph: {
+    nodes: [
+      {
+        id: "node:validate-input",
+        kind: "builtin:validate",
+        inputs: [
+          {
+            id: "in:payload",
+            direction: "input",
+            type: "builtin:object",
+            required: true
+          }
+        ],
+        outputs: [
+          {
+            id: "out:validated",
+            direction: "output",
+            type: "builtin:object"
+          }
+        ],
+        parameters: {
+          schemaType: "type:User"
+        }
+      }
+    ],
+    edges: [],
+    inputs: [
+      {
+        id: "graph-input:request",
+        name: "Request Body",
+        type: "builtin:object",
+        target: {
+          nodeId: "node:validate-input",
+          portId: "in:payload"
+        }
+      }
+    ],
+    outputs: [],
+    metadata: {}
+  },
+  types: [
+    {
+      id: "type:User",
+      kind: "object",
+      fields: [
+        { name: "id", type: "builtin:string", required: true },
+        { name: "email", type: "builtin:string", required: true }
+      ]
+    }
+  ]
+};
+
+// Validate against the Graphenix JSON Schema
+const res = validateGraph(doc);
+if (!res.valid) {
+  throw new Error(JSON.stringify(res.errors, null, 2));
+}
+
+// Programmatically add a new node + edge
+const withCreateNode = addNode(doc, {
+  id: "node:create-user",
+  kind: "task:http-request",
+  inputs: [
+    {
+      id: "in:validated",
+      direction: "input",
+      type: "type:User",
+      required: true
+    }
+  ],
+  outputs: [
+    {
+      id: "out:user",
+      direction: "output",
+      type: "type:User"
+    }
+  ],
+  parameters: {
+    method: "POST",
+    url: "https://example.com/users"
+  }
+});
+
+const finalDoc = addEdge(withCreateNode, {
+  id: "edge:validate-to-create",
+  from: { nodeId: "node:validate-input", portId: "out:validated" },
+  to: { nodeId: "node:create-user", portId: "in:validated" }
+});
+```
+
+This matches the structure described in `GRAPHENIX-FORMAT.md` and can be fed directly to your executor.
+
+---
+
+#### CRUD helpers
+
+CRUD helpers operate on an in-memory `GraphDocument` and return a new document by default (immutable), or mutate in-place when `mutate: true` is passed.
+
+```ts
+import {
+  addNode,
+  updateNode,
+  removeNode,
+  addEdge,
+  removeEdge,
+  addType
+} from "@graphenix/format";
+
+import type { GraphDocument } from "@graphenix/format";
+
+let doc: GraphDocument = /* ... */;
+
+// Add a node (immutable)
+doc = addNode(doc, {
+  id: "node:validate-input",
+  kind: "builtin:validate",
+  inputs: [],
+  outputs: []
+});
+
+// Update a node
+doc = updateNode(doc, "node:validate-input", {
+  name: "Validate Input"
+});
+
+// Remove a node (also removes attached edges and graph IO)
+doc = removeNode(doc, "node:validate-input");
+```
+
+All CRUD helpers accept an optional `{ mutate?: boolean }`:
+
+```ts
+addNode(doc, newNode, { mutate: true }); // modifies `doc` in place
+```
+
+Available helpers:
+
+- **Nodes**: `getNode`, `addNode`, `updateNode`, `removeNode`
+- **Edges**: `getEdge`, `addEdge`, `updateEdge`, `removeEdge`
+- **Types**: `getType`, `addType`, `updateType`, `removeType`
+- **Subgraphs**: `getSubgraph`, `addSubgraph`, `updateSubgraph`, `removeSubgraph`
+
+---
+
+### Working with subgraphs and types
+
+Subgraphs are just nested `graph` structures that can be referenced via node `kind`:
+
+```ts
+import {
+  type GraphDocument,
+  addSubgraph,
+  addNode
+} from "@graphenix/format";
+
+let doc: GraphDocument = /* existing document */;
+
+// Add a reusable subgraph
+doc = addSubgraph(doc, {
+  id: "graph:user-validation",
+  name: "User Validation",
+  graph: {
+    nodes: [],
+    edges: [],
+    inputs: [],
+    outputs: []
+  }
+});
+
+// Use it as a node in the main graph
+doc = addNode(doc, {
+  id: "node:user-validation",
+  kind: "subgraph:graph:user-validation",
+  inputs: [],
+  outputs: []
+});
+```
+
+For a full description of all fields and constraints, see `GRAPHENIX-FORMAT.md` in this repo.
+
+---
+
+### Build & test locally
+
+```bash
+# install dev dependencies
+npm install
+
+# build ESM + CJS
+npm run build
+
+# run a tiny smoke test that validates the minimal example graph
+npm test
+```
+
+The minimal example graph lives in `src/examples/minimal-graph.ts` and mirrors the example from `GRAPHENIX-FORMAT.md`.
+
+---
+
+### Worox-graph alignment (`metadata.graphEntry` / `metadata.graphResponse`)
+
+Worox-graph attaches **entry** and **response** contracts to graph JSON; graphenix-format exposes the same shapes as **optional fields on the graph document**:
+
+| Field | Type | Role |
+|-------|------|------|
+| `metadata.graphEntry` | `GraphEntryContract` | Entry / execution expectations |
+| `metadata.graphResponse` | `GraphResponseContract` | Final output shape |
+
+**`GraphEntryContract`** may include:
+
+- `summary` — short description of what the graph expects at entry.
+- `requiredExecutionPaths` / `notableExecutionPaths` — path descriptors (engine-specific item shapes).
+- `executionSchema` — JSON Schema for the merged **execution** object after entry (optional tooling validation only).
+
+**`GraphResponseContract`** may include:
+
+- `summary` — description of the response.
+- `finalOutputSchema` — JSON Schema for the **final output** value (optional tooling validation only).
+
+**I/O visibility layers (single narrative for authors):**
+
+- **Layer 01** — **Entry**: what must be satisfied when the graph is invoked; described by `graphEntry` (`summary`, paths, `executionSchema`).
+- **Layer 08** — **Response**: what leaves the graph as the final result; described by `graphResponse` (`summary`, `finalOutputSchema`).
+
+Optional **AJV** checks (not required for graphenix planning):
+
+```ts
+import {
+  validateGraph,
+  validateExecutionAgainstContract,
+  validateFinalOutputAgainstContract,
+  type GraphDocument
+} from "@graphenix/format";
+
+const doc: GraphDocument = /* ... with metadata.graphEntry / metadata.graphResponse ... */;
+
+validateGraph(doc);
+validateExecutionAgainstContract(doc, mergedExecution);
+validateFinalOutputAgainstContract(doc, finalOutput);
+```
+
+For how worox-graph’s task/DAG JSON differs from port-based `Graph`, see [`docs/interop-worox-graph.md`](docs/interop-worox-graph.md).
+
+**Planning-only catalog fields (worox-graph):** optional `metadata.catalogRequests` on the document, and optional `metadata.catalogRequest` / `metadata.catalogBinding` on nodes, align with `@woroces/worox-graph` (`refs.ts`). JSON Schema `$defs` `WoroxCatalogRequest`, `WoroxCatalogBinding`, `WoroxCatalogRequests` describe the same keys for optional cross-validation; execution is unchanged.
+
+---
+
+### Notes
+
+- The package is **execution-agnostic**: it only knows about the static Graphenix format.
+- Runtime concerns (scheduling, retries, parallelism, logging, etc.) are intentionally left to your executor/runtime.
+

package/dist/examples/validate-minimal.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 const validate_1 = require("../validate");
+const validateWorox_1 = require("../validateWorox");
 const minimal_graph_1 = require("./minimal-graph");
 const result = (0, validate_1.validateGraph)(minimal_graph_1.minimalGraph);
 if (!result.valid) {
@@ -10,4 +11,40 @@ if (!result.valid) {
 else {
     console.log("Minimal graph is valid according to Graphenix format 1.0.0");
 }
+const withWoroxMetadata = {
+    ...minimal_graph_1.minimalGraph,
+    metadata: {
+        graphEntry: {
+            summary: "Smoke-test entry contract",
+            requiredExecutionPaths: [["node:validate-input"]],
+            executionSchema: {
+                type: "object",
+                properties: { ok: { type: "boolean" } },
+                required: ["ok"]
+            }
+        },
+        graphResponse: {
+            summary: "Smoke-test response contract",
+            finalOutputSchema: { type: "string", minLength: 1 }
+        }
+    }
+};
+const woroxDoc = (0, validate_1.validateGraph)(withWoroxMetadata);
+if (!woroxDoc.valid) {
+    console.error("Worox metadata document is INVALID", woroxDoc.errors);
+    process.exitCode = 1;
+}
+const execOk = (0, validateWorox_1.validateExecutionAgainstContract)(withWoroxMetadata, { ok: true });
+const execBad = (0, validateWorox_1.validateExecutionAgainstContract)(withWoroxMetadata, {});
+const outOk = (0, validateWorox_1.validateFinalOutputAgainstContract)(withWoroxMetadata, "done");
+const outBad = (0, validateWorox_1.validateFinalOutputAgainstContract)(withWoroxMetadata, "");
+if (!execOk.valid || execBad.valid || !outOk.valid || outBad.valid) {
+    console.error("Worox runtime validation smoke test failed", {
+        execOk,
+        execBad,
+        outOk,
+        outBad
+    });
+    process.exitCode = 1;
+}
 //# sourceMappingURL=validate-minimal.js.map

package/dist/examples/validate-minimal.js.map

@@ -1 +1 @@
-{"version":3,"file":"validate-minimal.js","sourceRoot":"","sources":["../../src/examples/validate-minimal.ts"],"names":[],"mappings":";;AAAA,0CAA4C;AAC5C,mDAA+C;AAE/C,MAAM,MAAM,GAAG,IAAA,wBAAa,EAAC,4BAAY,CAAC,CAAC;AAE3C,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;IAClB,OAAO,CAAC,KAAK,CAAC,0BAA0B,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC;IACzD,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;AACvB,CAAC;KAAM,CAAC;IACN,OAAO,CAAC,GAAG,CAAC,4DAA4D,CAAC,CAAC;AAC5E,CAAC"}
+{"version":3,"file":"validate-minimal.js","sourceRoot":"","sources":["../../src/examples/validate-minimal.ts"],"names":[],"mappings":";;AAAA,0CAA4C;AAC5C,oDAG0B;AAE1B,mDAA+C;AAE/C,MAAM,MAAM,GAAG,IAAA,wBAAa,EAAC,4BAAY,CAAC,CAAC;AAE3C,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;IAClB,OAAO,CAAC,KAAK,CAAC,0BAA0B,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC;IACzD,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;AACvB,CAAC;KAAM,CAAC;IACN,OAAO,CAAC,GAAG,CAAC,4DAA4D,CAAC,CAAC;AAC5E,CAAC;AAED,MAAM,iBAAiB,GAAkB;IACvC,GAAG,4BAAY;IACf,QAAQ,EAAE;QACR,UAAU,EAAE;YACV,OAAO,EAAE,2BAA2B;YACpC,sBAAsB,EAAE,CAAC,CAAC,qBAAqB,CAAC,CAAC;YACjD,eAAe,EAAE;gBACf,IAAI,EAAE,QAAQ;gBACd,UAAU,EAAE,EAAE,EAAE,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,EAAE;gBACvC,QAAQ,EAAE,CAAC,IAAI,CAAC;aACjB;SACF;QACD,aAAa,EAAE;YACb,OAAO,EAAE,8BAA8B;YACvC,iBAAiB,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,SAAS,EAAE,CAAC,EAAE;SACpD;KACF;CACF,CAAC;AAEF,MAAM,QAAQ,GAAG,IAAA,wBAAa,EAAC,iBAAiB,CAAC,CAAC;AAClD,IAAI,CAAC,QAAQ,CAAC,KAAK,EAAE,CAAC;IACpB,OAAO,CAAC,KAAK,CAAC,oCAAoC,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IACrE,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;AACvB,CAAC;AAED,MAAM,MAAM,GAAG,IAAA,gDAAgC,EAAC,iBAAiB,EAAE,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC;AACjF,MAAM,OAAO,GAAG,IAAA,gDAAgC,EAAC,iBAAiB,EAAE,EAAE,CAAC,CAAC;AACxE,MAAM,KAAK,GAAG,IAAA,kDAAkC,EAAC,iBAAiB,EAAE,MAAM,CAAC,CAAC;AAC5E,MAAM,MAAM,GAAG,IAAA,kDAAkC,EAAC,iBAAiB,EAAE,EAAE,CAAC,CAAC;AAEzE,IAAI,CAAC,MAAM,CAAC,KAAK,IAAI,OAAO,CAAC,KAAK,IAAI,CAAC,KAAK,CAAC,KAAK,IAAI,MAAM,CAAC,KAAK,EAAE,CAAC;IACnE,OAAO,CAAC,KAAK,CAAC,4CAA4C,EAAE;QAC1D,MAAM;QACN,OAAO;QACP,KAAK;QACL,MAAM;KACP,CAAC,CAAC;IACH,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;AACvB,CAAC"}

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export * from "./types";
 export * from "./validate";
+export * from "./validateWorox";
 export * from "./crud";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAC;AACxB,cAAc,YAAY,CAAC;AAC3B,cAAc,QAAQ,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAC;AACxB,cAAc,YAAY,CAAC;AAC3B,cAAc,iBAAiB,CAAC;AAChC,cAAc,QAAQ,CAAC"}

package/dist/index.js

@@ -16,5 +16,6 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./types"), exports);
 __exportStar(require("./validate"), exports);
+__exportStar(require("./validateWorox"), exports);
 __exportStar(require("./crud"), exports);
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,0CAAwB;AACxB,6CAA2B;AAC3B,yCAAuB"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,0CAAwB;AACxB,6CAA2B;AAC3B,kDAAgC;AAChC,yCAAuB"}