README
¶
Integrated specifications
spec/ contains deterministic, end-to-end scenarios that combine multiple Flow features and domain actions. These are acceptance-style examples: they show how a real workflow fits together and assert the result, rather than isolating one extension's syntax.
Scenarios
- Order intake validates an order, normalizes the customer's email, calculates a safe subtotal, applies a bounded retry policy, enforces a macro invariant, and returns an explicit accepted-order record. The separate email normalization check sends a lowercase email with surrounding spaces directly to
order.normalize, bypassing schema validation so its assertion isolates whitespace trimming; the main scenario retains uppercase-to-lowercase coverage. - Support triage validates and classifies a duplicate-charge ticket, routes it to the billing escalation queue, and creates a reply draft without sending a customer message. The unavailable-upstream case preserves the ticket for manual review and explicitly keeps the reply unsent.
- Payment reconciliation matches payment and bank references, reports mismatches and bank-only rows as audit exceptions, calculates totals in integer cents, and asserts that the batch variance is zero.
Structure and conventions
Each scenario is self-contained. When a workflow needs domain-specific Go actions, keep their implementation in that scenario's bundle/library.go and require it from the flow:
@require ./bundle
The local package uses the repository's single root Go module; do not add a nested go.mod. Keep the NFlow entrypoint beside its scenario bundle, use additional entrypoints for meaningful paths such as happy, failure, and recovery, and make assertions describe observable outcomes. Use fixed inputs and local deterministic behavior so the checks run offline and do not send messages, change accounts, or mutate external systems.
Use extensions/<name>/nflows/*.nflow for a single extension's conformance examples, with descriptive filenames and flat companion files. Use root spec/ when the value is the composition: multiple extensions, local domain actions, and a realistic workflow contract. Tutorial-first walkthroughs live in the central examples repository.
Run all integrated scenarios with:
task specs
This builds the CLI once, then runs every spec/<scenario>/*.nflow entrypoint through nflow run, which evaluates its @assert directives. The one-level glob deliberately includes all entrypoints beside scenario bundles while leaving nested included helpers such as 02_support_triage/common/triage.nflow to be loaded by their parent workflow. Every matched entrypoint is attempted; any execution or assertion failure makes the task return a non-zero exit status. Add new scenario entrypoints beside their scenario bundle; the specs task discovers them automatically.
task ci, also invoked by the GitHub Actions CI workflow, runs task specs together with the native extension self-tests and the Go lint/test gates. task test runs Go tests, including the extension conformance gate and host-configured embed fixture, but it does not execute the integrated scenarios. The CLI extension self-test gate is also useful on its own:
task self
Directories