Module engine 

The engine seam (ADR-0002): EngineFactory / EngineSession, step-kind routing, and capability hooks (step_kinds, doctor).

Both traits are sync + dyn (ADR-0006) and used as Box<dyn …>. Adding an engine is a new crate implementing both traits plus one registry line in proef-cli — with zero changes to this crate (the structural acceptance test for M6).

Example: a minimal engine

use proef_core::cancel::CancellationToken;
use proef_core::engine::{
    DoctorCheck, DoctorResult, EngineFactory, EngineSession, ScenarioCtx, StepKindSpec,
};
use proef_core::error::EngineError;
use proef_core::event::EventSink;
use proef_core::step::{BatchResult, StepBatch};
use proef_core::world::World;

struct NullEngine;
struct NullSession;

impl EngineFactory for NullEngine {
    fn id(&self) -> &'static str {
        "null"
    }
    fn step_kinds(&self) -> &'static [StepKindSpec] {
        const KINDS: &[StepKindSpec] = &[StepKindSpec {
            prefix: "null",
            schema: "true",
            validate: None,
            fragments: None,
        }];
        KINDS
    }
    fn doctor(&self) -> Vec<DoctorCheck> {
        Vec::new()
    }
    fn open(&self, _ctx: &ScenarioCtx) -> Result<Box<dyn EngineSession>, EngineError> {
        Ok(Box::new(NullSession))
    }
}

impl EngineSession for NullSession {
    fn run_batch(
        &mut self,
        batch: &StepBatch,
        _world: &mut World,
        _events: &EventSink,
        _cancel: &CancellationToken,
    ) -> BatchResult {
        BatchResult { steps: Vec::with_capacity(batch.steps.len()), error: None }
    }
    fn finish(&mut self) -> Result<(), EngineError> {
        Ok(())
    }
}

let factory: Box<dyn EngineFactory> = Box::new(NullEngine);
assert_eq!(factory.id(), "null");

Structs

ArtifactRef

A scenario’s emitted artifact, shared with the engine that executes it.

DoctorCheck

One named environment check (native libraries, tool availability, …) surfaced through proef doctor (ADR-0002 capability hook).

DoctorResult

Outcome of one environment check contributed by an engine.

EngineId

Identifies an engine (hurl, …). A macro step’s kind names the engine that executes it (ADR-0002 routing).

FragmentScanError

A fragment file the claiming engine’s parser could not read (1-based line/column within that file).

FragmentSupport

What a step kind needs to own a fragment file format: the extension that identifies one and the parser that reads it. Source discovery asks the registry for the extension rather than naming a file type itself, so adding an engine never teaches the CLI a new one (ADR-0002).

HttpDefaults

Batch-level HTTP defaults (per-entry [Options] in artifacts override them — clone-then-override, verified TECH-SPEC §5).

PayloadProbeError

A syntax problem found while probe-validating a step payload (1-based line/column within the payload text; the pack loader maps it onto the pack file).

ScannedFragment

One entry of a fragment file, as the claiming engine’s own parser sees it.

ScenarioCtx

Per-scenario context handed to EngineFactory::open. Fields grow additively as milestones land (artifact dirs, config, …).

StepKindSpec

An engine’s claim on a pack step kind: the key prefix (hurl; other prefixes reserved — ADR-0002 errata) plus the JSON-Schema fragment describing that step’s payload, merged into proef schema output (TECH-SPEC §6), and an optional static payload validator used by pack validation pass 7 (probe-instantiation parse — TECH-SPEC §4.1).

Enums

DoctorStatus

Severity of a DoctorResult.

Constants

OPTION_FAMILIES

The option families a pack step and a fragment can both declare, spelled as the pack spells them.

Traits

EngineFactory

Compiled-in engine entry point: identity, capability discovery, and session opening (ADR-0002). Registered in proef-cli’s registry, one line per engine.

EngineSession

A live per-scenario engine session (ADR-0002). Only a session runs batches — lifecycle is enforced by this ownership shape, not typestate.

Functions

secret_variables

Every engine variable a scenario must inject as a secret, paired with its value — ScenarioCtx::secret_bindings joined against ScenarioCtx::secrets. The one place that join is written.

Type Aliases

FragmentScanner

An engine-contributed reader for one fragment file’s whole text (ADR-0018).

PayloadValidator

An engine-contributed static payload validator (pack validation pass 7).