feat(checkpoint): chain-ambiguous category + spec v0.16.0 bump

Spec proposal 0018 (chain-ambiguity category) landed in spec
v0.16.0 between PR-4 push and the spec agent's code review.
This commit adds the new error category and the required
routing swaps; PR-4 stays open as the carrier.

- Submodule pinned to v0.16.0; pyproject + __spec_version__ +
  test_smoke pin assertions follow.
- New canonical error class CheckpointStateMigrationChainAmbiguous
  (and the matching category string) added to checkpoint/errors.py,
  re-exported from openarmature.checkpoint. Non-transient. Carries
  optional from_version / to_version when known (always set for
  the registration-time case; resume-time multi-shortest-path also
  populates).
- MigrationRegistry.register raises
  CheckpointStateMigrationChainAmbiguous directly at registration
  time per spec §10.10 (proposal 0018), so the canonical category
  surfaces at the registration boundary without wrapping. The
  internal BFS keeps raising ValueError for multi-shortest-path
  detection; CompiledGraph._migrate_record's except branch now
  routes that to CheckpointStateMigrationChainAmbiguous at the
  resume boundary.
- Routing precedence on resume per §10.10 (v0.16.0): chain-ambiguous
  → missing → failed → record-invalid. Code-comment in
  _migrate_record documents the ordering so a future reader
  doesn't swap it back.
- Code comments record two design-choice notes the spec agent
  flagged: the load-bearing equal-depth-re-entry behavior in BFS
  cycle protection (tightening to <= breaks multi-shortest-path
  detection), and the registration-order ordering of describe()
  output.
- Conformance harness gains the expected_chain_ambiguity_error
  primitive. Accepts the canonical category at EITHER the case
  top-level (registration-time detection: registration raises,
  resume block unreachable) OR inside resume (load-time detection
  during BFS). Spec §10.12.2's compile-time-SHOULD /
  load-time-acceptable carve-out lands in the driver as a
  single try/except wrap around both phases.
- Fixture 047 (state-migration-chain-ambiguous) covered; all 9
  state-migration fixtures (039-047) pass.
- 3 new unit tests for the new category's class shape +
  attribute carriage; existing duplicate-pair tests updated to
  assert the canonical category instead of ValueError.
- docs/concepts/checkpointing.md updated for the third category +
  the v0.16.0 routing precedence. CHANGELOG entry updated and
  Pinned-version line bumped to 0.10.0 → 0.16.0.

OTel openarmature.checkpoint.migrate span emission deferred to
a follow-on; documented inline in _migrate_record. Spec §6
cross-ref is SHOULD-level, and the emission needs the
_InvocationContext that's currently created AFTER the migration
path runs. The follow-on can either restructure resume to build
the context first or use a side-channel observer dispatch.

Author: chris-colinsky

CHANGELOG.md

@@ -8,7 +8,7 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). The
 
 ### Added
 
