Skip to main content

The IR and the two tiers

Every FluidGrids workflow version is stored as one definition, the IR (intermediate representation). The canvas, a TypeScript file, a Python file and a JSON export are all views of it. Because there is one source of truth, a workflow never has two versions of itself that can drift apart.

Schema version 2​

Code-first workflows use schema version 2 of the definition. It is a strict superset of the definitions the builder has always saved: every existing workflow is already a valid version-2 definition and keeps running exactly as before. Version 2 adds optional parts:

PartWhat it holds
interfaceThe typed contract of the workflow: input, output, and the signals, queries and updates it accepts, as JSON Schema
authoringHow the version was produced (canvas, code, AI, import) and the hashes that identify it

Version 2 also holds code, a reference to the code bundle of a version that contains durable functions, and two node types: Code workflow (run a durable function) and Wait for Signal.

Each version records an IR hash, the SHA-256 of the normalised definition. Two definitions with the same IR hash are the same workflow, however they were written. fluidgrids diff and the version diff compare definitions, not text.

Tier 1: code that builds a graph​

Tier-1 code runs once, when you push, and records a graph. It produces exactly what the canvas would save, so it adds no new runtime behaviour:

import { defineWorkflow, triggers } from '@fluidgrids/workflows';

export const ping = defineWorkflow({ key: 'ping', name: 'Ping' }, (wf) => {
const start = wf.trigger(triggers.api, { id: 'start' });
wf.http({ id: 'ping', after: start, args: { method: 'GET', url: 'https://example.com/health' } });
});

See The graph builder.

Tier 2: durable functions​

Tier-2 code is the workflow itself. The engine runs the function by replay: on every step it runs the function from the top, feeds it the results already recorded in the run's event history, and records the next thing the function asks for. The function has no direct access to the network, the clock or random numbers; everything that touches the outside world is an activity.

In the IR a durable function is a graph with a trigger and one Code workflow node, so triggers, permissions, quotas, versions, environments and Git work the same as for any other workflow.

See Durable functions.

Export formats​

FormatWhat you getCan be imported?
JSONThe definition in the FluidGrids export envelopeYes
TypeScriptA tier-1 moduleYes
PythonThe same, in PythonYes

Exporting a durable function as TypeScript gives its stored source.

Every export to code comes with a fidelity report. Lossless means that turning the exported code back into a definition reproduces the original exactly; the report is computed by doing that, not by guessing. When something cannot be expressed exactly, such as a free-form expression, the item is listed and kept verbatim.

Next steps​