@jarenjs/flow 0.34.0

package/schemas/jaren-dag.draft-07.schema.json

@@ -0,0 +1,200 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://jarenjs.dev/schemas/jaren-dag/0.1/draft-07",
+  "title": "Jaren dataflow graph 0.1",
+  "description": "Structural grammar of an executable jaren-dag document (see packages/flow/docs/FLOW-FORMAT.md sections 6-7): named nodes from a closed kind vocabulary (input, output, const, query, jslt, task) wired by edges that carry data, with embedded Jaren JSON Query and JSLT documents composed by reference - register those published grammars alongside this artifact. This schema is structural validation only: the compiler remains authoritative for the wiring rules it cannot express - unknown node references, port completeness and uniqueness, acyclicity, the exactly-one-output rule and task-registry resolution are compile-time checks (JF0xxx), and unknown members are ignored for forward compatibility.",
+  "type": "object",
+  "required": [
+    "$dag",
+    "nodes",
+    "edges"
+  ],
+  "properties": {
+    "$dag": {
+      "description": "The dag format version; required.",
+      "const": "0.1"
+    },
+    "nodes": {
+      "description": "Node declarations, id to declaration. The id is what edges reference.",
+      "type": "object",
+      "additionalProperties": {
+        "$ref": "#/definitions/node"
+      }
+    },
+    "edges": {
+      "description": "The wiring: data flows from a node's result to a consumer's input scope, in document order for port-object assembly.",
+      "type": "array",
+      "items": {
+        "$ref": "#/definitions/edge"
+      }
+    }
+  },
+  "definitions": {
+    "node": {
+      "oneOf": [
+        {
+          "description": "Yields the run's input value (null when absent). Accepts no inbound edge.",
+          "type": "object",
+          "properties": {
+            "kind": {
+              "const": "input"
+            },
+            "checkpoint": {
+              "type": "boolean",
+              "description": "Opt-in durable checkpointing (FLOW-FORMAT §7.6): asserts this node's output is JSON-serializable; recorded values are seeded on resume instead of re-evaluated."
+            }
+          },
+          "required": [
+            "kind"
+          ]
+        },
+        {
+          "description": "The run's result is this node's input scope value. Exactly one per document; no outbound edge.",
+          "type": "object",
+          "properties": {
+            "kind": {
+              "const": "output"
+            },
+            "checkpoint": {
+              "type": "boolean",
+              "description": "Opt-in durable checkpointing (FLOW-FORMAT §7.6): asserts this node's output is JSON-serializable; recorded values are seeded on resume instead of re-evaluated."
+            }
+          },
+          "required": [
+            "kind"
+          ]
+        },
+        {
+          "description": "Yields its literal value. Accepts no inbound edge.",
+          "type": "object",
+          "properties": {
+            "kind": {
+              "const": "const"
+            },
+            "value": {
+              "description": "Any JSON value, delivered by reference."
+            },
+            "checkpoint": {
+              "type": "boolean",
+              "description": "Opt-in durable checkpointing (FLOW-FORMAT §7.6): asserts this node's output is JSON-serializable; recorded values are seeded on resume instead of re-evaluated."
+            }
+          },
+          "required": [
+            "kind",
+            "value"
+          ]
+        },
+        {
+          "description": "A Jaren JSON Query evaluated with $ bound to the node's input scope; an empty result yields null.",
+          "type": "object",
+          "properties": {
+            "kind": {
+              "const": "query"
+            },
+            "query": {
+              "description": "The query document.",
+              "allOf": [
+                {
+                  "$ref": "https://jarenjs.dev/schemas/jaren-query/0.1/draft-07"
+                }
+              ]
+            },
+            "checkpoint": {
+              "type": "boolean",
+              "description": "Opt-in durable checkpointing (FLOW-FORMAT §7.6): asserts this node's output is JSON-serializable; recorded values are seeded on resume instead of re-evaluated."
+            }
+          },
+          "required": [
+            "kind",
+            "query"
+          ]
+        },
+        {
+          "description": "A JSLT stylesheet transforming the node's input scope; an empty result yields null.",
+          "type": "object",
+          "properties": {
+            "kind": {
+              "const": "jslt"
+            },
+            "stylesheet": {
+              "description": "The stylesheet document (bare rule array or envelope form).",
+              "allOf": [
+                {
+                  "$ref": "https://jarenjs.dev/schemas/jaren-jslt/0.1/draft-07"
+                }
+              ]
+            },
+            "checkpoint": {
+              "type": "boolean",
+              "description": "Opt-in durable checkpointing (FLOW-FORMAT §7.6): asserts this node's output is JSON-serializable; recorded values are seeded on resume instead of re-evaluated."
+            }
+          },
+          "required": [
+            "kind",
+            "stylesheet"
+          ]
+        },
+        {
+          "description": "A registered async handler, called as handler({ with, input }, signal); the handler must honor the run's shared AbortSignal.",
+          "type": "object",
+          "properties": {
+            "kind": {
+              "const": "task"
+            },
+            "run": {
+              "description": "The compile-time registry handler name.",
+              "type": "string",
+              "minLength": 1
+            },
+            "with": {
+              "description": "Handler props: a query resolved against the node's input scope (null when absent or empty).",
+              "allOf": [
+                {
+                  "$ref": "https://jarenjs.dev/schemas/jaren-query/0.1/draft-07"
+                }
+              ]
+            },
+            "checkpoint": {
+              "type": "boolean",
+              "description": "Opt-in durable checkpointing (FLOW-FORMAT §7.6): asserts this node's output is JSON-serializable; recorded values are seeded on resume instead of re-evaluated."
+            }
+          },
+          "required": [
+            "kind",
+            "run"
+          ]
+        }
+      ]
+    },
+    "edge": {
+      "type": "object",
+      "properties": {
+        "from": {
+          "description": "The producing node id.",
+          "type": "string"
+        },
+        "to": {
+          "description": "The consuming node id.",
+          "type": "string"
+        },
+        "port": {
+          "description": "Names this delivery in the consumer's input-scope object; when any inbound edge of a node is ported, all must be, uniquely.",
+          "type": "string",
+          "minLength": 1
+        },
+        "select": {
+          "description": "A query applied to the source value before delivery; an empty result delivers null.",
+          "allOf": [
+            {
+              "$ref": "https://jarenjs.dev/schemas/jaren-query/0.1/draft-07"
+            }
+          ]
+        }
+      },
+      "required": [
+        "from",
+        "to"
+      ]
+    }
+  }
+}

