> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bijection.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Orchestrate pipelines with Prefect

> Generate typed Prefect tasks with durable admission, exact results, and coordinated release checks.

Prefect schedules and observes Bijection computations. Bijection admits exact
inputs and verifies complete output groups; the installed external compute
resource executes the program. The adapter supports Prefect `>=3.8.8,<3.9` and
Python 3.12+. Install the application Python SDK and `packages/prefect` from your
Bijection source distribution into your Prefect runtime.

```mermaid theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
flowchart LR
  Definition[Pipeline declaration] --> Generated[Generated Python contracts]
  Generated --> Binding[Prefect binding registry]
  Binding --> Task[Prefect task]
  Task --> Admission[Immutable Bijection admission]
  Admission --> Compute[Customer compute]
  Compute --> Accepted[Accepted complete output group]
  Accepted --> Task
```

Generate from the application's analyzed contracts:

```sh theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
bijection codegen
bijection orchestration codegen --adapter prefect --python-package acme_bijection \
  --out orchestration/generated
```

Put the generated package on the Python import path. For a UTC daily pipeline
exported as `revenue:refresh`, bind its typed parameters and complete outputs:

```python theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
import bijection_prefect as bp
from acme_bijection import datasets
from acme_bijection.prefect import revenue_refresh as revenue

daily = revenue.bind(
    binding_id="finance.daily_revenue",
    partitioning=bp.utc_daily(start="2026-01-01"),
    parameters=revenue.Parameters(
        start_ms=bp.partition.parameter("start_ms"),
        end_ms=bp.partition.parameter("end_ms"),
    ),
    inputs=revenue.Inputs(orders=bp.selected_at_admission(datasets.orders)),
    outputs=revenue.Outputs(revenue="bijection://finance/revenue", totals="bijection://finance/totals"),
    completion="accepted",
)
run_revenue = daily.as_task(connection="finance-production")
registry = bp.Registry(tasks=[run_revenue])
```

Call `await run_revenue(partition=day, call_key="refresh")` inside an async
Prefect flow. The result has typed `revenue` and `totals` references. The logical
call key and flow-run identity survive retries. Pass an explicit `occurrence`
to recover across different flow runs. Separate intentional calls need distinct
call keys. Retry counters and task-run IDs do not identify computations.

Configure a `BijectionConnection` Prefect block with installation, mounted
credential file and durable `handles_uri`. Local directories work for development;
distributed workers require shared storage. S3 needs `bijection[orchestration-s3]`.
Receipts use atomic conditional publication; arbitrary filesystem drivers are
refused. Native custody and current permissions remain authoritative.

Recovery precedes mutable input resolution, and accepted output groups are
retained before framework projection. `bp.upstream_result(producer, "output")`
declares exact dependencies; supply their typed references in `RuntimeInputs`
and include producer tasks in the registry. Unknown or expired references fail
without a latest-version fallback. Task caching and Prefect result persistence
are disabled for these orchestration tasks, including under global cache settings.

`accepted`, `selected` and `served` completion modes observe distinct native
states. Waits never select results. Timeout and cancellation stop observing;
they do not implicitly cancel computation. Asynchronous observation keeps the
event loop responsive but retains the Prefect runtime process. Partitions are
unpartitioned or aligned UTC daily windows with identity mappings. Date labels
do not establish source completeness or historical retention.

Export and check the explicit registry without running flows:

```sh theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
bijection orchestration export --adapter prefect \
  --entrypoint orchestration.bindings:registry --python .venv/bin/python \
  --out build/orchestration-bindings.json
bijection orchestration check --bindings build/orchestration-bindings.json --offline
```

Build the immutable Prefect image, then capture the release with
`bijection orchestration release --bindings ... --generated-package ... --deployment-spec prefect.yaml --runtime-artifacts build/prefect-runtime-artifacts.json --python ... --out ...`.
Declare deployment names and flow entrypoints in `Registry(flows={...})`.
Each deployment must name an existing work pool and an immutable image in
`work_pool.job_variables.image`. Capture resolves environment templates and
refuses unresolved values or identities that differ from the declared registry.
It records source and resolved hashes without copying credential values or
executing deployment steps. Keep this manifest outside
the image whose digest it records. Add the exported bindings and release paths
to `bijection.json`'s `orchestration` configuration. Ordinary preparation checks
and captures them and the referenced deployment source bytes. Configure the block's
`release_file`, `generated_package`, `runtime_artifacts` and `deployment_spec`
to verify actual loaded artifacts before native calls. Task options are also
checked before entering Prefect, so cache-policy changes cannot skip the guard.
The artifact file maps `flow_worker` to its complete immutable `sha256:…` digest.
Image identities remain claims, not execution attestation.

Deploy Bijection, preflight it with `bijection orchestration check --bindings ... --target ... --credential ...`, then activate the corresponding Prefect image.
Preflight admits no computation. Export validates the declared registry;
arbitrary dynamic Python branches remain runtime concerns.

Prefect assets retain native acceptance metadata and program/definition digests
separately from task state. Successful selection and serving waits emit their
observed states; failed waits preserve acceptance without claiming completion.
Optional `lineage_namespace` reports through the installed OpenLineage owner;
`lineage_required=True` retries failed reporting against the same accepted result.
`events_required=True` requires successful Prefect event enqueue, which does not
establish server delivery. Reports carry no native acceptance or selection
authority, and Prefect transaction rollback cannot undo native acceptance.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.