-- **State migration for checkpointed graphs (proposal 0014, introduced in spec v0.15.0).** Saved checkpoints whose `schema_version` doesn't match the current state class now route through a registered migration chain instead of failing on resume. Surface: `State.schema_version: ClassVar[str] = ""` (declare a non-empty value to opt in), `GraphBuilder.with_state_migration(from_version, to_version, migrate)` and `with_state_migrations(*migrations)` for registration, `StateMigration` and `MigrationRegistry` types exported from `openarmature.checkpoint`. Chain resolution is BFS over the registered edges; the shortest path wins. Multi-shortest-path ambiguity (e.g., a diamond `v1→v2→v4` + `v1→v3→v4`) surfaces as `CheckpointStateMigrationMissing` per spec §10.12.2's load-time-detection allowance. Two new error categories: `CheckpointStateMigrationMissing` (no chain bridges the versions, or chain ambiguous) and `CheckpointStateMigrationFailed` (a migration function raised). Both non-transient. Post-migration deserialization failures still route to `CheckpointRecordInvalid` per §10.12.4. The same chain applies to each entry in `parent_states` in lockstep with the outer state per §10.12.2.
+- **State migration for checkpointed graphs (proposal 0014, introduced in spec v0.15.0; refined by proposal 0018 in spec v0.16.0).** Saved checkpoints whose `schema_version` doesn't match the current state class now route through a registered migration chain instead of failing on resume. Surface: `State.schema_version: ClassVar[str] = ""` (declare a non-empty value to opt in), `GraphBuilder.with_state_migration(from_version, to_version, migrate)` and `with_state_migrations(*migrations)` for registration, `StateMigration` and `MigrationRegistry` types exported from `openarmature.checkpoint`. Chain resolution is BFS over the registered edges; the shortest path wins. Three new error categories: `CheckpointStateMigrationChainAmbiguous` (proposal 0018: duplicate `(from, to)` pair at registration time, or multiple distinct shortest paths between the saved and current versions at resume time), `CheckpointStateMigrationMissing` (no chain bridges the versions), and `CheckpointStateMigrationFailed` (a migration function raised). All non-transient. Post-migration deserialization failures still route to `CheckpointRecordInvalid` per §10.12.4. The same chain applies to each entry in `parent_states` in lockstep with the outer state per §10.12.2. Routing precedence per §10.10 (v0.16.0): chain-ambiguous → missing → failed → record-invalid.
 - **`Checkpointer.supports_state_migration` Protocol attribute.** Marks whether a backend can expose the structural intermediate form (a plain dict, JSON tree) the migration registry consumes. `SQLiteCheckpointer(serialization="json")` opts in; `SQLiteCheckpointer(serialization="pickle")` and `InMemoryCheckpointer` opt out. On version mismatch against a non-migration-eligible backend the engine raises `CheckpointRecordInvalid` per spec §10.12.1.
 - **Prompt-management capability (proposal 0017, introduced in spec v0.15.0).** New `openarmature.prompts` subpackage. `PromptManager` composes one or more `PromptBackend`s, exposes `fetch` / `render` / `get`, applies the §8 fallback semantics (`prompt_store_unavailable` continues to the next backend; `prompt_not_found` stops the chain), and renders templates with Jinja2's `StrictUndefined` per §7. `Prompt` / `PromptResult` / `PromptGroup` are Pydantic models matching spec §3 / §4 / §9. Three error categories (`PromptNotFound`, `PromptRenderError`, `PromptStoreUnavailable`) with `PROMPT_TRANSIENT_CATEGORIES` exported for retry-middleware classifiers. `FilesystemPromptBackend` is the minimum local-filesystem reference backend (layout: `<root>/<label>/<name>.j2`; `version` derived from the first 16 hex chars of `template_hash`). New runtime dependency: `jinja2>=3.1`.
 - **`openarmature.prompts.context` — observability propagation per spec §11.** `with_active_prompt(result)` and `with_active_prompt_group(group)` context managers + `current_prompt_result()` / `current_prompt_group()` inspectors. When the OTel observer is active and an LLM call fires inside `with_active_prompt`, the `openarmature.llm.complete` span carries the normative `openarmature.prompt.*` attributes (`name`, `version`, `label`, `template_hash`, `rendered_hash`, `group_name`). Nesting is innermost-wins.
@@ -24,7 +24,7 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). The
 
 ### Changed
 
-- **Pinned spec version: 0.10.0 → 0.15.0.** Adopts the skip-ahead governance principle: the submodule jumps across v0.11.0–v0.15.0 (proposals 0009, 0011, 0014, 0015, 0016, 0017) in one bump. Only the surface introduced by proposal 0016 is implemented in this changelog entry; fixtures from 0011 / 0014 / 0015 / 0017 are marked deferred-skip in the conformance suite and unmark as their respective PRs land.
+- **Pinned spec version: 0.10.0 → 0.16.0.** Adopts the skip-ahead governance principle: the submodule jumps across v0.11.0–v0.16.0 (proposals 0009, 0011, 0014, 0015, 0016, 0017, 0018) in one bump. Only the surfaces introduced by proposals 0014–0017 are implemented in the batch's release; fixtures from 0011 are deferred-skip in the conformance suite and unmark with PR-5.
 - **`CheckpointRecord.schema_version` semantic shift (proposal 0014).** Previously a backend-internal record-shape version (`CHECKPOINT_SCHEMA_VERSION = "1"` constant), now the user-facing state-schema version per spec §10.2. The framework reads `type(state).schema_version` at save time. Pre-PR-4 records carrying `"1"` are reinterpreted as user-facing v1 identifiers; users with such records either declare `schema_version="1"` on their state class or discard the pre-PR-4 records. `SQLiteCheckpointer` no longer rejects records with non-default `schema_version` at the backend boundary; version-mismatch routing is now an engine concern at resume time. The `CHECKPOINT_SCHEMA_VERSION` module constant is removed; future record-shape evolution can add backend-private metadata fields if needed.
 
 ### Notes

