v0.14 Rust migration decision ledger
August 27, 2026 · View on GitHub
Status: active implementation ledger for Lacuna 0.14.0.
This page records the operational outcome of every foundation and candidate in the
Rust migration register. The register explains architecture and
candidate contracts; this ledger answers what was measured, what shipped, and why. A release tag
is blocked while any row remains PROPOSED, MEASURED, or ADMITTED.
Evidence contract
Every measured row links to a lacuna.native-migration-benchmark version 1 artifact produced from
the exact source commit. The artifact records effective dimensions, reference and candidate
latencies, incremental process RSS, copy/workspace bytes, thread configuration, equivalence
checksums, and the admission decision. Generated inputs use fixed seeds and are created outside the
timed region. Native admission requires correctness plus one of:
- at least 1.5 times end-to-end throughput over the optimized reference;
- at least 30% lower incremental peak RSS with no more than 10% latency regression;
- bounded-memory completion of a declared workload the reference cannot complete under the same budget.
The result must reproduce in nightly CI before a native path becomes SHIPPED_NATIVE. The
non-publishing release preflight repeats the same evidence for the exact release SHA and remains a
tag gate; it does not create or change candidate decisions. A negative result is terminal for
v0.14 unless a changed design or new representative evidence is reviewed.
Foundation decisions
| ID | State | Evidence commit/run | Effective shape | Reference/candidate result | Decision and reopening evidence |
|---|---|---|---|---|---|
| F-01 typed array boundary | SHIPPED_NATIVE | e54b757 CI | one Linux cp311-abi3 wheel on Python 3.11–3.14; Linux x86_64/aarch64, macOS arm64, and Windows x86_64 target wheels | Typed NumPy bulk-copy boundary, grouped IC, and PBO passed same-wheel and target-wheel parity; MSRV, dependency, license, and RustSec gates passed | Release-ready. Reopen only if the stable-ABI or target-wheel matrix stops passing. |
| F-02a exact c14n-v1 streaming | OPTIMIZED_NON_NATIVE | c7fd033 array, c7fd033 frame | 100,000 × 4 float64 array and Polars frame | 12.83×/38.1% RSS and 1.58×/27.3% RSS; exact digests | Python streaming resolves the material allocation and latency problem. Reopen native work only with a different design and pinned-Linux evidence. |
| F-02b new identity | BLOCKED | ADR-017 | not applicable | Deferred | Reopen only through a new canonicalization ADR and migration. |
| F-03a compact internal carriers | OPTIMIZED_NON_NATIVE | 957cc16, 010b873, 97db28e, d3f85df | cost components, resample values/indices/offsets, and CPCV design spike | contiguous carriers remain behind cost and scalar-bootstrap APIs; memory-heavy joint resampling and CPCV carriers were removed after full-call measurement | Reopen CPCV carriers only with a changed projection design or a separately approved public-carrier contract. |
| F-03b public carriers | BLOCKED | ADR-017 | not applicable | Deferred | Reopen through public API/schema migration. |
| F-04 execution budget | OPTIMIZED_NON_NATIVE | 2f5f180 | bounded bootstrap batches; native threads=1 | fixed/output and temporary allocation checks occur before allocation | Parallel native work remains blocked; extend the private resolver only as candidate callers migrate. |
| F-05 benchmark evidence | OPTIMIZED_NON_NATIVE | e54b757 nightly, e54b757 CI | isolated smoke/small/medium cases; seven timed repetitions after two warm-ups | sidecar v1 records process RSS, traced memory, copy/workspace/projection bytes, effective dimensions, thread configuration, exact checksums, full evidence comparison, and mechanical admission | The Python/CI harness is release-ready. Exact-SHA preflight must reproduce it before tagging. |
Candidate decisions
| ID | State | Public operation | Evidence commit/run | Effective shape | Baseline / optimized / native | Correctness | Decision and reopening evidence |
|---|---|---|---|---|---|---|---|
| R-01 | SHIPPED_NATIVE | grouped rank IC | e54b757 artifact, nightly run | 1,625,750 rows, 1,000 groups cycling through 3/250/1,250/5,000 rows, 3 horizons | local v0.13/reference/native: 282.50/282.50/41.14 ms; authoritative optimized NumPy/native: 11.935/2.076 s (5.749×) | exact structure, checksum, and all 2,989 compared numeric values; analytical, skewed-group, tie, signed-zero, null, boundary, and differential tests pass | Release-ready single-threaded typed-array kernel. The exact-SHA preflight remains a tag gate. Reopen a negative decision only with changed representative evidence. |
| R-02 | OPTIMIZED_NON_NATIVE | cost stress | 1a35b3e baseline, 957cc16 reference | 100,000 rows, 9 scenarios, 200 periods | repeated row/scenario tuple construction replaced by one component and period aggregation; local timing is non-authoritative | exact equivalence checksum plus literal row-rescan, unknown-row, reconciliation, and monotonicity tests | The complete non-fingerprint portion is only an 8.64% upper bound on public latency, below native materiality. Reopen with a changed full-call profile on the pinned runner. |
| R-03 | OPTIMIZED_NON_NATIVE | capacity curve | 37a0da5 baseline, 957cc16 reference | 100,000 rows, 3 scenarios, 10 capital points, 200 periods | exact s, s^(3/2) and period sufficient-statistic evaluation replaces 30 trade rescans | exact equivalence checksum plus literal trade-rescan, constraint, unknown-liquidity, and zero-quantity tests | The complete non-fingerprint portion is only an 8.01% upper bound on public latency. Reopen with a changed algorithm or pinned profile. |
| R-04 | OPTIMIZED_NON_NATIVE | break-even cost | 37a0da5 baseline, 957cc16 reference | 100,000 rows, 33 screen points, 200 periods | net P&L/return are O(1) per point; Sharpe/CAGR retain O(periods) | structural output is exact; literal rescans agree within 1e-12 and the near-zero trace difference is about 4e-11 | The complete non-fingerprint portion is an 8.77% upper bound on public latency. Native work is not material. |
| R-05 | OPTIMIZED_NON_NATIVE | purged/CPCV assembly | d3f85df rejected native spike | 100,000 rows, 6 groups, 15 combinations, 1.5 million role evaluations | 420.52 ms v0.13 baseline / 184.60 ms optimized / 159.42 ms native (1.158× versus optimized) | exact equivalence checksum; analytical, half-open interval, embargo, source-order, path-incidence, boundary, and property tests passed before removal | The optimized NumPy path is 2.28× faster than baseline. Native missed the 1.5× full-call gate because unchanged Fold and evidence projection dominate; the kernel, binding, and dispatch were removed. Reopen only with a changed projection design or new representative evidence. |
| R-06 | NOT_MIGRATING | shared resampling reduction | 957cc16 baseline, 97db28e bounded reference | 204 rows, 12 columns, 1,000 resamples | 120.15 ms / 125.02 ms bounded reference; experimental vectorization was 121.10 ms with about 23 MiB more RSS | final checksum is exact; RNG/substream and batch-size invariance plus independent White/Hansen fixtures pass | Index generation owns 96.4% of the measured path; the eligible reducer owns 3.6%. No native RNG is allowed, so the Rust reducer fails materiality. Reopen only with a new reducer scope or profile evidence. |
| R-07 | OPTIMIZED_NON_NATIVE | permutation reduction | 1bdb0a8 baseline, 3b492eb reference | 204 rows, 2,000 unrestricted Pearson permutations | 83.83 ms / 31.14 ms optimized / no native spike (2.69×) | exact equivalence checksum, exact RNG identities, and literal corrcoef agreement within 1e-15 | Centered norms and the paired vector are invariant, so one NumPy dot product replaces repeated corrcoef construction. The optimized public call is below 50 ms; reopen native work only with a newly material workload. |
| R-08 | SHIPPED_NATIVE | PBO/CSCV | c031c82 baseline, 7bbdf55 reference, e54b757 nightly artifact, nightly run | 1,008 rows, 12 strategies, 14 partitions, 3,432 combinations | 730.09 ms v0.13 / 178.23 ms optimized / 48.89 ms local native; authoritative optimized/native: 405.55/85.71 ms (4.732×) | structure is exact; all 17,163 finite values are within 1e-12 (max absolute error 1.67e-16, max relative error 9.15e-15); exact sidecar checksums remain recorded separately; Rust/core boundary, mean/Sharpe, tie, layout, and status tests pass | Release-ready at the 512-combination crossover. Python retains policy, RNG-free combination enumeration, and result construction. Exact-SHA preflight remains a tag gate. |
| R-09 | OPTIMIZED_NON_NATIVE | bucket assignment | a538500 baseline, 1c2817b reference | 100,000 rows, 200 groups, 5 buckets, 0.14% nulls | 142.19 ms / 61.87 ms optimized / no native spike (2.30×) | exact equivalence checksum plus literal group-oracle coverage across bucket kinds, ties, direction, exclusions, and group support | One Polars plan removed Python group materialization and cut traced Python peak memory 17.6%. Reopen only if pinned evidence isolates a material residual outside Polars. |
| R-10 | OPTIMIZED_NON_NATIVE | membership turnover | baseline, reference | 100,000 rows, 200 periods, 500 instruments, 5 buckets, 3 lags | 77.84 ms / 42.10 ms optimized / no native spike (1.85x) | exact equivalence checksum, legacy lag-one fixtures, and churn-heavy literal-set differential coverage | Endpoint self-joins eliminated Python sets and cut traced Python peak memory 83.8%; the optimized public call is below 50 ms. Reopen only with a newly material shape. |
| R-11 | OPTIMIZED_NON_NATIVE | prior-only regime quantiles | baseline, reference | 100,000 rows, 252-observation window, 63 minimum history, 1.03% nonfinite | 5.28 s / 1.74 s optimized / no native spike (3.04x) | exact equivalence checksum plus bit-identical NumPy-linear, prior-only, null/NaN, chunk, and permutation coverage | Polars order statistics remove the quadratic Python loop. The complete optimized Polars phase is about 1.7% of the instrumented public call, below native materiality. Reopen only if threshold work becomes material after a changed carrier or workload. |
| R-12 | OPTIMIZED_NON_NATIVE | event windows | baseline, reference | 100,000 price rows, 5,000 events, 80,000 requested path rows, 500 instruments | 182.93 ms / 61.94 ms optimized / no native spike (2.95x) | exact equivalence checksum plus irregular-calendar, null/exhausted-anchor, censoring, chunk, ordering, and overlap coverage | Polars as-of/range joins cut incremental RSS 85.1%. The eligible residual joins and aggregation are under 10% of instrumented public latency, below native materiality. Reopen with a newly material residual profile. |
| R-13 | OPTIMIZED_NON_NATIVE | event response | baseline, reference | 20,000 events, 40 clusters, 4 offsets, 1,000 resamples | 746.68 ms / 18.60 ms optimized / no native spike (40.1x) | exact equivalence checksum, unchanged Python RNG identities, literal path-concatenation agreement, unequal-cluster weighting, and batch-size invariance | Cluster sufficient statistics cut incremental RSS 98.3% and move the public call below 50 ms. R-06 leaves no material Rust reducer. Reopen only with a newly material shape. |
| R-14 | OPTIMIZED_NON_NATIVE | portfolio projection | baseline, reference | 100,000 rows, 200 cohorts, 10 neutral groups, rank-weighted long/short legs | 880.93 ms / 37.64 ms optimized / no native spike (23.4x) | exact equivalence checksum plus literal equal/rank/absolute score oracles, reconciliation, one-sided groups, zero fallback, and permutation invariance | Polars window allocation cut incremental RSS 91.5% and moved the public call below 50 ms. No residual constrained kernel remains. |
| R-15 | OPTIMIZED_NON_NATIVE | universe transitions | baseline, reference | 80,000 rows, 4 universes, 800 snapshots, 125 instruments per universe, 20% rotating exclusions | 579.37 ms / 400.23 ms optimized / no native spike (1.45x) | exact equivalence checksum plus literal multi-universe sets, zero/partial retention, chunk/order, duplicate, and c14n-v1 identity coverage | Snapshot self-joins cut RSS, but all optimized Polars work is only 5.6% of the instrumented call; exact streaming c14n-v1 owns over 92%. Native set operations fail materiality. |
| R-16 | OPTIMIZED_NON_NATIVE | c14n-v1 fingerprint | c7fd033 array, c7fd033 frame | 100,000 × 4 float64 array and Polars frame | array: 1.163 s / 90.61 ms; frame: 2.619 s / 1.659 s; no native spike | exact c14n-v1 checksums, frozen corpus, property and chunk-layout parity | Streaming Python passed the admission thresholds, so Rust is not justified. Reopen only for a changed encoder design backed by new benchmark evidence. |
Release closure
All v0.14 rows are terminal. Before tagging 0.14.0, the non-publishing preflight must reproduce the
native evidence for the exact release SHA and emit its checksummed manifest. Release notes list
SHIPPED_NATIVE, OPTIMIZED_NON_NATIVE, NOT_MIGRATING, and BLOCKED outcomes separately; they
do not describe an unmeasured candidate as a delivered performance improvement.