atoll

atoll is a strict Python package generated by scaffold-guard.

The implemented V1 slices scan Python projects for top-level symbols, dynamic blockers, mypy diagnostics, dependency edges, backend-neutral typed regions, conservative island candidates, poison residue, backend assessment, native artifact caching, PEP 517 wheel overlay, and runtime verification:

uv run atoll scan .

The scan command writes .atoll/report.json and .atoll/report.md. Report schema v3 preserves callable annotations, type parameters, class ownership, descriptor and execution kinds, class fields, connected typed regions, scalar and buffer proofs, and directed call-chain evidence for backend assessment and source-clean compilation. The public CompilerBackend contract separates per-member capability assessment, prepared compilation units, native compilation, strict fingerprints, and normalized diagnostics. The mypyc and Cython adapters emit region-owned artifact metadata, while the existing build_sidecars facade is reserved for explicit in-place enable/build behavior. Candidate scores are 0-100 scan-only heuristics for extraction safety, not predicted speed, while candidate risk also describes extraction risk. Frame-introspection code such as inspect.currentframe(), sys._getframe(), and direct frame attributes such as f_locals are hard blockers because mypyc changes Python frame semantics.

Compile

uv run atoll compile app.ranking
uv run atoll compile
uv run atoll compile --root /path/to/project

compile scans the target package, forms typed regions, asks the configured backends to assess each region automatically, compiles and caches supported variants, overlays staged routing code and region-owned native artifacts onto the project's normal PEP 517 wheel, verifies the result, and removes temporary artifacts by default. Pass a module name to limit the operation to one source module. --root ROOT selects the target checkout without changing the compile contract. The hidden package command uses the same source-clean typed-region pipeline. The original source files are left untouched. Discovery prefers the conventional src/ import root, then resolves explicit Setuptools, Hatch, Poetry, PDM, or Maturin source-root metadata for nonstandard layouts such as lib/package_name; undeclared layouts fall back to the project root.