docs/concepts/checkpointing.md

@@ -203,29 +203,38 @@ migration leading to v2 and another leading to v2-experimental;
 chain resolution picks the path that ends at the current declared
 version.
 
-Two ambiguity cases are configuration errors:
+Two ambiguity cases are configuration errors. Both surface as
+`CheckpointStateMigrationChainAmbiguous`:
 
 - **Duplicate edges.** Registering two migrations with the same
-  `(from_version, to_version)` pair raises `ValueError` at
-  registration. Either delete one or pick distinct version
-  identifiers.
+  `(from_version, to_version)` pair raises at registration time so
+  the configuration error surfaces before any resume attempt.
+  Either delete one or pick distinct version identifiers.
 - **Multiple shortest paths.** A diamond like
   `v1 → v2 → v4` and `v1 → v3 → v4` is ambiguous: both paths have
-  length 2. The engine surfaces this as
-  `CheckpointStateMigrationMissing` on resume so the user can
+  length 2. The engine raises during resume so the user can
   register fewer migrations or pick a single canonical route.
 
-### The two new error categories
+### The three new error categories
 
+- **`CheckpointStateMigrationChainAmbiguous`**: the registered
+  migration graph is ambiguous (duplicate `(from, to)` pair at
+  registration time, OR multiple distinct shortest paths between
+  the saved and current versions at resume time). Surfaces before
+  any migration function runs. Carries `from_version` and
+  `to_version` when known.
 - **`CheckpointStateMigrationMissing`**: the saved version doesn't
-  match the current version, and no chain (or no unambiguous chain)
-  bridges them. Carries `from_version`, `to_version`, a count of
-  registered migrations, and a human-readable `registry_description`
-  so operators see what IS available.
+  match the current version, and no chain bridges them. Carries
+  `from_version`, `to_version`, a count of registered migrations,
+  and a human-readable `registry_description` so operators see what
+  IS available.
 - **`CheckpointStateMigrationFailed`**: a user-supplied migration
   function raised. Subsequent migrations in the chain don't run;
   the resume fails. The migration's exception rides `__cause__`.
 
+Routing precedence on resume: chain-ambiguous → missing → failed →
+record-invalid.
+
 A third category, `CheckpointRecordInvalid`, continues to cover the
 **post**-migration case: a migration ran cleanly but produced
 output that the current state class can't deserialize (missing a

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.15.0"
+spec_version = "0.16.0"
 
 [dependency-groups]
 dev = [

pyproject.toml

@@ -1,4 +1,4 @@
 """OpenArmature — workflow framework for LLM pipelines and tool-calling agents."""
 
 __version__ = "0.5.0"
-__spec_version__ = "0.15.0"
+__spec_version__ = "0.16.0"

src/openarmature/__init__.py

@@ -26,6 +26,7 @@
     CheckpointNotFound,
     CheckpointRecordInvalid,
     CheckpointSaveFailed,
+    CheckpointStateMigrationChainAmbiguous,
     CheckpointStateMigrationFailed,
     CheckpointStateMigrationMissing,
 )
@@ -45,6 +46,7 @@
     "CheckpointRecord",
     "CheckpointRecordInvalid",
     "CheckpointSaveFailed",
+    "CheckpointStateMigrationChainAmbiguous",
     "CheckpointStateMigrationFailed",
     "CheckpointStateMigrationMissing",
     "CheckpointSummary",

src/openarmature/checkpoint/__init__.py

@@ -111,6 +111,42 @@ def __init__(
         self.registry_description = registry_description
 
 
+class CheckpointStateMigrationChainAmbiguous(CheckpointError):
+    """Raised when the registered migration graph is ambiguous per
+    spec §10.10 / §10.12 (proposal 0018, spec v0.16.0):
+
+    - Duplicate-pair case (§10.12.1): two migrations register with the
+      same ``(from_version, to_version)`` pair. Raised at registration
+      time so the user sees the ambiguity before any resume attempt.
+    - Multi-shortest-path case (§10.12.2): the registered migration
+      graph has multiple distinct shortest paths between the saved
+      and current versions (e.g., a diamond ``v1→v2→v4`` + ``v1→v3→v4``).
+      Spec accepts either compile-time detection (recommended) or
+      load-time detection (this impl runs the check inside BFS at
+      resume time).
+
+    Non-transient: retrying without changing the migration graph
+    will not succeed. Carries ``from_version`` / ``to_version`` when
+    known (always set for the duplicate-pair case, set on the resume
+    side too for multi-shortest-path detection).
+    """
+
+    category = "checkpoint_state_migration_chain_ambiguous"
+
+    from_version: str | None
+    to_version: str | None
+
+    def __init__(
+        self,
+        *args: Any,
+        from_version: str | None = None,
+        to_version: str | None = None,
+    ) -> None:
+        super().__init__(*args)
+        self.from_version = from_version
+        self.to_version = to_version
+
+
 class CheckpointStateMigrationFailed(CheckpointError):
     """Raised on resume when a registered migration function raises
     during chain application (per spec §10.12.2). The migration's
@@ -140,6 +176,7 @@ def __init__(
     "CheckpointNotFound",
     "CheckpointRecordInvalid",
     "CheckpointSaveFailed",
+    "CheckpointStateMigrationChainAmbiguous",
     "CheckpointStateMigrationFailed",
     "CheckpointStateMigrationMissing",
 ]

src/openarmature/checkpoint/errors.py

@@ -15,6 +15,8 @@
 from dataclasses import dataclass
 from typing import Any
 
+from .errors import CheckpointStateMigrationChainAmbiguous
+
 
 @dataclass(frozen=True)
 class StateMigration:
@@ -43,11 +45,14 @@ class MigrationRegistry:
     Registration-time invariants:
 
     - Two migrations with the same ``from_version`` AND
-      ``to_version`` raise ``ValueError`` (chain ambiguity per
-      §10.12.1).
+      ``to_version`` raise ``CheckpointStateMigrationChainAmbiguous``
+      directly per spec §10.10 (proposal 0018) so the canonical
+      category surfaces at the registration boundary without any
+      wrapping by the builder.
     - Two migrations with the same ``from_version`` and different
       ``to_version`` are permitted (branched migration graph;
-      chain resolution picks a path).
+      chain resolution picks a path or raises ambiguity if multiple
+      shortest paths exist).
 
     Resolution-time semantics (per §10.12.2):
 
@@ -59,9 +64,11 @@ class MigrationRegistry:
     - Non-empty registry with no connecting path → same.
     - Found a unique shortest path → return ordered list.
     - Found multiple distinct shortest paths (same edge count,
-      different edge sequences) → raise ``ValueError`` per
-      §10.12.2's ambiguous-chain rule. Spec accepts load-time
-      detection.
+      different edge sequences) → raise ``ValueError`` internally;
+      ``CompiledGraph._migrate_record`` wraps the ``ValueError`` as
+      ``CheckpointStateMigrationChainAmbiguous`` at the resume
+      boundary. The internal ``ValueError`` keeps the registry
+      module dependency-light (no canonical-error import cycle).
     """
 
     def __init__(self) -> None:
@@ -71,9 +78,16 @@ def __init__(self) -> None:
     def register(self, migration: StateMigration) -> None:
         key = (migration.from_version, migration.to_version)
         if key in self._migrations:
-            raise ValueError(
+            # Per spec §10.10 / §10.12.1 (proposal 0018, spec v0.16.0):
+            # duplicate-pair detection raises the canonical category
+            # directly at registration time. The category surfaces
+            # before any resume attempt — neither the builder nor the
+            # caller needs to wrap.
+            raise CheckpointStateMigrationChainAmbiguous(
                 f"duplicate state migration {migration.from_version!r}→"
-                f"{migration.to_version!r} registered; chain would be ambiguous"
+                f"{migration.to_version!r} registered; chain would be ambiguous",
+                from_version=migration.from_version,
+                to_version=migration.to_version,
             )
         self._migrations[key] = migration
         self._edges.setdefault(migration.from_version, []).append(migration)
@@ -132,6 +146,12 @@ def resolve_chain(
                 # shortest path. Allow re-entry only when the new
                 # arrival is at the same layer as the first arrival
                 # (distinct shortest paths through the same node).
+                # NOTE: the strict-less-than comparison is load-
+                # bearing for multi-shortest-path detection — a
+                # diamond v1→v2→v4 + v1→v3→v4 lets BFS reach v4 via
+                # both v2 and v3 at layer 2, and both paths land in
+                # ``shortest_paths``. Tightening this to ``<=`` would
+                # break the ambiguity check.
                 prior_depth = distances.get(next_version)
                 if prior_depth is not None and prior_depth < depth + 1:
                     continue
@@ -154,6 +174,13 @@ def describe(self) -> str:
         """Human-readable description of the registered set, used
         in the ``CheckpointStateMigrationMissing`` error payload.
         Empty registry returns ``"<no migrations registered>"``.
+
+        Output is registration-order (Python's dict preserves
+        insertion order). Diff-friendly test assertions should
+        not depend on the order across distinct registration
+        sequences; if cross-language conformance ever needs a
+        canonical order, a future change can sort by
+        ``(from_version, to_version)``.
         """
         if not self._migrations:
             return "<no migrations registered>"

src/openarmature/checkpoint/migration.py

@@ -49,6 +49,7 @@
     CheckpointNotFound,
     CheckpointRecordInvalid,
     CheckpointSaveFailed,
+    CheckpointStateMigrationChainAmbiguous,
     CheckpointStateMigrationFailed,
     CheckpointStateMigrationMissing,
 )
@@ -403,16 +404,17 @@ async def _migrate_record(
                 current_schema_version,
             )
         except ValueError as exc:
-            # MigrationRegistry signals ambiguous chains (multiple
-            # distinct shortest paths) via ValueError. Spec §10.12.2
-            # treats this as a configuration error — surface it
-            # promptly during the resume attempt.
-            raise CheckpointStateMigrationMissing(
+            # MigrationRegistry signals multi-shortest-path ambiguity
+            # via ValueError. Per spec §10.10 / §10.12.2 (proposal 0018,
+            # spec v0.16.0), this routes to the canonical
+            # CheckpointStateMigrationChainAmbiguous category. Spec
+            # accepts load-time detection (this is the resume-side
+            # path); the duplicate-pair case raises the same category
+            # directly from MigrationRegistry.register at build time.
+            raise CheckpointStateMigrationChainAmbiguous(
                 str(exc),
                 from_version=record.schema_version,
                 to_version=current_schema_version,
-                registered_migrations_count=len(self.migration_registry),
-                registry_description=self.migration_registry.describe(),
             ) from exc
 
         if chain is None:
@@ -431,6 +433,17 @@ async def _migrate_record(
             for i, parent in enumerate(migrated_parents):
                 migrated_parents[i] = _apply_migration_step(migration, parent, f"parent_states[{i}]")
 
+        # TODO(observability): emit an ``openarmature.checkpoint.migrate``
+        # span per spec §6 cross-ref. Deferred to a follow-on because
+        # ``_migrate_record`` runs before the invocation's
+        # ``_InvocationContext`` is created (the engine needs the
+        # migrated state shape to build the context), so the existing
+        # ``_dispatch``-based observer pathway is not yet available
+        # here. A natural fix is to dispatch a synthetic
+        # ``checkpoint_migrated`` event as the first event of the
+        # invocation after context creation. The chain metadata
+        # captured for that event: ``from_version``, ``to_version``
+        # (final target), ``chain_length = len(chain)``.
         return dataclass_replace(
             record,
             state=migrated_state,