Struct Engine 

pub struct Engine { /* private fields */ }

A configured engine instance.

Implementations

impl Engine

pub fn new<S: MarkingScheme>( config: Config, rule_sets: Vec<Box<dyn RuleSet>>, scheme: S, ) -> Result<Self, EngineConstructionError>

Create a new engine with the given configuration, rule sets, and marking scheme.

Runs the page-rewrite scheduler (Kahn’s algorithm over the scheme’s declared reads / writes axes) once at construction time. Cycles and unannotated Custom rewrites fail closed with EngineConstructionError rather than degrading at lint time.

Use Engine::with_clock for deterministic-timestamp testing.

pub fn with_clock<S: MarkingScheme>( config: Config, rule_sets: Vec<Box<dyn RuleSet>>, scheme: S, clock: Box<dyn Clock>, ) -> Result<Self, EngineConstructionError>

Create an engine with a custom clock (for deterministic tests).

pub fn scheduled_rewrites(&self) -> &[RewriteId]

The topologically-sorted rewrite order computed by the scheduler at construction time.

Exposed for diagnostic / test inspection. Per-document lint does not re-sort; this slice is the canonical order every page roll-up walks.

pub fn with_recognizer( self, recognizer: Arc<dyn Recognizer<CapcoScheme>>, ) -> Self

Override the engine’s recognizer. The default installed by Engine::new is [StrictOrDecoderRecognizer] (strict-first, decoder fallback). Callers that need to pin a different dispatch — most commonly [StrictRecognizer] for the SC-001 interactive- latency benchmark or tests asserting strict-only behavior — install one explicitly here.

Returns the engine by value so callers can chain:

let engine = Engine::new(config, rules, scheme)?
    .with_recognizer(Arc::new(StrictRecognizer::new()));

pub fn corpus_override_active(&self) -> bool

Whether a corpus override is in effect for this engine.

Returns false unconditionally when the corpus-override Cargo feature is not compiled in — the WASM and server builds therefore cannot observe a true here regardless of what any caller passes through other surfaces. Callers that need to thread the flag into audit-record construction (the private build_decoder_diagnostic helper inside this module) should go through this method rather than poking at the field directly.

pub fn lint(&self, source: &[u8]) -> LintResult

Lint a UTF-8 text buffer. Returns diagnostics without modifying input.

Back-compat shim over Engine::lint_with_options — calling lint(src) is equivalent to lint_with_options(src, &LintOptions::default()). New code that needs a deadline (spec 005 §R3) should call the _with_options variant directly.

pub fn lint_with_options(&self, source: &[u8], opts: &LintOptions) -> LintResult

Lint with per-call options (spec 005 §R2).

Phase 2 honors opts.deadline via cooperative cancellation (spec §R3): a pre-pass check returns immediately on an already-expired deadline, and a per-candidate check inside the rule loop breaks out as soon as the deadline passes. The returned LintResult carries truncated: bool together with candidates_processed / candidates_total so the caller can distinguish a complete pass from a deadline-bounded partial pass.

Granularity: the engine checks the deadline at candidate boundaries (between scanner-emitted candidates), not inside any individual rule’s check. A pathologically slow rule running on one large candidate can therefore overrun the deadline by the time that one rule takes; this is the spec §R3 trade-off — a finer-grained check inside Rule::check would require a deadline-aware rule trait.

pub fn fix(&self, source: &[u8], mode: FixMode) -> FixResult

Lint and apply fixes. Returns fixed source and audit log.

Fix application order follows FR-016: (span.end DESC, span.start DESC, rule_id ASC, replacement ASC) so reverse-byte application preserves earlier-span offsets and equal-span ties break deterministically.

Uses the confidence threshold configured in the engine’s Config. To supply a per-call override (e.g., from a --confidence CLI flag or an HTTP request field), use Engine::fix_with_threshold or Engine::fix_with_options.

Back-compat shim over Engine::fix_with_options — fix(src, mode) is equivalent to fix_with_options(src, mode, &FixOptions::default()) (no deadline, no threshold override). Both invariants make the expect here unreachable: the default options carry no deadline so EngineError::DeadlineExceeded cannot fire, and the config threshold is pre-validated at load time so EngineError::InvalidThreshold cannot fire.

pub fn fix_with_threshold( &self, source: &[u8], mode: FixMode, threshold_override: Option<f32>, ) -> Result<FixResult, InvalidThreshold>

Lint and apply fixes using an optional per-call confidence threshold.

When threshold_override is Some, it replaces the config-level threshold for this call only and is validated against [0.0, 1.0]. When None, the engine falls back to Config::confidence_threshold.

This signature is preserved for back-compat. New callers should prefer Engine::fix_with_options, which carries the deadline surface alongside the threshold override.

pub fn fix_with_options( &self, source: &[u8], mode: FixMode, opts: &FixOptions, ) -> Result<FixResult, EngineError>

Lint and apply fixes with per-call options (spec 005 §R2).

Phase 2 honors opts.deadline via cooperative cancellation (spec §R3). Asymmetric response per §R4 / Constitution V Principle V (audit-record integrity): a deadline expiring at any point during the fix path returns Err(EngineError::DeadlineExceeded { partial_lint }) rather than a partial FixResult. The partial_lint carries whatever the lint phase had produced before the deadline fired (or a fully-truncated lint when the deadline was already expired on entry); no half-applied fix is ever emitted into the audit stream.

opts.threshold_override is honored from Phase 1 onward; an out-of-range / NaN value is rejected as EngineError::InvalidThreshold before any work runs.