Metadata-Version: 2.5
Name: fluidgrids-workflows
Version: 2026.1114.2
Summary: Author FluidGrids workflows as code in Python: the tier-1 graph builder, byte-identical lowering to the workflow IR v2, the IR tools, tier-2 durable workflow functions with their deterministic runtime, test environment and self-hosted worker.
Project-URL: Homepage, https://fluidgrids.ai
Project-URL: Repository, https://github.com/Algoshred/fluidgrids-workflows-sdk-python
Project-URL: Issues, https://github.com/Algoshred/fluidgrids-workflows-sdk-python/issues
Project-URL: Changelog, https://github.com/Algoshred/fluidgrids-workflows-sdk-python/blob/main/CHANGELOG.md
Author-email: FluidGrids <info@fluidgrids.ai>
Maintainer-email: FluidGrids <info@fluidgrids.ai>
License: 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
License-File: LICENSE
Keywords: automation,fluidgrids,sdk,workflow,workflow-as-code
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: Other/Proprietary License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: jsonschema<5,>=4.23
Requires-Dist: tzdata>=2025.2; sys_platform == 'win32'
Provides-Extra: build
Requires-Dist: ruff==0.17.0; extra == 'build'
Provides-Extra: durable
Requires-Dist: pydantic==2.14.0; extra == 'durable'
Provides-Extra: keychain
Requires-Dist: keyring==25.7.0; extra == 'keychain'
Provides-Extra: managed
Requires-Dist: uvicorn==0.54.0; extra == 'managed'
Provides-Extra: metrics
Requires-Dist: prometheus-client==0.26.0; extra == 'metrics'
Provides-Extra: protobuf
Requires-Dist: protobuf==7.36.2; extra == 'protobuf'
Provides-Extra: tuner
Requires-Dist: psutil==7.2.2; extra == 'tuner'
Provides-Extra: worker
Requires-Dist: websockets==17.2; extra == 'worker'
Description-Content-Type: text/markdown

# fluidgrids-workflows

