Performance And Scale Evidence¶

This page summarizes the current Rust-backed performance posture and the reproducible gate commands. Detailed historical engine notes were condensed after the Rust-backed Bank path became the production extraction engine.

Rust engine conformance, benchmark, dense-memory, mode-strategy, and distribution gate evidence is recorded in rust-engine-gates.md. The semantic contract is recorded in decisions/0001-rust-engine-semantics.md.

Current Posture¶

• Public extraction compiles JSON banks through the Rust-backed Bank API and scans with the production entity_independent mode.
• Literal and regex patterns are canonicalized into Rust detector metadata, scanned natively, then projected into stable byte-offset records.
• Compiled native banks are cached in process by canonical bank hash, engine name/version, compile options, platform dimensions, and target triple.
• Extraction still performs schema/canonicalization and extraction-scope authoring diagnostics before native cache lookup. NERB does not maintain a disk cache or caller-supplied cache key.
• all_overlaps and global_leftmost are internal measurement modes only; they are not public JSON-bank extraction semantics.

Reproducible Gate¶

Routine local gate:

uv run python scripts/rust_engine_gate_report.py --iterations 5 --target-bytes 100000 --dense-bytes 512 \
  --bank-owner-entity-count 1000 \
  --bank-owner-growth-entity-count 1000 \
  --bank-owner-note "representative synthetic medium bank target"

Larger 1 MB evidence, used as recorded release-gate evidence rather than a routine local check:

timeout 180s uv run python scripts/rust_engine_gate_report.py --iterations 1 --target-bytes 1000000 --dense-bytes 512 \
  --bank-owner-entity-count 1000 \
  --bank-owner-growth-entity-count 1000 \
  --bank-owner-note "representative synthetic medium bank target"

The report emits JSON with conformance, performance, dense-memory, mode-strategy, distribution, and bank-owner cardinality sections. The measured sections in overall.passed are performance, dense memory, and mode strategy. Conformance and distribution are external-required sections proven by PR validation commands and wheel smoke tests.

Recorded Gate Highlights¶

Final routine 100 KB report highlights:

The mixed corpus-size gate passed at 10 KB and 100 KB in the routine report. The 1 MB report passed with 1,805 records, 0.002356s scan/project median, and 424.4 MB/s scan/project throughput.

The production medium-bank case validates 1,000 top-level entities with 8 generated patterns per entity over the configured 100 KB sparse no-match document. The routine report measured:

The corresponding 1 MB evidence measured 0.704808s native compile median, 0.034258s raw scan median, 0.043692s scan/project median, and 22.9 MB/s scan/project throughput.

Dense prefix stress validates semantic reconstruction through 64 synthetic entity classes, with 8 dense prefix detectors per entity over 256 bytes. At 64 entities, entity_independent emitted 2,048 production matches, raw all_overlaps emitted 129,280 matches, and global_leftmost emitted 32 matches. The 64-to-2 dense scan ratio was 18.875x under the 80x ceiling.

Smoke Profiles¶

benchmark_fixture_profiles() and make_benchmark_fixture_profile(profile_id) provide deterministic structural smoke profiles for benchmark output shape:

Run one smoke profile:

uv run python - <<'PY'
import json
from nerb import benchmark_bank, make_benchmark_fixture_profile

fixture = make_benchmark_fixture_profile("adversarial_smoke")
result = benchmark_bank(fixture["bank"], documents=fixture["documents"], options=fixture["options"])
summary = {
    "profile": fixture["id"],
    "gate": fixture["gate"],
    "sections": sorted(result),
    "compile_cache": result["stages"]["compile_cache"],
    "record_count_stable": {name: tier["record_count_stable"] for name, tier in result["tiers"].items()},
}
print(json.dumps(summary, indent=2, sort_keys=True))
PY

Large Synthetic Bank Review¶

The pre-release large-bank review showed exact-literal warm extraction was not the target-tier bottleneck; cold setup and bank hashing dominated large synthetic banks.

The full stress tier is not practical as a routine local or CI check.

Dependency Decision¶

NERB does not add a separate literal-matcher runtime dependency for the current production path. The portable Rust literal automaton meets the target tier without adding binary build, wheel availability, or supply-chain risk. Revisit an external matcher only if real workloads show long-document warm extraction is the bottleneck after the current engine path.

PCRE2 remains optional and is not a current blocker. The engine boundary leaves room for a future PCRE2 backend, but the recorded review does not justify making it part of the production path.

Resource Limits¶

Extraction and eval byte limits remain explicit options for callers. There is no disk cache in the current engine path.