[iamgp]

Summary

Bundle 9 — stable machine-facing API. Stacked on feat/lineage-diff (PR #12); do not merge before it.

Shared audit path (CLI ↔ API)

• New phlo_transform_engine::audit module: the promotion-evidence helpers moved verbatim out of the CLI — audited_diff (branch_diff.json preferred, single-model diff.json fallback, both-side staleness, post-diff materialisation, self-comparison rejection, --full requirement), read_environment/read_environment_for/environment_artifact_name/write_environment_artifacts/remove_environment_artifacts, contract_breaking_changes (live desired-vs-recorded contract diff), plus catalog_name and compiled_catalog. The CLI keeps thin delegating wrappers — one evidence path, no drift.

Daemon — read plane (never mutates)

• GET /v1/plan?select=&environment=&force= — plan DTO (needs adapter)
• GET /v1/lineage — full lineage document (lineage --format graph)
• GET /v1/diff/lineage?base=<git-ref> — semantic lineage diff, offline, read-only tree extraction
• GET /v1/diff/branch?from=&to=&full= — branch diff (needs adapter), persists branch_diff.json like the CLI so promote audits it
• GET /v1/state/runs[?environment=], /v1/state/runs/{id|prefix}, /v1/state/models/{id}[?environment=], /v1/state/promotions
• POST /v1/reload — synchronous snapshot recompile

Daemon — operation plane (mutations, long-running)

• POST /v1/operations {kind, idempotency_key?, params?} → handle; kinds run, test, promote, reload
• Lifecycle queued → running → succeeded|failed|cancelled; GET /v1/operations[/{id}] polls status; POST .../{id}/cancel cancels via the engine CancelHandle
• run ops expose live progress read back from the state store (the runner persists per-model transitions up front)
• promote runs the full gated path: ref resolution, run history, audited diff artifact, live contract breaks, provisioning-base target-hash pin, merge check, promotion record + optional cleanup — identical to promote on the CLI
• Idempotency: same idempotency_key (or Idempotency-Key header) replays the existing handle under one lock — no duplicate effects on retry, including across daemon restarts
• Durability: every transition is appended to .phlo/transform/operations.jsonl and folded back at startup; an op in flight at shutdown restores as failed/interrupted rather than silently re-running
• Single mutating-op gate: run/promote serialize (409 API008); test/reload ungated
• Strict param schemas (deny_unknown_fields); ?select= accepts single or repeated keys

Auth — daemon --token <secret> requires Authorization: Bearer on every endpoint except /status; missing/wrong credentials answer 401 API015. No token = unauthenticated loopback mode.

Errors — {"error":{code,message}} with stable codes API001–API015 documented in docs/daemon.md; capability gaps answer 503 API007; op records carry the same codes plus cancelled and interrupted.

Wiring — phlo-transform daemon builds ServiceConfig from the global CLI flags (adapter/state/nessie/environment/catalog/schema/token), degrading to API007 per missing capability; /v1/status reports capabilities.

Results reuse CLI DTOs: run → RunResult (run.json), test → {tests,failed}, promote → gates + PromotionRecord, diffs/state → the exact --json shapes.

Test plan

• cargo fmt --all -- --check
• cargo clippy --workspace --all-targets --all-features -- -D warnings
• cargo test --workspace — all suites green
• run op end-to-end on real DuckDB + sqlite state (succeeded, run persisted, state endpoints serve it, idempotent replay)
• promote end-to-end over HTTP — real DuckDB + sqlite state + recorded provisioning evidence + deep branch-diff artifact + in-memory Nessie: --check gates without merging, real promote merges and persists the promotion record, unaudited candidate fails run gate with ok:false
• test op, GET /v1/plan selector narrowing + API006, lineage document + self-diff, API010 on bogus ref
• Rejection matrix API007/008/009/012/015, conflict gate, cancel, POST /v1/reload
• Journal durability: ops + idempotency survive restart, in-flight restores as interrupted
• Nessie/Trino e2e (Docker, --ignored)