Bump spec to v0.22.1; refresh docs and CHANGELOG

Submodule pin advances from v0.20.1 to v0.22.1, absorbing proposals
0027 (result_is_error, v0.21.0), 0028 (schema_version canonical,
v0.21.1), 0029 (count drift strict, v0.22.0), and 0030 (drain
snapshot + timeout-input validation, v0.22.1 — purely textual; the
python engine already implements both behaviors per the 0010 PR's
review-round fix).

CHANGELOG Unreleased section gains result_is_error and count-drift
entries under Added; schema_version sourcing change noted under
Changed; cumulative pin-bump summary updated to v0.17.0 -> v0.22.1
across ten spec versions absorbed this cycle.

docs/concepts/checkpointing.md fan_out_progress framing updated
with the explicit result_is_error discriminator and the count-drift
strict-raise behavior; new "Canonical source for schema_version"
subsection documents the declared-class rule.

Author: chris-colinsky

CHANGELOG.md

@@ -8,6 +8,8 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). The
 
 ### Added
 
+- **`FanOutInstanceProgress.result_is_error` field** (proposal 0027, accepted in spec v0.21.0). Explicit boolean discriminator on each per-instance entry in `CheckpointRecord.fan_out_progress` — `True` for `collect`-mode error contributions (roll forward into `errors_field`), `False` for success contributions (roll forward into `target_field`). The engine reads the explicit field on resume rather than inferring routing from `result`'s shape; the previous structural heuristic (`_looks_like_error_record`) is removed. Backward-compat path on load: pre-0027 records that omit the key default to `False`.
+- **Strict `CheckpointRecordInvalid` on fan-out count drift** (proposal 0029, accepted in spec v0.22.0). When the resumed run's resolved instance count differs from the saved `fan_out_progress` entry's `instance_count`, the engine raises `CheckpointRecordInvalid` before any fan-out instance work runs on the resumed path. Replaces the pre-0029 pad/truncate behavior which silently dropped `completed` contributions on shrink (breaking §10.11.1's exactly-once guarantee) and dispatched unsaved work on grow.
 - **`tool_choice` parameter on `Provider.complete()`** (proposal 0025, accepted in spec v0.20.0). Optional discriminated-union value constraining the model's tool-calling behavior — one of `"auto"`, `"required"`, `"none"`, or a `ForceTool(name=...)` record. Validation runs pre-send: `"required"` and `ForceTool` both demand non-empty `tools`, and `ForceTool.name` must appear in the supplied list; violations raise `ProviderInvalidRequest` (§7's existing category — no new error category). When `tool_choice` is `None` (the default) the wire field is omitted and the provider's own default applies, preserving pre-0025 behavior exactly. The `OpenAIProvider` maps the spec shape onto OpenAI's wire shape per §8.1.1 (the `ForceTool.type="tool"` renames to wire `type="function"`).
 - **`ForceTool` and `ToolChoice` public types** at `openarmature.llm.ForceTool` / `openarmature.llm.ToolChoice`. `ForceTool` is a frozen Pydantic model with `type: Literal["tool"] = "tool"` and `name: str`; `ToolChoice = Literal["auto", "required", "none"] | ForceTool` is the type alias used in `Provider.complete()`'s signature.
 - **`validate_tool_choice` public validator** at `openarmature.llm.validate_tool_choice`. Standalone validator covering the three §5 pre-send rules; useful for third-party `Provider` implementations that want to reuse the canonical validation logic.
@@ -20,14 +22,15 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). The
 
 ### Changed
 
