kotlin-throwable-policy provides Kotlin Multiplatform helpers for deciding which Throwable instances must be propagated from broad catch blocks.

Use it at containment boundaries, cleanup paths, and callback adapters where code catches broadly but still needs to preserve fatal platform errors, interruption, cancellation, non-local control flow, and programmer-error signals.

commonMain.dependencies {
    implementation("one.wabbit:kotlin-throwable-policy:0.0.1")
}

import one.wabbit.throwables.Throwables

fun runBoundary(block: () -> Unit): Boolean =
    try {
        block()
        true
    } catch (t: Throwable) {
        Throwables.propagateIfNeeded(t)
        false
    }

propagateIfNeeded rethrows the first high-priority throwable selected by the active policy: fatal platform errors, interruption or cancellation, non-fatal errors, non-cancellation control flow, or contract violations. If nothing needs propagation, the caller can contain or translate the failure.

Throwables.defaultPolicy avoids allocation-heavy throwable graph traversal. It follows preferred causes and unwraps common platform wrapper exceptions.

Throwables.strictPolicy enables suppressed-exception scanning, follows suppressed causes, uses strict control-flow detection, and throws when traversal exceeds the configured maximum depth.

The rethrowControlFlow, rethrowCancellations, rethrowInterrupts, and rethrowContractViolations flags decide which non-fatal categories mustPropagate returns. Fatal platform errors always propagate.

Cleanup code can preserve primary and secondary failures without burying abort signals:

try {
    closeResource()
} catch (cleanup: Throwable) {
    Throwables.handleSuppressed(primary, cleanup)
}

If cleanup must propagate, it is thrown after primary is added as suppressed on a best-effort basis. Otherwise it is added to primary. When restoreInterrupt is enabled, handleSuppressed also restores the interrupt flag if cleanup contains an interruption signal.

This is an early 0.x policy library. The core API is small, but platform classifications may evolve as more targets and foreign runtime integrations are validated.

• User guide
• API reference notes
• Troubleshooting
• Development
• Policy contract

Generated API docs can be built locally with Dokka. See API reference notes for the command.

• CHANGELOG.md

This project is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0) for open source use.

For commercial use, contact Wabbit Consulting Corporation at wabbit@wabbit.one.

Contributions are governed by the repository contribution policy and the Wabbit CLA. See CONTRIBUTING.md and the files under legal/.