cairndev 0.1.3__tar.gz

cairndev-0.1.3/.dockerignore

@@ -0,0 +1,23 @@
+.git
+.gitignore
+.venv
+venv
+# JS deps — never needed in the engine image (the web dist is prebuilt separately
+# and baked in). They also contain self-referential symlinks to absolute host
+# paths that break hatchling's wheel-build file walk on Linux. Exclude at every depth.
+node_modules
+**/node_modules
+__pycache__
+*.pyc
+*.pyo
+.pytest_cache
+.mypy_cache
+.ruff_cache
+.env
+.env.local
+*.log
+.DS_Store
+docker-compose.yml
+Dockerfile
+.dockerignore
+docs

cairndev-0.1.3/.editorconfig

@@ -0,0 +1,12 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+indent_style = space
+indent_size = 4
+trim_trailing_whitespace = true
+
+[*.{yml,yaml,toml,json,md}]
+indent_size = 2

cairndev-0.1.3/.gitignore

@@ -0,0 +1,100 @@
+# Secrets
+.env
+prod/.env.prod
+.env.local
+.env.*.local
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+*.egg-info/
+.installed.cfg
+*.egg
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+.coverage.*
+htmlcov/
+
+# Virtualenvs
+.venv/
+venv/
+env/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Data caches
+data/chroma/
+*.log
+
+# Eval reports
+evals/last_report.json
+evals/*.report.json
+
+# Build
+build/
+dist/
+# The platform image's build context (#2514): the public wheels the ship step copies beside
+
+# Observability sinks (src/obs)
+events.jsonl
+replays/
+
+# CLI run artifacts: trace dirs (cairn run) + the hash-chained audit log.
+.cairn/
+audit.jsonl
+
+# DuckDB local analytics (scripts/dashboard.py)
+obs.duckdb
+*.duckdb.wal
+*.duckdb.tmp/
+
+# Optional external MCP backend — operators drop this in to enable CAIRN_BACKEND=otel.
+# Without it, the selector falls back to the mock backend with a warning.
+src/mcp/tools/_backends/otel.py
+tests/test_otel_backend.py
+
+# Refactor scratch — incident agent package split kept on disk for reference
+# but not part of the shipped tree. __init__.py files were removed so Python
+# imports src/agents/incident.py (the working single-file module) instead.
+src/agents/incident/
+
+
+.cache/
+.chainlit/
+.files/
+chainlit_app.py
+chainlit.md
+.deepeval/
+.langgraph_api/
+prod/
+
+# stale pre-rename data dir (runtime traces); data now lives in .cairn/
+.obs-agent/
+
+# Never commit a secrets file under any name (an untracked .env backup once held
+# the prod Postgres password, JWT secret and admin hash), nor local work areas.
+.env.*
+!.env.example
+!deploy/light/.env.infisical.example
+# the feature-proof profile's generated keys (scripts/oss/proof_seed.py), never committed
+deploy/light/.proof/
+.proof-out/
+*.bak
+/private/
+/site/
+/data/
+# the generated hello-cairn proof report (scripts/oss/feature_proof.sh)
+/FEATURE_PROOF.md

cairndev-0.1.3/.semgrep.yml

@@ -0,0 +1,36 @@
+# High-signal rules only (engineering OS, 2026-09-11). Not an architecture checker —
+# dependency direction lives in tests/core/test_architecture_boundaries.py.
+rules:
+  - id: cairn.subprocess-shell
+    message: subprocess with shell=True — pass an argv list (docs/security.md §Subprocess)
+    severity: ERROR
+    languages: [python]
+    patterns:
+      - pattern-either:
+          - pattern: subprocess.$F(..., shell=True, ...)
+          - pattern: asyncio.create_subprocess_shell(...)
+          - pattern: os.system(...)
+          - pattern: os.popen(...)
+    paths: { exclude: ["tests/", "**/tests/", "scripts/"] }
+  - id: cairn.command-string-interpolation
+    message: a shell command built from an f-string / format / concatenation — command injection risk; use argv
+    severity: WARNING
+    languages: [python]
+    patterns:
+      - pattern-either:
+          - pattern: subprocess.$F(f"...", ...)
+          - pattern: subprocess.$F("..." % ..., ...)
+          - pattern: subprocess.$F("...".format(...), ...)
+          - pattern: subprocess.$F($A + $B, ...)
+    paths: { exclude: ["tests/", "**/tests/"] }
+  - id: cairn.hardcoded-secret
+    message: a credential-looking literal — load it from a connection or the environment (docs/security.md)
+    severity: ERROR
+    languages: [python]
+    patterns:
+      - pattern-either:
+          - pattern: $KEY = "$VALUE"
+          - pattern: $OBJ[$KEY] = "$VALUE"
+      - metavariable-regex: { metavariable: $KEY, regex: "^(?i)(.*_)?(api[_-]?key|apikey|secret|password|passwd|token|private[_-]?key)$" }
+      - metavariable-regex: { metavariable: $VALUE, regex: "^(?!(sk-test|sk-ci|dummy|test|example|placeholder|change-?me|.*-dev-|\\$\\{|<|https?://|[A-Z][A-Z0-9_]+$)).{12,}$" }
+    paths: { exclude: ["tests/", "**/tests/", "**/test_*.py", "docs/"] }