package/schemas/jaren-dag.schema.json

@@ -0,0 +1,200 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://jarenjs.dev/schemas/jaren-dag/0.1",
+  "title": "Jaren dataflow graph 0.1",
+  "description": "Structural grammar of an executable jaren-dag document (see packages/flow/docs/FLOW-FORMAT.md sections 6-7): named nodes from a closed kind vocabulary (input, output, const, query, jslt, task) wired by edges that carry data, with embedded Jaren JSON Query and JSLT documents composed by reference - register those published grammars alongside this artifact. This schema is structural validation only: the compiler remains authoritative for the wiring rules it cannot express - unknown node references, port completeness and uniqueness, acyclicity, the exactly-one-output rule and task-registry resolution are compile-time checks (JF0xxx), and unknown members are ignored for forward compatibility.",
+  "type": "object",
+  "required": [
+    "$dag",
+    "nodes",
+    "edges"
+  ],
+  "properties": {
+    "$dag": {
+      "description": "The dag format version; required.",
+      "const": "0.1"
+    },
+    "nodes": {
+      "description": "Node declarations, id to declaration. The id is what edges reference.",
+      "type": "object",
+      "additionalProperties": {
+        "$ref": "#/$defs/node"
+      }
+    },
+    "edges": {
+      "description": "The wiring: data flows from a node's result to a consumer's input scope, in document order for port-object assembly.",
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/edge"
+      }
+    }
+  },
+  "$defs": {
+    "node": {
+      "oneOf": [
+        {
+          "description": "Yields the run's input value (null when absent). Accepts no inbound edge.",
+          "type": "object",
+          "properties": {
+            "kind": {
+              "const": "input"
+            },
+            "checkpoint": {
+              "type": "boolean",
+              "description": "Opt-in durable checkpointing (FLOW-FORMAT §7.6): asserts this node's output is JSON-serializable; recorded values are seeded on resume instead of re-evaluated."
+            }
+          },
+          "required": [
+            "kind"
+          ]
+        },
+        {
+          "description": "The run's result is this node's input scope value. Exactly one per document; no outbound edge.",
+          "type": "object",
+          "properties": {
+            "kind": {
+              "const": "output"
+            },
+            "checkpoint": {
+              "type": "boolean",
+              "description": "Opt-in durable checkpointing (FLOW-FORMAT §7.6): asserts this node's output is JSON-serializable; recorded values are seeded on resume instead of re-evaluated."
+            }
+          },
+          "required": [
+            "kind"
+          ]
+        },
+        {
+          "description": "Yields its literal value. Accepts no inbound edge.",
+          "type": "object",
+          "properties": {
+            "kind": {
+              "const": "const"
+            },
+            "value": {
+              "description": "Any JSON value, delivered by reference."
+            },
+            "checkpoint": {
+              "type": "boolean",
+              "description": "Opt-in durable checkpointing (FLOW-FORMAT §7.6): asserts this node's output is JSON-serializable; recorded values are seeded on resume instead of re-evaluated."
+            }
+          },
+          "required": [
+            "kind",
+            "value"
+          ]
+        },
+        {
+          "description": "A Jaren JSON Query evaluated with $ bound to the node's input scope; an empty result yields null.",
+          "type": "object",
+          "properties": {
+            "kind": {
+              "const": "query"
+            },
+            "query": {
+              "description": "The query document.",
+              "allOf": [
+                {
+                  "$ref": "https://jarenjs.dev/schemas/jaren-query/0.1"
+                }
+              ]
+            },
+            "checkpoint": {
+              "type": "boolean",
+              "description": "Opt-in durable checkpointing (FLOW-FORMAT §7.6): asserts this node's output is JSON-serializable; recorded values are seeded on resume instead of re-evaluated."
+            }
+          },
+          "required": [
+            "kind",
+            "query"
+          ]
+        },
+        {
+          "description": "A JSLT stylesheet transforming the node's input scope; an empty result yields null.",
+          "type": "object",
+          "properties": {
+            "kind": {
+              "const": "jslt"
+            },
+            "stylesheet": {
+              "description": "The stylesheet document (bare rule array or envelope form).",
+              "allOf": [
+                {
+                  "$ref": "https://jarenjs.dev/schemas/jaren-jslt/0.1"
+                }
+              ]
+            },
+            "checkpoint": {
+              "type": "boolean",
+              "description": "Opt-in durable checkpointing (FLOW-FORMAT §7.6): asserts this node's output is JSON-serializable; recorded values are seeded on resume instead of re-evaluated."
+            }
+          },
+          "required": [
+            "kind",
+            "stylesheet"
+          ]
+        },
+        {
+          "description": "A registered async handler, called as handler({ with, input }, signal); the handler must honor the run's shared AbortSignal.",
+          "type": "object",
+          "properties": {
+            "kind": {
+              "const": "task"
+            },
+            "run": {
+              "description": "The compile-time registry handler name.",
+              "type": "string",
+              "minLength": 1
+            },
+            "with": {
+              "description": "Handler props: a query resolved against the node's input scope (null when absent or empty).",
+              "allOf": [
+                {
+                  "$ref": "https://jarenjs.dev/schemas/jaren-query/0.1"
+                }
+              ]
+            },
+            "checkpoint": {
+              "type": "boolean",
+              "description": "Opt-in durable checkpointing (FLOW-FORMAT §7.6): asserts this node's output is JSON-serializable; recorded values are seeded on resume instead of re-evaluated."
+            }
+          },
+          "required": [
+            "kind",
+            "run"
+          ]
+        }
+      ]
+    },
+    "edge": {
+      "type": "object",
+      "properties": {
+        "from": {
+          "description": "The producing node id.",
+          "type": "string"
+        },
+        "to": {
+          "description": "The consuming node id.",
+          "type": "string"
+        },
+        "port": {
+          "description": "Names this delivery in the consumer's input-scope object; when any inbound edge of a node is ported, all must be, uniquely.",
+          "type": "string",
+          "minLength": 1
+        },
+        "select": {
+          "description": "A query applied to the source value before delivery; an empty result delivers null.",
+          "allOf": [
+            {
+              "$ref": "https://jarenjs.dev/schemas/jaren-query/0.1"
+            }
+          ]
+        }
+      },
+      "required": [
+        "from",
+        "to"
+      ]
+    }
+  }
+}

