Add failure-isolation catch gate and cause-chain classification primitive (0074)

[chris-colinsky]

Summary

Implements proposal 0074 (spec v0.65.0): the failure-isolation catch cause-chain category gate (§6.3) and the public cause-chain classification primitive (§6.4), plus the §6.1 retry-classifier-depth documentation. Pins the spec submodule v0.64.0 -> v0.65.0.

What changed

• catch gate (§6.3). FailureIsolationMiddleware gains an optional catch: a set of error categories. An exception is caught only if the derived category of its cause chain (the outermost non-carrier link's category, resolved through the engine's node_exception carriers, the same value reported as caught_exception.category) is in the set. This closes a degrade-into-crash footgun: at a wrapping placement (subgraph, fan-out instance, branch) the engine wraps the originating failure in a carrier, so a predicate inspecting the surface exception sees only the carrier and misses it, whereas catch classifies through it. catch composes with predicate as a conjunction (catch checked first, short-circuiting); both default permissive, so the both-unset default stays catch-all, and a null derived category never matches a non-empty set.
• §6.4 classification primitive. The carrier-skipping walk behind catch and caught_exception is promoted to a public classify_cause_chain(exc) -> CaughtException. The cause-chain types (CauseLink, CaughtException) move into a new graph/cause_chain.py alongside the primitive, so the concept has one cohesive home and events consumes it; the public openarmature.graph.* import paths are unchanged via the re-export.
• §6.1 (docs only). The default retry classifier's single-level depth is documented as deliberate (it classifies at re-attempt granularity, distinct from §6.3's full-chain degrade); no behavior change.
• Not shipped: the optional native-exception-type catch form (spec MAY); the normative contract is the category set.

Testing

• Conformance fixture 072 (two cases: catch matches through an instance-placement carrier and degrades; a non-matching catch propagates with no event).
• Unit tests: catch matches-through-carrier / non-match / null-category / conjunction / unset / short-circuit, and the primitive directly.
• Full suite green (1357 passed); pyright, ruff, and mkdocs clean.

Notes

• The 0.15.0 changelog date is tentative pending the release tag.

[Copilot]

Pull request overview

Implements spec proposal 0074 (spec v0.65.0) by adding a failure-isolation catch category gate and promoting the carrier-skipping cause-chain walk to a public classify_cause_chain primitive, plus related documentation and spec pin/version updates.

Changes:

• Add catch (category-set gate) to FailureIsolationMiddleware, using cause-chain derived category to match through node_exception carriers.
• Introduce graph/cause_chain.py with CauseLink, CaughtException, and classify_cause_chain, and re-export via openarmature.graph.
• Bump spec pin/version to v0.65.0 and update docs, changelog, and conformance runner for fixture 072.

Reviewed changes

Copilot reviewed 15 out of 15 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
tests/unit/test_failure_isolation_middleware.py	Adds unit tests for catch gating behavior and classify_cause_chain.
tests/test_smoke.py	Updates __spec_version__ assertion to 0.65.0.
tests/conformance/test_pipeline_utilities.py	Adds fixture 072 and wires catch from conformance configs.
src/openarmature/graph/middleware/retry.py	Documents deliberate single-level retry classification depth.
src/openarmature/graph/middleware/failure_isolation.py	Implements catch gate and uses classify_cause_chain for gating + event payload.
src/openarmature/graph/events.py	Moves CaughtException type usage to new cause-chain module import.
src/openarmature/graph/cause_chain.py	New public cause-chain types + classification primitive.
src/openarmature/graph/init.py	Re-exports cause-chain types/primitive from openarmature.graph.
src/openarmature/AGENTS.md	Updates bundled agent guide spec version to v0.65.0.
src/openarmature/init.py	Updates __spec_version__ to 0.65.0.
pyproject.toml	Updates tool.openarmature.spec_version to 0.65.0.
docs/concepts/middleware.md	Documents catch gate and the new classify_cause_chain primitive.
conformance.toml	Pins spec to v0.65.0 and records proposal 0074 as implemented.
CHANGELOG.md	Adds entry for proposal 0074 and updates spec pin narrative.

Comments suppressed due to low confidence (1)

src/openarmature/graph/events.py:782

• openarmature.graph.events previously exported CaughtException / CauseLink (via __all__). Removing them is an observable API change; consider continuing to re-export them from this module for backward compatibility (even if the canonical home moved to cause_chain).

__all__ = [
    "FailureIsolatedEvent",
    "FanOutEventConfig",
    "InvocationCompletedEvent",
    "InvocationStartedEvent",
    "LlmCompletionEvent",
    "LlmFailedEvent",
    "LlmRetryAttemptEvent",
    "MetadataAugmentationEvent",
    "NodeEvent",
    "ParallelBranchesEventConfig",
]

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.