automategraph 0.0.0-stage → 1.5.0

package/CHANGELOG.md

@@ -0,0 +1,292 @@
+# Changelog
+
+All notable changes to the AutomateGraph Execution Engine.
+Format follows [Keep a Changelog](https://keepachangelog.com/); the project uses semver.
+
+## [1.5.0] — Script loading
+
+A document can now say where its functions live and have them loaded: `scripts` entries point at
+files, inline source or URLs, and the loader executes them in the same realm. Purely additive —
+without a `scripts` field, nothing changes; the core stays isomorphic and the loader is a
+separate Node-only module.
+
+### Added
+
+- **`src/node/graph-scripts.ts`** (Node-only, excluded from the browser build):
+  `loadGraphScripts(document, options)` returns
+  `{ functions, namespaces, scripts, registry }` — ready to pass as
+  `createEngineFromJSON(document, { functions })`. Options: `baseDir` (default
+  `process.cwd()`), `collisions` (`"throw"` | `"override"`), `onLog`, and injectable
+  `readFile` / `fetchText`.
+- **Script declarations** in the graph document: `scripts: [{ namespace, path | source | url,
+  format? }]`. Validated by the isomorphic parser with JSON paths (`scripts[0].path`…): exactly
+  one source, identifier-like namespace, unique namespaces per document, known keys only, and
+  `parseGraphJSONDocument()` now exposes them. **Validation runs before execution** — a document
+  with a broken graph never runs a script.
+- **Two provision strategies**, mixable in one script:
+  - EXPORTS — `module.exports = { … }` (CJS), `export const …` / `export default { … }` (ESM);
+    non-function exports are ignored and reported in `ignoredExports`;
+  - SELF-REGISTRATION — `globalThis.GraphEngine.registerEngineNamespace(namespace, functions)`,
+    installed by the loader for the duration of the load only, realm restored afterwards
+    (verified by identity, including a pre-existing `GraphEngine` global).
+- **The namespace freeze** — claims are PROCESS-global (`globalThis` + `Symbol.for`), so a
+  second claim of the same namespace throws `NAMESPACE_ALREADY_REGISTERED`; a self-registering
+  script gets that throw from inside its own body. Claims are made at registration time, so a
+  script that registers and then throws leaves the namespace claimed.
+  `registeredNamespaces()` inspects the claims; `resetGraphScriptNamespaces()` clears them
+  (test/dev hygiene). Namespace mismatch throws `NAMESPACE_MISMATCH`.
+- **Names keep their spelling** — the namespace is a claim slot, never a name prefix.
+  Cross-script name collisions throw `FUNCTION_NAME_COLLISION` unless the load opts into
+  `{ collisions: "override" }` (which logs a warning).
+- **Format handling** — `.cjs` → `require`, `.mjs` → dynamic `import` (kept real through a
+  tsc-CommonJS-safe indirection), `.js`/URL → source-hint detection then CJS, falling back to
+  ESM and vice versa; `format: "cjs" | "esm" | "auto"` pins it and disables the fallback.
+- **Errors** — `GraphScriptError` with codes `SCRIPT_LOAD_FAILED`, `SCRIPT_NO_FUNCTIONS`,
+  `SCRIPT_EXPORT_INVALID`, `NAMESPACE_ALREADY_REGISTERED`, `NAMESPACE_MISMATCH`,
+  `FUNCTION_NAME_COLLISION`; a script-raised registration error surfaces unwrapped, never as a
+  generic load failure.
+- **Tests** — `tests/scripts.test.ts` (26) + 15 fixtures under `tests/fixtures/scripts/`;
+  suite 256 → 282.
+- **Example** — `examples/json-scripts.ts` + `examples/order-flow.scripted.graph.json` +
+  `examples/order-flow.functions.cjs` (`npm run example:scripts`): one document, a path script
+  and an inline self-registering script, run end-to-end, then the freeze and the reset.
+
+### Changed
+
+- `tsconfig.browser.json` excludes `src/node/**` — the isomorphic guard still covers the whole
+  core (engine, storage contract, JSON parser), the Node loader is deliberately outside it.
+- `parseGraphJSONDocument()` added to `src/graph-json.ts`; `parseGraphJSON()` is now its
+  `.definition` and keeps its exact v1.4 behaviour.
+
+### Fixed
+
+- **The format fallback replayed a script that had already run.** A script that executes and
+  throws while loading used to be retried in the other module format — running its body a second
+  time (double side effects, and a duplicate namespace claim for self-registering scripts).
+  The fallback is now restricted to module-FORMAT failures (`ERR_REQUIRE_ESM`, ESM syntax under
+  `require`, module-scope references); a script's own error fails the load immediately, after
+  exactly one execution. Guarded by scripts case S16.
+
+## [1.4.0] — Function registry and graph JSON
+
+Moves code out of the graph definition: `run` and edge `test` may name a function that lives in
+a registry, and a graph may be a JSON document. Purely additive — every v1.0–v1.3 graph keeps
+its behaviour, because inline functions are still accepted everywhere.
+
+### Added
+
+- **Function registry** — `FunctionRegistry` / `createFunctionRegistry()` /
+  `FunctionRegistry.from()`: `register`, `extend`, `has`, `get`, `names()` (sorted), `size`,
+  `snapshot()`, `info()`, `fingerprint()`. Keys must match `FUNCTION_NAME_PATTERN`
+  (`vendor:retry`, `order.chargeCard` are legal); registering a non-function throws.
+- **Engine-level table** — `new GraphExecutionEngine(graph, { functions })` plus
+  `engine.registerFunction(name, fn)` at any time, and `engine.registry` for
+  `{ fingerprint, names }`.
+- **Graph-level table** — `GraphDefinition.functions`, merged OVER the engine's table
+  (a graph may deliberately override a shared function). Mixed graphs — some nodes inline,
+  some named — are normal.
+- **Named references** — `NodeDefinition.run` and `NextEdge.test` accept a name. Resolution is
+  LAZY (per evaluation), so registering a function after construction, or while a run is in
+  flight, still takes effect.
+- **`UNKNOWN_FUNCTION`** — a missing `run` name records an unhandled error, fails the
+  activation, schedules nothing, and is PERMANENT: not retried, never routed through
+  `onThrow`/`fallback` (those are error recovery; this is a wiring defect). A missing `test`
+  name records the error once per node+name, never matches, and lets the rest of the chain
+  evaluate. The run settles FAILED because the error stays unhandled.
+- **Observability** — `fn` on `NodeResult` and on `node.started` / `node.succeeded` /
+  `node.failed`; `{ fingerprint, names }` on `graph.ready`, `ExecutionReport.registry` and
+  every `ExecutionSnapshot` (omitted when no registry is configured). The fingerprint
+  `fnr1:<count>:<hash>` covers sorted names + function source text.
+- **`edgeHasMatcher()`** — shared predicate for conditional vs. else edges; it counts a named
+  `test`, which fixed a lint regression (below).
+- **`src/graph-json.ts`** — `parseGraphJSON()`, `createEngineFromJSON()`, `isGraphJSON()`,
+  `GraphJSONError` (with `issues: [{ path, message }]`). Node `id` defaults to its key; unknown
+  properties are rejected at every level; dangling `next`/`onThrow`/`fallback`/entry/terminal
+  references are reported with their JSON paths; `functions` inside the document is rejected
+  with a pointer to the engine options. The loader is isomorphic (string or object in, no fs).
+- **`nodeFunctions()` / `edgeTests()`** — typed table builders, because a single table holds
+  both signatures and a bare literal cannot infer a parameter type from that union.
+- **Tests** — `tests/registry.test.ts` (28) and `tests/graphjson.test.ts` (19); suite 209 → 256.
+- **Examples** — `examples/json-graph.ts` + `examples/order-flow.graph.json`
+  (`npm run example:graphjson`): one document, four registries, including the missing-name case.
+
+### Changed
+
+- `NodeDefinition.run`, `NextEdgeObject.test`, `GraphDefinition.functions`,
+  `EngineOptions.functions`, `NodeResult.fn`, `ExecutionSnapshot.registry`,
+  `ExecutionReport.registry` — all additive; `NormalizedEdge` gained `testName`.
+- Validation: `run` must be a function or an identifier-like name; an edge `test` may be a
+  function or a name; the graph table's keys and values are checked at construction.
+
+### Fixed
+
+- **Lint treated a named `test` as an else edge.** After `test` was split into
+  `test`/`testName`, `lintGraph()` still asked `edge.test === undefined` — so every edge after a
+  named matcher was reported `UNREACHABLE_EDGE`, and `PARALLEL_EDGE_MATCHER_IGNORED` was missed
+  for parallel edges carrying a name. Both now use `edgeHasMatcher()`; regression-guarded by
+  registry cases R18/R19.
+
+## [1.3.0] — Typed edges and explicit routing
+
+Turns `next` from a list of destinations into an ordered, conditional edge list, and lets a node
+route itself. Purely additive: every v1.0–v1.2 graph keeps its behaviour, because a string entry
+normalizes to an unconditional parallel edge — exactly its old meaning.
+
+### Added
+
+- **`NextEdge`** — `next` accepts, in any mix:
+  | declared | normalized | meaning |
+  |---|---|---|
+  | `"audit"` | `{ nextNode, parallel: true }` | unconditional fan-out (v1.0 behaviour) |
+  | `{ nextNode: "b", result: 1 }` | `{ …, parallel: false, hasResult: true }` | exclusive, deep equality |
+  | `{ nextNode: "c", test: fn }` | `{ …, parallel: false }` | exclusive, predicate |
+  | `{ nextNode: "d" }` | `{ …, parallel: false }` | exclusive **else** edge |
+  | `{ nextNode: "x", parallel: true }` | unchanged | fires regardless of the exclusive chain |
+
+  Exclusive edges are evaluated **in declaration order, first match wins**; a matched edge
+  suppresses later exclusive edges, parallel edges are never suppressed. No match schedules
+  nothing and records no error (silent). `result` uses deep equality (`deepEquals`: `Object.is`
+  for primitives — so `NaN` matches `NaN` — element-wise for arrays, own keys for objects,
+  `getTime()` for Dates, cycle-safe); `result` and `test` together must both pass.
+- **Explicit routing** — a node can choose its own successor:
+  - `return new Next(target, value)` — `value` becomes the node's output, `target` the
+    destination. `Next` with an empty target throws `INVALID_NEXT_TARGET`.
+  - `context.goto(target)` followed by the normal `return value` — for void/imperative nodes.
+  - An explicit route **replaces the whole edge list** for that activation (parallel edges
+    included), may target any node in the graph, and is validated at runtime: an unknown target
+    records `INVALID_GOTO_TARGET` and schedules nothing.
+  - `Next` wins over `goto` when both are used; each retry attempt starts with no route set.
+- **`NodeContext.goto()`**, **`Next`**, **`isNext()`**, **`normalizeNextEdges()`**,
+  **`deepEquals()`** exported.
+- **`node.succeeded` payload** gains an optional `route: { nextNode, via: "next-class" | "goto" }`
+  when the activation routed itself.
+- **New lint codes**: `UNREACHABLE_EDGE` (error — an exclusive edge declared after an else edge
+  can never fire), `PARALLEL_EDGE_MATCHER_IGNORED` (warn — parallel edges fire unconditionally,
+  so their matcher is ignored), `TERMINAL_EDGE_IGNORED` (warn — a terminal node latches completion
+  before routing, so its edges never run).
+- **Validation** for edge entries: non-empty `nextNode`, `test` must be a function, `parallel`
+  must be a boolean, malformed entries rejected, targets must exist.
+- **`tests/edges.test.ts` — 26 cases** wiring the whole contract, including the `a → b/c/d/e/f`
+  picture as a single execution (5 seeds) and the finding that a runtime route is invisible to
+  static reachability, so the edge should be declared as a fallback.
+- **`examples/branching-edges.ts`** + comparison of the three approaches in `examples/README.md`.
+
+### Changed
+
+- `NodeDefinition.next` is now `readonly NextEdge[]` (was `readonly string[]`). Source-compatible:
+  string arrays are still valid and behave identically.
+- Terminal nodes: settlement order is unchanged (terminal check → routing), now documented and
+  warned about by lint.
+- `lintGraph()` reachability follows declared edges only; runtime `Next`/`goto` targets cannot be
+  seen statically.
+
+## [1.2.0] — Success dead-end linting
+
+Closes a linting gap found while explaining the C-19 resilience fixture: a non-terminal node
+could declare `onThrow` (or a `fallback`) and never be flagged, even though its **success path
+led nowhere** — the node could only "continue" by failing.
+
+### Added
+
+- **`SUCCESS_DEAD_END` lint code (error tier)** — fires when a node is not a terminal node and
+  has no `next` target, but does have at least one live error transition (`onThrow`, or `fallback`
+  when the effective policy is `FALLBACK`). Message: *"…cannot continue after success (no next
+  target); only its error transitions are declared. Add next targets or declare it as a terminal
+  node"*. The rule is intentional about the difference: `DEAD_END_NODE` stays for the total case
+  (no `next`, no `onThrow`, no live `fallback`), and the two codes are **mutually exclusive** — a
+  node with no `next` always produces exactly one of them.
+- **`tests/lint.test.ts` — 13 cases** covering the rule, its boundaries (terminal nodes, nodes
+  with `next`, inert fallbacks, live fallbacks, unreachable nodes) and its engine integration in
+  both `lint: "warn"` and `lint: "error"` modes. The C-19 fixture and the C-01 order-pipeline
+  fixture are asserted directly, so the two graphs discussed in review are now pinned by CI.
+- New report kind `LINT` in the dashboard (badge, filter, inventory table).
+
+### Changed
+
+- `lintGraph()` message for `DEAD_END_NODE` now spells out why it fired:
+  *"(no next, onThrow or fallback)"*.
+- Lint lines are logged at the **issue** severity (`error` for error-tier codes) even when the
+  mode is `"warn"`; the mode only decides whether error-tier issues are enforced. This was already
+  the behaviour — it is now covered by a test so it cannot drift.
+
+### Upgrade notes
+
+`lint: "error"` users may see graphs rejected that previously passed. The fix is one of:
+add a `next` target, handle the failure inside the node so it always succeeds, or declare the node
+in `terminalNodes` (pair it with `completionPolicy: "ALL_TERMINALS"` / `"DRAIN"` if other branches
+must still complete). Linting is off by default, so default behaviour is unchanged.
+
+## [1.1.0] — Wave 1: correctness, policy and contract
+
+Wave 1 turns the 18 audited behaviours into explicit guarantees. **Defaults preserve
+v1.0 semantics** except for the two behaviour changes marked BREAKING below. Everything
+else is additive or opt-in.
+
+### Added
+
+- **`CompletionPolicy`** (`GraphDefinition.completionPolicy`): `"FIRST_TERMINAL"` (default,
+  v1.0 behaviour) | `"ALL_TERMINALS"` | `"DRAIN"`.
+- **`activation.dropped` event** — every time the scheduler clears pending work it now
+  reports the dropped activations and the reason (`logical-completion`, `all-terminals-reached`,
+  `fail-fast`, `graph-fail-fast`, `checkpoint-failure`, `step-budget-exceeded`, `cancellation`).
+- **Cancellation drain deadline** (A2): setting `EngineOptions.cancellationTimeoutMs` now also
+  bounds the drain. Work still running when the deadline elapses is marked
+  `NodeStatus.ABANDONED`, the run settles, and `ExecutionReport.drainTimedOut` /
+  `abandonedActivations` report what happened. Unset ⇒ v1.0 behaviour (wait for cooperative drain).
+- **`NodeStatus.ABANDONED`** — a cancellation-deadline outcome distinct from `CANCELLED`.
+- **Real FALLBACK routing** (A5): `NodeDefinition.fallback` is used as the error transition when
+  the effective error policy is `FALLBACK` and no `onThrow` is declared. The error is recorded
+  as handled; unknown targets are rejected at construction.
+- **Bounded concurrency and step budget** (A8): `EngineOptions.maxConcurrency` (default:
+  unbounded) and `EngineOptions.maxActivations` — the latter records `STEP_BUDGET_EXCEEDED`,
+  stops scheduling and settles the run, which makes runaway cycles terminate.
+- **Graph linting** (A9): exported `lintGraph(graph)` plus `EngineOptions.lint`
+  (`"off"` default | `"warn"` | `"error"`). Issues: `DUPLICATE_ENTRY`, `DUPLICATE_TERMINAL`,
+  `UNREACHABLE_NODE`, `UNREACHABLE_TERMINAL`, `DEAD_END_NODE`, `FALLBACK_TARGET_IGNORED`.
+  Findings are surfaced on `ExecutionReport.lintIssues`.
+- **`node.cancelled` event** — emitted when an activation settles as cancelled.
+- **Introspection**: `getInFlightActivationIds()`, `getLintIssues()`.
+- **Storage adapter contract** (`src/storage-adapter.ts`): `StorageAdapter`, `StorageCapabilities`,
+  shape validation (`storageAdapterViolations`, `assertStorageAdapter`, `defineStorageAdapter`) and
+  a canonical JSON wire format (`serializeSnapshot`, `deserializeSnapshot`, `stableStringify`,
+  `compareSnapshots`, `SNAPSHOT_FORMAT`/`SNAPSHOT_FORMAT_VERSION`).
+- **Storage conformance suite** (`src/storage-conformance.ts`): `runStorageConformance(fixture)`
+  verifies round-trip, missing-key behavior, execution isolation, no aliasing on save/load,
+  overwrite, deterministic serialization, JSON stability, failed-save atomicity (when the fixture
+  can inject faults), listing, delete idempotency and close.
+- **`InMemoryStorage`** is now a full reference adapter: `capabilities`, `listExecutionIds()`,
+  `delete()`, `close()`.
+- **Isomorphic build proof**: `tsconfig.browser.json` (DOM libs, `types: []`, `noEmit`) plus a test
+  that asserts the core compiles with no Node APIs. Timers are `setTimeout`-based only.
+- **New test packs**: `tests/upgrade.test.ts` (19 cases) and `tests/conformance.test.ts` (11 cases),
+  wired into a kind-driven harness/report. Suite total: **170 tests**.
+
+### Changed (BREAKING)
+
+- **A1 — cancellation symmetry.** A node callback that *rejects because of* an abort now settles
+  `NodeStatus.CANCELLED` with a **handled** `GRAPH_CANCELLED` error record. Previously it settled
+  `FAILED` with an unhandled error, which made cooperative cancellation asymmetric.
+- **A4 — `FAIL_FAST` is sticky.** A node-level `FAIL_FAST` now installs the same persistent stop as
+  a graph-level one (it previously flushed the pending queue once, which was a no-op under unbounded
+  concurrency). A node-level `CONTINUE` still cannot shield other branches from a graph-level stop.
+
+### Fixed
+
+- **A6 — `NodeResult.error`** is now populated for `FAILED` and `TIMED_OUT` activations (the field
+  existed but was never assigned).
+- **A10 — dead code and hygiene**: removed the unused `resolveRun` field; in-flight activations are
+  tracked and released deterministically (`getInFlightActivationIds()` is empty after a settle);
+  `NodeJS.ErrnoException` replaced with a structural cast so the core compiles without Node types.
+
+### Notes
+
+- `cancel()` still returns before the graph settles; in-flight work drains cooperatively. Outputs
+  produced by abandoned activations are never adopted.
+- `InMemoryStorage.version` moved to `1.1.0` to reflect the adapter surface.
+
+## [1.0.0]
+
+- Initial single-file engine: graph validation, event bus, in-memory storage, scheduler with
+  unbounded concurrency, retry/error policies, cooperative cancellation, atomic checkpoints.
+- Audit suite: 140 tests (100 unit, 20 complex integration, 20 async-callback) documenting
+  18 engine behaviours, with a self-contained HTML/JSON report and a live preview server.

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026 ammisaidkaidi
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.