DWG NO: FF-CORE  |  REV 1.1.1
LICENSE: MIT  |  SCALE: N/A

FLITFLOW CORE SPECIFICATION

Runs the way it's written, never crashes.

FlitFlow is a language-independent specification for executing AST-defined workflows safely. Undefined function calls and invalid access never crash the runtime — they're logged and execution continues. Today, it's implemented by the official Python runtime.

Step Execution Pipeline — SPEC 1.2.3

Resolvefunction
Evaluateargs
Invokeexecute()
Bindtarget_variable
Propagatesignal

SPEC × RUNTIME

The spec and the runtime are two different things.

FlitFlow is defined as a common specification, independent of any single language. The Python runtime is one official implementation that conforms to it. The same AST script produces the same result on any implementation that follows the spec.

FlitFlow Core SpecFlitFlow-labs/FlitFlow-Core-Spec
Python Runtime
official implementation · v1.1.1
TypeScript
not yet implemented · open to anyone
Go / Rust
not yet implemented · open to anyone

CORE GUARANTEES

Four things the spec guarantees.

Every conforming implementation is required to hold these.

PART 01

Always Safe execution

Undefined function calls and invalid type operations never crash the runtime. Abnormal conditions are logged and execution continues safely.

PART 02

Unified pipeline

args are pre-evaluated, params are passed through as deferred blocks, and results are automatically bound to target_variable.

PART 03

Explicit signal propagation

RETURN, BREAK, and CONTINUE are structured signals, not exceptions — consumed at well-defined boundaries.

PART 04

Deterministic fallback

Out-of-bounds access and unresolved branches resolve exactly as the spec defines — to NULL or a warning log, with no guesswork.

QUICK LOOK

Your first flow, in four lines of AST.

Full usage is covered in the documentation. This is just the shape of it.

quickstart.pyFlitFlow-labs/FlitFlow-Python
# 1. Define a workflow as an AST
ast = {
    "main": [
        { "function": "set_variables", "args": { "message": "Hello, FlitFlow!" } }
    ]
}

# 2. Validate against the spec, then run it
engine = RuntimeEngine(ast)
register_builtin_functions(engine)

state = {}
result = engine.run(state)

print(state["message"])   # Hello, FlitFlow!
print(result.status)     # Status.SUCCESS

SPEC COMPLIANCE

Verified by tests, not by assumption.

FlitFlow treats compatibility as something to prove, not promise.

SPECCOMPLIANTv1.1.1 · conformance tested
  • Schema validation: every AST is validated against the official JSON Schema before it runs.
  • Conformance matrix: each spec requirement is mapped to the test case that verifies it, published as the Conformance Matrix.
  • Clear versioning: patch, minor, and major changes are scoped so breaking changes are never a surprise.
  • Migration guides: behavioral differences between versions are documented to make upgrades a checklist, not a guess.

USE CASES

Where FlitFlow fits.

Workflow automation

Approval chains, batch jobs, and business logic you'd rather declare as an AST than hand-code.

No-code / low-code execution engines

Flows assembled visually in a builder, run by an engine that won't crash on a bad configuration.

External API pipelines

Wrap API calls or database access as custom functions and wire them safely into a flow.

Consistent execution across languages

Any runtime that conforms to the same spec produces the same behavior, now or after a migration.

ROADMAP

Where the spec stands.

v1.0

Baseline specification

Always Safe execution, the unified pipeline, and the core control signals were defined.

v1.1

Clarified execution semantics

Boolean normalization in switch, shallow-copied nested state, and out-of-loop signal handling were made explicit.

v1.1.1

Added set_global_variables

A built-in for updating root-level state across nested scopes. Supported by the current Python runtime.

Next

Other language runtimes

Because the spec is language-independent, conforming implementations in TypeScript, Go, or elsewhere are open for anyone to build.

Start with the spec.

SPEC.md and core_schema.json in FlitFlow-Core-Spec are the source of truth for every behavior described here.