# Failure classification and decisions

Classify an observed failure by its earliest decisive symptom.

## Resolver says no usable distribution

1. Inspect candidate filenames and tags.
2. If a pure wheel exists, fix resolver/tag/metadata behavior; do not compile.
3. If a matching SandboxedJS wheel exists, inspect index `abiId`, digest, and
   dependency metadata.
4. If only an sdist or host-native wheels exist, route to the external
   cross-builder. Do not let the runtime installer build source yet.

## Build frontend cannot start

- Missing host Python module: classify as a build requirement.
- Unpinned requirement: add an exact version and hash acquisition path.
- Unsupported backend: add a backend adapter, not a package conditional.
- Network failure: preserve the command and request network approval; do not
  substitute an unverified archive.

## Compiler uses host headers or compiler

- Inspect generated cross-sysconfig and command line.
- Fix host/target environment separation.
- Never solve this by renaming a produced artifact.

## Header or library not found

1. Determine whether it is a Python dependency or a native target library.
2. For a target library, require a declared, pinned native dependency.
3. Build it into the ABI/profile-specific sysroot.
4. Expose sysroot include/library paths through the cross environment.
5. Add a reduced fixture proving the dependency mechanism before retrying a
   large real package.

## Configure test compiles, then tries to execute

This is a cross-compilation probe problem. Prefer, in order:

1. upstream-supported cross-file/cache variables;
2. a generic build-backend cross configuration;
3. a visible package patch providing the target fact.

Never execute target WebAssembly as if it were a host binary. If executing a
probe under a controlled runner is proposed, stop for architectural review.

## Linker failure

- Missing `Py*` symbols can remain unresolved in a side module if supplied by
  the main module; confirm rather than blindly adding `-lpython`.
- Missing native-library symbols require target dependency/link-order work.
- Shared-memory, PIC, exception, relocation, or atomics errors are ABI issues;
  inspect `INVARIANTS.md` and escalate before changing flags.
- Duplicate symbols often indicate a static library linked twice; inspect the
  complete link line.

## Wheel builds but validation fails

- Not `\0asm`: host compiler leakage.
- No `dylink`: side-module link mode was lost.
- Missing `PyInit_*`: module naming/export problem.
- Wrong tag or ABI: wheel construction problem. Rebuild; never retag.

## Install succeeds but import fails

- Missing Python wrapper files: wheel assembly/layout defect.
- Missing dependent shared/static symbols: target dependency closure defect.
- Init symbol mismatch: derive the module name from installed path.
- Trap, memory corruption, or exception failure: ABI mismatch until disproven.

## Import succeeds but behavior fails

Classify whether the package needs an unavailable OS capability, contains a
32-bit assumption, exceeds memory, or has a package defect. Record an honest
compatibility limitation when the platform capability is genuinely absent.

## Test hangs

Do not immediately increase timeouts. Determine whether the process is waiting
on input, network, a child process, a pthread, or a host ABI response. Capture a
bounded stack/process snapshot where possible. Kill only the exact process you
started.