package/schemas/jaren-fsm.draft-07.schema.json

@@ -0,0 +1,127 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://jarenjs.dev/schemas/jaren-fsm/0.1/draft-07",
+  "title": "Jaren finite state machine 0.1",
+  "description": "Structural grammar of an executable jaren-fsm document (see packages/flow/docs/FLOW-FORMAT.md): declared states, an initial state and a document-ordered transition table whose guards and effect props are Jaren JSON Query documents — register the published query grammar alongside this artifact. The shape is a strict superset of the mermaid state-diagram projection ('jaren-workflow'): its version key is optional, a plain-string guard is a query document (a $-path expression; any other non-empty string is a literal and therefore always true), and null means no guard / any event. This schema is structural validation only: the compiler remains authoritative for semantic rules it cannot express — undeclared state references, duplicate ids and guard compilability are compile-time checks (JF0xxx), and unknown members are ignored for forward compatibility.",
+  "type": "object",
+  "properties": {
+    "$fsm": {
+      "description": "The fsm format version; absent implies 0.1.",
+      "const": "0.1"
+    },
+    "initial": {
+      "description": "The id of the machine's initial state, or null when the document does not choose one (a session must then be started with an explicit state).",
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "states": {
+      "description": "Declared states, in document order. A string is shorthand for { id }.",
+      "type": "array",
+      "items": {
+        "anyOf": [
+          {
+            "type": "string"
+          },
+          {
+            "type": "object",
+            "properties": {
+              "id": {
+                "description": "The state id transitions refer to.",
+                "type": "string"
+              },
+              "entry": {
+                "$ref": "#/definitions/effects"
+              },
+              "exit": {
+                "$ref": "#/definitions/effects"
+              },
+              "final": {
+                "description": "Marks a terminal state; a session reports done here.",
+                "type": "boolean"
+              }
+            },
+            "required": [
+              "id"
+            ]
+          }
+        ]
+      }
+    },
+    "transitions": {
+      "description": "The transition table. Document order IS the selection order: the first entry whose from-state, event (a null or absent event matches any name) and guard all match fires.",
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "from": {
+            "description": "The state this transition leaves.",
+            "type": "string"
+          },
+          "event": {
+            "description": "The event name this transition answers; null or absent matches any event (a wildcard). A transition never fires spontaneously.",
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "guard": {
+            "description": "A Jaren JSON Query document asserted by effective boolean value against the evaluation scope { state, event, payload, context }; null or absent means no guard. A plain string not starting with '$' is a literal and therefore always true — projection-produced display guards are vacuous by design.",
+            "anyOf": [
+              {
+                "type": "null"
+              },
+              {
+                "$ref": "https://jarenjs.dev/schemas/jaren-query/0.1/draft-07"
+              }
+            ]
+          },
+          "to": {
+            "description": "The state this transition enters.",
+            "type": "string"
+          },
+          "effects": {
+            "$ref": "#/definitions/effects"
+          }
+        },
+        "required": [
+          "from",
+          "to"
+        ]
+      }
+    }
+  },
+  "required": [
+    "initial",
+    "states",
+    "transitions"
+  ],
+  "definitions": {
+    "effects": {
+      "description": "Effect descriptors, returned as resolved data when their state or transition fires — the engine never executes them.",
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "run": {
+            "description": "The host-registered handler name.",
+            "type": "string",
+            "minLength": 1
+          },
+          "with": {
+            "description": "Handler props: a Jaren JSON Query document evaluated against the scope at fire time; an empty result omits the member.",
+            "allOf": [
+              {
+                "$ref": "https://jarenjs.dev/schemas/jaren-query/0.1/draft-07"
+              }
+            ]
+          }
+        },
+        "required": [
+          "run"
+        ]
+      }
+    }
+  }
+}

