@jarenjs/flow 0.46.5 → 0.56.0

package/README.md

@@ -190,7 +190,7 @@ built with `@jarenjs/flow` and XState v5 and asserted to agree before
 timing:
 
 - **Transitions** — the pure `step` runs several times faster than an
-  XState actor's `send` (≈<!--bm:flow.fsmBand-->5.6–8.1<!--/bm-->× across 5/50/500-state machines); the
+  XState actor's `send` (≈<!--fact:flow.fsmBand-->5.6–8.1<!--/fact-->× across 5/50/500-state machines); the
   `createFsmSession` wrapper is on the page too.
 - **Compile** — `compileFsm` beats `createMachine` + `createActor`
   ≈1.5–2.6×. Not like-for-like: XState builds a scheduling actor, so the
@@ -227,6 +227,40 @@ section shows the `composeChecks(schema, compileGate)` recipe, and
 runs a model as an ordinary dag `task`. Neither package imports the
 other — the composition is data.
 
+## Authoring by code
+
+The same documents have a by-code twin. `@jarenjs/linq/flow` is the
+suite's pen for both formats: state ids, event names and node ids are
+literal types, so a transition into an undeclared state or an edge from
+an undeclared node is a compile error, and guards, effect props, node
+queries and edge selectors are callbacks captured over the scope the
+engine evaluates them in — never a path typed as a string.
+
+```javascript
+import { defineFsm, on, state, effect } from '@jarenjs/linq/flow';
+
+const doc = defineFsm({
+  initial: 'idle',
+  states: [
+    'idle',
+    state('loading', { entry: [effect('fetch', (s) => ({ url: s.context.url }))] }),
+    state('done', { final: true }),
+  ],
+  transitions: [
+    on('idle', 'start').to('loading'),
+    on('loading', 'ok').when((s) => s.payload.fresh).to('done'),
+    on('loading', 'fail').to('idle'),
+  ],
+});                                // the document at the top of this README, byte for byte
+
+compileFsm(doc).step('idle', 'start', { context: { url: '/rows' } });
+```
+
+A model-authored document and a pen-written one go through the SAME
+gate — `compileFsm`/`compileDag`. The mapping table, and where the pen's
+refusals end and the compiler's begin, are
+[FLOW-PEN.md](../linq/docs/FLOW-PEN.md).
+
 ## Development
 
 Unit tests live in `test/flow/` at the repository root

package/docs/FLOW-FORMAT.md

@@ -67,6 +67,15 @@ honestly-stated divergences, is specified in
 [APP-INTEGRATION.md](APP-INTEGRATION.md); nothing there changes the
 format defined here.
 
+Documents in both formats are authored by hand, projected from a
+diagram, decoded by a model under the published grammar, or written by
+code: `@jarenjs/linq/flow` is the suite's by-code producer
+(`defineFsm`, `defineDag`), and it emits exactly the documents this
+section defines — its guards, effect props, node queries and edge
+selectors are callbacks captured over the scopes §3 and §6.1 fix. It
+imports nothing of this package; the compilers here remain the only
+judge of what a document means.
+
 ## §2 The jaren-fsm document
 
 ```json

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@jarenjs/flow",
   "private": false,
-  "version": "0.46.5",
+  "version": "0.56.0",
   "type": "module",
   "main": "./src/index.js",
   "types": "./dist/types/index.d.ts",
@@ -49,7 +49,7 @@
     "prepack": "npm run build:types"
   },
   "dependencies": {
-    "@jarenjs/core": "^0.46.5",
-    "@jarenjs/json": "^0.46.5"
+    "@jarenjs/core": "^0.56.0",
+    "@jarenjs/json": "^0.56.0"
   }
 }