weavegraph 0.7.0

# Migration Guide

This document outlines breaking changes between Weavegraph versions and provides
migration guidance for upgrading your code.

---

## v0.7.0

### Overview

v0.7.0 is a release-preparation cleanup that removes unused public API surface,
adds an ergonomic LLM streaming event builder, and tightens docs/examples around
the `examples` feature flag. Most changes are internal maintenance; the items
below are the user-visible migrations.

### Breaking: `LLMStreamingEvent::new` removed

The eight-argument `LLMStreamingEvent::new(...)` constructor has been removed.
Use the builder when constructing custom events:

```rust
use weavegraph::event_bus::{LLMStreamingEvent, LLMStreamingEventScope};

let event = LLMStreamingEvent::builder(chunk)
    .session_id(session_id)
    .node_id(node_id)
    .stream_id(stream_id)
    .is_final(true)
    .scope(LLMStreamingEventScope::Chunk)
    .metadata(metadata)
    .build();
```

For standard cases, the existing `chunk_event`, `final_event`, and `error_event`
factory methods remain available and are still preferred.

### Breaking: `NodeContext::emit_node()` removed

`NodeContext::emit_node(scope, message)` was a redundant alias for
`NodeContext::emit(scope, message)`.

**Migration**: replace calls directly:

```rust
// Before
ctx.emit_node("progress", "started")?;

// After
ctx.emit("progress", "started")?;
```

### Breaking: smaller public surfaces

The following unused or internal-only public items were removed:

- `PersistenceError::MissingField`
- `SQLiteCheckpointerError`; use `CheckpointerError` directly
- `checkpointer_postgres_helpers` and `checkpointer_sqlite_helpers`
- `IdError`, `ParsedId`, and unused `IdGenerator` helpers
- `id_utils`, `merge_inspector`, `message_id_helpers`, and `type_guards`
- `JsonValueExt::deep_clone()`; use `.clone()` instead

### Breaking: `conditional_edges()` returns a slice

`conditional_edges()` now returns `&[ConditionalEdge]` instead of
`&Vec<ConditionalEdge>`. Most callers need no change. If you explicitly
annotated the returned value as `&Vec<_>`, change the annotation to a slice:

```rust
// Before
let edges: &Vec<ConditionalEdge> = config.conditional_edges();

// After
let edges: &[ConditionalEdge] = config.conditional_edges();
```

### Breaking: Migration SQL checksum mismatch (existing databases)

#### Severity

**Hard failure. The application will not start against an existing database
until the fix is applied.**

`sqlx` stores a SHA-384 checksum of every migration file in the
`_sqlx_migrations` table at the time the migration first runs. On every
subsequent `connect()` call it rechecks the file on disk against the stored
checksum. The `0001_init.sql` files for both SQLite and PostgreSQL were
rederived in 0.7.0 with equivalent schemas but changed file contents. The
checksums no longer match, and `sqlx` responds with a hard error:

```
error: migration 1/migrate `0001_init` was previously applied but has been modified
```

This is raised inside `SQLiteCheckpointer::connect()` /
`PostgresCheckpointer::connect()` before any graph logic runs. The application
will fail to initialize and will not continue.

> **This is not a schema change.** No tables, columns, indexes, or data are
> altered. The database contents are safe. Only the checksum bookkeeping record
> needs updating.

#### Who is affected

| Backend    | Feature flag          | Default? | Affected?                         |
|------------|-----------------------|----------|-----------------------------------|
| SQLite     | `sqlite-migrations`   | **Yes**  | All users unless explicitly opted out |
| PostgreSQL | `postgres-migrations` | No       | Only users who explicitly enabled this feature |

If you use SQLite and did not set `default-features = false` in your
`Cargo.toml` dependency declaration, you are affected.

#### When does it happen

The error fires on the **first `connect()` call after upgrading** to 0.7.0.
If the database file already has data from a previous run, the mismatch is
detected immediately and the call returns an error. There is no grace period
and no warning — it is a hard error.

#### Can the fix be applied while the application is running?

Only partially. If the application is already running and has an open
connection pool, that pool is unaffected until it reconnects. However:

- Any new process that calls `connect()` (e.g. a restarted container, a new
  worker process, or a second instance in a scaled deployment) will fail
  immediately.
- The safest approach is to apply the fix SQL **before** deploying 0.7.0 to
  any environment. The fix is a single-row `UPDATE` with no locking impact on
  application traffic.

#### Fix: SQLite

Connect to the database file with any SQLite client (`sqlite3`, DB Browser for
SQLite, etc.) and run:

```sql
UPDATE _sqlx_migrations
SET checksum = x'3b3263ea3c19ba500ad4f6535b9589ea011a6215a09dc40447e3b4756aebc6bf75b067213afc8692f719706611a8f81b'
WHERE version = 1;
```

Verify the row was updated before proceeding:

```sql
SELECT version, checksum FROM _sqlx_migrations WHERE version = 1;
-- Should return one row; checksum will display as a hex BLOB.
```

#### Fix: PostgreSQL

Connect as a user with `UPDATE` permission on `_sqlx_migrations` and run:

```sql
UPDATE _sqlx_migrations
SET checksum = '\x5db62b4ff42843f429d889f5445a4117b0ff3b4cd185fae1d1b7685a8d3b37cd3d7a8da4265e95c9b0ab5b6efc9ac343'::bytea
WHERE version = 1;
```

Verify:

```sql
SELECT version, encode(checksum, 'hex') AS checksum FROM _sqlx_migrations WHERE version = 1;
```

The `encode(...)` output should be:
```
5db62b4ff42843f429d889f5445a4117b0ff3b4cd185fae1d1b7685a8d3b37cd3d7a8da4265e95c9b0ab5b6efc9ac343
```

#### Example: Docker deployment with automatic image pulls (PostgreSQL)

Many production PostgreSQL deployments use Docker Compose or a container
orchestrator (Kubernetes, Nomad, ECS, etc.) configured to pull and restart the
application container automatically when a new image is published. In this
setup, upgrading to 0.7.0 without patching the checksum first will cause the
application container to crash-loop immediately after starting — before it can
serve any traffic — because `connect()` is called at startup.

**Apply the fix before deploying the new image.** Step-by-step:

1. **Do not pull the new image yet.** Keep the existing 0.6.x container running
   while you patch the database.

2. **Connect to the PostgreSQL container** (adjust the container name, host,
   port, user, and database name to match your deployment):

   ```bash
   docker exec -it <postgres-container-name> \
     psql -U <db-user> -d <db-name>
   ```

   Or, if PostgreSQL is not in Docker but is a managed service (RDS, Cloud
   SQL, etc.), use `psql` from any host that can reach it:

   ```bash
   psql "postgresql://<user>:<password>@<host>:<port>/<db-name>"
   ```

3. **Run the checksum update:**

   ```sql
   UPDATE _sqlx_migrations
   SET checksum = '\x5db62b4ff42843f429d889f5445a4117b0ff3b4cd185fae1d1b7685a8d3b37cd3d7a8da4265e95c9b0ab5b6efc9ac343'::bytea
   WHERE version = 1;
   -- Expected: UPDATE 1
   ```

4. **Verify the update succeeded:**

   ```sql
   SELECT version, encode(checksum, 'hex') AS checksum FROM _sqlx_migrations WHERE version = 1;
   ```

   Confirm the hex value matches exactly:
   ```
   5db62b4ff42843f429d889f5445a4117b0ff3b4cd185fae1d1b7685a8d3b37cd3d7a8da4265e95c9b0ab5b6efc9ac343
   ```

5. **Exit `psql`** (`\q`) and disconnect from the database container.

6. **Now pull and deploy the 0.7.0 image.** Because the checksum record
   already reflects the new file, `connect()` will succeed and the container
   will start normally.

   ```bash
   docker pull <your-registry>/weavegraph:<new-tag>
   docker compose up -d   # or however you restart your stack
   ```

7. **Confirm the container is healthy** before considering the upgrade complete:

   ```bash
   docker ps   # check STATUS column
   docker logs <app-container-name> --tail 50
   ```

If you missed this step and the container is already crash-looping, the
database is unharmed. Apply the `UPDATE` in step 3, then restart the container.

#### Option: regenerate the database (development / test only)

If the database contains only test or ephemeral data, the simplest fix is to
delete the database file (SQLite) or drop and recreate the schema (PostgreSQL)
so that `sqlx` runs the migration fresh against the new file.

**Do not do this with production data.**

---

## v0.6.0

### Overview

v0.6.0 adds two major feature groups (WG-006 and WG-007) with only one breaking change: five
public error enums are now `#[non_exhaustive]`. The new APIs are purely additive and backward-compatible.

### Breaking: `#[non_exhaustive]` error enums

The following enums are now `#[non_exhaustive]` to allow adding new variants in future minor releases without a breaking change:

- `RunnerError`
- `NodeError`
- `CheckpointerError`
- `StateSlotError`
- `ReplayConformanceError`

**Migration**: Any exhaustive `match` on these types will now fail to compile. Add a wildcard arm:

```rust
// Before (0.5.0)
match err {
    RunnerError::SessionNotFound(_) => { /* ... */ }
    RunnerError::StepFailed(_) => { /* ... */ }
    // compiler accepted this as exhaustive
}

// After (0.6.0)
match err {
    RunnerError::SessionNotFound(_) => { /* ... */ }
    RunnerError::StepFailed(_) => { /* ... */ }
    _ => { /* handle any future variants */ }
}
```

### Breaking: `MapMerge` now deletes keys with null values (RFC 7396)

