fluidgrids-workflows 2026.1030.1__tar.gz

fluidgrids_workflows-2026.1030.1/.gitignore

@@ -0,0 +1,30 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+build/
+dist/
+
+# Tool caches and reports
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+.coverage.*
+coverage.xml
+htmlcov/
+
+# Node (the TypeScript reference package installed for scripts/sync_fixtures.py)
+node_modules/
+
+# IDE and OS
+.vscode/
+.idea/
+*.swp
+.DS_Store
+
+# Environment and local agent state
+.env
+.env.*
+.claude/

fluidgrids_workflows-2026.1030.1/CHANGELOG.md

@@ -0,0 +1,144 @@
+# Changelog
+
+All notable changes to `fluidgrids-workflows` are recorded here. Versions are
+CalVer (`YYYY.MDD.PATCH`); the release workflow stamps the version, so
+`pyproject.toml` is not bumped by hand.
+
+## Unreleased (R2 vendoring)
+
+The Python side of SDK release R2 (BOFF-9905, work package B19-P2). Python
+tier 2 is still Phase C, so no tier-2 options are added; the Python SDK reads
+and checks R2 histories.
+
+- The fixtures and the five JSON Schemas are vendored from
+  `fluidgrids-workflows-sdk-node` `8274143` (SDK R2: the C-GATE and C-SCHEMA
+  freeze plus the R2 runtime). `fixtures/histories/` now holds 78 histories:
+  the 53 R1 histories, unchanged, and 25 new ones (the 21 R2 conformance
+  histories plus `local-activity-cancelled-in-scope`,
+  `local-activity-abandoned-at-completion`,
+  `continue-as-new-r1-retry-options` and
+  `continue-as-new-r1-long-task-queue`).
+- Histories that Phase B (R1) runs stored keep loading: the vendored schemas
+  leave `WORKFLOW_CONTINUED_AS_NEW.options` a plain object (an R1 run could
+  store a fractional `retryDelay`, a `backoffMultiplier` below 1 or a task
+  queue over 256 characters there), and the activity-shaped `CONTINUE_AS_NEW`
+  retry has the R1 number semantics.
+- The command feature gate (C-GATE) is ported: `CommandFeature`,
+  `COMMAND_FEATURES`, `PHASE_B_CORE_FEATURES`, `PHASE_B_PARITY_FEATURES`,
+  `CORE_CHILD_OPTIONS`, `CORE_CAN_OPTIONS`, `command_features`,
+  `continue_as_new_retry_shape`, `CommandRelief`, `is_relief_command` and
+  `unsupported_feature_message`. `validate_commands` and
+  `is_workflow_command_enabled` take a feature set (`CommandGate`), and
+  `validate_commands` takes the lease's `relief`. The release levels `"core"`
+  and `"parity"` and `is_command_enabled` are deprecated: they keep their R1
+  meaning and are not the service's Phase B gate. `scripts/ts_reference.mjs`
+  records the gate's verdicts for every command batch, 23 new R2 batches
+  among them.
+- `durable_phase_issues` (and `validate(..., refuse_phase_c=True)`) refuses
+  every `code.features` entry that is not a Phase B runtime feature: the Phase
+  C ones and unknown values (`PHASE_B_CODE_FEATURES`,
+  `PHASE_C_CODE_FEATURES`). The IR v2 schema gains
+  `config.retry`, `code.features` and `code.exports.workflows.<fn>.config`.
+- `fluidgrids_workflows.history` gains the C-SCHEMA fields:
+  `WorkflowInfoSnapshot` adds `workflowId`, `runAttempt`, `memo`,
+  `versioningBehavior` and `retry` (and `timeouts` is typed);
+  `WorkflowIdTarget` adds `firstRunId`; `RecordLocalActivityCommand` adds
+  `nodeType`, `operation` and `summary`; `WorkflowTaskResult` adds
+  `unfinishedHandlers` and types `localActivityRequests`.
+- New TypedDicts: `RunRetryPolicy`, `WorkflowTimeouts`, `WorkflowTaskRequest`,
+  `BuiltInQuery`, `LocalActivityRequest` (with `attempt`, `backoffMs` and
+  `summary`), `LocalActivityResult` and `UnfinishedHandler`. New constants:
+  `RUNTIME_RELEASE`, `WORKFLOW_ID_REUSE_POLICIES`,
+  `WORKFLOW_ID_CONFLICT_POLICIES`, `VERSIONING_BEHAVIORS`,
+  `WORKFLOW_TIMEOUT_TYPES` and `LOCAL_ACTIVITY_MAX_TIMEOUT_MS`, checked
+  against the TypeScript values in `fixtures/ts-vectors.json`.
+- New tests compare every history TypedDict, command TypedDicts included,
+  with its definition in the vendored schemas: the keys, the required keys,
+  and the `Literal` values of every `enum` or `const` property (or the
+  constant tuple a `str`-typed enum is built from), so a schema change that
+  the Python types miss fails the suite. `WorkflowTaskRequest.protocol` and
+  `WorkflowTaskResult.protocol` are typed `Literal[1]`. Integer properties stay
+  `int | float`, as in R1: JSON Schema counts `1.0` as an integer.
+- The TypeScript reference outputs come from the published R2,
+  `@fluidgrids/workflows@2026.1029.1` (npm `gitHead` `8274143`), pinned in
+  `scripts/ts-reference`. They differ from the 2026.1028.2 outputs only in
+  `authoring.generatorVersion` and in the history vectors for the new files
+  and constants.
+  The release workflow now runs the same `references` check and publishes
+  only when it passes, so a release cannot ship fixtures no published
+  TypeScript SDK backs.
+
+## Unreleased (2026.1028.x)
+
+Phase B of the code-first spec set (BOFF-9905, work package B2): the Python
+SDK's part of managed durable functions. It pairs with
+`@fluidgrids/workflows@2026.1028.2`.
+
+- `wf.code_workflow(export_name, ...)` adds an `internal:code-workflow` node
+  with `input`, `task_queue`, `wait_for_completion`, `timeout_seconds`,
+  `fail_on_error` and `parent_close_policy`, lowering byte for byte like
+  `wf.codeWorkflow`. Options left out are not written; the service applies the
+  DB13 parent-close default.
+- `wf.wait_for_signal` takes `consume` (`first` or `all`) and `until`
+  (`limitWaitUntil`, an ISO 8601 string or a timezone-aware `datetime`).
+- `validate` ports the B1 rules: the warnings `codeWorkflow.closePolicyEndsChild`
+  and `codeWorkflow.timeoutIgnored`, the error `waitForSignal.invalidDeadline`
+  (with a port of `Date.parse` for ISO strings), and the schema's new
+  wait-for-signal fields.
+- `durable_phase_issues` and `validate(..., refuse_phase_c=True)` report the
+  features that arrive in Phase C (`durable.phaseC`): Python bundles,
+  self-hosted workers, user activities and task queues other than `managed`.
+  `lower_project` returns them as `LowerResult.issues`, and the `lower` command
+  prints them under `issues`; `validate --refuse-phase-c` is the command-line
+  form.
+- `fluidgrids_workflows.history`: the durable-function contract (enums,
+  TypedDicts, the four JSON Schemas vendored from the TypeScript SDK, command
+  and history validation, `load_history`, the activity allow-list and the
+  DB13 default).
+- The fixtures are vendored from `fluidgrids-workflows-sdk-node` `9a02b2c` (tag 2026.1028.2),
+  including the 53 durable-function histories in `fixtures/histories/`; the
+  TypeScript reference outputs come from `@fluidgrids/workflows@2026.1028.2`.
+- `conformance/hybrid-code-workflow/` is a Python-owned conformance fixture
+  with its TypeScript twin; `scripts/ts_reference.mjs` lowers the twin.
+
+## 2026.1027.x
+
+The first release: the Python half of Phase A of the code-first workflows spec
+set (BOFF-9904, epic BOFF-9902).
+
+- The tier-1 graph builder (`define_workflow`, `wf.trigger`, `wf.step` and a
+  helper for every internal node type, typed references and predicates,
+  `expr`, `edge`, `wf.connect`, `wf.edge_order_is`, sticky notes, `extra`),
+  lowering byte for byte to the same IR v2 as `@fluidgrids/workflows` on every
+  shared fixture.
+- `to_ir` / `assemble_recording` with connection resolution, the layout
+  sidecar, the automatic layout and pinned data; `lower_project` for a project
+  directory, with a determinism check that imports the project twice.
+- Ports of the IR tools: `normalize_definition`, `validate` (with `strict` and
+  `is_task_queue_known`), `ir_hash`, RFC 8785 canonical JSON, `stable_stringify`,
+  `diff_definitions`, `executor_view`, `auto_layout`, durations, schedule checks
+  and the `{{ … }}` reference parser; the IR v2 JSON Schema.
+- `fluidgrids_workflows.project` loads the project's generated node clients
+  (`.fluidgrids/nodes.py`), and `op` / `trigger` / `Json` / `FileRef` are the
+  names those clients import.
+- The `fluidgrids-workflows` command line: `lower`, `validate`, `hash`,
+  `normalize`.
+- The shared fixtures and TypeScript reference outputs of
+  `@fluidgrids/workflows@2026.1027.1`, vendored with checksums.
+- Cron schedules are checked by a port of `cron-parser` (`ir/_cron.py`)
+  instead of `croniter`, so `validate` gives the same verdict and fire times as
+  the TypeScript SDK, including the empty expression, `?`, `L`, `#`, `W`,
+  reversed ranges and lower-case or offset time zones. `croniter` is no longer
+  a dependency.
+- `lower` keeps standard output for its JSON result: what the project prints
+  while it is imported (`print`, logging, C code writing to descriptor 1) goes
+  to standard error.
+- The determinism check also re-imports project modules imported by absolute
+  name (`from workflows.helpers import X`), and lowering unloads them.
+- A workflow module that calls `sys.exit` fails lowering with reason `import`.
+- The command line reports every error as one `fluidgrids-workflows:` line,
+  reads files that are not valid UTF-8 with replacement characters as Node
+  does, and reads integers beyond the double range as `Infinity`, as
+  `JSON.parse` does.
+- `validate` leaves `nodeId` out of a per-node issue when the node id is the
+  empty string, as the TypeScript SDK does.

