@fluidgrids/workflows 0.0.0-stage → 2026.1027.1

package/LICENSE

@@ -0,0 +1,9 @@
+Copyright (c) 2025 Algoshred Technologies Private Limited.
+
+All rights reserved.
+
+This software is proprietary and confidential. Unauthorized copying, modification, distribution, or use of this software, via any medium, is strictly prohibited without the express written permission of the copyright holders.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+For licensing inquiries, please contact: legal@algoshred.com

package/README.md

@@ -1,3 +1,209 @@
-# Temporary Holding Version
+# @fluidgrids/workflows
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Author [FluidGrids](https://fluidgrids.ai) workflows as code. This package is
+Phase A of the code-first workflows spec set (BOFF-9902 / BOFF-9904,
+`fluidgrids-specs/product/specs/code-first/`):
+
+- the workflow IR, schema version 2: types, JSON Schema 2020-12, normalisation,
+  validation, hashing, diff, interface derivation and the export envelope;
+- the tier-1 graph builder: TypeScript that constructs a canvas workflow;
+- lift (IR to TypeScript or Python) and lower (TypeScript to IR), with a
+  fidelity report computed by actually lowering the code;
+- typed node clients generated from a node registry snapshot.
+
+Durable (tier-2) workflow functions are Phase B and are not in this package yet.
+
+## Install
+
+```bash
+bun add @fluidgrids/workflows
+```
+
+## Entry points
+
+| Import                                           | Contents                                                                                                                                          | Runs in                                   |
+| ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- |
+| `@fluidgrids/workflows`                          | `defineWorkflow`, `triggers`, `nodes`, `edge`, `expr`, `and`, `or`, `op`, `trigger`, `toIR`                                                       | anywhere; also bundled into workflow code |
+| `@fluidgrids/workflows/ir`                       | IR v2 types, `IR_V2_SCHEMA`, `normalizeDefinition`, `validate`, `irHash`, `canonicalJson`, `diffDefinitions`, `deriveInterface`, envelope helpers | anywhere, browser included                |
+| `@fluidgrids/workflows/roundtrip`                | `liftToTypeScript`, `liftToPython`, `lower`, `exportWorkflowCode`, `checkFidelity`                                                                | Node or Bun                               |
+| `@fluidgrids/workflows/codegen`                  | `generateNodeClients(manifests, 'ts' \| 'py')`                                                                                                    | anywhere                                  |
+| `@fluidgrids/workflows/quickjs`                  | `createQuickJSEvaluator()` for lowering untrusted code                                                                                            | Node or Bun                               |
+| `@fluidgrids/workflows/schema/ir-v2.schema.json` | the JSON Schema                                                                                                                                   | data                                      |
+
+## Tier 1: the graph builder
+
+```ts
+import { defineWorkflow, expr, triggers } from '@fluidgrids/workflows';
+import { nodes as n } from '../.fluidgrids/nodes';
+
+export const leadEnrichment = defineWorkflow(
+  { key: 'lead-enrichment', name: 'Lead enrichment' },
+  (wf) => {
+    const inbound = wf.trigger(triggers.webhook, { id: 'inbound', args: { path: 'leads' } });
+    const enrich = wf.http({
+      id: 'enrich',
+      after: inbound,
+      connection: 'enrichment-api',
+      args: {
+        method: 'GET',
+        url: 'https://person.clearbit.com/v2/combined/find',
+        queryParams: { email: wf.json.body.email },
+      },
+      retry: { maxRetries: 3, retryDelay: 2000 },
+    });
+    const isEnterprise = wf.if({
+      id: 'is-enterprise',
+      after: enrich,
+      condition: enrich.output.body.company.metrics.employees.gte(500),
+    });
+    wf.step(n.slack.sendMessage, {
+      id: 'notify-sales',
+      after: isEnterprise.true,
+      connection: 'slack-ops',
+      args: {
+        channelId: 'C0SALES',
+        text: expr`New enterprise lead: ${enrich.output.body.person.name.fullName}`,
+      },
+    });
+  }
+);
+```
+
+The callback runs once and records a graph; `toIR(workflow, { connections, layout })`
+turns the recording into IR v2. Lowering is a pure function of the builder
+calls, so the same source always gives the same IR.
+
+- Every node needs an `id` (`defineWorkflow({ autoIds: true })` derives them for quick scripts).
+- References lower to the expression language the workers evaluate:
+  `enrich.output.a.b` becomes `{{ $node["enrich"].item.a.b }}`, `wf.json.x`
+  becomes `{{ $json.x }}`. Comparisons (`gte`, `eq`, `contains`, `isEmpty`, …,
+  `and`, `or`) become the condition tree `internal:if` evaluates.
+- `connection: 'name'` resolves to a connection id when the workflow is pushed.
+- Lowering must not read the clock or a random source while the workflow is
+  defined: `Date.now()`, `new Date()` / `Date()` without arguments,
+  `Math.random()`, `crypto.getRandomValues()` / `crypto.randomUUID()` and an
+  argument-less `Intl.DateTimeFormat` `format()` throw a `DeterminismViolation`
+  error in both evaluators. Use `wf.now` and other references for run-time values.
+- Positions come from the layout sidecar `workflows/<key>.layout.json`, or the
+  automatic layout the AI draft generator uses.
+- An edge without an explicit `id` gets `e-<source>-<target>[-<sourceHandle>][-<targetHandle>]`.
+  Ids may contain `-`, so two edges can share that default; the later ones get
+  `-2`, `-3`, … in declaration order. Only a repeated explicit id is an error.
+- `edge(source, { id, type, targetHandle, label, mapping, extra })`,
+  `wf.connect`, `wf.edgeOrderIs` and the `extra` option on every node keep any
+  stored definition expressible exactly.
+- References into unknown shapes use index signatures, so a project
+  `tsconfig.json` should leave `noPropertyAccessFromIndexSignature` and
+  `noUncheckedIndexedAccess` off. Declared fields of generated clients are typed
+  either way.
+
+## Lift, lower and fidelity
+
+```ts
+import { exportWorkflowCode, lower } from '@fluidgrids/workflows/roundtrip';
+
+const exported = await exportWorkflowCode(definition, {
+  format: 'TYPESCRIPT', // or 'PYTHON'
+  registry, // node manifests, for typed clients
+  connectionNames, // connectionId -> name
+});
+exported.files; // workflows/<key>.ts|.py, the layout sidecar, .fluidgrids/nodes.*
+exported.fidelity.level; // 'lossless' when lowering the code reproduces the IR
+
+const { buildId, workflows } = await lower(files, { connections });
+```
+
+- **Lift** normalises the definition, plans builder calls, runs the plan through
+  the builder to prove each node and edge lowers back unchanged (falling back to
+  an exact `nodes.custom()` + `extra` form where the readable form would not),
+  and prints TypeScript with the pinned Prettier or Python that `ruff format`
+  leaves unchanged.
+- **Lower** bundles the project with esbuild 0.28.2 (`format: esm`,
+  `platform: neutral`, `target: es2023`) from an in-memory file map, serves
+  `@fluidgrids/workflows` from the runtime embedded in this package, and
+  evaluates the bundle in an isolate. `buildId` is the SHA-256 of the bundle; it
+  is identical with `esbuild` and `esbuild-wasm` of the same version, so the CLI
+  and the service agree. Workflow code may import project files and
+  `@fluidgrids/workflows` only. The sources are limited to `maxSourceBytes`
+  (default 1 MiB) before esbuild runs and the bundle to `maxBundleBytes`
+  (default 1.5 MiB) before it is evaluated; a `LowerError` with
+  `reason: 'too-large'` reports either.
+- **Evaluators**: the default is a fresh Node `vm` context (for the CLI, which
+  runs the developer's own code). Services use `createQuickJSEvaluator()` from
+  `@fluidgrids/workflows/quickjs` (quickjs-emscripten 0.32.0, the engine the
+  workers use), which bounds memory exactly. Both evaluate in a worker thread
+  that is terminated at `timeoutMs`, so the budget covers parsing and compiling
+  the bundle, promise jobs and anything the code leaves behind, and the calling
+  process never runs or inspects a value from the isolate. Failures are
+  `LowerError`s with a `reason` (`timeout`, `determinism`, `out-of-memory`, …).
+- **Fidelity** is `lossless` when `irHash(lower(lift(ir))) == irHash(ir)`. Items
+  report what is kept as plain strings or exact forms: `expression-verbatim`,
+  `legacy-syntax`, `unknown-node`, `connection-id-only`, `connection-ambiguous`
+  (a connection name that more than one connection id has, so the id is kept),
+  `raw-node`, `key-added`;
+  `layout-omitted`, `pinned-data-omitted`, `roundtrip-mismatch` and
+  `lowering-failed` make an export lossy.
+
+## The IR
+
+- `normalizeDefinition` rewrites the builder's legacy mirrors (`data.*`,
+  `config` on internal nodes) into the canonical node fields following the
+  executor's own reading order, so no executor-visible value changes
+  (`executorView` computes what the executor reads, for checking). It is pure
+  and idempotent. It keeps the mirrors some executor path reads from the data
+  bag only: `data.executionSettings.runOn`, `data.operation_name` (the agent tool
+  binding) and an external node's `data.version` (node-state rows). It does not
+  promote an external node's `data.state`, which the sub-node paths do not read;
+  `validate --strict` reports it. Keys named `__proto__` are ordinary keys
+  everywhere (copies, hashes, lift and lower).
+- `irHash` is `sha256:` + the SHA-256 of the RFC 8785 canonical JSON of the
+  normalised definition without `authoring`.
+- `validate(definition, { strict, isTaskQueueKnown })` applies the service's
+  structural rules and the version-2 rules of spec 01 §9. A stored version-1
+  definition that the service accepts never fails it; `strict` adds the
+  legacy-mirror, `${…}` and slug-id rules.
+- `buildExportDocument` and `serializeWorkflowDocument` reproduce today's
+  export envelope byte for byte for definitions without version-2 fields
+  (envelope `schemaVersion: 1`, definition untouched); only definitions that use
+  version-2 fields export as `schemaVersion: 2`, normalised.
+
+## Node clients
+
+```ts
+import { generateNodeClients } from '@fluidgrids/workflows/codegen';
+
+const { path, content, registrySnapshot } = await generateNodeClients(manifests, 'ts'); // .fluidgrids/nodes.ts
+```
+
+One property per node type, one descriptor per operation, typed from the
+manifest's `input_fields` / `output_fields`; trigger operations also appear
+under `triggers`. Internal nodes ship in the package as `nodes.internal.*` and
+`triggers.*`.
+
+## Shared fixtures
+
+`fixtures/` holds the conformance fixtures shared with the Python SDK: every
+internal node type, the five spec examples, the FG-UC doctor samples and a
+builder-shaped canvas definition, each with the expected TypeScript, Python,
+layout and IR. See `fixtures/README.md`.
+
+## Development
+
+```bash
+bun install
+bun run test                 # vitest
+bun run test:coverage        # with the 85% gate
+bun run lint
+bun run typecheck            # src, tests and the fixture projects
+bun run check:fixtures       # fixtures are current; add --ruff to run ruff format --check
+bun run build                # tsup: ESM + CJS + .d.ts
+bun run sanity               # everything above
+```
+
+Releases are CalVer (`YYYY.MDD.PATCH`) through `.github/workflows/release.yml`
+(the shared G60 workflow): push a CalVer tag or run the workflow from the
+Actions tab.
+
+## License
+
+Proprietary. Copyright (c) Algoshred Technologies Private Limited. See `LICENSE`.