`MapMerge`, the built-in reducer for `VersionedState.extra`, previously wrote `serde_json::Value::Null` verbatim into the state map. It now **removes** the key when the incoming value is `null`, following [JSON Merge Patch](https://www.rfc-editor.org/rfc/rfc7396) semantics.

**Impact**: If your graph stores `serde_json::Value::Null` intentionally as a meaningful value (as opposed to an absence marker), replace it with an explicit sentinel, for example:

```json
{ "absent": true }
```

**Benefit**: `NodePartial::clear_extra_keys` and `clear_typed_extra_key` now fully delete keys — no wrapper reducer or post-processing is required.

### New: Invocation-scoped state slots (WG-006)

Mark a `StateKey<T>` as `InvocationScoped` using the new const builder:

```rust
const SCRATCH: StateKey<ScratchPad> = StateKey::new("wq", "scratch", 1)
    .invocation_scoped();
```

Keys marked `InvocationScoped` compare equal to a `Durable` key with the same `(namespace, name, schema_version)` — lifecycle is intentionally excluded from equality and hashing so that the same slot can be used across invocations without registry conflicts.

To clear invocation-scoped slots at re-entry (e.g. in iterative sessions), call `clear_typed_extra_key` on the outgoing `NodePartial`:

```rust
partial.clear_typed_extra_key(SCRATCH)
```

This **deletes** the key from `VersionedState.extra` — no separate cleanup reducer is needed.
`MapMerge` (the built-in extra reducer) now follows JSON Merge Patch semantics (RFC 7396):
an incoming `null` removes the key rather than storing a null value.

### New: Replay normalization profiles (WG-006)

Use `StateNormalizeProfile` to ignore volatile or invocation-scoped keys during replay comparison:

```rust
let profile = StateNormalizeProfile::new()
    .ignore_key(SCRATCH)         // typed — records lifecycle for conflict detection
    .ignore_extra_keys(["ts"]);  // raw string — no lifecycle

let comparison = compare_final_state_with(&run_a, &run_b, &profile);
assert!(comparison.is_equivalent());
```

### New: Runtime observer (WG-007)

Attach a `RuntimeObserver` to an `AppRunner` for structured hook callbacks at key lifecycle points:

```rust
#[derive(Debug)]
struct MyObserver;

impl RuntimeObserver for MyObserver {
    fn on_invocation_finish(&self, meta: &InvocationFinishMeta<'_>) {
        println!("run {} completed in {}ms", meta.session_id, meta.duration_ms);
    }
}

let runner = AppRunner::builder()
    .app(app)
    .observer(Arc::new(MyObserver))
    .build()
    .await?;
```

When no observer is attached, there is zero overhead — the observer field is `Option<Arc<...>>`.

Observer panics are caught via `catch_unwind` and logged as warnings; a misbehaving observer
cannot crash or abort a workflow invocation.

### New: MetricsObserver (WG-007, `metrics` feature)

Enable the `metrics` feature and attach `MetricsObserver` to export standard Prometheus-compatible metrics via any `metrics`-crate recorder (e.g. `metrics-exporter-prometheus`):

```toml
weavegraph = { version = "0.7", features = ["metrics"] }
metrics-exporter-prometheus = "0.17"
```

```rust
use weavegraph::runtimes::MetricsObserver;

let runner = AppRunner::builder()
    .app(app)
    .observer(Arc::new(MetricsObserver))
    .build()
    .await?;
```

See the `metrics_observer` module docs for the full metric inventory.

---

## v0.5.0

### Overview

v0.5.0 is the recommended target for the WeaveQuant production feedback work. The changes add new public runtime APIs and a public `RunnerError` variant, so they should not ship as a `0.4.1` patch.

### New Runtime APIs

Use `AppRunner::create_iterative_session(...)` and `AppRunner::invoke_next(...)` when one durable session should process many logical inputs:

```rust
runner
    .create_iterative_session(run_id.clone(), initial_state, NodeKind::Start)
    .await?;

runner
    .invoke_next(&run_id, input_patch, NodeKind::Start)
    .await?;
```

`NodeKind::Start` resolves to the graph's normal Start outgoing frontier. A registered custom node can be supplied for narrower re-entry. `NodeKind::End` now returns `RunnerError::InvalidIterativeEntry` when used as an iterative entry.

When an `AppRunner` event stream is subscribed before iterative execution, each `invoke_next(...)` emits `INVOCATION_END_SCOPE` and keeps the stream open for the next logical input. Call `finish_iterative_session(...)` after the final input to emit the normal `STREAM_END_SCOPE` sentinel and close the stream.

### Typed State Slots

Typed state slots are a thin, JSON-compatible layer over `VersionedState.extra`. Define a reusable key in the domain crate, then read and write typed payloads without hand-rolled `serde_json` calls at every node boundary:

```rust
use serde::{Deserialize, Serialize};
use weavegraph::node::NodePartial;
use weavegraph::state::{StateKey, StateSnapshot};

#[derive(Serialize, Deserialize)]
struct PortfolioState {
    cash_cents: i64,
}

const PORTFOLIO: StateKey<PortfolioState> = StateKey::new("wq", "portfolio", 1);

fn read(snapshot: &StateSnapshot) -> Result<Option<PortfolioState>, weavegraph::state::StateSlotError> {
    snapshot.get_typed(PORTFOLIO)
}

fn write(value: PortfolioState) -> Result<NodePartial, weavegraph::state::StateSlotError> {
    NodePartial::new().with_typed_extra(PORTFOLIO, value)
}
```

The storage key is namespaced and versioned as `namespace:name:v{schema_version}`. Untyped `extra` remains available.

### Deterministic Runtime Clock

Use the existing `Clock` abstraction to inject deterministic time into nodes and emitted node-event metadata:

```rust
use std::sync::Arc;
use weavegraph::runtimes::{AppRunner, CheckpointerType};
use weavegraph::utils::clock::MockClock;

let runner = AppRunner::builder()
    .app(app)
    .checkpointer(CheckpointerType::InMemory)
    .clock(Arc::new(MockClock::new(1_700_000_000)))
    .build()
    .await;
```

Inside a node, call `ctx.now_unix_ms()` and `ctx.invocation_id()`. `NodeContext::new(...)` is now the easiest way to construct contexts in tests.

### Metadata Helpers

Compiled graphs and runners expose deterministic metadata helpers for audit labels and replay manifests:

```rust
let graph = app.graph_metadata();
let graph_hash = app.graph_definition_hash();
let run = runner.run_metadata();
```

The graph hash includes node kinds, edges, conditional edge registrations, and reducer definition labels. It does not inspect closure bodies for conditional predicates. Custom reducers can override `Reducer::definition_label(...)` when a durable audit label is preferable to the default Rust type path.

### Replay Conformance Helpers

Replay helpers live under `weavegraph::runtimes::replay` and are re-exported from `weavegraph::runtimes`:

```rust
use weavegraph::runtimes::{ReplayRun, compare_replay_runs};

let expected = ReplayRun::new(expected_state, expected_events);
let actual = ReplayRun::new(actual_state, actual_events);

compare_replay_runs(&expected, &actual).assert_matches()?;
```

`normalize_event(...)` strips runtime timestamps. Use `compare_event_sequences_with(...)` or `compare_replay_runs_with(...)` when domain events need semantic normalization.

### Compatibility Notes

- `App::invoke(...)`, `AppRunner::create_session(...)`, and `AppRunner::run_until_complete(...)` keep their existing behavior.
- `RunnerError` is an exhaustive public enum. Code that matches every variant must handle `InvalidIterativeEntry` after upgrading.
- `GraphMetadata`, `RunMetadata`, `ReplayRun`, `NodeContext`, and `SchedulerRunContext` are `#[non_exhaustive]`; use provided constructors/builders instead of external struct literals.
- `Reducer` gains a default `definition_label(...)` method for graph metadata. Existing reducer implementations do not need to change unless they want a custom stable label.
- `RuntimeConfig` gains a public `clock` field. Code using struct literals should add `clock: None` or switch to `RuntimeConfig::default()` / builder-style methods.
- `NodeContext` gains `clock` and `invocation_id` fields. Tests should prefer `NodeContext::new(...)` over struct literals.
- Direct calls to `Scheduler::superstep(...)` must pass the optional clock and invocation ID arguments.
- Iterative sessions keep step numbers monotonic across invocations and reload checkpoints through the existing checkpointer path.

---

## v0.4.0

### Overview

v0.4.0 is the **API freeze** release. All items deprecated in v0.2.0 and v0.3.0
have been removed. No new public APIs were added. If you are already on v0.3.0
with no deprecation warnings, upgrading requires only the signature change to
`RuntimeConfig::new()`.

### Breaking Changes

#### 1. `Message::new(role: &str, content: &str)` removed

**Removed in:** v0.4.0 (deprecated since v0.3.0)

Use the typed constructors instead:

```rust
// Before
let m = Message::new("user", "hello");

// After — typed Role enum
let m = Message::with_role(Role::User, "hello");

// Or use the convenience constructors
let m = Message::user("hello");
let m = Message::assistant("reply");
let m = Message::system("you are a helpful assistant");
```

---

#### 2. `RuntimeConfig::new()` signature changed

**Removed in:** v0.4.0

The `checkpointer: Option<CheckpointerType>` middle parameter is removed.

```rust
// Before (v0.3.0)
let config = RuntimeConfig::new(
    Some("session-id".into()),
    Some(CheckpointerType::InMemory),
    None,
);

// After (v0.4.0) — two parameters only
let config = RuntimeConfig::new(
    Some("session-id".into()),
    None, // sqlite_db_name
);
```

Set the checkpointer type via `AppRunner::builder()`:

```rust
AppRunner::builder()
    .app_arc(app)
    .checkpointer(CheckpointerType::SQLite)
    .build()
    .await?;
```

---

#### 3. `RuntimeConfig.checkpointer` field, `with_checkpointer()`, and `checkpointer_type()` removed

**Removed in:** v0.4.0

Configure the checkpointer exclusively through `AppRunner::builder()`:

```rust
// Before — field on RuntimeConfig
let config = RuntimeConfig { checkpointer: Some(CheckpointerType::Postgres), ..Default::default() };
// or
let config = RuntimeConfig::default().with_checkpointer(CheckpointerType::Postgres);

// After — builder method on AppRunner
AppRunner::builder()
    .app_arc(app)
    .checkpointer(CheckpointerType::Postgres)
    .build()
    .await?;

// For a fully custom checkpointer — still on RuntimeConfig
let config = RuntimeConfig::new(None, None)
    .checkpointer_custom(Arc::new(my_checkpointer));
```

---

#### 4. Legacy `AppRunner` constructors removed

**Removed in:** v0.4.0 (deprecated since v0.2.0)

All free-standing constructors have been removed. Use `AppRunner::builder()` exclusively:

| Removed | Replacement |
|---------|-------------|
| `AppRunner::new(app)` | `AppRunner::builder().app(app).build().await` |
| `AppRunner::from_arc(app)` | `AppRunner::builder().app_arc(app).build().await` |
| `AppRunner::with_options(app, config)` | `AppRunner::builder().app(app)` + config methods |
| `AppRunner::with_options_arc(app, config)` | `AppRunner::builder().app_arc(app)` + config methods |
| `AppRunner::with_options_and_bus(app, config, bus)` | `AppRunner::builder().app(app).event_bus(bus)` |
| `AppRunner::with_options_arc_and_bus(app, config, bus)` | `AppRunner::builder().app_arc(app).event_bus(bus)` |

```rust
// Before
let runner = AppRunner::with_options_and_bus(app, config, bus).await?;

// After
let runner = AppRunner::builder()
    .app(app)
    .checkpointer(CheckpointerType::InMemory)
    .event_bus(bus)
    .build()
    .await?;
```

---

#### 5. `LadderError` type alias removed

**Removed in:** v0.4.0 (deprecated since v0.3.0)

```rust
// Before
use weavegraph::channels::errors::LadderError;
fn my_fn() -> Result<(), LadderError> { ... }

// After
use weavegraph::channels::errors::WeaveError;
fn my_fn() -> Result<(), WeaveError> { ... }
```

---

#### 6. `llm` feature flag alias removed

**Removed in:** v0.4.0 (deprecated since v0.3.0)

```toml
# Before
weavegraph = { version = "0.3", features = ["llm"] }

# After
weavegraph = { version = "0.4", features = ["rig"] }
```

---

### New in v0.4.0

- `DIAGNOSTIC_SCOPE` constant exported from `weavegraph::event_bus` — use to
  identify internal diagnostic events when filtering the event stream.
- `#![warn(missing_docs)]` is now enforced — all public API items are documented.
- `examples/production_streaming.rs` — golden-path reference for Axum + SSE +
  Postgres checkpointing (use `--features postgres-migrations,examples` for a
  fresh database).

---

## v0.3.0

### Breaking Changes

#### 1. `Message.role` is now `Role` (High Impact)

**What changed:**
`Message.role` changed from `String` to typed [`Role`](weavegraph::message::Role).

Serialization remains wire-compatible: roles still encode as plain JSON strings
(`"user"`, `"assistant"`, etc.) and decode from plain strings.

**Before (v0.2.x):**
```rust
use weavegraph::message::{Message, Role};

if msg.role == "user" {
    // ...
}

let role = msg.role_type();
if msg.is_role(Role::Assistant) {
    // ...
}
```

**After (v0.3.0):**
```rust
use weavegraph::message::{Message, Role};

if msg.role == Role::User {
    // ...
}

let role = msg.role.clone();
let role_str = msg.role.as_str();
```

**Migration steps:**
1. Replace string comparisons like `msg.role == "user"` with `msg.role == Role::User`
2. Replace `msg.is_role(Role::X)` with `msg.role == Role::X`
3. Replace `msg.role_type()` with `msg.role` (or `msg.role.clone()`)
4. For string interop, use `msg.role.as_str()`

#### 2. Role helper removals and deprecations (High Impact)

**Removed in v0.3.0:**
- `Message::role_type()`
- `Message::is_role(...)`
- `Message::has_role(...)`
- `Message::USER`, `Message::ASSISTANT`, `Message::SYSTEM`

**Deprecated in v0.3.0 (removed in v0.4.0):**
- `Message::new(role: &str, content: &str)`

**Replacement guidance:**
- Use `Message::with_role(Role::..., ...)` for typed construction
- Use `Message::user(...)`, `Message::assistant(...)`, `Message::system(...)`, `Message::tool(...)` for common roles
- Use `Message::with_role(Role::Custom("name".into()), ...)` for custom roles

#### 3. Error System Redesign (`0.3.2-alt`) (High Impact)

**What changed:**
- `NodeError` remains a structured public enum (library-friendly and matchable)
- `NodeError::Anyhow(...)` was removed from the public API
- `NodeError::Other(Box<dyn Error + Send + Sync>)` remains the generic fallback
- Rich diagnostics are now optional via `diagnostics` feature
- New ergonomic helper: `NodeResultExt::node_err()` for natural `?` propagation
- **All public error types now follow a uniform architecture** (see below)

This keeps public APIs typed and introspectable while reducing dependency pressure.

**Uniform Error Architecture (0.3.2-alt):**

All public error enums in Weavegraph now follow this pattern for consistency and feature-gating:

```rust
use thiserror::Error;

#[derive(Debug, Error)]
#[cfg_attr(feature = "diagnostics", derive(miette::Diagnostic))]
pub enum MyError {
    #[error("user-facing description")]
    #[cfg_attr(
        feature = "diagnostics",
        diagnostic(
            code(weavegraph::module::variant),
            help("Optional help text for debugging")
        )
    )]
    VariantName(/* fields */),
}
```

This pattern applies to:
- `NodeError` & `NodeContextError` (node execution)
- `RunnerError` & `SchedulerError` (workflow runtime)
- `CheckpointerError` (state persistence)
- `PersistenceError` (serialization/deserialization)
- `GraphCompileError` (graph validation)
- `JsonError` & `CollectionError` (data operations)
- `IdError` (ID generation)
- `EmitterError` (event bus)
- `AppEventStreamError` (event stream lifecycle)
- `ReducerError` (state reduction)

**Before (v0.2.x / early v0.3 drafts):**
```rust
return Err(NodeError::Provider {
    provider: "mcp",
    message: err.to_string(),
});
```

**After (v0.3.0):**
```rust
use weavegraph::node::{NodeError, NodeResultExt};

// Keep Provider for real provider identity.
return Err(NodeError::Provider {
    provider: "mcp",
    message: "upstream rejected request".to_string(),
});

// Generic external errors use Other.
let parsed = std::fs::read_to_string("config.json").node_err()?;
```

**Optional diagnostics metadata:**
```toml
[features]
diagnostics = ["dep:miette"]
```

Enable `diagnostics` when you want `miette::Diagnostic` metadata on error enums.

**Migration steps:**
1. Keep `NodeError::Provider` only for true provider/service errors
2. Replace generic wrapping with `NodeError::other(...)` or `.node_err()?`
3. Remove use of `NodeError::Anyhow` and the `anyhow` crate feature
4. Enable `diagnostics` only where rich terminal diagnostics are desired
5. All error types are now matchable enums — use pattern matching instead of `.downcast_ref()`

#### 4. LLM Abstraction + Rig Feature Rename (`0.3.3` + `0.3.5`) (High Impact)

**What changed:**
- Added framework-agnostic traits under `weavegraph::llm` (`LlmProvider`, `LlmStreamProvider`, `LlmResponse`)
- Added dedicated Rig adapter module under `weavegraph::llm::rig_adapter` (gated by `rig` feature)
- Renamed feature flag from `llm` to `rig`
- Kept `llm` as backward-compatible alias to `rig` for 0.3.x
- Added both conversion impls:
    - `From<weavegraph::message::Message> for rig::completion::message::Message`
    - `From<rig::completion::message::Message> for weavegraph::message::Message`

**Why this matters:**
Weavegraph no longer treats a specific LLM SDK as part of its core API contract.
Consumers can keep using Rig via feature-gated adapters while retaining a stable,
framework-neutral integration surface.

**Feature migration:**
```toml
# Before
weavegraph = { version = "0.2", features = ["llm"] }

# After (preferred)
weavegraph = { version = "0.3", features = ["rig"] }

# 0.3.x compatibility path (still works)
weavegraph = { version = "0.3", features = ["llm"] }
```

**Message conversion migration:**
```rust
use weavegraph::message::Message;

// weavegraph -> rig
let rig_messages: Vec<rig::completion::message::Message> =
        history.clone().into_iter().map(Into::into).collect();

// rig -> weavegraph
let wg_messages: Vec<Message> = rig_messages.into_iter().map(Into::into).collect();
```

**Role-mapping caveats:**
- Rig completion history is user/assistant-oriented.
- `Role::System`, `Role::Tool`, and `Role::Custom(_)` map to Rig user messages.
- Reverse conversion cannot reconstruct original non-native roles from Rig message history.

**Migration steps:**
1. Prefer `features = ["rig"]` in `Cargo.toml`
2. Keep `llm` only as a temporary alias while rolling upgrades
3. Replace bespoke conversion boilerplate with `Into::into` impls
4. If your workflow depends on preserving system/tool/custom roles across Rig round-trips, carry role metadata out-of-band

#### 5. Checkpointer Custom Escape Hatch + Precedence (`0.3.4`) (Medium Impact)

**What changed:**
- Added `AppRunner::builder().checkpointer_custom(Arc<dyn Checkpointer>)`
- Added `RuntimeConfig::checkpointer_custom(Arc<dyn Checkpointer>)`
- Kept enum convenience route (`CheckpointerType`) for in-memory/SQLite/Postgres
- Added deterministic precedence when both are present: custom checkpointer wins
- Marked `RuntimeConfig.checkpointer` field as deprecated for planned removal in `0.4.0`

**Precedence rules:**
1. If a custom checkpointer is set, it is always used
2. Otherwise, enum-based `CheckpointerType` is used
3. If neither is set, runtime falls back to `CheckpointerType::InMemory`

**Before (enum only):**
```rust
let runner = AppRunner::builder()
    .app(app)
    .checkpointer(CheckpointerType::InMemory)
    .build()
    .await;
```

**After (custom override):**
```rust
use std::sync::Arc;
use weavegraph::runtimes::{AppRunner, Checkpointer, CheckpointerType};

let custom: Arc<dyn Checkpointer> = Arc::new(MyCheckpointer::new());

let runner = AppRunner::builder()
    .app(app)
    .checkpointer(CheckpointerType::InMemory) // convenience default
    .checkpointer_custom(custom) // takes precedence
    .build()
    .await;
```

**RuntimeConfig migration:**
```rust
use std::sync::Arc;
use weavegraph::runtimes::{CheckpointerType, RuntimeConfig};

let cfg = RuntimeConfig::new(None, Some(CheckpointerType::InMemory), None)
    .checkpointer_custom(Arc::new(MyCheckpointer::new()));
```

**Migration steps:**
1. Keep enum configuration for standard backends
2. Use `checkpointer_custom(...)` when injecting custom storage backends
3. Treat `RuntimeConfig.checkpointer` field as deprecated and migrate call sites to `RuntimeConfig::with_checkpointer(...)`/`checkpointer_custom(...)`
4. If both are configured, **custom always wins** (add tests for your expected resume behavior)

#### 6. Examples and Guide Renames (`0.3.7`) (Low Impact)

**What changed:**
- `examples/demo1.rs` -> `examples/graph_execution.rs`
- `examples/demo2.rs` -> `examples/scheduler_fanout.rs`
- `examples/STREAMING_QUICKSTART.md` moved to `docs/STREAMING.md`
- `docs/QUICKSTART.md` now replaces the old guide entrypoint
- `examples/README.md` was reduced to a lean runnable index

**Migration steps:**
1. Update local scripts and docs that run `cargo run --example demo1` to `cargo run --example graph_execution`
2. Update local scripts and docs that run `cargo run --example demo2` to `cargo run --example scheduler_fanout`
3. Update links from old streaming/example docs paths to `docs/STREAMING.md`
4. Update guide links to `docs/QUICKSTART.md`

#### 7. `LadderError` renamed to `WeaveError` (`0.3.8`) (Medium Impact)

**What changed:**
- Canonical error type in `channels::errors` is now `WeaveError`
- A 0.3.x compatibility alias remains:
    `#[deprecated] pub type LadderError = WeaveError;`
- Alias removal is planned for `0.4.0`

**Before:**
```rust
use weavegraph::channels::errors::{ErrorEvent, LadderError};

let event = ErrorEvent::app(LadderError::msg("startup failed"));
```

**After (preferred):**
```rust
use weavegraph::channels::errors::{ErrorEvent, WeaveError};

let event = ErrorEvent::app(WeaveError::msg("startup failed"));
```

**Migration steps:**
1. Replace imports of `LadderError` with `WeaveError`
2. Replace explicit type annotations (`LadderError`) with `WeaveError`
3. If you consume JSON schema names directly, update references from `LadderError` to `WeaveError`

---

## v0.2.0

### Breaking Changes

#### 1. Message Role Helpers + `Role` Enum (High Impact)

**What changed:**  
Weavegraph introduced a typed [`Role`](weavegraph::message::Role) enum and helper APIs.

For backward compatibility, `Message.role` remains a `String` (it still serializes cleanly to JSON), but you should treat roles as typed via `Role`, `Message::with_role`, `Message::role_type()`, and `Message::is_role()`.

**Before (v0.1.x):**
```rust
// Old: role was a String
let msg = Message::new("user", "Hello");

// Checking roles
if msg.role == "user" { ... }
```

**After (v0.2.0):**
```rust
use weavegraph::message::{Message, Role};

// New: use Role enum variants
let msg = Message::with_role(Role::User, "Hello");

// Or construct explicitly with a typed Role
let msg = Message::with_role(Role::User, "Hello");

// Checking roles (type-safe)
if msg.is_role(Role::User) {
    // ...
}
```

**Migration steps:**
1. Prefer `Message::with_role(Role::..., ...)` (typed roles)
2. Replace string comparisons like `msg.role == "user"` with `msg.is_role(Role::User)`
3. For custom roles, prefer `Message::with_role(Role::Custom("my_role".into()), ...)`
4. If you must keep string roles (interop), use `msg.role_type()` when branching

**Convenience constructors (recommended):**
```rust
// These create messages with the correct role already set
let user_msg = Message::with_role(Role::User, "User input");
let assistant_msg = Message::with_role(Role::Assistant, "AI response");
let system_msg = Message::with_role(Role::System, "System prompt");
let tool_msg = Message::with_role(Role::Tool, "Tool output");
```

---

#### 2. AppRunner Constructor Consolidation (Medium Impact)

**What changed:**  
Multiple `AppRunner` constructors have been consolidated into a builder pattern.

**Before (v0.1.x):**
```rust
// Various constructors
let runner = AppRunner::new(app, CheckpointerType::InMemory).await;
let runner = AppRunner::with_options(app, checkpointer, event_bus).await;
let runner = AppRunner::with_options_and_bus(app, checkpointer, event_bus).await;
```

**After (v0.2.0):**
```rust
// Use the builder pattern
let runner = AppRunner::builder()
    .app(app)
    .checkpointer(CheckpointerType::InMemory)
    .build()
    .await;

// With event bus
let runner = AppRunner::builder()
    .app(app)
    .checkpointer(CheckpointerType::SQLite)
    .event_bus(bus)
    .autosave(true)
    .build()
    .await;
```

**Migration steps:**
1. Replace `AppRunner::new(app, checkpointer)` with `AppRunner::builder().app(app).checkpointer(checkpointer).build()`
2. Replace `AppRunner::with_options(...)` with the equivalent builder calls
3. The old constructors are deprecated but still available; update at your convenience

---

#### 3. Runner Module Decomposition (Low Impact - Internal)

**What changed:**  
The `runtimes/runner.rs` module was split into focused sub-modules:
- `runtimes/session.rs` - Session lifecycle management
- `runtimes/execution.rs` - Step execution logic
- `runtimes/streaming.rs` - Event stream management
- `runtimes/runner.rs` - Slim coordinator

**Impact:**  
This is primarily an internal refactoring. Public API remains stable. If you were
importing internal types directly from the runner module, update your imports:

```rust
// Before (if using internal imports)
use weavegraph::runtimes::runner::SessionState;

// After
use weavegraph::runtimes::session::SessionState;
```

---

#### 4. Removed `.expect()` Calls (Low Impact)

**What changed:**  
Production code no longer uses `.expect()`. Methods that previously panicked now
return `Result` types.

**Affected methods:**
- `AppRunner` internal checkpoint operations now propagate errors
- Clock timestamp operations use safe fallbacks

**Impact:**  
If you were relying on panics for error handling, you'll need to handle `Result`
types explicitly. This improves reliability in production deployments.

---

### Deprecations

The following items are deprecated and will be removed in v0.3.0:

| Deprecated | Replacement |
|-----------|-------------|
| `Message::USER` constant | `Role::User` + `Message::with_role(...)` |
| `Message::ASSISTANT` constant | `Role::Assistant` + `Message::with_role(...)` |
| `Message::SYSTEM` constant | `Role::System` + `Message::with_role(...)` |
| `AppRunner::new()` | `AppRunner::builder()...build()` |
| `AppRunner::with_options()` | `AppRunner::builder()...build()` |

---

### New Features

#### Type-Safe Message Roles
The new `Role` enum provides compile-time safety for message roles:
```rust
use weavegraph::message::Role;

match msg.role {
    Role::User => handle_user_input(),
    Role::Assistant => handle_ai_response(),
    Role::System => handle_system_prompt(),
    Role::Tool => handle_tool_result(),
    Role::Custom(ref name) => handle_custom(name),
}
```

#### Builder Pattern for AppRunner
More flexible and self-documenting runner construction:
```rust
let runner = AppRunner::builder()
    .app(app)
    .checkpointer(CheckpointerType::SQLite)
    .event_bus(EventBus::with_sinks(vec![Box::new(JsonLinesSink::new(file))]))
    .autosave(true)
    .build()
    .await;
```

#### Graph API Enhancements
New iteration methods inspired by petgraph:
```rust
let builder = GraphBuilder::new()
    .add_node(NodeKind::Custom("A".into()), MyNode)
    .add_node(NodeKind::Custom("B".into()), MyNode)
    .add_edge(NodeKind::Start, NodeKind::Custom("A".into()))
    .add_edge(NodeKind::Custom("A".into()), NodeKind::Custom("B".into()))
    .add_edge(NodeKind::Custom("B".into()), NodeKind::End);

for node_kind in builder.nodes() {
    println!("Node: {node_kind}");
}

for (from, to) in builder.edges() {
    println!("Edge: {from} -> {to}");
}

for node in builder.topological_sort() {
    println!("Topo: {node}");
}
```

---

## v0.1.x Releases

### v0.1.3
- Added `VersionedState::new_with_user_message()` convenience constructor
- Fixed edge case in conditional edge routing with empty predicate results
- Improved event bus backpressure handling
- Added Postgres checkpointing

### v0.1.2
- Initial public release
- Graph-driven workflow execution
- SQLite and in-memory checkpointing
- Event bus with multiple sink types
- Property-based test coverage

---

## Getting Help

If you encounter issues during migration:

1. Check the [examples](examples/) for updated usage patterns
2. Review the [ARCHITECTURE.md](docs/ARCHITECTURE.md) for design context
3. Open an issue on [GitHub](https://github.com/Idleness76/weavegraph/issues)

---

## Version Compatibility Matrix

| Weavegraph | Rust MSRV | rig-core | tokio |
|------------|-----------|----------|-------|
| 0.7.x      | 1.90.0    | 0.30.x   | 1.x   |
| 0.6.x      | 1.90.0    | 0.30.x   | 1.x   |
| 0.5.x      | 1.90.0    | 0.30.x   | 1.x   |
| 0.4.x      | 1.90.0    | 0.30.x   | 1.x   |
| 0.3.x      | 1.90.0    | 0.30.x   | 1.x   |
| 0.2.x      | 1.89.0    | 0.28+    | 1.x   |
| 0.1.x      | 1.89.0    | 0.28+    | 1.x   |