ADR 002: Native Boundary and Execution Architecture¶

Default rule: no native code until measurement proves otherwise¶

Native code is not added because a path might be hot, because Rust is available, or because a microbenchmark of a function in isolation looks good. It is added only after measurement of the user-visible path shows a performance, latency, jitter, scale, memory, reliability, or platform-interface limit that the Python implementation cannot resolve algorithmically or structurally, against a named baseline.

The baseline is trunk for active development comparisons and a tag or release for release-facing claims. The measurement must make the relevant boundary cost visible: how often Python crosses into native code, how much data crosses, and how much work native code performs per crossing.

This default outranks every shape below. The shapes describe how to integrate native code once the default is overcome, not whether native code is justified.

Accelerator: drop-in for a public Python API¶

An accelerator replaces a pure Python public API with a native implementation that preserves observable behavior. Python defines the meaning; Rust makes that same meaning faster.

Accelerators are governed by ADR 001.

Test: removing the native build changes nothing a user can observe except speed. The same callable, argument forms, return shapes, exceptions, mutation behavior, equality, hashing, ordering, serialization, context-manager behavior, and async behavior remain available.

Boundary: a public Python API to its native equivalent.

Tests: the same behavioral suite passes on both paths, with no tolerance unless the public API already documents one.

An accelerator may be invoked once per public callable invocation. That does not make per-item native crossings acceptable inside a larger internal loop unless the measured user-visible path proves that this crossing pattern is better than a batched boundary.

Do not dress a simple accelerator up as an engine to avoid ADR 001 compatibility tests.

Engine: in-process work over a plan, batch, or scoped native state¶

An engine consumes a normalized, typed plan or batch that Python builds, performs bounded in-process work or owns explicitly scoped native state, and returns compact results through coarse calls. Python remains the public authoring surface and source of truth. The native side does not receive an arbitrary Python object graph and does not call back into Python inside per-item loops.

Test: the boundary is crossed once per coarse unit, such as per run, per operation, per plan, per batch, or per flush. Native work happens in-process and does not own an independent lifecycle or event loop hidden from Python.

Boundary: Python-owned normalization to native-owned plan, batch, or scoped state.

Tests: semantic agreement with the Python path where behavior overlaps, plus tests for plan normalization, error mapping, resource cleanup, lifecycle boundaries, repeated use, and failure handling. Approximate reductions may use documented numeric tolerances, but native code must not silently change public semantics.

During heavy native work that touches no Python objects, the engine releases the Python interpreter so other Python threads can make progress. The policy is behavioral: heavy native work yields the interpreter. A clean implementation may choose the exact API spelling for that binding.

Shape analogues: Polars-style Python plan construction with native execution; pydantic-core-style schema construction with native validation.

Worker: independent lifecycle behind a message-passing protocol¶

A worker runs independently of the Python caller and communicates by message passing rather than by synchronous in-process calls. The distinguishing axis is message passing vs. direct FFI, not the operating-system process. A separate binary, a separate process, or a long-lived native background thread that talks to Python over a channel can all be workers if they own an independent lifecycle.

Test: the boundary is a versioned protocol or channel, and the native side runs its own lifecycle. The two sides could be versioned, deployed, or replaced independently as long as they agree on the protocol.

Boundary: Python orchestrator to independent worker over a protocol.

Tests: protocol schema tests, compatibility tests across protocol versions, crash handling, timeout handling, cancellation handling, resource cleanup, unsupported-capability rejection, and equivalence tests against the Python runtime where behavior overlaps.

A worker crash, protocol mismatch, or unsupported capability is reported as an operation failure. It is not masked by a silent switch to another execution model.

A new worker execution mode and protocol require their own ADR unless an existing approved protocol already covers the mode. Once a protocol exists, additional workers implementing that protocol are ordinary feature work if they do not change public semantics, packaging, or lifecycle behavior.

Boundary analogues: pure-native tools such as native CLIs demonstrate the process-boundary and no-hot-path-FFI model. A Python-orchestrated worker applies that idea through a versioned protocol.

Choosing the shape¶

Classify the boundary, not the component. A component with one boundary takes the narrowest shape that honestly fits it. Evaluate in order and stop at the first match:

1. Replaces a public Python API, observable only as speed? Use accelerator and ADR 001.

2. Runs in-process over a typed plan, batch, or scoped native state, with coarse calls and no per-item Python callbacks? Use engine.

3. Runs independently behind a message-passing protocol or channel? Use worker.

A component that exposes more than one boundary must satisfy every shape it touches. For example, a public callable backed by a background worker must satisfy the accelerator rules for the callable surface and the worker rules for the worker surface.

When a single boundary is genuinely ambiguous between adjacent shapes, take the stricter higher shape. An accelerator/engine straddle is governed as an engine. An engine/worker straddle is governed as a worker. A boundary that fits none of the three is not designed yet. Design it before writing native code.

Positive¶

• Native code has a measured reason to exist before implementation starts.

• The boundary shape, crossing frequency, and test burden are fixed before review.

• Drop-in accelerators remain governed by strict Python compatibility rules.

• Engines and workers can exist without pretending to be transparent accelerators.

• Native speedups are less likely to be erased by per-item FFI cost.

• Native logic can be tested separately from Python bindings.

Tradeoffs¶

• The project maintains boundary types, plan types, or protocol types where native engines or workers exist.

• Some native ideas are rejected because the boundary is too fine-grained or the packaging cost is too high.

• Engines and workers require more tests than pure Python alone.

• Declarative native subsets must be treated as explicit capabilities, not transparent acceleration.

Risks¶

Shape inflation: a simple accelerator may be called an engine to avoid ADR 001. The ordered classification rule mitigates this by checking the accelerator shape first.

Hidden lifecycle: a callable may quietly spawn a worker. The rule that each boundary is governed by its own shape mitigates this.

Semantic drift: native behavior may diverge from Python behavior. The mitigation is shared compatibility tests for accelerators, semantic comparison tests for engines, and protocol contract tests for workers.

Silent fallback: native failures may be hidden by broad fallback behavior. The mitigation is explicit fallback policy and tests that fail on unexpected native import, runtime, or protocol errors.

Boundary creep: a coarse boundary may decay into per-item calls. The mitigation is the native change record’s crossing-frequency field and benchmark requirement.