package/schemas/jaren-fsm.schema.json

@@ -0,0 +1,94 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://jarenjs.dev/schemas/jaren-fsm/0.1",
+  "title": "Jaren finite state machine 0.1",
+  "description": "Structural grammar of an executable jaren-fsm document (see packages/flow/docs/FLOW-FORMAT.md): declared states, an initial state and a document-ordered transition table whose guards and effect props are Jaren JSON Query documents — register the published query grammar alongside this artifact. The shape is a strict superset of the mermaid state-diagram projection ('jaren-workflow'): its version key is optional, a plain-string guard is a query document (a $-path expression; any other non-empty string is a literal and therefore always true), and null means no guard / any event. This schema is structural validation only: the compiler remains authoritative for semantic rules it cannot express — undeclared state references, duplicate ids and guard compilability are compile-time checks (JF0xxx), and unknown members are ignored for forward compatibility.",
+  "type": "object",
+  "properties": {
+    "$fsm": {
+      "description": "The fsm format version; absent implies 0.1.",
+      "const": "0.1"
+    },
+    "initial": {
+      "description": "The id of the machine's initial state, or null when the document does not choose one (a session must then be started with an explicit state).",
+      "type": ["string", "null"]
+    },
+    "states": {
+      "description": "Declared states, in document order. A string is shorthand for { id }.",
+      "type": "array",
+      "items": {
+        "anyOf": [
+          { "type": "string" },
+          {
+            "type": "object",
+            "properties": {
+              "id": {
+                "description": "The state id transitions refer to.",
+                "type": "string"
+              },
+              "entry": { "$ref": "#/$defs/effects" },
+              "exit": { "$ref": "#/$defs/effects" },
+              "final": {
+                "description": "Marks a terminal state; a session reports done here.",
+                "type": "boolean"
+              }
+            },
+            "required": ["id"]
+          }
+        ]
+      }
+    },
+    "transitions": {
+      "description": "The transition table. Document order IS the selection order: the first entry whose from-state, event (a null or absent event matches any name) and guard all match fires.",
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "from": {
+            "description": "The state this transition leaves.",
+            "type": "string"
+          },
+          "event": {
+            "description": "The event name this transition answers; null or absent matches any event (a wildcard). A transition never fires spontaneously.",
+            "type": ["string", "null"]
+          },
+          "guard": {
+            "description": "A Jaren JSON Query document asserted by effective boolean value against the evaluation scope { state, event, payload, context }; null or absent means no guard. A plain string not starting with '$' is a literal and therefore always true — projection-produced display guards are vacuous by design.",
+            "anyOf": [
+              { "type": "null" },
+              { "$ref": "https://jarenjs.dev/schemas/jaren-query/0.1" }
+            ]
+          },
+          "to": {
+            "description": "The state this transition enters.",
+            "type": "string"
+          },
+          "effects": { "$ref": "#/$defs/effects" }
+        },
+        "required": ["from", "to"]
+      }
+    }
+  },
+  "required": ["initial", "states", "transitions"],
+  "$defs": {
+    "effects": {
+      "description": "Effect descriptors, returned as resolved data when their state or transition fires — the engine never executes them.",
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "run": {
+            "description": "The host-registered handler name.",
+            "type": "string",
+            "minLength": 1
+          },
+          "with": {
+            "description": "Handler props: a Jaren JSON Query document evaluated against the scope at fire time; an empty result omits the member.",
+            "allOf": [{ "$ref": "https://jarenjs.dev/schemas/jaren-query/0.1" }]
+          }
+        },
+        "required": ["run"]
+      }
+    }
+  }
+}