+- **`CheckpointRecord.schema_version` sourcing** clarified per proposal 0028 (spec v0.21.1). Every save site within an invocation now reads `schema_version` from the declared graph state class — the class passed to `GraphBuilder(...)` — threaded as `context.state_cls`. Previously the outer dispatch save read from the declared class while fan-out instance internal saves read from `type(state)` at save time; the inconsistency only surfaced when a user passed a State subclass that shadowed `schema_version`, but the divergence made `§10.12` migration lookups unreliable across save sites. Now uniform across outer / subgraph-internal / fan-out instance internal saves.
 - **`Provider.complete()` signature** extended with an optional `tool_choice: ToolChoice | None = None` parameter (per proposal 0025 v0.20.0). Backward-compatible: callers that omit the new argument see no wire-shape change. Third-party `Provider` implementations MUST add the parameter to remain Protocol-conformant under strict type checking (and to accept calls that pass `tool_choice` without raising `TypeError`); they MAY ignore it in their wire-body emission, which is how "provider doesn't honor tool_choice" looks at the impl level. The `OpenAIProvider` wire mapping is implemented per §8.1.1.
 - **`CompiledGraph.drain()` return type** changed from `None` to `DrainSummary` (pre-1.0; per proposal 0010 v0.19.0 contract). Callers that ignored the return are unaffected — `await graph.drain()` discards the returned dataclass exactly as before. Callers that explicitly typed the return as `None` will need to update their annotation.
 - **Fan-out resume behavior** flipped from atomic restart (0008's v1 contract) to per-instance resume. A crash mid-fan-out used to re-run the entire fan-out on resume; now only the instances that did not complete-and-record their contribution re-run. The economics matter for large fan-outs of expensive work (LLM calls, long extractions): an 80% complete fan-out crash now restores 80% of its results rather than discarding them.
 - **`SQLiteCheckpointer` schema** picks up a new `fan_out_progress_blob` column (added via `ALTER TABLE` for backward compatibility with pre-0009 databases). Pre-0009 rows back-fill as NULL on load and round-trip as the empty-tuple default. Both `pickle` and `json` serialization modes round-trip the new field.
 
 ### Notes
 
-- **Pinned spec version bumped from v0.17.0 to v0.20.1 over this Unreleased cycle.** Six spec versions absorbed: v0.17.1 (proposal 0019, multi-provider wire-format extension — purely textual reframe of llm-provider §8 as a catalog of wire-format mappings; OpenAI-compatible body nested under §8.1), v0.18.0 (proposal 0009, per-instance fan-out resume — pipeline-utilities §10.3 / §10.7 revised, §10.11 added; the `append` reducer no-double-merge invariant is the load-bearing correctness story), v0.18.1 (fixture-only patch correcting an off-by-one literal in fixture 052's expected `results`), v0.19.0 (proposal 0010, bounded drain timeout — graph-engine §6 amended with the `timeout` parameter and `DrainSummary` return contract), v0.20.0 (proposal 0025, llm-provider `tool_choice` — §5 / §7 / §8.1.1 amended; see Added / Changed above), and v0.20.1 (proposal 0026, llm-provider §8.X wire-format mapping subsection template — purely textual §8 framing paragraph; the existing OpenAI §8.1 mapping is the template's reference shape so no python module-level work was needed). All existing conformance fixtures continue to pass.
+- **Pinned spec version bumped from v0.17.0 to v0.22.1 over this Unreleased cycle.** Ten spec versions absorbed: v0.17.1 (proposal 0019, multi-provider wire-format extension — purely textual reframe of llm-provider §8 as a catalog of wire-format mappings; OpenAI-compatible body nested under §8.1), v0.18.0 (proposal 0009, per-instance fan-out resume — pipeline-utilities §10.3 / §10.7 revised, §10.11 added; the `append` reducer no-double-merge invariant is the load-bearing correctness story), v0.18.1 (fixture-only patch correcting an off-by-one literal in fixture 052's expected `results`), v0.19.0 (proposal 0010, bounded drain timeout — graph-engine §6 amended with the `timeout` parameter and `DrainSummary` return contract), v0.20.0 (proposal 0025, llm-provider `tool_choice` — §5 / §7 / §8.1.1 amended), v0.20.1 (proposal 0026, llm-provider §8.X wire-format mapping subsection template — purely textual §8 framing paragraph; the existing OpenAI §8.1 mapping is the template's reference shape so no python module-level work was needed), v0.21.0 (proposal 0027, explicit `result_is_error` discriminator on `fan_out_progress` per-instance entries — see Added above), v0.21.1 (proposal 0028, canonical source for `schema_version` — declared graph state class wins over runtime subclass shadowing; see Changed above), v0.22.0 (proposal 0029, strict `CheckpointRecordInvalid` on fan-out count drift — see Added above), and v0.22.1 (proposal 0030, drain snapshot semantic + timeout-input validation — purely textual; python already implemented both behaviors per the 0010 impl PR, so no module-level work needed). All existing conformance fixtures continue to pass.
 
 ## [0.8.0] — 2026-05-23
 

docs/concepts/checkpointing.md

@@ -113,13 +113,27 @@ Field framing worth getting right:
   `completed`) plus the recorded contribution for finalized
   instances. On resume the engine consults this field to decide
   which instances skip (their contributions roll forward) vs re-run
