Upgrade action boundaries
For @arki/[email protected] · source docs/upgrade-actions.md
- Keep each business failure's canonical definition at its source. Replace handwritten unions and code arrays with references to those definitions.
- Choose a reusable
actiondescriptor or retain an independent native contract. Share schemas by reference when the operations are equivalent. - Bind the usecase with
bindActionon the server. Keep service closures out of browser contract imports. Declare adapter exposure, principal, approval and retry. - Use
runfor unknown input. Usehandleafter native input parsing, and let that transport validate and encode successful output exactly once. - Build RPC errors with
errorMap, throw throughorThrowRpc, and revive with the same canonical definitions. Declare HTTP failures on the route; handle canonical failure values instead of inspecting legacy HTTP error strings. - Check auth policy outcomes with
isFailure. Preserve masked resource access and transport challenge/retry headers. An authenticated principal attestation is established by trusted middleware, never by the caller's body. - Make retry ownership explicit. Action retry policy describes permission; execution does not retry. Update HTTP client callers for typed failure values, including unknown-code and invalid-payload protocol refusals.
- Register an OTel SDK and context manager once at app entry if exporting
telemetry. Use
$telemetryin plugin contexts ortelemetryFor(feature); avoid wrapping an already instrumented transport/provider operation again.
For executable authoring and exact source fixtures, see actions.
The MCP asTool annotation reuses contracts but does not execute them; its runtime
adapter remains outside this slice. See MCP contracts.