Release v0.3.1

Focus

0.3.1 hardens the public runtime contract shipped in 0.3.0.

This release closes semantic gaps between runtime docs and real execution,
tightens lane/data-plane planning, improves recovery explainability at the CLI,
and adds preservation coverage so these guarantees do not drift silently.

---

Highlights

Runtime planning and delivery semantics are more stable

Agora now keeps source, planner, writer, and sink decisions aligned more
consistently across the public runtime entrypoints and internal lane
orchestration.

Key hardening areas include:

• lane selection and data-plane validation across pipeline.py,
  executor.py, source.py, sink.py, and _plan.py
• buffered and ordered delivery behavior in _buffered.py,
  _delivery.py, and _lanes.py
• startup and shutdown rollback so partially opened sink graphs do not leak
  state when later components fail to open
• checkpoint and source-delivery gating so acknowledgement remains tied to
  successful downstream handling

This release is intentionally about making 0.3.x safer to trust under stress,
not about adding a brand-new execution model.

Public data-plane contract is now easier for plugin authors to follow

Agora now exposes and documents the preferred contract helpers:

• source_data_plane_spec()
• sink_data_plane_spec()
• SourceDataPlaneSpec
• SinkDataPlaneSpec

The legacy capability booleans still work in 0.3.x, but docs now steer
custom source and sink authors toward explicit data-plane specs instead of
guessing from older flags.

Related docs were tightened in:

• docs/source/custom.md
• docs/sink/custom.md
• docs/plugins/contract.md

Recovery UX is more explainable from the CLI

Two recovery-oriented CLI surfaces are now much more actionable:

• agora checkpoint inspect
• agora diagnose

They now expose runtime recovery posture more directly, including details such
as recovery support, resume keys, checkpoint granularity, resume behavior, and
warnings when resuming large file-backed sources may be costly.

This makes it easier to answer practical operator questions like:

• can this pipeline actually resume?
• what unit of progress is persisted?
• what does "resume" mean for this source?
• is recovery likely to be cheap or expensive?

agora doctor is now a stronger preflight tool

agora doctor now goes beyond basic configuration shape checks.

It can validate:

• selected pipeline resolution from config
• import references used by config-backed components
• pipeline buildability before execution
• recovery posture
• DLQ replay support
• required environment variables for the selected pipeline

This helps catch miswired configs earlier, before a real run discovers them the
hard way.

Spawn safety and test isolation are tighter

The CLI path bootstrapping helper now ignores mocked or otherwise non-pathlike
ctx.cwd values when adding project paths to sys.path.

That closes a subtle failure mode where test doubles could pollute process-spawn
state and later break process-batch execution with pickling failures.

---

Tests

Release validation for 0.3.1 includes:

• full package CI from the checked-out source tree
• preservation coverage for runtime guarantees, recovery edge cases, plugin
  contract, and baseline behaviors
• targeted CLI coverage for doctor, checkpoint inspect, and diagnose
• public API coverage for the data-plane helper surface

New or expanded test areas include:

• tests/core/test_doctor_cli.py
• tests/core/test_recovery_cli.py
• tests/core/test_data_plane_public_api.py
• tests/preservation/test_runtime_guarantees.py
• tests/preservation/test_recovery_edge_cases.py