fluidgrids_workflows-2026.1030.1/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

fluidgrids_workflows-2026.1030.1/PKG-INFO

@@ -0,0 +1,356 @@
+Metadata-Version: 2.5
+Name: fluidgrids-workflows
+Version: 2026.1030.1
+Summary: Author FluidGrids workflows as code in Python: the tier-1 graph builder, byte-identical lowering to the workflow IR v2, and the IR tools (normalise, validate, hash).
+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'
+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`).
+
+Python durable (tier-2) workflow functions and the Python worker are Phase C
+(BOFF-9906) and are not in this package yet; `lower` and `validate
+--refuse-phase-c` report what needs them as `durable.phaseC`. 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`.
+
+## 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 arrives in Phase C
+
+`durable_phase_issues(definition)` (in `fluidgrids_workflows.ir`) lists, with
+code `durable.phaseC`, what a definition needs that Phase B does not run: a
+Python code bundle, `determinism: "worker"`, `code.exports.activities` (user
+activities), task queues other than `managed`, and every `code.features` entry
+that is not a Phase B runtime feature: the Phase C ones (`userActivity`,
+`updates`, `queries`, `searchAttributes`, `dynamic`, `interceptors`) and any
+value the SDK does not know, so the check fails closed
+(`PHASE_B_CODE_FEATURES`, `PHASE_C_CODE_FEATURES`). `lower_project` returns them
+as `LowerResult.issues`, `fluidgrids-workflows lower` prints them under
+`issues`, and `validate(..., refuse_phase_c=True)` (`validate
+--refuse-phase-c`) makes them errors. Without that option `validate` gives the
+TypeScript SDK's verdict.
+
+## 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 validate FILE [--strict] [--allow-empty] [--refuse-phase-c]
+fluidgrids-workflows hash FILE
+fluidgrids-workflows normalize FILE
+```
+
+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 the contract describes (`RUNTIME_RELEASE`, 2 from SDK
+  R2) 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`;
+- 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`.