cairn-pack-hello 0.2.0__tar.gz

cairn_pack_hello-0.2.0/.gitignore

@@ -0,0 +1,3 @@
+# The root .gitignore drops every `data/` dir (scratch datasets); this pack's
+# sample IS source, so it is re-included here.
+!data/

cairn_pack_hello-0.2.0/PKG-INFO

@@ -0,0 +1,238 @@
+Metadata-Version: 2.5
+Name: cairn-pack-hello
+Version: 0.2.0
+Summary: Example cairn domain pack: a data, an agentic, an ml and an operations pipeline, each behind gates.
+License: Apache-2.0
+Requires-Python: >=3.12
+Requires-Dist: cairndev>=0.1.0
+Provides-Extra: all
+Requires-Dist: cairndev[rag-sqlite-vec,runtime-dbos,ssh]>=0.1.0; extra == 'all'
+Description-Content-Type: text/markdown
+
+# hello-cairn: the example pack
+
+`hello-cairn` is a domain pack: data plus a little glue, no operators. It runs on the cairn
+engine and its builtin operator packs alone. Its four pipelines each do one thing a new user
+recognises, and together they exercise what the engine adds around a piece of work: gates
+answered by data or by a person, budgets, triggers, an agentic template, an MCP tool,
+retrieval, a run hook, SSH, secrets, and an audit record.
+
+| Pipeline | Kind | What it does |
+|---|---|---|
+| `profile-and-publish` | data | Profile a dataset, stop unless the profile passes, redact the summary, run a flow, stage it, ask a person, tag it, publish it, audit it. |
+| `ask-the-docs` | agentic | Retrieve from the pack's docs, ask a model, measure the answer with a tool on the pack's own MCP server, remember it, check its length, ask a person. |
+| `nightly-ops` | operations | Check a secret, run a report on an SSH box, carry it through a flow, propose the follow-up to a person, audit it. Nightly once enabled; a run hook writes receipts. |
+| `tiny-finetune` | ml | Profile training rows, LoRA fine-tune a small model on CPU, gate on its held-out loss, tag it, ask a person, write its card. |
+
+## Quickstart
+
+Run everything from the repository root: relative paths in the pipelines' defaults resolve
+against the engine's working directory.
+
+### 1. Install, and point the engine at the example
+
+```bash
+uv sync --extra dev --extra hello --extra rag   # add --extra auth if your engine needs it
+export CAIRN_PROFILE=examples/hello-cairn/profiles/hello.toml
+```
+
+`--extra rag` is what lets the engine index the docs corpus at boot (LlamaIndex ingest);
+without it ask-the-docs still runs and retrieves nothing. `auth` is optional: `cairn dev`
+signs you in as dev/dev without it.
+
+`cairndev[hello]` installs this pack as the wheel `cairn-pack-hello` plus what its pipelines
+reach beyond the base install: the sqlite-vec store (retrieval and memory), asyncssh
+(`remote/exec`) and DBOS (`CAIRN_RUNTIME=dbos`). Without installing it,
+`export CAIRN_PACK_PATH=examples/hello-cairn` loads the same directory as a dev pack; a dev
+pack declares no entry points, so the run-hook listener does not fire.
+
+`profiles/hello.toml` is the deployment profile the example runs under. It carries
+`cairn/profiles/local-dev.toml`'s bindings for the builtin operators (memory, storage, rag,
+mcp), but not local-dev's `eval.delta` binding (a platform operator) or its `llm_gateway` and
+`embedder` backend entries: the model and the embedder come from the engine's environment
+(step 3). It adds `secrets.store` → `secrets/env` (nightly-ops' secret check is a capability
+node and compiles only with a binding, which local-dev does not carry) and the `hello-calc`
+MCP server the pack declares. It pins no runtime, so `CAIRN_RUNTIME=dbos` selects DBOS.
+
+### 2. See what will happen before anything runs
+
+```bash
+cairn pipeline explain hello-cairn/profile-and-publish -e sandbox
+cairn validate examples/hello-cairn          # with CAIRN_PROFILE set as in step 1
+```
+
+`cairn validate` needs the example's profile: under local-dev the nightly-job template does
+not compile (no `secrets.store` binding).
+
+`explain` lists every leg with the operator class or flow file it resolves to, the gate that
+answers it, and the budget, series and approvers.
+
+### 3. Start an engine
+
+```bash
+export OPENAI_API_KEY=sk-...                 # ask-the-docs' model call and embeddings
+export RAG_EMBED_PROVIDER=openai             # retrieval and memory embed with OpenAI
+export CAIRN_RAG_AUTOINDEX=1                 # index rag/docs at boot (needs the `rag` extra)
+export CAIRN_MCP_SERVERS='{"hello-calc": {"transport": "stdio", "command": "python",
+  "args": ["examples/hello-cairn/tools/calc_server.py"]}}'
+cairn dev --engine-only --port 8471 &        # sqlite engine, in-process runtime, login dev/dev
+cairn remote login -u dev -p dev -e http://localhost:8471
+```
+
+Any OpenAI-compatible endpoint works in place of a key: `OPENAI_BASE_URL`, or
+`LLM_GATEWAY=proxy` with `LLM_GATEWAY_URL`. The engine has no built-in mock model, and
+`CAIRN_BACKEND=mock` is the telemetry backend, not a model. `profile-and-publish` and
+`nightly-ops` call no model.
+
+### 4. Run each pipeline
+
+**profile-and-publish**
+
+```bash
+cairn remote launch hello-cairn/profile-and-publish --environment sandbox --watch
+cairn remote advance <pipeline_id> review        # the person gate
+cairn remote advance <pipeline_id> promote       # the operator's own gate
+```
+
+The pipeline stops a second time at `promote`: `artifact/promote` declares
+`requires_approval`, and a pipeline can add a gate but never remove one an operator declares.
+`cairn remote advance` approves either kind and records the signed-in user as the approver.
+
+The record ends `done`: `data-ok` has verdict `data`, `review` `approved`, `promote` the
+tag `hello-sample@published` on the flow leg's registered artifact, and `audit` a
+hash-chained row in `CAIRN_AUDIT_LOG` (default `./audit.jsonl`). `storage/put` writes under
+`CAIRN_ARTIFACTS_DIR` (default `~/.cairn/artifacts`). With `-i min_rows=1000` the data gate
+stops the pipeline (`gate_blocked`) before anything is written. Launch with
+`--environment hello-prod` and the pack's policy
+(`policies/require-review-on-publish.yaml`) stops `stage` for an approval before it writes.
+
+**ask-the-docs**
+
+```bash
+cairn remote launch hello-cairn/ask-the-docs --environment sandbox --watch
+cairn remote advance <pipeline_id> review
+cairn remote findings <pipeline_id>              # hits, answer, answer_stats, remembered
+```
+
+The `assistant` leg (`flows/assistant.md`) searches the `docs` corpus (`rag/docs`, declared
+in `pack.toml` as `[requires.rag.docs]`), re-ranks, asks the model, calls `word_count` on
+`tools/calc_server.py` through `mcp/call`, and writes the exchange to the `hello_answers`
+memory store. `length` flags answers longer than `max_words`. An un-indexed corpus returns no
+hits and the model says the docs do not cover the question. Retrieval uses sqlite-vec unless
+`RAG_VECTOR_STORE=pgvector`.
+
+**nightly-ops**
+
+```bash
+export HELLO_REPORT_TOKEN=...                    # the secret the job checks for
+export HELLO_SSH_KEY="$(cat ~/.ssh/id_ed25519)"  # in the ENGINE's environment
+CAIRN_STORAGE=sqlite:///$HOME/.cairn/dev.db \
+cairn connect add ssh --name hello-ssh --set host=<box> --set user=<user> \
+  --set known_hosts=$HOME/.ssh/known_hosts --secret PRIVATE_KEY=HELLO_SSH_KEY
+cairn remote launch hello-cairn/nightly-ops --environment sandbox --watch
+```
+
+The connection goes into the engine's store, hence `CAIRN_STORAGE`; its secret is an env var
+NAME the engine reads. The box needs `sh`, an SFTP subsystem, and `setsid` (Linux) or
+`perl` (macOS): `remote/exec` detaches the job into its own session through whichever is
+present (#2606). `job` (`flows/nightly-job.md`) checks the secret through the profile's
+`secrets.store` binding, then runs `command` on the box and reads back `metrics.json`.
+`propose` waits for a person (`monitor/propose` declares `requires_approval`;
+`cairn remote advance <pipeline_id> propose`). With the wheel installed, every settled leg
+appends a line to `$CAIRN_HOME/hello-cairn/receipts.jsonl` (default `~/.cairn`).
+
+For secrets in Infisical, run the engine with
+`CAIRN_PROFILE=examples/hello-cairn/profiles/hello-infisical.toml`, `uv sync --extra
+infisical`, and `INFISICAL_CLIENT_ID`, `INFISICAL_CLIENT_SECRET`, `INFISICAL_PROJECT_ID`
+(and `INFISICAL_HOST` for a self-hosted server). Nothing in the pipeline changes.
+
+**tiny-finetune**
+
+Needs the builtin train-local pack (inside `cairndev`) and its training stack on the engine's
+box: `cairndev[train]` (torch, transformers, peft, datasets; CPU is enough;
+there is no torch wheel for Intel macOS).
+
+```bash
+cairn remote launch hello-cairn/tiny-finetune --environment sandbox --watch
+cairn remote launch hello-cairn/tiny-finetune -i base_model=Qwen/Qwen2.5-0.5B --watch
+```
+
+`base_model` defaults to the stand-in `sshleifer/tiny-gpt2` (seconds); Qwen2.5-0.5B trains
+in minutes. `loss-ok` stops the pipeline when the held-out loss is above `target_loss`;
+`promote` and `review` each wait for a person.
+
+Until the train-local pack was merged (hello-cairn WP3), tiny-finetune was pending in two
+strict xfails and one strict list entry. WP3 removed all three in the change that added the
+pack: `test_tiny_finetune_is_runnable_on_the_public_core`
+(`tests/core/test_example_pipeline_governance.py`) and `test_the_example_pack_validates_clean`
+(`tests/cli/test_validate_example_pack.py`, under `profiles/hello.toml`) are ordinary tests,
+and `tests/core/test_validate_author_gate.py` admits tiny-finetune like every other shipped
+pipeline.
+
+### Triggers
+
+The engine arms every declared trigger when it starts: it installs each discovered pipeline
+into the `default` workspace, and each trigger becomes a row that starts its own pipeline
+(ADR-0131, #2631). A trigger fires only when its declaration says `enabled: true`; to turn one
+on, set that in the pipeline file and restart the engine. Out of the box only nightly-ops' cron
+is on. profile-and-publish's dataset `watch` (`on_change: start`), weekly `schedule` and custom
+`webhook` (`POST /triggers/hello-sample`) are `enabled: false`. Turned on, the watch makes each
+tick check whether `hello-sample` gained a registered version, and starts the pipeline only
+when it did. A version is registered by the `engine-check` leg, which records the checked file's content as a version of `hello-sample` (#2632): a changed sample is a new version, and the same sample adds none. With the watch on, a run that registers a new version is followed by one watch-started run on that same content; moving the registration to the job that lands the data is tracked separately. nightly-ops' `table` watch is declared but not armed: a `table` (or `s3`) watch
+needs cairn-platform's governed import, so core names it unarmed. Every armed row is pinned to
+start a `hello-cairn` pipeline.
+
+### Events
+
+`profile-and-publish`'s `publish` leg declares `emits: dataset.ready`: when it completes,
+the bus carries that topic with the leg's output as the payload. A leg declared
+`trigger: on:dataset.ready` (in any pipeline) waits for it; `trigger:` also takes `manual`
+and `schedule:<cron>` (#2605). On the Postgres bus the event is durable and replayed to a
+leg that starts waiting later; on the in-process bus only a leg already waiting sees it.
+
+A whole pipeline can start on a topic too: `ask-the-docs` declares a `kind: event` trigger on
+`dataset.ready` (`enabled: false`). Turned on, each published `dataset.ready` starts one
+ask-the-docs run (ADR-0131 D4). The listener runs on the engine's leader, so a message
+published while no leader is subscribed starts nothing, on either bus. A pipeline may not
+start on a topic its own legs emit.
+
+### How it runs inside the engine
+
+[docs/golden-paths/hello.md](../../docs/golden-paths/hello.md) traces each pipeline from the
+start door to its legs, names where governance fires, and lists the proof for each feature.
+
+### Seeded demo data
+
+`cairn dev --seed` and `cairn demo` seed three records of profile-and-publish
+(`cairn/core/demo_seed.py`). The seeder takes the steps from the loaded pipeline's plan, so
+each record carries every step in plan order (`redact`, `promote` and `audit` included):
+the published record has all of them done, the blocked one stops at `data-ok`, and the
+waiting one stops at `review` with the later steps pending (#2608).
+
+## Files
+
+```
+pack.toml                         manifest (kind = domain): the docs corpus, the MCP server
+__init__.py                       the one-line shim the entry point targets
+pipelines/*.yaml                  the four pipelines (the runnable surface)
+flows/engine-check.yaml           data flow: one noop stage
+flows/summarise.yaml              data flow: noop + noop.slow
+flows/lora.yaml                   ml flow: train.lora
+flows/assistant.md                agentic template of ask-the-docs
+flows/nightly-job.md              agentic template of nightly-ops (no model)
+rag/docs/*.txt                    the docs corpus
+data/sample.jsonl                 20 invented rows: id, text, label
+data/train.jsonl                  48 invented sentences for the fine-tune
+policies/require-review-on-publish.yaml   a hello-prod storage policy
+profiles/hello.toml               the example's deployment profile
+profiles/hello-infisical.toml     the same, with secrets in Infisical
+hooks.py                          run-hook listener: receipts.jsonl
+tools/calc_server.py              stdio MCP server: add, word_count
+pyproject.toml                    builds the data wheel cairn-pack-hello
+```
+
+Tests: `tests/examples/test_hello_cairn.py`, `tests/core/test_example_pipeline_governance.py`,
+`tests/cli/test_validate_example_pack.py`. The feature proof (ADR-0127 D1) runs all four pipelines
+on real servers in every storage × runtime × bus cell, plus the crash cells: `tests/e2e/hello`,
+driven by `scripts/oss/feature_proof.sh`, which writes `FEATURE_PROOF.md`. Its model is a keyless
+OpenAI-compatible stub, `tests/e2e/model_stub.py`.

cairn_pack_hello-0.2.0/README.md

@@ -0,0 +1,227 @@
+# hello-cairn: the example pack
+
+`hello-cairn` is a domain pack: data plus a little glue, no operators. It runs on the cairn
+engine and its builtin operator packs alone. Its four pipelines each do one thing a new user
+recognises, and together they exercise what the engine adds around a piece of work: gates
+answered by data or by a person, budgets, triggers, an agentic template, an MCP tool,
+retrieval, a run hook, SSH, secrets, and an audit record.
+
+| Pipeline | Kind | What it does |
+|---|---|---|
+| `profile-and-publish` | data | Profile a dataset, stop unless the profile passes, redact the summary, run a flow, stage it, ask a person, tag it, publish it, audit it. |
+| `ask-the-docs` | agentic | Retrieve from the pack's docs, ask a model, measure the answer with a tool on the pack's own MCP server, remember it, check its length, ask a person. |
+| `nightly-ops` | operations | Check a secret, run a report on an SSH box, carry it through a flow, propose the follow-up to a person, audit it. Nightly once enabled; a run hook writes receipts. |
+| `tiny-finetune` | ml | Profile training rows, LoRA fine-tune a small model on CPU, gate on its held-out loss, tag it, ask a person, write its card. |
+
+## Quickstart
+
+Run everything from the repository root: relative paths in the pipelines' defaults resolve
+against the engine's working directory.
+
+### 1. Install, and point the engine at the example
+
+```bash
+uv sync --extra dev --extra hello --extra rag   # add --extra auth if your engine needs it
+export CAIRN_PROFILE=examples/hello-cairn/profiles/hello.toml
+```
+
+`--extra rag` is what lets the engine index the docs corpus at boot (LlamaIndex ingest);
+without it ask-the-docs still runs and retrieves nothing. `auth` is optional: `cairn dev`
+signs you in as dev/dev without it.
+
+`cairndev[hello]` installs this pack as the wheel `cairn-pack-hello` plus what its pipelines
+reach beyond the base install: the sqlite-vec store (retrieval and memory), asyncssh
+(`remote/exec`) and DBOS (`CAIRN_RUNTIME=dbos`). Without installing it,
+`export CAIRN_PACK_PATH=examples/hello-cairn` loads the same directory as a dev pack; a dev
+pack declares no entry points, so the run-hook listener does not fire.
+
+`profiles/hello.toml` is the deployment profile the example runs under. It carries
+`cairn/profiles/local-dev.toml`'s bindings for the builtin operators (memory, storage, rag,
+mcp), but not local-dev's `eval.delta` binding (a platform operator) or its `llm_gateway` and
+`embedder` backend entries: the model and the embedder come from the engine's environment
+(step 3). It adds `secrets.store` → `secrets/env` (nightly-ops' secret check is a capability
+node and compiles only with a binding, which local-dev does not carry) and the `hello-calc`
+MCP server the pack declares. It pins no runtime, so `CAIRN_RUNTIME=dbos` selects DBOS.
+
+### 2. See what will happen before anything runs
+
+```bash
+cairn pipeline explain hello-cairn/profile-and-publish -e sandbox
+cairn validate examples/hello-cairn          # with CAIRN_PROFILE set as in step 1
+```
+
+`cairn validate` needs the example's profile: under local-dev the nightly-job template does
+not compile (no `secrets.store` binding).
+
+`explain` lists every leg with the operator class or flow file it resolves to, the gate that
+answers it, and the budget, series and approvers.
+
+### 3. Start an engine
+
+```bash
+export OPENAI_API_KEY=sk-...                 # ask-the-docs' model call and embeddings
+export RAG_EMBED_PROVIDER=openai             # retrieval and memory embed with OpenAI
+export CAIRN_RAG_AUTOINDEX=1                 # index rag/docs at boot (needs the `rag` extra)
+export CAIRN_MCP_SERVERS='{"hello-calc": {"transport": "stdio", "command": "python",
+  "args": ["examples/hello-cairn/tools/calc_server.py"]}}'
+cairn dev --engine-only --port 8471 &        # sqlite engine, in-process runtime, login dev/dev
+cairn remote login -u dev -p dev -e http://localhost:8471
+```
+
+Any OpenAI-compatible endpoint works in place of a key: `OPENAI_BASE_URL`, or
+`LLM_GATEWAY=proxy` with `LLM_GATEWAY_URL`. The engine has no built-in mock model, and
+`CAIRN_BACKEND=mock` is the telemetry backend, not a model. `profile-and-publish` and
+`nightly-ops` call no model.
+
+### 4. Run each pipeline
+
+**profile-and-publish**
+
+```bash
+cairn remote launch hello-cairn/profile-and-publish --environment sandbox --watch
+cairn remote advance <pipeline_id> review        # the person gate
+cairn remote advance <pipeline_id> promote       # the operator's own gate
+```
+
+The pipeline stops a second time at `promote`: `artifact/promote` declares
+`requires_approval`, and a pipeline can add a gate but never remove one an operator declares.
+`cairn remote advance` approves either kind and records the signed-in user as the approver.
+
+The record ends `done`: `data-ok` has verdict `data`, `review` `approved`, `promote` the
+tag `hello-sample@published` on the flow leg's registered artifact, and `audit` a
+hash-chained row in `CAIRN_AUDIT_LOG` (default `./audit.jsonl`). `storage/put` writes under
+`CAIRN_ARTIFACTS_DIR` (default `~/.cairn/artifacts`). With `-i min_rows=1000` the data gate
+stops the pipeline (`gate_blocked`) before anything is written. Launch with
+`--environment hello-prod` and the pack's policy
+(`policies/require-review-on-publish.yaml`) stops `stage` for an approval before it writes.
+
+**ask-the-docs**
+
+```bash
+cairn remote launch hello-cairn/ask-the-docs --environment sandbox --watch
+cairn remote advance <pipeline_id> review
+cairn remote findings <pipeline_id>              # hits, answer, answer_stats, remembered
+```
+
+The `assistant` leg (`flows/assistant.md`) searches the `docs` corpus (`rag/docs`, declared
+in `pack.toml` as `[requires.rag.docs]`), re-ranks, asks the model, calls `word_count` on
+`tools/calc_server.py` through `mcp/call`, and writes the exchange to the `hello_answers`
+memory store. `length` flags answers longer than `max_words`. An un-indexed corpus returns no
+hits and the model says the docs do not cover the question. Retrieval uses sqlite-vec unless
+`RAG_VECTOR_STORE=pgvector`.
+
+**nightly-ops**
+
+```bash
+export HELLO_REPORT_TOKEN=...                    # the secret the job checks for
+export HELLO_SSH_KEY="$(cat ~/.ssh/id_ed25519)"  # in the ENGINE's environment
+CAIRN_STORAGE=sqlite:///$HOME/.cairn/dev.db \
+cairn connect add ssh --name hello-ssh --set host=<box> --set user=<user> \
+  --set known_hosts=$HOME/.ssh/known_hosts --secret PRIVATE_KEY=HELLO_SSH_KEY
+cairn remote launch hello-cairn/nightly-ops --environment sandbox --watch
+```
+
+The connection goes into the engine's store, hence `CAIRN_STORAGE`; its secret is an env var
+NAME the engine reads. The box needs `sh`, an SFTP subsystem, and `setsid` (Linux) or
+`perl` (macOS): `remote/exec` detaches the job into its own session through whichever is
+present (#2606). `job` (`flows/nightly-job.md`) checks the secret through the profile's
+`secrets.store` binding, then runs `command` on the box and reads back `metrics.json`.
+`propose` waits for a person (`monitor/propose` declares `requires_approval`;
+`cairn remote advance <pipeline_id> propose`). With the wheel installed, every settled leg
+appends a line to `$CAIRN_HOME/hello-cairn/receipts.jsonl` (default `~/.cairn`).
+
+For secrets in Infisical, run the engine with
+`CAIRN_PROFILE=examples/hello-cairn/profiles/hello-infisical.toml`, `uv sync --extra
+infisical`, and `INFISICAL_CLIENT_ID`, `INFISICAL_CLIENT_SECRET`, `INFISICAL_PROJECT_ID`
+(and `INFISICAL_HOST` for a self-hosted server). Nothing in the pipeline changes.
+
+**tiny-finetune**
+
+Needs the builtin train-local pack (inside `cairndev`) and its training stack on the engine's
+box: `cairndev[train]` (torch, transformers, peft, datasets; CPU is enough;
+there is no torch wheel for Intel macOS).
+
+```bash
+cairn remote launch hello-cairn/tiny-finetune --environment sandbox --watch
+cairn remote launch hello-cairn/tiny-finetune -i base_model=Qwen/Qwen2.5-0.5B --watch
+```
+
+`base_model` defaults to the stand-in `sshleifer/tiny-gpt2` (seconds); Qwen2.5-0.5B trains
+in minutes. `loss-ok` stops the pipeline when the held-out loss is above `target_loss`;
+`promote` and `review` each wait for a person.
+
+Until the train-local pack was merged (hello-cairn WP3), tiny-finetune was pending in two
+strict xfails and one strict list entry. WP3 removed all three in the change that added the
+pack: `test_tiny_finetune_is_runnable_on_the_public_core`
+(`tests/core/test_example_pipeline_governance.py`) and `test_the_example_pack_validates_clean`
+(`tests/cli/test_validate_example_pack.py`, under `profiles/hello.toml`) are ordinary tests,
+and `tests/core/test_validate_author_gate.py` admits tiny-finetune like every other shipped
+pipeline.
+
+### Triggers
+
+The engine arms every declared trigger when it starts: it installs each discovered pipeline
+into the `default` workspace, and each trigger becomes a row that starts its own pipeline
+(ADR-0131, #2631). A trigger fires only when its declaration says `enabled: true`; to turn one
+on, set that in the pipeline file and restart the engine. Out of the box only nightly-ops' cron
+is on. profile-and-publish's dataset `watch` (`on_change: start`), weekly `schedule` and custom
+`webhook` (`POST /triggers/hello-sample`) are `enabled: false`. Turned on, the watch makes each
+tick check whether `hello-sample` gained a registered version, and starts the pipeline only
+when it did. A version is registered by the `engine-check` leg, which records the checked file's content as a version of `hello-sample` (#2632): a changed sample is a new version, and the same sample adds none. With the watch on, a run that registers a new version is followed by one watch-started run on that same content; moving the registration to the job that lands the data is tracked separately. nightly-ops' `table` watch is declared but not armed: a `table` (or `s3`) watch
+needs cairn-platform's governed import, so core names it unarmed. Every armed row is pinned to
+start a `hello-cairn` pipeline.
+
+### Events
+
+`profile-and-publish`'s `publish` leg declares `emits: dataset.ready`: when it completes,
+the bus carries that topic with the leg's output as the payload. A leg declared
+`trigger: on:dataset.ready` (in any pipeline) waits for it; `trigger:` also takes `manual`
+and `schedule:<cron>` (#2605). On the Postgres bus the event is durable and replayed to a
+leg that starts waiting later; on the in-process bus only a leg already waiting sees it.
+
+A whole pipeline can start on a topic too: `ask-the-docs` declares a `kind: event` trigger on
+`dataset.ready` (`enabled: false`). Turned on, each published `dataset.ready` starts one
+ask-the-docs run (ADR-0131 D4). The listener runs on the engine's leader, so a message
+published while no leader is subscribed starts nothing, on either bus. A pipeline may not
+start on a topic its own legs emit.
+
+### How it runs inside the engine
+
+[docs/golden-paths/hello.md](../../docs/golden-paths/hello.md) traces each pipeline from the
+start door to its legs, names where governance fires, and lists the proof for each feature.
+
+### Seeded demo data
+
+`cairn dev --seed` and `cairn demo` seed three records of profile-and-publish
+(`cairn/core/demo_seed.py`). The seeder takes the steps from the loaded pipeline's plan, so
+each record carries every step in plan order (`redact`, `promote` and `audit` included):
+the published record has all of them done, the blocked one stops at `data-ok`, and the
+waiting one stops at `review` with the later steps pending (#2608).
+
+## Files
+
+```
+pack.toml                         manifest (kind = domain): the docs corpus, the MCP server
+__init__.py                       the one-line shim the entry point targets
+pipelines/*.yaml                  the four pipelines (the runnable surface)
+flows/engine-check.yaml           data flow: one noop stage
+flows/summarise.yaml              data flow: noop + noop.slow
+flows/lora.yaml                   ml flow: train.lora
+flows/assistant.md                agentic template of ask-the-docs
+flows/nightly-job.md              agentic template of nightly-ops (no model)
+rag/docs/*.txt                    the docs corpus
+data/sample.jsonl                 20 invented rows: id, text, label
+data/train.jsonl                  48 invented sentences for the fine-tune
+policies/require-review-on-publish.yaml   a hello-prod storage policy
+profiles/hello.toml               the example's deployment profile
+profiles/hello-infisical.toml     the same, with secrets in Infisical
+hooks.py                          run-hook listener: receipts.jsonl
+tools/calc_server.py              stdio MCP server: add, word_count
+pyproject.toml                    builds the data wheel cairn-pack-hello
+```
+
+Tests: `tests/examples/test_hello_cairn.py`, `tests/core/test_example_pipeline_governance.py`,
+`tests/cli/test_validate_example_pack.py`. The feature proof (ADR-0127 D1) runs all four pipelines
+on real servers in every storage × runtime × bus cell, plus the crash cells: `tests/e2e/hello`,
+driven by `scripts/oss/feature_proof.sh`, which writes `FEATURE_PROOF.md`. Its model is a keyless
+OpenAI-compatible stub, `tests/e2e/model_stub.py`.

cairn_pack_hello-0.2.0/__init__.py

@@ -0,0 +1,11 @@
+"""hello-cairn — the example domain pack (#2423, ADR-0127 D2). Data plus glue; this
+shim builds the Pack from the ``pack.toml`` beside it. The glue (``hooks.py``,
+``tools/calc_server.py``) is reached through an entry point and a profile, never
+imported here."""
+from __future__ import annotations
+
+from cairn.core.pack import Pack
+
+pack = Pack.from_manifest(__file__)
+
+__all__ = ["pack"]

cairn_pack_hello-0.2.0/data/sample.jsonl

@@ -0,0 +1,20 @@
+{"id": 1, "text": "The soup arrived hot and the bread was fresh.", "label": "positive"}
+{"id": 2, "text": "Delivery took two hours longer than promised.", "label": "negative"}
+{"id": 3, "text": "The packaging was fine, nothing special.", "label": "neutral"}
+{"id": 4, "text": "Best noodles I have had in months.", "label": "positive"}
+{"id": 5, "text": "The order was missing the side salad.", "label": "negative"}
+{"id": 6, "text": "Portion size was about what I expected.", "label": "neutral"}
+{"id": 7, "text": "The courier was polite and quick.", "label": "positive"}
+{"id": 8, "text": "My drink had spilled inside the bag.", "label": "negative"}
+{"id": 9, "text": "I ordered the same dish as last week.", "label": "neutral"}
+{"id": 10, "text": "The dessert was a lovely surprise.", "label": "positive"}
+{"id": 11, "text": "The curry was far too salty to finish.", "label": "negative"}
+{"id": 12, "text": "Paid with the app, it worked as usual.", "label": "neutral"}
+{"id": 13, "text": "Everything was still warm when it came.", "label": "positive"}
+{"id": 14, "text": "The tracking map never updated.", "label": "negative"}
+{"id": 15, "text": "The menu has not changed since spring.", "label": "neutral"}
+{"id": 16, "text": "Great value for a weeknight dinner.", "label": "positive"}
+{"id": 17, "text": "The rice was undercooked again.", "label": "negative"}
+{"id": 18, "text": "Arrived at the time the app estimated.", "label": "neutral"}
+{"id": 19, "text": "The new vegetarian option is excellent.", "label": "positive"}
+{"id": 20, "text": "Support never answered my refund request.", "label": "negative"}

cairn_pack_hello-0.2.0/data/train.jsonl

@@ -0,0 +1,48 @@
+{"text": "The tea works well on cold mornings."}
+{"text": "A paper map needed a second try."}
+{"text": "The bicycle bell fits in a coat pocket."}
+{"text": "This notebook looks better in person."}
+{"text": "The garden hose is lighter than it looks."}
+{"text": "A wool scarf smells faintly of cedar."}
+{"text": "The desk lamp made less noise than expected."}
+{"text": "That umbrella arrived a day early."}
+{"text": "The bread knife lasted the whole season."}
+{"text": "A clay mug was easy to set up."}
+{"text": "The tea works well on cold mornings."}
+{"text": "A paper map needed a second try."}
+{"text": "The bicycle bell fits in a coat pocket."}
+{"text": "This notebook looks better in person."}
+{"text": "The garden hose is lighter than it looks."}
+{"text": "A wool scarf smells faintly of cedar."}
+{"text": "The desk lamp made less noise than expected."}
+{"text": "That umbrella arrived a day early."}
+{"text": "The bread knife lasted the whole season."}
+{"text": "A clay mug was easy to set up."}
+{"text": "The tea works well on cold mornings."}
+{"text": "A paper map needed a second try."}
+{"text": "The bicycle bell fits in a coat pocket."}
+{"text": "This notebook looks better in person."}
+{"text": "The garden hose is lighter than it looks."}
+{"text": "A wool scarf smells faintly of cedar."}
+{"text": "The desk lamp made less noise than expected."}
+{"text": "That umbrella arrived a day early."}
+{"text": "The bread knife lasted the whole season."}
+{"text": "A clay mug was easy to set up."}
+{"text": "The tea works well on cold mornings."}
+{"text": "A paper map needed a second try."}
+{"text": "The bicycle bell fits in a coat pocket."}
+{"text": "This notebook looks better in person."}
+{"text": "The garden hose is lighter than it looks."}
+{"text": "A wool scarf smells faintly of cedar."}
+{"text": "The desk lamp made less noise than expected."}
+{"text": "That umbrella arrived a day early."}
+{"text": "The bread knife lasted the whole season."}
+{"text": "A clay mug was easy to set up."}
+{"text": "The tea works well on cold mornings."}
+{"text": "A paper map needed a second try."}
+{"text": "The bicycle bell fits in a coat pocket."}
+{"text": "This notebook looks better in person."}
+{"text": "The garden hose is lighter than it looks."}
+{"text": "A wool scarf smells faintly of cedar."}
+{"text": "The desk lamp made less noise than expected."}
+{"text": "That umbrella arrived a day early."}

cairn_pack_hello-0.2.0/flows/assistant.md

@@ -0,0 +1,97 @@
+---
+name: assistant
+version: 0.1.0
+module: ask
+tags:
+  - flow:state_machine
+  - domain:example
+description: |
+  Answer a question from the pack's own docs: retrieve from the `docs` corpus,
+  re-rank, ask a model, measure the answer with a tool on the example's MCP server,
+  and remember the exchange. The agentic leg of `ask-the-docs`.
+
+flow:
+  type: state_machine
+  source: behavior_tree
+  root:
+    type: sequence
+    children:
+      # Retrieval: the builtin rag/search over the corpus pack.toml declares as
+      # [requires.rag.docs] (sqlite-vec by default; pgvector when RAG_VECTOR_STORE
+      # says so). Read-only.
+      - type: operation
+        operator: rag/search
+        id: search
+        input:
+          corpus: docs
+          query: $input.question
+          top_k: 5
+        output:
+          hits: $state.findings.hits
+          ok: $state.findings.search_ok
+          error: $state.findings.search_error
+      # Re-rank the hits (identity unless a cross-encoder or Cohere is installed).
+      - type: operation
+        operator: rag/rerank
+        id: rerank
+        input:
+          query: $input.question
+          hits: $default($state.findings.hits, [])
+          top_k: 3
+        output:
+          hits: $state.findings.context
+          reranker_used: $state.findings.reranker
+      # The model call. The compiler builds it through core's build_chat_model, so
+      # the call is redacted (when a redact.text binding is active) and costed.
+      - type: action
+        ref: answer
+      # A tool call on the example's own stdio MCP server (tools/calc_server.py),
+      # through the builtin mcp/call operator: governed and audited like any tool call.
+      - type: operation
+        operator: mcp/call
+        id: measure
+        input:
+          server: hello-calc
+          tool: word_count
+          args:
+            text: $state.findings.answer
+        output:
+          result: $state.findings.answer_stats
+          ok: $state.findings.measure_ok
+          error: $state.findings.measure_error
+      # Remember the exchange in a local memory store (memory/write, sqlite-vec). A
+      # store name is a collection name: letters, digits and underscores only.
+      - type: operation
+        operator: memory/write
+        id: remember
+        input:
+          store: hello_answers
+          record:
+            question: $input.question
+            answer: $state.findings.answer
+          embed_text: $input.question
+        output:
+          ok: $state.findings.remembered
+          id: $state.findings.memory_id
+          error: $state.findings.memory_error
+
+  nodes:
+    answer:
+      type: prompt
+      model: gpt-4o-mini
+      capabilities: []
+      prompt_section: answer
+
+tools:
+  required: []
+---
+
+# Ask the docs
+
+## answer
+
+You answer a question about the hello-cairn example pack. The retrieved passages
+are in `state.findings.context` (each hit's `payload.content` is the text, and
+`payload.source` names the file). Answer in at most three sentences, using only
+what the passages say, and name the file you used. When the passages do not cover
+the question, say that the docs do not cover it. Do not invent features.