Performance Implementation

The public performance summary should prefer the primary assura check product path and the ls-lint-cli row from the same release profile. The current checked-in headline claim is scoped to the Linux static-CRT primary assura launcher, which routes supported one-shot checks through the lightweight checker before falling back to the assura-full companion for less common commands. Local macOS dynamic rows are diagnostic lower-bound evidence. The LS-Lint row executes the native platform binary resolved from the pinned @ls-lint/ls-lint package. It does not time npm exec, package resolution, or the package’s Node wrapper. The top-level rows include process startup, config discovery/load, validation, report construction, and process exit.

Traversal and phase rows answer narrower engineering questions. They belong on this page because they explain why a strategy was chosen, not whether users should expect one tool to be faster than the other.

Row Families

Row Family	Meaning	Use For
`assura-cli`	Primary installable Assura launcher running the quiet fast `assura check` success path	Product comparison against LS-Lint
`assura-check-cli`	Internal focused checker binary	Historical and implementation attribution
`ls-lint-cli`	Native LS-Lint CLI subprocess check	Product comparison baseline
`assura-in-process`	Assura validation inside the current process	Runtime attribution without process startup
`assura:phase:*`	Timed Assura implementation phases	Locating hot spots
`traversal:*`	Raw filesystem enumeration only	Traversal strategy attribution
`strategy:*`	Full-check traversal strategy variants	Comparing implementation choices under validation load
`native:content-*`	Assura-native content collection and document graph CLI rows	Product surfaces without LS-Lint equivalents
`native:context-pack-cli`	Context-pack selection and rendering through the full CLI	Agent context payload performance
`native:agent-query-*`	Agent-oriented query paths over the content graph	Agent/editor query latency evidence
`native:markdown-safe-fix-dry-run-cli`	Markdown safe-fix planning without writing changes	Markdown validation and fix-planning cost
`native:session-agent-context-cli`	Session-style agent-context query row	Warm workflow proxy evidence, not cold CLI parity
`native:daemon-status-cli`	Daemon status request through the full CLI	Daemon surface smoke and protocol overhead
`native:phase:*`	Assura-native attribution rows for model load, schema compile, repository validation, fact-store indexing, incremental update, warm query, and JSON serialization	Deciding what to optimize before adding caches or a persistent store

Fixture Acceptance

fixture_acceptance is the machine-readable gate class for a fixture row:

accepted-ls-lint-equivalent rows are current no-slower gate inputs.
diagnostic rows are retained for attribution and regression detection.
experimental rows are not yet support-grade proof.
retired rows are kept only for historical review.
assura-native-diagnostic rows cover Assura-specific fixtures that do not have a native LS-Lint equivalent.

The fixture-floor gate operates on accepted LS-Lint-equivalent fixtures, not on aggregate runtime totals. A slower accepted fixture blocks the merge even when the cohort aggregate is faster.

Traversal Decision

The non-fail-fast default traversal path is walkdir. It gives deterministic sorted traversal, supports exclusion pruning through filter_entry, and did not show a meaningful full-check regression against serial jwalk on the current realistic fixture bundle.

Serial jwalk remains the deterministic fail-fast path and an opt-in diagnostic strategy. Parallel jwalk can be useful for raw traversal experiments, but raw entry enumeration is not the same as full validation throughput.

Reporting Rule

Do not place traversal-only wins in the headline performance claim. If a future strategy should influence the public claim, add a strategy:* full-check row for that implementation and compare it against the same fixture, config, binary profile, and iteration count.

Two-Times-Faster Gate

Rows include two_x_target_runtime_ms, which is half of the native LS-Lint median for the same fixture. Assura CLI rows also include two_x_claim_status:

meets-target means the measured row is at or below the 2x target.
misses-target means the row is slower than the target and the measured process floors do not by themselves exceed the target.
blocked-by-process-floor means launching /usr/bin/true already exceeds the target on that fixture.
blocked-by-rust-cli-floor means the smallest Assura Rust CLI status-check process already exceeds the target.

meets_two_x_target remains the numeric pass/fail result. The claim-status field explains whether a miss is an implementation gap or a measured subprocess-floor limit.

Cold Optimization Keep Bar

Cold LS-Lint optimization work must prove progress on product-facing rows, not only on internal diagnostics. Retain a cold structure optimization only when a same-host cargo perf-vps comparison shows all of these:

the target public assura-cli row improves by at least 5% and 0.75 ms;
the exact public assura check --quiet tie-breaker improves by at least 3%;
no accepted fixture regresses by more than 5% or 0.25 ms;
cargo xtask performance-no-slower passes on the candidate report.

The helper’s accepted_fixture_delta table is the minimum review surface for a candidate. Phase rows, traversal rows, in-process rows, hot daemon rows, and assura-check-cli rows explain cause, but they do not justify keeping a change when the ordinary public command is flat or slower. The current stop/keep matrix is tracked in docs/analysis/2026-07-05-performance-decision-matrix.md.

Assura-Native Gate

The native report suite is generated with assura performance-report --suite native. It writes native-current.json and native-history.jsonl beside the LS-Lint comparison data. Native rows are intentionally classified as assura-native-diagnostic: they measure Assura-only content, graph, Markdown, agent-query, session, and daemon surfaces and must not be used to satisfy the cold assura check versus LS-Lint claim.

CI and local release checks use cargo xtask native-performance-no-regression to reject native reports that drop matrix rows, publish non-passing rows, omit samples, lose expected Assura exit-status metadata, stop identifying the report as --suite native, or regress past the checked baseline envelope for a native row. The native matrix also requires native:phase:* attribution rows so content runtime costs cannot be reported only as full CLI latency. Those rows identify whether cost is owned by schema compilation, file indexing, object validation and diagnostic construction, relation validation, fact-store ingest/indexing, incremental generation replacement, warm query execution, or JSON serialization. The current checked native artifacts are:

benches/history/native-current.json
benches/history/native-history.jsonl
website/public/data/performance/native-current.json
website/public/data/performance/native-history.jsonl

Each native row now carries:

commit_sha and branch for the exact measured git snapshot; when checked artifacts are regenerated from a materialized clean snapshot of a dirty lane, those fields identify the temporary measured snapshot rather than the original lane tip;
source_commit_sha, source_branch, and source_patch_id when the measured snapshot was materialized from another source lane, so reviewers can trace the checked artifact back to the real branch/base commit plus the exact diff envelope that was measured;
source_worktree_dirty on the report envelope, which now describes the source lane that was materialized into the measured snapshot. For ordinary in-place runs without source_* provenance, it still describes the executing checkout directly;
native_regression_baseline_median_ms from the checked native baseline, scoped to matching row metadata: operating system, architecture, toolchain, Assura version, and build profile;
native_regression_threshold_ms, which stays strict once a row has at least two checked reports and otherwise uses a provisional single-report envelope derived from the checked row’s observed spread;
native_regression_delta_ms for quick review;
native_regression_status, which must stay within-calibrated-baseline once a row has at least two checked reports. Single-report native rows may remain checked as within-provisional-baseline until that history exists.

The gate uses the row median against that calibrated threshold. p95 remains review evidence in the report, but the merge gate is intentionally about material row regressions and cross-checks the row median, threshold, and delta fields instead of trusting a status string alone.

The report envelope also includes claim_summary, a machine-readable verdict for the public headline row set. two_x_claim_verdict=complete is only valid when every measured realistic-equivalent focused-check row has a matching native LS-Lint row, meets its two-times-faster target, and the report was generated with at least minimum_completion_iterations measured iterations. Lower-sample smoke reports use not-complete-low-sample instead of complete. Diagnostic rows such as hot daemon checks, status-file checks, in-process validation, and traversal experiments are excluded from that verdict.

The envelope also includes warm_claim_summary for the persistent assura-check-dirty-project-session-cli row. That is a separate editor-session contract: a long-lived CLI process talks to the hot daemon over stdin/stdout so repeated agent/editor checks do not pay process startup on every validation.

Post-Beta Reassessment

The current post-beta reassessment records a narrower conclusion than the old universal 2x ambition: accepted LS-Lint-equivalent cold rows must be no slower than native LS-Lint, and any remaining 2x misses must be attributable by phase. Small fixtures are expected to be sensitive to process floor and Rust CLI floor measurements; larger misses must identify real config-loading, checker-init, or walk-and-validate work instead of being excused by aggregate speedups.

See docs/analysis/2026-07-02-ls-lint-performance-reassessment.md for the current accepted-row and phase-attribution summary.