-  (re-execute from the inner subgraph's declared entry node). Empty
-  tuple when no fan-outs are in flight. See
+  (re-execute from the inner subgraph's declared entry node). Each
+  per-instance entry carries an explicit `result_is_error` boolean
+  that discriminates success contributions (roll forward into
+  `target_field`) from `collect`-mode error contributions (roll
+  forward into `errors_field`) — the engine reads the explicit field
+  on resume rather than inferring routing from the shape of `result`.
+  Empty tuple when no fan-outs are in flight. See
   [Resume semantics](fan-out.md#resume-semantics) on the fan-out
   page for the full per-instance contract including reducer
   composition, error_policy semantics, and the optional
   fan-out-internal save batching.
 
+  **Count drift between runs raises.** If the resumed run's resolved
+  instance count differs from the saved entry's `instance_count`
+  (e.g., the user shrunk or grew the `items_field` list between
+  crash and resume), the engine raises `CheckpointRecordInvalid`
+  before any fan-out instance work runs. The strict raise prevents
+  silent contribution loss (under shrink) or dispatching unsaved
+  work (under grow); the user either coheres the inputs or restarts
+  cleanly.
+
 ## The Checkpointer Protocol
 
 Four methods:
@@ -206,6 +220,16 @@ resolves a chain through the registry (BFS for the shortest path),
 applies each migration in order to the record's state, then
 deserializes the result into your current state class.
 
+**Canonical source for `schema_version`.** The framework reads
+`schema_version` from the state class declared at graph construction
+time — the class passed to `GraphBuilder(...)`. If you pass a State
+subclass instance at runtime whose `schema_version` shadows the
+declared class's value, the saved record still carries the declared
+class's value. This rule keeps every save site within an invocation
+consistent (outer dispatch saves, subgraph-internal saves, fan-out
+instance internal saves all report the same version) and aligns
+with how the migration registry is keyed.
+
 ### Chain resolution
 
 Registered migrations form a directed graph. Each

openarmature-spec

@@ -48,7 +48,7 @@ Repository = "https://github.com/LunarCommand/openarmature-python"
 Specification = "https://github.com/LunarCommand/openarmature-spec"
 
 [tool.openarmature]
-spec_version = "0.20.1"
+spec_version = "0.22.1"
 
 [dependency-groups]
 dev = [

pyproject.toml

@@ -1,4 +1,4 @@
 """OpenArmature: workflow framework for LLM pipelines and tool-calling agents."""
 
 __version__ = "0.8.0"
-__spec_version__ = "0.20.1"
+__spec_version__ = "0.22.1"

src/openarmature/__init__.py

@@ -9,7 +9,7 @@
 
 def test_package_versions() -> None:
     assert openarmature.__version__ == "0.8.0"
-    assert openarmature.__spec_version__ == "0.20.1"
+    assert openarmature.__spec_version__ == "0.22.1"
 
 
 def test_spec_version_matches_pyproject() -> None: