feat(plugin): report incomplete user function outcomes

[wangyb-A]

Summary

• add UserFunctionOutcome.INCOMPLETE without adding a new plugin hook or info type
• guarantee every on_user_function_start is paired with exactly one existing on_user_function_end, including suspension and other BaseException exits
• release OTel context scopes for incomplete CONTEXT and STEP user functions without marking or ending incomplete STEP spans
• document the three-outcome lifecycle contract and update the suspension/threading regression tests

Semantics

INCOMPLETE means the current user-function execution left without producing a success or failure outcome. It covers suspension, orphaned branches, background checkpoint failures, and interpreter-exit control flow. Plugins receive it on the thread that executed the user function, allowing thread-bound state to be released. A suspended operation may resume later and report another start/end pair with its eventual outcome.

No new DurableInstrumentationPlugin callback or payload type is introduced. SUCCEEDED and FAILED behavior is unchanged.

Validation

• hatch run test:all — 3253 passed, 2 skipped, 5 subtests passed
• hatch run types:check — clean
• hatch run dev-core:typecheck — clean
• hatch run dev-otel:typecheck — clean
• hatch run dev-otel:test — 146 passed
• hatch fmt --check — clean
• independent diff review — no blocking findings

Resolves #658

[github-actions]

Codex AI review

[P1] Version the new lifecycle contract across packages

The plugin API remains v1, so a core-only upgrade still loads existing v1 plugins. Released OTel plugins treat every non-FAILED STEP end as success, causing INCOMPLETE attempts to be exported as successful. Conversely, this PR's OTel package still permits core >=1.8.0, where INCOMPLETE does not exist, so its new enum access raises AttributeError on every STEP end. Increment the core/plugin-provider API version and OTel core dependency floor together, or add a compatibility shim, with mixed-version tests in both directions.

[github-actions]

Codex AI review

One blocking cross-version compatibility issue remains in the core/OTel plugin lifecycle contract.

Reviewed commit 48df93edf85e5fe0d197415f8f49e4fdc6e0c45a. Workflow run