Author [FluidGrids](https://fluidgrids.ai) workflows as code in Python. This
package is the Python half of Phase A of the code-first workflows spec set
(BOFF-9902 / BOFF-9904, `fluidgrids-specs/product/specs/code-first/`, spec 03):

- the tier-1 graph builder: Python that constructs a canvas workflow;
- lowering a Python project to the workflow IR, schema version 2, byte for
  byte the same as `@fluidgrids/workflows` lowers the TypeScript twin of the
  same graph;
- ports of the IR tools: `normalize_definition`, `validate`, `ir_hash`,
  canonical JSON (RFC 8785), the structural diff, the executor view, the
  automatic layout, durations and schedule checks;
- loading the typed node clients that `fluidgrids codegen --lang python`
  generates (`.fluidgrids/nodes.py`);
- from Phase B (BOFF-9905): `wf.code_workflow`, which embeds a TypeScript
  durable function in a graph, and `fluidgrids_workflows.history`, the
  durable-function contract (event and command enums, the command and history
  JSON Schemas, command and history validation, `load_history`).

From Phase C (BOFF-9906): Python durable (tier-2) workflow functions
(`fluidgrids_workflows.durable`), the deterministic runtime that runs them,
`TestWorkflowEnvironment`, deterministic bundles (`build_project`), the
managed Python VM (`fluidgrids_workflows.managed`) and client profiles.
Lifting (IR to Python source) lives in the TypeScript package, which the
service and the CLI use for `fluidgrids pull --format py`.

## Install

```bash
uv add fluidgrids-workflows     # or: pip install fluidgrids-workflows
```

Python 3.11 or later. The floor matches `fluidgrids-node-sdk` (spec 03 §1) and
the generated clients, which use `typing.Required`.

Optional extras, each pinned: `durable` (Pydantic models as schemas),
`build` (ruff diagnostics in builds), `managed` (uvicorn for the managed VM),
`worker`, `metrics`, `tuner`, `protobuf` and `keychain` (keyring, for
`keychain:` token references).

## Tier 1: the graph builder

```python
from fluidgrids_workflows import define_workflow, expr, triggers
from fluidgrids_workflows.project import nodes as n


@define_workflow(key="lead-enrichment", name="Lead enrichment")
def lead_enrichment(wf):
    inbound = wf.trigger(triggers.webhook, id="inbound", args={"path": "leads"})
    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},
    )
    is_enterprise = wf.if_(
        id="is-enterprise",
        after=enrich,
        condition=enrich.output.body.company.metrics.employees >= 500,
    )
    wf.step(
        n.slack.send_message,
        id="notify-sales",
        after=is_enterprise.true,
        connection="slack-ops",
        args={
            "channelId": "C0SALES",
            "text": expr("New enterprise lead: ", enrich.output.body.person.name.fullName),
        },
    )
```

The decorated function runs once, immediately, and records a graph;
`to_ir(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.

- Builder methods and keyword options are snake_case (`wf.if_`,
  `wf.wait_for_signal`, `on_error`, `execution_settings`). Dictionary values
  (`args`, `retry`, `config`, `extra`, …) keep the IR's own keys
  (`maxRetries`, `channelId`) and lower byte for byte.
- Every node needs an `id` (`define_workflow(..., auto_ids=True)` derives them
  from labels for quick scripts).
- References lower to the expression language the workers evaluate:
  `enrich.output.a.b` becomes `{{ $node["enrich"].item.a.b }}` and `wf.json.x`
  becomes `{{ $json.x }}`. Use `ref["key"]` for keys that are not identifiers,
  are Python keywords, start with `_` or are reference method names, and
  `ref[0]` for indices.
- Comparisons (`>=`, `==`, …, `contains`, `is_empty`, `matches`, the generic
  `is_(operator, value)`) and `and_()` / `or_()` become the condition tree
  `internal:if` evaluates. `and`, `or`, `not` and `in` raise, because they would
  be evaluated by Python at definition time.
- `expr("text ", ref, " more")` concatenates text and references.
- Leaving an option out writes the default; `False` for `operation`, `version`
  and edge `id` / `type` writes no such field; `None` is JSON `null`.
- `edge(source, id=..., type=..., target_handle=..., label=..., data=...,
  mapping=..., extra=...)`, `wf.connect`, `wf.edge_order_is` and the `extra`
  option on every node keep any stored definition expressible exactly.
- An edge without an explicit `id` gets
  `e-<source>-<target>[-<sourceHandle>][-<targetHandle>]`; when that id is taken
  the later edges get `-2`, `-3`, … in declaration order.
- `connection="name"` resolves to a connection id when the workflow is pushed;
  an unknown name raises `UnresolvedConnectionsError`.
- Positions come from the layout sidecar `workflows/<key>.layout.json`, or the
  automatic layout the AI draft generator uses.

The complete surface is pinned by the shared fixtures; `fixtures/README.md`
lists it.

### Durable functions in a graph

`wf.code_workflow("<exportName>", ...)` adds an `internal:code-workflow` node
that runs a `workflow()` function of the definition's code bundle as a durable
child run. In Phase B the bundle is a TypeScript one, given with
`define_workflow(code=...)`:

```python
from datetime import UTC, datetime

process = wf.code_workflow(
    "processOrder",
    id="process-order",
    after=received,
    input={"order": wf.json.body},  # inputMapping
    timeout_seconds=900,  # 0 or absent: no node-level timeout
    fail_on_error=False,
)
shipped = wf.wait_for_signal(
    id="await-shipment",
    after=process,
    name="shipped",
    consume="all",  # or "first" (the default)
    until=datetime(2026, 12, 1, tzinfo=UTC),  # limitWaitUntil; or limit="2d"
)
```

As with every builder option, an option left out writes nothing and the
service applies the default: `task_queue` `managed`, `wait_for_completion`
`True`, and the parent-close policy of decision DB13, `TERMINATE` when the node
waits for the child and `ABANDON` when it does not
(`fluidgrids_workflows.history.code_workflow_parent_close_policy`).
`validate` warns about a fire-and-forget node with `TERMINATE` or
`REQUEST_CANCEL` (`codeWorkflow.closePolicyEndsChild`) or a timeout
(`codeWorkflow.timeoutIgnored`). `until` takes an ISO 8601 string or a
timezone-aware `datetime`.

### What needs self-hosted workers

`durable_phase_issues(definition, self_hosted=False)` (in
`fluidgrids_workflows.ir`) lists, with code `durable.phaseC`, what a definition
needs that a workspace without self-hosted workers cannot run:
`code.exports.activities` (user activities), task queues other than `managed`,
the `userActivity` feature, and any `code.features` value the SDK does not
know, so the check fails closed. Python bundles (`determinism: "worker"`) and
the handler features (`updates`, `queries`, `searchAttributes`, `dynamic`,
`interceptors`) pass; the service still gates each of them by its workspace
flag. `lower_project` returns the issues as `LowerResult.issues`,
`fluidgrids-workflows lower` prints them under `issues`, and
`validate(..., refuse_phase_c=True)` (`validate --refuse-phase-c
[--self-hosted]`) makes them errors. Without that option `validate` gives the
TypeScript SDK's verdict.

## Tier 2: durable functions in Python

```python
from fluidgrids_workflows import triggers
from fluidgrids_workflows.durable import define_signal, workflow
from fluidgrids_workflows.project import nodes as n

approve = define_signal("approve")


@workflow("process-order", trigger={"operation": triggers.webhook, "args": {"path": "orders"}})
async def processOrder(ctx, order):
    charge = await ctx.run(n.stripe.create_charge, args={"amount": order["amount"]})
    await ctx.signal_received(approve)
    await ctx.sleep("1h")
    return {"charge": charge["id"]}
```

Workflow code awaits only what the context returns (`ctx.run`, `ctx.activity`,
`ctx.sleep`, `ctx.condition`, `ctx.child`, `ctx.gather`, `ctx.race`, ...); the
runtime gives those awaitables JavaScript promise semantics, so a Python
function issues exactly the commands its TypeScript twin issues and both
record the same history. Modules run under an import guard that refuses the
clock, randomness, the file system, the network and processes; use
`ctx.now()`, `ctx.random()`, `ctx.uuid()` and activities instead.

`TestWorkflowEnvironment` (in `fluidgrids_workflows.testing.environment`) runs
workflows in process with time skipping, activity mocks, user activities,
signals, queries, updates, cancellation and resets. `replay_history` checks a
history file against the current code.

## Projects and generated node clients

A project is a directory with workflow modules in `workflows/*.py`, optional
layout sidecars (`workflows/<key>.layout.json`), TEST-only pinned data
(`workflows/<key>.pinned.json`) and the generated clients in
`.fluidgrids/nodes.py`. Workflow modules import the clients with
`from fluidgrids_workflows.project import nodes as n`, which resolves to the
project being lowered, then `FLUIDGRIDS_PROJECT_DIR`, then the nearest
`.fluidgrids/nodes.py` at or above the working directory.

```python
from fluidgrids_workflows import lower_project

result = lower_project(".", connections={"slack-ops": {"connectionId": "c1", "adapter": "slack"}})
for workflow in result.workflows:
    print(workflow.key, workflow.definition)
```

`lower_project` imports the project's modules, so it is for code the caller
trusts (the CLI lowering a developer's own project; services never run Python
workflow code, spec decision D1). It imports the project twice and refuses a
workflow whose graph changes between the two (`LowerError(reason="determinism")`),
which catches definitions that read the clock or a random source.

## Command line

```bash
fluidgrids-workflows lower [PROJECT] [--connections FILE] [--entry workflows/x.py]
fluidgrids-workflows build [PROJECT] [--out bundle.pyz] [--entry ...] [--no-diagnostics]
fluidgrids-workflows replay HISTORY [--project DIR] [--entry ...]
fluidgrids-workflows test [PROJECT] [PYTEST_ARGS...]
fluidgrids-workflows validate FILE [--strict] [--allow-empty] [--refuse-phase-c] [--self-hosted]
fluidgrids-workflows hash FILE
fluidgrids-workflows normalize FILE
```

`build` gives the `fluidgrids.python-build-result` the managed build VM gives
for the same sources: the deterministic bundle (`bundleBytes`, base64), its
`buildId` (`sha256:` of the bundle), the lowered definitions, `issues` and
ruff `diagnostics`.

## Self-hosted workers

`fluidgrids_workflows.worker.Worker` runs workflow tasks of Python bundles and
user activities on your own machines (spec 02 §7b, 11 §2.29-2.31). It is the
twin of `@fluidgrids/workflows/worker` and speaks the same bridge protocol
(v2), so Python and TypeScript workers can serve one task queue. It needs the
`worker` extra (`pip install 'fluidgrids-workflows[worker]'`).

```python
import asyncio

from fluidgrids_workflows.durable import define_activity
from fluidgrids_workflows.worker import Worker


@define_activity("billing.charge", task_queue="payments")
async def charge(ctx, args):
    await ctx.heartbeat({"step": "charging"})
    return {"chargeId": "ch_1"}


async def main() -> None:
    worker = Worker(
        "payments",
        workflow_bundles=[".fluidgrids/build/bundle.pyz"],
        activities=[charge],
        max_concurrent_activities=16,
    )
    await worker.run()  # SIGTERM or SIGINT drains and stops it


asyncio.run(main())
```

- The worker connects outbound to `FLUIDGRIDS_BRIDGE_URL` (default
  `wss://graphqlworkspaces.burdenoff.com/runner-bridge`; `ws://` only to
  localhost) with the worker token in `FLUIDGRIDS_WORKER_TOKEN` (`fgr_...`,
  kind WORKER). The service accepts it only while
  `fluidgrids.self-hosted-workers` is on for the workspace and a worker seat
  is free; a refusal for good (close codes 4001-4004 and 4010-4012, or an
  HTTP 401/403 upgrade) makes `run()` raise `BridgeClosedError`, anything
  else reconnects with capped, jittered backoff.
- A queue is `orders` (every environment of the queue) or `orders@staging`
  (only the staging-scoped queue; `@dev`, `@staging` or `@prod`). The
  `environment` keyword, or `FLUIDGRIDS_WORKER_ENVIRONMENT`, binds every
  plain name, so a staging worker never takes production tasks of the same
  queue name. A worker token bound to `orders@staging` enforces the same on
  the service side, whatever the worker announces.
- Workflow tasks replay the run's history in this SDK's runtime, from the
  same bundle bytes (and `buildId`) that `fluidgrids push` stored. By default
  each task runs in a process forked from a `PYTHONHASHSEED=0` forkserver with
  a SIGKILL deadline (`runner="fork"`); `runner="thread"` runs them in this
  process, importing the bundle's workflow modules afresh for every task so
  module-level state never carries over (vendored third-party packages are
  imported once per process). Activity values with NaN or an infinity travel
  as null, as `JSON.stringify` writes them. A sticky cache keeps each run's history so the service sends only
  the tail. Queries, updates, sinks and workflow interceptors (only when the
  lease enables the `interceptors` feature) work as on the managed runtime.
- User local activities (gap G5): `ctx.local_activity(declaration | "name",
  args=..., retry=..., start_to_close_timeout=..., summary=...)` runs a
  declared user activity inside the workflow task, in the worker's own
  process, with the implementation in its `activities` (or its dynamic
  activity). The worker asks the service to grant the round
  (`workflowTask.heartbeat`) before anything runs, renews the task lease every
  5 s, retries inside the task's 30 s budget and records one
  `RECORD_LOCAL_ACTIVITY` marker per call under the node type
  `activity:<name>`. Implementations must be idempotent (at least once); they
  get `ctx.info.is_local`, and have no heartbeats, no `complete_async()` and
  no connections. On the managed queue the call raises
  `taskQueue.userActivityOnManaged`, and `lower` refuses it at push. A node
  operation as a local activity still fails the task `UNSUPPORTED_COMMAND`
  on a self-hosted worker. `max_concurrent_local_activities` defaults to 100
  on a worker with bundles and activities.
- Send and Wait as a durable activity (H5, runtime release 5):
  `ctx.run(nodes.internal.send_and_wait, args=...)` parks until the person
  answers when the workspace has `fluidgrids.run-control` on (the lease lists
  the `asyncCompletion` feature). `lower` reports the `asyncCompletion` bundle
  feature for a module that uses it, so the service refuses the push while run
  control is off. A replayed Send and Wait keeps working after the flag is
  turned off. `ctx.local_activity` never runs it, and `internal:wait` stays
  refused.
- `run_task(registry, request, debug=hook)` (runtime release 4) hands a replay
  debugger each command, input event and mismatch (`DebugHook.on_command`,
  `on_event`, `on_mismatch`) as JSON copies. The hook cannot change the result,
  and the workers never pass one.
- Activities get `ctx.heartbeat()` (throttled; the acknowledgement carries
  cancellation and pause), `ctx.cancelled`, `ctx.complete_async()`,
  `ctx.connection(name)` (only connections the activity declares and the
  token allows), `ctx.log` and `ctx.metrics`. Plain functions run on a
  thread pool and can call `ctx.heartbeat_nowait()`. The engine owns retries
  and timeouts: an attempt past its deadline, or of a lost session, is
  stopped and not reported.
- Options: `max_concurrent_workflow_tasks` (4), `max_concurrent_activities`
  (100), `max_activities_per_second`, `max_cached_runs` (1000), `pollers`, a
  `resource_based()` tuner (the `tuner` extra) instead of fixed limits,
  `shutdown_grace_time` (30 s), activity interceptors, sinks, a payload
  `codec` and `payload_converter` (`protobuf_payload_converter` with the
  `protobuf` extra), and metrics served as Prometheus text on `127.0.0.1`
  (`metrics={"prometheus": {"port": 9464}}`), pushed as OTLP/HTTP JSON, or
  added to a `prometheus_client` registry with `prometheus_collector`.

## The managed Python VM

`fluidgrids_workflows.managed.server:app` is the ASGI app of the managed
runtime's MicroVM (no egress, no public ingress). Every call carries
`x-fluidgrids-worker-secret`; failed attempts are rate limited. `PUT
/bundles/{buildId}` stores a bundle, `POST /task` runs a workflow task (the VM
keeps each run's history and answers `409 {"need": "bundle"}` or
`409 {"need": "history"}` when it lacks one) and `POST /build` builds a
project. Each task runs in a process forked from a forkserver started with
`PYTHONHASHSEED=0`, under `RLIMIT_AS` (`PY_TASK_MEMORY_BYTES`) and a SIGKILL
deadline (`PY_TASK_DEADLINE_SECONDS`).

## Profiles

`fluidgrids_workflows.profiles` reads `~/.fluidgrids/config.toml`
(`FLUIDGRIDS_CONFIG` overrides the path): `[profiles.<name>]` tables and
`defaultProfile`, chosen with `FLUIDGRIDS_PROFILE`, with `FLUIDGRIDS_<KEY>`
overrides. Tokens never live in the file: `tokenRef` is `env:VAR` or
`keychain:<service>/<account>`, and `FLUIDGRIDS_TOKEN` always wins.

Every command prints JSON; `FILE` may be `-` for standard input. The FluidGrids
CLI calls `lower` for Python projects; its result carries `issues` only when a
workflow needs a Phase C feature.

## The IR

`fluidgrids_workflows.ir` ports `@fluidgrids/workflows/ir`:

- `normalize_definition` rewrites the builder's legacy mirrors into the
  canonical node fields following the executor's reading order; it is pure and
  idempotent.
- `ir_hash` is `sha256:` + the SHA-256 of the RFC 8785 canonical JSON of the
  normalised definition without `authoring`, so both SDKs and the canvas hash a
  graph equally.
- `validate(definition, strict=..., is_task_queue_known=...)` applies the
  service's structural rules and the version-2 rules of spec 01 §9. Issue codes
  match the TypeScript validator; messages are English and may differ in
  wording.
- `canonical_json`, `stable_stringify`, `diff_definitions`, `executor_view`,
  `auto_layout`, `duration_ms`, `check_schedule_spec` and the `{{ … }}`
  reference parser are exact ports.
- `ir_v2_schema()` is the IR v2 JSON Schema, vendored byte for byte from the
  TypeScript package.

## The durable-function contract

`fluidgrids_workflows.history` is the Python side of
`@fluidgrids/workflows/history`, the contract the service, the workers and both
SDKs share:

- `EVENT_TYPES`, `COMMAND_TYPES`, `TASK_FAILURE_CAUSES`, the Phase B core,
  parity and Phase C command sets, and the event classes, in the TypeScript
  order;
- TypedDicts for events (`RunEventRecord`), every command, failures, retry
  policies, task requests and results, local-activity requests and results,
  run targets and history files; `tests/test_history.py` checks each one
  against the vendored schemas;
- the runtime release this SDK's runtime implements (`RUNTIME_RELEASE`, 6:
  the TypeScript runtime train through the replay-debugger hook, Send and Wait
  under run control and user local activities) and the R2 enums: workflow-id reuse and conflict policies, versioning
  behaviours, workflow timeout types and `LOCAL_ACTIVITY_MAX_TIMEOUT_MS`;
- `history_schema(name)` for the four vendored JSON Schemas (`run-event`,
  `workflow-command`, `workflow-task`, `history-file`);
- `validate_command`, `validate_commands` (shape, the gate, unique ids,
  terminal command last, the activity allow-list), `validate_history` and
  `validate_history_file`, with the TypeScript verdicts and failure causes;
- the command feature gate (C-GATE) the service applies: `command_features`,
  `PHASE_B_CORE_FEATURES`, `PHASE_B_PARITY_FEATURES` (what
  `fluidgrids.durable-parity` adds), `is_relief_command` and `CommandRelief`.
  Pass a feature set as `validate_commands(..., enabled=PHASE_B_CORE_FEATURES)`
  for the service's Phase B verdict. The default levels `"core"` and
  `"parity"` (and `is_command_enabled`) are deprecated: they keep their R1
  meaning, decide by command type only and are not the service's gate (`core`
  accepts the R2 child options and workflow-id targets the service refuses
  without the parity flag, and refuses `CONTINUE_AS_NEW`, which it accepts);
- `load_history(path)` / `parse_history_file(text)`, which raise
  `HistoryFileError` for a file that does not match the schema;
- `is_activity_node_type_allowed` (the activity allow-list) and
  `code_workflow_parent_close_policy` (DB13).

```python
from fluidgrids_workflows.history import load_history

history = load_history("fixtures/histories/signal-wait.history.json")
print([event["type"] for event in history["events"]])
```

Python does not replay histories in Phase B; the replay runner is the
TypeScript SDK's.

## Conformance with the TypeScript SDK

`fixtures/` is vendored from `fluidgrids-workflows-sdk-node` by
`scripts/sync_fixtures.py`, together with reference outputs the published
`@fluidgrids/workflows` computes (`<fixture>/lowered.ts.json` and
`fixtures/ts-vectors.json`). The test suite:

- lowers every fixture's `workflows/<key_snake>.py` and requires the canonical
  JSON to equal the TypeScript lowering of `workflows/<key>.ts` (apart from the
  provenance block) and the `irHash` to equal `fixture.json`;
- checks normalisation, hashing, the executor view, validation codes, canonical
  JSON, SHA-256, durations, schedules, reference parsing, diffs and layouts
  against the TypeScript outputs;
- lowers the Python-owned fixtures in `conformance/` (features that are only
  sugar in a builder, such as `wf.code_workflow`, whose TypeScript twins the
  lifted fixtures cannot express) and compares them with the TypeScript
  lowering of their twin in the same directory;
- loads and validates every history in `fixtures/histories/` and compares the
  history contract with `@fluidgrids/workflows/history`;
- re-records every history with the Python twin of its TypeScript source
  (`conformance/histories/`), requires the history to equal the TypeScript
  recording event for event, replays it to the TypeScript result and replays
  every recorded task;
- checks `fixtures/CHECKSUMS.sha256`, so a hand edit to a vendored file
  (fixtures and the five schemas) fails.

`scripts/ts-reference/` pins the `@fluidgrids/workflows` release the
references come from. To pick up new fixtures, bump that pin (`package.json`
and `npm install --package-lock-only`), then:

```bash
make ts-reference
make sync-fixtures NODE_SDK=../fluidgrids-workflows-sdk-node
```

CI recomputes the TypeScript reference outputs from the pinned package
(`make verify-references`) and fails when they differ from the committed ones.

## Development

```bash
uv sync --locked
make lint          # ruff check + ruff format --check
make typecheck     # mypy --strict
make test          # pytest with the 85% coverage gate
make sanity        # all of the above, plus a build of the sdist and wheel
```

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. The upload uses PyPI trusted publishing when the repository
variable `PYPI_TRUSTED_PUBLISHING` is `true`, otherwise the
`PYPI_BURDENOFF_TOKEN` secret; with neither, the publish job fails and names
the missing secret.

## License

Proprietary. Copyright (c) Algoshred Technologies Private Limited. See `LICENSE`.
