feat: Slice 1 — Python client library (define + run pipelines in code, over gRPC)

[devarismeroxa]

First slice of the Conduit Python client library — the gRPC embed direction (ADR: embed bindings via gRPC, not a C-ABI). Define a pipeline in code, run it, control its lifecycle — all over Conduit's existing control-plane gRPC API. No core-engine changes.

What's here (Slice 1 / Case A)

• Pipeline builder: conduit.Pipeline(id).source(plugin, **cfg).destination(plugin, **cfg).process(plugin, **cfg).dlq(...) → a pure BuildPlan.
• conduit.local(...): spawns + supervises a conduit subprocess (download-on-first-use from GitHub Releases, GoReleaser naming, SHA-256 verified against checksums.txt, cached per-version via platformdirs, never touches PATH), stable state-dir default (./.conduit/state, warns, never ephemeral — at-least-once safety), graceful teardown on exit.
• conduit.connect(addr): bind to an already-running Conduit (local subprocess or remote/service).
• run = client.run(pipeline) → wait_running() / status() / stop().
• All gRPC failures wrap into conduit.ConduitError (decodes Conduit's real google.rpc.ErrorInfo — code + message, not raw stack traces).
• RPCs driven: CreatePipeline/GetPipeline/StartPipeline/StopPipeline/UpdateDLQ, CreateConnector, CreateProcessor, GetInfo.

Verification

• 45 unit tests (builder→payload mapping, error decoding against a real in-process gRPC server, run() sequencing, provisioning with mocked download).
• 1 integration test that actually ran (sandbox had network): downloaded Conduit v0.18.0, ran generator→log end-to-end through the client, stopped gracefully.
• ruff + mypy --strict clean; buf-generated stubs committed + reproducible.

Scope

Slice 1 = Case A (define + run). Out (later slices): the external-connector/inline_source host-as-source (Slice 2, needs the engine-side dial feature), Node (Slice 3), typed connector-config codegen (fast-follow — connector settings are **kwargs dicts for now).

Settled (were flagged open)

• Distribution name: conduit-client (PyPI-available, confirmed).
• Release target: v0.20 (pairs with the Python connector SDK GA).

Risk tier

Tier 1 — frozen public API surface (import path + New/Pipeline/local/connect/run shapes). Needs maintainer (DeVaris) sign-off; a fresh-context DX/correctness review runs before merge.

🤖 Generated with Claude Code
https://claude.ai/code/session_015GQFzakPShAYj8CcwajYDD

[devarismeroxa]

Pushed review fixes (5e02df3), not merged — Tier 1, needs DeVaris sign-off.

MUST-FIX — DLQ nack-window (data-integrity). Pipeline.dlq() only put window_size/window_nack_threshold on the wire when the caller passed them explicitly; otherwise UpdateDLQ received the protobuf zero. The engine's UpdateDLQ takes window_size at face value with no defaulting — window_size=0 disables the nack-window stop-safety, and DefaultDLQ (window_size=1) only applies at pipeline creation, never on update. So .dlq("builtin:log") was silently worse than never calling .dlq(). Fixed: .dlq() now defaults window_size=1/window_nack_threshold=0 (mirroring the engine's own DefaultDLQ) unless the caller passes explicit values — including an explicit 0, which is respected as a deliberate opt-out. Added test_dlq_defaults_window_size_to_one_when_not_given and test_dlq_explicit_window_size_zero_is_respected in tests/unit/test_pipeline_builder.py (this bug shipped invisibly — no prior test asserted on the DLQ payload's window fields).

SHOULD-FIX — partial-creation cleanup. Client.run()'s no-rollback design is intentional (documented), but a mid-sequence failure gave the caller no way to find the already-created pipeline. Added ConduitError.pipeline_id, set by run() whenever CreatePipeline already succeeded before the failing step. Regression test: test_run_mid_sequence_failure_carries_pipeline_id (tests/unit/test_client_run.py), plus a unit test on ConduitError.__str__/default in tests/unit/test_errors.py.

TRACK — check_version naming. Left the behavior (reachability-only) unchanged; added a TODO at the connect() call site and tightened the docstring so the flag doesn't overpromise version-checking that isn't implemented.

Gates: ruff format --check + ruff check clean, mypy (strict, packages=["conduit"], matching CI's uv run mypy) clean, full pytest green (50 tests), generated _grpc untouched.