cairndev-0.1.3/CHANGELOG.md

@@ -0,0 +1,51 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project uses [Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+## [0.1.3]
+
+### Security
+- The server's access log no longer records a bearer token sent in the query string: on the run event stream, which accepts `?access_token=`, the value is logged as `***`.
+- Webhook receivers live under `/triggers/`. A receiver whose path collides with an app route is refused, a receiver is public only for its own method and only with a non-empty signing secret, and its runs land in the workspace that declared it (#141).
+
+### Fixed
+- With no model configured, `cairn dev`, `cairn run --mock` and `cairn gate --mock` sent agentic model calls to the vendor with a placeholder key and failed with a 401. No placeholder key leaves the process now: the call stops with "no model configured: set OPENAI_API_KEY, or OPENAI_BASE_URL …". A keyless OpenAI-compatible endpoint (`OPENAI_BASE_URL`) still gets the call.
+- `cairn remote pipelines` shows each pipeline's name and step progress (it printed `0/0 steps` and no name).
+- The engine image starts with a bare `docker run`: without `CAIRN_PROFILE` it runs the packaged `secure` profile. The bind address still follows sign-in (0.0.0.0 with auth on, 127.0.0.1 with auth off), and the Dockerfile header and the install page show runs that answer. CI starts the built image on every pull request.
+- The Helm example values pin image tags that exist (the bare version), the released chart's `appVersion` is that tag, and the docs, chart README and install notes no longer say the GHCR packages are private (#140).
+- `cairn-admin`, `cairn remote console` and `cairn test` no longer point at extras that do not exist: they name the packages they need and the command that adds them to cairn's own environment.
+- `cairn pack sync` and `cairn pack add` render their colours instead of printing Rich markup.
+- `cairn compute sweep` without an AWS region says to pass `--region` or set `AWS_DEFAULT_REGION`, instead of a traceback.
+- `cairn pipeline show` no longer says flow legs cannot run yet.
+- `cairn dev` no longer promises a console at `/console` (the web console is not part of the public core), and `cairn demo`/`cairn dev --seed` say how to read the `demo` workspace.
+- `cairn init operator` scaffolds a smoke test per operator, so `cairn test <pack>` has something to run.
+- `cairn remote approve`/`reject` (`POST /runs/{id}/resume`) on a pipeline step gate answers 409 with the `cairn remote advance` command, not 502, on the in-process runtime; under DBOS and Temporal the step-gate resume is unchanged.
+- When a capability has no binding in the active profile, `cairn validate` names the active profile and the profiles the pack ships (hello-cairn validates under `profiles/hello.toml`).
+
+### Changed
+- CONTRIBUTING matches the public tree: the sync line includes `runtime-dbos` (the DBOS runtime tests need it), the console, npm, pre-commit and status-audit steps are gone, `cairn dev --engine-only` with a CLI login is the dev loop, and the CI gates and branch protection are described as they are.
+- The quickstart's `pip` alternative installs from the GitHub Release (`--find-links`) until the packages are on PyPI.
+- Feature proof: the run hook (`hooks`) is proved on `profile-and-publish`, which every cell runs, and the `public-e2e` job installs the `hello` extra that declares it. `secrets.infisical` and `worker.pull` stay NOT PROVED, each with the reason.
+
+## [0.1.2]
+
+### Security
+- A bearer token in the URL (`?access_token=`) is accepted only on the run event stream; anywhere else it is refused (401).
+- A per-run worker token reaches only its own run's reporting routes (events, control, heartbeat); anything else answers 403.
+- A webhook receiver answers without a cairn token only when its signature is required; an optional-signature receiver stays behind sign-in.
+- The OAuth callback is reachable without a token (the provider's redirect carries none) and escapes everything it shows; the saga approval decides on `POST /triggers/approve/{id}` only.
+- The workspace check covers the credential the auth guard accepted, so a token for one workspace cannot read another workspace's run stream.
+
+### Fixed
+- The quickstart's `cairn remote login` failed on a plain install with "password hashing needs the 'auth' extra": `cairn dev` turns on password sign-in, so `pwdlib[argon2]` is now a base dependency (the `auth` extra still works and installs nothing more).
+- `cairn dev` and `cairn remote` start the engine with `python -P`, so a `cairn/` folder in the working directory (a checkout) is never imported in place of the installed engine.
+
+## [0.1.1]
+
+### Added
+- 0.1.1, the first complete public release: the engine `cairndev`, `cairn-client`, the optional Metaflow and SkyPilot dataflow engines (`cairn-operator-dataflow-metaflow`, `cairn-operator-dataflow-skypilot`) and the example pack `cairn-pack-hello`.
+
+### Changed
+- The builtin operator packs and the core contracts ship inside the `cairndev` wheel (ADR-0137): they are no longer distributions of their own, and their extras are `cairndev` extras (`ssh`, `train`, `infisical`, `dataflow-engine`, `rerank-cross-encoder`, `rerank-cohere`).

cairndev-0.1.3/CITATION.cff

@@ -0,0 +1,9 @@
+cff-version: 1.2.0
+title: cairn
+message: If you use this software, please cite it as below.
+type: software
+authors:
+  - name: cairn maintainers
+repository-code: https://github.com/cairndev-sh/cairn
+url: https://cairndev.sh
+license: Apache-2.0

cairndev-0.1.3/CODE_OF_CONDUCT.md

@@ -0,0 +1,7 @@
+# Contributor Covenant Code of Conduct
+
+This project adopts the [Contributor Covenant](https://www.contributor-covenant.org/version/2/1/code_of_conduct/), version 2.1.
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the maintainers at the address in SECURITY.md. All complaints are reviewed and investigated promptly and fairly.
+
+The full text of the Covenant, including the enforcement guidelines, applies as published at the link above.

cairndev-0.1.3/CONTRIBUTING.md

@@ -0,0 +1,218 @@
+# Contributing to cairn
+
+Welcome! cairn is a governed ML control plane — identity, policy, HITL gates,
+cost, lineage and audit for data/ml/agentic pipelines. This guide gets you from
+clone to a running dev environment in about 15 minutes, with no tribal
+knowledge required.
+
+> **New here?** Start with this file, then the public
+> [Quickstart](https://docs.cairndev.sh/quickstart/) for the runtime side
+> (choosing SQLite vs Postgres, seeding demo fixtures, starting the server).
+> This file covers *contributing*; that one covers *running*.
+
+## Quickstart (the 15-minute path)
+
+```bash
+git clone https://github.com/cairndev-sh/cairn && cd cairn
+
+# 1. Python env (uv: https://docs.astral.sh/uv/)
+uv sync --extra dev --extra rag --extra rag-sqlite-vec \
+        --extra runtime-sqlite --extra runtime-temporal \
+        --extra runtime-dbos --extra telemetry --extra auth \
+        --extra ssh
+
+# ⚠ Any later bare `uv sync` REMOVES every extra not named on that command
+# line — auth, temporal, dbos and anything else you added (e.g. `--extra pii`
+# for presidio) vanish silently. After any sync, re-run the full command above.
+# (`uv run <cmd>` adds what is missing but removes nothing.)
+
+# 2. A local engine on a pinned sqlite config, with demo data
+uv run cairn dev --engine-only --seed
+
+# 3. In another shell: sign in and drive it
+uv run cairn remote login -u dev -p dev -e http://localhost:8000
+uv run cairn remote launch hello-cairn/profile-and-publish --environment sandbox \
+    -i path=$PWD/examples/hello-cairn/data/sample.jsonl --watch
+```
+
+`cairn dev` starts the engine on http://localhost:8000 on a **pinned** sqlite
+config (`~/.cairn/dev.db`): a stale `.env` can never redirect your dev session to
+someone's postgres. Sign in with **dev / dev**. From a checkout it adds
+`examples/hello-cairn` to `CAIRN_PACK_PATH`. `--seed` writes deterministic demo
+records (three pipelines, one paused at a person gate) into the `demo` workspace;
+`cairn remote` reads the default workspace, so send `X-Cairn-Workspace: demo` to
+the HTTP API to see them. The web console is not part of this repository, so pass
+`--engine-only`. Other flags: `--port`, `--db`.
+
+## Working on a pack
+
+A pack is discovered through the `cairn.packs` entry-point group, which is an
+*install*-time fact — so a freshly scaffolded pack is invisible to the engine
+until it is installed. Two loops (#1545):
+
+```bash
+cairn init pack mypack
+
+# 1. Zero-install loop: the engine scans these dirs on every start.
+export CAIRN_PACK_PATH="$PWD/mypack"     # `cairn pack add --dev mypack` prints this
+cairn ls mypack                          # edits take effect on the next run
+
+# 2. Make it permanent: wires the three root-pyproject.toml points
+#    (workspace member + dependency + [tool.uv.sources]) and prints the sync
+#    to run. Idempotent; it never syncs for you (a bare `uv sync` strips extras).
+cairn pack add mypack
+```
+
+An **installed** pack always wins a name collision with a `CAIRN_PACK_PATH`
+copy, so a dev pack can never silently shadow a deployed one; a broken dev pack
+is skipped with a warning (`cairn ls` lists load failures) rather than taking
+the engine down. A pack's `[compat] cairn_engine` range is checked against the
+installed engine at load time — a mismatch warns, in the log and as a
+`pack_compat:<name>` row in `cairn doctor`, and still loads.
+
+## Running tests
+
+```bash
+.venv/bin/pytest tests/core -q     # engine/core
+.venv/bin/pytest -q                # everything, incl. operator-pack tests
+uvx ruff check .                   # lint, the rule set CI runs
+```
+
+`tests/core/test_dbos_runtime.py` needs the `runtime-dbos` extra (in the sync line
+above). CI's `public` job runs `tests/core`, `tests/cli`, `tests/deploy` and the
+optional engines' own tests with `-m "not dbos and not timing and not e2e"`; its
+`public-e2e` job runs the feature proof (`-m e2e tests/e2e`, Postgres and DBOS cells
+included). `scripts/oss/feature_proof.sh` runs the same proof locally with services.
+
+The builtin operator packs and the core contracts are part of the `cairndev`
+project (ADR-0137). An editable install reads the packs' code and `pack.toml`
+from `packages/`, but holds COPIES of the contract definitions
+(`packages/cairn-contracts-*/definitions`). After editing a contract, refresh
+them: `uv sync --reinstall-package cairndev` (with the extras you use).
+
+`.venv/bin/pytest` and `uv run pytest` run the same environment: `uv run` installs
+what is missing but removes nothing, so the extras from the sync line stay.
+
+The suite is hermetic: no keys, no databases, no network. If a test you write
+needs a real backend, it must opt in explicitly — the repo `.env` is
+neutralized in `tests/conftest.py` on purpose. That neutralization covers the
+`.env` file only: a storage variable **exported in your shell** (a value that
+differs from `.env`) is treated as deliberate and steers the suite. If your
+shell exports one, unset it for the run:
+
+```bash
+env -u CAIRN_STORAGE .venv/bin/pytest tests/core -q
+```
+
+
+## Other CI gates
+
+- **`uv.lock`** — the install is `uv sync --locked`, so a dependency or version
+  change needs `uv lock` in the same PR (`uv lock --check` tells you).
+- **The wheels** — `scripts/check_folded_wheels.py` builds the five wheels and
+  checks that `cairndev` carries the builtin operators and the core contracts.
+- **The engine image** — the `image` job builds `Dockerfile.engine` and starts it.
+
+## Documentation
+
+The user docs at [docs.cairndev.sh](https://docs.cairndev.sh) are the Astro/Starlight site in
+`docs/site/`. Every pull request gets a preview deployment, and `main` deploys to production.
+Build it locally with `npm ci && npm run build` in `docs/site/`. The one-line installer is
+`docs/site/public/install.sh`, served at `https://docs.cairndev.sh/install.sh`.
+
+## Pull requests
+
+1. **One issue, one branch, one PR.** Open or claim a GitHub issue first;
+   branch from `main` (`fix/<issue>-slug` / `feat/<issue>-slug`). Never commit
+   to `main`.
+2. **CI must be green** — the required checks are the merge gate, not a
+   suggestion. PRs test one Python version for fast feedback; `main` re-proves
+   the full matrix.
+3. Comment progress on the issue as slices land; close it with a summary.
+4. Code style: match the surrounding code. Imports at module top (lazy imports
+   only for optional extras or real cycles, with a one-line reason). Operator
+   pack tests live inside the pack's own `tests/`, not top-level `tests/`.
+5. New operators ship with golden-fixture tests. Packs are data (md + YAML) —
+   code belongs in operator packs.
+6. **Regenerate what your change invalidates**: `uv lock` after a dependency or
+   version change, and the docs page a behaviour change makes wrong.
+7. **Sign off every commit (DCO).** Contributions are Apache-2.0 under the
+   [Developer Certificate of Origin](https://developercertificate.org/): commit
+   with `git commit -s`, which adds a `Signed-off-by: Your Name <you@example.com>`
+   line matching the commit author. The public repository's `dco` check refuses a
+   pull request with an unsigned commit; `git rebase --signoff main` fixes a branch after the fact.
+
+### What review looks for
+
+Reviews here are about evidence, not style policing — the formatter handles
+style. In rough priority:
+
+1. **Is the claim verified?** The PR says how it was checked, and the check
+   actually proves the thing. For anything user-facing, that means the real
+   surface was driven, not just a green unit test.
+2. **Was the problem re-verified before it was fixed?** Issues go stale.
+   Several "bugs" here turned out to be already fixed, or scoped wrong in the
+   issue. Saying "the issue was wrong, here's what's actually true" is a good
+   PR, not a failed one.
+3. **Does this rebuild something that exists?** Upstream libraries, existing
+   stores, shipped mechanisms. Extending beats duplicating.
+4. **Are failures reported honestly?** A known-failing test, an unverified
+   corner, a skipped step — all fine when stated. Not fine when discovered
+   later.
+
+Two things worth saying out loud, because they're easy to get wrong under
+time pressure: **never inherit a test baseline** (diagnose each failure's
+cause rather than memorising a count — an "11-failure baseline" here was
+4 wiped-venv, 2 stale tests, and 0 real defects), and **an empty grep proves
+nothing** until you've checked your search terms against the codebase's own
+vocabulary.
+
+### What gates a merge to `main`
+
+`main` is a protected branch:
+
+- **Every change lands through a PR** with one approving review; conversations
+  must be resolved, and force pushes and deletion are refused.
+- **Required checks**: `public` and `public-e2e` (`ci.yml`) and `dco` (`dco.yml`),
+  on a branch up to date with `main`. The `image` job runs on every PR too; a red
+  one is fixed in the PR, not merged around.
+
+## Where decisions live (reading order)
+
+1. [docs/architecture/00-overview.md](docs/architecture/00-overview.md) — the system, top-down.
+2. [docs/decisions/](docs/decisions/README.md) — the ADR log. Start with
+   ADR-0020 (the locked pack contract), ADR-0084 (control plane: one flow
+   concept, pipelines as the runnable surface), ADR-0085 (this contributor
+   experience and where it's going).
+3. The GitHub issue tracker — what's in flight. Issues labeled
+   `good-first-issue` are curated to be self-contained.
+
+Changing a locked surface needs a **new ADR**, not an edit to an old one.
+
+## Layout in one paragraph
+
+`src/cairn/core/` is the engine (dispatch, storage, policy, triggers/API server) and
+`src/cairn/cli/` the `cairn` command; `packages/cairn-operator-*` are the builtin
+operator packs and `packages/cairn-contracts-*` the core capability contracts, both
+shipped inside the `cairndev` wheel (ADR-0137), except the two optional engines
+(`cairn-operator-dataflow-metaflow`, `cairn-operator-dataflow-skypilot`), which are
+wheels of their own; `packages/cairn-client` is `cairn-client`, the typed API client
+(no `cairn.core` imports — CI-enforced); `examples/hello-cairn` is the example
+domain pack (data only, its own `cairn-pack-hello` wheel); `deploy/` holds the
+compose stack and the Helm chart; `docs/site/` is docs.cairndev.sh. The web console
+and the product modules are the private platform (ADR-0120 D3, ADR-0121), which the
+public core reaches only through entry-point groups (`cairn.routers`, `cairn.cli`,
+`cairn.run_hooks`, `cairn.model_catalogs`, `cairn.seeds`); `docs/decisions/` is why
+everything above is the way it is.
+
+## The public core and the platform
+
+`uv sync --extra dev` installs the public set (the engine with the builtin operator
+packs and the core contracts, and the client) and nothing private; the `public` CI
+job proves that set installs alone and passes `tests/core`, and
+`scripts/check_public_set.py` refuses any private distribution. Three rules the
+boundary tests enforce:
+the public core never imports `cairn_platform` or a domain pack; an operator pack
+imports only `cairn.core.operator` (its re-exports cover what a pack needs from the
+core) plus `cairn.core.dataflow` for engine providers; product logic lives in the platform,
+and what stays in core by decision is justified in `cairn/core/CLAUDE.md` (#2497).

cairndev-0.1.3/Dockerfile.dataflow-task

@@ -0,0 +1,83 @@
+# The image a REMOTE dataflow/ml task runs in (ADR-0089 #1346).
+#
+# `Dockerfile.engine` builds the CONTROL PLANE — server, console, every runtime
+# extra, torch under PRODUCTION_TIER. A Metaflow `@kubernetes`/`@batch` task
+# needs none of that: it runs ONE `CairnFlow.execute` step, which parses a
+# DataflowSpec and drives the shared runner over the kernel registry. So this
+# image carries exactly that, and is small enough to pull onto a cold node
+# without dominating the job's wall clock.
+#
+# What a task genuinely needs:
+#   * metaflow           — the task process itself is `python -m metaflow …`; the bridge it
+#                          runs is cairn-operator-dataflow-metaflow's (ADR-0134 D2)
+#   * cairn core         — DataflowSpec/DataflowResult (the boundary contract) and the
+#                          shared `run_dataflow` runner + stage loader (cairn.core.dataflow, #2583)
+#   * cairn-operator-dataflow  — the engine entrypoint (cairn-dataflow-run); the Metaflow
+#                          bridge flow is cairn-operator-dataflow-metaflow's (ADR-0134 D2)
+#   * the kernel packs   — whatever `spec.stages` names must be resolvable, or
+#                          the flow fails at stage 0 having already paid for the
+#                          node (engine.validate() catches this control-side,
+#                          but only for stages the CONTROL PLANE can see)
+#   * boto3              — the S3 datastore is mandatory for remote compute
+#                          (#1349 refuses remote + local datastore)
+#
+# Deliberately absent: torch, the console SPA, temporal/dbos runtimes, the
+# server. A task that needs a GPU trainer uses the training image instead —
+# this one is the data/ml-kernel substrate.
+FROM python:3.13-slim-trixie
+
+ENV PYTHONUNBUFFERED=1 \
+    PIP_DISABLE_PIP_VERSION_CHECK=1 \
+    PIP_NO_CACHE_DIR=1
+
+# `uv` for resolution speed; git because a few kernel extras resolve VCS pins.
+RUN apt-get update && apt-get install -y --no-install-recommends git \
+    && rm -rf /var/lib/apt/lists/* \
+    && pip install uv
+
+WORKDIR /app
+
+# Source layout mirrors the workspace so the operator packs resolve as local
+# path deps exactly as they do in CI — a task must run the SAME kernel code the
+# control plane validated against, not a re-resolved PyPI version.
+COPY pyproject.toml README.md ./
+COPY cairn ./cairn
+# `client`, `ask` and `sdk` are uv WORKSPACE MEMBERS (ADR-0085 D7 / ADR-0087):
+# `[tool.uv.sources]` pins them `workspace = true`, so resolution of the root
+# package FAILS ("references a workspace … but is not a workspace member") if
+# any of the three is absent — even though a dataflow task imports none of
+# them. They are small; omitting one costs a full failed build to discover.
+COPY client ./client
+COPY ask ./ask
+COPY sdk ./sdk
+# #2241 D — the contract distribution is a workspace member (`editable = false`) on the
+# same rule; a task imports none of it, but resolution of the root fails without it.
+COPY contracts ./contracts
+
+# `--extra engine` is the whole point: it pulls the dataflow engine + kernel
+# runtimes (polars/duckdb) the stages actually execute in. Installing the root
+# package alone yields an image whose flow dies with "unknown stage".
+RUN uv pip install --system --no-cache \
+        -e . \
+        -e ./cairn/operators/builtins/dataflow \
+        -e ./cairn/operators/optional/dataflow_metaflow \
+        -e ./cairn/operators/official/dataset_checks \
+        metaflow boto3 \
+    && uv pip install --system --no-cache polars duckdb \
+    # `kubernetes` is the CLIENT the submitter uses to talk to the API server.
+    # Its absence does not error — Metaflow simply never schedules and the
+    # submit hangs (observed: 10 minutes, no pod). Present here because this
+    # image doubles as the submitting environment in the ADR-0089 acceptance.
+    && uv pip install --system --no-cache kubernetes
+
+# Fail the BUILD, not the first remote task, if the registry cannot resolve the
+# kernels this image exists to run.
+RUN python -c "\
+from operator_dataflow.stages import load_stages; \
+s = load_stages(); \
+assert 'ingest.normalize' in s and 'dedup.exact' in s, sorted(s); \
+import metaflow, boto3; \
+import operator_dataflow_metaflow.metaflow_bridge, operator_dataflow_metaflow.metaflow_train_bridge; \
+print('task image OK — kernels:', len(s))"
+
+CMD ["python", "-c", "print('cairn dataflow task image')"]