The default persistent outputs are the wheel in .atoll/dist/*.whl plus .atoll/compile-report.json and .atoll/compile-report.md. Use --output to place generated wheel artifacts somewhere else. Pass --keep-install-tree only when you need to inspect the temporary install tree for debugging; the report marks that tree as retained. Atoll builds the target project's normal PEP 517 wheel from a temporary source-clean copy before overlaying staged routing code and region-owned native artifacts. The PEP 517 build is isolated and installs the project's declared build requirements automatically. This preserves package data, entry points, and backend-generated metadata. The final platform tag and RECORD are regenerated, then staged and wheel routing are verified in fresh interpreters before temporary trees are removed. For typed regions, compiled_regions records each backend variant, class and descriptor-aware bindings, runtime guards, concrete target owners, and native artifact paths. It also records lowering_mode; outlined-block variants list the private synchronous native_helpers called by their staged Python suspension shell. Typed-region entries preserve the original generic declaration and list specialization origins, substitutions, and concrete type bindings separately. Compile report schema v6 includes profile coverage, backend decisions, scalar and buffer proofs, dispatch order, suspension plans, native and execution-plan trials, source-optimization evidence, cache decisions, stage medians, optimization policy, and the final accepted composition. Source optimization remains report-only without configured semantic and benchmark commands. With both commands, Atoll may emit a patch only after the transformed source and its normally built PEP 517 wheel pass the hard source-optimization gate. Execution plans are reported separately from mypyc and Cython typed regions. It lists discovered and rejected plans, applied_execution_plans, three-arm execution-plan trials, staging cache status, payload-file evidence, marginal speedup over the unplanned payload, and overall speedup over the interpreted baseline. Unless applied_execution_plans lists a plan with passing semantic and benchmark evidence, it is discovery evidence only and does not change runtime behavior. The schema retains all v5 fields plus the legacy v2 compatibility fields islands and native_readiness; for source-clean typed-region compile they are legacy views and normally remain empty with zero counts. Region members expose ordered call sites, runtime imports, and suspension points, while dependency records identify invocation mode and whether a dependency must share a native compilation unit. Suspension plans include source coordinates, live-ins, live-outs, runtime dependencies, work signals, eligibility, and rejection evidence for every considered synchronous block.

For one precise coroutine, generator, or async-generator binding, a deterministic whole-callable Cython rejection can fall back to planner-approved synchronous blocks. The staged Python shell continues to own await, yield, cancellation, exception handlers, and cleanup while native helpers receive explicit live-ins and return live-outs. Unsafe control flow, cells, nonlocals, nested definitions, comprehensions, deletion, global declarations, and exception/context boundaries stay interpreted. Native helper failures propagate without retrying the same block in Python. Global and builtin names are resolved against the source module at every native read, preserving rebinding performed by earlier calls in the same block. Only bare @staticmethod and @classmethod descriptors are recognized; qualified and custom decorators stay interpreted.

Source-clean compile no longer generates Python sidecars or performs generated-AST native-readiness scoring before backend compilation. Ordinary functions, methods, classes, sync generators, coroutines, and async generators are eligible when a backend reports that it can lower the member while preserving the source contract. Atomic class replacement requires every method to be supported and no module-time decorator, reassignment, instance, subclass, annotation, default, registry use, source-defined base, asynchronous method, or class-body side effect. If that proof fails, Atoll preserves the source class and routes eligible methods independently. Cython owns atomic classes so their method reflection remains Python-compatible. An atomic-class rejection caused only by the supported iterator protocol does not block ordinary descriptor replacement on the original class; __iter__ and __next__ are the only special-method slots currently eligible for independent binding. Mypyc remains preferred for callable members, while Cython also handles unsupported member execution shapes or deterministic mypyc type failures. During automatic whole-project selection, a mypyc error originating in imported target-project source opens a cached project-scoped circuit for that import package: later eligible variants use batched Cython fallbacks instead of repeating the same type-graph failure, and an unchanged warm compile restores the decision and artifacts without compiler processes. Cached mypyc successes keep priority, any target-source change invalidates the project decision, and explicit module or member selections continue trying their requested backend. Cython annotation typing and C-type inference are disabled to preserve Python integer and container semantics. Relative imports inside copied callables keep their original execution scope and resolve against the source package rather than the private extension module. Reads, writes, and deletions of omitted same-module state route through the original source module so native bindings and Python fallbacks share one cache or registry. A profile-hot callable with explicit Any, incomplete annotations, or unresolved TypeVars may use boxed Cython semantics; without a configured benchmark those boxed candidates remain interpreted. PEP 695 function type-parameter syntax is removed only from private generated Cython input, while the public wrapper retains source annotations and type parameter metadata.

Generic definitions remain the Python fallback. Atoll creates a separate specialization only when every TypeVar closes from a same-module concrete subclass or an unambiguous same-module call with statically concrete inputs. Subclass specializations bind only to the concrete subclass. Runtime routing checks scalar or nominal classes, None, and unions of those in constant time, then calls the original Python function when a guard fails. Parameterized containers, defaults or variadics that carry TypeVars, conflicting calls, unresolved TypeVars, semantic Any, subclass overrides, and dynamic owner classes are not specialized. Profile-hot boxed callables can still compile without claiming their types became concrete.

Pure synchronous functions and static methods with exact int inputs can use guarded Cython int32_t and int64_t variants when interval analysis proves every native intermediate. Dispatch checks exact type and closed decimal bounds, then tries 32-bit, 64-bit, a generic compiled target, and Python. Invalid domains fall back before entry and overflow is never retried.

Proven acyclic same-module call chains can keep scalar values native through private cdef inline helpers. Root entry checks callable and code identities plus exact receiver and direct scalar-field guards. Atoll-managed helper dispatchers are canonicalized to their untouched Python fallback for identity checks; arbitrary monkey patches, recursion, indirect dispatch, and subclasses fall back.

Exact bytes, bytearray, memoryview, and array.array parameters can use a zero-copy Cython typed-memoryview kernel when static analysis proves a read-only sum, XOR, or conditional-count loop. Runtime dispatch checks exact type, one-dimensional contiguous format and item size, mutability when required, and a constant-time safe length before native entry. The initial memoryview and array.array specialization accepts unsigned-byte (B) layouts; unsupported formats, strided views, mutation, complex indexes, and mixed reductions retain Python behavior.

Profile-selected functions and methods use directed slices rooted at one public binding. Ordinary same-module calls, awaited calls, class construction, and receiver method dispatch remain normal late-bound runtime boundaries unless syntax proves a shared native unit is required. A blocked or dynamic callee therefore does not automatically reject its hot caller. Explicitly declared methods on recognized dataclasses may be rebound while the original class object and descriptor kind stay intact. A single unguarded exact-shape target with no source defaults can bind directly; defaulted, guarded, multi-variant, or instance-method targets without compatible descriptor behavior retain the generated dispatcher so source default objects and fallback selection remain authoritative.

During source-clean compile, Atoll prints timed progress lines to stderr for discovery, scanning, staging, cache lookup or restore, backend compilation, wheel writing, verification, and cleanup. Compile reports include cache status plus subphase timings such as mypycify, cythonize, and build_ext. Compatible cold Cython misses share a bounded parallel build; deterministic failures are bisected back to individual variants. Promotion requires a representative 20% cold-time reduction with artifact parity, while a fully warm batch restores every artifact without invoking a native compiler. Duplicate macOS linker -rpath warnings are filtered from terminal output; other native compiler diagnostics are still captured in Atoll's build diagnostics. Atoll keeps strict reusable compile and mypy cache state under .atoll/cache/. Typed variants are cached independently by backend and region under .atoll/cache/compile/regions/; deterministic non-transient backend rejections use the separate .atoll/cache/compile/decisions/ namespace. An unchanged variant restores either the decision or native files without invoking mypyc or Cython. With reproducible PEP 517 dependency resolution, such as an offline wheelhouse, a digest-verified copy of the target's normal wheel lives under .atoll/cache/baseline-wheel/; mutable online resolution bypasses reuse. Safe warm builds can therefore avoid recompiling target-owned extensions. atoll clean --cache removes all reusable build state. Benchmark-guided builds continue to collect a fresh profile on every invocation. The 2 ms sampler measures process-CPU leaf frames, may combine up to three short sampling passes to reach the minimum evidence floor, and retains nested scheduler attribution as orchestration evidence rather than native-candidate work. The unmeasured monitoring pass feeds mapped project starts into a fixed-budget heavy-hitter summary while limiting lifecycle and argument-type capture to selected targets, so very frequent thin work can be trialed without unbounded observation. A supported benchmark that still has insufficient evidence follows the measured no-op path instead of starting an exhaustive native build. The first strict native candidate plan is stored under .atoll/cache/profile-plans/, preventing statistical sample jitter, including a later empty selection, from creating a cold artifact variant on an unchanged warm build. Replay never skips the configured semantic, marginal-profitability, or final benchmark gates. After a source candidate passes every final 3x gate, Atoll stores only its strict identity under .atoll/cache/accepted-winners/; warm replay reruns tests, profiles, timings, and both final gates. The identity covers benchmark and test content, project metadata, the baseline wheel payload, dependency versions, and the build environment. A candidate that fails replay semantics is not retried during that invocation; the full search continues with the remaining candidates. A passing replay seeds, but never replaces, fresh bounded candidate comparison under the current environment. Module-level typing diagnostics, such as unsupported TypeVar keyword arguments, remain visible in scan and compile reports. A callable from such a module is compiled only when the typed-region analysis and backend capability assessment can still preserve its source behavior. Boxed executable code that reads a canonical module-level TypeVar, ParamSpec, or TypeVarTuple resolves the original object through the live source module rather than copying or erasing the declaration.

Atoll v1 source-clean compile targets backend-supported typed regions, including ordinary functions, eligible classes and methods, async shapes, and narrowly guarded concrete generic specializations. Dynamic, unresolved generic, runtime-incomplete, and identity-sensitive regions remain Python, and Atoll does not treat object-rich orchestration as one native unit. Large gains are expected only when meaningful application time is spent inside accepted CPU-bound code; successful compilation is not a speedup claim.

Profile-guided source optimization

With both test_command and benchmark_command, atoll compile evaluates source rewrites for hot async fan-out and fan-in pipelines. Trial eligibility requires 10,000 observed work items, no observed suspension for the fused callable shape, and at least 70% mapped hot-path coverage. Atoll uses the sampled coverage's 95% Wilson upper bound for this pre-trial decision, preventing noisy point estimates near 70% from changing unchanged cold and warm eligibility. Fresh semantic and profitability gates remain mandatory. Atoll ranks at most two plans and tests no more than eight ordered compositions with beam width two and depth four. An unsafe residual remains report evidence and does not block a later independently proven transformation.

LibCST applies each candidate only in a temporary project copy. The guarded path can drain a private transport in batches, execute proven quiescent coroutine work in one copied Context per logical item, fuse local producer/transport/consumer state, and auto-forward a private run-to-completion protocol. Every source, callable, scheduler, stream, descriptor, and code identity guard runs before the first transformed side effect. Suspension, task or cancellation introspection, context mutation, dynamic scheduling, changed descriptors, tracing, profiling, and monitoring use the original path. After optimized entry, Atoll never retries the operation in Python. ATOLL_DISABLE=1 forces the original path; ATOLL_REQUIRE_OPTIMIZED=1 exposes guard failure to strict tests.

After a transformed candidate passes semantics and the 1.05x marginal search gate, Atoll reruns profiling against that staged payload with optimized routing enabled. Only a completed dynamic profile can seed another search depth. The gate uses the median of corresponding current/candidate ratios from each rotating three-arm sample group, preventing one order-biased current measurement from changing the accepted patch. Unsupported launchers, insufficient samples, and failed passes stay in the report as rejection evidence. Structurally owned AnyIO-on-asyncio streams can receive ordered residual trials for run-scoped guard amortization, quiescent await-chain collapse, proven-safe context copy elision, incremental completion accounting, and private result-record projection. Each trial's fresh residual profile is included in the compile report.

A separate structural proof recognizes private exact-dictionary completion scans that test stack-run and node membership. The transformed source maintains a private count and index at every proven map write and removal while its fallback still creates the original value snapshot and invokes the original predicate. When profitable, one transactional Cython unit replaces the cached run guard, snapshot, and indexed query. Exact owner and predicate-code identities and the active-count invariant are checked before native routing, so missing artifacts, stale state, changed code, and ATOLL_DISABLE=1 retain the source scan.

Source-patch promotion requires max(3.0, minimum_speedup) for both the transformed source tree and its normally built PEP 517 wheel over seven alternating pairs. Default compile leaves checkout sources unchanged and writes an accepted patch to .atoll/patches/<candidate-id>.patch. Generated patch cache entries live under .atoll/cache/source-optimization/; failed candidates never emit a reviewable patch.

Accepted source optimization remains available as the fallback baseline for later stages. Atoll recreates the patch under disposable build storage, rescans it, and can layer profitable native regions or execution plans onto the transformed wheel. If a later stage fails semantics or its performance gate, the accepted source-only wheel survives; the transformed project copy is always removed with build scratch. The complete composition must improve the accepted source-only arm by at least 1.05x in a direct paired benchmark before the final overall gate can promote it.

uv run atoll compile --root . --apply-source

--apply-source requires Git, rejects --in-place, stale hashes, and files changed after profiling, runs git apply --check, then reruns tests and the full benchmark after applying the accepted patch. Atoll reverses the patch when either post-apply gate fails.

Semantic and performance gates

Without a configured benchmark, compile can emit a wheel but records performance as unbenchmarked. Configure argv commands in pyproject.toml when wheel promotion must require semantic equivalence and a measured minimum speedup:

[tool.atoll.compile]
backends = ["mypyc", "cython"]
test_command = ["pytest", "-q"]
benchmark_command = ["python", "benchmarks/atoll_workload.py"]
benchmark_warmups = 1
benchmark_samples = 7
minimum_speedup = 1.10

minimum_speedup must be greater than 1.0. Every native variant and execution plan requires a 1.05x marginal improvement. Both measured medians must exceed 0.25 seconds, while source patches and representative optimizer-family workflows use the separate 3.0x hard floor.

Atoll runs these arrays with shell=False. For python script.py and python -m module benchmark commands, it builds and tests the baseline wheel before region selection, then runs unmeasured profiling. A 2 ms statistical sampler combines project leaf frames with nested scheduler or library frames attributed to the active project caller. A bounded Python 3.12 monitoring pass records lifecycle counts and canonical module.qualname argument type identities for the hottest combined activity without retaining values or representations. It also maintains a bounded heavy-hitter summary across mapped project callables, processing at most 1,000,000 mapped starts and retaining at most 128 callable identities without collecting unbounded type evidence. Reports keep at most eight signatures per targeted member and distinguish polymorphism from a reached observation budget. Recognized task-spawn callees are also targeted directly; reports retain their completion count, maximum overlap, and pre-completion suspension count. Atoll requires 100 total samples, considers candidates with at least 20 leaf samples and 2% of workload samples, and separately considers mapped callables observed with a conservative lower bound of at least 10,000 calls and 2% of bounded invocation activity. It selects at most four; leaf-sample selection stops at 80% mapped coverage, while invocation-hot decisions remain explicit. Unsupported launchers or insufficient evidence fall back to static selection while retaining the final performance gate.

For a supported profile, Atoll compiles the candidate superset once and tests candidates in hotness order through an internal region allowlist. Each candidate combination runs the semantic command once, then one warmup and three alternating benchmark pairs compare it with the accepted set. Atoll retains only candidates with at least 1.05x marginal median speedup, rebuilds the payload from the baseline, and removes rejected shims and artifacts. Reports distinguish mapped coverage, selected hot coverage, accepted hot coverage, lowering mode, fallback reason, and marginal speedup. When every profiled candidate is rejected, Atoll records a structured no-op without timing or publishing an unchanged wheel.

Profile-selected async execution plans are trialed only when both test_command and benchmark_command are configured. Discovery is automatic for the built-in asyncio and AnyIO-on-asyncio dialects, and execution plans are evaluated independently of mypyc and Cython typed regions. Plan staging works in a disposable copy of the accepted payload, keeps the original implementation as a guarded fallback, and verifies every reported payload change before project code runs. Atoll executes the semantic command once, then compares one warmup and seven alternating benchmark trios across interpreted baseline, unplanned compiled payload, and planned payload. The planned payload must be at least 1.05x faster than the unplanned payload. Its provisional overall ratio remains report evidence, while the configured full benchmark is the sole minimum_speedup gate and removes the wheel when the final payload misses it. Otherwise the plan remains report-only or is recorded as rejected without discarding an accepted native wheel. Without both commands, plans remain report-only and native behavior remains unchanged. A plan-only overlay that contains no native artifacts preserves the baseline wheel's pure tag, such as py3-none-any.

For field-backed AnyIO rendezvous workflows, the task-preserving backend guards the exact task-group and source coroutine identities, hoists the stable worker name, and calls AnyIO's original create_task() path. This retains the task factory, task objects, handles, context, cancellation, stream sends, and stream receives; the original start_soon() branch remains the fallback. It can skip cancellation only after a source-hashed worker has made a tail-position terminal handoff on the plan's private stream. Custom factories, changed workers or task groups, nonterminal sends, sibling cancellation, changed stream topology, debugging, tracing, and monitoring retain the original path. A linked hot reducer may replace len(inspect.signature(function).parameters) with an exact code-object parameter count only for an unwrapped Python function under the original inspect implementation. Every other callable uses the original reflection expression. Cross-module plan members and their complete source hashes are recorded in schema v6.

Execution-plan staging cache entries live under .atoll/cache/execution-plans/. A cache hit restores the planned payload files but does not skip semantic or profitability gates: profile collection, the semantic command, three-arm execution-plan trials, and the final benchmark still run before a plan can be applied. Atoll does not report speedup unless the configured gates pass; failed, unavailable, or unprofitable plan trials remain report evidence only.

Atoll also emits deterministic report-only task-fusion plans for recognized start_soon, create_task, and ensure_future sites reachable from selected hot roots. A plan cannot proceed unless one same-module coroutine has at least 20 complete monomorphic observations, no overlap, no pre-completion suspension, and no cancellation, instrumentation, context-variable, additional concurrency, or unresolved dynamic-effect dependency. Reports list every rejection. If the safe compiled payload misses its full performance gate, the internal research runner stages each eligible plan in a disposable payload, compares baseline, unfused, and fused arms, and requires at least 1.05x over unfused plus 1.10x overall. Normal compile never enables task fusion, and no experimental_task_fusion setting is public unless the pinned hard benchmark passes those gates.

The manual generic source-optimizer benchmark runs the copied-context semantic matrix and enforces the 3.0x guarded feasibility floor without target-project rules. It calibrates each arm independently above the stability floor and compares normalized time per logical execution.

The manual native optimizer benchmark builds the generic fixture cold and warm, verifies zero warm compiler invocations, and requires independent 3.0x results for mixed scalar, direct call-chain, and standard-buffer workloads over one warmup and seven rotating pairs.

The repository also contains a manual Pydantic Graph hard benchmark. It pins one external revision, uses a deterministic async graph workload, compiles cold and warm, and verifies source hashes, stable source-plan and patch identities, a cold patch-cache miss, a warm patch-cache hit, and at least 3.0x for both transformed source and the normal wheel. It runs only through explicit GitHub workflow dispatch or the repository script; normal CI does not enforce host-dependent wall-clock ratios.

The multi-repository benchmark corpus measures a different boundary: complete project compatibility across 25 pinned repositories and end-to-end performance across 12 reviewed workloads. It keeps unsupported and no-op outcomes visible, separates Ubuntu from macOS, and never mixes calibration kernels or semantic negative controls into real-repository aggregates.

Profiling and candidate trials are excluded from the final benchmark medians. The accepted payload must pass the test command before Atoll runs the configured alternating baseline/compiled subprocess pairs. Medians below 0.25 seconds are too noisy. Test failure, invalid timing, or speedup below the threshold removes the candidate wheel; the JSON and Markdown reports retain the command evidence and decision. The wheel remains under temporary build storage until this full gate passes. Commands run from a temporary project copy that retains tests and benchmark files but removes importable checkout modules, preventing flat-layout source from shadowing either payload. Verification and gate failures remove the disposable build tree, install payload, and rejected wheel while retaining command and decision evidence in the compile reports; no failed candidate remains in the normal wheel output directory. Runtime safety selection can retain failed probes for rejected native variants without marking a successfully reduced and promoted wheel as failed.

Compiled functions and methods retain their source name, qualified name, documentation, annotations, signature, and sync, coroutine, generator, or async-generator shape. Async-generator wrappers forward asend, athrow, and aclose; method routing preserves normal, static, and class descriptors on the original source class. Atomic classes preserve their public module, qualified name, documentation, annotations, constructor signature, bases, subclass behavior, and pickle identity. ATOLL_DISABLE=1 keeps interpreted routing, while ATOLL_REQUIRE_COMPILED=1 checks only promised bindings. ATOLL_REQUIRE_OPTIMIZED=1 checks the accepted generated source fast path. Source-clean build failures keep terminal output short, write .atoll/compile-report.*, and remove temporary build and install roots. Run compile commands inside the target project's Python environment because native backends use the active interpreter and installed dependencies.

In-Place Compile

Use --in-place only when you intentionally want Atoll to modify the checkout with managed shim blocks marked BEGIN ATOLL MANAGED. In-place compile writes configuration to .atoll.toml, compiled extensions to .atoll/artifacts, and compilation summaries to .atoll/compilation-report.json and .atoll/compilation-report.md.

uv run atoll compile app.ranking --in-place
uv run atoll compile app.ranking --in-place --test "pytest tests"

Routing verification proves that managed shims import compiled extensions and rebound configured symbols; it does not prove semantic equivalence. Use --test with --in-place to run pytest with ATOLL_REQUIRE_COMPILED=1. Generated Python sidecars in .atoll/sidecars, native compiler scratch files, and mypy's internal mypyc cache in .atoll/build are disposable build inputs for explicit in-place enable/build workflows; successful in-place compile runs remove them and list the cleanup in the compilation report. If the semantic test gate fails, Atoll leaves generated build inputs in place for debugging and marks the compilation report failed. The older hidden atoll package command remains available as a compatibility alias for source-clean typed-region artifacts.

Lower-level commands remain available for debugging:

uv run atoll enable app.ranking --all-candidates
uv run atoll generate --check
uv run atoll build --clean-first
uv run atoll verify --require-compiled

Explain And Trial

uv run atoll explain app.ranking
uv run atoll explain app.ranking::score_user
uv run atoll trial --top 3 --test "pytest tests"
uv run atoll trial --top 3 --test "pytest tests" --benchmark "pytest benchmarks"
uv run atoll clean --all

explain reports fixed-width domains, fused call-chain helpers, zero-copy buffer layouts, and specialization fallback reasons. These are static capability facts rather than speedup estimates.

Trial mode preserves --candidate and --top selection, then compiles the selected callable closure through the same source-clean package pipeline used by atoll compile. It uses temporary wheel, install, and cache artifacts, binds only the requested public functions, and keeps helper callables private inside the compiled closure. Configured compile quality gates are ignored for trial; only the optional --test and --benchmark commands are run, and both are one-shot pytest-style exit checks. A failing --test stops before the benchmark. Temporary artifacts are removed by default; --keep-temp retains the wheel, install payload, and isolated cache for inspection. Compiled routing is required by default; use --allow-interpreted to permit interpreted fallback during trial commands. --allow-python-sidecar remains as a compatibility alias.

Validate

scaffold-guard validate

Explore

Start with src/atoll/core.py and tests/unit/test_core.py.