Results and proof boundaries
Why SDK failures are values, and why a type, test, or build proves only a bounded claim.
Capxul methods return CapxulResult<T> so expected workflow outcomes stay in
the type system:
const result = await client.accounts.read();
if (!result.ok) {
console.error(result.error.code);
return;
}
render(result.value);Invalid input, unauthenticated state, cancellation, insufficient balance, and provider failure are meaningfully different outcomes. A stable discriminated result preserves those differences across browser, Node, React, and agent consumers.
What exceptions mean
Expected domain failures are result values. An unexpected implementation throw is normalized or rethrown only at a boundary that cannot safely represent it as the normal contract. Observation distinguishes a failed result from a thrown failure, but never changes what the caller receives.
The proof ladder
Each kind of evidence supports a different claim:
| Evidence | What it proves | What it does not prove |
|---|---|---|
| Type surface | A consumer can express a call. | The method has a runtime implementation. |
| Hermetic unit/contract test | A deterministic program, adapter, or mapping behaves under its fixture. | A deployed backend, email provider, browser, or chain works. |
| Package build and pack inspection | The npm tarball compiles and exposes specific imports. | A live operation succeeds. |
| Process or adapter integration test | Selected real module boundaries compose. | Unused external services or product journeys work. |
| Named live proof | The exact described journey worked against real dependencies. | Adjacent methods or future runs are automatically proven. |
| Product/browser proof | A user-facing journey rendered and ran. | Every package contract or failure branch is correct. |
Negative contracts can be proven honestly
Some methods intentionally exist before the advertised operation so consumers
and dependent packages can converge on a shape. Those methods return
NOT_IMPLEMENTED. The narrow negative behavior can be shipped-proven without
claiming that the advertised operation works. Documentation must retain that
distinction until code and proof cross the actual capability boundary.
The current scaffold list is maintained in SDK capability status.